# Liquid Tabs

> A tab switcher with a physics-driven, stretching selection pill.

Install: `npx @modus-ui/cli add liquid-tabs`

A beautiful navigation primitive. The tab indicator mathematically squishes and stretches based on the physical velocity of the spring transition, rather than relying on standard hard-coded scales. If you jump multiple tabs, it stretches more!

## Installation

### CLI

```bash
npx @modus-ui/cli add liquid-tabs
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/liquid-tabs.tsx`.
3. Paste the code.

## Usage

```tsx
import { LiquidTabs } from "@/components/ui/liquid-tabs";

export default function Example() {
  const tabs = [
    { label: "Home", value: "home" },
    { label: "Profile", value: "profile" },
    { label: "Settings", value: "settings" },
  ];

  return <LiquidTabs items={tabs} defaultValue="home" />;
}
```

## Props

| Prop            | Type                      | Default | Description                                                              |
| :-------------- | :------------------------ | :------ | :----------------------------------------------------------------------- |
| `items`         | `LiquidTabItem[]`         | -       | The tabs to render.                                                      |
| `defaultValue`  | `string`                  | -       | The initially active tab when uncontrolled.                              |
| `value`         | `string`                  | -       | The active tab when controlled.                                          |
| `onValueChange` | `(value: string) => void` | -       | Called with the new value when a tab is selected.                        |
| `squish`        | `number`                  | `0.22`  | How much the indicator stretches while it moves (0 disables the effect). |

## Source

`components/ui/liquid-tabs.tsx`

```tsx
"use client";

import { motion, useReducedMotion, useSpring, useTransform, useVelocity } from "framer-motion";
import {
  useCallback,
  useEffect,
  useLayoutEffect,
  useRef,
  useState,
  type KeyboardEvent,
} from "react";
import { cn } from "@/lib/utils";

interface LiquidTabItem {
  label: string;
  value: string;
}

interface LiquidTabsProps {
  items: LiquidTabItem[];
  defaultValue?: string;
  value?: string;
  onValueChange?: (value: string) => void;
  squish?: number;
  className?: string;
}

export function LiquidTabs({
  items,
  defaultValue,
  value,
  onValueChange,
  squish = 0.22,
  className = "",
}: LiquidTabsProps) {
  const prefersReducedMotion = useReducedMotion();
  const listRef = useRef<HTMLDivElement>(null);
  const tabRefs = useRef<(HTMLButtonElement | null)[]>([]);
  const measured = useRef(false);

  const [uncontrolled, setUncontrolled] = useState(defaultValue ?? items[0]?.value ?? "");
  const selected = value ?? uncontrolled;
  const activeIndex = Math.max(
    0,
    items.findIndex((item) => item.value === selected),
  );

  const spring = { stiffness: 420, damping: 34, mass: 0.9 };
  const x = useSpring(0, spring);
  const width = useSpring(0, spring);

  const velocity = useVelocity(x);
  const stretch = useTransform(velocity, [-2600, 0, 2600], [1 + squish, 1, 1 + squish], {
    clamp: true,
  });
  const scaleX = useSpring(stretch, { stiffness: 500, damping: 30 });
  const scaleY = useTransform(scaleX, (current) => 1 / current);

  const sync = useCallback(() => {
    const tab = tabRefs.current[activeIndex];
    const list = listRef.current;
    if (!tab || !list) return;

    const left = tab.offsetLeft;
    const tabWidth = tab.offsetWidth;

    if (!measured.current || prefersReducedMotion) {
      measured.current = true;
      x.jump(left);
      width.jump(tabWidth);
      return;
    }

    x.set(left);
    width.set(tabWidth);
  }, [activeIndex, prefersReducedMotion, x, width]);

  useLayoutEffect(sync, [sync]);

  useEffect(() => {
    const list = listRef.current;
    if (!list || typeof ResizeObserver === "undefined") return;

    const observer = new ResizeObserver(sync);
    observer.observe(list);
    return () => observer.disconnect();
  }, [sync]);

  const select = (next: string) => {
    if (value === undefined) setUncontrolled(next);
    onValueChange?.(next);
  };

  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    const moves: Record<string, number> = {
      ArrowRight: 1,
      ArrowLeft: -1,
      Home: -activeIndex,
      End: items.length - 1 - activeIndex,
    };
    const step = moves[event.key];
    if (step === undefined) return;

    event.preventDefault();
    const next = (activeIndex + step + items.length) % items.length;
    const target = items[next];
    if (!target) return;

    select(target.value);
    tabRefs.current[next]?.focus();
  };

  return (
    <div
      ref={listRef}
      role="tablist"
      aria-orientation="horizontal"
      onKeyDown={handleKeyDown}
      className={cn(
        "relative isolate inline-flex max-w-full items-center gap-1 overflow-x-auto rounded-full border border-border bg-muted/50 p-1 [scrollbar-width:none]",
        className,
      )}
    >
      <motion.span
        aria-hidden="true"
        style={{ x, width, scaleX, scaleY }}
        className="absolute inset-y-1 left-0 -z-10 rounded-full bg-background shadow-sm ring-1 ring-border/70"
      />

      {items.map((item, index) => {
        const isActive = index === activeIndex;

        return (
          <button
            key={item.value}
            ref={(node) => {
              tabRefs.current[index] = node;
            }}
            type="button"
            role="tab"
            aria-selected={isActive}
            tabIndex={isActive ? 0 : -1}
            onClick={() => select(item.value)}
            className={cn(
              "relative whitespace-nowrap rounded-full px-4 py-1.5 text-sm font-medium transition-colors",
              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
              isActive ? "text-foreground" : "text-muted-foreground hover:text-foreground",
            )}
          >
            {item.label}
          </button>
        );
      })}
    </div>
  );
}
```

---

# Flowing Menu

> A full-screen menu where hovering an item triggers an infinite scrolling marquee.

Install: `npx @modus-ui/cli add flowing-menu`

A full-screen menu where hovering an item triggers an infinite scrolling marquee mask that reveals the image and text based on mouse entry position.

## Installation

### CLI

```bash
npx @modus-ui/cli add flowing-menu
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/flowing-menu.tsx`.
3. Paste the code.

## Usage

```tsx
import { FlowingMenu } from "@/components/ui/flowing-menu";

export default function Example() {
  const items = [
    { link: "#", text: "Home", image: "..." },
    { link: "#", text: "About", image: "..." },
  ];

  return (
    <div className="h-[400px]">
      <FlowingMenu items={items} speed={20} />
    </div>
  );
}
```

## Props

| Prop    | Type              | Default | Description                                       |
| :------ | :---------------- | :------ | :------------------------------------------------ |
| `items` | `MenuItemProps[]` | `[]`    | The menu entries to render.                       |
| `speed` | `number`          | `15`    | Duration in seconds of one marquee loop on hover. |

## Source

`components/ui/flowing-menu.tsx`

```tsx
"use client";
// Full-height menu rows; hovering one slides in a looping marquee from the edge the cursor entered.

import { useState } from "react";
import type React from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface MenuItemProps {
  link: string;
  text: string;
  image: string;
}

export interface FlowingMenuProps {
  items?: MenuItemProps[];
  speed?: number;
  className?: string;
}

type Edge = "top" | "bottom";

function edgeOf(e: React.MouseEvent<HTMLElement>): Edge {
  const rect = e.currentTarget.getBoundingClientRect();
  return e.clientY - rect.top < rect.height / 2 ? "top" : "bottom";
}

function Row({ item, speed }: { item: MenuItemProps; speed: number }) {
  const reduceMotion = useReducedMotion();
  const [edge, setEdge] = useState<Edge | null>(null);
  const [exitEdge, setExitEdge] = useState<Edge>("top");
  const offset = (side: Edge) => (side === "top" ? "-101%" : "101%");
  const strip = Array.from({ length: 4 }, (_, i) => (
    <span key={i} className="flex shrink-0 items-center gap-6 pr-6">
      <span className="font-display text-3xl uppercase sm:text-4xl">{item.text}</span>
      <span
        className="h-12 w-28 shrink-0 rounded-full bg-cover bg-center"
        style={{ backgroundImage: `url(${item.image})` }}
      />
    </span>
  ));

  return (
    <a
      href={item.link}
      className="relative flex flex-1 items-center justify-center overflow-hidden border-t border-border first:border-t-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[hsl(var(--ring))]"
      onMouseEnter={(e) => setEdge(edgeOf(e))}
      onMouseLeave={(e) => {
        setExitEdge(edgeOf(e));
        setEdge(null);
      }}
      onFocus={() => setEdge("top")}
      onBlur={() => setEdge(null)}
    >
      <span className="font-display text-3xl uppercase text-foreground sm:text-4xl">
        {item.text}
      </span>
      <AnimatePresence>
        {edge && (
          <motion.span
            aria-hidden
            className="absolute inset-0 flex items-center overflow-hidden bg-foreground text-background"
            initial={reduceMotion ? { opacity: 0 } : { y: offset(edge) }}
            animate={reduceMotion ? { opacity: 1 } : { y: "0%" }}
            exit={reduceMotion ? { opacity: 0 } : { y: offset(exitEdge) }}
            transition={{ duration: reduceMotion ? 0.15 : 0.5, ease: [0.22, 1, 0.36, 1] }}
          >
            <motion.span
              className="flex w-max"
              animate={reduceMotion ? undefined : { x: ["0%", "-50%"] }}
              transition={{ duration: speed, ease: "linear", repeat: Infinity }}
            >
              {strip}
              {strip}
            </motion.span>
          </motion.span>
        )}
      </AnimatePresence>
    </a>
  );
}

export function FlowingMenu({ items = [], speed = 15, className }: FlowingMenuProps) {
  return (
    <nav className={cn("flex h-full w-full flex-col bg-background", className)}>
      {items.map((item, i) => (
        <Row key={i} item={item} speed={speed} />
      ))}
    </nav>
  );
}
```

---

# Morphing Navbar

> A premium, scroll-aware header that dynamically adjusts its layout density and logo scale based on scroll position.

Install: `npx @modus-ui/cli add morphing-navbar`

A premium, scroll-aware navigation header that dynamically adjusts its layout, logo scale, and background density as the user scrolls. Part of the Premium UI series.

## Installation

### CLI

```bash
npx @modus-ui/cli add morphing-navbar
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/morphing-navbar.tsx`.
3. Paste the code.

## Usage

```tsx
import { MorphingNavbar } from "@/components/ui/morphing-navbar";
import { GraduationCap } from "lucide-react";

export default function Example() {
  return (
    <MorphingNavbar
      title="Morphing Navbar"
      logo={GraduationCap}
      breadcrumbSteps={[{ label: "Components" }, { label: "Navigation" }]}
    />
  );
}
```

## Props

| Prop              | Type          | Default             | Description                                                           |
| :---------------- | :------------ | :------------------ | :-------------------------------------------------------------------- |
| `title`           | `string`      | `"Morphing Navbar"` | The title text displayed next to the logo.                            |
| `logo`            | `ElementType` | `GraduationCap`     | The icon component to display as the logo.                            |
| `breadcrumbSteps` | `Step[]`      | `[]`                | Array of breadcrumb steps to display in expanded mode.                |
| `onHomeClick`     | `() => void`  | -                   | Called when the home button is clicked.                               |
| `onProfileClick`  | `() => void`  | -                   | Called when the profile avatar is clicked.                            |
| `onToggleSidebar` | `() => void`  | -                   | Called when the sidebar toggle is clicked.                            |
| `sidebarOpen`     | `boolean`     | `false`             | Whether the sidebar is open (sets the mobile toggle icon).            |
| `scrollThreshold` | `number`      | `36`                | Scroll distance in pixels before morphing to collapsed state.         |
| `targetId`        | `string`      | -                   | Optional ID of a scrollable container to track instead of the window. |

## Source

`components/ui/morphing-navbar.tsx`

```tsx
"use client";

import React, { useEffect, useState } from "react";
import Image from "next/image";
import { motion, AnimatePresence, useReducedMotion } from "framer-motion";
import { Menu, X, ChevronRight, GraduationCap, Moon, Sun } from "lucide-react";
import { cn } from "@/lib/utils";

// --- Simplified UI Helpers (Standalone) ---

const NavButton = ({
  children,
  onClick,
  className,
  variant = "primary",
}: {
  children: React.ReactNode;
  onClick?: () => void;
  className?: string;
  variant?: "primary" | "ghost" | "outline";
}) => {
  const variants = {
    primary: "bg-primary text-primary-foreground hover:opacity-90 shadow-sm",
    ghost: "bg-transparent text-foreground hover:bg-accent",
    outline: "border border-border bg-card/60 text-foreground hover:bg-accent",
  };

  return (
    <button
      onClick={onClick}
      className={cn(
        "inline-flex items-center justify-center rounded-full px-5 py-2.5 text-sm font-semibold transition-all duration-300 hover:scale-95 active:scale-90 motion-reduce:transition-none motion-reduce:hover:scale-100 motion-reduce:active:scale-100",
        variants[variant],
        className,
      )}
    >
      {children}
    </button>
  );
};

const UserAvatar = ({ src, alt }: { src?: string; alt: string }) => (
  <div className="flex h-10 w-10 items-center justify-center overflow-hidden rounded-full border border-border bg-secondary">
    {src ? (
      <Image src={src} alt={alt} width={40} height={40} className="h-full w-full object-cover" />
    ) : (
      <span className="text-xs font-bold text-muted-foreground">{alt.charAt(0)}</span>
    )}
  </div>
);

// --- Main Component ---

/**
 * MorphingNavbar is a premium, scroll-aware header that adjusts its layout density
 * based on the scroll position of the page or a target container.
 */
export function MorphingNavbar({
  title = "Morphing Navbar",
  logo: Logo = GraduationCap,
  breadcrumbSteps = [],
  onHomeClick = () => {},
  onProfileClick = () => {},
  onToggleSidebar = () => {},
  sidebarOpen = false,
  scrollThreshold = 36,
  targetId,
}: {
  /** The title text displayed next to the logo */
  title?: string;
  /** The icon component to display as the logo */
  logo?: React.ElementType;
  /** Array of breadcrumb steps to display in expanded mode */
  breadcrumbSteps?: { label: string; href?: string }[];
  /** Callback for home button click */
  onHomeClick?: () => void;
  /** Callback for profile/avatar click */
  onProfileClick?: () => void;
  /** Callback for sidebar toggle button */
  onToggleSidebar?: () => void;
  /** Boolean indicating if the sidebar is currently open (for mobile toggle icon) */
  sidebarOpen?: boolean;
  /** Scroll distance in pixels before morphing to collapsed state */
  scrollThreshold?: number;
  /** Optional ID of a scrollable container to track instead of the window */
  targetId?: string;
}) {
  const [collapsed, setCollapsed] = useState(false);
  const [isDarkMode, setIsDarkMode] = useState(false);
  const prefersReducedMotion = useReducedMotion();
  const instant = prefersReducedMotion ? { duration: 0 } : undefined;

  useEffect(() => {
    const scrollTarget = targetId ? document.getElementById(targetId) : window;
    if (!scrollTarget) return;

    const handleScroll = () => {
      const scrollY = targetId ? (scrollTarget as HTMLElement).scrollTop : window.scrollY;
      setCollapsed(scrollY > scrollThreshold);
    };

    // Check initial scroll position
    handleScroll();

    scrollTarget.addEventListener("scroll", handleScroll, { passive: true });
    return () => scrollTarget.removeEventListener("scroll", handleScroll);
  }, [scrollThreshold, targetId]);

  return (
    <header
      className={cn(
        "sticky top-0 z-50 w-full border-b transition-all duration-500 motion-reduce:transition-none",
        collapsed
          ? "h-[80px] border-border/80 bg-background/95 shadow-md backdrop-blur-md"
          : "h-[104px] border-border/40 bg-background/80 backdrop-blur-sm",
      )}
    >
      <div
        className={cn(
          "mx-auto flex h-full w-full flex-col justify-center px-4 transition-all duration-500 motion-reduce:transition-none md:px-8 lg:px-10",
          collapsed ? "max-w-full" : "max-w-[1200px]",
        )}
      >
        <div className="flex w-full items-center justify-between">
          {/* Left Section: Logo & Mobile Toggle */}
          <div className="flex items-center gap-3">
            <button
              onClick={onToggleSidebar}
              className="rounded-md p-2 transition-colors hover:bg-accent lg:hidden"
              aria-label="Toggle menu"
            >
              {sidebarOpen ? <X className="h-5 w-5" /> : <Menu className="h-5 w-5" />}
            </button>

            <button
              onClick={onHomeClick}
              className="group flex items-center border-none bg-transparent p-0 outline-none transition-opacity hover:opacity-80"
              aria-label="Go home"
            >
              <motion.div
                animate={{ scale: collapsed ? 0.9 : 1 }}
                transition={instant}
                style={{ originX: 0 }}
                className="grid grid-cols-[auto,auto] items-center gap-3"
              >
                <div className="flex items-center justify-center">
                  <Logo
                    className={cn(
                      "text-foreground transition-all duration-500 motion-reduce:transition-none",
                      collapsed ? "h-7 w-7" : "h-9 w-9",
                    )}
                  />
                </div>
                <h1 className="whitespace-nowrap font-serif text-3xl font-medium leading-none tracking-tight text-foreground">
                  {title}
                </h1>
              </motion.div>
            </button>
          </div>

          {/* Right Section: Actions */}
          <div className="flex items-center gap-2">
            <NavButton
              variant="ghost"
              onClick={onProfileClick}
              className="hidden h-10 w-10 overflow-hidden p-0 sm:flex"
              aria-label="View profile"
            >
              <UserAvatar alt="User" />
            </NavButton>

            <NavButton onClick={onHomeClick} className="xs:flex hidden">
              Home
            </NavButton>

            <div className="ml-2 hidden items-center gap-2 rounded-full border border-border bg-card/40 p-1 sm:flex">
              <button
                onClick={() => setIsDarkMode(!isDarkMode)}
                className="rounded-full p-1.5 transition-colors hover:bg-accent"
                aria-label="Toggle dark mode"
              >
                {isDarkMode ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
              </button>
            </div>
          </div>
        </div>

        {/* Breadcrumbs (Expandable) */}
        <AnimatePresence>
          {!collapsed && breadcrumbSteps.length > 0 && (
            <motion.div
              initial={{ opacity: 0, height: 0, marginTop: 0 }}
              animate={{ opacity: 1, height: "auto", marginTop: 8 }}
              transition={instant}
              exit={{ opacity: 0, height: 0, marginTop: 0 }}
              className="hidden overflow-hidden sm:block"
            >
              <div className="flex items-center gap-1 text-xs text-muted-foreground">
                <span className="cursor-pointer hover:text-foreground" onClick={onHomeClick}>
                  All Pages
                </span>
                {breadcrumbSteps.map((step, i) => (
                  <React.Fragment key={i}>
                    <ChevronRight className="h-3 w-3 flex-shrink-0" />
                    <span
                      className={cn(
                        "max-w-[150px] truncate",
                        i === breadcrumbSteps.length - 1
                          ? "font-medium text-foreground"
                          : "cursor-pointer hover:text-foreground",
                      )}
                    >
                      {step.label}
                    </span>
                  </React.Fragment>
                ))}
              </div>
            </motion.div>
          )}
        </AnimatePresence>
      </div>

      {/* Subtle bottom accent line */}
      <motion.div
        animate={{ opacity: collapsed ? 1 : 0.6 }}
        transition={instant}
        className="h-px w-full bg-border"
      />
    </header>
  );
}
```

---

# Floating Dock

> A premium navigation dock with smooth Apple-style magnifying zoom animation on hover.

Install: `npx @modus-ui/cli add floating-dock`

A premium floating dock navigation bar. Hovering over the icons enlarges them and their immediate neighbors dynamically using spring-based motion. Perfect for modern, app-like landing pages.

## Installation

### CLI

```bash
npx @modus-ui/cli add floating-dock
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/floating-dock.tsx`.
3. Paste the code.

## Usage

```tsx
import { FloatingDock } from "@/components/ui/floating-dock";
import { Home, Compass, Sparkles, Mail } from "lucide-react";

export default function Example() {
  const items = [
    { title: "Home", icon: <Home />, href: "/" },
    { title: "Explore", icon: <Compass />, href: "/explore" },
    { title: "Features", icon: <Sparkles />, onClick: () => console.log("clicked") },
    { title: "Contact", icon: <Mail />, href: "/contact" },
  ];

  return <FloatingDock items={items} />;
}
```

## Props

| Prop        | Type                 | Default    | Description                                                                               |
| :---------- | :------------------- | :--------- | :---------------------------------------------------------------------------------------- |
| `items`     | `FloatingDockItem[]` | -          | An array of navigation item objects containing title, icon, and optional href or onClick. |
| `direction` | `"top" \| "bottom"`  | `"bottom"` | The alignment and expansion direction of the tooltips.                                    |
| `className` | `string`             | -          | Custom container styles.                                                                  |

## Source

`components/ui/floating-dock.tsx`

```tsx
"use client";

import React, { useRef, useState } from "react";
import {
  motion,
  useMotionValue,
  useReducedMotion,
  useSpring,
  useTransform,
  AnimatePresence,
} from "framer-motion";
import { cn } from "@/lib/utils";

export interface FloatingDockItem {
  title: string;
  icon: React.ReactNode;
  href?: string;
  onClick?: () => void;
}

export interface FloatingDockProps {
  items: FloatingDockItem[];
  className?: string;
  direction?: "top" | "bottom";
}

export function FloatingDock({ items, className, direction = "bottom" }: FloatingDockProps) {
  const mouseX = useMotionValue(Infinity);
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      // Reduced motion: keep icons at rest size instead of magnifying toward the pointer.
      onMouseMove={(e) => !prefersReducedMotion && mouseX.set(e.pageX)}
      onMouseLeave={() => mouseX.set(Infinity)}
      className={cn(
        "relative mx-auto flex h-16 items-end gap-4 overflow-hidden rounded-3xl border border-border bg-background/90 px-4 pb-3 shadow-xl backdrop-blur-md",
        "before:pointer-events-none before:absolute before:inset-0 before:bg-[radial-gradient(circle,_#37322F_1px,_transparent_1px)] before:bg-[length:8px_8px] before:opacity-[0.03]",
        className,
      )}
    >
      {items.map((item, idx) => (
        <DockIcon
          key={idx}
          mouseX={mouseX}
          title={item.title}
          icon={item.icon}
          href={item.href}
          onClick={item.onClick}
          direction={direction}
          reducedMotion={!!prefersReducedMotion}
        />
      ))}
    </motion.div>
  );
}

interface DockIconProps {
  mouseX: any;
  title: string;
  icon: React.ReactNode;
  href?: string;
  onClick?: () => void;
  direction: "top" | "bottom";
  reducedMotion: boolean;
}

function DockIcon({ mouseX, title, icon, href, onClick, direction, reducedMotion }: DockIconProps) {
  const ref = useRef<HTMLDivElement>(null);
  const [hovered, setHovered] = useState(false);

  const distance = useTransform(mouseX, (val: number) => {
    const bounds = ref.current?.getBoundingClientRect() ?? { x: 0, width: 0 };
    return val - bounds.x - bounds.width / 2;
  });

  // Calculate icon scaling relative to distance from pointer
  const sizeTransform = useTransform(distance, [-120, 0, 120], [40, 60, 40]);
  const iconSizeTransform = useTransform(distance, [-120, 0, 120], [18, 30, 18]);

  const size = useSpring(sizeTransform, {
    mass: 0.1,
    stiffness: 200,
    damping: 15,
  });

  const iconSize = useSpring(iconSizeTransform, {
    mass: 0.1,
    stiffness: 200,
    damping: 15,
  });

  const Content = (
    <motion.div
      ref={ref}
      style={{ width: size, height: size }}
      onMouseEnter={() => setHovered(true)}
      onMouseLeave={() => setHovered(false)}
      whileTap={reducedMotion ? undefined : { scale: 0.9 }}
      className={cn(
        "relative flex items-center justify-center rounded-full border border-border bg-card text-foreground shadow-sm transition-colors hover:bg-background",
        "group cursor-pointer",
      )}
      onClick={onClick}
    >
      <AnimatePresence>
        {hovered && (
          <motion.div
            initial={
              reducedMotion
                ? { opacity: 0, y: direction === "bottom" ? -36 : 36, scale: 1 }
                : { opacity: 0, y: direction === "bottom" ? -10 : 10, scale: 0.95 }
            }
            animate={{ opacity: 1, y: direction === "bottom" ? -36 : 36, scale: 1 }}
            exit={
              reducedMotion
                ? { opacity: 0 }
                : { opacity: 0, y: direction === "bottom" ? -10 : 10, scale: 0.95 }
            }
            transition={
              reducedMotion ? { duration: 0.15 } : { type: "spring", stiffness: 300, damping: 20 }
            }
            className={cn(
              "absolute z-50 whitespace-nowrap rounded-md border border-border bg-background px-2 py-0.5 text-[10px] font-bold uppercase tracking-wider text-foreground shadow-sm",
              direction === "bottom" ? "-top-2" : "-bottom-2",
            )}
          >
            {title}
          </motion.div>
        )}
      </AnimatePresence>
      <motion.div
        style={{ width: iconSize, height: iconSize }}
        className="flex items-center justify-center"
      >
        {React.isValidElement(icon)
          ? React.cloneElement(icon as React.ReactElement, { className: "w-full h-full" })
          : icon}
      </motion.div>
    </motion.div>
  );

  if (href) {
    return (
      <a href={href} className="inline-block">
        {Content}
      </a>
    );
  }

  return Content;
}
```

---

# Notch Footer

> A premium, animated footer component with a smooth curved pocket.

Install: `npx @modus-ui/cli add notch-footer`

A premium, animated footer and call-to-action banner featuring a mathematically perfect curved notch pocket. Built with **Framer Motion** and **Tailwind CSS**. It is fully responsive and supports custom branding, dot grid indicators, and physics-based hover scaling out of the box.

## Installation

### CLI

```bash
npx @modus-ui/cli add notch-footer
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/notch-footer.tsx`.
3. Paste the code.

## Usage

```tsx
import { NotchFooter } from "@/components/notch-footer";

export default function Example() {
  const handleAction = () => {
    console.log("Action clicked!");
  };

  return (
    <NotchFooter
      title="Stop guessing about your digital experience with LogRocket"
      buttonText="Get started for free"
      onButtonClick={handleAction}
      bgColorClass="bg-gradient-to-r from-violet-600 via-indigo-600 to-purple-700"
      notchFillColor="hsl(var(--primary))" // Must match parent background color
    />
  );
}
```

## Props

| Prop               | Type         | Default                                                                                                                                                            | Description                                                             |
| :----------------- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |
| `title`            | `string`     | `"Stop guessing about your digital experience with Modus"`                                                                                                         | The primary headline rendered inside the banner                         |
| `buttonText`       | `string`     | `"Get started for free"`                                                                                                                                           | Text inside the bottom outline action button                            |
| `onButtonClick`    | `() => void` | -                                                                                                                                                                  | Callback function triggered when the CTA button is clicked              |
| `buttonHref`       | `string`     | -                                                                                                                                                                  | Optional destination link for the button (turns it into an `a` tag)     |
| `logo`             | `ReactNode`  | -                                                                                                                                                                  | Custom logo element floating gracefully inside the notch pocket         |
| `bgColorClass`     | `string`     | `"bg-primary"`                                                                                                                                                     | Tailwind class(es) setting the main banner's background                 |
| `titleColorClass`  | `string`     | `"!text-primary-foreground"`                                                                                                                                       | Tailwind class(es) for the headline colour.                             |
| `buttonColorClass` | `string`     | `"border-primary-foreground/20 hover:border-primary-foreground bg-primary-foreground/10 hover:bg-primary-foreground !text-primary-foreground hover:!text-primary"` | Tailwind class(es) for the button.                                      |
| `dotColorClass`    | `string`     | `"bg-primary-foreground/30"`                                                                                                                                       | Tailwind class(es) for the decorative dots.                             |
| `notchFillColor`   | `string`     | `"hsl(var(--background))"`                                                                                                                                         | Hex color filling the notch overlay (should match your page background) |
| `className`        | `string`     | -                                                                                                                                                                  | Additional CSS styling classes for the container                        |

## Source

`components/ui/notch-footer.tsx`

```tsx
"use client";

import React, { useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface NotchFooterProps {
  /** The main title text rendered inside the banner */
  title?: string;
  /** Text for the outline button at the bottom */
  buttonText?: string;
  /** Action triggered when the outline button is clicked */
  onButtonClick?: () => void;
  /** Optional href for the CTA button */
  buttonHref?: string;
  /** Logo or branding element placed inside the notch pocket */
  logo?: React.ReactNode;
  /** Custom background class for the banner container (e.g., gradients) */
  bgColorClass?: string;
  /** Custom text color class for the title */
  titleColorClass?: string;
  /** Custom color classes for the CTA button */
  buttonColorClass?: string;
  /** Custom background color class for the dots */
  dotColorClass?: string;
  /** Background color for the notch pocket overlay (must match parent page background) */
  notchFillColor?: string;
  /** Custom class name for the wrapper */
  className?: string;
}

export function NotchFooter({
  title = "Stop guessing about your digital experience with Modus",
  buttonText = "Get started for free",
  onButtonClick,
  buttonHref,
  logo,
  bgColorClass = "bg-primary",
  titleColorClass = "!text-primary-foreground", // Protect from .prose overrides
  buttonColorClass = "border-primary-foreground/20 hover:border-primary-foreground bg-primary-foreground/10 hover:bg-primary-foreground !text-primary-foreground hover:!text-primary", // Protect from .prose overrides
  dotColorClass = "bg-primary-foreground/30",
  notchFillColor = "hsl(var(--background))",
  className,
}: NotchFooterProps) {
  const [isHovered, setIsHovered] = useState(false);
  const prefersReducedMotion = useReducedMotion();
  // Reduced motion: hover parallax is disabled; the footer stays static.
  const hovered = isHovered && !prefersReducedMotion;

  return (
    <motion.footer
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
      className={cn(
        "relative flex w-full flex-col items-center justify-center overflow-hidden rounded-3xl px-8 py-16 text-center shadow-xl md:px-16",
        bgColorClass,
        className,
      )}
    >
      {/* 0. Border Outline Layer (Spatially layered at z-5, constructs the bottom, left, and right border frames) */}
      <div
        className="pointer-events-none absolute inset-0 rounded-3xl border-b border-l border-r border-border/10"
        style={{ zIndex: 5 }}
      />
      {/* Left Top Border Segment (Stops exactly at the start of the notch curves) */}
      <div
        className="pointer-events-none absolute left-0 top-0 h-[1px] bg-border/10"
        style={{ zIndex: 5, width: "calc(50% - 120px)" }}
      />
      {/* Right Top Border Segment (Starts exactly at the end of the notch curves) */}
      <div
        className="pointer-events-none absolute right-0 top-0 h-[1px] bg-border/10"
        style={{ zIndex: 5, width: "calc(50% - 120px)" }}
      />

      {/* 1. Fluid Liquid Notch Pocket (Layered at z-10 to mask the top border line perfectly) */}
      <div
        className="pointer-events-none absolute left-1/2 top-0 h-[48px] w-[240px] -translate-x-1/2 select-none"
        style={{ zIndex: 10 }}
      >
        <svg
          viewBox="0 0 240 48"
          width="240"
          height="48"
          className="h-full w-full"
          preserveAspectRatio="none"
        >
          <path
            d="M 0 0 C 20 0, 20 48, 40 48 L 200 48 C 220 48, 220 0, 240 0 Z"
            fill={notchFillColor}
          />
        </svg>
      </div>

      {/* 2. Logo container floating inside the Notch (Spatially isolated static wrapper to avoid Framer Motion transform overrides) */}
      <div
        className="absolute left-1/2 top-0 flex h-[38px] -translate-x-1/2 items-center justify-center"
        style={{ zIndex: 20 }}
      >
        <motion.div
          animate={{
            y: hovered ? 4 : 0,
            scale: hovered ? 1.05 : 1,
          }}
          transition={{ type: "spring", stiffness: 300, damping: 15 }}
          className="flex items-center justify-center"
        >
          {logo || (
            <div className="flex select-none items-center gap-1.5 rounded-full border border-border/40 bg-card/95 px-3 py-1 shadow-sm">
              <svg
                width="12"
                height="12"
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                strokeWidth="3"
                strokeLinecap="round"
                strokeLinejoin="round"
                className="animate-pulse text-foreground motion-reduce:animate-none"
              >
                <path d="M4 20V8a4 4 0 0 1 8 0v12" />
                <path d="M12 20V8a4 4 0 0 1 8 0v12" />
              </svg>
              <span className="font-serif text-[10px] font-bold uppercase tracking-wider text-foreground">
                Modus
              </span>
            </div>
          )}
        </motion.div>
      </div>

      {/* 3. Left Dotted Grid Decoration */}
      <div className="absolute bottom-6 left-6 hidden opacity-75 sm:block">
        <motion.div
          animate={{
            x: hovered ? 3 : 0,
            y: hovered ? -3 : 0,
          }}
          transition={{ duration: 0.4 }}
          className="grid grid-cols-3 gap-2"
        >
          {Array.from({ length: 12 }).map((_, i) => (
            <div key={i} className={cn("h-1 w-1 rounded-full", dotColorClass)} />
          ))}
        </motion.div>
      </div>

      {/* 4. Right Dotted Grid Decoration */}
      <div className="absolute right-6 top-6 hidden opacity-75 sm:block">
        <motion.div
          animate={{
            x: hovered ? -3 : 0,
            y: hovered ? 3 : 0,
          }}
          transition={{ duration: 0.4 }}
          className="grid grid-cols-3 gap-2"
        >
          {Array.from({ length: 12 }).map((_, i) => (
            <div key={i} className={cn("h-1 w-1 rounded-full", dotColorClass)} />
          ))}
        </motion.div>
      </div>

      {/* 5. Center Title */}
      <motion.h3
        initial={prefersReducedMotion ? false : { opacity: 0, y: 10 }}
        animate={{ opacity: 1, y: 0 }}
        transition={{ duration: 0.6 }}
        className={cn(
          "relative z-10 mb-8 mt-6 max-w-[700px] font-sans text-xl font-bold leading-tight tracking-tight md:text-3xl lg:text-4xl",
          titleColorClass,
        )}
      >
        {title}
      </motion.h3>

      {/* 6. Outline CTA Button */}
      <div className="relative z-10">
        {buttonHref ? (
          <a href={buttonHref} target="_blank" rel="noopener noreferrer" className="inline-block">
            <CTAButton text={buttonText} isHovered={hovered} buttonColorClass={buttonColorClass} />
          </a>
        ) : (
          <button onClick={onButtonClick} type="button">
            <CTAButton text={buttonText} isHovered={hovered} buttonColorClass={buttonColorClass} />
          </button>
        )}
      </div>
    </motion.footer>
  );
}

/* Internal CTA Button Component with physics scales */
function CTAButton({
  text,
  isHovered,
  buttonColorClass,
}: {
  text: string;
  isHovered: boolean;
  buttonColorClass: string;
}) {
  return (
    <motion.div
      animate={{
        scale: isHovered ? 1.03 : 1,
      }}
      transition={{ type: "spring", stiffness: 400, damping: 10 }}
      className={cn(
        "cursor-pointer select-none rounded-full border px-6 py-2.5 text-xs font-semibold uppercase tracking-wider shadow-md transition-colors duration-300 motion-reduce:transition-none",
        buttonColorClass,
      )}
    >
      {text}
    </motion.div>
  );
}
```

---

# Process Stepper

> A wizard-style stepper component for breaking down complex forms and processes into manageable chunks.

Install: `npx @modus-ui/cli add process-stepper`

A wizard-style stepper component for breaking down complex forms and processes into manageable chunks. Features smooth, dynamic height transitions and animated progress indicators.

## Installation

### CLI

```bash
npx @modus-ui/cli add process-stepper
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/process-stepper.tsx`.
3. Paste the code.

## Usage

```tsx
import { ProcessStepper, Step } from "@/components/ui/process-stepper";

export default function Example() {
  return (
    <ProcessStepper>
      <Step>
        <h3>Step 1</h3>
        <p>This is the first step.</p>
      </Step>
      <Step>
        <h3>Step 2</h3>
        <p>This is the second step.</p>
      </Step>
      <Step>
        <h3>Step 3</h3>
        <p>This is the final step.</p>
      </Step>
    </ProcessStepper>
  );
}
```

## Props

| Prop                    | Type                     | Default      | Description                                           |
| :---------------------- | :----------------------- | :----------- | :---------------------------------------------------- |
| `initialStep`           | `number`                 | `1`          | The step to start on.                                 |
| `onStepChange`          | `(step: number) => void` | -            | Callback fired when the step changes.                 |
| `onFinalStepCompleted`  | `() => void`             | -            | Callback fired when the user completes the last step. |
| `backButtonText`        | `string`                 | `"Back"`     | Text for the back button.                             |
| `nextButtonText`        | `string`                 | `"Continue"` | Text for the next button.                             |
| `disableStepIndicators` | `boolean`                | `false`      | If true, clicking step indicators won't navigate.     |

## Source

`components/ui/process-stepper.tsx`

```tsx
"use client";

import React, { useState, useRef, useLayoutEffect, Children } from "react";
import { motion, AnimatePresence, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ProcessStepperProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode;
  initialStep?: number;
  onStepChange?: (step: number) => void;
  onFinalStepCompleted?: () => void;
  backButtonText?: string;
  nextButtonText?: string;
  disableStepIndicators?: boolean;
}

export function ProcessStepper({
  children,
  initialStep = 1,
  onStepChange = () => {},
  onFinalStepCompleted = () => {},
  backButtonText = "Back",
  nextButtonText = "Continue",
  disableStepIndicators = false,
  className,
  ...rest
}: ProcessStepperProps) {
  const [currentStep, setCurrentStep] = useState(initialStep);
  const [direction, setDirection] = useState(0);

  const stepsArray = Children.toArray(children);
  const totalSteps = stepsArray.length;
  const isCompleted = currentStep > totalSteps;
  const isLastStep = currentStep === totalSteps;

  const updateStep = (newStep: number) => {
    setCurrentStep(newStep);
    if (newStep > totalSteps) {
      onFinalStepCompleted();
    } else {
      onStepChange(newStep);
    }
  };

  const handleBack = () => {
    if (currentStep > 1) {
      setDirection(-1);
      updateStep(currentStep - 1);
    }
  };

  const handleNext = () => {
    if (!isLastStep) {
      setDirection(1);
      updateStep(currentStep + 1);
    }
  };

  const handleComplete = () => {
    setDirection(1);
    updateStep(totalSteps + 1);
  };

  return (
    <div
      className={cn(
        "mx-auto flex w-full max-w-md flex-col overflow-hidden rounded-3xl border border-border bg-card shadow-sm",
        className,
      )}
      {...rest}
    >
      <div className="flex w-full items-center p-8">
        {stepsArray.map((_, index) => {
          const stepNumber = index + 1;
          const isNotLastStep = index < totalSteps - 1;

          return (
            <React.Fragment key={stepNumber}>
              <StepIndicator
                step={stepNumber}
                disableStepIndicators={disableStepIndicators}
                currentStep={currentStep}
                onClickStep={(clicked: number) => {
                  setDirection(clicked > currentStep ? 1 : -1);
                  updateStep(clicked);
                }}
              />
              {isNotLastStep && <StepConnector isComplete={currentStep > stepNumber} />}
            </React.Fragment>
          );
        })}
      </div>

      <StepContentWrapper
        isCompleted={isCompleted}
        currentStep={currentStep}
        direction={direction}
        className="space-y-4 px-8"
      >
        {stepsArray[currentStep - 1]}
      </StepContentWrapper>

      {!isCompleted && (
        <div className="px-8 pb-8 pt-4">
          <div className={cn("mt-6 flex", currentStep !== 1 ? "justify-between" : "justify-end")}>
            {currentStep !== 1 && (
              <button
                onClick={handleBack}
                className="px-4 py-2 text-sm font-medium text-muted-foreground transition-colors hover:text-foreground"
              >
                {backButtonText}
              </button>
            )}
            <button
              onClick={isLastStep ? handleComplete : handleNext}
              className="flex items-center justify-center rounded-full bg-primary px-6 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90 active:scale-95 motion-reduce:transition-none motion-reduce:active:scale-100"
            >
              {isLastStep ? "Complete" : nextButtonText}
            </button>
          </div>
        </div>
      )}
    </div>
  );
}

function StepContentWrapper({ isCompleted, currentStep, direction, children, className }: any) {
  const [parentHeight, setParentHeight] = useState(0);
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      style={{ position: "relative", overflow: "hidden" }}
      animate={{ height: isCompleted ? 0 : parentHeight }}
      transition={prefersReducedMotion ? { duration: 0 } : { type: "spring", duration: 0.4 }}
      className={className}
    >
      <AnimatePresence initial={false} mode="sync" custom={direction}>
        {!isCompleted && (
          <SlideTransition
            key={currentStep}
            direction={direction}
            reduced={!!prefersReducedMotion}
            onHeightReady={(h: number) => setParentHeight(h)}
          >
            {children}
          </SlideTransition>
        )}
      </AnimatePresence>
    </motion.div>
  );
}

function SlideTransition({ children, direction, reduced, onHeightReady }: any) {
  const containerRef = useRef<HTMLDivElement>(null);

  useLayoutEffect(() => {
    if (containerRef.current) onHeightReady(containerRef.current.offsetHeight);
  }, [children, onHeightReady]);

  return (
    <motion.div
      ref={containerRef}
      custom={direction}
      variants={{
        // Reduced motion: a short opacity-only crossfade instead of a slide.
        enter: (dir) => ({ x: reduced ? "0%" : dir >= 0 ? "-100%" : "100%", opacity: 0 }),
        center: { x: "0%", opacity: 1 },
        exit: (dir) => ({ x: reduced ? "0%" : dir >= 0 ? "50%" : "-50%", opacity: 0 }),
      }}
      initial="enter"
      animate="center"
      exit="exit"
      transition={{ duration: reduced ? 0.15 : 0.4 }}
      style={{ position: "absolute", left: 0, right: 0, top: 0 }}
    >
      {children}
    </motion.div>
  );
}

export function Step({ children, className }: { children: React.ReactNode; className?: string }) {
  return <div className={cn("w-full", className)}>{children}</div>;
}

function StepIndicator({ step, currentStep, onClickStep, disableStepIndicators }: any) {
  const status = currentStep === step ? "active" : currentStep < step ? "inactive" : "complete";
  const prefersReducedMotion = useReducedMotion();

  const handleClick = () => {
    if (step !== currentStep && !disableStepIndicators) onClickStep(step);
  };

  return (
    <motion.div
      onClick={handleClick}
      className={cn(
        "relative flex-shrink-0 outline-none focus:outline-none",
        disableStepIndicators ? "pointer-events-none opacity-50" : "cursor-pointer",
      )}
      animate={status}
      initial={false}
    >
      <motion.div
        variants={{
          inactive: {
            scale: 1,
            backgroundColor: "hsl(var(--muted))",
            color: "hsl(var(--muted-foreground))",
          },
          active: {
            scale: 1,
            backgroundColor: "hsl(var(--primary))",
            color: "hsl(var(--primary-foreground))",
          },
          complete: {
            scale: 1,
            backgroundColor: "hsl(var(--primary))",
            color: "hsl(var(--primary-foreground))",
          },
        }}
        transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.3 }}
        className="flex h-10 w-10 items-center justify-center rounded-full border-2 border-transparent font-semibold"
      >
        {status === "complete" ? (
          <CheckIcon className="h-5 w-5 text-primary-foreground" />
        ) : status === "active" ? (
          <div className="h-3 w-3 rounded-full bg-primary-foreground" />
        ) : (
          <span className="text-sm">{step}</span>
        )}
      </motion.div>
    </motion.div>
  );
}

function StepConnector({ isComplete }: { isComplete: boolean }) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <div className="relative mx-3 h-1 flex-1 overflow-hidden rounded-full bg-muted">
      <motion.div
        className="absolute left-0 top-0 h-full bg-primary"
        initial={false}
        animate={{ width: isComplete ? "100%" : "0%" }}
        transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.4 }}
      />
    </div>
  );
}

function CheckIcon(props: React.SVGProps<SVGSVGElement>) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <svg {...props} fill="none" stroke="currentColor" strokeWidth={3} viewBox="0 0 24 24">
      <motion.path
        initial={prefersReducedMotion ? false : { pathLength: 0 }}
        animate={{ pathLength: 1 }}
        transition={{ delay: 0.1, type: "tween", ease: "easeOut", duration: 0.3 }}
        strokeLinecap="round"
        strokeLinejoin="round"
        d="M5 13l4 4L19 7"
      />
    </svg>
  );
}
```

---

# Magnet

> A micro-interaction component that pulls an element towards the mouse cursor.

Install: `npx @modus-ui/cli add magnet`

A simple but highly effective physics micro-interaction. It wraps any element and pulls it towards the mouse cursor as it approaches, creating a magnetic gravity effect.

## Installation

### CLI

```bash
npx @modus-ui/cli add magnet
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/magnet.tsx`.
3. Paste the code.

## Usage

```tsx
import { Magnet } from "@/components/ui/magnet";

export default function Example() {
  return (
    <Magnet padding={150} magnetStrength={3}>
      <button>Magnetic Button</button>
    </Magnet>
  );
}
```

## Props

| Prop                 | Type      | Default                        | Description                                                         |
| :------------------- | :-------- | :----------------------------- | :------------------------------------------------------------------ |
| `padding`            | `number`  | `100`                          | Distance in pixels around the element within which the pull starts. |
| `disabled`           | `boolean` | `false`                        | Turns the magnetic effect off.                                      |
| `magnetStrength`     | `number`  | `2`                            | Divisor for the pull; higher values move the element less.          |
| `activeTransition`   | `string`  | `"transform 0.3s ease-out"`    | CSS transition used while the cursor is in range.                   |
| `inactiveTransition` | `string`  | `"transform 0.5s ease-in-out"` | CSS transition used when the element springs back.                  |
| `wrapperClassName`   | `string`  | `""`                           | Classes for the outer wrapper.                                      |
| `innerClassName`     | `string`  | `""`                           | Classes for the moving inner element.                               |

## Source

`components/ui/magnet.tsx`

```tsx
"use client";
// Pulls its child toward the cursor once the cursor comes within `padding` pixels.

import { useEffect, useRef, useState, type ReactNode } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface MagnetProps {
  children: ReactNode;
  padding?: number;
  disabled?: boolean;
  magnetStrength?: number;
  activeTransition?: string;
  inactiveTransition?: string;
  wrapperClassName?: string;
  innerClassName?: string;
}

export function Magnet({
  children,
  padding = 100,
  disabled = false,
  magnetStrength = 2,
  activeTransition = "transform 0.3s ease-out",
  inactiveTransition = "transform 0.5s ease-in-out",
  wrapperClassName = "",
  innerClassName = "",
}: MagnetProps) {
  const ref = useRef<HTMLDivElement>(null);
  const reduceMotion = useReducedMotion();
  const [pull, setPull] = useState<{ x: number; y: number } | null>(null);
  const off = disabled || reduceMotion;

  useEffect(() => {
    if (off) {
      setPull(null);
      return;
    }
    const onMove = (event: PointerEvent) => {
      const el = ref.current;
      if (!el) return;
      const box = el.getBoundingClientRect();
      const inRange =
        event.clientX > box.left - padding &&
        event.clientX < box.right + padding &&
        event.clientY > box.top - padding &&
        event.clientY < box.bottom + padding;
      setPull(
        inRange
          ? {
              x: (event.clientX - (box.left + box.width / 2)) / magnetStrength,
              y: (event.clientY - (box.top + box.height / 2)) / magnetStrength,
            }
          : null,
      );
    };
    window.addEventListener("pointermove", onMove);
    return () => window.removeEventListener("pointermove", onMove);
  }, [off, padding, magnetStrength]);

  return (
    <div ref={ref} className={cn("relative inline-block", wrapperClassName)}>
      <div
        className={cn("will-change-transform", innerClassName)}
        style={{
          transform: `translate3d(${pull?.x ?? 0}px, ${pull?.y ?? 0}px, 0)`,
          transition: pull ? activeTransition : inactiveTransition,
        }}
      >
        {children}
      </div>
    </div>
  );
}
```

---

# Magic Button

> A smooth animated button using Framer Motion.

Install: `npx @modus-ui/cli add magic-button`

A smooth animated button built with **Framer Motion**. It supports hover scales and tap interactions out of the box.

## Installation

### CLI

```bash
npx @modus-ui/cli add magic-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/magic-button.tsx`.
3. Paste the code.

## Usage

```tsx
import { MagicButton } from "@/components/magic-button";

export default function Example() {
  return <MagicButton>Magic</MagicButton>;
}
```

## Source

`components/ui/magic-button.tsx`

```tsx
"use client";

import React from "react";
import { motion, useReducedMotion } from "framer-motion";

export const MagicButton = () => {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.button
      whileHover={prefersReducedMotion ? undefined : { scale: 1.05 }}
      whileTap={prefersReducedMotion ? undefined : { scale: 0.95 }}
      className="rounded-lg bg-indigo-600 px-6 py-2 font-medium text-white shadow-lg transition-colors hover:bg-indigo-700 motion-reduce:transition-none"
    >
      Magic Button
    </motion.button>
  );
};
```

---

# Animated Button

> A smooth button with hover and tap scale animations using Framer Motion.

Install: `npx @modus-ui/cli add animated-button`

A smooth button with hover and tap scale animations using Framer Motion. Built to provide tactile feedback and a premium feel to interactive elements.

## Installation

### CLI

```bash
npx @modus-ui/cli add animated-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/animated-button.tsx`.
3. Paste the code.

## Usage

```tsx
import { AnimatedButton } from "@/components/ui/animated-button";

export default function Example() {
  return <AnimatedButton>Click Me</AnimatedButton>;
}
```

## Props

| Prop        | Type        | Default | Description                            |
| :---------- | :---------- | :------ | :------------------------------------- |
| `children`  | `ReactNode` | -       | The content inside the button.         |
| `className` | `string`    | -       | Additional CSS classes for the button. |

## Source

`components/ui/animated-button.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

interface AnimatedButtonProps {
  children: React.ReactNode;
  className?: string;
}

export function AnimatedButton({ children, className }: AnimatedButtonProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.button
      className={cn("rounded-lg bg-blue-500 px-4 py-2 text-white", className)}
      whileHover={prefersReducedMotion ? undefined : { scale: 1.05 }}
      whileTap={prefersReducedMotion ? undefined : { scale: 0.95 }}
    >
      {children}
    </motion.button>
  );
}
```

---

# Pulse Button

> A button with an organic, rhythmic pulsing animation to draw user attention.

Install: `npx @modus-ui/cli add pulse-button`

A button with an organic, rhythmic pulsing animation to draw user attention. Perfect for primary calls to action or "live" indicators.

## Installation

### CLI

```bash
npx @modus-ui/cli add pulse-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pulse-button.tsx`.
3. Paste the code.

## Usage

```tsx
import { PulseButton } from "@/components/ui/pulse-button";

export default function Example() {
  return <PulseButton>Get Started</PulseButton>;
}
```

## Props

| Prop        | Type        | Default | Description                            |
| :---------- | :---------- | :------ | :------------------------------------- |
| `children`  | `ReactNode` | -       | The content inside the button.         |
| `className` | `string`    | -       | Additional CSS classes for the button. |

## Source

`components/ui/pulse-button.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

interface PulseButtonProps {
  children: React.ReactNode;
  className?: string;
}

export function PulseButton({ children, className }: PulseButtonProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.button
      className={cn("rounded-lg bg-green-500 px-4 py-2 text-white", className)}
      // Reduced motion: no pulse; the button rests at its natural scale.
      animate={prefersReducedMotion ? undefined : { scale: [1, 1.1, 1] }}
      transition={prefersReducedMotion ? undefined : { duration: 1, repeat: Infinity }}
    >
      {children}
    </motion.button>
  );
}
```

---

# Bounce Cards

> A stack of playing cards that fan out and straighten out interactively when hovered.

Install: `npx @modus-ui/cli add bounce-cards`

A stack of playing cards that fan out and straighten out interactively when hovered. This component dynamically calculates transform positions and spring physics using purely Framer Motion, skipping heavy libraries like GSAP.

## Installation

### CLI

```bash
npx @modus-ui/cli add bounce-cards
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/bounce-cards.tsx`.
3. Paste the code.

## Usage

```tsx
import { BounceCards } from "@/components/ui/bounce-cards";

export default function Example() {
  const images = ["https://...", "https://..."];

  return (
    <BounceCards
      images={images}
      containerWidth={500}
      containerHeight={400}
      animationDelay={0.2}
      animationStagger={0.08}
      enableHover={true}
    />
  );
}
```

## Props

| Prop               | Type               | Default | Description                                     |
| :----------------- | :----------------- | :------ | :---------------------------------------------- |
| `images`           | `string[]`         | `[]`    | Image URLs for the cards.                       |
| `containerWidth`   | `number \| string` | `400`   | Width of the container.                         |
| `containerHeight`  | `number \| string` | `400`   | Height of the container.                        |
| `animationDelay`   | `number`           | `0.5`   | Delay in seconds before the cards bounce in.    |
| `animationStagger` | `number`           | `0.06`  | Delay in seconds between each card.             |
| `enableHover`      | `boolean`          | `false` | Spreads the cards apart when one is hovered.    |
| `transformStyles`  | `string[]`         | `[...]` | CSS transform for each card's resting position. |

## Source

`components/ui/bounce-cards.tsx`

```tsx
"use client";
// A fanned stack of photo cards that springs in and parts around the hovered card.

import { useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const DEFAULT_TRANSFORMS = [
  "rotate(10deg) translate(-170px)",
  "rotate(5deg) translate(-85px)",
  "rotate(-3deg)",
  "rotate(-10deg) translate(85px)",
  "rotate(2deg) translate(170px)",
];

const PUSH = 140;

function parsePose(transform: string) {
  const rotate = Number(transform.match(/rotate\((-?[\d.]+)deg\)/)?.[1] ?? 0);
  const x = Number(transform.match(/translate(?:X)?\((-?[\d.]+)px/)?.[1] ?? 0);
  return { rotate, x };
}

export interface BounceCardsProps {
  images?: string[];
  containerWidth?: number | string;
  containerHeight?: number | string;
  animationDelay?: number;
  animationStagger?: number;
  enableHover?: boolean;
  transformStyles?: string[];
  className?: string;
}

export function BounceCards({
  images = [],
  containerWidth = 400,
  containerHeight = 400,
  animationDelay = 0.5,
  animationStagger = 0.06,
  enableHover = false,
  transformStyles = DEFAULT_TRANSFORMS,
  className,
}: BounceCardsProps) {
  const reduceMotion = useReducedMotion();
  const [active, setActive] = useState<number | null>(null);

  return (
    <div
      className={cn("relative flex items-center justify-center", className)}
      style={{ width: containerWidth, height: containerHeight }}
      onMouseLeave={() => setActive(null)}
    >
      {images.map((src, i) => {
        const pose = parsePose(transformStyles[i] ?? "");
        const focused = active === i;
        const shift = active === null || focused ? 0 : i < active ? -PUSH : PUSH;

        return (
          <motion.div
            key={i}
            className="absolute aspect-square w-[200px] overflow-hidden rounded-[28px] border-8 border-card bg-muted shadow-xl"
            initial={reduceMotion ? false : { scale: 0, rotate: pose.rotate, x: pose.x }}
            animate={{
              scale: 1,
              rotate: focused ? 0 : pose.rotate,
              x: pose.x + shift,
              zIndex: focused ? images.length : i,
            }}
            transition={
              reduceMotion
                ? { duration: 0 }
                : {
                    type: "spring",
                    stiffness: 260,
                    damping: 14,
                    scale: {
                      type: "spring",
                      stiffness: 300,
                      damping: 11,
                      delay: animationDelay + i * animationStagger,
                    },
                  }
            }
            onMouseEnter={enableHover ? () => setActive(i) : undefined}
          >
            <img
              src={src}
              alt=""
              draggable={false}
              className="m-0 block h-full w-full object-cover"
            />
          </motion.div>
        );
      })}
    </div>
  );
}
```

---

# Masonry Grid

> A fully responsive, animated masonry layout powered by Framer Motion.

Install: `npx @modus-ui/cli add masonry-grid`

A fully responsive, animated masonry layout powered by Framer Motion. It automatically calculates column sizes based on screen width and provides stunning entrance animations with blur effects.

## Installation

### CLI

```bash
npx @modus-ui/cli add masonry-grid
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/masonry-grid.tsx`.
3. Paste the code.

## Usage

```tsx
import { MasonryGrid } from "@/components/ui/masonry-grid";

export default function Example() {
  const items = [
    { id: 1, height: 300, content: <div className="h-full w-full rounded-xl bg-primary/20" /> },
    { id: 2, height: 200, content: <div className="h-full w-full rounded-xl bg-primary/40" /> },
    { id: 3, height: 400, content: <div className="h-full w-full rounded-xl bg-primary/60" /> },
  ];

  return <MasonryGrid items={items} animateFrom="bottom" stagger={0.05} />;
}
```

## Props

| Prop          | Type                                                             | Default    | Description                                                |
| :------------ | :--------------------------------------------------------------- | :--------- | :--------------------------------------------------------- |
| `items`       | `MasonryItem[]`                                                  | `[]`       | Array of objects containing `id`, `height`, and `content`. |
| `animateFrom` | `"top" \| "bottom" \| "left" \| "right" \| "center" \| "random"` | `"bottom"` | Direction from which items animate in.                     |
| `stagger`     | `number`                                                         | `0.05`     | Delay interval between item animations.                    |

## Source

`components/ui/masonry-grid.tsx`

```tsx
"use client";

import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
import { motion, AnimatePresence, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const useMedia = (queries: string[], values: number[], defaultValue: number) => {
  const get = () => {
    if (typeof window === "undefined") return defaultValue;
    return values[queries.findIndex((q) => window.matchMedia(q).matches)] ?? defaultValue;
  };

  const [value, setValue] = useState(get);

  useEffect(() => {
    const mediaQueries = queries.map((q) => window.matchMedia(q));
    const handler = () => setValue(get);
    mediaQueries.forEach((query) => query.addEventListener("change", handler));
    return () => mediaQueries.forEach((query) => query.removeEventListener("change", handler));
  }, [queries]);

  return value;
};

const useMeasure = () => {
  const ref = useRef<HTMLDivElement>(null);
  const [size, setSize] = useState({ width: 0, height: 0 });

  useLayoutEffect(() => {
    if (!ref.current) return;
    const ro = new ResizeObserver(([entry]) => {
      const { width, height } = entry.contentRect;
      setSize({ width, height });
    });
    ro.observe(ref.current);
    return () => ro.disconnect();
  }, []);

  return [ref, size] as const;
};

export interface MasonryItem {
  id: string | number;
  height: number;
  content: React.ReactNode;
}

export interface MasonryGridProps {
  items: MasonryItem[];
  animateFrom?: "top" | "bottom" | "left" | "right" | "center" | "random";
  stagger?: number;
  className?: string;
}

export function MasonryGrid({
  items,
  animateFrom = "bottom",
  stagger = 0.05,
  className,
}: MasonryGridProps) {
  const columns = useMedia(
    ["(min-width: 1500px)", "(min-width: 1000px)", "(min-width: 600px)", "(min-width: 400px)"],
    [5, 4, 3, 2],
    1,
  );

  const [containerRef, { width }] = useMeasure();
  const prefersReducedMotion = useReducedMotion();
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  const grid = useMemo(() => {
    if (!width) return [];
    const colHeights = new Array(columns).fill(0);
    const gap = 16;
    const totalGaps = (columns - 1) * gap;
    const columnWidth = (width - totalGaps) / columns;

    return items.map((child) => {
      const col = colHeights.indexOf(Math.min(...colHeights));
      const x = col * (columnWidth + gap);
      const height = child.height;
      const y = colHeights[col];

      colHeights[col] += height + gap;
      return { ...child, x, y, w: columnWidth, h: height };
    });
  }, [columns, items, width]);

  const getInitialPosition = (item: any) => {
    if (typeof window === "undefined") return { x: item.x, y: item.y };
    const containerRect = containerRef.current?.getBoundingClientRect();
    if (!containerRect) return { x: item.x, y: item.y };

    let direction = animateFrom;
    if (animateFrom === "random") {
      const dirs = ["top", "bottom", "left", "right"];
      direction = dirs[Math.floor(Math.random() * dirs.length)] as any;
    }

    switch (direction) {
      case "top":
        return { x: item.x, y: -200 };
      case "bottom":
        return { x: item.x, y: window.innerHeight + 200 };
      case "left":
        return { x: -200, y: item.y };
      case "right":
        return { x: window.innerWidth + 200, y: item.y };
      case "center":
        return {
          x: containerRect.width / 2 - item.w / 2,
          y: containerRect.height / 2 - item.h / 2,
        };
      default:
        return { x: item.x, y: item.y + 100 };
    }
  };

  const containerHeight = Math.max(...grid.map((i) => i.y + i.h), 0);

  return (
    <div
      ref={containerRef}
      className={cn("relative w-full", className)}
      style={{ height: containerHeight > 0 ? containerHeight : "100vh" }}
    >
      <AnimatePresence>
        {mounted &&
          width > 0 &&
          grid.map((item, index) => (
            <motion.div
              key={item.id}
              layout
              initial={
                prefersReducedMotion
                  ? false
                  : {
                      opacity: 0,
                      ...getInitialPosition(item),
                      width: item.w,
                      height: item.h,
                      filter: "blur(10px)",
                    }
              }
              animate={{
                opacity: 1,
                x: item.x,
                y: item.y,
                width: item.w,
                height: item.h,
                filter: "blur(0px)",
              }}
              exit={
                prefersReducedMotion
                  ? { opacity: 0 }
                  : { opacity: 0, scale: 0.9, filter: "blur(10px)" }
              }
              transition={
                prefersReducedMotion
                  ? { duration: 0 }
                  : {
                      type: "spring",
                      stiffness: 300,
                      damping: 30,
                      opacity: { duration: 0.5, delay: index * stagger },
                      filter: { duration: 0.5, delay: index * stagger },
                      layout: { type: "spring", stiffness: 300, damping: 30 },
                    }
              }
              className="absolute box-border overflow-hidden"
              whileHover={prefersReducedMotion ? undefined : { scale: 0.98 }}
            >
              {item.content}
            </motion.div>
          ))}
      </AnimatePresence>
    </div>
  );
}
```

---

# Animated List

> A scrollable, animated list component with keyboard navigation, hover states, and smooth entrance physics.

Install: `npx @modus-ui/cli add animated-list`

A scrollable, animated list component with keyboard navigation, hover states, and smooth entrance physics. Perfect for settings menus, notifications, or selecting items from a large list.

## Installation

### CLI

```bash
npx @modus-ui/cli add animated-list
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/animated-list.tsx`.
3. Paste the code.

## Usage

```tsx
import { AnimatedList } from "@/components/ui/animated-list";

export default function Example() {
  const items = ["Item 1", "Item 2", "Item 3"];

  return <AnimatedList items={items} />;
}
```

## Props

| Prop                    | Type                                 | Default | Description                                                                     |
| :---------------------- | :----------------------------------- | :------ | :------------------------------------------------------------------------------ |
| `items`                 | `ReactNode[] \| string[]`            | `[...]` | The items to display in the list.                                               |
| `onItemSelect`          | `(item: any, index: number) => void` | -       | Callback when an item is clicked or selected via Enter key.                     |
| `itemClassName`         | `string`                             | -       | Classes for each item.                                                          |
| `showGradients`         | `boolean`                            | `true`  | Whether to show fading gradients at the top and bottom of the scroll container. |
| `enableArrowNavigation` | `boolean`                            | `true`  | Whether to enable up/down arrow and tab key navigation.                         |
| `displayScrollbar`      | `boolean`                            | `true`  | Whether to show the scrollbar.                                                  |
| `initialSelectedIndex`  | `number`                             | `-1`    | The index of the item that is selected initially.                               |

## Source

`components/ui/animated-list.tsx`

```tsx
"use client";
// Scrollable list whose rows rise into view, with keyboard selection.
import { useEffect, useRef, useState, type KeyboardEvent, type ReactNode } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface AnimatedListProps {
  items?: ReactNode[] | string[];
  onItemSelect?: (item: any, index: number) => void;
  className?: string;
  itemClassName?: string;
  showGradients?: boolean;
  enableArrowNavigation?: boolean;
  displayScrollbar?: boolean;
  initialSelectedIndex?: number;
}

const SAMPLE = Array.from({ length: 12 }, (_, i) => `Item ${i + 1}`);

export function AnimatedList({
  items = SAMPLE,
  onItemSelect,
  className,
  itemClassName,
  showGradients = true,
  enableArrowNavigation = true,
  displayScrollbar = true,
  initialSelectedIndex = -1,
}: AnimatedListProps) {
  const reduce = useReducedMotion();
  const scroller = useRef<HTMLDivElement>(null);
  const rows = useRef<(HTMLLIElement | null)[]>([]);
  const [active, setActive] = useState(initialSelectedIndex);
  const [edges, setEdges] = useState({ top: false, bottom: false });

  const measure = () => {
    const el = scroller.current;
    if (!el) return;
    setEdges({
      top: el.scrollTop > 4,
      bottom: el.scrollTop + el.clientHeight < el.scrollHeight - 4,
    });
  };

  useEffect(measure, [items]);

  useEffect(() => {
    rows.current[active]?.scrollIntoView({
      block: "nearest",
      behavior: reduce ? "auto" : "smooth",
    });
  }, [active, reduce]);

  const select = (index: number) => {
    setActive(index);
    onItemSelect?.(items[index], index);
  };

  const onKeyDown = (e: KeyboardEvent) => {
    if (!enableArrowNavigation) return;
    const step =
      e.key === "ArrowDown" || (e.key === "Tab" && !e.shiftKey)
        ? 1
        : e.key === "ArrowUp" || (e.key === "Tab" && e.shiftKey)
          ? -1
          : 0;
    if (step) {
      const next = active + step;
      // Let Tab leave the list at either end.
      if (next < 0 || next >= items.length) {
        if (e.key !== "Tab") e.preventDefault();
        return;
      }
      e.preventDefault();
      setActive(next);
    } else if (e.key === "Enter" && active >= 0) {
      e.preventDefault();
      select(active);
    }
  };

  return (
    <div className={cn("relative w-full max-w-md", className)}>
      <div
        ref={scroller}
        onScroll={measure}
        onKeyDown={onKeyDown}
        tabIndex={0}
        role="listbox"
        aria-activedescendant={active >= 0 ? `al-${active}` : undefined}
        className={cn(
          "max-h-[400px] overflow-y-auto rounded-xl p-1 outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
          !displayScrollbar && "[scrollbar-width:none] [&::-webkit-scrollbar]:hidden",
        )}
      >
        <ul className="flex list-none flex-col gap-3 p-0">
          {items.map((item, i) => (
            <motion.li
              key={i}
              id={`al-${i}`}
              role="option"
              aria-selected={i === active}
              ref={(node) => {
                rows.current[i] = node;
              }}
              initial={reduce ? false : { opacity: 0, y: 16, scale: 0.96 }}
              whileInView={{ opacity: 1, y: 0, scale: 1 }}
              viewport={{ root: scroller, amount: 0.4 }}
              transition={{ type: "spring", stiffness: 320, damping: 28 }}
              onMouseEnter={() => setActive(i)}
              onClick={() => select(i)}
              className={cn(
                "cursor-pointer rounded-xl border border-[hsl(var(--border))] bg-[hsl(var(--card))] p-4 text-[hsl(var(--card-foreground))] transition-colors",
                i === active && "border-[hsl(var(--ring))] bg-[hsl(var(--accent))]",
                itemClassName,
              )}
            >
              {item}
            </motion.li>
          ))}
        </ul>
      </div>
      {showGradients && (
        <>
          <div
            aria-hidden
            className={cn(
              "pointer-events-none absolute inset-x-0 top-0 h-12 bg-gradient-to-b from-[hsl(var(--background))] to-transparent transition-opacity",
              edges.top ? "opacity-100" : "opacity-0",
            )}
          />
          <div
            aria-hidden
            className={cn(
              "pointer-events-none absolute inset-x-0 bottom-0 h-16 bg-gradient-to-t from-[hsl(var(--background))] to-transparent transition-opacity",
              edges.bottom ? "opacity-100" : "opacity-0",
            )}
          />
        </>
      )}
    </div>
  );
}
```

---

# Kinetic Carousel

> A modern, physics-based carousel that supports dragging, infinite looping, and 3D perspective transitions.

Install: `npx @modus-ui/cli add kinetic-carousel`

A modern, physics-based carousel that supports dragging, infinite looping, and 3D perspective transitions. Excellent for testimonials, feature spotlights, or image galleries.

## Installation

### CLI

```bash
npx @modus-ui/cli add kinetic-carousel
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/kinetic-carousel.tsx`.
3. Paste the code.

## Usage

```tsx
import { KineticCarousel } from "@/components/ui/kinetic-carousel";

export default function Example() {
  const items = [
    <div key="1" className="flex h-48 items-center justify-center rounded-xl bg-muted p-8">
      Slide 1
    </div>,
    <div key="2" className="flex h-48 items-center justify-center rounded-xl bg-muted p-8">
      Slide 2
    </div>,
    <div key="3" className="flex h-48 items-center justify-center rounded-xl bg-muted p-8">
      Slide 3
    </div>,
  ];

  return <KineticCarousel items={items} loop={true} autoplay={true} />;
}
```

## Props

| Prop            | Type          | Default | Description                                                                        |
| :-------------- | :------------ | :------ | :--------------------------------------------------------------------------------- |
| `items`         | `ReactNode[]` | `[]`    | Array of React elements to display as slides.                                      |
| `baseWidth`     | `number`      | `320`   | The total width of the carousel container in pixels.                               |
| `autoplay`      | `boolean`     | `false` | Whether the carousel should automatically cycle.                                   |
| `autoplayDelay` | `number`      | `3000`  | The delay in milliseconds between automatic slide transitions.                     |
| `pauseOnHover`  | `boolean`     | `false` | Whether to pause autoplay when the user hovers over the carousel.                  |
| `loop`          | `boolean`     | `false` | Whether the carousel should infinitely loop from the last slide back to the first. |

## Source

`components/ui/kinetic-carousel.tsx`

```tsx
"use client";

import React, { useState, useEffect, useRef, useMemo } from "react";
import { motion, useMotionValue, useReducedMotion, useTransform, PanInfo } from "framer-motion";
import { cn } from "@/lib/utils";

const DRAG_BUFFER = 0;
const VELOCITY_THRESHOLD = 500;
const GAP = 16;
const SPRING_OPTIONS = { type: "spring" as any, stiffness: 300, damping: 30 };

interface CarouselItemProps {
  children: React.ReactNode;
  index: number;
  itemWidth: number;
  trackItemOffset: number;
  x: any;
  transition: any;
}

function CarouselItem({
  children,
  index,
  itemWidth,
  trackItemOffset,
  x,
  transition,
}: CarouselItemProps) {
  const range = [
    -(index + 1) * trackItemOffset,
    -index * trackItemOffset,
    -(index - 1) * trackItemOffset,
  ];
  const outputRange = [90, 0, -90];
  const rotateY = useTransform(x, range, outputRange, { clamp: false });

  return (
    <motion.div
      className="relative flex shrink-0 cursor-grab flex-col overflow-hidden rounded-2xl border border-border bg-card active:cursor-grabbing"
      style={{
        width: itemWidth,
        rotateY: rotateY,
      }}
      transition={transition}
    >
      {children}
    </motion.div>
  );
}

export interface KineticCarouselProps extends React.HTMLAttributes<HTMLDivElement> {
  items: React.ReactNode[];
  baseWidth?: number;
  autoplay?: boolean;
  autoplayDelay?: number;
  pauseOnHover?: boolean;
  loop?: boolean;
}

export function KineticCarousel({
  items,
  baseWidth = 320,
  autoplay = false,
  autoplayDelay = 3000,
  pauseOnHover = false,
  loop = false,
  className,
  ...props
}: KineticCarouselProps) {
  const containerPadding = 16;
  // Never wider than the space it is given, so cards stay whole on narrow screens.
  const [width, setWidth] = useState(baseWidth);
  const itemWidth = width - containerPadding * 2;
  const trackItemOffset = itemWidth + GAP;

  const itemsForRender = useMemo(() => {
    if (!loop) return items;
    if (items.length === 0) return [];
    return [items[items.length - 1], ...items, items[0]];
  }, [items, loop]);

  const [position, setPosition] = useState(loop ? 1 : 0);
  const x = useMotionValue(0);
  const [isHovered, setIsHovered] = useState(false);
  const [isJumping, setIsJumping] = useState(false);
  const [isAnimating, setIsAnimating] = useState(false);
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const parent = containerRef.current?.parentElement;
    if (!parent) return;
    const observer = new ResizeObserver(([entry]) => {
      setWidth(Math.min(baseWidth, entry.contentRect.width || baseWidth));
    });
    observer.observe(parent);
    return () => observer.disconnect();
  }, [baseWidth]);
  const prefersReducedMotion = useReducedMotion();

  useEffect(() => {
    if (pauseOnHover && containerRef.current) {
      const container = containerRef.current;
      const handleMouseEnter = () => setIsHovered(true);
      const handleMouseLeave = () => setIsHovered(false);
      container.addEventListener("mouseenter", handleMouseEnter);
      container.addEventListener("mouseleave", handleMouseLeave);
      return () => {
        container.removeEventListener("mouseenter", handleMouseEnter);
        container.removeEventListener("mouseleave", handleMouseLeave);
      };
    }
  }, [pauseOnHover]);

  useEffect(() => {
    // Reduced motion: no auto-advance; drag and the dots still work.
    if (!autoplay || prefersReducedMotion || itemsForRender.length <= 1) return;
    if (pauseOnHover && isHovered) return;

    const timer = setInterval(() => {
      setPosition((prev) => Math.min(prev + 1, itemsForRender.length - 1));
    }, autoplayDelay);

    return () => clearInterval(timer);
  }, [
    autoplay,
    prefersReducedMotion,
    autoplayDelay,
    isHovered,
    pauseOnHover,
    itemsForRender.length,
  ]);

  useEffect(() => {
    const startingPosition = loop ? 1 : 0;
    setPosition(startingPosition);
    x.set(-startingPosition * trackItemOffset);
  }, [items.length, loop, trackItemOffset, x]);

  useEffect(() => {
    if (!loop && position > itemsForRender.length - 1) {
      setPosition(Math.max(0, itemsForRender.length - 1));
    }
  }, [itemsForRender.length, loop, position]);

  const effectiveTransition = isJumping || prefersReducedMotion ? { duration: 0 } : SPRING_OPTIONS;

  const handleAnimationStart = () => setIsAnimating(true);

  const handleAnimationComplete = () => {
    if (!loop || itemsForRender.length <= 1) {
      setIsAnimating(false);
      return;
    }
    const lastCloneIndex = itemsForRender.length - 1;

    if (position === lastCloneIndex) {
      setIsJumping(true);
      setPosition(1);
      x.set(-1 * trackItemOffset);
      requestAnimationFrame(() => {
        setIsJumping(false);
        setIsAnimating(false);
      });
      return;
    }

    if (position === 0) {
      setIsJumping(true);
      setPosition(items.length);
      x.set(-items.length * trackItemOffset);
      requestAnimationFrame(() => {
        setIsJumping(false);
        setIsAnimating(false);
      });
      return;
    }

    setIsAnimating(false);
  };

  const handleDragEnd = (_: any, info: PanInfo) => {
    const { offset, velocity } = info;
    const direction =
      offset.x < -DRAG_BUFFER || velocity.x < -VELOCITY_THRESHOLD
        ? 1
        : offset.x > DRAG_BUFFER || velocity.x > VELOCITY_THRESHOLD
          ? -1
          : 0;

    if (direction === 0) return;

    setPosition((prev) => {
      const next = prev + direction;
      const max = itemsForRender.length - 1;
      return Math.max(0, Math.min(next, max));
    });
  };

  const dragProps = loop
    ? {}
    : {
        dragConstraints: {
          left: -trackItemOffset * Math.max(itemsForRender.length - 1, 0),
          right: 0,
        },
      };

  const activeIndex =
    items.length === 0
      ? 0
      : loop
        ? (position - 1 + items.length) % items.length
        : Math.min(position, items.length - 1);

  if (items.length === 0) return null;

  return (
    <div
      ref={containerRef}
      className={cn(
        "relative overflow-hidden rounded-[24px] border border-border bg-background p-4",
        className,
      )}
      style={{ width }}
      {...props}
    >
      <motion.div
        className="flex"
        drag={isAnimating ? false : "x"}
        {...dragProps}
        style={{
          width: itemWidth,
          gap: `${GAP}px`,
          perspective: 1000,
          perspectiveOrigin: `${position * trackItemOffset + itemWidth / 2}px 50%`,
          x,
        }}
        onDragEnd={handleDragEnd}
        animate={{ x: -(position * trackItemOffset) }}
        transition={effectiveTransition}
        onAnimationStart={handleAnimationStart}
        onAnimationComplete={handleAnimationComplete}
      >
        {itemsForRender.map((item, index) => (
          <CarouselItem
            key={index}
            index={index}
            itemWidth={itemWidth}
            trackItemOffset={trackItemOffset}
            x={x}
            transition={effectiveTransition}
          >
            {item}
          </CarouselItem>
        ))}
      </motion.div>

      <div className="mt-4 flex w-full justify-center">
        <div className="flex w-[150px] justify-between px-8">
          {items.map((_, index) => (
            <motion.button
              type="button"
              key={index}
              aria-label={`Go to slide ${index + 1}`}
              aria-current={activeIndex === index}
              className={cn(
                "h-2 w-2 cursor-pointer appearance-none rounded-full transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary",
                activeIndex === index ? "bg-primary" : "bg-muted-foreground/30",
              )}
              animate={{ scale: activeIndex === index ? 1.2 : 1 }}
              onClick={() => setPosition(loop ? index + 1 : index)}
              transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.15 }}
            />
          ))}
        </div>
      </div>
    </div>
  );
}
```

---

# Expandable Showcase

> A horizontal or vertical list of items where hovering or clicking expands one item while shrinking others.

Install: `npx @modus-ui/cli add expandable-showcase`

A horizontal or vertical list of items where hovering or clicking expands one item while shrinking others. Perfect for image galleries, product showcases, or interactive feature lists.

## Installation

### CLI

```bash
npx @modus-ui/cli add expandable-showcase
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/expandable-showcase.tsx`.
3. Paste the code.

## Usage

```tsx
import { ExpandableShowcase } from "@/components/ui/expandable-showcase";

export default function Example() {
  const items = [
    { id: 1, image: "/img1.jpg", label: "Mountain" },
    { id: 2, image: "/img2.jpg", label: "River" },
    { id: 3, image: "/img3.jpg", label: "Forest" },
  ];

  return <ExpandableShowcase items={items} />;
}
```

## Props

| Prop           | Type                         | Default        | Description                                       |
| :------------- | :--------------------------- | :------------- | :------------------------------------------------ |
| `items`        | `ShowcaseItem[]`             | -              | Array of objects containing id, image, and label. |
| `defaultIndex` | `number`                     | `0`            | The index of the initially expanded item.         |
| `orientation`  | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the gallery.                         |
| `height`       | `number \| string`           | `460`          | Height of the container.                          |
| `gap`          | `number`                     | `12`           | Spacing between items.                            |

## Source

`components/ui/expandable-showcase.tsx`

```tsx
"use client";

import React, { useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ShowcaseItem {
  id: string | number;
  image: string;
  label: string;
  link?: string;
  alt?: string;
}

export interface ExpandableShowcaseProps extends React.HTMLAttributes<HTMLDivElement> {
  items: ShowcaseItem[];
  defaultIndex?: number;
  orientation?: "horizontal" | "vertical";
  height?: number | string;
  gap?: number;
  className?: string;
}

export function ExpandableShowcase({
  items,
  defaultIndex = 0,
  orientation = "horizontal",
  height = 460,
  gap = 12,
  className,
  ...props
}: ExpandableShowcaseProps) {
  const [active, setActive] = useState(defaultIndex);
  const prefersReducedMotion = useReducedMotion();
  const instant = { duration: 0 };

  const isVertical = orientation === "vertical";

  return (
    <div
      className={cn("flex w-full overflow-hidden", isVertical ? "flex-col" : "flex-row", className)}
      style={{
        height: isVertical ? "auto" : height,
        minHeight: isVertical ? height : "auto",
        gap,
      }}
      role="list"
      aria-label="Expandable image gallery"
      {...props}
    >
      {items.map((item, i) => {
        const isActive = i === active;

        // Use motion.a if link is provided, otherwise motion.div
        const Tag = item.link ? motion.a : motion.div;

        return (
          <Tag
            key={item.id}
            href={item.link}
            onClick={() => setActive(i)}
            onFocus={() => setActive(i)}
            onMouseEnter={() => setActive(i)}
            onKeyDown={(e: React.KeyboardEvent) => {
              if (e.key === "Enter" || e.key === " ") {
                e.preventDefault();
                setActive(i);
                if (item.link) {
                  window.location.href = item.link;
                }
              } else if (e.key === "ArrowRight" || e.key === "ArrowDown") {
                e.preventDefault();
                setActive((i + 1) % items.length);
              } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
                e.preventDefault();
                setActive((i - 1 + items.length) % items.length);
              }
            }}
            tabIndex={0}
            role="listitem"
            aria-expanded={isActive}
            className="group relative cursor-pointer overflow-hidden rounded-2xl outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2"
            animate={{
              flexGrow: isActive ? 4 : 1,
              flexShrink: isActive ? 0 : 1,
              flexBasis: isActive ? (isVertical ? "40%" : "40%") : "15%",
            }}
            transition={
              prefersReducedMotion ? instant : { type: "spring", stiffness: 200, damping: 25 }
            }
            style={{
              minHeight: isVertical ? 80 : "auto",
            }}
          >
            {/* Image Layer */}
            <motion.div
              className="absolute inset-0 h-full w-full"
              animate={{
                filter: isActive ? "grayscale(0%)" : "grayscale(80%)",
              }}
              transition={prefersReducedMotion ? instant : { duration: 0.4 }}
            >
              <img
                src={item.image}
                alt={item.alt || item.label}
                className="absolute inset-0 h-full w-full object-cover"
                draggable={false}
              />
            </motion.div>

            {/* Gradient Overlay for Text Readability */}
            <motion.div
              className="absolute inset-0"
              animate={{
                background: isActive
                  ? "linear-gradient(to top, rgba(0,0,0,0.8) 0%, rgba(0,0,0,0) 50%)"
                  : "linear-gradient(to top, rgba(0,0,0,0.4) 0%, rgba(0,0,0,0) 100%)",
              }}
              transition={prefersReducedMotion ? instant : { duration: 0.4 }}
            />

            {/* Label and Indicator */}
            <div className="absolute bottom-6 left-6 right-6 flex items-center gap-4">
              <motion.div
                className="h-6 w-1 rounded-full bg-primary"
                initial={false}
                animate={{
                  opacity: isActive ? 1 : 0,
                  x: isActive || prefersReducedMotion ? 0 : -10,
                }}
                transition={
                  prefersReducedMotion
                    ? { duration: 0.15 }
                    : { duration: 0.3, delay: isActive ? 0.1 : 0 }
                }
              />
              <motion.span
                className="truncate text-lg font-bold text-white drop-shadow-md"
                initial={false}
                animate={{
                  opacity: isActive ? 1 : 0,
                  x: isActive || prefersReducedMotion ? 0 : -10,
                }}
                transition={
                  prefersReducedMotion
                    ? { duration: 0.15 }
                    : { duration: 0.3, delay: isActive ? 0.15 : 0 }
                }
              >
                {item.label}
              </motion.span>
            </div>
          </Tag>
        );
      })}
    </div>
  );
}
```

---

# Focus Card

> A card with a subtle radial gradient spotlight that follows the user's cursor.

Install: `npx @modus-ui/cli add focus-card`

A card with a subtle radial gradient spotlight that follows the user's cursor, bringing attention to the elements you're hovering over. Great for feature grids and pricing cards.

## Installation

### CLI

```bash
npx @modus-ui/cli add focus-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/focus-card.tsx`.
3. Paste the code.

## Usage

```tsx
import { FocusCard } from "@/components/ui/focus-card";

export default function Example() {
  return (
    <FocusCard>
      <div className="relative z-10 p-8">
        <h3 className="text-xl font-semibold">Hover me</h3>
        <p>The spotlight follows your mouse.</p>
      </div>
    </FocusCard>
  );
}
```

## Props

| Prop             | Type        | Default                       | Description                                 |
| :--------------- | :---------- | :---------------------------- | :------------------------------------------ |
| `children`       | `ReactNode` | -                             | The content inside the card.                |
| `className`      | `string`    | -                             | Additional CSS classes for the card.        |
| `spotlightColor` | `string`    | `"rgba(255, 255, 255, 0.15)"` | The color of the spotlight radial gradient. |

## Source

`components/ui/focus-card.tsx`

```tsx
"use client";

import React, { useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface FocusCardProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode;
  className?: string;
  spotlightColor?: string;
}

export function FocusCard({
  children,
  className,
  spotlightColor = "rgba(255, 255, 255, 0.15)",
  ...props
}: FocusCardProps) {
  const divRef = useRef<HTMLDivElement>(null);
  const [isFocused, setIsFocused] = useState(false);
  const [position, setPosition] = useState({ x: 0, y: 0 });
  const [opacity, setOpacity] = useState(0);
  const prefersReducedMotion = useReducedMotion();

  const handleMouseMove = (e: React.MouseEvent<HTMLDivElement>) => {
    if (!divRef.current || isFocused || prefersReducedMotion) return;

    const rect = divRef.current.getBoundingClientRect();
    setPosition({ x: e.clientX - rect.left, y: e.clientY - rect.top });
  };

  const handleFocus = () => {
    setIsFocused(true);
    setOpacity(0.6);
  };

  const handleBlur = () => {
    setIsFocused(false);
    setOpacity(0);
  };

  const handleMouseEnter = () => {
    setOpacity(0.6);
  };

  const handleMouseLeave = () => {
    setOpacity(0);
  };

  return (
    <div
      ref={divRef}
      onMouseMove={handleMouseMove}
      onFocus={handleFocus}
      onBlur={handleBlur}
      onMouseEnter={handleMouseEnter}
      onMouseLeave={handleMouseLeave}
      className={cn(
        "relative overflow-hidden rounded-3xl border border-border bg-card p-8",
        className,
      )}
      {...props}
    >
      <div
        className="pointer-events-none absolute inset-0 opacity-0 transition-opacity duration-500 ease-in-out motion-reduce:transition-none"
        style={{
          opacity,
          // Reduced motion: a static, centred spotlight instead of one that follows the pointer.
          background: prefersReducedMotion
            ? `radial-gradient(circle at 50% 50%, ${spotlightColor}, transparent 80%)`
            : `radial-gradient(circle at ${position.x}px ${position.y}px, ${spotlightColor}, transparent 80%)`,
        }}
        aria-hidden="true"
      />
      {children}
    </div>
  );
}
```

---

# Rotating Card

> A 3D-style rotating card that responds to user hover with smooth perspective shifts.

Install: `npx @modus-ui/cli add rotating-card`

A 3D-style rotating card that responds to user hover with smooth perspective shifts. Adds depth and interactivity to feature displays or profile cards.

## Installation

### CLI

```bash
npx @modus-ui/cli add rotating-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/rotating-card.tsx`.
3. Paste the code.

## Usage

```tsx
import { RotatingCard } from "@/components/ui/rotating-card";

export default function Example() {
  return (
    <RotatingCard>
      <div className="flex h-48 items-center justify-center p-8">
        <h3 className="font-serif text-xl">Feature Card</h3>
      </div>
    </RotatingCard>
  );
}
```

## Props

| Prop        | Type        | Default | Description                          |
| :---------- | :---------- | :------ | :----------------------------------- |
| `children`  | `ReactNode` | -       | The content inside the card.         |
| `className` | `string`    | -       | Additional CSS classes for the card. |

## Source

`components/ui/rotating-card.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

interface RotatingCardProps {
  children: React.ReactNode;
  className?: string;
}

export function RotatingCard({ children, className }: RotatingCardProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      className={cn("rounded-lg bg-white p-4 shadow-lg dark:bg-gray-800", className)}
      whileHover={prefersReducedMotion ? undefined : { rotateY: 10 }}
      transition={{ type: "spring", stiffness: 300 }}
    >
      {children}
    </motion.div>
  );
}
```

---

# Tilt Card

> A 3D parallax tilt card featuring smooth physics-based rotations on hover, collapsible tags and descriptions, and custom CTA buttons.

Install: `npx @modus-ui/cli add tilt-card`

A highly premium, interactive 3D parallax tilt card designed for presenting project portfolios, case studies, or feature cards. It responds dynamically to mouse/pointer hover with spring-loaded physics and wraps tags and long descriptions with collapsible states.

## Installation

### CLI

```bash
npx @modus-ui/cli add tilt-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tilt-card.tsx`.
3. Paste the code.

## Usage

```tsx
import { TiltCard } from "@/components/ui/tilt-card";

export default function Example() {
  return (
    <TiltCard
      title="AlphaAuctions"
      description="A premium, real-time online auction and bidding platform. Features live bidding rooms."
      image="https://images.unsplash.com/photo-1563013544-824ae1d704d3?auto=format&fit=crop&w=800&q=80"
      tag="Web"
      techStack="Next.js, TypeScript, Tailwind CSS, Prisma, PostgreSQL, Socket.io"
      liveUrl="https://example.com"
      githubUrl="https://github.com"
    />
  );
}
```

## Props

| Prop               | Type                 | Default | Description                                                                     |
| :----------------- | :------------------- | :------ | :------------------------------------------------------------------------------ |
| `title`            | `string`             | -       | The title of the card.                                                          |
| `description`      | `string`             | -       | Descriptive text for the project or feature.                                    |
| `image`            | `string`             | -       | Source URL of the cover image.                                                  |
| `tag`              | `string`             | -       | A category badge overlaid on the top-right of the image (e.g. "Web", "Design"). |
| `techStack`        | `string \| string[]` | -       | A comma-separated string or array of tags for technical skills/tools.           |
| `liveUrl`          | `string`             | -       | URL for the interactive preview button.                                         |
| `githubUrl`        | `string`             | -       | URL for the github source repository button.                                    |
| `caseStudyUrl`     | `string`             | -       | URL to show a separate Case Study button.                                       |
| `onCaseStudyClick` | `() => void`         | -       | Optional custom handler when clicking Case Study.                               |
| `maxTilt`          | `number`             | `15`    | Maximum rotation angle in degrees.                                              |
| `perspective`      | `number`             | `1000`  | Depth perspective value for 3D distortion.                                      |
| `children`         | `ReactNode`          | -       | Direct children override if you wish to build custom inner layout.              |
| `className`        | `string`             | -       | Custom container styles.                                                        |

## Source

`components/ui/tilt-card.tsx`

```tsx
"use client";

import React, { useRef, useState, useEffect } from "react";
import { motion, useMotionValue, useReducedMotion, useSpring, useTransform } from "framer-motion";
import { cn } from "@/lib/utils";

export interface TiltCardProps {
  title?: string;
  description?: string;
  image?: string;
  tag?: string;
  techStack?: string | string[];
  liveUrl?: string;
  githubUrl?: string;
  caseStudyUrl?: string;
  onCaseStudyClick?: () => void;
  className?: string;
  maxTilt?: number;
  perspective?: number;
  children?: React.ReactNode;
}

export function TiltCard({
  title,
  description,
  image,
  tag,
  techStack,
  liveUrl,
  githubUrl,
  caseStudyUrl,
  onCaseStudyClick,
  className,
  maxTilt = 15,
  perspective = 1000,
  children,
}: TiltCardProps) {
  const cardRef = useRef<HTMLDivElement>(null);
  const [tiltEnabled, setTiltEnabled] = useState(true);
  const [isExpanded, setIsExpanded] = useState(false);
  const [isTechExpanded, setIsTechExpanded] = useState(false);
  const prefersReducedMotion = useReducedMotion();
  // Reduced motion: the card stays flat and does not follow the pointer.
  const shouldTilt = tiltEnabled && !prefersReducedMotion;

  // Disable tilt on mobile/tablets for better UX
  useEffect(() => {
    const checkScreenSize = () => {
      setTiltEnabled(window.innerWidth >= 768);
    };
    checkScreenSize();
    window.addEventListener("resize", checkScreenSize);
    return () => window.removeEventListener("resize", checkScreenSize);
  }, []);

  const x = useMotionValue(0);
  const y = useMotionValue(0);

  const rotateXSpring = useSpring(y, { stiffness: 150, damping: 20 });
  const rotateYSpring = useSpring(x, { stiffness: 150, damping: 20 });

  const rotateX = useTransform(rotateXSpring, [-0.5, 0.5], [maxTilt, -maxTilt]);
  const rotateY = useTransform(rotateYSpring, [-0.5, 0.5], [-maxTilt, maxTilt]);

  const handleMouseMove = (event: React.MouseEvent<HTMLDivElement>) => {
    if (!shouldTilt || !cardRef.current) return;
    const rect = cardRef.current.getBoundingClientRect();
    const width = rect.width;
    const height = rect.height;

    const relativeX = (event.clientX - rect.left) / width - 0.5;
    const relativeY = (event.clientY - rect.top) / height - 0.5;

    x.set(relativeX);
    y.set(relativeY);
  };

  const handleMouseLeave = () => {
    x.set(0);
    y.set(0);
  };

  // Process tech stack tags
  const tags: string[] = React.useMemo(() => {
    if (!techStack) return [];
    if (Array.isArray(techStack)) return techStack;
    return techStack
      .split(",")
      .map((t) => t.trim())
      .filter(Boolean);
  }, [techStack]);

  const maxVisibleTags = 4;
  const hasMoreTags = tags.length > maxVisibleTags;
  const visibleTags = isTechExpanded ? tags : tags.slice(0, maxVisibleTags);
  const remainingTags = tags.length - maxVisibleTags;

  return (
    <motion.div
      ref={cardRef}
      onMouseMove={handleMouseMove}
      onMouseLeave={handleMouseLeave}
      style={{
        transformStyle: "preserve-3d",
        transformPerspective: perspective,
        rotateX: shouldTilt ? rotateX : 0,
        rotateY: shouldTilt ? rotateY : 0,
      }}
      className={cn(
        "flex w-full max-w-[360px] select-none flex-col justify-between overflow-hidden rounded-2xl border border-border bg-background p-5 shadow-sm transition-all duration-300 hover:shadow-md",
        className,
      )}
    >
      {children ? (
        children
      ) : (
        <div className="flex h-full flex-col gap-4" style={{ transform: "translateZ(20px)" }}>
          {/* Project Image Section */}
          {image && (
            <div className="relative h-[200px] w-full overflow-hidden rounded-xl border border-border/60 bg-card">
              <img
                src={image}
                alt={title || "Project image"}
                className="h-full w-full object-cover transition-transform duration-500 hover:scale-105 motion-reduce:transition-none motion-reduce:hover:scale-100"
                loading="lazy"
              />
              {tag && (
                <span className="absolute right-3 top-3 rounded-full border border-border bg-background/90 px-3 py-1 text-[10px] font-bold uppercase tracking-[0.1em] text-muted-foreground backdrop-blur-sm">
                  {tag}
                </span>
              )}
            </div>
          )}

          {/* Heading */}
          <div className="space-y-1">
            {title && (
              <h3 className="font-serif text-2xl font-normal leading-tight text-foreground">
                {title}
              </h3>
            )}

            {/* Tech Stack Badges */}
            {tags.length > 0 && (
              <div className="flex flex-wrap gap-1.5 pt-1">
                {visibleTags.map((tech, idx) => (
                  <span
                    key={idx}
                    className="inline-flex items-center gap-1 rounded border border-border/60 bg-card px-2 py-0.5 text-[9px] font-semibold uppercase tracking-wider text-muted-foreground shadow-sm"
                  >
                    <span className="h-1 w-1 rounded-full bg-muted-foreground/40" />
                    {tech}
                  </span>
                ))}
                {hasMoreTags && !isTechExpanded && (
                  <button
                    type="button"
                    onClick={(e) => {
                      e.stopPropagation();
                      setIsTechExpanded(true);
                    }}
                    className="inline-flex items-center rounded border border-border/60 bg-secondary px-2 py-0.5 text-[9px] font-bold tracking-wider text-foreground transition-colors hover:bg-background"
                  >
                    +{remainingTags} more
                  </button>
                )}
                {isTechExpanded && (
                  <button
                    type="button"
                    onClick={(e) => {
                      e.stopPropagation();
                      setIsTechExpanded(false);
                    }}
                    className="inline-flex items-center rounded border border-border/60 bg-secondary px-2 py-0.5 text-[9px] font-bold tracking-wider text-foreground transition-colors hover:bg-background"
                  >
                    Show less
                  </button>
                )}
              </div>
            )}
          </div>

          {/* Description */}
          {description && (
            <div className="flex flex-grow flex-col justify-between">
              <p
                className={cn(
                  "text-xs leading-relaxed text-muted-foreground transition-all duration-300",
                  isExpanded ? "line-clamp-none" : "line-clamp-2",
                )}
              >
                {description}
              </p>
              <button
                type="button"
                onClick={(e) => {
                  e.stopPropagation();
                  setIsExpanded(!isExpanded);
                }}
                className="mt-1 self-start text-[10px] font-bold uppercase tracking-wider text-foreground hover:underline"
              >
                {isExpanded ? "Read less" : "Read more"}
              </button>
            </div>
          )}

          {/* CTAs */}
          <div className="mt-auto flex gap-2 pt-2" style={{ transform: "translateZ(10px)" }}>
            {liveUrl && (
              <a
                href={liveUrl}
                target="_blank"
                rel="noopener noreferrer"
                className="flex-1 text-center"
              >
                <button className="w-full rounded-lg border border-border bg-card px-3 py-2 text-xs font-bold text-muted-foreground transition-all duration-200 hover:border-primary/40 hover:bg-background hover:text-foreground active:scale-[0.98]">
                  Preview
                </button>
              </a>
            )}

            {githubUrl && (
              <a
                href={githubUrl}
                target="_blank"
                rel="noopener noreferrer"
                className="flex-1 text-center"
              >
                <button className="w-full rounded-lg border border-primary bg-primary px-3 py-2 text-xs font-bold text-primary-foreground transition-all duration-200 hover:border-primary/90 hover:bg-primary/90 active:scale-[0.98]">
                  GitHub
                </button>
              </a>
            )}

            {(caseStudyUrl || onCaseStudyClick) && (
              <button
                type="button"
                onClick={(e) => {
                  e.stopPropagation();
                  if (onCaseStudyClick) onCaseStudyClick();
                  else if (caseStudyUrl) window.open(caseStudyUrl, "_blank");
                }}
                className="w-full rounded-lg border border-transparent bg-destructive px-3 py-2 text-xs font-bold text-destructive-foreground transition-all duration-200 hover:bg-destructive/90 active:scale-[0.98]"
              >
                Case Study
              </button>
            )}
          </div>
        </div>
      )}
    </motion.div>
  );
}
```

---

# Cursor Grid

> An interactive canvas grid that reacts to cursor proximity and clicks.

Install: `npx @modus-ui/cli add cursor-grid`

A highly optimized `<canvas>` implementation of a grid that lights up based on cursor proximity and triggers ripples on click. Since it uses `requestAnimationFrame` and canvas 2D, it has a negligible impact on DOM performance, easily running at 60fps on huge containers.

## Installation

### CLI

```bash
npx @modus-ui/cli add cursor-grid
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/cursor-grid.tsx`.
3. Paste the code.

## Usage

```tsx
import { CursorGrid } from "@/components/ui/cursor-grid";

export default function Example() {
  return (
    <div className="relative h-screen w-full bg-black">
      <CursorGrid color="hsl(var(--primary))" cellSize={25} radius={150} />
    </div>
  );
}
```

## Props

| Prop           | Type                                      | Default                 | Description                                            |
| :------------- | :---------------------------------------- | :---------------------- | :----------------------------------------------------- |
| `color`        | `string`                                  | `"hsl(var(--primary))"` | Colour of highlighted cells.                           |
| `cellSize`     | `number`                                  | `32`                    | Size of each grid cell in pixels.                      |
| `radius`       | `number`                                  | `120`                   | Radius in pixels of the cursor's influence.            |
| `falloff`      | `"linear" \| "exponential" \| "gaussian"` | `"gaussian"`            | How the highlight fades with distance from the cursor. |
| `holdTime`     | `number`                                  | `0`                     | Milliseconds a cell stays lit before fading.           |
| `fadeDuration` | `number`                                  | `600`                   | Milliseconds a cell takes to fade out.                 |
| `lineWidth`    | `number`                                  | `1`                     | Width of the grid lines in pixels.                     |
| `maxOpacity`   | `number`                                  | `1`                     | Maximum opacity of a highlighted cell.                 |
| `fillOpacity`  | `number`                                  | `0.1`                   | Opacity of the fill of highlighted cells.              |
| `gridOpacity`  | `number`                                  | `0.05`                  | Opacity of the resting grid lines.                     |
| `cellRadius`   | `number`                                  | `4`                     | Corner radius of each cell in pixels.                  |
| `clickPulse`   | `boolean`                                 | `true`                  | Sends a ripple across the grid on click.               |
| `pulseSpeed`   | `number`                                  | `800`                   | Duration in milliseconds of the click ripple.          |

## Source

`components/ui/cursor-grid.tsx`

```tsx
"use client";
// Canvas grid whose cells glow near the cursor and ripple outward on click.

import * as React from "react";
import { useAnimationFrame, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Falloff = "linear" | "exponential" | "gaussian";

export interface CursorGridProps extends React.HTMLAttributes<HTMLDivElement> {
  color?: string;
  cellSize?: number;
  radius?: number;
  falloff?: Falloff;
  holdTime?: number;
  fadeDuration?: number;
  lineWidth?: number;
  maxOpacity?: number;
  fillOpacity?: number;
  gridOpacity?: number;
  cellRadius?: number;
  clickPulse?: boolean;
  pulseSpeed?: number;
}

const strength = (d: number, radius: number, falloff: Falloff) => {
  const t = d / radius;
  if (t >= 1) return 0;
  if (falloff === "linear") return 1 - t;
  if (falloff === "exponential") return Math.exp(-4 * t);
  return Math.exp(-(t * t) * 4);
};

interface Field {
  cols: number;
  rows: number;
  heat: Float32Array;
  litAt: Float64Array;
}

export function CursorGrid({
  color = "hsl(var(--primary))",
  cellSize = 32,
  radius = 120,
  falloff = "gaussian",
  holdTime = 0,
  fadeDuration = 600,
  lineWidth = 1,
  maxOpacity = 1,
  fillOpacity = 0.1,
  gridOpacity = 0.05,
  cellRadius = 4,
  clickPulse = true,
  pulseSpeed = 800,
  className,
  ...props
}: CursorGridProps) {
  const reduceMotion = useReducedMotion();
  const canvasRef = React.useRef<HTMLCanvasElement>(null);
  const pointer = React.useRef<{ x: number; y: number } | null>(null);
  const pulses = React.useRef<{ x: number; y: number; start: number }[]>([]);
  const field = React.useRef<Field>({
    cols: 0,
    rows: 0,
    heat: new Float32Array(),
    litAt: new Float64Array(),
  });
  const rgb = React.useRef("0, 0, 0");

  React.useEffect(() => {
    const canvas = canvasRef.current!;
    const probe = document.createElement("span");
    probe.style.color = color;
    canvas.parentElement!.appendChild(probe);
    rgb.current = getComputedStyle(probe)
      .color.replace(/rgba?\(|\)/g, "")
      .split(",")
      .slice(0, 3)
      .join(",");
    probe.remove();
  }, [color]);

  React.useEffect(() => {
    const canvas = canvasRef.current!;
    const resize = () => {
      const { width, height } = canvas.getBoundingClientRect();
      const dpr = window.devicePixelRatio || 1;
      canvas.width = width * dpr;
      canvas.height = height * dpr;
      canvas.getContext("2d")!.setTransform(dpr, 0, 0, dpr, 0, 0);
      const cols = Math.ceil(width / cellSize);
      const rows = Math.ceil(height / cellSize);
      field.current = {
        cols,
        rows,
        heat: new Float32Array(cols * rows),
        litAt: new Float64Array(cols * rows),
      };
    };
    resize();
    const observer = new ResizeObserver(resize);
    observer.observe(canvas);
    return () => observer.disconnect();
  }, [cellSize]);

  useAnimationFrame((_, delta) => {
    const now = performance.now();
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return;
    const { cols, rows, heat, litAt } = field.current;
    const w = canvas.width / (window.devicePixelRatio || 1);
    const h = canvas.height / (window.devicePixelRatio || 1);
    const ringWidth = cellSize * 1.5;
    const reach = Math.hypot(w, h);
    pulses.current = pulses.current.filter((p) => now - p.start < pulseSpeed);

    ctx.clearRect(0, 0, w, h);
    ctx.lineWidth = lineWidth;
    const inset = lineWidth / 2;
    const size = cellSize - lineWidth;

    for (let row = 0; row < rows; row++) {
      for (let col = 0; col < cols; col++) {
        const i = row * cols + col;
        const cx = col * cellSize + cellSize / 2;
        const cy = row * cellSize + cellSize / 2;
        let target = 0;
        if (pointer.current) {
          target = strength(
            Math.hypot(cx - pointer.current.x, cy - pointer.current.y),
            radius,
            falloff,
          );
        }
        for (const p of pulses.current) {
          const ring = ((now - p.start) / pulseSpeed) * reach;
          const off = Math.abs(Math.hypot(cx - p.x, cy - p.y) - ring);
          if (off < ringWidth)
            target = Math.max(target, (1 - off / ringWidth) * (1 - ring / reach));
        }
        if (target >= heat[i]) {
          heat[i] = target;
          litAt[i] = now;
        } else if (reduceMotion || fadeDuration <= 0) {
          heat[i] = target;
        } else if (now - litAt[i] > holdTime) {
          heat[i] = Math.max(target, heat[i] - delta / fadeDuration);
        }

        const level = heat[i] * maxOpacity;
        ctx.beginPath();
        ctx.roundRect(col * cellSize + inset, row * cellSize + inset, size, size, cellRadius);
        ctx.strokeStyle = `rgba(${rgb.current}, ${Math.max(gridOpacity, level)})`;
        ctx.stroke();
        if (level > 0.01) {
          ctx.fillStyle = `rgba(${rgb.current}, ${level * fillOpacity})`;
          ctx.fill();
        }
      }
    }
  });

  const local = (e: React.PointerEvent) => {
    const rect = e.currentTarget.getBoundingClientRect();
    return { x: e.clientX - rect.left, y: e.clientY - rect.top };
  };

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      onPointerMove={(e) => (pointer.current = local(e))}
      onPointerLeave={() => (pointer.current = null)}
      onPointerDown={(e) => {
        if (clickPulse && !reduceMotion)
          pulses.current.push({ ...local(e), start: performance.now() });
      }}
      {...props}
    >
      <canvas ref={canvasRef} className="block h-full w-full" />
    </div>
  );
}
```

---

# Waves

> A reactive background of flowing lines driven by Perlin noise and cursor physics.

Install: `npx @modus-ui/cli add waves`

A physics-based line wave background that utilizes Perlin noise and cursor proximity to disturb the wave field dynamically.

## Installation

### CLI

```bash
npx @modus-ui/cli add waves
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/waves.tsx`.
3. Paste the code.

## Usage

```tsx
import { Waves } from "@/components/ui/waves";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <Waves
        lineColor="rgba(55, 50, 47, 0.2)"
        waveSpeedX={0.02}
        waveSpeedY={0.01}
        waveAmpX={40}
        waveAmpY={20}
      />
      <div className="relative z-10 flex h-full items-center justify-center">
        <h1>Content over waves</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type                  | Default                | Description                                          |
| :---------------- | :-------------------- | :--------------------- | :--------------------------------------------------- |
| `lineColor`       | `string`              | `"rgba(0, 0, 0, 0.2)"` | Colour of the wave lines.                            |
| `backgroundColor` | `string`              | `"transparent"`        | Background colour behind the lines.                  |
| `waveSpeedX`      | `number`              | `0.0125`               | Horizontal speed of the noise field.                 |
| `waveSpeedY`      | `number`              | `0.005`                | Vertical speed of the noise field.                   |
| `waveAmpX`        | `number`              | `32`                   | Horizontal amplitude of the waves.                   |
| `waveAmpY`        | `number`              | `16`                   | Vertical amplitude of the waves.                     |
| `xGap`            | `number`              | `10`                   | Horizontal gap between lines in pixels.              |
| `yGap`            | `number`              | `32`                   | Vertical gap between points in pixels.               |
| `friction`        | `number`              | `0.925`                | How quickly cursor-induced motion settles.           |
| `tension`         | `number`              | `0.005`                | How strongly points spring back to rest.             |
| `maxCursorMove`   | `number`              | `100`                  | Maximum displacement caused by the cursor in pixels. |
| `style`           | `React.CSSProperties` | `{}`                   | Inline styles for the container.                     |

## Source

`components/ui/waves.tsx`

```tsx
"use client";
// Canvas line field bent by gradient noise and pushed around by the cursor.

import * as React from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface WavesProps {
  lineColor?: string;
  backgroundColor?: string;
  waveSpeedX?: number;
  waveSpeedY?: number;
  waveAmpX?: number;
  waveAmpY?: number;
  xGap?: number;
  yGap?: number;
  friction?: number;
  tension?: number;
  maxCursorMove?: number;
  style?: React.CSSProperties;
  className?: string;
}

// Small seeded 2D gradient noise in roughly [-1, 1].
const PERM = (() => {
  const p = Array.from({ length: 256 }, (_, i) => i);
  let seed = 1337;
  for (let i = 255; i > 0; i--) {
    seed = (seed * 16807) % 2147483647;
    const j = seed % (i + 1);
    [p[i], p[j]] = [p[j], p[i]];
  }
  return [...p, ...p];
})();

function noise(x: number, y: number) {
  const xi = Math.floor(x);
  const yi = Math.floor(y);
  const fx = x - xi;
  const fy = y - yi;
  const corner = (cx: number, cy: number) => {
    const angle = (PERM[(PERM[(xi + cx) & 255] + yi + cy) & 511] / 256) * Math.PI * 2;
    return Math.cos(angle) * (fx - cx) + Math.sin(angle) * (fy - cy);
  };
  const fade = (t: number) => t * t * (3 - 2 * t);
  const u = fade(fx);
  const v = fade(fy);
  const top = corner(0, 0) + (corner(1, 0) - corner(0, 0)) * u;
  const bottom = corner(0, 1) + (corner(1, 1) - corner(0, 1)) * u;
  return (top + (bottom - top) * v) * 1.4;
}

interface Point {
  x: number;
  y: number;
  dx: number;
  dy: number;
  vx: number;
  vy: number;
}

export function Waves({
  lineColor = "rgba(0, 0, 0, 0.2)",
  backgroundColor = "transparent",
  waveSpeedX = 0.0125,
  waveSpeedY = 0.005,
  waveAmpX = 32,
  waveAmpY = 16,
  xGap = 10,
  yGap = 32,
  friction = 0.925,
  tension = 0.005,
  maxCursorMove = 100,
  style = {},
  className,
}: WavesProps) {
  const canvasRef = React.useRef<HTMLCanvasElement>(null);
  const reduceMotion = useReducedMotion();

  React.useEffect(() => {
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return;

    let columns: Point[][] = [];
    let width = 0;
    let height = 0;
    const cursor = { x: -1e4, y: -1e4, vx: 0, vy: 0 };

    const build = () => {
      const rect = canvas.getBoundingClientRect();
      const dpr = window.devicePixelRatio || 1;
      width = rect.width;
      height = rect.height;
      canvas.width = width * dpr;
      canvas.height = height * dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      columns = [];
      for (let x = -xGap; x <= width + xGap; x += xGap) {
        const column: Point[] = [];
        for (let y = -yGap; y <= height + yGap; y += yGap) {
          column.push({ x, y, dx: 0, dy: 0, vx: 0, vy: 0 });
        }
        columns.push(column);
      }
    };

    const draw = (time: number) => {
      ctx.clearRect(0, 0, width, height);
      ctx.strokeStyle = lineColor;
      ctx.lineWidth = 1;
      ctx.beginPath();
      for (const column of columns) {
        column.forEach((p, i) => {
          const n = noise((p.x + time * waveSpeedX) * 0.002, (p.y + time * waveSpeedY) * 0.0015);
          if (!reduceMotion) {
            const dist = Math.hypot(p.x - cursor.x, p.y - cursor.y);
            const reach = Math.max(175, Math.hypot(cursor.vx, cursor.vy) * 10);
            if (dist < reach) {
              const push = 1 - dist / reach;
              p.vx += cursor.vx * push * 0.0065;
              p.vy += cursor.vy * push * 0.0065;
            }
            p.vx = (p.vx - p.dx * tension) * friction;
            p.vy = (p.vy - p.dy * tension) * friction;
            p.dx = Math.max(-maxCursorMove, Math.min(maxCursorMove, p.dx + p.vx));
            p.dy = Math.max(-maxCursorMove, Math.min(maxCursorMove, p.dy + p.vy));
          }
          const x = p.x + Math.cos(n * Math.PI * 2) * waveAmpX + p.dx;
          const y = p.y + Math.sin(n * Math.PI) * waveAmpY + p.dy;
          if (i === 0) ctx.moveTo(x, y);
          else ctx.lineTo(x, y);
        });
      }
      ctx.stroke();
    };

    let frame = 0;
    const tick = (time: number) => {
      cursor.vx *= 0.9;
      cursor.vy *= 0.9;
      draw(time / 16);
      frame = requestAnimationFrame(tick);
    };

    const onMove = (event: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      const x = event.clientX - rect.left;
      const y = event.clientY - rect.top;
      if (cursor.x > -1e3) {
        cursor.vx = x - cursor.x;
        cursor.vy = y - cursor.y;
      }
      cursor.x = x;
      cursor.y = y;
    };

    const observer = new ResizeObserver(() => {
      build();
      if (reduceMotion) draw(0);
    });
    observer.observe(canvas);
    build();
    if (reduceMotion) draw(0);
    else {
      frame = requestAnimationFrame(tick);
      window.addEventListener("pointermove", onMove);
    }
    return () => {
      cancelAnimationFrame(frame);
      observer.disconnect();
      window.removeEventListener("pointermove", onMove);
    };
  }, [
    lineColor,
    waveSpeedX,
    waveSpeedY,
    waveAmpX,
    waveAmpY,
    xGap,
    yGap,
    friction,
    tension,
    maxCursorMove,
    reduceMotion,
  ]);

  return (
    <div
      aria-hidden
      className={cn("pointer-events-none absolute inset-0 overflow-hidden", className)}
      style={{ backgroundColor, ...style }}
    >
      <canvas ref={canvasRef} className="block h-full w-full" />
    </div>
  );
}
```

---

# Letter Glitch

> A canvas-rendered procedural matrix of glitching letters and symbols.

Install: `npx @modus-ui/cli add letter-glitch`

A highly-optimized canvas component that renders a dense grid of randomly fluctuating letters, smoothly transitioning between specified colors. Includes built-in center and edge vignette effects.

## Installation

### CLI

```bash
npx @modus-ui/cli add letter-glitch
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/letter-glitch.tsx`.
3. Paste the code.

## Usage

```tsx
import { LetterGlitch } from "@/components/ui/letter-glitch";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full">
      <LetterGlitch
        glitchSpeed={50}
        centerVignette={true}
        outerVignette={true}
        smooth={true}
        glitchColors={["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"]}
      />
    </div>
  );
}
```

## Props

| Prop              | Type       | Default                                                                 | Description                                           |
| :---------------- | :--------- | :---------------------------------------------------------------------- | :---------------------------------------------------- |
| `glitchColors`    | `string[]` | `["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"]` | Colours the letters cycle through.                    |
| `glitchSpeed`     | `number`   | `50`                                                                    | Milliseconds between glitch updates.                  |
| `centerVignette`  | `boolean`  | `true`                                                                  | Darkens the centre with a radial vignette.            |
| `outerVignette`   | `boolean`  | `true`                                                                  | Darkens the edges with a radial vignette.             |
| `smooth`          | `boolean`  | `true`                                                                  | Fades between colours instead of switching instantly. |
| `lightMode`       | `boolean`  | `false`                                                                 | Uses light-theme vignettes.                           |
| `backgroundColor` | `string`   | -                                                                       | Canvas background colour.                             |
| `characters`      | `string`   | `"ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$&*()-_+=/[]{};:<>.,0123456789"`         | Characters the grid is drawn from.                    |

## Source

`components/ui/letter-glitch.tsx`

```tsx
"use client";
// Canvas grid of characters that keep scrambling and shifting colour.

import * as React from "react";
import { useAnimationFrame, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface LetterGlitchProps extends React.HTMLAttributes<HTMLDivElement> {
  glitchColors?: string[];
  glitchSpeed?: number;
  centerVignette?: boolean;
  outerVignette?: boolean;
  smooth?: boolean;
  lightMode?: boolean;
  backgroundColor?: string;
  characters?: string;
}

const CELL_W = 10;
const CELL_H = 20;
const SHARE = 0.05;

type RGB = [number, number, number];

interface Cell {
  char: string;
  color: RGB;
  target: RGB;
}

const pick = <T,>(list: T[]) => list[Math.floor(Math.random() * list.length)];

export function LetterGlitch({
  glitchColors = ["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"],
  glitchSpeed = 50,
  centerVignette = true,
  outerVignette = true,
  smooth = true,
  lightMode = false,
  backgroundColor,
  characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$&*()-_+=/[]{};:<>.,0123456789",
  className,
  ...props
}: LetterGlitchProps) {
  const reduceMotion = useReducedMotion();
  const canvasRef = React.useRef<HTMLCanvasElement>(null);
  const cells = React.useRef<Cell[]>([]);
  const cols = React.useRef(0);
  const palette = React.useRef<RGB[]>([[255, 255, 255]]);
  const lastGlitch = React.useRef(0);
  const glyphs = React.useMemo(() => Array.from(characters), [characters]);
  const shade = lightMode ? "255,255,255" : "0,0,0";
  const colorKey = glitchColors.join("|");

  const draw = React.useCallback(() => {
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return;
    ctx.clearRect(0, 0, canvas.width, canvas.height);
    ctx.font = `${CELL_H * 0.8}px ui-monospace, monospace`;
    ctx.textBaseline = "top";
    cells.current.forEach((cell, i) => {
      ctx.fillStyle = `rgb(${cell.color.map(Math.round).join(",")})`;
      ctx.fillText(cell.char, (i % cols.current) * CELL_W, Math.floor(i / cols.current) * CELL_H);
    });
  }, []);

  React.useEffect(() => {
    const canvas = canvasRef.current!;
    const probe = document.createElement("span");
    canvas.parentElement!.appendChild(probe);
    palette.current = glitchColors.map((c) => {
      probe.style.color = c;
      return getComputedStyle(probe)
        .color.match(/[\d.]+/g)!
        .slice(0, 3)
        .map(Number) as RGB;
    });
    probe.remove();

    const resize = () => {
      const { width, height } = canvas.getBoundingClientRect();
      const dpr = window.devicePixelRatio || 1;
      canvas.width = width * dpr;
      canvas.height = height * dpr;
      canvas.getContext("2d")!.setTransform(dpr, 0, 0, dpr, 0, 0);
      cols.current = Math.ceil(width / CELL_W);
      cells.current = Array.from({ length: cols.current * Math.ceil(height / CELL_H) }, () => {
        const color = pick(palette.current);
        return { char: pick(glyphs), color: [...color], target: color };
      });
      draw();
    };
    resize();
    const observer = new ResizeObserver(resize);
    observer.observe(canvas);
    return () => observer.disconnect();
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [colorKey, glyphs, draw]);

  useAnimationFrame((time) => {
    if (reduceMotion) return;
    if (time - lastGlitch.current >= glitchSpeed) {
      lastGlitch.current = time;
      const count = Math.max(1, Math.floor(cells.current.length * SHARE));
      for (let n = 0; n < count; n++) {
        const cell = pick(cells.current);
        if (!cell) break;
        cell.char = pick(glyphs);
        cell.target = pick(palette.current);
        if (!smooth) cell.color = [...cell.target];
      }
    }
    if (smooth) {
      for (const cell of cells.current) {
        for (let k = 0; k < 3; k++) cell.color[k] += (cell.target[k] - cell.color[k]) * 0.08;
      }
    }
    draw();
  });

  return (
    <div className={cn("relative h-full w-full overflow-hidden", className)} {...props}>
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ backgroundColor: backgroundColor ?? (lightMode ? "#ffffff" : "#000000") }}
      />
      {outerVignette && (
        <div
          className="pointer-events-none absolute inset-0"
          style={{
            background: `radial-gradient(circle, rgba(${shade},0) 55%, rgba(${shade},1) 100%)`,
          }}
        />
      )}
      {centerVignette && (
        <div
          className="pointer-events-none absolute inset-0"
          style={{
            background: `radial-gradient(circle, rgba(${shade},0.75) 0%, rgba(${shade},0) 60%)`,
          }}
        />
      )}
    </div>
  );
}
```

---

# Aurora Background

> A stunning, smooth animated aurora borealis background effect using Framer Motion.

Install: `npx @modus-ui/cli add aurora-background`

A stunning, smooth animated aurora borealis background effect using Framer Motion. Built natively without heavy WebGL libraries.

## Installation

### CLI

```bash
npx @modus-ui/cli add aurora-background
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/aurora-background.tsx`.
3. Paste the code.

## Usage

```tsx
import { AuroraBackground } from "@/components/ui/aurora-background";

export default function Example() {
  return (
    <AuroraBackground>
      <h1 className="relative z-10 text-5xl font-bold text-white">Hello World</h1>
    </AuroraBackground>
  );
}
```

## Props

| Prop                 | Type                               | Default | Description                                    |
| :------------------- | :--------------------------------- | :------ | :--------------------------------------------- |
| `children`           | `ReactNode`                        | -       | The content to render on top of the aurora.    |
| `colors`             | `[string, string, string, string]` | `[...]` | The four colours of the aurora blobs.          |
| `showRadialGradient` | `boolean`                          | `true`  | Whether to mask the bottom edge of the aurora. |

## Source

`components/ui/aurora-background.tsx`

```tsx
"use client";

import React from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface AuroraBackgroundProps extends React.HTMLAttributes<HTMLDivElement> {
  children?: React.ReactNode;
  showRadialGradient?: boolean;
  /** The four blob colours. */
  colors?: [string, string, string, string];
}

export function AuroraBackground({
  children,
  className,
  showRadialGradient = true,
  colors = ["#38bdf8", "#818cf8", "#34d399", "#e879f9"],
  ...props
}: AuroraBackgroundProps) {
  // Reduced motion: the blobs stay at their resting positions as a still gradient.
  const prefersReducedMotion = useReducedMotion();

  return (
    <div
      className={cn(
        "transition-bg relative flex h-[100vh] w-full flex-col items-center justify-center overflow-hidden bg-background text-foreground",
        className,
      )}
      {...props}
    >
      <div className="pointer-events-none absolute inset-0 overflow-hidden">
        <div
          className={cn(
            "absolute inset-0 will-change-transform",
            showRadialGradient &&
              `[mask-image:radial-gradient(ellipse_at_center,black_10%,transparent_70%)]`,
          )}
        >
          <div className="absolute inset-0 opacity-50 mix-blend-normal dark:opacity-80 dark:mix-blend-lighten">
            {/* Animated Blob 1 */}
            <motion.div
              animate={
                prefersReducedMotion
                  ? undefined
                  : {
                      x: ["0%", "20%", "-20%", "0%"],
                      y: ["0%", "-20%", "20%", "0%"],
                      scale: [1, 1.2, 0.8, 1],
                    }
              }
              transition={{
                duration: 20,
                repeat: Infinity,
                ease: "linear",
              }}
              style={{ backgroundColor: colors[0] }}
              className="absolute -left-[10%] -top-[10%] h-[60%] w-[60%] rounded-full opacity-70 mix-blend-multiply blur-[80px] dark:mix-blend-screen md:blur-[120px]"
            />

            {/* Animated Blob 2 */}
            <motion.div
              animate={
                prefersReducedMotion
                  ? undefined
                  : {
                      x: ["0%", "-20%", "20%", "0%"],
                      y: ["0%", "20%", "-20%", "0%"],
                      scale: [1, 0.8, 1.2, 1],
                    }
              }
              transition={{
                duration: 25,
                repeat: Infinity,
                ease: "linear",
              }}
              style={{ backgroundColor: colors[1] }}
              className="absolute -right-[10%] top-[10%] h-[50%] w-[50%] rounded-full opacity-70 mix-blend-multiply blur-[80px] dark:mix-blend-screen md:blur-[120px]"
            />

            {/* Animated Blob 3 */}
            <motion.div
              animate={
                prefersReducedMotion
                  ? undefined
                  : {
                      x: ["0%", "30%", "-30%", "0%"],
                      y: ["0%", "30%", "-30%", "0%"],
                      scale: [1, 1.3, 0.7, 1],
                    }
              }
              transition={{
                duration: 30,
                repeat: Infinity,
                ease: "linear",
              }}
              style={{ backgroundColor: colors[2] }}
              className="absolute -bottom-[20%] left-[20%] h-[70%] w-[70%] rounded-full opacity-70 mix-blend-multiply blur-[80px] dark:mix-blend-screen md:blur-[120px]"
            />

            {/* Animated Blob 4 (Extra for richness) */}
            <motion.div
              animate={
                prefersReducedMotion
                  ? undefined
                  : {
                      x: ["0%", "-30%", "30%", "0%"],
                      y: ["0%", "-30%", "30%", "0%"],
                      scale: [1, 0.9, 1.1, 1],
                    }
              }
              transition={{
                duration: 35,
                repeat: Infinity,
                ease: "linear",
              }}
              style={{ backgroundColor: colors[3] }}
              className="absolute bottom-[10%] right-[20%] h-[50%] w-[50%] rounded-full opacity-60 mix-blend-multiply blur-[80px] dark:mix-blend-screen md:blur-[120px]"
            />
          </div>
        </div>
      </div>
      <div className="relative z-10">{children}</div>
    </div>
  );
}
```

---

# Circuit Background

> A highly ambient, canvas-based circuit board animation with interactive mouse ripple effects.

Install: `npx @modus-ui/cli add circuit-background`

A premium HTML5 Canvas-based background animation. Technical circuit lines grow, branch off, and fade, while pointer hover and clicks trigger smooth, natural water ripples that respond to current theme modes.

## Installation

### CLI

```bash
npx @modus-ui/cli add circuit-background
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/circuit-background.tsx`.
3. Paste the code.

## Usage

```tsx
import { CircuitBackground } from "@/components/ui/circuit-background";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div className="relative min-h-screen">
      <CircuitBackground />
      <main className="relative z-10">{children}</main>
    </div>
  );
}
```

## Props

| Prop           | Type     | Default | Description                                                                          |
| :------------- | :------- | :------ | :----------------------------------------------------------------------------------- |
| `maxTrails`    | `number` | `60`    | The maximum amount of concurrently active growing circuits.                          |
| `lineColor`    | `string` | -       | Custom stroke color for circuit lines. (Defaults to theme-adapted colors).           |
| `circleColor`  | `string` | -       | Custom border color for connection node circles. (Defaults to theme-adapted colors). |
| `glowStrength` | `number` | `6`     | Glow shadow size in pixels.                                                          |
| `circleSize`   | `number` | `5`     | Radius of the circuit connection nodes.                                              |
| `spawnChance`  | `number` | `0.03`  | Probability of spawning a new circuit line per frame.                                |
| `className`    | `string` | -       | Additional CSS class for the canvas containers.                                      |

## Source

`components/ui/circuit-background.tsx`

```tsx
"use client";

import React, { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

// Self-contained ripple class for interactive mouse effects
class CircuitRipple {
  x: number;
  y: number;
  radius: number;
  maxRadius: number;
  speed: number;
  alpha: number;
  fadeSpeed: number;
  thickness: number;
  waveOffset: number;
  waveSpeed: number;
  waveAmplitude: number;
  waveFrequency: number;
  isActive: boolean;

  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
    this.radius = 0;
    this.maxRadius = 80 + Math.random() * 40;
    this.speed = 1.2 + Math.random() * 0.3;
    this.alpha = 0.45;
    this.fadeSpeed = 0.008;
    this.thickness = 1.5;
    this.waveOffset = Math.random() * Math.PI * 2;
    this.waveSpeed = 0.05 + Math.random() * 0.02;
    this.waveAmplitude = 3 + Math.random() * 2;
    this.waveFrequency = 0.02 + Math.random() * 0.01;
    this.isActive = true;
  }

  update(ctx: CanvasRenderingContext2D, isDarkMode: boolean) {
    if (!this.isActive) return;

    this.radius += this.speed;
    this.alpha -= this.fadeSpeed;

    if (this.alpha <= 0 || this.radius > this.maxRadius) {
      this.isActive = false;
      return;
    }

    // Ripple color adapts to theme
    const rippleColor = isDarkMode ? "250, 249, 247" : "55, 50, 47";

    for (let i = 0; i < 4; i++) {
      const circleRadius = this.radius - i * 6;
      if (circleRadius > 0) {
        const circleAlpha = this.alpha * (1 - i * 0.2) * 0.7;
        ctx.strokeStyle = `rgba(${rippleColor}, ${circleAlpha})`;
        ctx.lineWidth = this.thickness - i * 0.15;

        ctx.beginPath();
        ctx.moveTo(this.x + circleRadius, this.y);
        for (let angle = 0; angle <= Math.PI * 2; angle += 0.1) {
          const waveDistortion =
            Math.sin(angle * this.waveFrequency + this.waveOffset) * this.waveAmplitude;
          const distortedRadius = circleRadius + waveDistortion;
          const pointX = this.x + Math.cos(angle) * distortedRadius;
          const pointY = this.y + Math.sin(angle) * distortedRadius;
          ctx.lineTo(pointX, pointY);
        }
        ctx.stroke();
      }
    }

    this.waveOffset += this.waveSpeed;
  }
}

interface CircuitTrail {
  points: { x: number; y: number }[];
  hue: number;
  startTime: number;
  growTime: number;
  holdTime: number;
  fadeTime: number;
  backSpawned: number;
  endSpawned: number;
  dead?: boolean;
}

export interface CircuitBackgroundProps {
  maxTrails?: number;
  lineColor?: string;
  circleColor?: string;
  glowStrength?: number;
  circleSize?: number;
  spawnChance?: number;
  className?: string;
}

export function CircuitBackground({
  maxTrails = 60,
  lineColor,
  circleColor,
  glowStrength = 6,
  circleSize = 5,
  spawnChance = 0.03,
  className,
}: CircuitBackgroundProps) {
  const canvasRef = useRef<HTMLCanvasElement | null>(null);
  const rippleCanvasRef = useRef<HTMLCanvasElement | null>(null);
  const trailsRef = useRef<CircuitTrail[]>([]);
  const ripplesRef = useRef<CircuitRipple[]>([]);
  const animationRef = useRef<number | null>(null);
  // Reduced motion: draw one still frame of fully grown traces; no loop, drift or ripples.
  const prefersReducedMotion = useReducedMotion();

  useEffect(() => {
    const isMobile = window.innerWidth < 768;
    if (isMobile) return;

    const canvas = canvasRef.current;
    const rippleCanvas = rippleCanvasRef.current;
    if (!canvas || !rippleCanvas) return;

    const ctx = canvas.getContext("2d", { alpha: true })!;
    const rippleCtx = rippleCanvas.getContext("2d", { alpha: true })!;
    const bufferCanvas = document.createElement("canvas");
    const bufferCtx = bufferCanvas.getContext("2d", { alpha: true })!;

    let W: number, H: number;
    let running = true;

    // Check document class list for dark theme
    const isDarkMode = document.documentElement.classList.contains("dark");

    // Colors mapping to Modus UI warm design palette
    const resolvedLineColor =
      lineColor || (isDarkMode ? "rgba(250, 249, 247, 0.15)" : "rgba(55, 50, 47, 0.1)");
    const resolvedCircleColor =
      circleColor || (isDarkMode ? "rgba(250, 249, 247, 0.3)" : "rgba(55, 50, 47, 0.2)");

    const allowedAngles = [0, 45, 90, 135, 180, 225, 270, 315];
    const turnChoices = [45, 90];

    const random = (a: number = 1, b: number = 0) => Math.random() * (a - b) + b;
    const choose = <T,>(arr: T[]): T => arr[Math.floor(Math.random() * arr.length)];
    const normalizeDegrees = (deg: number) => ((deg % 360) + 360) % 360;

    function pickTurnFrom(baseDeg: number): number {
      const candidates = new Set<number>();
      for (const turn of turnChoices) {
        const angle1 = normalizeDegrees(baseDeg + turn);
        const angle2 = normalizeDegrees(baseDeg - turn);
        if (allowedAngles.includes(angle1)) candidates.add(angle1);
        if (allowedAngles.includes(angle2)) candidates.add(angle2);
      }
      const arr = Array.from(candidates);
      return arr.length ? choose(arr) : baseDeg;
    }

    function createTrail(startPoint?: { x: number; y: number }, angleDeg?: number): CircuitTrail {
      const start = startPoint || {
        x: Math.random() * bufferCanvas.width,
        y: Math.random() * bufferCanvas.height,
      };
      const baseAngle =
        typeof angleDeg === "number" ? normalizeDegrees(angleDeg) : choose(allowedAngles);
      const baseRad = (baseAngle * Math.PI) / 180;

      const length1 = random(60, 100);
      const point1 = {
        x: start.x + Math.cos(baseRad) * length1,
        y: start.y + Math.sin(baseRad) * length1,
      };

      const turnAngle = pickTurnFrom(baseAngle);
      const turnRad = (turnAngle * Math.PI) / 180;
      const length2 = random(60, 120);
      const point2 = {
        x: point1.x + Math.cos(turnRad) * length2,
        y: point1.y + Math.sin(turnRad) * length2,
      };

      const length3 = random(80, 150);
      const point3 = {
        x: point2.x + Math.cos(turnRad) * length3,
        y: point2.y + Math.sin(turnRad) * length3,
      };

      return {
        points: [start, point1, point2, point3],
        hue: choose([20, 30, 40, 50]), // Warm hues
        startTime: performance.now(),
        growTime: random(2000, 1200),
        holdTime: random(1800, 800),
        fadeTime: 1000,
        backSpawned: 0,
        endSpawned: 0,
      };
    }

    function getTrailLength(points: { x: number; y: number }[]) {
      let length = 0;
      for (let i = 0; i < points.length - 1; i++) {
        length += Math.hypot(points[i + 1].x - points[i].x, points[i + 1].y - points[i].y);
      }
      return length;
    }

    function drawCircle(x: number, y: number, radius: number, alpha: number) {
      const dpr = window.devicePixelRatio || 1;
      bufferCtx.globalCompositeOperation = "destination-out";
      bufferCtx.beginPath();
      bufferCtx.arc(x, y, radius - 1.2 * dpr, 0, Math.PI * 2);
      bufferCtx.fill();

      bufferCtx.globalCompositeOperation = "source-over";
      bufferCtx.strokeStyle = resolvedCircleColor;
      bufferCtx.lineWidth = 1.5 * dpr;
      bufferCtx.beginPath();
      bufferCtx.arc(x, y, radius, 0, Math.PI * 2);
      bufferCtx.stroke();
    }

    function drawTrail(trail: CircuitTrail, currentTime: number) {
      const elapsed = currentTime - trail.startTime;
      const totalLength = getTrailLength(trail.points);
      let alpha = 1;
      let progress = 0;

      if (elapsed < trail.growTime) {
        progress = elapsed / trail.growTime;
        alpha = progress;
      } else if (elapsed < trail.growTime + trail.holdTime) {
        progress = 1;
      } else if (elapsed < trail.growTime + trail.holdTime + trail.fadeTime) {
        progress = 1;
        alpha = 1 - (elapsed - trail.growTime - trail.holdTime) / trail.fadeTime;
      } else {
        trail.dead = true;
        return;
      }

      alpha *= 0.25; // Keep it subtle and ambient
      const drawLength = totalLength * progress;

      bufferCtx.strokeStyle = resolvedLineColor;
      bufferCtx.lineWidth = 1.2 * (window.devicePixelRatio || 1);
      bufferCtx.lineCap = "round";

      bufferCtx.shadowBlur = glowStrength * (window.devicePixelRatio || 1);
      bufferCtx.shadowColor = resolvedLineColor;

      bufferCtx.beginPath();
      bufferCtx.moveTo(trail.points[0].x, trail.points[0].y);
      let remaining = drawLength;

      for (let i = 0; i < trail.points.length - 1; i++) {
        const pointA = trail.points[i];
        const pointB = trail.points[i + 1];
        const segmentLength = Math.hypot(pointB.x - pointA.x, pointB.y - pointA.y);

        if (remaining >= segmentLength) {
          bufferCtx.lineTo(pointB.x, pointB.y);
          remaining -= segmentLength;
        } else {
          const t = remaining / segmentLength;
          bufferCtx.lineTo(
            pointA.x + (pointB.x - pointA.x) * t,
            pointA.y + (pointB.y - pointA.y) * t,
          );
          break;
        }
      }
      bufferCtx.stroke();

      drawCircle(
        trail.points[0].x,
        trail.points[0].y,
        circleSize * (window.devicePixelRatio || 1),
        alpha,
      );

      if (progress >= 1) {
        drawCircle(
          trail.points[3].x,
          trail.points[3].y,
          circleSize * (window.devicePixelRatio || 1),
          alpha,
        );

        // Branching logic at ends
        if (!trail.endSpawned && trailsRef.current.length < maxTrails && Math.random() < 0.1) {
          trail.endSpawned = 1;
          const dx = trail.points[3].x - trail.points[2].x;
          const dy = trail.points[3].y - trail.points[2].y;
          const parentAngle = normalizeDegrees((Math.atan2(dy, dx) * 180) / Math.PI);
          const turnAngle = pickTurnFrom(parentAngle);

          if (turnAngle !== parentAngle) {
            trailsRef.current.push(createTrail(trail.points[3], turnAngle));
          }
        }
      }
    }

    function resize() {
      W = window.innerWidth;
      H = window.innerHeight;
      canvas!.width = W;
      canvas!.height = H;
      rippleCanvas!.width = W;
      rippleCanvas!.height = H;
      bufferCanvas.width = W * 1.5;
      bufferCanvas.height = H * 1.5;
    }

    function drawStatic() {
      bufferCtx.setTransform(1, 0, 0, 1, 0, 0);
      bufferCtx.clearRect(0, 0, bufferCanvas.width, bufferCanvas.height);
      trailsRef.current = Array.from({ length: Math.min(12, maxTrails) }, () => createTrail());
      for (const trail of trailsRef.current) {
        drawTrail(trail, trail.startTime + trail.growTime);
      }
      ctx.setTransform(1, 0, 0, 1, 0, 0);
      ctx.clearRect(0, 0, W, H);
      ctx.drawImage(bufferCanvas, -W * 0.25, -H * 0.25, W * 1.5, H * 1.5);
    }

    if (prefersReducedMotion) {
      const handleStaticResize = () => {
        resize();
        drawStatic();
      };
      handleStaticResize();
      window.addEventListener("resize", handleStaticResize);
      return () => {
        window.removeEventListener("resize", handleStaticResize);
        trailsRef.current = [];
      };
    }

    function animate(currentTime: number) {
      if (!running) return;

      bufferCtx.setTransform(1, 0, 0, 1, 0, 0);
      bufferCtx.clearRect(0, 0, bufferCanvas.width, bufferCanvas.height);

      if (Math.random() < spawnChance && trailsRef.current.length < maxTrails) {
        trailsRef.current.push(createTrail());
      }

      trailsRef.current = trailsRef.current.filter((trail) => {
        drawTrail(trail, currentTime);
        return !trail.dead;
      });

      // Render camera drift/perspective zoom
      ctx.setTransform(1, 0, 0, 1, 0, 0);
      ctx.clearRect(0, 0, W, H);

      const driftX = Math.sin(currentTime * 0.0001) * 80;
      const driftY = Math.cos(currentTime * 0.00008) * 50;

      ctx.drawImage(bufferCanvas, -W * 0.25 + driftX, -H * 0.25 + driftY, W * 1.5, H * 1.5);

      // Ripple drawing
      rippleCtx.clearRect(0, 0, rippleCanvas!.width, rippleCanvas!.height);
      ripplesRef.current = ripplesRef.current.filter((ripple) => {
        ripple.update(rippleCtx, isDarkMode);
        return ripple.isActive;
      });

      animationRef.current = requestAnimationFrame(animate);
    }

    const handleMouseMove = (e: MouseEvent) => {
      if (Math.random() < 0.3) {
        ripplesRef.current.push(new CircuitRipple(e.clientX, e.clientY));
      }
    };

    const handleClick = (e: MouseEvent) => {
      const x = e.clientX;
      const y = e.clientY;
      for (let i = 0; i < 4; i++) {
        const ripple = new CircuitRipple(
          x + (Math.random() - 0.5) * 20,
          y + (Math.random() - 0.5) * 20,
        );
        ripple.maxRadius = 110 + Math.random() * 40;
        ripple.speed = 1.8 + Math.random() * 0.8;
        ripplesRef.current.push(ripple);
      }
    };

    resize();
    window.addEventListener("resize", resize);
    window.addEventListener("mousemove", handleMouseMove);
    window.addEventListener("click", handleClick);

    for (let i = 0; i < 3; i++) {
      trailsRef.current.push(createTrail());
    }

    animationRef.current = requestAnimationFrame(animate);

    return () => {
      running = false;
      if (animationRef.current) cancelAnimationFrame(animationRef.current);
      window.removeEventListener("resize", resize);
      window.removeEventListener("mousemove", handleMouseMove);
      window.removeEventListener("click", handleClick);
      trailsRef.current = [];
      ripplesRef.current = [];
    };
  }, [
    maxTrails,
    lineColor,
    circleColor,
    glowStrength,
    circleSize,
    spawnChance,
    prefersReducedMotion,
  ]);

  return (
    <>
      <canvas
        ref={canvasRef}
        className={cn(className)}
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          width: "100vw",
          height: "100vh",
          zIndex: 0,
          pointerEvents: "none",
        }}
      />
      <canvas
        ref={rippleCanvasRef}
        style={{
          position: "fixed",
          top: 0,
          left: 0,
          width: "100vw",
          height: "100vh",
          zIndex: 10,
          pointerEvents: "none",
        }}
      />
    </>
  );
}
```

---

# Orbiting Elements

> Elements that mathematically orbit around a central node in circular paths.

Install: `npx @modus-ui/cli add orbiting-elements`

A beautiful physics-driven layout component. It places child elements evenly around a circle and rotates them around a center point. Crucially, each item counter-rotates at the exact same speed, ensuring icons and text never end up upside down as they travel the orbit.

## Installation

### CLI

```bash
npx @modus-ui/cli add orbiting-elements
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/orbiting-elements.tsx`.
3. Paste the code.

## Usage

```tsx
import { OrbitingElements } from "@/components/ui/orbiting-elements";

export default function Example() {
  return (
    <div className="relative flex h-[400px] items-center justify-center">
      <div className="h-16 w-16 rounded-full border bg-card" />

      <div className="absolute inset-0 flex items-center justify-center">
        <OrbitingElements radius={100} duration={10}>
          <div className="h-8 w-8 rounded-full bg-primary" />
          <div className="h-8 w-8 rounded-full bg-secondary" />
        </OrbitingElements>
      </div>
    </div>
  );
}
```

## Props

| Prop         | Type      | Default | Description                 |
| :----------- | :-------- | :------ | :-------------------------- |
| `radius`     | `number`  | `100`   | Orbit radius in pixels.     |
| `duration`   | `number`  | `20`    | Seconds for one full orbit. |
| `reverse`    | `boolean` | `false` | Orbits counter-clockwise.   |
| `showPath`   | `boolean` | `true`  | Draws the orbit path.       |
| `startAngle` | `number`  | `0`     | Starting angle in degrees.  |

## Source

`components/ui/orbiting-elements.tsx`

```tsx
"use client";

import { Children, type ReactNode } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface OrbitingElementsProps {
  children: ReactNode;
  radius?: number;
  duration?: number;
  reverse?: boolean;
  showPath?: boolean;
  startAngle?: number;
  className?: string;
}

export function OrbitingElements({
  children,
  radius = 100,
  duration = 20,
  reverse = false,
  showPath = true,
  startAngle = 0,
  className = "",
}: OrbitingElementsProps) {
  const items = Children.toArray(children);
  const prefersReducedMotion = useReducedMotion();
  const spin = reverse ? -360 : 360;

  const transition = {
    duration,
    repeat: Infinity,
    ease: "linear" as const,
  };

  return (
    <div className={cn("relative", className)} style={{ width: radius * 2, height: radius * 2 }}>
      {showPath ? (
        <div
          aria-hidden="true"
          className="absolute inset-0 rounded-full border border-dashed border-border"
        />
      ) : null}

      {items.map((item, index) => {
        const angle = startAngle + (360 / items.length) * index;

        return (
          <motion.div
            key={index}
            className="absolute left-1/2 top-1/2 size-0"
            initial={{ rotate: angle }}
            animate={prefersReducedMotion ? undefined : { rotate: angle + spin }}
            transition={transition}
          >
            <div className="w-max" style={{ transform: `translateX(${radius}px)` }}>
              <motion.div
                initial={{ rotate: -angle }}
                animate={prefersReducedMotion ? undefined : { rotate: -angle - spin }}
                transition={transition}
                className="flex w-max -translate-x-1/2 -translate-y-1/2 items-center justify-center"
              >
                {item}
              </motion.div>
            </div>
          </motion.div>
        );
      })}
    </div>
  );
}
```

---

# Gloop Trail

> A pooled ink trail that follows the pointer, shading from the theme ink toward muted grey.

Install: `npx @modus-ui/cli add gloop-trail`

An ink trail that follows the pointer. Each step of the trail shades from your theme ink toward the muted token. It uses a custom SVG `feGaussianBlur` and `feColorMatrix` filter to blend multiple trailing DOM elements into a single fluid "pool" that follows your cursor physics.

## Installation

### CLI

```bash
npx @modus-ui/cli add gloop-trail
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/gloop-trail.tsx`.
3. Paste the code.

## Usage

```tsx
import { GloopTrail } from "@/components/ui/gloop-trail";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full cursor-none overflow-hidden">
      <GloopTrail fillColor="hsl(var(--primary))" />
    </div>
  );
}
```

## Props

| Prop        | Type                               | Default                 | Description                          |
| :---------- | :--------------------------------- | :---------------------- | :----------------------------------- |
| `blobType`  | `"circle" \| "square" \| "almond"` | `"circle"`              | Shape of the trailing drops.         |
| `fillColor` | `string`                           | `"hsl(var(--primary))"` | Ink colour at the head of the trail. |

## Source

`components/ui/gloop-trail.tsx`

```tsx
"use client";
// Drops that chase the pointer at different speeds and melt into one pool through a goo filter.
import { useState, useEffect, useId, useRef } from "react";
import {
  motion,
  useMotionValue,
  useReducedMotion,
  useSpring,
  type MotionValue,
} from "framer-motion";

type BlobType = "circle" | "square" | "almond";

interface GloopTrailProps {
  blobType?: BlobType;
  fillColor?: string;
}

const DROPS = 4;
const RADII: Record<BlobType, string> = { circle: "50%", square: "22%", almond: "50% 0" };

function Drop({
  x,
  y,
  index,
  blobType,
  fillColor,
  still,
}: {
  x: MotionValue<number>;
  y: MotionValue<number>;
  index: number;
  blobType: BlobType;
  fillColor: string;
  still: boolean;
}) {
  const spring = { stiffness: 520 - index * 110, damping: 28 + index * 4, mass: 0.6 };
  const sx = useSpring(x, spring);
  const sy = useSpring(y, spring);
  const size = 64 - index * 10;
  return (
    <motion.div
      className="absolute left-0 top-0"
      style={{
        x: still ? x : sx,
        y: still ? y : sy,
        width: size,
        height: size,
        marginLeft: -size / 2,
        marginTop: -size / 2,
        rotate: blobType === "almond" ? 45 : 0,
        borderRadius: RADII[blobType],
        background: `color-mix(in hsl, ${fillColor}, hsl(var(--muted-foreground)) ${index * 22}%)`,
      }}
    />
  );
}

export function GloopTrail({
  blobType = "circle",
  fillColor = "hsl(var(--primary))",
}: GloopTrailProps) {
  const prefersReduced = useReducedMotion();
  // Follow the setting only after hydration, so the first render matches the server's.
  const [reduce, setReduce] = useState(false);
  useEffect(() => setReduce(Boolean(prefersReduced)), [prefersReduced]);
  const filterId = `gloop-${useId().replace(/:/g, "")}`;
  const layer = useRef<HTMLDivElement>(null);
  const x = useMotionValue(-200);
  const y = useMotionValue(-200);

  useEffect(() => {
    const onMove = (e: PointerEvent) => {
      const box = layer.current?.getBoundingClientRect();
      if (!box) return;
      x.set(e.clientX - box.left);
      y.set(e.clientY - box.top);
    };
    window.addEventListener("pointermove", onMove);
    return () => window.removeEventListener("pointermove", onMove);
  }, [x, y]);

  return (
    <div ref={layer} aria-hidden className="pointer-events-none absolute inset-0 overflow-hidden">
      <svg className="absolute h-0 w-0">
        <filter id={filterId}>
          <feGaussianBlur stdDeviation="10" />
          <feColorMatrix values="1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 24 -10" />
        </filter>
      </svg>
      <div className="absolute inset-0" style={{ filter: `url(#${filterId})` }}>
        {Array.from({ length: reduce ? 1 : DROPS }, (_, i) => (
          <Drop
            key={i}
            x={x}
            y={y}
            index={i}
            blobType={blobType}
            fillColor={fillColor}
            still={!!reduce}
          />
        ))}
      </div>
    </div>
  );
}
```

---

# Iron Filings

> A field of fine ink filings that turn to face the pointer, like iron around a lodestone.

Install: `npx @modus-ui/cli add iron-filings`

A field of fine filings in alternating ink and accent. It renders a CSS grid of simple `<span>` elements and uses a single window event listener to calculate the geometric angle (using `Math.acos()`) from each line to your mouse, applying the rotation via CSS custom properties.

## Installation

### CLI

```bash
npx @modus-ui/cli add iron-filings
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/iron-filings.tsx`.
3. Paste the code.

## Usage

```tsx
import { IronFilings } from "@/components/ui/iron-filings";

export default function Example() {
  return (
    <div className="flex h-screen w-full items-center justify-center bg-background">
      <IronFilings
        rows={9}
        columns={9}
        lineColor="hsl(var(--primary))"
        lineWidth="2px"
        lineHeight="40px"
      />
    </div>
  );
}
```

## Props

| Prop            | Type     | Default                    | Description                               |
| :-------------- | :------- | :------------------------- | :---------------------------------------- |
| `rows`          | `number` | `13`                       | Number of rows of lines.                  |
| `columns`       | `number` | `13`                       | Number of columns of lines.               |
| `containerSize` | `string` | `"70vmin"`                 | CSS size of the square container.         |
| `lineColor`     | `string` | `"hsl(var(--foreground))"` | Colour of the lines.                      |
| `lineWidth`     | `string` | `"0.4vmin"`                | CSS width of each line.                   |
| `lineHeight`    | `string` | `"3.6vmin"`                | CSS length of each line.                  |
| `baseAngle`     | `number` | `45`                       | Resting rotation of the lines in degrees. |

## Source

`components/ui/iron-filings.tsx`

```tsx
"use client";
// A grid of short strokes that swing to point at the cursor.
import { useEffect, useRef } from "react";
import { cn } from "@/lib/utils";

interface IronFilingsProps {
  rows?: number;
  columns?: number;
  containerSize?: string;
  lineColor?: string;
  lineWidth?: string;
  lineHeight?: string;
  baseAngle?: number;
  className?: string;
}

export function IronFilings({
  rows = 13,
  columns = 13,
  containerSize = "70vmin",
  lineColor = "hsl(var(--foreground))",
  lineWidth = "0.4vmin",
  lineHeight = "3.6vmin",
  baseAngle = 45,
  className,
}: IronFilingsProps) {
  const root = useRef<HTMLDivElement>(null);

  useEffect(() => {
    let frame = 0;
    let pointer: { x: number; y: number } | null = null;
    const aim = () => {
      frame = 0;
      if (!pointer || !root.current) return;
      for (const el of root.current.children as HTMLCollectionOf<HTMLElement>) {
        const r = el.getBoundingClientRect();
        const deg =
          (Math.atan2(pointer.y - (r.top + r.height / 2), pointer.x - (r.left + r.width / 2)) *
            180) /
            Math.PI +
          90;
        el.style.setProperty("--aim", `${deg}deg`);
      }
    };
    const onMove = (e: PointerEvent) => {
      pointer = { x: e.clientX, y: e.clientY };
      if (!frame) frame = requestAnimationFrame(aim);
    };
    window.addEventListener("pointermove", onMove);
    return () => {
      window.removeEventListener("pointermove", onMove);
      cancelAnimationFrame(frame);
    };
  }, []);

  return (
    <div
      ref={root}
      aria-hidden
      className={cn("grid place-items-center", className)}
      style={{
        width: containerSize,
        height: containerSize,
        gridTemplateColumns: `repeat(${columns}, 1fr)`,
        gridTemplateRows: `repeat(${rows}, 1fr)`,
      }}
    >
      {Array.from({ length: rows * columns }, (_, i) => (
        <span
          key={i}
          className="block rounded-full transition-transform duration-300 ease-out motion-reduce:transition-none"
          style={{
            width: lineWidth,
            height: lineHeight,
            background: i % 2 ? "hsl(var(--primary) / 0.55)" : lineColor,
            transform: `rotate(var(--aim, ${baseAngle}deg))`,
          }}
        />
      ))}
    </div>
  );
}
```

---

# Grid Motion

> An interactive, infinite grid that tracks mouse movement with beautiful inertia physics.

Install: `npx @modus-ui/cli add grid-motion`

An interactive, infinite grid that tracks mouse movement with beautiful inertia physics. Perfect for hero sections or showcasing features and partner logos.

## Installation

### CLI

```bash
npx @modus-ui/cli add grid-motion
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/grid-motion.tsx`.
3. Paste the code.

## Usage

```tsx
import { GridMotion } from "@/components/ui/grid-motion";

export default function Example() {
  const items = [
    "Design",
    "Development",
    "Engineering",
    "Architecture",
    "Performance",
    "Accessibility",
    "Framer Motion",
    "Tailwind",
  ];

  return (
    <div className="h-[600px] w-full">
      <GridMotion items={items} />
    </div>
  );
}
```

## Props

| Prop            | Type          | Default                    | Description                                                                                      |
| :-------------- | :------------ | :------------------------- | :----------------------------------------------------------------------------------------------- |
| `items`         | `ReactNode[]` | `[]`                       | Array of items to populate the grid. Should ideally have at least 28 items to fill the viewport. |
| `gradientColor` | `string`      | `"hsl(var(--background))"` | Center color of the radial gradient mask overlay.                                                |

## Source

`components/ui/grid-motion.tsx`

```tsx
"use client";
// A tilted wall of tiles whose rows drift with the pointer, each row on its own lagging spring.

import { useEffect } from "react";
import type React from "react";
import {
  motion,
  useMotionValue,
  useReducedMotion,
  useSpring,
  useTransform,
  type MotionValue,
} from "framer-motion";
import { cn } from "@/lib/utils";

const ROWS = 4;
const COLS = 7;
const TRAVEL = 220;

export interface GridMotionProps {
  items?: React.ReactNode[];
  gradientColor?: string;
  className?: string;
}

function Row({
  pointer,
  index,
  cells,
}: {
  pointer: MotionValue<number>;
  index: number;
  cells: React.ReactNode[];
}) {
  const direction = index % 2 === 0 ? 1 : -1;
  const target = useTransform(pointer, (p) => p * TRAVEL * direction);
  const x = useSpring(target, { stiffness: 40 - index * 7, damping: 18, mass: 1 + index * 0.3 });

  return (
    <motion.div className="grid grid-cols-7 gap-4" style={{ x }}>
      {cells.map((cell, i) => (
        <div
          key={i}
          className="flex aspect-[4/3] items-center justify-center rounded-2xl bg-card p-4 text-center font-sans text-lg text-card-foreground shadow-sm"
        >
          {cell}
        </div>
      ))}
    </motion.div>
  );
}

export function GridMotion({
  items = [],
  gradientColor = "hsl(var(--background))",
  className,
}: GridMotionProps) {
  const reduceMotion = useReducedMotion();
  const pointer = useMotionValue(0);

  useEffect(() => {
    if (reduceMotion) return;
    const onMove = (e: PointerEvent) => pointer.set((e.clientX / window.innerWidth) * 2 - 1);
    window.addEventListener("pointermove", onMove);
    return () => window.removeEventListener("pointermove", onMove);
  }, [pointer, reduceMotion]);

  const cells = Array.from({ length: ROWS * COLS }, (_, i) =>
    items.length ? items[i % items.length] : null,
  );

  return (
    <section
      className={cn("relative h-full w-full overflow-hidden", className)}
      style={{ background: `radial-gradient(circle, ${gradientColor} 0%, hsl(var(--muted)) 100%)` }}
    >
      <div className="absolute left-1/2 top-1/2 flex w-[150%] -translate-x-1/2 -translate-y-1/2 -rotate-[15deg] flex-col gap-4">
        {Array.from({ length: ROWS }, (_, r) => (
          <Row key={r} index={r} pointer={pointer} cells={cells.slice(r * COLS, r * COLS + COLS)} />
        ))}
      </div>
    </section>
  );
}
```

---

# Moon Lattice

> A centred WebGL globe of noise-carved points, tilted and threaded with thin rings, inked in the theme colours.

Install: `npx @modus-ui/cli add moon-lattice`

A Three.js point globe carved by noise and tilted on its axis, wrapped in six thin rings that drift in opposite directions. Colours come from the theme: `--primary` for the bright points and nodes, `--muted-foreground` for the dim ones and `--foreground` for the rings. In light mode it is drawn as ink on paper; in dark mode it glows additively. It follows palette and mode changes live. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add moon-lattice
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/moon-lattice.tsx`.
4. Paste the code.

## Usage

```tsx
import { MoonLattice } from "@/components/ui/moon-lattice";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <MoonLattice />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop               | Type     | Default                    | Description                           |
| :----------------- | :------- | :------------------------- | :------------------------------------ |
| `speed`            | `number` | `1`                        | Rotation speed multiplier.            |
| `particleSize`     | `number` | `0.022`                    | Size of each particle.                |
| `particleOpacity`  | `number` | `0.8`                      | Opacity of the particles.             |
| `orbitOpacity`     | `number` | `0.35`                     | Opacity of the rings.                 |
| `scale`            | `number` | `1`                        | Scale of the whole sphere.            |
| `haloOpacity`      | `number` | `0.2`                      | Opacity of the glow around each node. |
| `hue`              | `number` | `0`                        | Hue rotation in degrees.              |
| `particleColor`    | `string` | theme `--primary`          | Colour of the bright particles.       |
| `particleDimColor` | `string` | theme `--muted-foreground` | Colour of the dim particles.          |
| `orbitColor`       | `string` | theme `--foreground`       | Colour of the orbit rings.            |
| `nodeColor`        | `string` | theme `--primary`          | Colour of the orbiting nodes.         |
| `haloColor`        | `string` | theme `--primary`          | Colour of the node halos.             |
| `backgroundColor`  | `string` | theme `--background`       | Background behind the sphere.         |

## Source

`components/ui/moon-lattice.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Orbital Sphere (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

/** Reads a bare-HSL theme token as an `hsl(h, s%, l%)` string three.js can parse. */
const themeColor = (name: string) =>
  `hsl(${getComputedStyle(document.documentElement).getPropertyValue(name).trim().split(/\s+/).join(", ")})`;
const isLightTheme = () =>
  Number.parseFloat(
    getComputedStyle(document.documentElement)
      .getPropertyValue("--background")
      .trim()
      .split(/\s+/)[2] ?? "0",
  ) > 50;

export interface MoonLatticeProps {
  speed?: number;
  particleSize?: number;
  particleOpacity?: number;
  orbitOpacity?: number;
  scale?: number;
  haloOpacity?: number;
  hue?: number;
  particleColor?: string;
  particleDimColor?: string;
  orbitColor?: string;
  nodeColor?: string;
  haloColor?: string;
  backgroundColor?: string;
  className?: string;
}

export function MoonLattice({
  speed = 1,
  particleSize = 0.022,
  particleOpacity = 0.8,
  orbitOpacity = 0.35,
  scale = 1,
  haloOpacity = 0.2,
  hue = 0,
  particleColor,
  particleDimColor,
  orbitColor,
  nodeColor,
  haloColor,
  backgroundColor,
  className,
}: MoonLatticeProps) {
  const prefersReducedMotion = useReducedMotion();
  const [themeKey, setThemeKey] = useState(0);
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({
    speed,
    particleSize,
    particleOpacity,
    orbitOpacity,
    scale,
    haloOpacity,
  });
  options.current = { speed, particleSize, particleOpacity, orbitOpacity, scale, haloOpacity };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 1000);
    const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    // The original ran on three r128 (no colour management): colours reach the screen untouched.
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    const raw = (value: string) => new THREE.Color().setStyle(value, THREE.LinearSRGBColorSpace);
    const light = isLightTheme();
    const blending = light ? THREE.NormalBlending : THREE.AdditiveBlending;
    const networkGroup = new THREE.Group();
    scene.add(networkGroup);

    const radius = 2.2;
    const particleCount = 15000;
    const positions = new Float32Array(particleCount * 3);
    const colors = new Float32Array(particleCount * 3);
    const colorBright = raw(particleColor ?? themeColor("--primary"));
    const colorDim = raw(particleDimColor ?? themeColor("--muted-foreground"));
    let validIndex = 0;
    for (let index = 0; index < particleCount; index += 1) {
      const phi = Math.acos(-1 + (2 * index) / particleCount);
      const theta = Math.sqrt(particleCount * Math.PI) * phi;
      const x = radius * Math.cos(theta) * Math.sin(phi);
      const y = radius * Math.sin(theta) * Math.sin(phi);
      const z = radius * Math.cos(phi);
      const noise =
        Math.sin(x * 3.5) * Math.cos(y * 3.5) * Math.sin(z * 3.5) + Math.cos(x * 6) * 0.4;
      if (noise <= -0.1) continue;
      const distortion = 1 + noise * 0.1;
      positions[validIndex * 3] = x * distortion;
      positions[validIndex * 3 + 1] = y * distortion;
      positions[validIndex * 3 + 2] = z * distortion;
      const mixedColor = colorDim.clone().lerp(colorBright, noise > 0.5 ? 1 : 0.3);
      colors[validIndex * 3] = mixedColor.r;
      colors[validIndex * 3 + 1] = mixedColor.g;
      colors[validIndex * 3 + 2] = mixedColor.b;
      validIndex += 1;
    }
    const particleGeometry = new THREE.BufferGeometry();
    particleGeometry.setAttribute(
      "position",
      new THREE.BufferAttribute(positions.slice(0, validIndex * 3), 3),
    );
    particleGeometry.setAttribute(
      "color",
      new THREE.BufferAttribute(colors.slice(0, validIndex * 3), 3),
    );
    const particleMaterial = new THREE.PointsMaterial({
      size: 0.015,
      vertexColors: true,
      transparent: true,
      opacity: 0.8,
      blending,
      depthWrite: false,
    });
    networkGroup.add(new THREE.Points(particleGeometry, particleMaterial));

    const orbitMaterial = new THREE.LineBasicMaterial({
      color: raw(orbitColor ?? themeColor("--foreground")),
      transparent: true,
      opacity: 0.25,
      blending,
    });
    const orbitGeometries: THREE.BufferGeometry[] = [];
    const nodeGeometries: THREE.BufferGeometry[] = [];
    const nodeMaterials: THREE.Material[] = [];
    const haloMaterials: THREE.MeshBasicMaterial[] = [];
    let responsiveScale = 1;
    for (let index = 0; index < 6; index += 1) {
      const geometry = new THREE.BufferGeometry();
      const points: number[] = [];
      const orbitRadius = radius * (1.08 + Math.random() * 0.2);
      for (let point = 0; point <= 90; point += 1) {
        const angle = (point / 90) * Math.PI * 2;
        points.push(
          Math.cos(angle) * orbitRadius,
          Math.sin(angle) * orbitRadius,
          Math.sin(angle * 4) * 0.1,
        );
      }
      geometry.setAttribute("position", new THREE.Float32BufferAttribute(points, 3));
      orbitGeometries.push(geometry);
      const line = new THREE.Line(geometry, orbitMaterial);
      line.rotation.x = Math.random() * Math.PI * 2;
      line.rotation.y = Math.random() * Math.PI * 2;
      networkGroup.add(line);
      if (index % 2 !== 0) {
        const nodeGeometry = new THREE.SphereGeometry(0.025, 16, 16);
        const nodeMaterial = new THREE.MeshBasicMaterial({
          color: raw(nodeColor ?? themeColor("--primary")),
        });
        const node = new THREE.Mesh(nodeGeometry, nodeMaterial);
        const angle = Math.random() * Math.PI * 2;
        node.position.set(Math.cos(angle) * orbitRadius, Math.sin(angle) * orbitRadius, 0);
        line.add(node);
        const haloGeometry = new THREE.SphereGeometry(0.08, 16, 16);
        const haloMaterial = new THREE.MeshBasicMaterial({
          color: raw(haloColor ?? themeColor("--primary")),
          transparent: true,
          opacity: 0.2,
          blending,
        });
        node.add(new THREE.Mesh(haloGeometry, haloMaterial));
        nodeGeometries.push(nodeGeometry, haloGeometry);
        nodeMaterials.push(nodeMaterial, haloMaterial);
        haloMaterials.push(haloMaterial);
      }
    }

    const render = (advance: boolean) => {
      const o = options.current;
      particleMaterial.size = o.particleSize;
      particleMaterial.opacity = o.particleOpacity;
      orbitMaterial.opacity = o.orbitOpacity;
      haloMaterials.forEach((material) => (material.opacity = o.haloOpacity));
      networkGroup.scale.setScalar(responsiveScale * o.scale);
      if (advance) {
        networkGroup.rotation.y += 0.0008 * o.speed;
        networkGroup.rotation.x += 0.0003 * o.speed;
        networkGroup.children.forEach((child, index) => {
          if (child.type === "Line")
            child.rotation.z += 0.0004 * o.speed * (index % 2 === 0 ? 1 : -1);
        });
      }
      renderer.render(scene, camera);
    };

    const resize = () => {
      const { width, height } = host.getBoundingClientRect();
      camera.aspect = width / Math.max(1, height);
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);
      if (width >= 1024) {
        networkGroup.position.set(0, 0, -1.5);
        responsiveScale = 0.95;
        camera.position.z = 6;
      } else {
        networkGroup.position.set(0, 0, -3);
        responsiveScale = 1;
        camera.position.z = 6.5;
      }
      render(false);
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      render(true);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !frame) frame = requestAnimationFrame(tick);
    };
    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    networkGroup.rotation.set(0.5, 0, 0.35);
    // Re-run the scene when the site switches light/dark mode or palette.
    const themeObserver = new MutationObserver(() => setThemeKey((key) => key + 1));
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      themeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      particleGeometry.dispose();
      particleMaterial.dispose();
      orbitMaterial.dispose();
      orbitGeometries.forEach((item) => item.dispose());
      nodeGeometries.forEach((item) => item.dispose());
      nodeMaterials.forEach((item) => item.dispose());
      renderer.dispose();
    };
  }, [
    prefersReducedMotion,
    themeKey,
    particleColor,
    particleDimColor,
    orbitColor,
    nodeColor,
    haloColor,
  ]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ filter: `hue-rotate(${hue}deg)` }}
      />
    </div>
  );
}
```

---

# Resonance Plate

> Chladni-style nodal lines shimmering across an off-centre plate, with drifting motes, in theme ink.

Install: `npx @modus-ui/cli add resonance-plate`

A WebGL shader draws the shifting nodal lines of a vibrating plate set off to the right, leaving the left side calm for copy. Nodal lines take the muted ink, antinodes and the periodic strike ring take the primary, and a few motes drift upward. Click to strike it. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add resonance-plate
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/resonance-plate.tsx`.
3. Paste the code.

## Usage

```tsx
import { ResonancePlate } from "@/components/ui/resonance-plate";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ResonancePlate />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type       | Default     | Description                                                                     |
| :---------------- | :--------- | :---------- | :------------------------------------------------------------------------------ |
| `speed`           | `number`   | `1`         | Animation speed multiplier.                                                     |
| `pointerAmount`   | `number`   | `1`         | How far the pattern follows the pointer.                                        |
| `strikeDuration`  | `number`   | `2400`      | Milliseconds a strike's ring takes to fade.                                     |
| `emberAmount`     | `number`   | `1`         | Share of the 58 drifting motes to draw (0 to 1).                                |
| `brightness`      | `number`   | `1`         | CSS brightness filter.                                                          |
| `opacity`         | `number`   | `1`         | Overall opacity.                                                                |
| `hue`             | `number`   | `0`         | Hue rotation in degrees.                                                        |
| `saturation`      | `number`   | `1`         | CSS saturation filter.                                                          |
| `backgroundColor` | `string`   | `undefined` | CSS background. Defaults to the theme background.                               |
| `colors`          | `string[]` | `undefined` | Hex overrides for deep, node, antinode and highlight. Defaults to theme tokens. |
| `emberColors`     | `string[]` | `undefined` | Hex overrides for hot and cool motes. Defaults to theme tokens.                 |

## Source

`components/ui/resonance-plate.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Bell Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ResonancePlateProps {
  speed?: number;
  pointerAmount?: number;
  strikeDuration?: number;
  emberAmount?: number;
  brightness?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  /** CSS background. Defaults to the theme background. */
  backgroundColor?: string;
  /** Hex overrides for [deep, node, antinode, highlight]. Defaults to theme tokens. */
  colors?: string[];
  /** Hex overrides for [hot, cool] motes. Defaults to theme tokens. */
  emberColors?: string[];
  className?: string;
}

const TOKENS = [
  "primary",
  "foreground",
  "background",
  "muted-foreground",
  "border",
  "card",
] as const;
type Tokens = Record<(typeof TOKENS)[number], string>;

/** Bare HSL channels of the Modus theme tokens, re-read when the theme or palette changes. */
function useThemeTokens(): Tokens | null {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const next = Object.fromEntries(
        TOKENS.map((name) => [name, style.getPropertyValue(`--${name}`).trim()]),
      ) as Tokens;
      setTokens((prev) => (prev && TOKENS.every((k) => prev[k] === next[k]) ? prev : next));
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

/** Bare HSL channels ("h s% l%") to 0–1 RGB. */
function channelsToRgb(channels: string): [number, number, number] {
  const [h, s, l] = channels.split(/\s+/).map((part) => parseFloat(part));
  const sat = (s || 0) / 100;
  const lig = (l || 0) / 100;
  const k = (n: number) => (n + (h || 0) / 30) % 12;
  const a = sat * Math.min(lig, 1 - lig);
  const f = (n: number) => lig - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}
const EMBER_COUNT = 58;

const VERTEX_SHADER = `
attribute vec2 position;
void main() { gl_Position = vec4(position, 0.0, 1.0); }
`;

const FRAGMENT_SHADER = `
precision highp float;
uniform vec2 u_resolution;
uniform float u_time;
uniform vec2 u_mouse;
uniform float u_strike;
uniform vec3 u_deep;
uniform vec3 u_patina;
uniform vec3 u_bronze;
uniform vec3 u_ash;

#define PI 3.14159265359

float hash(vec2 p) { return fract(sin(dot(p, vec2(23.71, 91.37))) * 41537.1234); }

// damped-cosine stand-in for the Bessel envelope of a circular mode
float bess(float x) { return cos(x - 0.785398) / sqrt(1.0 + abs(x)); }

void main() {
  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
  vec2 p = uv * 2.0 - 1.0;
  p.x *= u_resolution.x / u_resolution.y;
  // The plate sits off-centre, to the right, leaving the left side calm for copy.
  p.x -= 0.62 * u_resolution.x / u_resolution.y;
  p.y += 0.12;

  vec2 m = u_mouse / u_resolution.xy * 2.0 - 1.0;
  m.y = -m.y;
  m.x *= u_resolution.x / u_resolution.y;
  p -= m * 0.11;

  float t = u_time * 0.09;
  float r = length(p);
  float a = atan(p.y, p.x);

  // the bell drifts between partials the way a struck bell does
  float ang = 3.0 + 1.6 * sin(t * 0.37) + sin(t * 0.19 + 1.7);
  float k   = 3.1 + 1.0 * sin(t * 0.23 + 0.6);

  float amp = 1.0 + (1.0 - u_strike) * 0.55;
  float f1 = bess(r * k * PI - t * 2.2) * cos(ang * a + t * 0.5);
  float f2 = bess(r * k * 1.6 * PI + t * 1.4) * cos((ang * 2.0 + 1.0) * a - t * 0.31);
  float f = (f1 + f2 * 0.30) * amp;

  // nodal lines — where the metal stands still
  float node = 1.0 - smoothstep(0.0, 0.075 + 0.075 * r, abs(f));
  // antinodes — where it moves, and glows hot
  float anti = smoothstep(0.40, 0.95, abs(f));

  // the crown stays quiet — clears a reading zone under the type
  float open = smoothstep(0.14, 0.92, r);
  node *= open;
  anti *= open;

  vec3 col = u_deep;
  col = mix(col, u_patina, node * 0.50);
  col = mix(col, u_bronze, anti * 0.55);
  col = mix(col, u_ash, pow(node, 3.0) * 0.25);

  // shock ring travelling out from the strike
  float ring = smoothstep(0.06, 0.0, abs(r - u_strike * 2.3)) * (1.0 - u_strike);
  col = mix(col, u_bronze, ring * 0.6);

  col = mix(u_deep, col, smoothstep(2.2, 0.3, r));
  col += (hash(gl_FragCoord.xy) - 0.5) * 0.022;

  gl_FragColor = vec4(col, 1.0);
}
`;

type Ember = {
  x: number;
  y: number;
  r: number;
  vy: number;
  vx: number;
  ph: number;
  sp: number;
  hot: boolean;
};

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create Resonance Plate shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader) ?? "Resonance Plate shader compilation failed");
  }
  return shader;
}

function hexToRgb(hex: string): [number, number, number] {
  const value = parseInt(hex.replace("#", ""), 16);
  return [((value >> 16) & 255) / 255, ((value >> 8) & 255) / 255, (value & 255) / 255];
}

export function ResonancePlate({
  speed = 1,
  pointerAmount = 1,
  strikeDuration = 2400,
  emberAmount = 1,
  brightness = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  backgroundColor,
  colors,
  emberColors,
  className,
}: ResonancePlateProps) {
  const tokens = useThemeTokens();
  const hostRef = useRef<HTMLDivElement>(null);
  const modeRef = useRef<HTMLCanvasElement>(null);
  const emberRef = useRef<HTMLCanvasElement>(null);
  const prefersReducedMotion = useReducedMotion();
  const optionsRef = useRef({
    speed,
    pointerAmount,
    strikeDuration,
    emberAmount,
    colors,
    emberColors,
    tokens,
  });
  optionsRef.current = {
    speed,
    pointerAmount,
    strikeDuration,
    emberAmount,
    colors,
    emberColors,
    tokens,
  };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = modeRef.current;
    const emberCanvas = emberRef.current;
    if (!host || !canvas || !emberCanvas) return;
    const gl = canvas.getContext("webgl");
    const emberContext = emberCanvas.getContext("2d");
    if (!gl || !emberContext) return;

    const vertex = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const program = gl.createProgram();
    if (!program) return;
    gl.attachShader(program, vertex);
    gl.attachShader(program, fragment);
    gl.linkProgram(program);
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      throw new Error(gl.getProgramInfoLog(program) ?? "Resonance Plate program link failed");
    }
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(
      gl.ARRAY_BUFFER,
      new Float32Array([-1, -1, 1, -1, -1, 1, 1, -1, 1, 1, -1, 1]),
      gl.STATIC_DRAW,
    );
    const position = gl.getAttribLocation(program, "position");
    gl.enableVertexAttribArray(position);
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);

    const resolution = gl.getUniformLocation(program, "u_resolution");
    const time = gl.getUniformLocation(program, "u_time");
    const mouseUniform = gl.getUniformLocation(program, "u_mouse");
    const strikeUniform = gl.getUniformLocation(program, "u_strike");
    const colorUniforms = ["u_deep", "u_patina", "u_bronze", "u_ash"].map((name) =>
      gl.getUniformLocation(program, name),
    );

    let width = 1;
    let height = 1;
    let dpr = 1;
    let mouseX = 0.5;
    let mouseY = 0.5;
    let targetX = 0.5;
    let targetY = 0.5;
    let frame = 0;
    let visible = true;
    let initialized = false;
    let lastStrikeMs = -1e9;
    const startedAt = performance.now();

    const embers: Ember[] = Array.from({ length: EMBER_COUNT }, () => ({
      x: Math.random(),
      y: Math.random(),
      r: 0.4 + Math.random() * 1.4,
      vy: -(0.1 + Math.random() * 0.26),
      vx: (Math.random() - 0.5) * 0.08,
      ph: Math.random() * Math.PI * 2,
      sp: 0.5 + Math.random() * 1.4,
      hot: Math.random() < 0.36,
    }));

    const draw = (now: number) => {
      const options = optionsRef.current;
      const t = now * 0.001 * options.speed;
      mouseX += (targetX - mouseX) * 0.04;
      mouseY += (targetY - mouseY) * 0.04;
      gl.uniform1f(time, (now - startedAt) * 0.001 * options.speed);
      gl.uniform1f(
        strikeUniform,
        Math.min(1, Math.max(0, (now - lastStrikeMs) / options.strikeDuration)),
      );
      gl.uniform2f(mouseUniform, mouseX * dpr, mouseY * dpr);
      const tk = options.tokens;
      const themed = tk ? [tk.background, tk["muted-foreground"], tk.primary, tk.foreground] : null;
      colorUniforms.forEach((location, index) => {
        const override = options.colors?.[index];
        const channels = themed?.[index];
        const [r, g, b] = override
          ? hexToRgb(override)
          : channels
            ? channelsToRgb(channels)
            : [0.5, 0.5, 0.5];
        gl.uniform3f(location, r, g, b);
      });
      gl.drawArrays(gl.TRIANGLES, 0, 6);

      const moteRgb = (index: number, fallback: string | undefined) => {
        const override = options.emberColors?.[index];
        const [r, g, b] = override
          ? hexToRgb(override)
          : fallback
            ? channelsToRgb(fallback)
            : [0.5, 0.5, 0.5];
        return `${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}`;
      };
      const hot = moteRgb(0, tk?.primary);
      const cool = moteRgb(1, tk?.["muted-foreground"]);
      emberContext.clearRect(0, 0, width, height);
      const count = Math.max(
        0,
        Math.min(EMBER_COUNT, Math.round(EMBER_COUNT * options.emberAmount)),
      );
      for (let index = 0; index < count; index += 1) {
        const ember = embers[index];
        if (!prefersReducedMotion) {
          ember.y += ember.vy * options.speed;
          ember.x += (ember.vx + Math.sin(t * ember.sp * 0.5 + ember.ph) * 0.13) * options.speed;
        }
        if (ember.y < -4) {
          ember.y = height + 4;
          ember.x = Math.random() * width;
        }
        if (ember.x < -4) ember.x = width + 4;
        if (ember.x > width + 4) ember.x = -4;
        const twinkle = 0.5 + 0.5 * Math.sin(t * ember.sp + ember.ph);
        emberContext.beginPath();
        emberContext.arc(ember.x, ember.y, ember.r, 0, Math.PI * 2);
        emberContext.fillStyle = ember.hot
          ? `rgba(${hot}, ${0.06 + twinkle * 0.34})`
          : `rgba(${cool}, ${0.04 + twinkle * 0.24})`;
        emberContext.fill();
      }
    };

    const render = (now: number) => {
      draw(now);
      frame = visible && !document.hidden ? requestAnimationFrame(render) : 0;
    };

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      width = Math.max(1, bounds.width);
      height = Math.max(1, bounds.height);
      dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.round(width * dpr));
      canvas.height = Math.max(1, Math.round(height * dpr));
      emberCanvas.width = canvas.width;
      emberCanvas.height = canvas.height;
      emberContext.setTransform(dpr, 0, 0, dpr, 0, 0);
      gl.viewport(0, 0, canvas.width, canvas.height);
      gl.uniform2f(resolution, canvas.width, canvas.height);
      if (!initialized) {
        mouseX = targetX = width * 0.5;
        mouseY = targetY = height * 0.5;
        initialized = true;
      }
      embers.forEach((ember) => {
        if (ember.x <= 1) ember.x *= width;
        if (ember.y <= 1) ember.y *= height;
      });
      if (prefersReducedMotion) draw(startedAt + 14000 / Math.max(speed, 0.001));
    };

    const inside = (event: PointerEvent) => {
      const bounds = host.getBoundingClientRect();
      return (
        event.clientX >= bounds.left &&
        event.clientX <= bounds.right &&
        event.clientY >= bounds.top &&
        event.clientY <= bounds.bottom
      );
    };
    const pointer = (event: PointerEvent) => {
      if (!inside(event)) return;
      const bounds = host.getBoundingClientRect();
      const amount = optionsRef.current.pointerAmount;
      targetX = width * 0.5 + (event.clientX - bounds.left - width * 0.5) * amount;
      targetY = height * 0.5 + (event.clientY - bounds.top - height * 0.5) * amount;
    };
    const strike = () => {
      lastStrikeMs = performance.now();
    };
    const pointerDown = (event: PointerEvent) => {
      if (inside(event)) strike();
    };

    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    resize();

    if (prefersReducedMotion) {
      return () => {
        resizeObserver.disconnect();
        gl.deleteBuffer(buffer);
        gl.deleteShader(vertex);
        gl.deleteShader(fragment);
        gl.deleteProgram(program);
      };
    }

    const firstStrike = window.setTimeout(strike, 1700);
    const strikeTimer = window.setInterval(strike, 8200);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible && !frame) frame = requestAnimationFrame(render);
      if (!visible && frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    intersection.observe(host);
    window.addEventListener("pointermove", pointer, { passive: true });
    window.addEventListener("pointerdown", pointerDown);
    frame = requestAnimationFrame(render);

    return () => {
      if (frame) cancelAnimationFrame(frame);
      window.clearTimeout(firstStrike);
      window.clearInterval(strikeTimer);
      resizeObserver.disconnect();
      intersection.disconnect();
      window.removeEventListener("pointermove", pointer);
      window.removeEventListener("pointerdown", pointerDown);
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
      gl.deleteProgram(program);
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        opacity,
        filter: `hue-rotate(${hue}deg) saturate(${saturation}) brightness(${brightness})`,
      }}
    >
      <canvas ref={modeRef} className="absolute inset-0 z-0 block h-full w-full" />
      <canvas
        ref={emberRef}
        className="pointer-events-none absolute inset-0 z-[1] block h-full w-full"
      />
    </div>
  );
}
```

---

# Confluence Lines

> A WebGL shader of three light streams meeting on the page background, inked in the theme primary, foreground and muted tones.

Install: `npx @modus-ui/cli add confluence-lines`

A WebGL shader of three light streams meeting on the page background, inked in the theme primary, foreground and muted tones. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add confluence-lines
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/confluence-lines.tsx`.
3. Paste the code.

## Usage

```tsx
import { ConfluenceLines } from "@/components/ui/confluence-lines";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ConfluenceLines />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type       | Default                                        | Description                       |
| :---------------- | :--------- | :--------------------------------------------- | :-------------------------------- |
| `speed`           | `number`   | `1`                                            | Animation speed multiplier.       |
| `fidelity`        | `number`   | `0.5`                                          | Spread between the three streams. |
| `scale`           | `number`   | `1`                                            | Scale of the rendered canvas.     |
| `brightness`      | `number`   | `1`                                            | CSS brightness filter.            |
| `opacity`         | `number`   | `1`                                            | Canvas opacity.                   |
| `hue`             | `number`   | `0`                                            | Hue rotation in degrees.          |
| `saturation`      | `number`   | `1`                                            | CSS saturation filter.            |
| `backgroundColor` | `string`   | theme background                               | Background behind the canvas.     |
| `colors`          | `string[]` | theme primary, foreground and muted foreground | One colour per stream.            |

## Source

`components/ui/confluence-lines.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Stream Convergence (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface ConfluenceLinesProps {
  speed?: number;
  fidelity?: number;
  scale?: number;
  brightness?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  /** Defaults to the theme background. */
  backgroundColor?: string;
  /** One CSS colour per stream. Defaults to the theme primary, foreground and muted foreground. */
  colors?: string[];
  className?: string;
}

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];

// Per-band ink strength: the middle stream is the boldest.
const BAND_GAIN = [0.75, 1, 0.55];

const VERTEX_SHADER = `
attribute vec2 position;
varying vec2 vUv;
void main() {
  vUv = position * 0.5 + 0.5;
  gl_Position = vec4(position, 0.0, 1.0);
}
`;

const FRAGMENT_SHADER = /* glsl */ `
precision highp float;
uniform float u_time;
uniform vec2 u_resolution;
uniform float u_interactive_fidelity;
uniform vec3 u_band0;
uniform vec3 u_band1;
uniform vec3 u_band2;
uniform vec3 u_background;
varying vec2 vUv;

mat2 rotate2d(float _angle){
  return mat2(cos(_angle),-sin(_angle),
              sin(_angle),cos(_angle));
}

void main() {
  vec2 p = vUv * 2.0 - 1.0;
  p.x *= u_resolution.x / u_resolution.y;
  p = rotate2d(-0.32) * p;

  vec3 color = u_background;
  float spread = 0.09 * (0.3 + u_interactive_fidelity * 0.7);
  float fade = exp(-length(vUv * 2.0 - 1.0) * 0.9);

  // Streams are inked onto the paper one over the other, so they hold on light and dark grounds.
  for(int i = 0; i < 3; i++) {
    float offset = float(1 - i) * spread;
    float y = p.y + offset + (sin(p.x * 1.8 - u_time * 1.2) * 0.18);
    float line = sin(y * 4.5 + u_time * 1.6) * 0.5 + 0.5;
    float wave = smoothstep(0.9, 0.995, line) + smoothstep(0.7, 0.995, line) * 0.18;
    vec3 ink = i == 0 ? u_band0 : (i == 1 ? u_band1 : u_band2);
    float gain = i == 0 ? ${BAND_GAIN[0].toFixed(2)} : (i == 1 ? ${BAND_GAIN[1].toFixed(2)} : ${BAND_GAIN[2].toFixed(2)});
    color = mix(color, ink, clamp(wave * gain * fade, 0.0, 1.0));
  }

  gl_FragColor = vec4(color, 1.0);
}
`;

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create Confluence Lines shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader) ?? "Confluence Lines shader compilation failed");
  }
  return shader;
}

export function ConfluenceLines({
  speed = 1,
  fidelity = 0.5,
  scale = 1,
  brightness = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  backgroundColor,
  colors,
  className,
}: ConfluenceLinesProps) {
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const prefersReducedMotion = useReducedMotion();
  const optionsRef = useRef({ speed, fidelity, inks: [] as Rgb[], ground: [0, 0, 0] as Rgb });
  const colorKey = colors?.join(",");
  useEffect(() => {
    if (!theme) return;
    optionsRef.current.ground = backgroundColor ? toRgb(backgroundColor) : theme.background;
    optionsRef.current.inks = colorKey
      ? colorKey.split(",").map(toRgb)
      : [theme.primary, theme.foreground, theme["muted-foreground"]];
  }, [theme, backgroundColor, colorKey]);
  optionsRef.current.speed = speed;
  optionsRef.current.fidelity = fidelity;

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas || !theme) return;
    const gl = canvas.getContext("webgl", { alpha: true, antialias: false });
    if (!gl) return;

    const vertex = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const program = gl.createProgram();
    if (!program) return;
    gl.attachShader(program, vertex);
    gl.attachShader(program, fragment);
    gl.linkProgram(program);
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      throw new Error(gl.getProgramInfoLog(program) ?? "Confluence Lines program link failed");
    }
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(
      gl.ARRAY_BUFFER,
      new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
      gl.STATIC_DRAW,
    );
    const position = gl.getAttribLocation(program, "position");
    gl.enableVertexAttribArray(position);
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);

    const uTime = gl.getUniformLocation(program, "u_time");
    const uResolution = gl.getUniformLocation(program, "u_resolution");
    const uFidelity = gl.getUniformLocation(program, "u_interactive_fidelity");
    const uBands = ["u_band0", "u_band1", "u_band2"].map((name) =>
      gl.getUniformLocation(program, name),
    );
    const uBackground = gl.getUniformLocation(program, "u_background");
    let frame = 0;
    let visible = true;

    const draw = (now: number) => {
      const options = optionsRef.current;
      gl.uniform1f(uTime, now * 0.0003 * options.speed);
      gl.uniform1f(uFidelity, options.fidelity);
      uBands.forEach((location, index) => {
        gl.uniform3fv(location, options.inks[index] ?? options.inks[0] ?? options.ground);
      });
      gl.uniform3fv(uBackground, options.ground);
      gl.drawArrays(gl.TRIANGLES, 0, 6);
    };

    const render = (now: number) => {
      draw(now);
      frame = visible && !document.hidden ? requestAnimationFrame(render) : 0;
    };

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.round(bounds.width * dpr));
      canvas.height = Math.max(1, Math.round(bounds.height * dpr));
      gl.viewport(0, 0, canvas.width, canvas.height);
      gl.uniform2f(uResolution, canvas.width, canvas.height);
      if (prefersReducedMotion) draw(8000);
    };

    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    resize();

    let intersection: IntersectionObserver | undefined;
    if (!prefersReducedMotion) {
      intersection = new IntersectionObserver(([entry]) => {
        visible = entry?.isIntersecting ?? true;
        if (visible && !frame) frame = requestAnimationFrame(render);
        if (!visible && frame) {
          cancelAnimationFrame(frame);
          frame = 0;
        }
      });
      intersection.observe(host);
      frame = requestAnimationFrame(render);
    }

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection?.disconnect();
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
      gl.deleteProgram(program);
    };
  }, [prefersReducedMotion, theme]);

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("pointer-events-none absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full"
        style={{
          opacity,
          filter: `hue-rotate(${hue}deg) saturate(${saturation}) brightness(${brightness})`,
          transform: `scale(${scale})`,
        }}
      />
    </div>
  );
}
```

---

# Silk Bands

> A WebGL background of slow, wide bands printed through a coarse halftone screen in a ramp of the theme colours.

Install: `npx @modus-ui/cli add silk-bands`

A full-bleed WebGL shader of three slow, wide bands printed through a coarse scanning halftone screen. The colours are a ramp built from the theme (`--primary` at several lightnesses, `--foreground` and `--muted-foreground`) over `--background`, so it is ink on paper in light mode and follows palette changes live. The bands gather on the left and fade out to the right, leaving room for text, and drift with the pointer. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add silk-bands
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/silk-bands.tsx`.
3. Paste the code.

## Usage

```tsx
import { SilkBands } from "@/components/ui/silk-bands";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SilkBands />
      <div className="relative z-10 p-8 text-white">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type       | Default              | Description                                                         |
| :---------------- | :--------- | :------------------- | :------------------------------------------------------------------ |
| `speed`           | `number`   | `1`                  | Animation speed multiplier.                                         |
| `pointerAmount`   | `number`   | `1`                  | How strongly the bands follow the pointer.                          |
| `smoothing`       | `number`   | `0.035`              | Pointer easing per frame.                                           |
| `brightness`      | `number`   | `1`                  | CSS brightness filter.                                              |
| `opacity`         | `number`   | `1`                  | Canvas opacity.                                                     |
| `hue`             | `number`   | `0`                  | Hue rotation in degrees.                                            |
| `saturation`      | `number`   | `1`                  | CSS saturation filter.                                              |
| `backgroundColor` | `string`   | theme `--background` | Base colour behind the bands.                                       |
| `colors`          | `string[]` | theme ramp           | Six band colours (any CSS colour): three bands, two accents, bloom. |

## Source

`components/ui/silk-bands.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Ribbon Field (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface SilkBandsProps {
  speed?: number;
  pointerAmount?: number;
  smoothing?: number;
  brightness?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  backgroundColor?: string;
  colors?: string[];
  className?: string;
}

const readToken = (name: string) =>
  getComputedStyle(document.documentElement).getPropertyValue(name).trim();

/** A theme token with its lightness shifted, for building a ramp from one hue. */
function shade(name: string, shift: number) {
  const [h = "0", sat = "0%", l = "50%"] = readToken(name).split(/\s+/);
  return `hsl(${h} ${sat} ${Math.min(96, Math.max(4, Number.parseFloat(l) + shift))}%)`;
}

/** The six band colours, ramped from the theme's primary, foreground and muted ink. */
const themeColors = () => [
  shade("--primary", 0),
  shade("--foreground", 0),
  shade("--muted-foreground", 0),
  shade("--primary", 18),
  shade("--primary", -12),
  shade("--primary", 30),
];
const COLOR_UNIFORMS = ["teal", "cyan", "indigo", "purple", "blue", "bloomColor"];

const VERTEX_SHADER = `
attribute vec2 position;
void main() {
  gl_Position = vec4(position, 0.0, 1.0);
}
`;

const FRAGMENT_SHADER = `
precision highp float;
uniform vec2 resolution;
uniform float time;
uniform vec2 pointer;
uniform vec3 teal;
uniform vec3 cyan;
uniform vec3 indigo;
uniform vec3 purple;
uniform vec3 blue;
uniform vec3 bloomColor;
uniform vec3 base;

float hash(vec2 p) {
  p = fract(p * vec2(123.34, 456.21));
  p += dot(p, p + 45.32);
  return fract(p.x * p.y);
}

float ribbon(vec2 uv, float offset, float width, float phase) {
  float y = 0.48 + 0.16 * sin((uv.x * 1.6) + phase) + 0.045 * sin((uv.x * 7.0) - phase * 0.7);
  float d = abs(uv.y - y - offset);
  return exp(-(d * d) / width);
}

void main() {
  vec2 uv = gl_FragCoord.xy / resolution.xy;
  vec2 p = uv;
  p.x *= resolution.x / resolution.y;

  float t = time * 0.22;
  float drift = (pointer.x - 0.5) * 0.06;

  float rightFade = 1.0 - smoothstep(0.30, 0.78, uv.x);
  float centerDark = 1.0 - smoothstep(0.0, 0.88, distance(uv, vec2(0.86, 0.52)));

  float r1 = ribbon(vec2(uv.x + drift, uv.y), 0.03, 0.0065, t + 0.9);
  float r2 = ribbon(vec2(uv.x - drift * 0.7, uv.y), -0.23, 0.0085, t + 3.25);
  float r3 = ribbon(vec2(uv.x + drift * 0.4, uv.y), 0.25, 0.014, t + 1.85);

  float glow = r1 * 1.14 + r2 * 1.05 + r3 * 0.48;

  vec3 col = vec3(0.0);
  col += cyan * r1 * 0.92;
  col += teal * r1 * 0.62;
  col += indigo * r3 * 0.42;
  col += blue * r2 * 0.66;
  col += purple * (r2 + r3) * 0.30;

  float bloom = exp(-pow(distance(uv, vec2(0.26, 0.58 + 0.035 * sin(t))), 2.0) / 0.050);
  bloom += exp(-pow(distance(uv, vec2(0.32, 0.24 + 0.025 * cos(t))), 2.0) / 0.030);
  col += bloomColor * bloom * 0.34;

  vec2 grid = fract(gl_FragCoord.xy / 10.0) - 0.5;
  float dotShape = smoothstep(0.29, 0.11, length(grid));
  float noise = hash(floor(gl_FragCoord.xy / 10.0));
  float scan = 0.72 + 0.28 * sin((uv.x + uv.y) * 38.0 + time * 1.3);
  float dots = dotShape * (0.48 + 0.52 * noise) * scan;

  float micro = hash(gl_FragCoord.xy + time) * 0.035;
  float alpha = clamp((glow * 1.55 + bloom * 0.50) * dots * rightFade, 0.0, 1.0);
  alpha *= 1.0 - centerDark * 0.56;

  vec3 finalColor = mix(base, col, clamp(alpha * 1.55, 0.0, 1.0));
  finalColor += micro * rightFade;

  gl_FragColor = vec4(finalColor, 1.0);
}
`;

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create Silk Bands shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader) ?? "Silk Bands shader compilation failed");
  }
  return shader;
}

let probe: CanvasRenderingContext2D | null = null;
/** Resolves any CSS colour string to 0–1 RGB through a 1×1 canvas. */
function toRgb(color: string): [number, number, number] {
  probe ??= document.createElement("canvas").getContext("2d", { willReadFrequently: true });
  if (!probe) return [0, 0, 0];
  probe.clearRect(0, 0, 1, 1);
  probe.fillStyle = color;
  probe.fillRect(0, 0, 1, 1);
  const [r, g, b] = probe.getImageData(0, 0, 1, 1).data;
  return [r / 255, g / 255, b / 255];
}

export function SilkBands({
  speed = 1,
  pointerAmount = 1,
  smoothing = 0.035,
  brightness = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  backgroundColor,
  colors,
  className,
}: SilkBandsProps) {
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const prefersReducedMotion = useReducedMotion();
  const optionsRef = useRef({ speed, pointerAmount, smoothing, backgroundColor, colors });
  optionsRef.current = { speed, pointerAmount, smoothing, backgroundColor, colors };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    const gl = canvas.getContext("webgl", {
      alpha: true,
      antialias: false,
      premultipliedAlpha: false,
    });
    if (!gl) return;

    const vertex = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const program = gl.createProgram();
    if (!program) return;
    gl.attachShader(program, vertex);
    gl.attachShader(program, fragment);
    gl.linkProgram(program);
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      throw new Error(gl.getProgramInfoLog(program) ?? "Silk Bands program link failed");
    }
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(
      gl.ARRAY_BUFFER,
      new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
      gl.STATIC_DRAW,
    );
    const position = gl.getAttribLocation(program, "position");
    gl.enableVertexAttribArray(position);
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);

    const resolution = gl.getUniformLocation(program, "resolution");
    const time = gl.getUniformLocation(program, "time");
    const pointerUniform = gl.getUniformLocation(program, "pointer");
    const baseUniform = gl.getUniformLocation(program, "base");
    const colorUniforms = COLOR_UNIFORMS.map((name) => gl.getUniformLocation(program, name));
    let base: [number, number, number] = [0, 0, 0];
    let palette: [number, number, number][] = [];
    const readTheme = () => {
      const options = optionsRef.current;
      base = toRgb(options.backgroundColor ?? `hsl(${readToken("--background")})`);
      const fallback = themeColors();
      palette = fallback.map((color, index) => toRgb(options.colors?.[index] ?? color));
    };
    readTheme();
    let mouseX = 0.72;
    let mouseY = 0.42;
    let targetX = 0.72;
    let targetY = 0.42;
    let frame = 0;
    let visible = true;
    const startedAt = performance.now();

    const draw = (elapsed: number) => {
      const options = optionsRef.current;
      mouseX += (targetX - mouseX) * options.smoothing;
      mouseY += (targetY - mouseY) * options.smoothing;
      gl.uniform1f(time, elapsed * options.speed);
      gl.uniform2f(pointerUniform, mouseX, mouseY);
      gl.uniform3f(baseUniform, ...base);
      colorUniforms.forEach((location, index) => gl.uniform3f(location, ...palette[index]));
      gl.drawArrays(gl.TRIANGLES, 0, 6);
    };

    const render = (now: number) => {
      draw((now - startedAt) * 0.001);
      frame = visible && !document.hidden ? requestAnimationFrame(render) : 0;
    };

    const pointer = (event: PointerEvent) => {
      const bounds = host.getBoundingClientRect();
      if (
        event.clientX < bounds.left ||
        event.clientX > bounds.right ||
        event.clientY < bounds.top ||
        event.clientY > bounds.bottom
      ) {
        return;
      }
      const amount = optionsRef.current.pointerAmount;
      targetX = 0.72 + ((event.clientX - bounds.left) / Math.max(bounds.width, 1) - 0.72) * amount;
      targetY =
        0.42 + (1 - (event.clientY - bounds.top) / Math.max(bounds.height, 1) - 0.42) * amount;
    };

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      const ratio = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(bounds.width * ratio));
      canvas.height = Math.max(1, Math.floor(bounds.height * ratio));
      gl.viewport(0, 0, canvas.width, canvas.height);
      gl.uniform2f(resolution, canvas.width, canvas.height);
      if (prefersReducedMotion) draw(4);
    };

    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    resize();
    const themeObserver = new MutationObserver(() => {
      readTheme();
      if (prefersReducedMotion) draw(4);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });

    let intersection: IntersectionObserver | undefined;
    if (!prefersReducedMotion) {
      intersection = new IntersectionObserver(([entry]) => {
        visible = entry?.isIntersecting ?? true;
        if (visible && !frame) frame = requestAnimationFrame(render);
        if (!visible && frame) {
          cancelAnimationFrame(frame);
          frame = 0;
        }
      });
      intersection.observe(host);
      window.addEventListener("pointermove", pointer, { passive: true });
      frame = requestAnimationFrame(render);
    }

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      themeObserver.disconnect();
      intersection?.disconnect();
      window.removeEventListener("pointermove", pointer);
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
      gl.deleteProgram(program);
    };
  }, [prefersReducedMotion, backgroundColor, colors]);

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full"
        style={{
          opacity,
          filter: `hue-rotate(${hue}deg) saturate(${saturation}) brightness(${brightness})`,
        }}
      />
    </div>
  );
}
```

---

# Mercury Bloom

> A raymarched WebGL blob of liquid metal that reflects your theme and turns toward the pointer.

Install: `npx @modus-ui/cli add mercury-bloom`

A full-bleed raymarched WebGL shader of a metal blob that morphs with layered simplex noise. Its studio environment is built from the theme's background, card and primary tones, so it reads as polished pewter on paper in light mode and as dark mercury in dark mode, and follows the palette. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add mercury-bloom
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/mercury-bloom.tsx`.
3. Paste the code.

## Usage

```tsx
import { MercuryBloom } from "@/components/ui/mercury-bloom";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <MercuryBloom />
    </div>
  );
}
```

## Props

| Prop          | Type     | Default | Description                                     |
| :------------ | :------- | :------ | :---------------------------------------------- |
| `speed`       | `number` | `1`     | Animation speed multiplier.                     |
| `morph`       | `number` | `1.8`   | Strength of the surface deformation.            |
| `noiseScale`  | `number` | `1.3`   | Frequency of the deformation noise.             |
| `mouseAmount` | `number` | `0.15`  | How far the camera looks toward the pointer.    |
| `metal`       | `number` | `1`     | Reflection and specular strength.               |
| `camera`      | `number` | `6.5`   | Camera distance.                                |
| `tintHue`     | `number` | `220`   | Hue of the optional tint in degrees.            |
| `tintAmount`  | `number` | `0`     | Strength of the tint (0 keeps the theme metal). |

## Source

`components/ui/mercury-bloom.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Liquid Form (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface MercuryBloomProps {
  speed?: number;
  morph?: number;
  noiseScale?: number;
  mouseAmount?: number;
  metal?: number;
  camera?: number;
  tintHue?: number;
  tintAmount?: number;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** HSL channels to sRGB 0–1 for shader uniforms. */
function toRgb([h, s, l]: Hsl): [number, number, number] {
  const sat = Math.min(100, Math.max(0, s)) / 100;
  const lig = Math.min(100, Math.max(0, l)) / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = sat * Math.min(lig, 1 - lig);
  const f = (n: number) => lig - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}

const VERTEX_SHADER = `
attribute vec2 a_pos;
void main(){ gl_Position = vec4(a_pos, 0.0, 1.0); }
`;

const FRAGMENT_SHADER = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform vec2 u_mouse;
uniform float u_morph;
uniform float u_noise_scale;
uniform float u_mouse_amount;
uniform float u_metal;
uniform float u_camera;
uniform vec3 u_bg;
uniform vec3 u_ink;
uniform vec3 u_hi;

#define MAX_STEPS 70
#define MAX_DIST 20.0
#define SURF_DIST 0.002

vec3 mod289(vec3 x){return x-floor(x*(1.0/289.0))*289.0;}
vec4 mod289(vec4 x){return x-floor(x*(1.0/289.0))*289.0;}
vec4 permute(vec4 x){return mod289(((x*34.0)+1.0)*x);}
vec4 taylorInvSqrt(vec4 r){return 1.79284291400159-0.85373472095314*r;}
float snoise(vec3 v){
  const vec2 C=vec2(1.0/6.0,1.0/3.0);
  const vec4 D=vec4(0.0,0.5,1.0,2.0);
  vec3 i=floor(v+dot(v,C.yyy));
  vec3 x0=v-i+dot(i,C.xxx);
  vec3 g=step(x0.yzx,x0.xyz);
  vec3 l=1.0-g;
  vec3 i1=min(g.xyz,l.zxy);
  vec3 i2=max(g.xyz,l.zxy);
  vec3 x1=x0-i1+C.xxx;
  vec3 x2=x0-i2+C.yyy;
  vec3 x3=x0-D.yyy;
  i=mod289(i);
  vec4 p=permute(permute(permute(i.z+vec4(0.0,i1.z,i2.z,1.0))+i.y+vec4(0.0,i1.y,i2.y,1.0))+i.x+vec4(0.0,i1.x,i2.x,1.0));
  float n_=0.142857142857;
  vec3 ns=n_*D.wyz-D.xzx;
  vec4 j=p-49.0*floor(p*ns.z*ns.z);
  vec4 x_=floor(j*ns.z);
  vec4 y_=floor(j-7.0*x_);
  vec4 x=x_*ns.x+ns.yyyy;
  vec4 y=y_*ns.x+ns.yyyy;
  vec4 h=1.0-abs(x)-abs(y);
  vec4 b0=vec4(x.xy,y.xy);
  vec4 b1=vec4(x.zw,y.zw);
  vec4 s0=floor(b0)*2.0+1.0;
  vec4 s1=floor(b1)*2.0+1.0;
  vec4 sh=-step(h,vec4(0.0));
  vec4 a0=b0.xzyw+s0.xzyw*sh.xxyy;
  vec4 a1=b1.xzyw+s1.xzyw*sh.zzww;
  vec3 p0=vec3(a0.xy,h.x);
  vec3 p1=vec3(a0.zw,h.y);
  vec3 p2=vec3(a1.xy,h.z);
  vec3 p3=vec3(a1.zw,h.w);
  vec4 norm=taylorInvSqrt(vec4(dot(p0,p0),dot(p1,p1),dot(p2,p2),dot(p3,p3)));
  p0*=norm.x;p1*=norm.y;p2*=norm.z;p3*=norm.w;
  vec4 m=max(0.6-vec4(dot(x0,x0),dot(x1,x1),dot(x2,x2),dot(x3,x3)),0.0);
  m=m*m;
  return 42.0*dot(m*m,vec4(dot(p0,x0),dot(p1,x1),dot(p2,x2),dot(p3,x3)));
}

float map(vec3 p, float t) {
  float radius = 1.8;
  float morph = snoise(p * (0.8 * u_noise_scale) + t * 0.1) * 0.2;
  morph += snoise(p * (1.5 * u_noise_scale) - t * 0.05 + 10.0) * 0.08;
  morph += snoise(p * (3.0 * u_noise_scale) + t * 0.02) * 0.02;
  return length(p) - radius + morph * u_morph;
}

vec3 calcNormal(vec3 p, float t) {
  vec2 e = vec2(0.002, 0.0);
  return normalize(vec3(
    map(p+e.xyy, t) - map(p-e.xyy, t),
    map(p+e.yxy, t) - map(p-e.yxy, t),
    map(p+e.yyx, t) - map(p-e.yyx, t)
  ));
}

vec3 envLighting(vec3 rd, vec2 mouse) {
  vec3 col = u_bg * 0.35;
  vec3 keyDir = normalize(vec3(0.5 + mouse.x, 1.0 + mouse.y * 0.5, 1.2));
  float key = pow(max(dot(rd, keyDir), 0.0), 12.0);
  col += u_hi * key * 1.5;
  vec3 rimDir = normalize(vec3(-0.8, -0.2, -1.0));
  float rim = pow(max(dot(rd, rimDir), 0.0), 6.0);
  col += u_ink * rim * 1.4;
  vec3 fillDir = normalize(vec3(-1.0, 0.5, 0.5));
  float fill = pow(max(dot(rd, fillDir), 0.0), 3.0);
  col += mix(u_ink, u_bg, 0.5) * fill * 0.7;
  float panel = exp(-pow((rd.y - 0.2) * 4.0, 2.0)) * smoothstep(-0.5, 0.5, rd.z);
  col += u_bg * 0.25 * panel;
  return col;
}

void main() {
  vec2 uv = (gl_FragCoord.xy - u_res * 0.5) / min(u_res.x, u_res.y);
  float t = u_time * 0.8;
  vec2 m = u_mouse * u_mouse_amount;
  vec3 ro = vec3(0.0, 0.0, u_camera);
  vec3 lookAt = vec3(m.x, m.y, 0.0);
  vec3 fwd = normalize(lookAt - ro);
  vec3 right = normalize(cross(vec3(0.0, 1.0, 0.0), fwd));
  vec3 up = cross(fwd, right);
  vec3 rd = normalize(fwd + uv.x * right + uv.y * up);
  vec3 col = vec3(0.0);
  bool hit = false;
  float d = 0.0;
  for(int i=0; i<MAX_STEPS; i++) {
    vec3 p = ro + rd * d;
    float ds = map(p, t);
    d += ds;
    if(d > MAX_DIST || abs(ds) < SURF_DIST) break;
  }
  if(d < MAX_DIST) {
    hit = true;
    vec3 p = ro + rd * d;
    vec3 n = calcNormal(p, t);
    vec3 ref = reflect(rd, n);
    float fresnel = pow(1.0 - max(dot(n, -rd), 0.0), 4.0);
    fresnel = mix(0.4, 1.0, fresnel);
    vec3 env = envLighting(ref, u_mouse);
    col = env * fresnel * 1.8 * u_metal;
    vec3 lightPos = normalize(vec3(0.5 + u_mouse.x, 1.0, 1.0));
    float spec = pow(max(dot(ref, lightPos), 0.0), 60.0);
    col += vec3(1.0) * spec * 2.0 * u_metal;
    float disp = map(p, t) - (length(p) - 1.8);
    col *= mix(0.7, 1.0, smoothstep(-0.1, 0.1, disp));
  }
  col = col / (col + 0.5);
  col = pow(col, vec3(1.0/2.2));
  // The ground stays the page colour, with a soft halo of the ink around the form.
  float halo = exp(-length(uv) * 2.2);
  vec3 ground = mix(u_bg, u_ink, halo * 0.18);
  if (!hit) col = ground;
  gl_FragColor = vec4(col, 1.0);
}
`;

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create Mercury Bloom shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader) ?? "Mercury Bloom shader compilation failed");
  }
  return shader;
}

export function MercuryBloom({
  speed = 1,
  morph = 1.8,
  noiseScale = 1.3,
  mouseAmount = 0.15,
  metal = 1,
  camera = 6.5,
  tintHue = 220,
  tintAmount = 0,
  className,
}: MercuryBloomProps) {
  const themeVersion = useThemeVersion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const prefersReducedMotion = useReducedMotion();
  const optionsRef = useRef({ speed, morph, noiseScale, mouseAmount, metal, camera });
  optionsRef.current = { speed, morph, noiseScale, mouseAmount, metal, camera };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    const gl = canvas.getContext("webgl", {
      alpha: false,
      antialias: false,
      powerPreference: "high-performance",
    });
    if (!gl) return;

    const vertex = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const program = gl.createProgram();
    if (!program) return;
    gl.attachShader(program, vertex);
    gl.attachShader(program, fragment);
    gl.linkProgram(program);
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      throw new Error(gl.getProgramInfoLog(program) ?? "Mercury Bloom program link failed");
    }
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), gl.STATIC_DRAW);
    const position = gl.getAttribLocation(program, "a_pos");
    gl.enableVertexAttribArray(position);
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);

    const uniforms = {
      resolution: gl.getUniformLocation(program, "u_res"),
      time: gl.getUniformLocation(program, "u_time"),
      mouse: gl.getUniformLocation(program, "u_mouse"),
      morph: gl.getUniformLocation(program, "u_morph"),
      noiseScale: gl.getUniformLocation(program, "u_noise_scale"),
      mouseAmount: gl.getUniformLocation(program, "u_mouse_amount"),
      metal: gl.getUniformLocation(program, "u_metal"),
      camera: gl.getUniformLocation(program, "u_camera"),
    };
    const theme = readTheme();
    const [ph, ps, pl] = theme.primary;
    gl.uniform3fv(gl.getUniformLocation(program, "u_bg"), toRgb(theme.background));
    gl.uniform3fv(
      gl.getUniformLocation(program, "u_ink"),
      toRgb([ph, Math.max(ps, 40), theme.dark ? Math.max(pl, 55) : Math.min(Math.max(pl, 30), 45)]),
    );
    gl.uniform3fv(gl.getUniformLocation(program, "u_hi"), toRgb([ph + 25, 30, 94]));
    let targetX = 0;
    let targetY = 0;
    let mouseX = 0;
    let mouseY = 0;
    let frame = 0;
    let visible = true;
    const startedAt = performance.now();

    const draw = (elapsed: number) => {
      const options = optionsRef.current;
      mouseX += (targetX - mouseX) * 0.05;
      mouseY += (targetY - mouseY) * 0.05;
      gl.uniform2f(uniforms.resolution, canvas.width, canvas.height);
      gl.uniform1f(uniforms.time, elapsed * options.speed);
      gl.uniform2f(uniforms.mouse, mouseX, mouseY);
      gl.uniform1f(uniforms.morph, options.morph);
      gl.uniform1f(uniforms.noiseScale, options.noiseScale);
      gl.uniform1f(uniforms.mouseAmount, options.mouseAmount);
      gl.uniform1f(uniforms.metal, options.metal);
      gl.uniform1f(uniforms.camera, options.camera);
      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
    };

    const render = (now: number) => {
      draw((now - startedAt) * 0.001);
      frame = visible && !document.hidden ? requestAnimationFrame(render) : 0;
    };

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      const pixelRatio = Math.min(window.devicePixelRatio || 1, 1.5);
      canvas.width = Math.max(1, Math.round(bounds.width * pixelRatio));
      canvas.height = Math.max(1, Math.round(bounds.height * pixelRatio));
      gl.viewport(0, 0, canvas.width, canvas.height);
      if (prefersReducedMotion) draw(6);
    };

    const pointer = (event: PointerEvent) => {
      const bounds = canvas.getBoundingClientRect();
      if (
        event.clientX < bounds.left ||
        event.clientX > bounds.right ||
        event.clientY < bounds.top ||
        event.clientY > bounds.bottom
      ) {
        return;
      }
      targetX = ((event.clientX - bounds.left) / Math.max(1, bounds.width)) * 2 - 1;
      targetY = -(((event.clientY - bounds.top) / Math.max(1, bounds.height)) * 2 - 1);
    };

    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    resize();

    let intersection: IntersectionObserver | undefined;
    if (!prefersReducedMotion) {
      intersection = new IntersectionObserver(([entry]) => {
        visible = entry?.isIntersecting ?? true;
        if (visible && !frame) frame = requestAnimationFrame(render);
        if (!visible && frame) {
          cancelAnimationFrame(frame);
          frame = 0;
        }
      });
      intersection.observe(host);
      window.addEventListener("pointermove", pointer, { passive: true });
      frame = requestAnimationFrame(render);
    }

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection?.disconnect();
      window.removeEventListener("pointermove", pointer);
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
      gl.deleteProgram(program);
    };
  }, [prefersReducedMotion, themeVersion]);

  const tintFilter =
    tintAmount > 0
      ? `sepia(${tintAmount}) saturate(${1 + tintAmount * 5}) hue-rotate(${tintHue - 35}deg)`
      : undefined;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 isolate overflow-hidden bg-background", className)}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full"
        style={{ filter: tintFilter }}
      />
    </div>
  );
}
```

---

# Lumen Core

> A slowly turning sphere of smoke-veined light in a field of drifting motes, shaded from your theme.

Install: `npx @modus-ui/cli add lumen-core`

A WebGL sphere set right of centre, veined with rotating fbm smoke and ringed by a soft halo, over a canvas of drifting motes. Its shading is a lightness ramp on the theme's primary hue: a glowing core on a dark background, an inked one on paper, following the palette picker. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add lumen-core
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/lumen-core.tsx`.
3. Paste the code.

## Usage

```tsx
import { LumenCore } from "@/components/ui/lumen-core";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <LumenCore />
      <div className="relative z-10 p-8 text-white">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                               |
| :---------------- | :------- | :------------------------- | :---------------------------------------- |
| `speed`           | `number` | `1`                        | Rotation speed multiplier.                |
| `scale`           | `number` | `1`                        | Scale of the core canvas.                 |
| `smokeScale`      | `number` | `1`                        | Size of the smoke detail.                 |
| `smokeStrength`   | `number` | `1`                        | Brightness of the smoke veil.             |
| `smokeSpeed`      | `number` | `1`                        | Speed of the smoke flow.                  |
| `hue`             | `number` | `0`                        | Hue rotation in degrees (core and motes). |
| `saturation`      | `number` | `1`                        | Orb colour saturation.                    |
| `glow`            | `number` | `1`                        | Strength of the rim and outer glow.       |
| `starDensity`     | `number` | `1`                        | Star count multiplier.                    |
| `starSpeed`       | `number` | `1`                        | Star drift speed.                         |
| `starSize`        | `number` | `1`                        | Star size multiplier.                     |
| `brightness`      | `number` | `1`                        | CSS brightness filter on the core.        |
| `opacity`         | `number` | `1`                        | Orb opacity.                              |
| `backgroundColor` | `string` | `"hsl(var(--background))"` | Colour behind the core.                   |

## Source

`components/ui/lumen-core.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Energy Orb (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface LumenCoreProps {
  speed?: number;
  scale?: number;
  smokeScale?: number;
  smokeStrength?: number;
  smokeSpeed?: number;
  hue?: number;
  saturation?: number;
  glow?: number;
  starDensity?: number;
  starSpeed?: number;
  starSize?: number;
  brightness?: number;
  opacity?: number;
  /** Colour behind the core; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** HSL channels to linear-free 0..1 RGB for shader uniforms. */
function rgb([h, s, l]: Hsl) {
  const sat = Math.min(100, Math.max(0, s)) / 100;
  const light = Math.min(100, Math.max(0, l)) / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = sat * Math.min(light, 1 - light);
  const f = (n: number) => light - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
  return [f(0), f(8), f(4)];
}

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

type Star = { x: number; y: number; depth: number; phase: number; drift: number; size: number };

const VERTEX_SHADER = "attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}";

const FRAGMENT_SHADER = [
  "precision highp float;",
  "uniform float uT;uniform vec2 uR;",
  "uniform float uSmokeScale;uniform float uSmokeStrength;uniform float uSmokeSpeed;",
  "uniform float uHue;uniform float uSaturation;uniform float uGlow;",
  "uniform vec3 uDeep;uniform vec3 uMid;uniform vec3 uBright;uniform vec3 uRim;",
  "float hash(vec3 p){p=fract(p*0.3183099+vec3(0.1,0.2,0.3));p*=17.0;return fract(p.x*p.y*p.z*(p.x+p.y+p.z));}",
  "float noise(vec3 x){vec3 i=floor(x);vec3 f=fract(x);f=f*f*(3.0-2.0*f);",
  " return mix(mix(mix(hash(i),hash(i+vec3(1,0,0)),f.x),mix(hash(i+vec3(0,1,0)),hash(i+vec3(1,1,0)),f.x),f.y),",
  " mix(mix(hash(i+vec3(0,0,1)),hash(i+vec3(1,0,1)),f.x),mix(hash(i+vec3(0,1,1)),hash(i+vec3(1,1,1)),f.x),f.y),f.z);}",
  "float fbm(vec3 p){float v=0.0;float a=0.5;for(int i=0;i<5;i++){v+=a*noise(p);p=p*2.03+vec3(1.7);a*=0.5;}return v;}",
  "vec3 gradeColor(vec3 color){",
  " float luminance=dot(color,vec3(0.2126,0.7152,0.0722));",
  " color=mix(vec3(luminance),color,uSaturation);",
  " vec3 axis=normalize(vec3(1.0));",
  " return max(vec3(0.0),color*cos(uHue)+cross(axis,color)*sin(uHue)+axis*dot(axis,color)*(1.0-cos(uHue)));",
  "}",
  "void main(){",
  " vec2 uv=(gl_FragCoord.xy-vec2(0.6,0.46)*uR)/min(uR.x,uR.y);",
  " float r=length(uv);",
  " float R=0.24;",
  " vec3 col=vec3(0.0);float alpha=0.0;",
  " if(r<R){",
  "   float z=sqrt(R*R-r*r);",
  "   vec3 n=normalize(vec3(uv,z));",
  "   float ca=uT*0.15;",
  "   mat3 rot=mat3(cos(ca),0.,sin(ca),0.,1.,0.,-sin(ca),0.,cos(ca));",
  "   vec3 sp=rot*n;",
  "   float smokeTime=uT*uSmokeSpeed;",
  "   float f1=fbm(sp*(2.6*uSmokeScale)+vec3(0.0,smokeTime*0.12,0.0));",
  "   float f2=fbm(sp*(4.5*uSmokeScale)-vec3(smokeTime*0.08,0.0,smokeTime*0.05)+f1*1.8);",
  "   float veil=smoothstep(0.35,0.75,f2);",
  "   col=mix(uDeep,uMid,f1*1.2);",
  "   col=mix(col,uBright,clamp(veil*0.65*uSmokeStrength,0.0,1.0));",
  "   float fres=pow(1.0-z/R,2.2);",
  "   col=mix(col,uRim,clamp(fres*1.1*uGlow,0.0,1.0));",
  "   float top=pow(max(dot(n,normalize(vec3(0.0,0.7,0.7))),0.0),3.0);",
  "   col=mix(col,uBright,clamp(top*0.35*uGlow,0.0,1.0));",
  "   alpha=1.0;",
  " }",
  " float glow=exp(-(r-R)*14.0);",
  " if(r>=R){",
  "   glow=clamp(glow,0.0,1.0);",
  "   col=uRim;",
  "   alpha=clamp(glow*0.7*uGlow,0.0,1.0);",
  " } else {",
  "   float rim=smoothstep(R-0.03,R,r);",
  "   col=mix(col,uRim,clamp(rim*0.6*uGlow,0.0,1.0));",
  " }",
  " col=gradeColor(col);",
  " gl_FragColor=vec4(col,alpha);",
  "}",
].join("\n");

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create Lumen Core shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader) ?? "Lumen Core shader compilation failed");
  }
  return shader;
}

function seeded(index: number, salt: number) {
  return Math.abs(Math.sin(index * 91.173 + salt * 17.719) * 43758.5453) % 1;
}

function createStars(count: number): Star[] {
  return Array.from({ length: count }, (_, index) => ({
    x: seeded(index, 1),
    y: seeded(index, 2),
    depth: 0.25 + seeded(index, 3) * 0.75,
    phase: seeded(index, 4) * Math.PI * 2,
    drift: 0.35 + seeded(index, 5) * 0.65,
    size: 0.45 + seeded(index, 6) * 1.15,
  }));
}

function fract(value: number) {
  return value - Math.floor(value);
}

export function LumenCore({
  speed = 1,
  scale = 1,
  smokeScale = 1,
  smokeStrength = 1,
  smokeSpeed = 1,
  hue = 0,
  saturation = 1,
  glow = 1,
  starDensity = 1,
  starSpeed = 1,
  starSize = 1,
  brightness = 1,
  opacity = 1,
  backgroundColor = "hsl(var(--background))",
  className,
}: LumenCoreProps) {
  const hostRef = useRef<HTMLDivElement>(null);
  const starCanvasRef = useRef<HTMLCanvasElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const prefersReducedMotion = useReducedMotion();
  const theme = useThemeVersion();
  const optionsRef = useRef({
    speed,
    smokeScale,
    smokeStrength,
    smokeSpeed,
    hue,
    saturation,
    glow,
    starDensity,
    starSpeed,
    starSize,
  });
  optionsRef.current = {
    speed,
    smokeScale,
    smokeStrength,
    smokeSpeed,
    hue,
    saturation,
    glow,
    starDensity,
    starSpeed,
    starSize,
  };

  useEffect(() => {
    const host = hostRef.current;
    const starCanvas = starCanvasRef.current;
    const canvas = canvasRef.current;
    if (!host || !starCanvas || !canvas) return;

    // The core is shaded with a lightness ramp on the theme's primary hue.
    const { dark, primary } = readTheme();
    const [h, s] = primary;
    const sat = Math.max(s, 36);
    const ramp = dark
      ? {
          deep: rgb([h, sat, 7]),
          mid: rgb([h, sat, 30]),
          bright: rgb([h - 16, sat, 80]),
          rim: rgb([h, sat * 0.7, 86]),
        }
      : {
          deep: rgb([h, sat, 12]),
          mid: rgb([h, sat, 30]),
          bright: rgb([h - 16, sat, 66]),
          rim: rgb([h, sat, 46]),
        };

    const starContext = starCanvas.getContext("2d", { alpha: true });
    const gl = canvas.getContext("webgl", {
      alpha: true,
      premultipliedAlpha: false,
      antialias: true,
    });
    if (!starContext || !gl) return;

    const vertex = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragment = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const program = gl.createProgram();
    if (!program) {
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
      return;
    }
    gl.attachShader(program, vertex);
    gl.attachShader(program, fragment);
    gl.linkProgram(program);
    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
      throw new Error(gl.getProgramInfoLog(program) ?? "Lumen Core program link failed");
    }
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
    const position = gl.getAttribLocation(program, "p");
    gl.enableVertexAttribArray(position);
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);

    const uniforms = {
      time: gl.getUniformLocation(program, "uT"),
      resolution: gl.getUniformLocation(program, "uR"),
      smokeScale: gl.getUniformLocation(program, "uSmokeScale"),
      smokeStrength: gl.getUniformLocation(program, "uSmokeStrength"),
      smokeSpeed: gl.getUniformLocation(program, "uSmokeSpeed"),
      hue: gl.getUniformLocation(program, "uHue"),
      saturation: gl.getUniformLocation(program, "uSaturation"),
      glow: gl.getUniformLocation(program, "uGlow"),
      deep: gl.getUniformLocation(program, "uDeep"),
      mid: gl.getUniformLocation(program, "uMid"),
      bright: gl.getUniformLocation(program, "uBright"),
      rim: gl.getUniformLocation(program, "uRim"),
    };
    gl.enable(gl.BLEND);
    gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
    gl.clearColor(0, 0, 0, 0);

    const stars = createStars(180);
    let width = 1;
    let height = 1;
    let starDpr = 1;
    let frame = 0;
    let visible = true;
    const startedAt = performance.now();

    const drawStars = (elapsed: number) => {
      const options = optionsRef.current;
      starContext.setTransform(1, 0, 0, 1, 0, 0);
      starContext.clearRect(0, 0, starCanvas.width, starCanvas.height);
      const density = Math.max(0, options.starDensity);
      const count = Math.min(stars.length, Math.round(((width * height) / 4_200) * density));
      if (!count) return;

      starContext.setTransform(starDpr, 0, 0, starDpr, 0, 0);
      starContext.globalCompositeOperation = dark ? "screen" : "multiply";
      const particleTime = prefersReducedMotion ? 0 : elapsed * Math.max(0, options.starSpeed);
      const colorHue = fract((h + options.hue) / 360) * 360;
      for (let index = 0; index < count; index += 1) {
        const star = stars[index];
        const x = fract(star.x + particleTime * 0.0022 * star.drift) * width;
        const y = fract(star.y - particleTime * 0.0008 * star.depth + 1) * height;
        const twinkle = prefersReducedMotion
          ? 0.78
          : 0.58 + Math.sin(particleTime * (0.8 + star.depth) + star.phase) * 0.24;
        const alpha = Math.max(0.08, twinkle * (0.22 + star.depth * 0.48));
        const radius = Math.max(0.35, star.size * star.depth * Math.max(0.25, options.starSize));
        starContext.fillStyle = `hsla(${colorHue}, ${sat}%, ${dark ? 72 + star.depth * 20 : 40 - star.depth * 20}%, ${alpha})`;
        starContext.beginPath();
        starContext.arc(x, y, radius, 0, Math.PI * 2);
        starContext.fill();
      }
      starContext.globalCompositeOperation = "source-over";
    };

    const draw = (elapsed: number) => {
      const options = optionsRef.current;
      drawStars(elapsed);
      gl.uniform1f(uniforms.time, elapsed * options.speed);
      gl.uniform1f(uniforms.smokeScale, Math.max(0.01, options.smokeScale));
      gl.uniform1f(uniforms.smokeStrength, Math.max(0, options.smokeStrength));
      gl.uniform1f(uniforms.smokeSpeed, Math.max(0, options.smokeSpeed));
      gl.uniform1f(uniforms.hue, (options.hue * Math.PI) / 180);
      gl.uniform1f(uniforms.saturation, Math.max(0, options.saturation));
      gl.uniform1f(uniforms.glow, Math.max(0, options.glow));
      gl.uniform3fv(uniforms.deep, ramp.deep);
      gl.uniform3fv(uniforms.mid, ramp.mid);
      gl.uniform3fv(uniforms.bright, ramp.bright);
      gl.uniform3fv(uniforms.rim, ramp.rim);
      gl.clear(gl.COLOR_BUFFER_BIT);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    };

    const render = (now: number) => {
      frame = 0;
      draw((now - startedAt) * 0.001);
      if (visible && !document.hidden) frame = requestAnimationFrame(render);
    };

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      width = Math.max(1, bounds.width);
      height = Math.max(1, bounds.height);
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      const bufferWidth = Math.max(1, Math.round(width * dpr));
      const bufferHeight = Math.max(1, Math.round(height * dpr));
      if (canvas.width !== bufferWidth || canvas.height !== bufferHeight) {
        canvas.width = bufferWidth;
        canvas.height = bufferHeight;
      }
      gl.viewport(0, 0, bufferWidth, bufferHeight);
      gl.uniform2f(uniforms.resolution, bufferWidth, bufferHeight);

      starDpr = Math.min(window.devicePixelRatio || 1, 1.5);
      const starWidth = Math.max(1, Math.round(width * starDpr));
      const starHeight = Math.max(1, Math.round(height * starDpr));
      if (starCanvas.width !== starWidth || starCanvas.height !== starHeight) {
        starCanvas.width = starWidth;
        starCanvas.height = starHeight;
      }
      if (prefersReducedMotion) draw(4);
    };

    const start = () => {
      if (!frame && visible && !document.hidden) frame = requestAnimationFrame(render);
    };
    const stop = () => {
      if (frame) cancelAnimationFrame(frame);
      frame = 0;
    };
    const onVisibilityChange = () => {
      if (document.hidden) stop();
      else start();
    };

    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    resize();

    let intersection: IntersectionObserver | undefined;
    if (!prefersReducedMotion) {
      intersection = new IntersectionObserver(([entry]) => {
        visible = entry?.isIntersecting ?? true;
        if (visible) start();
        else stop();
      });
      intersection.observe(host);
      document.addEventListener("visibilitychange", onVisibilityChange);
      start();
    }

    return () => {
      stop();
      resizeObserver.disconnect();
      intersection?.disconnect();
      document.removeEventListener("visibilitychange", onVisibilityChange);
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
      gl.deleteProgram(program);
    };
  }, [prefersReducedMotion, theme]);

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("pointer-events-none absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor }}
    >
      <canvas ref={starCanvasRef} className="absolute inset-0 z-0 block h-full w-full" />
      <canvas
        ref={canvasRef}
        className="absolute inset-0 z-[1] block h-full w-full"
        style={{ opacity, filter: `brightness(${brightness})`, transform: `scale(${scale})` }}
      />
    </div>
  );
}
```

---

# Light Cut

> A WebGL shader of a beam of light cutting through fog, tinted from your theme, with five scenes.

Install: `npx @modus-ui/cli add light-cut`

A full-bleed WebGL shader of a beam of light through drifting fog that tilts toward the pointer, tinted from the palette's primary on the page ground. It opens on the prism aperture; switch to the matrix field, atmospheric blade, vanishing array or halftone relay. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add light-cut
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/light-cut.tsx`.
3. Paste the code.

## Usage

```tsx
import { LightCut } from "@/components/ui/light-cut";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <LightCut />
    </div>
  );
}
```

## Props

| Prop              | Type                                                                                                         | Default                  | Description                                   |
| :---------------- | :----------------------------------------------------------------------------------------------------------- | :----------------------- | :-------------------------------------------- |
| `variant`         | `"matrix-field"` \| `"atmospheric-blade"` \| `"vanishing-array"` \| `"prism-aperture"` \| `"halftone-relay"` | `"prism-aperture"`       | Which scene to draw.                          |
| `speed`           | `number`                                                                                                     | `1`                      | Animation speed (0 to 3).                     |
| `size`            | `number`                                                                                                     | `1`                      | Beam width (0.35 to 2.5).                     |
| `length`          | `number`                                                                                                     | `1`                      | Beam length (0.35 to 2.5).                    |
| `density`         | `number`                                                                                                     | `1`                      | Fog and detail density (0.25 to 2.5).         |
| `opacity`         | `number`                                                                                                     | `1`                      | Canvas opacity (0.05 to 1).                   |
| `hue`             | `number`                                                                                                     | `0`                      | Hue shift in degrees (-180 to 180).           |
| `saturation`      | `number`                                                                                                     | `1`                      | Colour saturation (0 to 2).                   |
| `brightness`      | `number`                                                                                                     | `1`                      | Brightness (0.35 to 1.65).                    |
| `backgroundColor` | `string`                                                                                                     | `hsl(var(--background))` | Background behind the canvas, any CSS colour. |

## Source

`components/ui/light-cut.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Laser (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export type LightCutVariant =
  "matrix-field" | "atmospheric-blade" | "vanishing-array" | "prism-aperture" | "halftone-relay";

export interface LightCutProps {
  variant?: LightCutVariant;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour behind the beams; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** HSL channels to sRGB 0–1 for shader uniforms. */
function toRgb([h, s, l]: Hsl): [number, number, number] {
  const sat = Math.min(100, Math.max(0, s)) / 100;
  const lig = Math.min(100, Math.max(0, l)) / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = sat * Math.min(lig, 1 - lig);
  const f = (n: number) => lig - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}

const VARIANT_INDEX: Record<Exclude<LightCutVariant, "matrix-field">, number> = {
  "atmospheric-blade": 0,
  "vanishing-array": 1,
  "prism-aperture": 2,
  "halftone-relay": 3,
};

const VERTEX_SHADER = `
attribute vec2 a_position;

void main() {
  gl_Position = vec4(a_position, 0.0, 1.0);
}
`;

const FRAGMENT_SHADER = `
precision highp float;

uniform vec2 u_resolution;
uniform vec2 u_pointer;
uniform float u_time;
uniform float u_variant;
uniform float u_size;
uniform float u_length;
uniform float u_density;
uniform float u_hue;
uniform float u_saturation;
uniform float u_brightness;

uniform vec3 u_bg;
uniform vec3 u_ink;
uniform vec3 u_hot;

// Maps emitted light onto the theme: ground -> ink -> hot core (ink on paper in light mode).
vec3 themed(vec3 light) {
  float lum = clamp(max(light.r, max(light.g, light.b)), 0.0, 1.0);
  vec3 tone = mix(u_ink, u_hot, smoothstep(0.55, 1.0, lum));
  return mix(u_bg, tone, smoothstep(0.02, 0.85, lum));
}

float hash21(vec2 p) {
  p = fract(p * vec2(123.34, 456.21));
  p += dot(p, p + 45.32);
  return fract(p.x * p.y);
}

float valueNoise(vec2 p) {
  vec2 i = floor(p);
  vec2 f = fract(p);
  vec2 u = f * f * (3.0 - 2.0 * f);
  return mix(
    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0)), u.x),
    u.y
  );
}

float fbm(vec2 p) {
  float result = 0.0;
  float weight = 0.54;
  for (int i = 0; i < 4; i++) {
    result += valueNoise(p) * weight;
    p = mat2(1.62, 1.21, -1.21, 1.62) * p + 9.13;
    weight *= 0.48;
  }
  return result;
}

vec3 hsv2rgb(vec3 c) {
  vec3 p = abs(fract(c.xxx + vec3(0.0, 0.6666667, 0.3333333)) * 6.0 - 3.0);
  return c.z * mix(vec3(1.0), clamp(p - 1.0, 0.0, 1.0), c.y);
}

vec3 accent(float baseHue, float saturationScale) {
  float hue = fract(baseHue + u_hue / 360.0);
  return hsv2rgb(vec3(hue, clamp(u_saturation * saturationScale, 0.0, 1.0), 1.0));
}

vec2 beamProfile(float distanceToLine, float coreWidth, float glowWidth) {
  float core = exp(-pow(distanceToLine / max(coreWidth, 0.0002), 2.0));
  float glow = exp(-pow(distanceToLine / max(glowWidth, 0.001), 1.25));
  return vec2(core, glow);
}

vec3 atmosphericBlade(vec2 p) {
  float drift = sin(u_time * 0.21) * 0.025;
  float center = u_pointer.x * 0.16 + drift;
  float tilt = u_pointer.x * 0.055 + sin(u_time * 0.13) * 0.018;
  float distanceToBeam = abs(p.x - center - p.y * tilt);
  float verticalMask = 1.0 - smoothstep(0.68 * u_length, 1.35 * u_length, abs(p.y));
  vec2 beam = beamProfile(distanceToBeam, 0.0028 * u_size, 0.052 * u_size);

  vec2 fogUv = vec2(p.x * 3.4, p.y * 2.15 - u_time * 0.075);
  fogUv.x += sin(p.y * 3.2 - u_time * 0.17) * 0.18;
  float fogNoise = fbm(fogUv + u_pointer * 0.35);
  float fogEnvelope = exp(-pow(distanceToBeam / (0.24 * u_size), 1.35));
  float fog = smoothstep(0.34, 0.78, fogNoise) * fogEnvelope * u_density * verticalMask;

  float mirageDistance = abs(abs(p.x - center + p.y * tilt * 0.35) - 0.105 * u_length);
  vec2 mirage = beamProfile(mirageDistance, 0.0011 * u_size, 0.016 * u_size);
  float mirageMask = (1.0 - smoothstep(0.08, 1.2, abs(p.y))) * (0.35 + 0.65 * fogNoise);

  vec3 tint = accent(0.43, 0.82);
  vec3 color = vec3(0.0025, 0.004, 0.006);
  color += tint * fog * 0.34;
  color += tint * beam.y * verticalMask * (0.48 + 0.06 * sin(u_time * 1.1));
  color += mix(tint, vec3(1.0), 0.88) * beam.x * verticalMask * 1.65;
  color += tint * mirage.y * mirageMask * 0.12 * u_density;
  color += vec3(0.8, 0.98, 0.9) * mirage.x * mirageMask * 0.35 * u_density;

  float contact = exp(-length(vec2((p.x - center) * 2.5, p.y + 0.77 * u_length)) * 7.0);
  color += tint * contact * 0.45;
  return color;
}

vec3 vanishingArray(vec2 p) {
  vec2 origin = vec2(u_pointer.x * 0.16, 0.12 + u_pointer.y * 0.075);
  vec2 q = p - origin;
  float radius = length(q);
  float angle = atan(q.y, q.x);
  float spokeCount = floor(11.0 + u_density * 10.0);
  float angularDistance = abs(sin(angle * spokeCount));
  float spoke = exp(-angularDistance * max(radius, 0.06) / (0.0075 * u_size));
  float reach = smoothstep(0.035, 0.16, radius) * (1.0 - smoothstep(0.42 * u_length, 1.55 * u_length, radius));
  float lowerField = 1.0 - smoothstep(-0.12, 0.22, q.y);
  float upperField = smoothstep(0.02, 0.52, q.y) * 0.48;
  float fieldMask = max(lowerField, upperField);

  float carrier = 0.55 + 0.45 * sin(radius * 16.0 - u_time * 4.1 + angle * 2.0);
  carrier = pow(max(carrier, 0.0), 7.0);
  float rail = spoke * reach * fieldMask;
  float railCore = pow(rail, 2.1);

  float ringPhase = abs(sin((radius * 13.0 - u_time * 1.5) / max(u_length, 0.35)));
  float rings = exp(-ringPhase / (0.035 * u_size)) * (1.0 - smoothstep(0.1, 1.2, radius)) * lowerField;
  float horizon = exp(-abs(q.y) / (0.0035 * u_size)) * (1.0 - smoothstep(0.12, 1.15, abs(q.x)));

  vec3 violet = accent(0.70, 0.78);
  vec3 amber = accent(0.055, 0.84);
  vec3 railTint = mix(violet, amber, 0.5 + 0.5 * sin(angle * 3.0));
  vec3 color = vec3(0.004, 0.0035, 0.009);
  color += railTint * rail * (0.24 + carrier * 0.72);
  color += mix(railTint, vec3(1.0), 0.9) * railCore * (0.52 + carrier * 0.92);
  color += violet * rings * 0.14 * u_density;
  color += vec3(0.82, 0.9, 1.0) * horizon * 0.38;
  color += violet * exp(-radius * 15.0) * 0.95;
  return color;
}

vec3 prismAperture(vec2 p) {
  vec2 center = u_pointer * vec2(0.12, 0.08);
  vec2 q = p - center;
  float breathing = 0.46 * u_length + sin(u_time * 0.72) * 0.012;
  float warp = (fbm(q * 3.2 + vec2(0.0, -u_time * 0.08)) - 0.5) * 0.025 * u_density;
  float diamond = abs(q.x * 0.82) + abs(q.y) - breathing - warp;
  float innerDiamond = abs(q.x * 0.82) + abs(q.y) - breathing * 0.66 + warp * 0.45;
  vec2 outer = beamProfile(abs(diamond), 0.0024 * u_size, 0.046 * u_size);
  vec2 inner = beamProfile(abs(innerDiamond), 0.0012 * u_size, 0.018 * u_size);

  float edgeMask = 1.0 - smoothstep(0.25, 1.18, length(q));
  float perimeterPhase = sin((q.x - q.y) * 15.0 - u_time * 3.3);
  float packets = pow(max(perimeterPhase, 0.0), 10.0) * outer.y;
  float axisX = exp(-abs(q.x) / (0.002 * u_size)) * (1.0 - smoothstep(0.04, breathing, abs(q.y)));
  float axisY = exp(-abs(q.y) / (0.002 * u_size)) * (1.0 - smoothstep(0.04, breathing, abs(q.x)));

  float redFringe = exp(-pow(abs(diamond - 0.011 * u_size) / (0.011 * u_size), 1.4));
  float blueFringe = exp(-pow(abs(diamond + 0.011 * u_size) / (0.011 * u_size), 1.4));
  vec3 tint = accent(0.79, 0.8);
  vec3 color = vec3(0.004, 0.0025, 0.007);
  color += tint * outer.y * edgeMask * 0.5;
  color += mix(tint, vec3(1.0), 0.9) * outer.x * edgeMask * 1.5;
  color += tint * inner.y * edgeMask * 0.18 * u_density;
  color += vec3(1.0) * inner.x * edgeMask * 0.48 * u_density;
  color += accent(0.98, 0.92) * redFringe * 0.13;
  color += accent(0.54, 0.9) * blueFringe * 0.16;
  color += vec3(0.92, 0.96, 1.0) * (axisX + axisY) * 0.2;
  color += tint * packets * 0.85;
  color += tint * exp(-length(q) * 9.0) * 0.22;
  return color;
}

vec3 halftoneRelay(vec2 p) {
  float center = 0.29 + u_pointer.x * 0.12;
  float bend = sin(p.y * 2.1 - u_time * 0.25) * 0.018;
  float mainDistance = abs(p.x - center - bend);
  float relayDistance = abs(p.x - center + 0.075 * u_length + bend * 0.45);
  vec2 mainBeam = beamProfile(mainDistance, 0.0022 * u_size, 0.072 * u_size);
  vec2 relayBeam = beamProfile(relayDistance, 0.0012 * u_size, 0.025 * u_size);

  vec2 fogUv = vec2(p.x * 3.0, p.y * 2.5 - u_time * 0.1);
  float fogNoise = fbm(fogUv + vec2(sin(u_time * 0.16), 0.0));
  float fog = smoothstep(0.28, 0.78, fogNoise) * exp(-mainDistance * 9.5 / u_size) * u_density;

  float dotScale = mix(9.0, 4.5, clamp((u_density - 0.25) / 2.25, 0.0, 1.0));
  vec2 dotCell = fract(gl_FragCoord.xy / dotScale) - 0.5;
  float dot = 1.0 - smoothstep(0.08, 0.34, length(dotCell));
  float dotMask = dot * smoothstep(0.08, 0.68, fog + mainBeam.y * 0.65);

  float pulse = pow(max(0.0, sin(p.y * 9.0 - u_time * 4.0)), 12.0);
  float horizontalRelay = exp(-abs(p.y + 0.34 - u_pointer.y * 0.08) / (0.0024 * u_size));
  horizontalRelay *= 1.0 - smoothstep(0.1, 1.05 * u_length, abs(p.x - center));

  vec3 tint = accent(0.54, 0.84);
  vec3 color = vec3(0.002, 0.005, 0.009);
  color += tint * fog * 0.24;
  color += tint * mainBeam.y * 0.54;
  color += mix(tint, vec3(1.0), 0.9) * mainBeam.x * 1.48;
  color += tint * relayBeam.y * 0.2;
  color += vec3(0.78, 0.95, 1.0) * relayBeam.x * 0.5;
  color += tint * dotMask * (0.3 + pulse * 0.42);
  color += mix(tint, vec3(1.0), 0.8) * horizontalRelay * (0.22 + pulse * 0.58);
  return color;
}

void main() {
  vec2 p = (gl_FragCoord.xy * 2.0 - u_resolution.xy) / min(u_resolution.x, u_resolution.y);
  vec3 color;

  if (u_variant < 0.5) {
    color = atmosphericBlade(p);
  } else if (u_variant < 1.5) {
    color = vanishingArray(p);
  } else if (u_variant < 2.5) {
    color = prismAperture(p);
  } else {
    color = halftoneRelay(p);
  }

  float vignette = 1.0 - smoothstep(0.24, 1.45, length(p * vec2(0.72, 0.88)));
  color *= 0.55 + vignette * 0.45;
  color *= u_brightness;
  color = color / (color + vec3(0.72));
  color = pow(max(color, vec3(0.0)), vec3(0.82));
  gl_FragColor = vec4(themed(color), 1.0);
}
`;

// Matrix Field (ThreeUI "Matrix Junction") keeps its original standalone shader.
const MATRIX_FIELD_SHADER = `
precision highp float;

uniform vec3 u_bg;
uniform vec3 u_ink;
uniform vec3 u_hot;

// Maps emitted light onto the theme: ground -> ink -> hot core (ink on paper in light mode).
vec3 themed(vec3 light) {
  float lum = clamp(max(light.r, max(light.g, light.b)), 0.0, 1.0);
  vec3 tone = mix(u_ink, u_hot, smoothstep(0.55, 1.0, lum));
  return mix(u_bg, tone, smoothstep(0.02, 0.85, lum));
}
uniform vec2 u_resolution;
uniform float u_time;
uniform vec2 u_mouse;
uniform float u_mouseActive;
uniform float u_intensity;

float hash(float n) { return fract(sin(n)*753.5453123); }
float noise(float x) {
    float i = floor(x);
    float f = fract(x);
    f = f*f*(3.0-2.0*f);
    return mix(hash(i), hash(i+1.0), f);
}

vec2 sdLine(vec2 p, vec2 a, vec2 b) {
    vec2 pa = p - a, ba = b - a;
    float h = clamp(dot(pa, ba) / dot(ba, ba), 0.0, 1.0);
    return vec2(length(pa - ba * h), h);
}

float lightning(vec2 uv, vec2 a, vec2 b, float t) {
    vec2 ab = b - a;
    float len = length(ab);
    if(len < 0.01) return 0.0;
    vec2 dir = ab / len;

    vec2 pa = uv - a;
    float h = clamp(dot(pa, dir) / len, 0.0, 1.0);
    float dist = length(pa - dir * (h * len));

    float env = sin(h * 3.1415);

    float offset = (noise(h * 25.0 - t * 35.0) - 0.5) * 0.08 * env;
    offset += (noise(h * 70.0 + t * 50.0) - 0.5) * 0.02 * env;

    float d = abs(dist + offset);

    return (0.0002 / (d + 0.0002) + 0.00001 / (d*d + 0.00001)) * env;
}

void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution.xy;
    uv = uv * 2.0 - 1.0;
    uv.x *= u_resolution.x / u_resolution.y;

    vec2 mouseUV = u_mouse / u_resolution.xy;
    mouseUV = mouseUV * 2.0 - 1.0;
    mouseUV.x *= u_resolution.x / u_resolution.y;

    vec2 center = vec2(-0.8, -0.2);
    center.x += sin(u_time * 0.4) * 0.03;
    center.y += cos(u_time * 0.3) * 0.03;

    vec2 dirUp = normalize(vec2(0.15, 1.0));
    vec2 dirRight = normalize(vec2(1.0, -0.25));
    vec2 dirDownLeft = normalize(vec2(-0.8, -0.6));

    vec2 l1 = sdLine(uv, center, center + dirUp * 5.0);
    vec2 l2 = sdLine(uv, center, center + dirRight * 5.0);
    vec2 l3 = sdLine(uv, center, center + dirDownLeft * 5.0);

    float intensity = u_intensity;
    float glow = intensity / (l1.x + 0.001) +
                 intensity / (l2.x + 0.001) +
                 (intensity * 0.4) / (l3.x + 0.001);

    float pulse1 = smoothstep(0.1, 0.0, abs(l1.y - fract(u_time * 0.4))) * 0.03 / (l1.x + 0.001);
    float pulse2 = smoothstep(0.1, 0.0, abs(l2.y - fract(u_time * 0.5 + 0.3))) * 0.03 / (l2.x + 0.001);
    float pulse3 = smoothstep(0.1, 0.0, abs(l3.y - fract(u_time * 0.3 + 0.7))) * 0.015 / (l3.x + 0.001);
    glow += pulse1 + pulse2 + pulse3;

    vec2 p1 = center + dirUp * clamp(dot(mouseUV - center, dirUp), 0.0, 5.0);
    vec2 p2 = center + dirRight * clamp(dot(mouseUV - center, dirRight), 0.0, 5.0);
    vec2 p3 = center + dirDownLeft * clamp(dot(mouseUV - center, dirDownLeft), 0.0, 5.0);

    float lgt1 = lightning(uv, p1, mouseUV, u_time);
    float lgt2 = lightning(uv, p2, mouseUV, u_time + 10.0);
    float lgt3 = lightning(uv, p3, mouseUV, u_time + 20.0);

    float flicker = step(0.1, noise(u_time * 60.0)) * (noise(u_time * 150.0) * 0.8 + 0.2);

    float d1 = length(mouseUV - p1);
    float d2 = length(mouseUV - p2);
    float d3 = length(mouseUV - p3);

    glow += lgt1 * smoothstep(2.0, 0.0, d1) * u_mouseActive * flicker;
    glow += lgt2 * smoothstep(2.0, 0.0, d2) * u_mouseActive * flicker;
    glow += lgt3 * smoothstep(2.0, 0.0, d3) * u_mouseActive * flicker;

    float distToCenter = length(uv - center);
    glow += 0.04 / (distToCenter + 0.01);

    vec3 baseColor = vec3(0.6, 0.75, 1.0);
    vec3 finalColor = baseColor * glow;

    finalColor *= 0.85 + 0.15 * sin(u_time * 2.0 - distToCenter * 8.0);

    float vignette = 1.0 - smoothstep(0.4, 2.0, length(uv));
    finalColor *= vignette;

    float n = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
    finalColor += n * 0.02;

    gl_FragColor = vec4(themed(finalColor), 1.0);
}
`;

function clamp(value: number, minimum: number, maximum: number) {
  return Math.min(maximum, Math.max(minimum, value));
}

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create Light Cut shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    const message = gl.getShaderInfoLog(shader) ?? "Light Cut shader compilation failed";
    gl.deleteShader(shader);
    throw new Error(message);
  }
  return shader;
}

export function LightCut({
  variant = "prism-aperture",
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
  className,
}: LightCutProps) {
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const redrawRef = useRef<() => void>(() => undefined);
  const prefersReducedMotion = useReducedMotion();
  const themeVersion = useThemeVersion();
  const optionsRef = useRef({ variant, speed, size, length, density, hue, saturation, brightness });
  optionsRef.current = { variant, speed, size, length, density, hue, saturation, brightness };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;

    const gl = canvas.getContext("webgl", {
      alpha: false,
      antialias: false,
      powerPreference: "high-performance",
      premultipliedAlpha: false,
    });
    if (!gl) return;

    const vertexShader = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragmentShader = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const matrixShader = compile(gl, gl.FRAGMENT_SHADER, MATRIX_FIELD_SHADER);
    const link = (fragment: WebGLShader) => {
      const linked = gl.createProgram();
      if (!linked) throw new Error("Unable to create Light Cut program");
      gl.attachShader(linked, vertexShader);
      gl.attachShader(linked, fragment);
      gl.bindAttribLocation(linked, 0, "a_position");
      gl.linkProgram(linked);
      if (!gl.getProgramParameter(linked, gl.LINK_STATUS)) {
        const message = gl.getProgramInfoLog(linked) ?? "Light Cut program link failed";
        gl.deleteProgram(linked);
        throw new Error(message);
      }
      return linked;
    };
    const program = link(fragmentShader);
    const matrixProgram = link(matrixShader);

    const theme = readTheme();
    const [ph, ps, pl] = theme.primary;
    const ground = toRgb(theme.background);
    const ink = toRgb([
      ph,
      Math.max(ps, 45),
      theme.dark ? Math.max(pl, 58) : Math.min(Math.max(pl, 32), 46),
    ]);
    const hot = theme.dark ? toRgb([ph + 20, 40, 94]) : toRgb(theme.foreground);
    for (const linked of [program, matrixProgram]) {
      gl.useProgram(linked);
      gl.uniform3fv(gl.getUniformLocation(linked, "u_bg"), ground);
      gl.uniform3fv(gl.getUniformLocation(linked, "u_ink"), ink);
      gl.uniform3fv(gl.getUniformLocation(linked, "u_hot"), hot);
    }

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(
      gl.ARRAY_BUFFER,
      new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
      gl.STATIC_DRAW,
    );
    gl.enableVertexAttribArray(0);
    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);

    const uniforms = {
      resolution: gl.getUniformLocation(program, "u_resolution"),
      pointer: gl.getUniformLocation(program, "u_pointer"),
      time: gl.getUniformLocation(program, "u_time"),
      variant: gl.getUniformLocation(program, "u_variant"),
      size: gl.getUniformLocation(program, "u_size"),
      length: gl.getUniformLocation(program, "u_length"),
      density: gl.getUniformLocation(program, "u_density"),
      hue: gl.getUniformLocation(program, "u_hue"),
      saturation: gl.getUniformLocation(program, "u_saturation"),
      brightness: gl.getUniformLocation(program, "u_brightness"),
    };

    const matrixUniforms = {
      resolution: gl.getUniformLocation(matrixProgram, "u_resolution"),
      time: gl.getUniformLocation(matrixProgram, "u_time"),
      mouse: gl.getUniformLocation(matrixProgram, "u_mouse"),
      mouseActive: gl.getUniformLocation(matrixProgram, "u_mouseActive"),
      intensity: gl.getUniformLocation(matrixProgram, "u_intensity"),
    };

    let frame = 0;
    let mouseX = -1000;
    let mouseY = -1000;
    let lastMouseMove = -Infinity;
    let mouseActive = 0;
    let visible = true;
    let targetX = 0;
    let targetY = 0;
    let pointerX = 0;
    let pointerY = 0;
    const startedAt = performance.now();

    const draw = (now: number) => {
      const options = optionsRef.current;
      const time = prefersReducedMotion
        ? 2.75
        : (now - startedAt) * 0.001 * clamp(options.speed, 0, 3);

      if (options.variant === "matrix-field") {
        const sinceMove = now - lastMouseMove;
        const targetActive = prefersReducedMotion
          ? 0
          : sinceMove < 150
            ? 1
            : Math.max(0, 1 - (sinceMove - 150) / 350);
        mouseActive += (targetActive - mouseActive) * 0.15;
        gl.useProgram(matrixProgram);
        gl.uniform2f(matrixUniforms.resolution, canvas.width, canvas.height);
        gl.uniform1f(matrixUniforms.time, time);
        gl.uniform2f(matrixUniforms.mouse, mouseX, mouseY);
        gl.uniform1f(matrixUniforms.mouseActive, mouseActive);
        gl.uniform1f(
          matrixUniforms.intensity,
          0.006 * clamp(options.size, 0.05, 200) * clamp(options.length, 0.35, 2.5),
        );
        gl.drawArrays(gl.TRIANGLES, 0, 6);
        return;
      }

      const index = VARIANT_INDEX[options.variant] ?? 0;
      pointerX += (targetX - pointerX) * (prefersReducedMotion ? 1 : 0.055);
      pointerY += (targetY - pointerY) * (prefersReducedMotion ? 1 : 0.055);

      gl.useProgram(program);
      gl.uniform2f(uniforms.resolution, canvas.width, canvas.height);
      gl.uniform2f(uniforms.pointer, pointerX, pointerY);
      gl.uniform1f(uniforms.time, time);
      gl.uniform1f(uniforms.variant, index);
      gl.uniform1f(uniforms.size, clamp(options.size, 0.35, 2.5));
      gl.uniform1f(uniforms.length, clamp(options.length, 0.35, 2.5));
      gl.uniform1f(uniforms.density, clamp(options.density, 0.25, 2.5));
      gl.uniform1f(uniforms.hue, clamp(options.hue, -180, 180));
      gl.uniform1f(uniforms.saturation, clamp(options.saturation, 0, 2));
      gl.uniform1f(uniforms.brightness, clamp(options.brightness, 0.35, 1.65));
      gl.drawArrays(gl.TRIANGLES, 0, 6);
    };

    const render = (now: number) => {
      frame = 0;
      draw(now);
      if (!prefersReducedMotion && visible && !document.hidden) {
        frame = requestAnimationFrame(render);
      }
    };

    const sync = () => {
      if (prefersReducedMotion || !visible || document.hidden) {
        if (frame) cancelAnimationFrame(frame);
        frame = 0;
        draw(performance.now());
        return;
      }
      if (!frame) frame = requestAnimationFrame(render);
    };
    redrawRef.current = () => draw(performance.now());

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      const pixelRatio = Math.min(window.devicePixelRatio || 1, 1.5);
      canvas.width = Math.max(1, Math.round(bounds.width * pixelRatio));
      canvas.height = Math.max(1, Math.round(bounds.height * pixelRatio));
      gl.viewport(0, 0, canvas.width, canvas.height);
      draw(performance.now());
    };

    // Listen on window so content layered above the background does not block the beam.
    const handlePointerMove = (event: PointerEvent) => {
      const bounds = host.getBoundingClientRect();
      const inside =
        event.clientX >= bounds.left &&
        event.clientX <= bounds.right &&
        event.clientY >= bounds.top &&
        event.clientY <= bounds.bottom;
      if (inside) {
        const pixelRatio = canvas.width / Math.max(1, bounds.width);
        mouseX = (event.clientX - bounds.left) * pixelRatio;
        mouseY = (bounds.bottom - event.clientY) * pixelRatio;
        lastMouseMove = performance.now();
        targetX = ((event.clientX - bounds.left) / Math.max(1, bounds.width)) * 2 - 1;
        targetY = -(((event.clientY - bounds.top) / Math.max(1, bounds.height)) * 2 - 1);
      } else {
        targetX = 0;
        targetY = 0;
      }
      if (prefersReducedMotion) draw(performance.now());
    };
    const handlePointerLeave = () => {
      targetX = 0;
      targetY = 0;
      if (prefersReducedMotion) draw(performance.now());
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      sync();
    });
    resizeObserver.observe(host);
    intersection.observe(host);
    window.addEventListener("pointermove", handlePointerMove, { passive: true });
    document.documentElement.addEventListener("pointerleave", handlePointerLeave);
    document.addEventListener("visibilitychange", sync);
    resize();
    sync();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      window.removeEventListener("pointermove", handlePointerMove);
      document.documentElement.removeEventListener("pointerleave", handlePointerLeave);
      document.removeEventListener("visibilitychange", sync);
      redrawRef.current = () => undefined;
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertexShader);
      gl.deleteShader(fragmentShader);
      gl.deleteShader(matrixShader);
      gl.deleteProgram(program);
      gl.deleteProgram(matrixProgram);
    };
  }, [prefersReducedMotion, themeVersion]);

  useEffect(() => {
    redrawRef.current();
  }, [variant, speed, size, length, density, hue, saturation, brightness]);

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="pointer-events-none absolute inset-0 block h-full w-full"
        style={{
          opacity: clamp(opacity, 0.05, 1),
          // ThreeUI tints Matrix Field with a CSS filter instead of in the shader.
          filter:
            variant === "matrix-field" && (hue !== 0 || saturation !== 1 || brightness !== 1)
              ? `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`
              : undefined,
        }}
      />
    </div>
  );
}
```

---

# Stipple Tide

> A WebGL stipple of theme-coloured dots that swell in slow rings from the centre and drift with the pointer.

Install: `npx @modus-ui/cli add stipple-tide`

A full-bleed Three.js stipple that sits on the page's own background: dots rest in the muted ink colour and swell into the primary colour as slow rings travel outward from the centre, fading toward the edges. It follows the active palette and light or dark mode, and shifting slightly as the pointer moves anywhere over the page. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add stipple-tide
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/stipple-tide.tsx`.
4. Paste the code.

## Usage

```tsx
import { StippleTide } from "@/components/ui/stipple-tide";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <StippleTide />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default        | Description                                                 |
| :---------------- | :------- | :------------- | :---------------------------------------------------------- |
| `speed`           | `number` | `1`            | Animation speed multiplier.                                 |
| `gridScale`       | `number` | `36`           | Number of dot cells across the height.                      |
| `mouseAmount`     | `number` | `0.03`         | How far the grid shifts with the pointer.                   |
| `pulseSpeed`      | `number` | `0.25`         | Rings per second travelling outward.                        |
| `radius`          | `number` | `0.26`         | Extra dot radius at the peak of a pulse.                    |
| `opacity`         | `number` | `0.9`          | Overall opacity of the dots.                                |
| `hue`             | `number` | `0`            | Hue rotation in degrees.                                    |
| `color`           | `string` | `--primary`    | Dot colour at the crest of a ring (theme token by default). |
| `backgroundColor` | `string` | `--background` | Background behind the dots (theme token by default).        |

## Source

`components/ui/stipple-tide.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Dot Matrix (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

export interface StippleTideProps {
  speed?: number;
  gridScale?: number;
  mouseAmount?: number;
  pulseSpeed?: number;
  radius?: number;
  opacity?: number;
  hue?: number;
  /** Dot colour at the crest of a ripple. Defaults to the theme's `--primary`. */
  color?: string;
  /** Background behind the dots. Defaults to the theme's `--background`. */
  backgroundColor?: string;
  className?: string;
}

const VERTEX_SHADER = `
varying vec2 vUv;
void main() {
  vUv = uv;
  gl_Position = vec4(position, 1.0);
}
`;

const FRAGMENT_SHADER = `
uniform float uTime;
uniform vec2 uResolution;
uniform vec2 uMouse;
uniform float uGridScale;
uniform float uMouseAmount;
uniform float uPulseSpeed;
uniform float uRadius;
uniform float uOpacity;
uniform vec3 uColor;
uniform vec3 uBase;
varying vec2 vUv;
void main() {
  vec2 uv = gl_FragCoord.xy / uResolution.xy;
  float aspect = uResolution.x / uResolution.y;
  uv.x *= aspect;
  uv += uMouse * uMouseAmount;
  vec2 grid = fract(uv * uGridScale);
  vec2 id = floor(uv * uGridScale);
  float dist = length(grid - vec2(0.5));
  vec2 center = vec2(0.5 * aspect, 0.5);
  float ring = length(id - center * uGridScale);
  float pulse = sin(uTime * uPulseSpeed * 6.2831 - ring * 0.32) * 0.5 + 0.5;
  pulse = pow(pulse, 2.2);
  float radius = 0.06 + pulse * uRadius;
  float alpha = smoothstep(radius, radius - 0.05, dist);
  float depthFade = smoothstep(1.05, 0.05, length(uv - center));
  vec3 color = mix(uBase, uColor, pulse);
  gl_FragColor = vec4(color, alpha * mix(0.35, 1.0, pulse) * depthFade * uOpacity);
}
`;

export function StippleTide({
  speed = 1,
  gridScale = 36,
  mouseAmount = 0.03,
  pulseSpeed = 0.25,
  radius = 0.26,
  opacity = 0.9,
  hue = 0,
  color,
  backgroundColor,
  className,
}: StippleTideProps) {
  const prefersReducedMotion = useReducedMotion();
  const tokens = useTokens();
  const ink = color ?? tokens?.primary ?? "currentColor";
  const base = tokens?.muted ?? ink;
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({ speed, gridScale, mouseAmount, pulseSpeed, radius, opacity, ink, base });
  options.current = { speed, gridScale, mouseAmount, pulseSpeed, radius, opacity, ink, base };
  const redraw = useRef<() => void>(() => {});

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;

    const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;
    const uniforms = {
      uTime: { value: 0 },
      uResolution: { value: new THREE.Vector2() },
      uMouse: { value: new THREE.Vector2() },
      uGridScale: { value: 60 },
      uMouseAmount: { value: 0.04 },
      uPulseSpeed: { value: 0.4 },
      uRadius: { value: 0.15 },
      uOpacity: { value: 0.35 },
      uColor: { value: new THREE.Color() },
      uBase: { value: new THREE.Color() },
    };
    const geometry = new THREE.PlaneGeometry(2, 2);
    const material = new THREE.ShaderMaterial({
      uniforms,
      vertexShader: VERTEX_SHADER,
      fragmentShader: FRAGMENT_SHADER,
      transparent: true,
      depthWrite: false,
    });
    scene.add(new THREE.Mesh(geometry, material));

    const mouse = new THREE.Vector2();
    const target = new THREE.Vector2();
    const startedAt = performance.now();
    let frame = 0;
    let visible = true;

    // Listen on window so overlaid content does not block the pointer drift.
    const onPointer = (event: PointerEvent) => {
      const bounds = canvas.getBoundingClientRect();
      target.x = ((event.clientX - bounds.left) / Math.max(1, bounds.width)) * 2 - 1;
      target.y = -(((event.clientY - bounds.top) / Math.max(1, bounds.height)) * 2 - 1);
    };
    const draw = (now: number) => {
      const o = options.current;
      mouse.lerp(target, 0.05);
      uniforms.uTime.value = (now - startedAt) * 0.001 * o.speed;
      uniforms.uMouse.value = mouse;
      uniforms.uGridScale.value = o.gridScale;
      uniforms.uMouseAmount.value = o.mouseAmount;
      uniforms.uPulseSpeed.value = o.pulseSpeed;
      uniforms.uRadius.value = o.radius;
      uniforms.uOpacity.value = o.opacity;
      if (o.ink !== "currentColor") {
        uniforms.uColor.value.setStyle(o.ink, THREE.LinearSRGBColorSpace);
        uniforms.uBase.value.setStyle(o.base, THREE.LinearSRGBColorSpace);
      }
      renderer.render(scene, camera);
    };
    const tick = (now: number) => {
      draw(now);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !frame) frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      const { width, height } = host.getBoundingClientRect();
      renderer.setSize(width, height, false);
      uniforms.uResolution.value.set(width, height);
      if (prefersReducedMotion) draw(startedAt);
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    redraw.current = () => {
      if (prefersReducedMotion) draw(startedAt);
    };
    resizeObserver.observe(host);
    intersection.observe(host);
    if (!prefersReducedMotion) window.addEventListener("pointermove", onPointer, { passive: true });
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      window.removeEventListener("pointermove", onPointer);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
    };
  }, [prefersReducedMotion]);

  // A still frame has to be repainted when the theme changes under it.
  useEffect(() => {
    redraw.current();
  }, [ink, base]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ filter: `hue-rotate(${hue}deg)` }}
      />
    </div>
  );
}
```

---

# Tide Line

> A slow band of ink-toned light rolling along the top edge, tinted from your theme.

Install: `npx @modus-ui/cli add tide-line`

A full-bleed Three.js shader of a soft band of light that hangs from the top edge and rolls in slow waves. Its two inks are derived from the theme's primary hue, so it sits on paper in light mode and glows on the dark background in dark mode, following the palette picker. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add tide-line
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/tide-line.tsx`.
4. Paste the code.

## Usage

```tsx
import { TideLine } from "@/components/ui/tide-line";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <TideLine />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type               | Default            | Description                                             |
| :---------------- | :----------------- | :----------------- | :------------------------------------------------------ |
| `speed`           | `number`           | `1`                | Animation speed multiplier.                             |
| `waveScale`       | `number`           | `1`                | Height of the horizon waves.                            |
| `variation`       | `number`           | `1`                | Strength of the brightness variation along the horizon. |
| `glow`            | `number`           | `1`                | Glow intensity.                                         |
| `vignette`        | `number`           | `1`                | Vignette strength, from 0 (off) to 1.                   |
| `hue`             | `number`           | `0`                | Hue rotation in degrees.                                |
| `colors`          | `[string, string]` | theme primary ramp | The two glow colours blended across the band.           |
| `backgroundColor` | `string`           | theme background   | Colour of the ground behind the glow.                   |

## Source

`components/ui/tide-line.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Emerald Horizon (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

interface TideLineProps {
  speed?: number;
  waveScale?: number;
  variation?: number;
  glow?: number;
  vignette?: number;
  hue?: number;
  /** Two glow colours; defaults to a ramp derived from the theme's primary hue. */
  colors?: [string, string];
  /** Colour behind the glow; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

const VERTEX_SHADER = `
varying vec2 vUv;
void main() {
  vUv = uv;
  gl_Position = vec4(position, 1.0);
}
`;

const FRAGMENT_SHADER = `
uniform float u_time;
uniform vec2 u_resolution;
uniform float u_wave_scale;
uniform float u_variation;
uniform float u_glow;
uniform float u_vignette;
uniform vec3 u_base;
uniform vec3 u_glow1;
uniform vec3 u_glow2;
varying vec2 vUv;
float hash(float n) { return fract(sin(n) * 1e4); }
float noise(float x) {
  float i = floor(x);
  float f = fract(x);
  float u = f * f * (3.0 - 2.0 * f);
  return mix(hash(i), hash(i + 1.0), u);
}
void main() {
  vec2 st = gl_FragCoord.xy / u_resolution.xy;
  float yPos = 1.0 - st.y;
  float wave1 = sin(st.x * 3.0 + u_time * 0.5) * 0.1 * u_wave_scale;
  float wave2 = sin(st.x * 5.0 - u_time * 0.3) * 0.05 * u_wave_scale;
  float combinedWave = wave1 + wave2;
  float intensity = smoothstep(0.4, -0.1, yPos + combinedWave);
  float variation = noise(st.x * 2.0 + u_time * 0.1) * 0.5 + 0.5;
  intensity *= variation * 1.5 * u_variation;
  vec3 finalGlow = mix(u_glow1, u_glow2, clamp(st.x + sin(u_time*0.2)*0.5, 0.0, 1.0));
  // Ink mixed onto the ground, so it reads on paper as well as on a dark stage.
  vec3 color = mix(u_base, finalGlow, clamp(pow(intensity, 1.5) * 1.2 * u_glow, 0.0, 1.0));
  float vignette = mix(1.0, smoothstep(1.2, 0.5, length(st - vec2(0.5, 1.0))), u_vignette);
  color = mix(u_base, color, vignette);
  gl_FragColor = vec4(color, 1.0);
}
`;

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** Two inks on the primary hue, spread apart for a little colour movement. */
function themeGlow(): [string, string] {
  const { dark, primary } = readTheme();
  const [h, s] = primary;
  const sat = Math.max(s, 38);
  return dark
    ? [hsl([h, sat, 58]), hsl([h - 22, sat + 10, 72])]
    : [hsl([h, sat, 30]), hsl([h - 22, sat + 6, 44])];
}

export function TideLine({
  speed = 1,
  waveScale = 1,
  variation = 1,
  glow = 1,
  vignette = 1,
  hue = 0,
  colors,
  backgroundColor,
  className,
}: TideLineProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const theme = useThemeVersion();
  const options = useRef({ speed, waveScale, variation, glow, vignette });
  options.current = { speed, waveScale, variation, glow, vignette };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
    const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    const uniforms = {
      u_time: { value: 0 },
      u_resolution: { value: new THREE.Vector2(1, 1) },
      u_wave_scale: { value: 1 },
      u_variation: { value: 1 },
      u_glow: { value: 1 },
      u_vignette: { value: 1 },
      u_base: { value: new THREE.Color() },
      u_glow1: { value: new THREE.Color() },
      u_glow2: { value: new THREE.Color() },
    };
    const material = new THREE.ShaderMaterial({
      vertexShader: VERTEX_SHADER,
      fragmentShader: FRAGMENT_SHADER,
      uniforms,
      depthWrite: false,
      depthTest: false,
    });
    const geometry = new THREE.PlaneGeometry(2, 2);
    scene.add(new THREE.Mesh(geometry, material));

    const glowColors = colors ?? themeGlow();
    const base = backgroundColor ?? hsl(readTheme().background);
    const startedAt = performance.now();
    let frame = 0;
    let visible = true;
    const draw = (now: number) => {
      const o = options.current;
      uniforms.u_time.value = (now - startedAt) * 0.001 * o.speed;
      uniforms.u_wave_scale.value = o.waveScale;
      uniforms.u_variation.value = o.variation;
      uniforms.u_glow.value = o.glow;
      uniforms.u_vignette.value = o.vignette;
      // Colours go straight into the shader as sRGB values.
      uniforms.u_base.value.setStyle(base, THREE.LinearSRGBColorSpace);
      uniforms.u_glow1.value.setStyle(glowColors[0], THREE.LinearSRGBColorSpace);
      uniforms.u_glow2.value.setStyle(glowColors[1], THREE.LinearSRGBColorSpace);
      renderer.render(scene, camera);
    };
    const tick = (now: number) => {
      draw(now);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !frame) frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      const { width, height } = host.getBoundingClientRect();
      renderer.setSize(width, height, false);
      uniforms.u_resolution.value.set(width, height);
      if (prefersReducedMotion) draw(startedAt);
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [prefersReducedMotion, theme, colors?.[0], colors?.[1], backgroundColor]);

  return (
    <div className={cn("absolute inset-0 isolate overflow-hidden", className)} ref={hostRef}>
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ filter: `hue-rotate(${hue}deg)` }}
      />
    </div>
  );
}
```

---

# Lattice Drift

> A WebGL dome of ink points turning slowly under a fading mask, with scattered accent points in the theme primary.

Install: `npx @modus-ui/cli add lattice-drift`

A WebGL dome of ink points turning slowly under a fading mask, with scattered accent points in the theme primary. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add lattice-drift
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/lattice-drift.tsx`.
3. Paste the code.

## Usage

```tsx
import { LatticeDrift } from "@/components/ui/lattice-drift";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <LatticeDrift />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default          | Description                                                |
| :---------------- | :------- | :--------------- | :--------------------------------------------------------- |
| `speed`           | `number` | `0.7`            | Rotation speed multiplier.                                 |
| `pointSize`       | `number` | `0.11`           | Size of each point.                                        |
| `opacity`         | `number` | `0.75`           | Opacity of the points.                                     |
| `maskStart`       | `number` | `0.05`           | Fraction of the height where the fade mask begins.         |
| `maskSolid`       | `number` | `0.35`           | Fraction of the height where the points are fully visible. |
| `color`           | `string` | theme foreground | Colour of most points.                                     |
| `accentColor`     | `string` | theme primary    | Colour of the scattered accent points.                     |
| `backgroundColor` | `string` | theme background | Background behind the points.                              |

## Source

`components/ui/lattice-drift.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Structure Flow (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

interface LatticeDriftProps {
  speed?: number;
  pointSize?: number;
  opacity?: number;
  maskStart?: number;
  maskSolid?: number;
  /** Colour of most points. Defaults to the theme foreground. */
  color?: string;
  /** Colour of the scattered accent points. Defaults to the theme primary. */
  accentColor?: string;
  /** Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];

export function LatticeDrift({
  speed = 0.7,
  pointSize = 0.11,
  opacity = 0.75,
  maskStart = 0.05,
  maskSolid = 0.35,
  color,
  accentColor,
  backgroundColor,
  className,
}: LatticeDriftProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({ speed, pointSize, opacity });
  options.current = { speed, pointSize, opacity };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas || !theme) return;

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(60, 1, 0.1, 1000);
    // Looking down onto the dome's crown rather than across its rim.
    camera.position.set(0, 14, 24);
    camera.lookAt(0, -2, 0);
    const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    // The original ran on three r128 (no colour management): colours reach the screen untouched.
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    const ink = color ? toRgb(color) : theme.foreground;
    const accent = accentColor ? toRgb(accentColor) : theme.primary;
    const geometry = new THREE.BufferGeometry();
    const count = 15000;
    const positions = new Float32Array(count * 3);
    const tints = new Float32Array(count * 3);
    const radius = 25;
    for (let index = 0; index < count; index += 1) {
      const u = Math.random();
      Math.random(); // The original sampled an unused v here.
      const theta = u * 2 * Math.PI;
      const phi = Math.acos(Math.random() * 0.8 + 0.2);
      positions[index * 3] = radius * Math.sin(phi) * Math.cos(theta);
      positions[index * 3 + 1] = radius * Math.cos(phi) - 20;
      positions[index * 3 + 2] = radius * Math.sin(phi) * Math.sin(theta);
      // Points ink in the foreground, with a seeded scatter of accent points.
      tints.set(
        Math.random() < 0.14 ? accent : mix(ink, theme["muted-foreground"], Math.random() * 0.5),
        index * 3,
      );
    }
    geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
    geometry.setAttribute("color", new THREE.BufferAttribute(tints, 3));
    const material = new THREE.PointsMaterial({
      size: 0.08,
      vertexColors: true,
      transparent: true,
      opacity: 0.4,
      depthWrite: false,
    });
    const particles = new THREE.Points(geometry, material);
    scene.add(particles);

    const render = (advance: boolean) => {
      const o = options.current;
      if (advance) {
        particles.rotation.y += 0.0008 * o.speed;
        particles.rotation.z += 0.0002 * o.speed;
      }
      material.size = o.pointSize;
      material.opacity = o.opacity;
      renderer.render(scene, camera);
    };
    const resize = () => {
      const { width, height } = host.getBoundingClientRect();
      camera.aspect = width / Math.max(1, height);
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);
      render(false);
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      render(true);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !frame) frame = requestAnimationFrame(tick);
    };
    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
    };
  }, [prefersReducedMotion, theme, color, accentColor]);

  const mask = `linear-gradient(to bottom, transparent ${maskStart * 100}%, black ${maskSolid * 100}%, black 100%)`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ WebkitMaskImage: mask, maskImage: mask }}
      />
    </div>
  );
}
```

---

# Star Tunnel

> A WebGL flight down a corridor of letters, streaks, keycaps or rings, coloured from a ramp of the theme primary and foreground.

Install: `npx @modus-ui/cli add star-tunnel`

A WebGL flight down a corridor of letters, streaks, keycaps or rings, coloured from a ramp of the theme primary and foreground. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add star-tunnel
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/star-tunnel.tsx`.
3. Paste the code.

## Usage

```tsx
import { StarTunnel } from "@/components/ui/star-tunnel";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <StarTunnel />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type                                                  | Default                              | Description                                       |
| :---------------- | :---------------------------------------------------- | :----------------------------------- | :------------------------------------------------ |
| `variant`         | `"streaks" \| "letters" \| "keycaps" \| "hyperspace"` | `"letters"`                          | Which corridor to fly through.                    |
| `speed`           | `number`                                              | `12`                                 | Distance travelled per frame.                     |
| `streakOpacity`   | `number`                                              | `0.6`                                | Opacity of the streaks (and keycap sparks).       |
| `tileOpacity`     | `number`                                              | `0.9`                                | Opacity of the tiles, letters, keycaps or tunnel. |
| `fov`             | `number`                                              | `62`                                 | Camera field of view in degrees.                  |
| `brightness`      | `number`                                              | `1`                                  | CSS brightness filter.                            |
| `hue`             | `number`                                              | `0`                                  | Hue rotation in degrees.                          |
| `saturation`      | `number`                                              | `1`                                  | CSS saturation filter.                            |
| `colors`          | `string[]`                                            | ramp of theme primary and foreground | Streak colours.                                   |
| `backgroundColor` | `string`                                              | theme background                     | Scene and fog colour.                             |

## Source

`components/ui/star-tunnel.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Warp Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

type StarTunnelVariant = "streaks" | "letters" | "keycaps" | "hyperspace";

interface StarTunnelProps {
  variant?: StarTunnelVariant;
  speed?: number;
  streakOpacity?: number;
  tileOpacity?: number;
  fov?: number;
  brightness?: number;
  hue?: number;
  saturation?: number;
  /** CSS colours for the streaks. Default to a ramp of the theme primary and foreground. */
  colors?: string[];
  /** Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];
const css = (c: Rgb, alpha = 1) => `rgb(${c.map((v) => Math.round(v * 255)).join(" ")} / ${alpha})`;

// Output is linear (no colour management), so sRGB channels reach the screen untouched.
const color3 = (c: Rgb) => new THREE.Color(c[0], c[1], c[2]);

/** The scene's colours, all derived from the Modus theme tokens. */
type Inks = { ink: Rgb; accent: Rgb; soft: Rgb; ground: Rgb; card: Rgb; border: Rgb; font: string };

const RECYCLE_Z = 200;
const CAP_RECYCLE_Z = 110;
const CAP_RESET_Z = -1200;
/* the glyph and keycap corridors are shorter than the streak corridor: a rigid
   wrap over the full 2000 units arrives in waves at these object counts, and the
   solid ones also have to turn back before they can swallow the lens */
const LETTER_RECYCLE_Z = 140;
const LETTER_RESET_Z = -1300;
const RESET_Z = -1800;
const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
const SPEED_SCALE: Record<StarTunnelVariant, number> = {
  streaks: 1,
  letters: 0.5,
  keycaps: 0.7,
  hyperspace: 2.4,
};
type Layer = {
  update?: (step: number, time: number) => void;
  setOpacity?: (streakOpacity: number, tileOpacity: number) => void;
  dispose: () => void;
};
type StreakSettings = {
  count: number;
  radiusMin: number;
  radiusSpread: number;
  lengthMin: number;
  lengthSpread: number;
  palette: Rgb[];
  opacityScale: number;
};

function createStreakLayer(group: THREE.Group, settings: StreakSettings, opacity: number): Layer {
  const geometry = new THREE.BufferGeometry();
  const positions = new Float32Array(settings.count * 6);
  const colors = new Float32Array(settings.count * 6);
  const palette = settings.palette.map(color3);
  for (let index = 0; index < settings.count; index += 1) {
    const angle = Math.random() * Math.PI * 2;
    const radius = Math.random() * settings.radiusSpread + settings.radiusMin;
    const x = Math.cos(angle) * radius;
    const y = Math.sin(angle) * radius;
    const z = (Math.random() - 0.5) * 2000;
    const length = Math.random() * settings.lengthSpread + settings.lengthMin;
    positions[index * 6] = x;
    positions[index * 6 + 1] = y;
    positions[index * 6 + 2] = z;
    positions[index * 6 + 3] = x;
    positions[index * 6 + 4] = y;
    positions[index * 6 + 5] = z + length;
    const color = palette[Math.floor(Math.random() * palette.length)];
    colors[index * 6] = color.r;
    colors[index * 6 + 1] = color.g;
    colors[index * 6 + 2] = color.b;
    colors[index * 6 + 3] = color.r;
    colors[index * 6 + 4] = color.g;
    colors[index * 6 + 5] = color.b;
  }
  geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
  geometry.setAttribute("color", new THREE.BufferAttribute(colors, 3));
  const material = new THREE.LineBasicMaterial({
    vertexColors: true,
    transparent: true,
    opacity: opacity * settings.opacityScale,
  });
  const streaks = new THREE.LineSegments(geometry, material);
  group.add(streaks);
  const attribute = geometry.attributes.position as unknown as {
    array: Float32Array;
    needsUpdate: boolean;
  };
  return {
    update(step) {
      for (let index = 0; index < settings.count; index += 1) {
        positions[index * 6 + 2] += step;
        positions[index * 6 + 5] += step;
        if (positions[index * 6 + 2] > RECYCLE_Z) {
          const length = positions[index * 6 + 5] - positions[index * 6 + 2];
          positions[index * 6 + 2] = RESET_Z;
          positions[index * 6 + 5] = RESET_Z + length;
        }
      }
      attribute.needsUpdate = true;
    },
    setOpacity(streakOpacity) {
      const scaled = streakOpacity * settings.opacityScale;
      if (material.opacity !== scaled) material.opacity = scaled;
    },
    dispose() {
      geometry.dispose();
      material.dispose();
    },
  };
}

/* 40 slim panes flying past on the rails */
function createTileLayer(group: THREE.Group, opacity: number, inks: Inks): Layer {
  const geometry = new THREE.PlaneGeometry(8, 20);
  const template = new THREE.MeshBasicMaterial({
    transparent: true,
    opacity,
    side: THREE.DoubleSide,
  });
  const tiles: THREE.Mesh[] = [];
  let lastOpacity = opacity;
  for (let index = 0; index < 40; index += 1) {
    const material = template.clone();
    material.color = color3(
      Math.random() > 0.6 ? inks.accent : Math.random() > 0.5 ? inks.soft : inks.ink,
    );
    const mesh = new THREE.Mesh(geometry, material);
    const angle = Math.random() * Math.PI * 2;
    const radius = Math.random() * 400 + 100;
    mesh.position.x = Math.cos(angle) * radius;
    mesh.position.y = Math.sin(angle) * radius;
    mesh.position.z = (Math.random() - 0.5) * 2000;
    mesh.lookAt(0, 0, mesh.position.z + 100);
    const scale = Math.random() * 1.5 + 0.5;
    mesh.scale.set(scale, scale, scale);
    group.add(mesh);
    tiles.push(mesh);
  }
  return {
    update(step) {
      tiles.forEach((tile) => {
        tile.position.z += step;
        if (tile.position.z > RECYCLE_Z) tile.position.z = RESET_Z;
      });
    },
    setOpacity(_streakOpacity, tileOpacity) {
      if (lastOpacity === tileOpacity) return;
      tiles.forEach((tile) => {
        (tile.material as THREE.MeshBasicMaterial).opacity = tileOpacity;
      });
      lastOpacity = tileOpacity;
    },
    dispose() {
      geometry.dispose();
      template.dispose();
      tiles.forEach((tile) => (tile.material as THREE.MeshBasicMaterial).dispose());
    },
  };
}

type GlyphAtlas = { texture: THREE.CanvasTexture; columns: number; rows: number };

function createGlyphAtlas(font: string): GlyphAtlas {
  const columns = 6;
  const rows = 6;
  const cell = 128;
  const canvas = document.createElement("canvas");
  canvas.width = columns * cell;
  canvas.height = rows * cell;
  const context = canvas.getContext("2d");
  if (context) {
    context.fillStyle = "white";
    context.font = `500 ${Math.round(cell * 0.68)}px ${font}`;
    context.textAlign = "center";
    context.textBaseline = "middle";
    GLYPHS.split("").forEach((glyph, index) => {
      const column = index % columns;
      const row = Math.floor(index / columns);
      context.fillText(glyph, column * cell + cell / 2, row * cell + cell * 0.54);
    });
  }
  const texture = new THREE.CanvasTexture(canvas);
  texture.minFilter = THREE.LinearFilter;
  return { texture, columns, rows };
}

/* one unit plane per glyph, with its uv window pinned to that atlas cell, so a
   whole alphabet renders from a single texture and a handful of materials */
function createGlyphGeometries(atlas: GlyphAtlas): THREE.PlaneGeometry[] {
  return GLYPHS.split("").map((_, index) => {
    const geometry = new THREE.PlaneGeometry(1, 1);
    const column = index % atlas.columns;
    const row = Math.floor(index / atlas.columns);
    const originU = column / atlas.columns;
    const originV = 1 - (row + 1) / atlas.rows;
    const uv = geometry.attributes.uv as THREE.BufferAttribute;
    for (let vertex = 0; vertex < uv.count; vertex += 1) {
      uv.setXY(
        vertex,
        originU + uv.getX(vertex) / atlas.columns,
        originV + uv.getY(vertex) / atlas.rows,
      );
    }
    uv.needsUpdate = true;
    return geometry;
  });
}

type Tumbler = {
  mesh: THREE.Mesh;
  spin: number;
  swayX: number;
  swayY: number;
  phase: number;
  drift: number;
  radius: number;
};

function createLetterLayer(group: THREE.Group, opacity: number, inks: Inks): Layer {
  const atlas = createGlyphAtlas(inks.font);
  const geometries = createGlyphGeometries(atlas);
  const tints = [inks.ink, inks.ink, inks.accent, inks.soft].map(
    (color) =>
      new THREE.MeshBasicMaterial({
        map: atlas.texture,
        color: color3(color),
        transparent: true,
        opacity,
        depthWrite: false,
        side: THREE.DoubleSide,
      }),
  );
  const letters: Tumbler[] = [];
  let lastOpacity = opacity;
  for (let index = 0; index < 260; index += 1) {
    const mesh = new THREE.Mesh(
      geometries[Math.floor(Math.random() * geometries.length)],
      tints[Math.floor(Math.random() * tints.length)],
    );
    const angle = Math.random() * Math.PI * 2;
    const radius = Math.random() * 430 + 60;
    mesh.position.set(
      Math.cos(angle) * radius,
      Math.sin(angle) * radius,
      LETTER_RESET_Z + Math.random() * (LETTER_RECYCLE_Z - LETTER_RESET_Z),
    );
    const scale = Math.random() * 30 + 24;
    mesh.scale.set(scale, scale, scale);
    group.add(mesh);
    letters.push({
      mesh,
      spin: (Math.random() - 0.5) * 0.02,
      swayX: Math.random() * 0.5 + 0.2,
      swayY: Math.random() * 0.6 + 0.2,
      phase: Math.random() * Math.PI * 2,
      drift: Math.random() * 0.9 + 0.2,
      radius,
    });
  }
  return {
    update(step, time) {
      letters.forEach((letter) => {
        const { mesh } = letter;
        mesh.position.z += step;
        /* letters wander across the corridor instead of running the rails, which
           is what separates them from the streaks flying past behind them */
        const wander = time * letter.drift + letter.phase;
        mesh.position.x += Math.cos(wander) * letter.drift * 0.9;
        mesh.position.y += Math.sin(wander * 0.8) * letter.drift * 0.9;
        mesh.rotation.z += letter.spin;
        mesh.rotation.x = Math.sin(wander * 0.6) * letter.swayX;
        mesh.rotation.y = Math.cos(wander * 0.5) * letter.swayY;
        if (mesh.position.z > LETTER_RECYCLE_Z) {
          const angle = Math.random() * Math.PI * 2;
          const radius = Math.random() * 430 + 60;
          mesh.position.set(Math.cos(angle) * radius, Math.sin(angle) * radius, LETTER_RESET_Z);
        }
      });
    },
    setOpacity(_streakOpacity, tileOpacity) {
      if (lastOpacity === tileOpacity) return;
      tints.forEach((tint) => {
        tint.opacity = tileOpacity;
      });
      lastOpacity = tileOpacity;
    },
    dispose() {
      geometries.forEach((geometry) => geometry.dispose());
      tints.forEach((tint) => tint.dispose());
      atlas.texture.dispose();
    },
  };
}

/* a box with its top face drawn in, the cheapest read of an injection-moulded cap */
function createKeycapGeometry(width: number, height: number, depth: number): THREE.BoxGeometry {
  const geometry = new THREE.BoxGeometry(width, height, depth);
  const position = geometry.attributes.position as THREE.BufferAttribute;
  for (let vertex = 0; vertex < position.count; vertex += 1) {
    if (position.getY(vertex) > 0)
      position.setXYZ(
        vertex,
        position.getX(vertex) * 0.78,
        position.getY(vertex),
        position.getZ(vertex) * 0.78,
      );
  }
  position.needsUpdate = true;
  geometry.computeVertexNormals();
  return geometry;
}

function createSparkTexture(): THREE.CanvasTexture {
  const size = 64;
  const canvas = document.createElement("canvas");
  canvas.width = size;
  canvas.height = size;
  const context = canvas.getContext("2d");
  if (context) {
    const gradient = context.createRadialGradient(
      size / 2,
      size / 2,
      0,
      size / 2,
      size / 2,
      size / 2,
    );
    gradient.addColorStop(0, "white");
    gradient.addColorStop(0.4, "rgb(255 255 255 / 0.5)");
    gradient.addColorStop(1, "transparent");
    context.fillStyle = gradient;
    context.fillRect(0, 0, size, size);
  }
  const texture = new THREE.CanvasTexture(canvas);
  return texture;
}

function createSparkLayer(
  group: THREE.Group,
  count: number,
  size: number,
  color: THREE.Color,
  opacity: number,
  radiusSpread: number,
) {
  const geometry = new THREE.BufferGeometry();
  const positions = new Float32Array(count * 3);
  for (let index = 0; index < count; index += 1) {
    const angle = Math.random() * Math.PI * 2;
    const radius = Math.random() * radiusSpread + 20;
    positions[index * 3] = Math.cos(angle) * radius;
    positions[index * 3 + 1] = Math.sin(angle) * radius;
    positions[index * 3 + 2] = (Math.random() - 0.5) * 2000;
  }
  geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
  const texture = createSparkTexture();
  const material = new THREE.PointsMaterial({
    map: texture,
    color,
    size,
    transparent: true,
    opacity,
    depthWrite: false,
    sizeAttenuation: true,
  });
  const points = new THREE.Points(geometry, material);
  group.add(points);
  const attribute = geometry.attributes.position as unknown as { needsUpdate: boolean };
  return {
    positions,
    count,
    material,
    update(step: number) {
      for (let index = 0; index < count; index += 1) {
        positions[index * 3 + 2] += step;
        if (positions[index * 3 + 2] > RECYCLE_Z) positions[index * 3 + 2] = RESET_Z;
      }
      attribute.needsUpdate = true;
    },
    dispose() {
      geometry.dispose();
      material.dispose();
      texture.dispose();
    },
  };
}

function createKeycapLayer(
  scene: THREE.Scene,
  group: THREE.Group,
  opacity: number,
  inks: Inks,
): Layer {
  const atlas = createGlyphAtlas(inks.font);
  const legendGeometries = createGlyphGeometries(atlas);
  const capGeometry = createKeycapGeometry(26, 14, 26);
  const bodies = [inks.card, mix(inks.card, inks.border, 0.6), inks.border].map(
    (color) =>
      new THREE.MeshLambertMaterial({
        color: color3(color),
        transparent: true,
        opacity,
      }),
  );
  const legends = [inks.accent, inks.ink].map(
    (color) =>
      new THREE.MeshBasicMaterial({
        map: atlas.texture,
        color: color3(color),
        transparent: true,
        opacity,
        depthWrite: false,
        side: THREE.DoubleSide,
      }),
  );
  const ambient = new THREE.AmbientLight(color3(inks.ground), 0.8 * Math.PI);
  const key = new THREE.DirectionalLight(new THREE.Color(1, 1, 1), 1.2 * Math.PI);
  key.position.set(0.4, 1, 0.7);
  const rim = new THREE.DirectionalLight(color3(inks.accent), 0.6 * Math.PI);
  rim.position.set(-0.7, -0.4, 0.5);
  const flash = new THREE.PointLight(color3(inks.accent), 0.8 * Math.PI, 900, 1);
  flash.position.set(0, 0, 140);
  scene.add(ambient, key, rim, flash);
  const caps: Tumbler[] = [];
  let lastOpacity = opacity;
  for (let index = 0; index < 95; index += 1) {
    const mesh = new THREE.Mesh(capGeometry, bodies[Math.floor(Math.random() * bodies.length)]);
    const legend = new THREE.Mesh(
      legendGeometries[Math.floor(Math.random() * legendGeometries.length)],
      legends[Math.floor(Math.random() * legends.length)],
    );
    legend.scale.set(15, 15, 15);
    legend.position.y = 7.2;
    legend.rotation.x = -Math.PI / 2;
    mesh.add(legend);
    const angle = Math.random() * Math.PI * 2;
    const radius = Math.random() * 430 + 130;
    mesh.position.set(
      Math.cos(angle) * radius,
      Math.sin(angle) * radius,
      CAP_RESET_Z + Math.random() * (CAP_RECYCLE_Z - CAP_RESET_Z),
    );
    mesh.rotation.set(Math.random() * Math.PI, Math.random() * Math.PI, Math.random() * Math.PI);
    const scale = Math.random() * 1.15 + 0.8;
    mesh.scale.set(scale, scale, scale);
    group.add(mesh);
    caps.push({
      mesh,
      spin: (Math.random() - 0.5) * 0.03,
      swayX: (Math.random() - 0.5) * 0.026,
      swayY: (Math.random() - 0.5) * 0.03,
      phase: 0,
      drift: 0,
      radius,
    });
  }
  const sparks = createSparkLayer(group, 750, 7, color3(inks.accent), opacity, 620);
  return {
    update(step) {
      caps.forEach((cap) => {
        cap.mesh.position.z += step;
        cap.mesh.rotation.x += cap.swayX;
        cap.mesh.rotation.y += cap.swayY;
        cap.mesh.rotation.z += cap.spin;
        /* a cap is a solid volume, so it wraps before it can swallow the lens */
        if (cap.mesh.position.z > CAP_RECYCLE_Z) {
          const angle = Math.random() * Math.PI * 2;
          const radius = Math.random() * 430 + 130;
          cap.mesh.position.set(Math.cos(angle) * radius, Math.sin(angle) * radius, CAP_RESET_Z);
        }
      });
      sparks.update(step * 1.35);
    },
    setOpacity(streakOpacity, tileOpacity) {
      if (sparks.material.opacity !== streakOpacity) sparks.material.opacity = streakOpacity;
      if (lastOpacity === tileOpacity) return;
      bodies.forEach((body) => {
        body.opacity = tileOpacity;
      });
      legends.forEach((legend) => {
        legend.opacity = tileOpacity;
      });
      lastOpacity = tileOpacity;
    },
    dispose() {
      capGeometry.dispose();
      legendGeometries.forEach((geometry) => geometry.dispose());
      bodies.forEach((body) => body.dispose());
      legends.forEach((legend) => legend.dispose());
      atlas.texture.dispose();
      sparks.dispose();
      scene.remove(ambient, key, rim, flash);
    },
  };
}

function createTunnelTexture(ink: Rgb): THREE.CanvasTexture {
  const size = 512;
  const canvas = document.createElement("canvas");
  canvas.width = size;
  canvas.height = size;
  const context = canvas.getContext("2d");
  if (context) {
    for (let index = 0; index < 240; index += 1) {
      const x = Math.random() * size;
      const width = Math.random() * 3 + 0.6;
      const height = Math.random() * 320 + 90;
      const top = Math.random() * size;
      const alpha = (Math.random() * 0.45 + 0.08).toFixed(3);
      /* drawn once above and once below the seam so the scrolling wrap is invisible */
      for (const offset of [-size, 0, size]) {
        const gradient = context.createLinearGradient(0, top + offset, 0, top + offset + height);
        gradient.addColorStop(0, css(ink, 0));
        gradient.addColorStop(0.5, css(ink, Number(alpha)));
        gradient.addColorStop(1, css(ink, 0));
        context.fillStyle = gradient;
        context.fillRect(x, top + offset, width, height);
      }
    }
  }
  const texture = new THREE.CanvasTexture(canvas);
  texture.wrapS = THREE.RepeatWrapping;
  texture.wrapT = THREE.RepeatWrapping;
  texture.repeat.set(4, 2);
  return texture;
}

function createGlowTexture(inks: Inks): THREE.CanvasTexture {
  const size = 256;
  const canvas = document.createElement("canvas");
  canvas.width = size;
  canvas.height = size;
  const context = canvas.getContext("2d");
  if (context) {
    const gradient = context.createRadialGradient(
      size / 2,
      size / 2,
      0,
      size / 2,
      size / 2,
      size / 2,
    );
    gradient.addColorStop(0, css(inks.accent, 0.9));
    gradient.addColorStop(0.18, css(inks.accent, 0.45));
    gradient.addColorStop(0.45, css(inks.soft, 0.14));
    gradient.addColorStop(1, css(inks.ground, 0));
    context.fillStyle = gradient;
    context.fillRect(0, 0, size, size);
  }
  const texture = new THREE.CanvasTexture(canvas);
  return texture;
}

function createHyperspaceLayer(group: THREE.Group, opacity: number, inks: Inks): Layer {
  const tunnelTexture = createTunnelTexture(inks.ink);
  const tunnelGeometry = new THREE.CylinderGeometry(900, 240, 3000, 64, 1, true);
  tunnelGeometry.rotateX(Math.PI / 2);
  const tunnelMaterial = new THREE.MeshBasicMaterial({
    map: tunnelTexture,
    side: THREE.BackSide,
    transparent: true,
    opacity: opacity * 0.6,
    depthWrite: false,
  });
  const tunnel = new THREE.Mesh(tunnelGeometry, tunnelMaterial);
  tunnel.position.z = -1400;
  group.add(tunnel);

  const glowTexture = createGlowTexture(inks);
  const glowMaterial = new THREE.SpriteMaterial({
    map: glowTexture,
    transparent: true,
    opacity,
    depthWrite: false,
  });
  const glow = new THREE.Sprite(glowMaterial);
  glow.position.z = -900;
  glow.scale.set(760, 760, 1);
  group.add(glow);
  let lastOpacity = opacity;
  return {
    update(step, time) {
      /* the walls run with the streaks, and a slow roll keeps the jump from
         reading as a still image once the streak rails line up */
      tunnelTexture.offset.y -= step * 0.0016;
      tunnel.rotation.z += 0.0016;
      const pulse = 1 + Math.sin(time * 1.6) * 0.06;
      glow.scale.set(760 * pulse, 760 * pulse, 1);
    },
    setOpacity(_streakOpacity, tileOpacity) {
      if (lastOpacity === tileOpacity) return;
      tunnelMaterial.opacity = tileOpacity * 0.6;
      glowMaterial.opacity = tileOpacity;
      lastOpacity = tileOpacity;
    },
    dispose() {
      tunnelGeometry.dispose();
      tunnelMaterial.dispose();
      tunnelTexture.dispose();
      glowMaterial.dispose();
      glowTexture.dispose();
    },
  };
}

const STREAK_SETTINGS: Record<StarTunnelVariant, Omit<StreakSettings, "palette">> = {
  streaks: {
    count: 400,
    radiusMin: 20,
    radiusSpread: 800,
    lengthMin: 50,
    lengthSpread: 150,
    opacityScale: 1,
  },
  letters: {
    count: 260,
    radiusMin: 20,
    radiusSpread: 800,
    lengthMin: 40,
    lengthSpread: 120,
    opacityScale: 1,
  },
  keycaps: {
    count: 220,
    radiusMin: 20,
    radiusSpread: 800,
    lengthMin: 40,
    lengthSpread: 140,
    opacityScale: 1,
  },
  hyperspace: {
    count: 1200,
    radiusMin: 6,
    radiusSpread: 760,
    lengthMin: 170,
    lengthSpread: 420,
    opacityScale: 1.45,
  },
};

export function StarTunnel({
  variant = "letters",
  speed = 12,
  streakOpacity = 0.6,
  tileOpacity = 0.9,
  fov = 62,
  brightness = 1,
  hue = 0,
  saturation = 1,
  colors,
  backgroundColor,
  className,
}: StarTunnelProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({ speed, streakOpacity, tileOpacity, fov });
  options.current = { speed, streakOpacity, tileOpacity, fov };
  const paletteKey = colors?.join(",") ?? "";

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas || !theme) return;

    const ground = backgroundColor ? toRgb(backgroundColor) : theme.background;
    const inks: Inks = {
      ink: theme.foreground,
      accent: theme.primary,
      soft: mix(theme.primary, theme["muted-foreground"], 0.5),
      ground,
      card: theme.card,
      border: theme.border,
      font: getComputedStyle(host).fontFamily,
    };
    const startOptions = options.current;
    const scene = new THREE.Scene();
    scene.background = color3(ground);
    scene.fog = new THREE.FogExp2(color3(ground), 0.0012);
    const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 2000);
    camera.position.z = 0;
    const renderer = new THREE.WebGLRenderer({
      canvas,
      alpha: true,
      antialias: true,
      powerPreference: "high-performance",
    });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;

    const group = new THREE.Group();
    scene.add(group);

    const settings = STREAK_SETTINGS[variant];
    const palette = paletteKey
      ? paletteKey.split(",").map(toRgb)
      : [inks.ink, inks.accent, inks.soft, mix(inks.ink, inks.ground, 0.4)];
    const layers: Layer[] = [
      createStreakLayer(group, { ...settings, palette }, startOptions.streakOpacity),
    ];
    if (variant === "streaks") layers.push(createTileLayer(group, startOptions.tileOpacity, inks));
    if (variant === "letters")
      layers.push(createLetterLayer(group, startOptions.tileOpacity, inks));
    if (variant === "keycaps")
      layers.push(createKeycapLayer(scene, group, startOptions.tileOpacity, inks));
    if (variant === "hyperspace")
      layers.push(createHyperspaceLayer(group, startOptions.tileOpacity, inks));

    let elapsed = 0;
    const render = (advance: boolean) => {
      const o = options.current;
      if (camera.fov !== o.fov) {
        camera.fov = o.fov;
        camera.updateProjectionMatrix();
      }
      if (advance) elapsed += 1 / 60;
      const step = advance ? o.speed * SPEED_SCALE[variant] : 0;
      layers.forEach((layer) => {
        layer.setOpacity?.(o.streakOpacity, o.tileOpacity);
        if (advance) layer.update?.(step, elapsed);
      });
      renderer.render(scene, camera);
    };
    const resize = () => {
      const { width, height } = host.getBoundingClientRect();
      camera.aspect = width / Math.max(1, height);
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);
      render(false);
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      render(true);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !frame) frame = requestAnimationFrame(tick);
    };
    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      layers.forEach((layer) => layer.dispose());
      renderer.dispose();
    };
  }, [prefersReducedMotion, variant, paletteKey, backgroundColor, theme]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden font-mono", className)}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{
          filter: `hue-rotate(${hue}deg) saturate(${saturation}) brightness(${brightness})`,
        }}
      />
    </div>
  );
}
```

---

# Plate Wheel

> A tilted WebGL wheel of curved, muted image plates turning over a ruled sheet in the theme colours.

Install: `npx @modus-ui/cli add plate-wheel`

Sixteen curved image plates wound around a tilted cylinder, turning slowly and floating up and down over a ruled grid drawn from the theme background and foreground tokens. Photos are desaturated by default for a quiet editorial tone. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add plate-wheel
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/plate-wheel.tsx`.
4. Paste the code.

## Usage

```tsx
import { PlateWheel } from "@/components/ui/plate-wheel";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <PlateWheel />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type       | Default                           | Description                                  |
| :---------------- | :--------- | :-------------------------------- | :------------------------------------------- |
| `images`          | `string[]` | five sample photos                | Image URLs, repeated across the 16 panels.   |
| `speed`           | `number`   | `1`                               | Rotation speed, clamped to 0–3.              |
| `scale`           | `number`   | `1`                               | Scale of the helix, clamped to 0.7–1.35.     |
| `opacity`         | `number`   | `1`                               | Canvas opacity, clamped to 0.05–1.           |
| `hue`             | `number`   | `0`                               | Hue rotation in degrees, clamped to ±180.    |
| `saturation`      | `number`   | `0.55`                            | CSS saturation filter, clamped to 0–2.       |
| `brightness`      | `number`   | `1`                               | CSS brightness filter, clamped to 0.35–1.65. |
| `backgroundColor` | `string`   | `"hsl(var(--background))"`        | Background colour.                           |
| `dotColor`        | `string`   | `"hsl(var(--foreground) / 0.08)"` | Colour of the ruled background grid.         |

## Source

`components/ui/plate-wheel.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Gallery (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface PlateWheelProps {
  images?: string[];
  speed?: number;
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  backgroundColor?: string;
  dotColor?: string;
  className?: string;
}

const DEFAULT_IMAGES = [
  "https://images.unsplash.com/photo-1755331039789-7e5680e26e8f?q=80&w=774&auto=format&fit=crop",
  "https://images.unsplash.com/photo-1755569309049-98410b94f66d?q=80&w=772&auto=format&fit=crop",
  "https://images.unsplash.com/photo-1755497595318-7e5e3523854f?q=80&w=774&auto=format&fit=crop",
  "https://images.unsplash.com/photo-1755353985163-c2a0fe5ac3d8?q=80&w=774&auto=format&fit=crop",
  "https://images.unsplash.com/photo-1745965976680-d00be7dc0377?q=80&w=774&auto=format&fit=crop",
];

const clamp = (value: number, minimum: number, maximum: number) =>
  Math.min(maximum, Math.max(minimum, value));

export function PlateWheel({
  images = DEFAULT_IMAGES,
  speed = 1,
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 0.55,
  brightness = 1,
  backgroundColor = "hsl(var(--background))",
  dotColor = "hsl(var(--foreground) / 0.08)",
  className,
}: PlateWheelProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const settings = useRef({ speed, scale });
  settings.current = { speed, scale };
  const imageKey = images.join("\n");

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const urls = imageKey.split("\n").filter(Boolean);
    if (!host || !canvas || urls.length === 0) return;

    const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
    renderer.setClearColor(0x000000, 0);
    renderer.outputColorSpace = THREE.SRGBColorSpace;
    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(35, 1, 0.1, 100);
    camera.position.set(0, 3.2, 17);
    camera.lookAt(0, 0, 0);
    const gallery = new THREE.Group();
    gallery.rotation.z = -0.12;
    scene.add(gallery);

    const geometry = new THREE.CylinderGeometry(5, 5, 1.8, 64, 1, true, 0, Math.PI * 0.4);
    const loader = new THREE.TextureLoader();
    loader.setCrossOrigin("anonymous");
    let disposed = false;
    let frame = 0;
    let elapsed = 0;
    let previousTime = 0;
    let hostVisible = true;

    const render = (time = performance.now()) => {
      const safeSpeed = clamp(settings.current.speed, 0, 3);
      const safeScale = clamp(settings.current.scale, 0.7, 1.35);
      if (previousTime) elapsed += Math.min((time - previousTime) / 1000, 0.05) * safeSpeed;
      previousTime = time;
      gallery.rotation.y = elapsed * 0.18;
      gallery.position.y = Math.sin(elapsed) * 1.5;
      gallery.scale.setScalar(safeScale);
      renderer.render(scene, camera);
    };

    const textures = urls.map((url) => {
      const texture = loader.load(url, () => {
        if (disposed) {
          texture.dispose();
          return;
        }
        renderer.render(scene, camera);
      });
      texture.colorSpace = THREE.SRGBColorSpace;
      texture.anisotropy = Math.min(8, renderer.capabilities.getMaxAnisotropy());
      return texture;
    });
    const materials = Array.from(
      { length: 16 },
      (_, index) =>
        new THREE.MeshBasicMaterial({
          map: textures[index % textures.length],
          opacity: 0.85,
          side: THREE.DoubleSide,
          toneMapped: false,
          transparent: true,
        }),
    );
    materials.forEach((material, index) => {
      const panel = new THREE.Mesh(geometry, material);
      panel.position.y = (index - 8) * 2.4;
      panel.rotation.y = (index / 16) * Math.PI * 4;
      gallery.add(panel);
    });

    const tick = (time: number) => {
      if (disposed || !hostVisible || document.hidden) {
        frame = 0;
        previousTime = 0;
        return;
      }
      render(time);
      frame = requestAnimationFrame(tick);
    };
    const start = () => {
      if (prefersReducedMotion) {
        render(0);
        return;
      }
      if (!frame && hostVisible && !document.hidden) frame = requestAnimationFrame(tick);
    };
    const stop = () => {
      if (frame) cancelAnimationFrame(frame);
      frame = 0;
      previousTime = 0;
    };
    const resize = () => {
      const bounds = host.getBoundingClientRect();
      const width = Math.max(1, Math.round(bounds.width));
      const height = Math.max(1, Math.round(bounds.height));
      renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
      renderer.setSize(width, height, false);
      camera.aspect = width / height;
      camera.updateProjectionMatrix();
      render();
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      hostVisible = entry?.isIntersecting ?? true;
      if (hostVisible) start();
      else stop();
    });
    const onVisibility = () => (document.hidden ? stop() : start());
    resizeObserver.observe(host);
    intersection.observe(host);
    document.addEventListener("visibilitychange", onVisibility);
    resize();
    start();

    return () => {
      disposed = true;
      stop();
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      gallery.clear();
      geometry.dispose();
      materials.forEach((material) => material.dispose());
      textures.forEach((texture) => texture.dispose());
      renderer.dispose();
    };
  }, [prefersReducedMotion, imageKey]);

  return (
    <div
      ref={hostRef}
      role="img"
      aria-label="Turning wheel of image plates"
      className={cn("pointer-events-none absolute inset-0 overflow-hidden", className)}
      style={{
        backgroundColor,
        backgroundImage: `linear-gradient(${dotColor} 1px, transparent 1px), linear-gradient(90deg, ${dotColor} 1px, transparent 1px)`,
        backgroundSize: "44px 44px",
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{
          opacity: clamp(opacity, 0.05, 1),
          filter: `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`,
        }}
      />
    </div>
  );
}
```

---

# Node Weave

> A canvas weave of hollow knots and solid ink hubs, threaded by hairlines that tighten around the pointer.

Install: `npx @modus-ui/cli add node-weave`

Hollow knots drift across a 2D canvas on the page's own background, threaded together by hairlines whenever they come close; every sixth knot is a solid hub in the primary colour with a breathing ring, and its threads take on that colour. Colours come from the active theme, so the weave is ink on paper in light mode and follows the palette in dark mode. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add node-weave
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/node-weave.tsx`.
3. Paste the code.

## Usage

```tsx
import { NodeWeave } from "@/components/ui/node-weave";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <NodeWeave />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default        | Description                                                     |
| :---------------- | :------- | :------------- | :-------------------------------------------------------------- |
| `speed`           | `number` | `1`            | Drift and pulse speed multiplier (0 to 3).                      |
| `size`            | `number` | `1`            | Knot radius multiplier.                                         |
| `length`          | `number` | `1`            | Link distance multiplier (base 160px, 0.35 to 2.5).             |
| `density`         | `number` | `1`            | Node count multiplier (85 nodes on wide hosts, 40 under 768px). |
| `strokeWidth`     | `number` | `0.75`         | Link line width in pixels.                                      |
| `opacity`         | `number` | `1`            | Opacity of nodes and links (0.05 to 1).                         |
| `hue`             | `number` | `0`            | Hue rotation in degrees (-180 to 180).                          |
| `saturation`      | `number` | `1`            | Saturation multiplier (0 to 2).                                 |
| `brightness`      | `number` | `1`            | Brightness multiplier (0.35 to 1.65).                           |
| `color`           | `string` | `--primary`    | Hub and hub-thread colour (theme token by default).             |
| `backgroundColor` | `string` | `--background` | Scene background (theme token by default).                      |

## Source

`components/ui/node-weave.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Constellation Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

export interface NodeWeaveProps {
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  strokeWidth?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Hub and link colour. Defaults to the theme's `--primary`. */
  color?: string;
  /** Scene background. Defaults to the theme's `--background`. */
  backgroundColor?: string;
  className?: string;
}

type Node = { x: number; y: number; vx: number; vy: number; radius: number; hub: boolean };

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

export function NodeWeave({
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  strokeWidth = 0.75,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  color,
  backgroundColor,
  className,
}: NodeWeaveProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const tokens = useTokens();
  const ink = color ?? tokens?.primary ?? "transparent";
  const thread = tokens?.muted ?? ink;
  const background = backgroundColor ?? "hsl(var(--background))";
  const paper = backgroundColor ?? tokens?.background ?? "transparent";
  const live = useRef({ speed, ink, thread, paper });
  live.current = { speed: clamp(speed, 0, 3), ink, thread, paper };
  const repaint = useRef<() => void>(() => {});

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    const LINK = Math.round(160 * clamp(length, 0.35, 2.5));
    const safeDensity = clamp(density, 0.25, 2.5);
    const nodeSize = clamp(size, 0.05, 200);
    const lineWidth = Number(Math.max(0.25, clamp(strokeWidth, 0.25, 8)).toFixed(2));
    let width = 1;
    let height = 1;
    let nodes: Node[] = [];
    const pointer = { x: -1000, y: -1000 };
    // Virtual clock so the node pulse follows `speed`, like the original's patched Date.now.
    let clock = 0;
    let last = performance.now();

    const resize = () => {
      const rect = host.getBoundingClientRect();
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      width = rect.width;
      height = rect.height;
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      ctx.imageSmoothingEnabled = false;
    };

    const initNodes = () => {
      const max =
        width < 768
          ? Math.max(8, Math.round(40 * safeDensity))
          : Math.max(12, Math.round(85 * safeDensity));
      nodes = [];
      for (let i = 0; i < max; i++) {
        nodes.push({
          x: Math.random() * width,
          y: Math.random() * height,
          vx: (Math.random() - 0.5) * 0.3,
          vy: (Math.random() - 0.5) * 0.3,
          radius: (Math.random() * 1.6 + 1.4) * nodeSize,
          hub: i % 6 === 0,
        });
      }
    };

    const draw = (advance: boolean) => {
      const { speed: s, ink: fill, thread, paper } = live.current;
      const now = performance.now();
      clock += (now - last) * (s || 1);
      last = now;
      ctx.clearRect(0, 0, width, height);
      ctx.lineCap = "butt";
      ctx.lineJoin = "miter";

      // Draw links first so nodes sit crisp on top.
      ctx.strokeStyle = thread;
      ctx.lineWidth = lineWidth;
      for (let i = 0; i < nodes.length; i++) {
        for (let j = i + 1; j < nodes.length; j++) {
          const d = Math.hypot(nodes[i].x - nodes[j].x, nodes[i].y - nodes[j].y);
          if (d < LINK) {
            const touchesHub = nodes[i].hub || nodes[j].hub;
            ctx.strokeStyle = touchesHub ? fill : thread;
            ctx.globalAlpha = (touchesHub ? 0.25 : 0.12) + (1 - d / LINK) * 0.45;
            ctx.beginPath();
            ctx.moveTo(nodes[i].x, nodes[i].y);
            ctx.lineTo(nodes[j].x, nodes[j].y);
            ctx.stroke();
          }
        }
      }

      nodes.forEach((node) => {
        if (advance) {
          node.x += node.vx * (s || 1);
          node.y += node.vy * (s || 1);
          if (node.x < 0 || node.x > width) node.vx *= -1;
          if (node.y < 0 || node.y > height) node.vy *= -1;
          // Gentle pointer gravity.
          if (Math.hypot(node.x - pointer.x, node.y - pointer.y) < 220) {
            node.x -= (node.x - pointer.x) * 0.005;
            node.y -= (node.y - pointer.y) * 0.005;
          }
        }
        // Hubs are solid ink with a breathing ring; the rest are hollow knots on the weave.
        const pulse = 0.5 + Math.sin(clock * 0.0012 + node.x * 0.05) * 0.5;
        if (node.hub) {
          ctx.fillStyle = fill;
          ctx.globalAlpha = 1;
          ctx.beginPath();
          ctx.arc(node.x, node.y, node.radius * 1.2, 0, Math.PI * 2);
          ctx.fill();
          ctx.strokeStyle = fill;
          ctx.globalAlpha = 0.15 + pulse * 0.35;
          ctx.beginPath();
          ctx.arc(node.x, node.y, node.radius * (2.6 + pulse * 1.4), 0, Math.PI * 2);
          ctx.stroke();
        } else {
          ctx.fillStyle = paper;
          ctx.strokeStyle = thread;
          ctx.globalAlpha = 0.9;
          ctx.beginPath();
          ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
          ctx.fill();
          ctx.stroke();
        }
      });
      ctx.globalAlpha = 1;
    };

    const onPointerMove = (event: PointerEvent) => {
      const rect = host.getBoundingClientRect();
      const x = event.clientX - rect.left;
      const y = event.clientY - rect.top;
      const inside = x >= 0 && y >= 0 && x <= rect.width && y <= rect.height;
      pointer.x = inside ? x : -1000;
      pointer.y = inside ? y : -1000;
    };
    const onPointerLeave = () => {
      pointer.x = -1000;
      pointer.y = -1000;
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      draw(true);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || frame || !visible || document.hidden) return;
      last = performance.now();
      frame = requestAnimationFrame(tick);
    };
    const stop = () => {
      if (frame) cancelAnimationFrame(frame);
      frame = 0;
    };

    const resizeObserver = new ResizeObserver(() => {
      resize();
      initNodes();
      draw(false);
    });
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else stop();
    });
    const onVisibility = () => (document.hidden ? stop() : start());

    repaint.current = () => draw(false);
    resize();
    initNodes();
    draw(false);
    resizeObserver.observe(host);
    intersection.observe(host);
    window.addEventListener("pointermove", onPointerMove);
    document.documentElement.addEventListener("pointerleave", onPointerLeave);
    document.addEventListener("visibilitychange", onVisibility);
    start();

    return () => {
      stop();
      resizeObserver.disconnect();
      intersection.disconnect();
      window.removeEventListener("pointermove", onPointerMove);
      document.documentElement.removeEventListener("pointerleave", onPointerLeave);
      document.removeEventListener("visibilitychange", onVisibility);
    };
  }, [prefersReducedMotion, size, length, density, strokeWidth]);

  // Repaint the still frame when the theme changes under it.
  useEffect(() => {
    repaint.current();
  }, [ink, thread, paper]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background, filter }}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Aperture Bloom

> A centred, noise-warped pair of WebGL rings inked in the theme colours that leans toward the pointer.

Install: `npx @modus-ui/cli add aperture-bloom`

A full-bleed Three.js shader draws a tight aperture of two noise-warped rings at the centre of the frame. In light mode they are inked on `--background` in `--primary` with a `--muted-foreground` fringe; in dark mode they glow additively, a `--foreground` core over a `--primary` fringe. It follows palette and mode changes live, and drifts slightly toward the pointer. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add aperture-bloom
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/aperture-bloom.tsx`.
4. Paste the code.

## Usage

```tsx
import { ApertureBloom } from "@/components/ui/aperture-bloom";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ApertureBloom />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                 |
| :---------------- | :------- | :------------------- | :------------------------------------------ |
| `speed`           | `number` | `1`                  | Animation speed multiplier (0 to 3).        |
| `size`            | `number` | `1`                  | Ring thickness multiplier.                  |
| `length`          | `number` | `1`                  | Ring radius multiplier (0.35 to 2.5).       |
| `opacity`         | `number` | `1`                  | Opacity of the glow (0.05 to 1).            |
| `hue`             | `number` | `0`                  | Hue rotation in degrees (-180 to 180).      |
| `saturation`      | `number` | `1`                  | Saturation multiplier (0 to 2).             |
| `brightness`      | `number` | `1`                  | Brightness multiplier (0.35 to 1.65).       |
| `coreColor`       | `string` | theme tokens         | Colour of the ring's bright core.           |
| `fringeColor`     | `string` | theme tokens         | Colour of the soft fringe and ambient wash. |
| `backgroundColor` | `string` | theme `--background` | Scene background behind the glow.           |

## Source

`components/ui/aperture-bloom.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Portal Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface ApertureBloomProps {
  speed?: number;
  size?: number;
  length?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  coreColor?: string;
  fringeColor?: string;
  backgroundColor?: string;
  className?: string;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// Shader colours are raw sRGB values, as in the original three r134 page (no colour management).
const rawColor = (target: THREE.Color, value: string) =>
  target.setStyle(value, THREE.LinearSRGBColorSpace);

const readToken = (name: string) =>
  getComputedStyle(document.documentElement).getPropertyValue(name).trim();
/** A bare-HSL theme token as `hsl(h, s%, l%)`, the form three.js parses. */
const themeColor = (name: string) => `hsl(${readToken(name).split(/\s+/).join(", ")})`;
const isLightTheme = () => Number.parseFloat(readToken("--background").split(/\s+/)[2] ?? "0") > 50;

/** WebGL1 GLSL ES requires float literals (10.0), not ints (10). */
const glslFloat = (value: number, digits = 3) => {
  const fixed = Number(value).toFixed(digits);
  return fixed.includes(".") ? fixed : `${fixed}.0`;
};

const vertexShader = `
  varying vec2 vUv;
  void main() {
    vUv = uv;
    gl_Position = vec4(position, 1.0);
  }
`;

const fragmentShader = (size: number, length: number) => `
  uniform float u_time;
  uniform vec2 u_resolution;
  uniform vec2 u_mouse;
  uniform vec3 u_colorCore;
  uniform vec3 u_colorFringe;
  uniform float u_isLightMode;
  varying vec2 vUv;

  vec2 hash( vec2 p ) {
    p = vec2( dot(p,vec2(127.1,311.7)), dot(p,vec2(269.5,183.3)) );
    return -1.0 + 2.0*fract(sin(p)*43758.5453123);
  }
  float noise( in vec2 p ) {
    const float K1 = 0.366025404;
    const float K2 = 0.211324865;
    vec2 i = floor( p + (p.x+p.y)*K1 );
    vec2 a = p - i + (i.x+i.y)*K2;
    vec2 o = (a.x>a.y) ? vec2(1.0,0.0) : vec2(0.0,1.0);
    vec2 b = a - o + K2;
    vec2 c = a - 1.0 + 2.0*K2;
    vec3 h = max( 0.5-vec3(dot(a,a), dot(b,b), dot(c,c) ), 0.0 );
    vec3 n = h*h*h*h*vec3( dot(a,hash(i+0.0)), dot(b,hash(i+o)), dot(c,hash(i+1.0)));
    return dot( n, vec3(70.0) );
  }

  float sdArc(vec2 p, vec2 center, float radius, float width, float warp) {
    p.y += sin(p.x * 2.0 + u_time * 0.3) * warp;
    p.x += noise(p * 1.5 + u_time * 0.1) * (warp * 0.8);
    float d = length(p - center) - radius;
    return abs(d) - width;
  }

  void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution.xy;
    vec2 st = uv;
    st.x *= u_resolution.x / u_resolution.y;

    vec2 mouseOffset = (u_mouse - 0.5) * 0.05;
    st += mouseOffset;

    // A smaller aperture centred in the frame, with a second ring set further out.
    vec2 center = vec2(0.5 * u_resolution.x / u_resolution.y, 0.5);

    float d1 = sdArc(st, center, ${glslFloat(0.3 * length, 3)}, ${glslFloat(0.012 * size, 4)}, 0.08);
    float d2 = sdArc(st, center, ${glslFloat(0.36 * length, 3)}, ${glslFloat(0.05 * size, 4)}, 0.14);

    float coreGlow = exp(-d1 * 30.0);
    float fringeGlow = exp(-d2 * 10.0);
    float wash = smoothstep(1.5, -0.5, length(st - center)) * 0.15;

    vec3 finalColor = vec3(0.0);
    finalColor += u_colorCore * coreGlow;
    finalColor += u_colorFringe * fringeGlow;
    finalColor += u_colorFringe * wash * (sin(u_time * 0.5) * 0.2 + 0.8);

    if(u_isLightMode > 0.5) {
      // On paper: ink the rings in the token colours instead of adding light.
      vec3 ink = mix(u_colorFringe, u_colorCore, clamp(coreGlow, 0.0, 1.0));
      float inkAlpha = clamp(coreGlow * 0.9 + fringeGlow * 0.45 + wash * 0.5, 0.0, 0.85);
      gl_FragColor = vec4(ink * inkAlpha, inkAlpha);
      return;
    }

    float alpha = clamp(coreGlow + fringeGlow + wash, 0.0, 1.0);
    finalColor = vec3(1.0) - exp(-finalColor * 1.5);
    gl_FragColor = vec4(finalColor, alpha * 0.6);
  }
`;

export function ApertureBloom({
  speed = 1,
  size = 1,
  length = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  coreColor,
  fringeColor,
  backgroundColor,
  className,
}: ApertureBloomProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const live = useRef({ speed, coreColor, fringeColor });
  live.current = { speed: clamp(speed, 0, 3), coreColor, fringeColor };

  const [themeKey, setThemeKey] = useState(0);

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return;
    const light = isLightTheme();
    const colors = () => ({
      core: live.current.coreColor ?? themeColor(light ? "--primary" : "--foreground"),
      fringe: live.current.fringeColor ?? themeColor(light ? "--muted-foreground" : "--primary"),
    });

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.display = "block";
    renderer.domElement.style.width = "100%";
    renderer.domElement.style.height = "100%";
    host.appendChild(renderer.domElement);

    const geometry = new THREE.PlaneGeometry(2, 2);
    const material = new THREE.ShaderMaterial({
      vertexShader,
      fragmentShader: fragmentShader(clamp(size, 0.05, 200), clamp(length, 0.35, 2.5)),
      uniforms: {
        u_time: { value: 0 },
        u_resolution: { value: new THREE.Vector2(1, 1) },
        u_mouse: { value: new THREE.Vector2(0.5, 0.5) },
        u_colorCore: { value: rawColor(new THREE.Color(), colors().core) },
        u_colorFringe: { value: rawColor(new THREE.Color(), colors().fringe) },
        u_isLightMode: { value: light ? 1 : 0 },
      },
      transparent: true,
      premultipliedAlpha: light,
      blending: light ? THREE.NormalBlending : THREE.AdditiveBlending,
    });
    const mesh = new THREE.Mesh(geometry, material);
    scene.add(mesh);

    const targetMouse = new THREE.Vector2(0.5, 0.5);
    const onPointerMove = (event: PointerEvent) => {
      const rect = host.getBoundingClientRect();
      targetMouse.x = (event.clientX - rect.left) / rect.width;
      targetMouse.y = 1 - (event.clientY - rect.top) / rect.height;
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      const width = Math.max(1, rect.width);
      const height = Math.max(1, rect.height);
      renderer.setSize(width, height, false);
      // The original passes CSS pixels here while gl_FragCoord is in device pixels.
      material.uniforms.u_resolution.value.set(width, height);
    };

    let time = 0;
    let last = performance.now();
    const render = () => {
      const now = performance.now();
      time += ((now - last) / 1000) * live.current.speed;
      last = now;
      material.uniforms.u_time.value = time;
      const { core, fringe } = colors();
      rawColor(material.uniforms.u_colorCore.value, core);
      rawColor(material.uniforms.u_colorFringe.value, fringe);
      material.uniforms.u_mouse.value.lerp(targetMouse, 0.03);
      renderer.render(scene, camera);
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      render();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || frame || !visible || document.hidden) return;
      last = performance.now();
      frame = requestAnimationFrame(tick);
    };
    const stop = () => {
      if (frame) cancelAnimationFrame(frame);
      frame = 0;
    };

    const resizeObserver = new ResizeObserver(() => {
      resize();
      render();
    });
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else stop();
    });
    const onVisibility = () => (document.hidden ? stop() : start());

    resize();
    render();
    resizeObserver.observe(host);
    intersection.observe(host);
    window.addEventListener("pointermove", onPointerMove);
    document.addEventListener("visibilitychange", onVisibility);
    start();
    const themeObserver = new MutationObserver(() => setThemeKey((key) => key + 1));
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });

    return () => {
      stop();
      themeObserver.disconnect();
      resizeObserver.disconnect();
      intersection.disconnect();
      window.removeEventListener("pointermove", onPointerMove);
      document.removeEventListener("visibilitychange", onVisibility);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, size, length, themeKey]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    >
      <div
        ref={hostRef}
        className="absolute inset-0 dark:mix-blend-screen"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Mosaic Crest

> A swooping band of square tesserae that ripples with travelling waves, laid in the active theme colours.

Install: `npx @modus-ui/cli add mosaic-crest`

A 2D canvas lays square tesserae along a swooping band that dips low through the frame and rises to both corners, rippling with travelling waves. Edge tiles are muted ink; the crest of the band is laid in the primary colour, on the page's own background, so it reads as ink on paper in light mode and follows the active palette. Set a positive `arcDrop` to turn the band into an arch. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add mosaic-crest
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/mosaic-crest.tsx`.
3. Paste the code.

## Usage

```tsx
import { MosaicCrest } from "@/components/ui/mosaic-crest";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <MosaicCrest />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default        | Description                                                                            |
| :---------------- | :------- | :------------- | :------------------------------------------------------------------------------------- |
| `speed`           | `number` | `1`            | Wave speed multiplier.                                                                 |
| `pixelSize`       | `number` | `12`           | Size of each tile cell in pixels.                                                      |
| `arcCenter`       | `number` | `0.82`         | Vertical position of the band at the centre, as a fraction of the height.              |
| `arcDrop`         | `number` | `-0.72`        | How far the band moves toward the sides, as a fraction of the height (negative rises). |
| `thickness`       | `number` | `0.24`         | Thickness of the arc band, as a fraction of the height.                                |
| `brightness`      | `number` | `1`            | Tile opacity multiplier.                                                               |
| `hue`             | `number` | `0`            | Hue rotation in degrees.                                                               |
| `saturation`      | `number` | `1`            | Saturation multiplier.                                                                 |
| `backgroundColor` | `string` | `--background` | Scene background (theme token by default).                                             |

## Source

`components/ui/mosaic-crest.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Data Pixel Arc (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

export interface MosaicCrestProps {
  speed?: number;
  pixelSize?: number;
  arcCenter?: number;
  arcDrop?: number;
  thickness?: number;
  brightness?: number;
  hue?: number;
  saturation?: number;
  /** Scene background. Defaults to the theme's `--background`. */
  backgroundColor?: string;
  className?: string;
}

export function MosaicCrest({
  speed = 1,
  pixelSize = 12,
  arcCenter = 0.82,
  arcDrop = -0.72,
  thickness = 0.24,
  brightness = 1,
  hue = 0,
  saturation = 1,
  backgroundColor,
  className,
}: MosaicCrestProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const tokens = useTokens();
  const paper = backgroundColor ?? tokens?.background;
  const ink = tokens?.primary;
  const edge = tokens?.muted;
  const options = useRef({
    speed,
    pixelSize,
    arcCenter,
    arcDrop,
    thickness,
    brightness,
    paper,
    ink,
    edge,
  });
  const repaint = useRef<() => void>(() => {});
  options.current = {
    speed,
    pixelSize,
    arcCenter,
    arcDrop,
    thickness,
    brightness,
    paper,
    ink,
    edge,
  };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const context = canvas?.getContext("2d", { alpha: false });
    if (!host || !canvas || !context) return;

    let width = 1;
    let height = 1;
    let time = 0;

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      width = Math.max(1, bounds.width);
      height = Math.max(1, bounds.height);
      const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.round(width * pixelRatio);
      canvas.height = Math.round(height * pixelRatio);
      context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
    };

    const render = () => {
      const o = options.current;
      if (!o.paper || !o.ink || !o.edge) return;
      context.globalAlpha = 1;
      context.fillStyle = o.paper;
      context.fillRect(0, 0, width, height);
      const cols = Math.ceil(width / o.pixelSize);
      const rows = Math.ceil(height / o.pixelSize);
      const arcCenterY = height * o.arcCenter;
      const drop = height * o.arcDrop;
      const band = height * o.thickness;
      const gap = Math.max(1, Math.round(o.pixelSize * 0.18));
      for (let x = 0; x < cols; x += 1) {
        for (let y = 0; y < rows; y += 1) {
          const px = x * o.pixelSize;
          const py = y * o.pixelSize;
          const nx = (px / width) * 2 - 1;
          const curveY = arcCenterY + Math.pow(Math.abs(nx), 1.8) * drop;
          let intensity = Math.max(0, 1 - Math.abs(py - curveY) / band);
          if (intensity <= 0.01) continue;
          const wave1 = Math.sin(nx * 4 - time * 1.5) * 0.1;
          const wave2 = Math.cos(py * 0.01 + time) * 0.1;
          intensity = Math.max(0, Math.min(1, intensity + wave1 + wave2));
          intensity *= Math.max(0, 1 - Math.pow(Math.abs(nx), 2.5));
          if (intensity <= 0.02) continue;
          const size = o.pixelSize - gap;
          // Muted tesserae make the band; the crest is laid in the primary colour on top.
          context.fillStyle = o.edge;
          context.globalAlpha = Math.min(1, Math.pow(intensity, 0.8) * 0.55 * o.brightness);
          context.fillRect(px, py, size, size);
          const core = Math.pow(intensity, 2.6);
          if (core > 0.04) {
            context.fillStyle = o.ink;
            context.globalAlpha = Math.min(1, core * o.brightness);
            context.fillRect(px, py, size, size);
          }
        }
      }
      context.globalAlpha = 1;
      time += 0.02 * o.speed;
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      render();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || frame || !visible || document.hidden) return;
      frame = requestAnimationFrame(tick);
    };
    const stop = () => {
      if (frame) cancelAnimationFrame(frame);
      frame = 0;
    };

    const resizeObserver = new ResizeObserver(() => {
      resize();
      render();
    });
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else stop();
    });
    const onVisibility = () => (document.hidden ? stop() : start());

    repaint.current = render;
    resize();
    render();
    resizeObserver.observe(host);
    intersection.observe(host);
    document.addEventListener("visibilitychange", onVisibility);
    start();

    return () => {
      stop();
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
    };
  }, [prefersReducedMotion]);

  // Repaint the still frame when the theme changes under it.
  useEffect(() => {
    repaint.current();
  }, [paper, ink, edge]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ filter: `hue-rotate(${hue}deg) saturate(${saturation})` }}
      />
    </div>
  );
}
```

---

# Forecast Curve

> A rising dotted curve whose dots swell and shimmer in crossing waves, inked in the theme accent.

Install: `npx @modus-ui/cli add forecast-curve`

A 2D canvas samples a curve that dips low in the middle and lifts toward both edges, like a chart line climbing out of a trough. Each dot on a sparse grid grows with its closeness to the curve and shimmers in crossing waves: cores are drawn in `--primary`, edges in `--muted-foreground`, on `--background`. In dark mode the dots blend additively. It follows palette and mode changes live. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add forecast-curve
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/forecast-curve.tsx`.
3. Paste the code.

## Usage

```tsx
import { ForecastCurve } from "@/components/ui/forecast-curve";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ForecastCurve />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                                            |
| :---------------- | :------- | :------------------- | :--------------------------------------------------------------------- |
| `speed`           | `number` | `1`                  | Wave speed multiplier.                                                 |
| `spacing`         | `number` | `7`                  | Grid spacing between dots in pixels.                                   |
| `dotSize`         | `number` | `5`                  | Maximum dot size in pixels.                                            |
| `archHeight`      | `number` | `0.5`                | How far the curve rises toward the sides, as a fraction of the height. |
| `thickness`       | `number` | `1`                  | Thickness multiplier of the curve band.                                |
| `brightness`      | `number` | `1`                  | Dot opacity multiplier.                                                |
| `hue`             | `number` | `0`                  | Hue rotation in degrees.                                               |
| `saturation`      | `number` | `1`                  | Saturation multiplier.                                                 |
| `backgroundColor` | `string` | theme `--background` | Scene background.                                                      |

## Source

`components/ui/forecast-curve.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Predictive Arc (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const readToken = (name: string) =>
  getComputedStyle(document.documentElement).getPropertyValue(name).trim();

export interface ForecastCurveProps {
  speed?: number;
  spacing?: number;
  dotSize?: number;
  archHeight?: number;
  thickness?: number;
  brightness?: number;
  hue?: number;
  saturation?: number;
  backgroundColor?: string;
  className?: string;
}

export function ForecastCurve({
  speed = 1,
  spacing = 7,
  dotSize = 5,
  archHeight = 0.5,
  thickness = 1,
  brightness = 1,
  hue = 0,
  saturation = 1,
  backgroundColor,
  className,
}: ForecastCurveProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({
    speed,
    spacing,
    dotSize,
    archHeight,
    thickness,
    brightness,
    backgroundColor,
  });
  options.current = {
    speed,
    spacing,
    dotSize,
    archHeight,
    thickness,
    brightness,
    backgroundColor,
  };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const context = canvas?.getContext("2d", { alpha: false });
    if (!host || !canvas || !context) return;

    let width = 1;
    let height = 1;
    let time = 0;
    let background = "";
    let accent = "";
    let ink = "";
    let isLight = true;
    const readTheme = () => {
      background = readToken("--background");
      accent = readToken("--primary");
      ink = readToken("--muted-foreground");
      isLight = Number.parseFloat(background.split(/\s+/)[2] ?? "100") > 50;
    };
    readTheme();

    const resize = () => {
      const bounds = host.getBoundingClientRect();
      width = Math.max(1, bounds.width);
      height = Math.max(1, bounds.height);
      const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.round(width * pixelRatio);
      canvas.height = Math.round(height * pixelRatio);
      context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
    };

    const render = () => {
      const o = options.current;
      context.fillStyle = o.backgroundColor ?? `hsl(${background})`;
      context.fillRect(0, 0, width, height);
      time += 0.015 * o.speed;

      const centerX = width / 2;
      // A rising curve: low in the middle, lifting toward both edges.
      const archPeakY = height * 0.72;
      const archWidth = width * 1.5;
      const archHeight = height * o.archHeight;
      context.globalCompositeOperation = isLight ? "source-over" : "lighter";

      for (let x = 0; x < width; x += o.spacing) {
        const normX = (x - centerX) / (archWidth / 2);
        const curveY = archPeakY - normX * normX * archHeight;
        for (let y = 0; y < height; y += o.spacing) {
          const distanceToCurve = Math.abs(y - curveY);
          const band = (90 + (1 - Math.abs(normX)) * 60) * o.thickness;
          if (distanceToCurve >= band) continue;
          let intensity = 1 - distanceToCurve / band;
          const waveX = Math.sin(x * 0.015 + time);
          const waveY = Math.cos(y * 0.02 + time);
          intensity = intensity * 0.7 + waveX * waveY * 0.3 * intensity;
          intensity *= Math.max(0, 1 - Math.pow(Math.abs(normX), 2.5));
          if (intensity <= 0.02) continue;

          // Cores take the accent; the band's edges stay in muted ink.
          const alpha = Math.min(1, intensity * o.brightness);
          context.fillStyle = `hsl(${intensity > 0.6 ? accent : ink} / ${alpha.toFixed(2)})`;
          context.fillRect(x, y, o.dotSize * intensity, o.dotSize * intensity);
        }
      }
      context.globalCompositeOperation = "source-over";
    };

    let frame = 0;
    let visible = true;
    const tick = () => {
      render();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || frame || !visible || document.hidden) return;
      frame = requestAnimationFrame(tick);
    };
    const stop = () => {
      if (frame) cancelAnimationFrame(frame);
      frame = 0;
    };

    const resizeObserver = new ResizeObserver(() => {
      resize();
      render();
    });
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else stop();
    });
    const onVisibility = () => (document.hidden ? stop() : start());

    resize();
    render();
    resizeObserver.observe(host);
    intersection.observe(host);
    document.addEventListener("visibilitychange", onVisibility);
    start();
    const themeObserver = new MutationObserver(() => {
      readTheme();
      render();
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });

    return () => {
      stop();
      themeObserver.disconnect();
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
    };
  }, [prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        className="block h-full w-full"
        style={{ filter: `hue-rotate(${hue}deg) saturate(${saturation})` }}
      />
    </div>
  );
}
```

---

# Dew Pane

> Fine beads of dew that grow, merge and run down a pane, drawn in theme ink.

Install: `npx @modus-ui/cli add dew-pane`

A 2D canvas simulates beads that grow in place, then run down, swallowing smaller beads in their path and leaving a primary ripple at the bottom edge. Beads use the theme's muted ink with a paper glint; every colour can be overridden. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add dew-pane
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/dew-pane.tsx`.
3. Paste the code.

## Usage

```tsx
import { DewPane } from "@/components/ui/dew-pane";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <DewPane />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default     | Description                                                             |
| :---------------- | :------- | :---------- | :---------------------------------------------------------------------- |
| `speed`           | `number` | `0.8`       | Simulation speed multiplier.                                            |
| `dropAmount`      | `number` | `1.5`       | Multiplier on the maximum number of beads.                              |
| `opacity`         | `number` | `1`         | Overall opacity of the beads.                                           |
| `dropColor`       | `string` | `undefined` | Hex override for the bead body. Defaults to the theme muted foreground. |
| `edgeColor`       | `string` | `undefined` | Hex override for the bead rim. Defaults to the theme foreground.        |
| `highlightColor`  | `string` | `undefined` | Hex override for the glint. Defaults to the theme background.           |
| `splashColor`     | `string` | `undefined` | Hex override for the ripple. Defaults to the theme primary.             |
| `backgroundColor` | `string` | `undefined` | CSS background. Defaults to the theme background.                       |

## Source

`components/ui/dew-pane.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Condensation (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface DewPaneProps {
  speed?: number;
  dropAmount?: number;
  opacity?: number;
  /** Hex override for the drop body. Defaults to the theme's muted foreground. */
  dropColor?: string;
  /** Hex override for the drop rim. Defaults to the theme foreground. */
  edgeColor?: string;
  /** Hex override for the glint. Defaults to the theme background. */
  highlightColor?: string;
  /** Hex override for the splash ring. Defaults to the theme primary. */
  splashColor?: string;
  /** CSS background. Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Drop = {
  x: number;
  y: number;
  r: number;
  rMax: number;
  grow: number;
  running: boolean;
  vy: number;
};

type Splash = { x: number; y: number; r0: number; born: number };

const TOKENS = [
  "primary",
  "foreground",
  "background",
  "muted-foreground",
  "border",
  "card",
] as const;
type Tokens = Record<(typeof TOKENS)[number], string>;

/** Bare HSL channels of the Modus theme tokens, re-read when the theme or palette changes. */
function useThemeTokens(): Tokens | null {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const next = Object.fromEntries(
        TOKENS.map((name) => [name, style.getPropertyValue(`--${name}`).trim()]),
      ) as Tokens;
      setTokens((prev) => (prev && TOKENS.every((k) => prev[k] === next[k]) ? prev : next));
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

const hexRgb = (hex: string) => {
  const value = hex.replace("#", "");
  const full = value.length === 3 ? [...value].map((c) => c + c).join("") : value;
  const n = parseInt(full, 16);
  return `${(n >> 16) & 255},${(n >> 8) & 255},${n & 255}`;
};

/** A canvas colour at an alpha: a hex override, or theme channels. */
const tint = (override: string | undefined, channels: string) =>
  override
    ? (alpha: number) => `rgba(${hexRgb(override)},${alpha})`
    : (alpha: number) => `hsl(${channels} / ${alpha})`;

export function DewPane({
  speed = 0.8,
  dropAmount = 1.5,
  opacity = 1,
  dropColor,
  edgeColor,
  highlightColor,
  splashColor,
  backgroundColor,
  className,
}: DewPaneProps) {
  const tokens = useThemeTokens();
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({ speed, dropAmount });
  options.current = { speed, dropAmount };
  const colors = tokens
    ? [
        tint(dropColor, tokens["muted-foreground"]),
        tint(edgeColor, tokens.foreground),
        tint(highlightColor, tokens.background),
        tint(splashColor, tokens.primary),
      ]
    : null;
  const colorKey = tokens
    ? [dropColor, edgeColor, highlightColor, splashColor, ...Object.values(tokens)].join("|")
    : "";
  const colorsRef = useRef(colors);
  colorsRef.current = colors;

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    const palette = colorsRef.current;
    if (!host || !canvas || !ctx || !palette) return;

    let width = 1;
    let height = 1;
    let dpr = 1;
    let floorY = 1;
    let baseMaxDrops = 120;
    let lastCascade = 0;
    let now = 0;
    let last = 0;
    let drops: Drop[] = [];
    let splashes: Splash[] = [];
    const [dropTint, edgeTint, shineTint, splashTint] = palette;
    const sprites = new Map<number, HTMLCanvasElement>();

    const sprite = (radius: number) => {
      const key = Math.max(0.5, Math.round(radius * 2) / 2);
      const cached = sprites.get(key);
      if (cached) return cached;
      const padding = Math.ceil(2 * dpr);
      const size = Math.ceil(key * 2 + padding * 2);
      const element = document.createElement("canvas");
      element.width = size;
      element.height = size;
      const c = element.getContext("2d");
      if (!c) return element;
      const center = size / 2;
      const lit = key / (4.4 * dpr);
      c.fillStyle = dropTint(0.18 + lit * 0.22);
      c.beginPath();
      c.arc(center, center, key, 0, Math.PI * 2);
      c.fill();
      c.strokeStyle = edgeTint(0.35 + lit * 0.35);
      c.lineWidth = 0.9 * dpr;
      c.stroke();
      c.fillStyle = shineTint(0.55 + lit * 0.3);
      c.beginPath();
      c.arc(
        center - key * 0.32,
        center - key * 0.36,
        Math.max(0.45 * dpr, key * 0.24),
        0,
        Math.PI * 2,
      );
      c.fill();
      sprites.set(key, element);
      return element;
    };

    const maxDrops = () => Math.round(baseMaxDrops * options.current.dropAmount);

    const seedDrop = (headStart = 0) => {
      const margin = 8 * dpr;
      drops.push({
        x: margin + Math.random() * Math.max(1, width - margin * 2),
        y: margin + Math.random() * Math.max(1, floorY - margin * 2),
        r: (0.5 + headStart * 0.7) * dpr,
        rMax: (1.6 + Math.random() * 3.4) * dpr,
        grow: (0.0022 + Math.random() * 0.0032) * dpr,
        running: false,
        vy: 0,
      });
    };

    const step = (motion: number) => {
      if (drops.length < maxDrops() && Math.random() < 0.34 * motion) seedDrop();
      if (now - lastCascade > 6400) {
        lastCascade = now;
        drops
          .filter((drop) => !drop.running)
          .sort((a, b) => b.r - a.r)
          .slice(0, 3)
          .forEach((drop) => {
            drop.running = true;
            drop.vy = 0.35 * dpr;
          });
      }
      for (let index = drops.length - 1; index >= 0; index--) {
        const drop = drops[index];
        if (!drop.running) {
          drop.r += drop.grow * motion;
          if (drop.r >= drop.rMax) {
            drop.running = true;
            drop.vy = 0.3 * dpr;
          }
          continue;
        }
        drop.vy = Math.min(drop.vy + 0.075 * dpr * motion, 5.4 * dpr);
        drop.y += drop.vy * motion;
        // Running drops swallow the still ones in their path.
        for (let other = drops.length - 1; other >= 0; other--) {
          const o = drops[other];
          if (o === drop || o.running) continue;
          const overlapsX = Math.abs(o.x - drop.x) < drop.r + o.r + 1.5 * dpr;
          const overlapsY = o.y > drop.y - drop.r && o.y < drop.y + drop.vy + drop.r;
          if (overlapsX && overlapsY) {
            drop.r = Math.sqrt(drop.r * drop.r + o.r * o.r);
            drops.splice(other, 1);
            if (other < index) index--;
          }
        }
        if (drop.y >= floorY) {
          splashes.push({ x: drop.x, y: floorY, r0: drop.r, born: now });
          drops.splice(index, 1);
        }
      }
      splashes = splashes.filter((splash) => now - splash.born < 760);
    };

    const render = () => {
      ctx.clearRect(0, 0, width, height);
      drops.forEach((drop) => {
        const image = sprite(drop.r);
        ctx.drawImage(image, drop.x - image.width / 2, drop.y - image.height / 2);
      });
      splashes.forEach((splash) => {
        const progress = (now - splash.born) / 760;
        if (progress < 0 || progress > 1) return;
        const radius = splash.r0 + progress * 16 * dpr;
        ctx.lineWidth = 1.1 * dpr;
        ctx.strokeStyle = splashTint((1 - progress) * 0.7);
        ctx.beginPath();
        ctx.ellipse(splash.x, splash.y, radius, radius * 0.34, 0, 0, Math.PI * 2);
        ctx.stroke();
      });
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      dpr = Math.min(window.devicePixelRatio || 1, 2);
      width = canvas.width = Math.max(1, Math.floor(rect.width * dpr));
      height = canvas.height = Math.max(1, Math.floor(rect.height * dpr));
      floorY = Math.max(1, height - 2 * dpr);
      baseMaxDrops = Math.max(80, Math.min(240, Math.round((width * height) / (dpr * dpr) / 5200)));
      drops = [];
      splashes = [];
      sprites.clear();
      const seedCount = Math.round(maxDrops() * 0.62);
      for (let i = 0; i < seedCount; i++) seedDrop(Math.random() * 3);
      render();
    };

    let frame = 0;
    let visible = true;
    const tick = (time: number) => {
      const delta = last ? Math.min(50, time - last) : 16.67;
      last = time;
      now += delta * options.current.speed;
      step(options.current.speed);
      render();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || frame) return;
      last = 0;
      frame = requestAnimationFrame(tick);
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && visible && start();
    document.addEventListener("visibilitychange", onVisibility);

    resizeObserver.observe(host);
    intersection.observe(host);
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      drops = [];
      splashes = [];
      sprites.clear();
    };
  }, [prefersReducedMotion, colorKey]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas ref={canvasRef} className="block h-full w-full" style={{ opacity }} />
    </div>
  );
}
```

---

# Ink Pill

> A mono-set pill call-to-action washed in the theme's ink, with a diamond glyph and a paper-card sibling.

Install: `npx @modus-ui/cli add ink-pill`

A pill call-to-action set in uppercase mono. The primary variant is an ink wash of the theme's primary colour that thins toward the paper, with a soft shadow and a small diamond glyph, and brightens on hover. The ghost variant is a card-coloured pill with a hairline border. Both follow the active theme and palette in light and dark mode. Hue, saturation and brightness grade the button with a CSS filter, and transitions are switched off when the user prefers reduced motion. The component centres the button in its parent and is transparent unless you pass `background`.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-pill
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ink-pill.tsx`.
4. Paste the code.

## Usage

```tsx
import { InkPill } from "@/components/ui/ink-pill";

export default function Example() {
  return (
    <div className="h-[300px] w-full">
      <InkPill label="Get started" onClick={() => console.log("clicked")} />
    </div>
  );
}
```

## Props

| Prop         | Type                                   | Default           | Description                                      |
| :----------- | :------------------------------------- | :---------------- | :----------------------------------------------- |
| `variant`    | `"primary" \| "ghost"`                 | `"primary"`       | Ink wash pill or card pill.                      |
| `label`      | `string`                               | `"Begin a draft"` | Button text.                                     |
| `ring`       | `boolean`                              | `true`            | Shows the small diamond glyph after the label.   |
| `hue`        | `number`                               | `0`               | Hue rotation in degrees, clamped to -180 to 180. |
| `saturation` | `number`                               | `1`               | Saturation multiplier, clamped to 0 to 2.        |
| `brightness` | `number`                               | `1`               | Brightness multiplier, clamped to 0.35 to 1.65.  |
| `disabled`   | `boolean`                              | `false`           | Disables the button.                             |
| `type`       | `"button" \| "submit" \| "reset"`      | `"button"`        | Native button type.                              |
| `onClick`    | `MouseEventHandler<HTMLButtonElement>` | `undefined`       | Click handler.                                   |
| `background` | `string`                               | `undefined`       | Stage background; transparent when omitted.      |

## Source

`components/ui/ink-pill.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Lumen CTA (MIT, © 2026 Meng To).

import type { CSSProperties, MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface InkPillProps {
  variant?: "primary" | "ghost";
  label?: string;
  ring?: boolean;
  hue?: number;
  saturation?: number;
  brightness?: number;
  disabled?: boolean;
  type?: "button" | "submit" | "reset";
  onClick?: MouseEventHandler<HTMLButtonElement>;
  background?: string;
  className?: string;
}

const clamp = (value: number, minimum: number, maximum: number) =>
  Math.min(maximum, Math.max(minimum, value));

// An ink wash: full primary on the left, thinning into the paper on the right.
const INK_WASH =
  "linear-gradient(100deg, hsl(var(--primary)) 0%, hsl(var(--primary)) 45%, color-mix(in oklab, hsl(var(--primary)) 62%, hsl(var(--background))) 100%)";

export function InkPill({
  variant = "primary",
  label = "Begin a draft",
  ring = true,
  hue = 0,
  saturation = 1,
  brightness = 1,
  disabled = false,
  type = "button",
  onClick,
  background,
  className,
}: InkPillProps) {
  const prefersReducedMotion = useReducedMotion();
  const ghost = variant === "ghost";
  const grade = `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)})`;
  const level = clamp(brightness, 0.35, 1.65);
  const transition = prefersReducedMotion
    ? "none"
    : "filter 0.25s ease, background 0.25s ease, transform 0.25s ease";

  const buttonStyle: CSSProperties = ghost
    ? { filter: `${grade} brightness(${level})`, transition }
    : {
        background: INK_WASH,
        boxShadow:
          "0 10px 24px -12px hsl(var(--primary) / 0.55), inset 0 1px 0 hsl(var(--primary-foreground) / 0.18)",
        filter: `${grade} brightness(calc(${level} * var(--ink-pill-lift, 1)))`,
        transition,
      };

  return (
    <div
      className={cn(
        "relative isolate grid h-full min-h-0 w-full min-w-0 place-items-center overflow-hidden",
        className,
      )}
      style={background ? { background } : undefined}
    >
      <button
        type={type}
        disabled={disabled}
        onClick={onClick}
        className={cn(
          "relative inline-flex h-12 cursor-pointer appearance-none items-center gap-3 whitespace-nowrap rounded-full border-0 pl-7 pr-5 font-mono text-[12px] font-medium uppercase leading-none tracking-[0.18em]",
          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[3px] focus-visible:outline-[hsl(var(--primary))]",
          "disabled:cursor-default disabled:opacity-55",
          !prefersReducedMotion && "active:enabled:translate-y-px",
          ghost
            ? "bg-[hsl(var(--card))] text-foreground ring-1 ring-[hsl(var(--border))] hover:enabled:bg-[hsl(var(--primary)/0.08)]"
            : "text-[hsl(var(--primary-foreground))] hover:enabled:[--ink-pill-lift:1.12]",
        )}
        style={buttonStyle}
      >
        {label}
        {ring ? (
          <i
            aria-hidden="true"
            className={cn(
              "h-[7px] w-[7px] flex-none rotate-45 border-[1.3px] border-solid",
              ghost ? "border-[hsl(var(--primary))]" : "border-[hsl(var(--primary-foreground))]",
            )}
          />
        ) : null}
      </button>
    </div>
  );
}
```

---

# Glyph Eddy

> Turning rings of set type that crumble into glyph dust under the cursor and gather into the centre on click, drawn in the Modus type and theme ink.

Install: `npx @modus-ui/cli add glyph-eddy`

Turning rings of set type that crumble into glyph dust under the cursor and gather into the centre on click, drawn in the Modus type and theme ink. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add glyph-eddy
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/glyph-eddy.tsx`.
3. Paste the code.

## Usage

```tsx
import { GlyphEddy } from "@/components/ui/glyph-eddy";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <GlyphEddy />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                                 | Description                                          |
| :---------------- | :------- | :-------------------------------------- | :--------------------------------------------------- |
| `phrase`          | `string` | `"MODUS / FORM FOLLOWS MOTION / "`      | Text repeated around every ring.                     |
| `speed`           | `number` | `0.8`                                   | Ring rotation speed multiplier.                      |
| `ringGrowth`      | `number` | `1.15`                                  | Radius ratio between neighbouring rings (min 1.08).  |
| `opacity`         | `number` | `1`                                     | Overall opacity of the type, guides and dust.        |
| `dissolveRadius`  | `number` | `1`                                     | Size multiplier of the hole carved by the pointer.   |
| `particleAmount`  | `number` | `1`                                     | How much dust the pointer sheds.                     |
| `suctionDuration` | `number` | `920`                                   | Length of the click gather in milliseconds.          |
| `hint`            | `string` | `"Hover to dissolve · Click to gather"` | Caption at the bottom; pass an empty string to hide. |

## Source

`components/ui/glyph-eddy.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Typography Vortex (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type GlyphEddyOptions = {
  theme: Theme;
  phrase: string;
  speed: number;
  ringGrowth: number;
  opacity: number;
  dissolveRadius: number;
  particleAmount: number;
  suctionDuration: number;
};

interface GlyphEddyProps {
  phrase?: string;
  speed?: number;
  ringGrowth?: number;
  opacity?: number;
  dissolveRadius?: number;
  particleAmount?: number;
  suctionDuration?: number;
  hint?: string;
  className?: string;
}

const NOISE =
  "url(\"data:image/svg+xml,%3Csvg viewBox='0 0 180 180' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.85' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='.16'/%3E%3C/svg%3E\")";

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const css = (c: Rgb, alpha = 1) => `rgb(${c.map((v) => Math.round(v * 255)).join(" ")} / ${alpha})`;

type Ring = {
  radius: number;
  fontSize: number;
  alpha: number;
  speed: number;
  offset: number;
  spacing: number;
  wobble: number;
  bitmap: HTMLCanvasElement;
  size: number;
};

type Stray = {
  radius: number;
  angle: number;
  speed: number;
  character: string;
  alpha: number;
  fontSize: number;
};

type Dust = {
  x: number;
  y: number;
  velocityX: number;
  velocityY: number;
  size: number;
  life: number;
  maxLife: number;
  phase: number;
  spin: number;
  color: string;
  sucked: boolean;
};

const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));
const lerp = (from: number, to: number, amount: number) => from + (to - from) * amount;
const mulberry32 = (seed: number) => () => {
  seed |= 0;
  seed = (seed + 0x6d2b79f5) | 0;
  let value = Math.imul(seed ^ (seed >>> 15), 1 | seed);
  value = (value + Math.imul(value ^ (value >>> 7), 61 | value)) ^ value;
  return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
};

function createGlyphEddyRenderer(
  host: HTMLElement,
  canvas: HTMLCanvasElement,
  getOptions: () => GlyphEddyOptions,
  reduced: boolean,
) {
  const context = canvas.getContext("2d");
  const layer = document.createElement("canvas");
  const layerContext = layer.getContext("2d", { willReadFrequently: true });
  if (!context || !layerContext) return () => undefined;

  const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
  const pointer = { x: 0, y: 0, inside: false };
  const suction = { x: 0, y: 0, started: 0, until: 0 };
  let width = 0;
  let height = 0;
  let rings: Ring[] = [];
  let strays: Stray[] = [];
  let particles: Dust[] = [];
  let dissolve = 0;
  let lastSpawn = 0;
  let lastAmbientSpawn = 0;
  let lastTime = 0;
  let stateFrame = 0;
  let frame = 0;
  let visible = true;
  let renderSignature = "";
  // The host carries `font-mono`, so this is the palette's mono stack.
  const fontFamily = getComputedStyle(host).fontFamily;

  const buildRings = () => {
    const options = getOptions();
    const phrase = options.phrase || "MODUS / FORM FOLLOWS MOTION / ";
    const random = mulberry32(11 * 29 + 5);
    const ringPixelRatio = Math.max(pixelRatio, 1.5);
    const maximumRadius =
      Math.hypot(Math.max(width * 0.55, width * 0.48), Math.max(height * 0.52, height * 0.5)) + 40;
    rings = [];
    let radius = Math.max(26, width * 0.038);
    let index = 0;
    while (radius < maximumRadius) {
      const sparse = index % 3 === 2;
      const ringBase = {
        radius,
        fontSize: clamp(7 + radius * 0.015, 7, 17),
        alpha:
          clamp(0.34 + radius / maximumRadius, 0.36, 0.92) * (sparse ? 0.72 : 1) * options.opacity,
        speed: (0.05 + 40 / (radius + 60)) * 0.35,
        offset: random() * Math.PI * 2,
        spacing: sparse ? 2.4 + random() * 1.2 : 1.02 + random() * 0.14,
        wobble: random() * Math.PI * 2,
      };
      const size = Math.ceil((ringBase.radius + ringBase.fontSize * 2) * 2);
      const bitmap = document.createElement("canvas");
      bitmap.width = bitmap.height = Math.ceil(size * ringPixelRatio);
      const bitmapContext = bitmap.getContext("2d");
      if (!bitmapContext) break;
      bitmapContext.scale(ringPixelRatio, ringPixelRatio);
      bitmapContext.translate(size / 2, size / 2);
      bitmapContext.font = `${ringBase.fontSize}px ${fontFamily}`;
      bitmapContext.textAlign = "center";
      bitmapContext.textBaseline = "middle";
      // Every fourth ring is set in the accent colour.
      const ink = index % 4 === 1 ? options.theme.primary : options.theme.foreground;
      bitmapContext.fillStyle = css(ink, ringBase.alpha);
      const step = (ringBase.fontSize * 0.62 * ringBase.spacing) / ringBase.radius;
      const count = Math.max(4, Math.floor((Math.PI * 2) / step));
      const actualStep = (Math.PI * 2) / count;
      for (let characterIndex = 0; characterIndex < count; characterIndex += 1) {
        const angle = characterIndex * actualStep;
        const character = phrase[characterIndex % phrase.length];
        if (character === " ") continue;
        bitmapContext.save();
        bitmapContext.translate(
          Math.cos(angle) * ringBase.radius,
          Math.sin(angle) * ringBase.radius,
        );
        bitmapContext.rotate(angle + Math.PI / 2);
        bitmapContext.fillText(character, 0, 0);
        bitmapContext.restore();
      }
      rings.push({ ...ringBase, bitmap, size });
      radius *= Math.max(1.08, options.ringGrowth);
      index += 1;
    }

    strays = [];
    for (let strayIndex = 0; strayIndex < 34; strayIndex += 1) {
      strays.push({
        radius: 30 + random() * (maximumRadius - 60),
        angle: random() * Math.PI * 2,
        speed: (random() - 0.5) * 0.06,
        character: phrase[(random() * phrase.length) | 0],
        alpha: (0.18 + random() * 0.3) * options.opacity,
        fontSize: 8 + random() * 6,
      });
    }
  };

  const resize = () => {
    const bounds = host.getBoundingClientRect();
    width = Math.max(1, bounds.width);
    height = Math.max(1, bounds.height);
    canvas.width = Math.round(width * pixelRatio);
    canvas.height = Math.round(height * pixelRatio);
    layer.width = Math.round(width * pixelRatio);
    layer.height = Math.round(height * pixelRatio);
    context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
    layerContext.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
    particles = [];
    renderSignature = "";
  };

  const spawnPointerDust = (time: number, radius: number) => {
    const options = getOptions();
    if (
      reduced ||
      time < suction.until ||
      !pointer.inside ||
      dissolve < 0.08 ||
      time - lastSpawn < 44
    )
      return;
    lastSpawn = time;
    const x0 = Math.max(0, Math.floor((pointer.x - radius) * pixelRatio));
    const y0 = Math.max(0, Math.floor((pointer.y - radius) * pixelRatio));
    const x1 = Math.min(layer.width, Math.ceil((pointer.x + radius) * pixelRatio));
    const y1 = Math.min(layer.height, Math.ceil((pointer.y + radius) * pixelRatio));
    if (x1 <= x0 || y1 <= y0) return;
    const sampleWidth = x1 - x0;
    const sampleHeight = y1 - y0;
    const pixels = layerContext.getImageData(x0, y0, sampleWidth, sampleHeight).data;
    const sampleStep = Math.max(4, Math.round(4.5 * pixelRatio));
    const spawnLimit = Math.max(1, Math.round(44 * options.particleAmount));
    let spawned = 0;
    for (let y = 0; y < sampleHeight && spawned < spawnLimit; y += sampleStep) {
      for (let x = 0; x < sampleWidth && spawned < spawnLimit; x += sampleStep) {
        const pixelIndex = (y * sampleWidth + x) * 4;
        const alpha = pixels[pixelIndex + 3];
        if (alpha < 34 || Math.random() > 0.34) continue;
        const particleX = (x0 + x) / pixelRatio;
        const particleY = (y0 + y) / pixelRatio;
        const deltaX = particleX - pointer.x;
        const deltaY = particleY - pointer.y;
        const distance = Math.hypot(deltaX, deltaY);
        if (distance > radius || distance < radius * 0.16) continue;
        const normalX = deltaX / Math.max(1, distance);
        const normalY = deltaY / Math.max(1, distance);
        const burst = 0.35 + Math.random() * 1.35;
        const tangent = (Math.random() - 0.5) * 1.4;
        particles.push({
          x: particleX,
          y: particleY,
          velocityX: normalX * burst - normalY * tangent + (Math.random() - 0.5) * 0.35,
          velocityY: normalY * burst + normalX * tangent - 0.15 + Math.random() * 0.55,
          size: 0.65 + Math.random() * 1.55,
          life: 560 + Math.random() * 620,
          maxLife: 1180,
          phase: Math.random() * Math.PI * 2,
          spin: Math.random() > 0.5 ? 1 : -1,
          color: `${pixels[pixelIndex]} ${pixels[pixelIndex + 1]} ${pixels[pixelIndex + 2]}`,
          sucked: false,
        });
        spawned += 1;
      }
    }
    const maximum = Math.max(1, Math.round(720 * options.particleAmount));
    if (particles.length > maximum) particles.splice(0, particles.length - maximum);
  };

  const spawnAmbientDust = (time: number, ambientWidth: number) => {
    const options = getOptions();
    if (reduced || time < suction.until || time - lastAmbientSpawn < 115) return;
    lastAmbientSpawn = time;
    const sampleWidth = Math.min(width, ambientWidth * 1.12);
    const pixelWidth = Math.max(1, Math.floor(sampleWidth * pixelRatio));
    const pixelHeight = Math.max(1, Math.floor(height * pixelRatio));
    const pixels = layerContext.getImageData(0, 0, pixelWidth, pixelHeight).data;
    const spawnLimit = Math.max(1, Math.round(16 * options.particleAmount));
    let spawned = 0;
    for (let attempt = 0; attempt < 520 && spawned < spawnLimit; attempt += 1) {
      const x = (Math.random() * pixelWidth) | 0;
      const y = (Math.random() * pixelHeight) | 0;
      const pixelIndex = (y * pixelWidth + x) * 4;
      if (pixels[pixelIndex + 3] < 32) continue;
      const particleX = x / pixelRatio;
      const particleY = y / pixelRatio;
      const edge = clamp(particleX / sampleWidth, 0, 1);
      particles.push({
        x: particleX,
        y: particleY,
        velocityX: 0.18 + Math.random() * 0.8 + edge * 0.35,
        velocityY: (Math.random() - 0.5) * 0.8,
        size: 0.55 + Math.random() * 1.35,
        life: 620 + Math.random() * 520,
        maxLife: 1140,
        phase: Math.random() * Math.PI * 2,
        spin: Math.random() > 0.5 ? 1 : -1,
        color: `${pixels[pixelIndex]} ${pixels[pixelIndex + 1]} ${pixels[pixelIndex + 2]}`,
        sucked: false,
      });
      spawned += 1;
    }
    const maximum = Math.max(1, Math.round(720 * options.particleAmount));
    if (particles.length > maximum) particles.splice(0, particles.length - maximum);
  };

  const updateDust = (time: number, deltaTime: number) => {
    const options = getOptions();
    const step = clamp(deltaTime / 16.67, 0.25, 3);
    const suctionActive = !reduced && time < suction.until;
    const alive: Dust[] = [];
    for (const particle of particles) {
      particle.life -= deltaTime;
      if (particle.life <= 0 || (particle.sucked && !suctionActive)) continue;
      let distanceToSink = Infinity;
      if (suctionActive && particle.sucked) {
        const deltaX = suction.x - particle.x;
        const deltaY = suction.y - particle.y;
        distanceToSink = Math.hypot(deltaX, deltaY);
        if (distanceToSink < 5) continue;
        const targetSpeed = clamp(distanceToSink * 0.078, 3.2, 28);
        const pull = 1 - Math.pow(0.76, step);
        particle.velocityX = lerp(
          particle.velocityX,
          (deltaX / distanceToSink) * targetSpeed,
          pull,
        );
        particle.velocityY = lerp(
          particle.velocityY,
          (deltaY / distanceToSink) * targetSpeed,
          pull,
        );
      } else {
        const swirl = Math.sin(time * 0.0024 + particle.phase) * 0.018 * particle.spin;
        particle.velocityX +=
          Math.cos(particle.phase + time * 0.0017) * 0.012 * step - swirl * particle.velocityY;
        particle.velocityY += 0.018 * step + swirl * particle.velocityX;
        particle.velocityX *= Math.pow(0.987, step);
        particle.velocityY *= Math.pow(0.991, step);
      }
      particle.x += particle.velocityX * step;
      particle.y += particle.velocityY * step;
      const sinkFade = suctionActive && particle.sucked ? clamp(distanceToSink / 42, 0.12, 1) : 1;
      const alpha =
        clamp(particle.life / Math.min(particle.maxLife, 820), 0, 1) * sinkFade * options.opacity;
      context.fillStyle = `rgb(${particle.color} / ${alpha * 0.88})`;
      const size = particle.size * (0.5 + alpha * 0.5);
      context.fillRect(particle.x - size * 0.5, particle.y - size * 0.5, size, size);
      alive.push(particle);
    }
    particles = alive;
    if (suctionActive) {
      const progress = clamp((time - suction.started) / (suction.until - suction.started), 0, 1);
      context.save();
      context.strokeStyle = css(options.theme.primary, (1 - progress) * 0.5 * options.opacity);
      context.lineWidth = 1;
      context.beginPath();
      context.arc(suction.x, suction.y, 5 + progress * 22, 0, Math.PI * 2);
      context.stroke();
      context.fillStyle = css(options.theme.foreground, (1 - progress) * 0.62 * options.opacity);
      context.fillRect(suction.x - 1, suction.y - 1, 2, 2);
      context.restore();
    }
  };

  const draw = (time: number) => {
    const options = getOptions();
    const { theme } = options;
    const signature = `${theme.foreground}|${theme.primary}|${options.phrase}|${options.ringGrowth}|${options.opacity}|${width}|${height}`;
    if (signature !== renderSignature) {
      renderSignature = signature;
      buildRings();
    }
    context.clearRect(0, 0, width, height);
    context.fillStyle = css(theme.background);
    context.fillRect(0, 0, width, height);
    layerContext.clearRect(0, 0, width, height);
    const deltaTime = Math.min(time - (lastTime || time), 100);
    lastTime = time;
    const dissolveTarget = pointer.inside && !reduced ? 1 : 0;
    dissolve = lerp(dissolve, dissolveTarget, 1 - Math.pow(0.78, deltaTime / 16.6));
    if (dissolve < 0.002) dissolve = 0;
    const centerX = width * 0.5;
    const centerY = height * 0.5;
    const seconds = (time / 1000) * options.speed;

    context.save();
    context.translate(centerX, centerY);
    context.strokeStyle = css(theme["muted-foreground"], 0.22 * options.opacity);
    context.lineWidth = 1;
    context.setLineDash([3, 9]);
    for (const ring of rings) {
      context.beginPath();
      context.arc(0, 0, ring.radius * 1.115, 0, Math.PI * 2);
      context.stroke();
    }
    context.restore();

    layerContext.save();
    layerContext.translate(centerX, centerY);
    for (const ring of rings) {
      const base =
        ring.offset + seconds * ring.speed + Math.sin(seconds * 0.11 + ring.wobble) * 0.02;
      layerContext.save();
      layerContext.rotate(base);
      layerContext.drawImage(ring.bitmap, -ring.size / 2, -ring.size / 2, ring.size, ring.size);
      layerContext.restore();
    }
    layerContext.textAlign = "center";
    layerContext.textBaseline = "middle";
    for (const stray of strays) {
      const angle = stray.angle + seconds * stray.speed;
      layerContext.font = `${stray.fontSize}px ${fontFamily}`;
      layerContext.fillStyle = css(theme.primary, stray.alpha);
      layerContext.save();
      layerContext.translate(Math.cos(angle) * stray.radius, Math.sin(angle) * stray.radius);
      layerContext.rotate(angle + Math.PI / 2);
      layerContext.fillText(stray.character, 0, 0);
      layerContext.restore();
    }
    layerContext.restore();

    const ambientWidth = clamp(width * 0.22, 108, 180);
    const radius = clamp(Math.min(width, height) * 0.24, 128, 196) * options.dissolveRadius;
    spawnAmbientDust(time, ambientWidth);
    spawnPointerDust(time, radius);

    if (!reduced) {
      layerContext.save();
      layerContext.globalCompositeOperation = "destination-out";
      const ambientMask = layerContext.createLinearGradient(0, 0, ambientWidth, 0);
      ambientMask.addColorStop(0, "rgba(0,0,0,.98)");
      ambientMask.addColorStop(0.34, "rgba(0,0,0,.88)");
      ambientMask.addColorStop(0.72, "rgba(0,0,0,.36)");
      ambientMask.addColorStop(1, "rgba(0,0,0,0)");
      layerContext.fillStyle = ambientMask;
      layerContext.fillRect(0, 0, ambientWidth, height);
      layerContext.restore();
    }

    if (dissolve > 0.002) {
      const maskedRadius = radius * (0.42 + dissolve * 0.58);
      layerContext.save();
      layerContext.globalCompositeOperation = "destination-out";
      const mask = layerContext.createRadialGradient(
        pointer.x,
        pointer.y,
        maskedRadius * 0.06,
        pointer.x,
        pointer.y,
        maskedRadius,
      );
      mask.addColorStop(0, "rgba(0,0,0,1)");
      mask.addColorStop(0.57, "rgba(0,0,0,.98)");
      mask.addColorStop(0.84, "rgba(0,0,0,.42)");
      mask.addColorStop(1, "rgba(0,0,0,0)");
      layerContext.fillStyle = mask;
      layerContext.beginPath();
      layerContext.arc(pointer.x, pointer.y, maskedRadius, 0, Math.PI * 2);
      layerContext.fill();
      layerContext.restore();
    }

    context.drawImage(layer, 0, 0, layer.width, layer.height, 0, 0, width, height);
    updateDust(time, deltaTime);
    if (dissolve > 0.02) {
      context.save();
      context.strokeStyle = css(theme.primary, (0.12 + dissolve * 0.25) * options.opacity);
      context.lineWidth = 1;
      context.setLineDash([2, 6]);
      context.beginPath();
      context.arc(pointer.x, pointer.y, radius * (0.42 + dissolve * 0.58), 0, Math.PI * 2);
      context.stroke();
      context.restore();
    }

    if (++stateFrame % 5 === 0) {
      const suctionActive = !reduced && time < suction.until;
      host.dataset.dissolveState = reduced
        ? "reduced"
        : suctionActive
          ? "suction"
          : pointer.inside
            ? "active"
            : dissolve > 0.02
              ? "recovering"
              : "ambient";
      host.dataset.suctionState = suctionActive ? "active" : "idle";
      host.dataset.particles = String(particles.length);
      host.dataset.dissolveStrength = dissolve.toFixed(2);
    }
  };

  const animate = (time: number) => {
    draw(time);
    frame = visible && !document.hidden ? requestAnimationFrame(animate) : 0;
  };
  const locatePointer = (event: PointerEvent) => {
    const bounds = host.getBoundingClientRect();
    pointer.x = clamp(event.clientX - bounds.left, 0, bounds.width);
    pointer.y = clamp(event.clientY - bounds.top, 0, bounds.height);
    pointer.inside = true;
  };
  const onPointerLeave = () => {
    pointer.inside = false;
  };
  const onPointerDown = (event: PointerEvent) => {
    locatePointer(event);
    const options = getOptions();
    suction.x = pointer.x;
    suction.y = pointer.y;
    suction.started = performance.now();
    suction.until = suction.started + options.suctionDuration;
    for (const particle of particles) {
      particle.sucked = true;
      particle.life = Math.max(particle.life, options.suctionDuration + 20);
      particle.maxLife = Math.max(particle.maxLife, options.suctionDuration + 20);
    }
    host.dataset.suctionState = "active";
  };
  const onVisibility = () => {
    if (!document.hidden && visible && !frame) frame = requestAnimationFrame(animate);
  };
  const resizeObserver = new ResizeObserver(resize);
  const intersectionObserver = new IntersectionObserver(([entry]) => {
    visible = entry?.isIntersecting ?? true;
    if (visible && !frame && !document.hidden) frame = requestAnimationFrame(animate);
    if (!visible && frame) {
      cancelAnimationFrame(frame);
      frame = 0;
    }
  });

  host.addEventListener("pointerenter", locatePointer);
  host.addEventListener("pointermove", locatePointer);
  host.addEventListener("pointerleave", onPointerLeave);
  host.addEventListener("pointerdown", onPointerDown);
  document.addEventListener("visibilitychange", onVisibility);
  resizeObserver.observe(host);
  intersectionObserver.observe(host);
  resize();
  frame = requestAnimationFrame(animate);

  return () => {
    if (frame) cancelAnimationFrame(frame);
    resizeObserver.disconnect();
    intersectionObserver.disconnect();
    host.removeEventListener("pointerenter", locatePointer);
    host.removeEventListener("pointermove", locatePointer);
    host.removeEventListener("pointerleave", onPointerLeave);
    host.removeEventListener("pointerdown", onPointerDown);
    document.removeEventListener("visibilitychange", onVisibility);
  };
}

export function GlyphEddy({
  phrase = "MODUS / FORM FOLLOWS MOTION / ",
  speed = 0.8,
  ringGrowth = 1.15,
  opacity = 1,
  dissolveRadius = 1,
  particleAmount = 1,
  suctionDuration = 920,
  hint = "Hover to dissolve · Click to gather",
  className,
}: GlyphEddyProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = {
    theme: theme as Theme,
    phrase,
    speed,
    ringGrowth,
    opacity,
    dissolveRadius,
    particleAmount,
    suctionDuration,
  };
  const optionsRef = useRef(options);
  optionsRef.current = options;

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas || !theme) return undefined;
    return createGlyphEddyRenderer(
      host,
      canvas,
      () => optionsRef.current,
      Boolean(prefersReducedMotion),
    );
    // Only the first resolution matters here: later theme changes reach the renderer via optionsRef.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [prefersReducedMotion, Boolean(theme)]);

  return (
    <div
      ref={hostRef}
      className={cn(
        "absolute inset-0 isolate cursor-crosshair touch-none overflow-hidden [container-type:inline-size]",
        "bg-background font-mono",
        className,
      )}
      data-dissolve-state="ambient"
      data-suction-state="idle"
      data-particles="0"
      data-dissolve-strength="0.00"
    >
      <canvas
        ref={canvasRef}
        aria-label="Interactive glyph eddy"
        className="absolute inset-0 block h-full w-full"
      />
      {hint ? (
        <span className="pointer-events-none absolute bottom-4 left-4 z-[6] font-mono text-[10px] uppercase leading-none tracking-[0.2em] text-muted-foreground">
          {hint}
        </span>
      ) : null}
      <div
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 z-[5] opacity-[0.12] mix-blend-soft-light"
        style={{ backgroundImage: NOISE }}
      />
    </div>
  );
}
```

---

# Phosphor Tube

> A WebGL cathode-ray tube tinted with the theme tokens, showing a film countdown, a typing boot log, a fault report or a pixel-art title screen.

Install: `npx @modus-ui/cli add phosphor-tube`

A WebGL cathode-ray tube. Each variant paints its picture into an offscreen 2D canvas, then a fragment shader adds barrel curvature, scanlines, an aperture grille, chromatic fringing, phosphor halation, a rolling bar, flicker, grain and a vignette. By default the tube's light is mapped through the theme tokens, so its phosphor takes on the active palette in both light and dark mode; set `palette="original"` for the source phosphor colours.

- `countdown` (default) is a monochrome film leader: a sweeping 8 to 2 countdown, scrolling perforations, registration marks and a running timecode, then a title card set in the theme's heading font.
- `terminal` types out the Modus studio boot log with a status column and a blinking block cursor.
- `fault` is a fault report with analogue tracking jitter, a rolling dropout band and a head-switching scramble.
- `arcade` is a 320x180 pixel-art title screen, sampled with nearest filtering, where a runner jumps crates under a sweeping wordmark.

It pauses off screen. When the user prefers reduced motion it renders one still frame, with the terminal log fully typed.

## Installation

### CLI

```bash
npx @modus-ui/cli add phosphor-tube
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/phosphor-tube.tsx`.
4. Paste the code.

## Usage

```tsx
import { PhosphorTube } from "@/components/ui/phosphor-tube";

export default function Example() {
  return (
    <div className="relative h-[420px] w-full overflow-hidden">
      <PhosphorTube variant="terminal" />
    </div>
  );
}
```

## Props

| Prop         | Type                                               | Default       | Description                                                                                 |
| :----------- | :------------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------ |
| `variant`    | `"countdown" \| "terminal" \| "fault" \| "arcade"` | `"countdown"` | Which screen the tube shows.                                                                |
| `palette`    | `"theme" \| "original"`                            | `"theme"`     | `theme` tints the tube with the theme tokens; `original` keeps the source phosphor colours. |
| `speed`      | `number`                                           | `1`           | Time multiplier for the shader and animated screens.                                        |
| `typeSpeed`  | `number`                                           | `1`           | Terminal typing speed multiplier.                                                           |
| `motion`     | `number`                                           | `1`           | Strength of scanline drift, the rolling bar and flicker.                                    |
| `brightness` | `number`                                           | `1`           | CSS brightness applied to the whole tube.                                                   |
| `opacity`    | `number`                                           | `1`           | Opacity of the whole tube.                                                                  |
| `hue`        | `number`                                           | `0`           | Hue rotation in degrees.                                                                    |
| `saturation` | `number`                                           | `1`           | CSS saturation multiplier.                                                                  |

## Source

`components/ui/phosphor-tube.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's CRT (MIT, © 2026 Meng To).

import { useEffect, useId, useMemo, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const CRT_VERTEX_SHADER = "attribute vec2 aPos;\nvoid main(){ gl_Position = vec4(aPos,0.0,1.0); }";

const CRT_FRAGMENT_SHADER = `precision highp float;
uniform sampler2D uTex;
uniform vec2 uRes;
uniform float uTime;
uniform float uMotion;
uniform vec2 uCurve;
uniform float uScan;
uniform float uScanDepth;
uniform float uTriad;
uniform float uGrille;
uniform float uChroma;
uniform float uBar;
uniform float uFlicker;
uniform float uGrain;
uniform float uNoise;
uniform float uVignette;
uniform float uMono;
uniform float uGain;
uniform float uHalo;
uniform vec3 uSheen;
uniform vec3 uRoom;

float hash(vec2 p){ p=fract(p*vec2(123.34,456.21)); p+=dot(p,p+45.32); return fract(p.x*p.y); }

vec2 curve(vec2 uv){
  uv = uv*2.0-1.0;
  vec2 o = uv.yx*uv.yx;
  uv += uv * o * uCurve;
  uv = uv*0.5+0.5;
  return uv;
}

void main(){
  vec2 fuv = gl_FragCoord.xy / uRes;
  vec2 uv = curve(fuv);
  float t = uTime;

  /* analogue transport faults: per-row jitter, a rolling dropout band, and the
     head-switching scramble along the bottom edge of the raster */
  float band = 0.0;
  if (uNoise > 0.001){
    float row = floor(uv.y * 190.0);
    float gate = step(0.905, hash(vec2(row, floor(t*15.0))));
    uv.x += (hash(vec2(row*1.7, floor(t*15.0)+7.0)) - 0.5) * 0.052 * gate * uNoise;
    float pos = fract(uv.y * 0.8 - t * 0.17);
    band = smoothstep(0.075, 0.0, pos);
    uv.x += band * (hash(vec2(floor(uv.y*260.0), floor(t*26.0))) - 0.5) * 0.030 * uNoise;
    float head = smoothstep(0.030, 0.0, uv.y);
    uv.x += head * (hash(vec2(floor(uv.y*520.0), floor(t*22.0))) - 0.32) * 0.075 * uNoise;
    band = max(band, head);
  }

  vec2 inb = step(vec2(0.0), uv) * step(uv, vec2(1.0));
  float inside = inb.x*inb.y;
  vec2 ed = min(uv, 1.0-uv);
  inside *= smoothstep(0.0,0.020, min(ed.x,ed.y));

  vec2 dir = uv-0.5;
  float d2 = dot(dir,dir);
  vec2 ao = dir * (0.0010 + 0.0075*d2) * uChroma;
  vec3 col;
  col.r = texture2D(uTex, uv + ao).r;
  col.g = texture2D(uTex, uv).g;
  col.b = texture2D(uTex, uv - ao).b;

  /* phosphor halation: a wide cheap tap ring so bright glyphs bloom into the
     glass instead of relying on the text canvas alone */
  if (uHalo > 0.001){
    float s = 0.0038;
    vec3 wide = texture2D(uTex, uv + vec2( s, 0.0)).rgb
              + texture2D(uTex, uv + vec2(-s, 0.0)).rgb
              + texture2D(uTex, uv + vec2(0.0,  s)).rgb
              + texture2D(uTex, uv + vec2(0.0, -s)).rgb
              + texture2D(uTex, uv + vec2( s,  s)*0.72).rgb
              + texture2D(uTex, uv + vec2(-s, -s)*0.72).rgb;
    col += wide * (uHalo / 6.0);
  }

  float sl = sin(uv.y*3.14159265*uScan + t*4.0*uMotion);
  col *= mix(1.0 - uScanDepth, 1.0, sl*sl);

  float gx = gl_FragCoord.x * (6.2831853/max(uTriad, 1.0));
  vec3 grille = (1.0-uGrille) + uGrille*cos(gx + vec3(0.0,2.094,4.188));
  col *= mix(vec3(1.0), grille, step(0.001, uGrille));
  col *= uGain;

  float bar = fract(uv.y*0.5 - t*0.07*uMotion);
  bar = smoothstep(0.0,0.05,bar)*smoothstep(0.18,0.05,bar);
  col += bar*uBar*uMotion;

  float sheen = smoothstep(0.55,0.0, distance(uv, vec2(0.50,0.15)));
  col += sheen*0.030*uSheen;

  float vig = smoothstep(0.98,0.30, length((uv-0.5)*vec2(1.05,1.0)));
  col *= mix(1.0-uVignette, 1.0, vig);
  col *= 1.0 - uFlicker*uMotion*sin(t*8.0);

  if (uNoise > 0.001){
    float st = hash(fuv*uRes*0.5 + vec2(floor(t*24.0), floor(t*24.0)*1.7));
    col += (st-0.5)*0.135*uNoise;
    col += band*0.085*uNoise;
  }
  col += (hash(fuv + fract(t*0.37)) - 0.5)*uGrain;

  float luma = dot(col, vec3(0.2126,0.7152,0.0722));
  col = mix(col, vec3(luma), uMono);

  float spill = smoothstep(0.85,0.18, length(fuv-0.5))*0.05;
  vec3 room = uRoom + uSheen*spill*0.42;
  col = mix(room, col, inside);
  col = max(col, uRoom*0.34);
  gl_FragColor = vec4(col,1.0);
}`;

export type PhosphorTubeVariant = "countdown" | "terminal" | "fault" | "arcade";

type ScreenSurface =
  | { mode: "buffer" }
  | { mode: "cap"; width: number }
  | { mode: "fixed"; width: number; height: number };

type CrtStyle = {
  curve: readonly [number, number];
  scanDensity: number;
  scanDepth: number;
  triadCss: number;
  grille: number;
  chroma: number;
  bar: number;
  flicker: number;
  grain: number;
  noise: number;
  vignette: number;
  mono: number;
  gain: number;
  halo: number;
  sheen: readonly [number, number, number];
  room: readonly [number, number, number];
  background: string;
  filtering: "linear" | "nearest";
  surface: ScreenSurface;
  redrawMs: number;
};

const CRT_STYLES: Record<PhosphorTubeVariant, CrtStyle> = {
  terminal: {
    curve: [0.115, 0.165],
    scanDensity: 0.44,
    scanDepth: 0.3,
    triadCss: 3.2,
    grille: 0.34,
    chroma: 1,
    bar: 0.045,
    flicker: 0.028,
    grain: 0.022,
    noise: 0,
    vignette: 0.58,
    mono: 0,
    gain: 1.34,
    halo: 0.1,
    sheen: [0.55, 1.0, 0.78],
    room: [0.012, 0.03, 0.022],
    background: "#03100a",
    filtering: "linear",
    surface: { mode: "buffer" },
    redrawMs: 0,
  },
  countdown: {
    curve: [0.085, 0.125],
    scanDensity: 0.4,
    scanDepth: 0.22,
    triadCss: 3.6,
    grille: 0.14,
    chroma: 0.7,
    bar: 0.022,
    flicker: 0.02,
    grain: 0.055,
    noise: 0,
    vignette: 0.74,
    mono: 1,
    gain: 1.16,
    halo: 0.2,
    sheen: [0.86, 0.9, 1.0],
    room: [0.016, 0.016, 0.018],
    background: "#07070a",
    filtering: "linear",
    surface: { mode: "cap", width: 1280 },
    redrawMs: 33,
  },
  fault: {
    curve: [0.13, 0.18],
    scanDensity: 0.46,
    scanDepth: 0.34,
    triadCss: 3.0,
    grille: 0.3,
    chroma: 1.9,
    bar: 0.055,
    flicker: 0.042,
    grain: 0.038,
    noise: 1,
    vignette: 0.6,
    mono: 0,
    gain: 1.22,
    halo: 0.16,
    sheen: [0.62, 0.76, 1.0],
    room: [0.014, 0.02, 0.046],
    background: "#050a24",
    filtering: "linear",
    surface: { mode: "cap", width: 1600 },
    redrawMs: 96,
  },
  arcade: {
    curve: [0.07, 0.1],
    scanDensity: 0.34,
    scanDepth: 0.26,
    triadCss: 3.4,
    grille: 0.2,
    chroma: 0.55,
    bar: 0.018,
    flicker: 0.014,
    grain: 0.014,
    noise: 0,
    vignette: 0.46,
    mono: 0,
    gain: 1.2,
    halo: 0.06,
    sheen: [0.72, 0.84, 1.0],
    room: [0.02, 0.024, 0.04],
    background: "#0a1030",
    filtering: "nearest",
    surface: { mode: "fixed", width: 320, height: 180 },
    redrawMs: 16,
  },
};

type ScreenPainter = (
  context: CanvasRenderingContext2D,
  width: number,
  height: number,
  time: number,
) => void;

const MONO_STACK = 'ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace';
const GROTESQUE_STACK = '"Helvetica Neue", "Inter", Helvetica, Arial, sans-serif';
/** The countdown's title face: the theme's heading font, read from `--font-heading` once mounted. */
let headingStack = GROTESQUE_STACK;
const pad = (value: number, size = 2) => String(Math.floor(value)).padStart(size, "0");

/* ---------------------------------------------------------------- cinematic */

const CINEMATIC_CYCLE = 8;
const CINEMATIC_CHROME = [
  { text: "PICTURE START", corner: "tl" },
  { text: "MODUS · STUDIO", corner: "bl" },
  { text: "REEL 02 OF 04", corner: "br" },
] as const;

function registrationMark(context: CanvasRenderingContext2D, x: number, y: number, size: number) {
  context.beginPath();
  context.moveTo(x - size, y);
  context.lineTo(x + size, y);
  context.moveTo(x, y - size);
  context.lineTo(x, y + size);
  context.stroke();
  context.beginPath();
  context.arc(x, y, size * 0.52, 0, Math.PI * 2);
  context.stroke();
}

const paintCinematic: ScreenPainter = (context, width, height, time) => {
  const bar = height * 0.112,
    top = bar,
    bottom = height - bar,
    frameHeight = bottom - top;
  const cx = width / 2,
    cy = top + frameHeight / 2,
    radius = frameHeight * 0.325;
  const phase = ((time % CINEMATIC_CYCLE) + CINEMATIC_CYCLE) % CINEMATIC_CYCLE,
    counting = phase < 7;
  const label = Math.max(2, 9 - Math.ceil(phase || 0.0001));

  const wash = context.createLinearGradient(0, top, 0, bottom);
  wash.addColorStop(0, "#101013");
  wash.addColorStop(0.55, "#08080a");
  wash.addColorStop(1, "#0d0d10");
  context.setTransform(1, 0, 0, 1, 0, 0);
  context.fillStyle = wash;
  context.fillRect(0, 0, width, height);

  /* the running film edge: perforations scroll past on both sides of the frame */
  context.fillStyle = "rgba(236,236,240,0.20)";
  const pitch = frameHeight / 9,
    offset = (time * pitch * 2.4) % pitch,
    perfWidth = width * 0.011,
    perfHeight = pitch * 0.34;
  for (let y = top - pitch + offset; y < bottom + pitch; y += pitch) {
    context.fillRect(width * 0.022, y, perfWidth, perfHeight);
    context.fillRect(width - width * 0.022 - perfWidth, y, perfWidth, perfHeight);
  }

  context.strokeStyle = "rgba(238,238,244,0.16)";
  context.lineWidth = Math.max(1, height * 0.0016);
  context.beginPath();
  context.moveTo(cx, top);
  context.lineTo(cx, bottom);
  context.moveTo(width * 0.06, cy);
  context.lineTo(width * 0.94, cy);
  context.stroke();

  context.strokeStyle = "rgba(238,238,244,0.30)";
  for (const corner of ["tl", "tr", "bl", "br"] as const) {
    const x = corner.endsWith("l") ? width * 0.085 : width * 0.915,
      y = corner.startsWith("t") ? top + frameHeight * 0.16 : bottom - frameHeight * 0.16;
    registrationMark(context, x, y, height * 0.024);
  }

  if (counting) {
    context.strokeStyle = "rgba(240,240,246,0.42)";
    context.lineWidth = Math.max(1.4, height * 0.0032);
    context.beginPath();
    context.arc(cx, cy, radius, 0, Math.PI * 2);
    context.stroke();
    context.strokeStyle = "rgba(240,240,246,0.22)";
    context.beginPath();
    context.arc(cx, cy, radius * 0.845, 0, Math.PI * 2);
    context.stroke();

    const sweep = (phase % 1) * Math.PI * 2,
      start = -Math.PI / 2;
    context.fillStyle = "rgba(244,244,250,0.085)";
    context.beginPath();
    context.moveTo(cx, cy);
    context.arc(cx, cy, radius, start, start + sweep);
    context.closePath();
    context.fill();
    context.strokeStyle = "rgba(248,248,252,0.70)";
    context.lineWidth = Math.max(1.2, height * 0.0026);
    context.beginPath();
    context.moveTo(cx, cy);
    context.lineTo(cx + Math.cos(start + sweep) * radius, cy + Math.sin(start + sweep) * radius);
    context.stroke();

    context.strokeStyle = "rgba(238,238,244,0.34)";
    context.lineWidth = Math.max(1, height * 0.002);
    for (let tick = 0; tick < 12; tick += 1) {
      const angle = start + (tick / 12) * Math.PI * 2,
        inner = tick % 3 === 0 ? radius * 1.055 : radius * 1.028;
      context.beginPath();
      context.moveTo(cx + Math.cos(angle) * inner, cy + Math.sin(angle) * inner);
      context.lineTo(cx + Math.cos(angle) * radius * 1.1, cy + Math.sin(angle) * radius * 1.1);
      context.stroke();
    }

    context.textAlign = "center";
    context.textBaseline = "middle";
    context.shadowColor = "rgba(255,255,255,0.55)";
    context.shadowBlur = height * 0.03;
    context.fillStyle = "#f6f6fa";
    context.font = `700 ${(radius * 1.28).toFixed(2)}px ${GROTESQUE_STACK}`;
    context.fillText(String(label), cx, cy + radius * 0.02);
    context.shadowBlur = 0;
  } else {
    const flash = Math.max(0, 1 - (phase - 7) / 0.1);
    if (flash > 0) {
      context.fillStyle = `rgba(250,250,252,${(flash * 0.62).toFixed(3)})`;
      context.fillRect(0, top, width, frameHeight);
    }
    context.textAlign = "center";
    context.textBaseline = "middle";
    context.fillStyle = "rgba(244,244,248,0.92)";
    const size = height * 0.052;
    context.font = `italic 400 ${(size * 1.5).toFixed(2)}px ${headingStack}`;
    const title = "Modus, reel one";
    context.shadowColor = "rgba(255,255,255,0.45)";
    context.shadowBlur = height * 0.02;
    /* clear of the horizontal crosshair, which otherwise rules through the baseline */
    context.fillText(title, cx, cy - size * 0.78);
    context.shadowBlur = 0;
    context.font = `400 ${(size * 0.42).toFixed(2)}px ${MONO_STACK}`;
    context.fillStyle = "rgba(232,232,238,0.60)";
    context.fillText("P L A T E   0 4   ·   T A K E   0 1", cx, cy + size * 0.62);
  }

  const chromeSize = height * 0.0255;
  context.font = `500 ${chromeSize.toFixed(2)}px ${MONO_STACK}`;
  context.textBaseline = "middle";
  context.fillStyle = "rgba(226,226,232,0.66)";
  for (const item of CINEMATIC_CHROME) {
    context.textAlign = item.corner.endsWith("l") ? "left" : "right";
    const x = item.corner.endsWith("l") ? width * 0.055 : width * 0.945;
    context.fillText(
      item.text,
      x,
      item.corner.startsWith("t") ? top + frameHeight * 0.055 : bottom - frameHeight * 0.055,
    );
  }
  const frames = Math.floor(time * 24);
  context.textAlign = "right";
  context.fillStyle = "rgba(240,240,246,0.82)";
  context.fillText(
    `01:${pad((frames / 1440) % 60)}:${pad((frames / 24) % 60)}:${pad(frames % 24)}`,
    width * 0.945,
    top + frameHeight * 0.055,
  );

  context.fillStyle = "#000";
  context.fillRect(0, 0, width, bar);
  context.fillRect(0, bottom, width, bar + 1);
};

/* -------------------------------------------------------------- blue screen */

type BlueLine = { text: string; tone?: "head" | "dim" | "bright" };
const BLUE_LINES: BlueLine[] = [
  { text: "MODUS HALTED", tone: "head" },
  { text: "" },
  { text: "A fault was detected in the video subsystem and the raster" },
  { text: "driver was stopped to prevent damage to the display." },
  { text: "" },
  { text: "*  If this screen appears again, power the unit down and let" },
  { text: "   the flyback transformer discharge before restarting." },
  { text: "" },
  { text: "*  Horizontal deflection module HD-04 reported a bad sync" },
  { text: "   pulse on line 312 of field 2." },
  { text: "" },
  { text: "Technical information:", tone: "bright" },
  { text: "" },
  { text: "***  STOP: 0x0000CA7E  (0x0F13D0C0, 0x00000002, 0xC0000005)" },
  { text: "***  RASTER.SYS  -  address 8C1FA00E  base at 8C1F0000" },
  { text: "" },
];

const paintBlueScreen: ScreenPainter = (context, width, height, time) => {
  const wash = context.createLinearGradient(0, 0, 0, height);
  wash.addColorStop(0, "#212ec0");
  wash.addColorStop(0.62, "#1a22a4");
  wash.addColorStop(1, "#141a86");
  context.setTransform(1, 0, 0, 1, 0, 0);
  context.fillStyle = wash;
  context.fillRect(0, 0, width, height);

  /* the panel is sized off the line budget so the whole fault report clears the
     curved edges of the tube at any aspect */
  const columns = 62,
    total = BLUE_LINES.length + 4;
  const size = Math.min((height * 0.88) / (total * 1.44), (width * 0.82) / (columns * 0.6));
  context.font = `600 ${size.toFixed(2)}px ${MONO_STACK}`;
  const advance = context.measureText("M").width || size * 0.6,
    lineHeight = size * 1.44;
  const blockWidth = advance * columns,
    left = Math.round((width - blockWidth) / 2);
  const startY = Math.round((height - total * lineHeight) / 2);
  context.textBaseline = "top";
  context.textAlign = "left";

  const head = BLUE_LINES[0].text,
    headWidth = advance * (head.length + 4);
  context.fillStyle = "#e9ecff";
  context.fillRect(Math.round((width - headWidth) / 2), startY - size * 0.2, headWidth, lineHeight);
  context.fillStyle = "#161d92";
  context.fillText(head, Math.round((width - headWidth) / 2) + advance * 2, startY);

  context.shadowColor = "rgba(196,214,255,0.55)";
  context.shadowBlur = size * 0.3;
  let y = startY + lineHeight;
  for (const line of BLUE_LINES.slice(1)) {
    if (line.text) {
      context.fillStyle =
        line.tone === "bright" ? "#ffffff" : line.tone === "dim" ? "#aab6f0" : "#dfe5ff";
      context.fillText(line.text, left, y);
    }
    y += lineHeight;
  }

  const dump = Math.min(100, Math.floor((((time % 12) + 12) % 12) * 22));
  context.fillStyle = "#dfe5ff";
  context.fillText(
    dump >= 100
      ? "Dump of video memory complete."
      : `Beginning dump of video memory: ${pad(dump, 2)}%`,
    left,
    y,
  );
  y += lineHeight * 2;
  const prompt = "Press any key to restart the deflection stage ";
  context.fillText(prompt, left, y);
  if (Math.floor(time * 2) % 2 === 0)
    context.fillRect(left + advance * prompt.length, y + size * 0.08, advance * 0.9, size * 0.96);
  context.shadowBlur = 0;
};

/* ----------------------------------------------------------------- nintendo */

const GLYPHS: Record<string, string> = {
  "0": ".###.#...##..###.#.###..##...#.###.",
  "1": "..#...##....#....#....#....#...###.",
  "2": ".###.#...#....#...#...#...#...#####",
  "3": "####.....#....#.###.....#....#####.",
  "4": "#..#.#..#.#..#.#####...#....#....#.",
  "5": "######....####.....#....##...#.###.",
  "6": ".###.#....#....####.#...##...#.###.",
  "7": "#####....#...#...#...#....#....#...",
  "8": ".###.#...##...#.###.#...##...#.###.",
  "9": ".###.#...##...#.####....#....#.###.",
  A: ".###.#...##...#######...##...##...#",
  B: "####.#...##...#####.#...##...#####.",
  C: ".#####....#....#....#....#.....####",
  D: "####.#...##...##...##...##...#####.",
  E: "######....#....####.#....#....#####",
  F: "######....#....####.#....#....#....",
  G: ".#####....#....#..###...##...#.####",
  H: "#...##...##...#######...##...##...#",
  I: "#####..#....#....#....#....#..#####",
  J: "....#....#....#....##...##...#.###.",
  K: "#...##..#.#.#..##...#.#..#..#.#...#",
  L: "#....#....#....#....#....#....#####",
  M: "#...###.###.#.##...##...##...##...#",
  N: "#...###..##.#.##..###...##...##...#",
  O: ".###.#...##...##...##...##...#.###.",
  P: "####.#...##...#####.#....#....#....",
  Q: ".###.#...##...##...##.#.##..#..##.#",
  R: "####.#...##...#####.#.#..#..#.#...#",
  S: ".#####....#.....###.....#....#####.",
  T: "#####..#....#....#....#....#....#..",
  U: "#...##...##...##...##...##...#.###.",
  V: "#...##...##...##...##...#.#.#...#..",
  W: "#...##...##...##...##.#.###.###...#",
  X: "#...##...#.#.#...#...#.#.#...##...#",
  Y: "#...##...#.#.#...#....#....#....#..",
  Z: "#####....#...#...#...#...#....#####",
  " ": "...................................",
  "-": "...............#####...............",
  ".": "..........................##...##..",
  ":": "......##...##........##...##.......",
  "!": "..#....#....#....#....#.........#..",
  "?": ".###.#...#....#..##...#.........#..",
  "(": "..##..#....#....#....#....#.....##.",
  ")": ".##.....#....#....#....#....#..##..",
  "/": "....#....#...#...#...#...#....#....",
  "*": ".....#.#.#.###.#####.###.#.#.#.....",
  "'": "..#....#...........................",
};

const GLYPH_WIDTH = 5,
  GLYPH_HEIGHT = 7;

function pixelTextWidth(text: string, scale: number) {
  return text.length ? (text.length * (GLYPH_WIDTH + 1) - 1) * scale : 0;
}

function drawPixelText(
  context: CanvasRenderingContext2D,
  text: string,
  x: number,
  y: number,
  scale: number,
  color: string,
) {
  context.fillStyle = color;
  let cursor = x;
  for (const character of text.toUpperCase()) {
    const rows = GLYPHS[character];
    if (rows) {
      for (let row = 0; row < GLYPH_HEIGHT; row += 1) {
        for (let column = 0; column < GLYPH_WIDTH; column += 1) {
          if (rows[row * GLYPH_WIDTH + column] === "#")
            context.fillRect(cursor + column * scale, y + row * scale, scale, scale);
        }
      }
    }
    cursor += (GLYPH_WIDTH + 1) * scale;
  }
}

const RUNNER_PALETTE: Record<string, string> = {
  "1": "#1a1028",
  "2": "#e0402c",
  "3": "#f4f4f4",
  "4": "#2ec4e8",
  "5": "#22304a",
};
const RUNNER_HEAD = [
  "....111111....",
  "...13333331...",
  "..1333333331..",
  "..1355555531..",
  "..1355555531..",
  "..1333333331..",
  "...13333331...",
  "....111111....",
  "...12222221...",
  ".122222222221.",
  ".124444444421.",
  ".122222222221.",
  "..1222222221..",
];
const RUNNER_LEGS: Record<string, string[]> = {
  a: ["...122..221...", "...122..221...", "..1111..1111.."],
  b: ["..122....221..", ".122......221.", "1111......1111"],
  jump: ["..122....221..", ".1221....1221.", ".111......111."],
};

function drawRunner(
  context: CanvasRenderingContext2D,
  x: number,
  y: number,
  pose: keyof typeof RUNNER_LEGS,
  flip: boolean,
) {
  const rows = [...RUNNER_HEAD, ...RUNNER_LEGS[pose]];
  for (let row = 0; row < rows.length; row += 1) {
    const line = rows[row];
    for (let column = 0; column < line.length; column += 1) {
      const color = RUNNER_PALETTE[line[column]];
      if (color) {
        context.fillStyle = color;
        context.fillRect(x + (flip ? line.length - 1 - column : column), y + row, 1, 1);
      }
    }
  }
}

function drawCloud(context: CanvasRenderingContext2D, x: number, y: number, scale: number) {
  context.fillStyle = "#f4f8ff";
  const puffs: readonly (readonly [number, number, number, number])[] = [
    [0, 4, 22, 6],
    [4, 1, 14, 4],
    [11, 2, 12, 5],
    [2, 8, 20, 3],
  ];
  for (const [dx, dy, w, h] of puffs)
    context.fillRect(
      Math.round(x + dx * scale),
      Math.round(y + dy * scale),
      Math.round(w * scale),
      Math.round(h * scale),
    );
}

function drawHill(
  context: CanvasRenderingContext2D,
  x: number,
  baseY: number,
  size: number,
  color: string,
) {
  context.fillStyle = color;
  for (let step = 0; step < size; step += 1) {
    const width = (size - step) * 4;
    context.fillRect(Math.round(x - width / 2), baseY - (step + 1) * 3, width, 3);
  }
}

/* one 320x180 title screen, laid out so the wordmark, credit, prompt, crates, and
   the runner's jump arc each own a horizontal band and never overlap */
const NINTENDO_CYCLE = 10;
const CRATE_X = [118, 208],
  GROUND_ROW = 154,
  JUMP_SPAN = 50,
  JUMP_LIFT = 22;

function drawCrate(context: CanvasRenderingContext2D, x: number, y: number) {
  context.fillStyle = "#20140c";
  context.fillRect(x, y, 16, 16);
  context.fillStyle = "#d8902c";
  context.fillRect(x + 1, y + 1, 14, 14);
  context.fillStyle = "#f0c060";
  context.fillRect(x + 1, y + 1, 14, 3);
  context.fillStyle = "#8a5414";
  context.fillRect(x + 1, y + 11, 14, 3);
  context.fillStyle = "#20140c";
  context.fillRect(x + 6, y + 5, 4, 2);
  context.fillRect(x + 5, y + 7, 6, 2);
  context.fillRect(x + 6, y + 9, 4, 2);
}

function drawGem(context: CanvasRenderingContext2D, x: number, y: number, spin: number) {
  const gemWidth = [8, 6, 2, 6][spin],
    half = gemWidth / 2,
    inset = gemWidth > 3 ? 1 : 0;
  context.fillStyle = "#20140c";
  context.fillRect(x - half - 1, y + 1, gemWidth + 2, 8);
  context.fillRect(x - half, y - 1, gemWidth, 12);
  context.fillStyle = "#ffe070";
  context.fillRect(x - half, y + 1, gemWidth, 8);
  context.fillRect(x - half + inset, y, gemWidth - inset * 2, 10);
  context.fillStyle = "#fff8c8";
  context.fillRect(x - half + inset, y + 2, Math.max(1, half - inset), 4);
}

const paintNintendo: ScreenPainter = (context, width, height, time) => {
  const groundY = GROUND_ROW,
    phase = ((time % NINTENDO_CYCLE) + NINTENDO_CYCLE) % NINTENDO_CYCLE;

  const sky = context.createLinearGradient(0, 0, 0, groundY);
  sky.addColorStop(0, "#2440b8");
  sky.addColorStop(0.55, "#5c94fc");
  sky.addColorStop(1, "#9ecbff");
  context.setTransform(1, 0, 0, 1, 0, 0);
  context.fillStyle = sky;
  context.fillRect(0, 0, width, height);

  for (let star = 0; star < 22; star += 1) {
    const x = (star * 61) % width,
      y = 2 + ((star * 29) % 16);
    context.fillStyle =
      (star + Math.floor(time * 3)) % 5 === 0 ? "rgba(255,255,255,0.85)" : "rgba(255,255,255,0.30)";
    context.fillRect(x, y, 1, 1);
  }

  /* clouds sit in the sky band above the wordmark, never behind its counters */
  for (const [speed, cloudY, scale] of [
    [6, 18, 1.25],
    [3.5, 32, 0.85],
  ] as const) {
    const span = width + 80;
    for (let copy = 0; copy < 3; copy += 1)
      drawCloud(
        context,
        ((time * speed + (copy * span) / 3) % span) - 50,
        cloudY + (copy % 2) * 5,
        scale,
      );
  }

  drawHill(context, 48, groundY, 9, "#2f7a3a");
  drawHill(context, 268, groundY, 11, "#2f7a3a");
  drawHill(context, 160, groundY, 6, "#3e9a48");

  context.fillStyle = "#3ca03c";
  context.fillRect(0, groundY, width, 4);
  context.fillStyle = "#2c7a2c";
  context.fillRect(0, groundY + 4, width, 2);
  context.fillStyle = "#a05a28";
  context.fillRect(0, groundY + 6, width, height - groundY - 6);
  context.fillStyle = "#7c4018";
  for (let y = groundY + 6; y < height; y += 6) {
    context.fillRect(0, y, width, 1);
    for (let x = y % 12 === 0 ? 0 : 6; x < width; x += 12) context.fillRect(x, y, 1, 6);
  }

  const spin = Math.floor(time * 8) % 4,
    bob = [0, 1, 1, 0][Math.floor(time * 6) % 4];
  for (const crateX of CRATE_X) {
    drawCrate(context, crateX, groundY - 16);
    drawGem(context, crateX + 8, groundY - 32 - bob, spin);
  }

  const runX = Math.round(-24 + (phase / NINTENDO_CYCLE) * (width + 60));
  let lift = 0;
  for (const crateX of CRATE_X) {
    const progress = (runX - (crateX - 28)) / JUMP_SPAN;
    if (progress > 0 && progress < 1)
      lift = Math.max(lift, Math.sin(progress * Math.PI) * JUMP_LIFT);
  }
  const pose = lift > 0.5 ? "jump" : Math.floor(time * 9) % 2 === 0 ? "a" : "b";
  context.fillStyle = "rgba(20,16,10,0.20)";
  context.fillRect(runX + 2, groundY - 1, 10, 2);
  drawRunner(context, runX, groundY - 16 - Math.round(lift), pose, false);

  for (const [text, x] of [
    ["PLAYER-1", 10],
    ["GEMS 0" + (2 + Math.floor(phase / 4)), 96],
    ["WORLD 1-1", 174],
    ["TIME " + pad(Math.max(0, 384 - Math.floor(time * 2)) % 1000, 3), 254],
  ] as const) {
    drawPixelText(context, String(text), Number(x), 7, 1, "#141428");
    drawPixelText(context, String(text), Number(x), 6, 1, "#ffffff");
  }

  const title = "INK RUNNER",
    titleWidth = pixelTextWidth(title, 3),
    titleX = Math.round((width - titleWidth) / 2);
  drawPixelText(context, title, titleX + 3, 53, 3, "#141028");
  drawPixelText(context, title, titleX, 50, 3, "#f8e038");
  /* a highlight band sweeps the wordmark the way an attract-mode title does */
  const sweepX = titleX + ((time * 130) % (titleWidth + 110)) - 55;
  context.save();
  context.beginPath();
  context.rect(sweepX, 50, 24, 21);
  context.clip();
  drawPixelText(context, title, titleX, 50, 3, "#fffce0");
  context.restore();

  const credit = "(C) 2026 MODUS",
    creditX = Math.round((width - pixelTextWidth(credit, 1)) / 2);
  drawPixelText(context, credit, creditX, 79, 1, "#0e1430");
  drawPixelText(context, credit, creditX, 78, 1, "#dfe8ff");

  if (Math.floor(time * 1.6) % 2 === 0) {
    const start = "PUSH START",
      startX = Math.round((width - pixelTextWidth(start, 2)) / 2);
    drawPixelText(context, start, startX + 2, 100, 2, "#141028");
    drawPixelText(context, start, startX, 98, 2, "#ffffff");
  }
};

const CRT_SCREENS: Record<Exclude<PhosphorTubeVariant, "terminal">, ScreenPainter> = {
  countdown: paintCinematic,
  fault: paintBlueScreen,
  arcade: paintNintendo,
};

type CrtOptions = {
  variant: PhosphorTubeVariant;
  speed: number;
  typeSpeed: number;
  motion: number;
  brightness: number;
  opacity: number;
  hue: number;
  saturation: number;
};
const CRT_DEFAULTS: CrtOptions = {
  variant: "countdown",
  speed: 1,
  typeSpeed: 1,
  motion: 1,
  brightness: 1,
  opacity: 1,
  hue: 0,
  saturation: 1,
};
const crtStyle = (variant: PhosphorTubeVariant): CrtStyle =>
  CRT_STYLES[variant] ?? CRT_STYLES.terminal;
type Segment = { t: string; c: "p" | "d" | "a" | "h" };
const segment = (text: string, color: Segment["c"] = "p"): Segment => ({ t: text, c: color });
const dots = (count: number) => "·".repeat(count);
const LOG: Segment[][] = [
  [segment("MODUS STUDIO OS  v4.2"), segment("   (c) 2026 Modus UI", "d")],
  [segment("REGISTRY Broadcast  Rev C  S/N MD-0426-0001", "d")],
  [],
  [segment("Indexing registry components "), segment(`${dots(10)} `, "d"), segment("OK", "a")],
  [
    segment("Theme tokens  --primary..--card "),
    segment(`${dots(4)} `, "d"),
    segment("BOUND "),
    segment("OK", "a"),
  ],
  [segment("Resolving palettes "), segment(`${dots(12)} `, "d"), segment("9 found")],
  [
    segment("type0  HEADING SERIF LOADED ", "d"),
    segment(`${dots(6)} `, "d"),
    segment("READY", "a"),
  ],
  [
    segment("motn0  REDUCED MOTION CHECK ", "d"),
    segment(`${dots(6)} `, "d"),
    segment("READY", "a"),
  ],
  [segment("cli0   npx @modus-ui/cli ", "d"), segment(`${dots(9)} `, "d"), segment("LINK", "a")],
  [segment("Mounting /docs -> ROOT: "), segment(`${dots(9)} `, "d"), segment("OK", "a")],
  [segment("Compiling demo stages "), segment(`${dots(10)} `, "d"), segment("OK", "a")],
  [segment("Grading paper & ink "), segment(`${dots(12)} `, "d"), segment("99.9%")],
  [],
  [segment("ALL SURFACES  "), segment("composed.", "h")],
  [segment("studio idle   cursor waiting ", "d"), segment("_", "d")],
  [],
  [segment("modus add: ")],
];
const COLORS = {
  p: { fill: "#8df0b4", glow: "rgba(28,236,132,0.95)" },
  d: { fill: "#4f9a76", glow: "rgba(28,236,132,0.45)" },
  a: { fill: "#ffba5e", glow: "rgba(255,150,52,0.95)" },
  h: { fill: "#eafff3", glow: "rgba(120,255,190,0.95)" },
};
const lineLength = (line: Segment[]) => line.reduce((total, item) => total + item.t.length, 0);
const TOTAL = LOG.reduce((total, line) => total + lineLength(line), 0);
const MAX_CHARS = Math.max(...LOG.map(lineLength));
/* backing-store ceiling: the composite is one triangle, so the cost that matters is
   the 2D screen redraw and its upload, not the fragment pass */
const MAX_BUFFER_WIDTH = 1920,
  MIN_BUFFER_WIDTH = 640,
  MAX_BUFFER_PIXELS = 2_400_000;
function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Unable to create CRT shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS))
    throw new Error(gl.getShaderInfoLog(shader) ?? "CRT shader compilation failed");
  return shader;
}

function createCrtRenderer(
  host: HTMLElement,
  canvas: HTMLCanvasElement,
  getOptions: () => CrtOptions,
  reduced: boolean,
) {
  const gl = canvas.getContext("webgl", {
    antialias: false,
    alpha: false,
    depth: false,
    premultipliedAlpha: false,
  });
  if (!gl) throw new Error("CRT requires WebGL");
  const textCanvas = document.createElement("canvas"),
    textContext = textCanvas.getContext("2d");
  if (!textContext) throw new Error("CRT text canvas unavailable");
  const vertex = compile(gl, gl.VERTEX_SHADER, CRT_VERTEX_SHADER),
    fragment = compile(gl, gl.FRAGMENT_SHADER, CRT_FRAGMENT_SHADER),
    program = gl.createProgram();
  if (!program) throw new Error("Unable to create CRT program");
  gl.attachShader(program, vertex);
  gl.attachShader(program, fragment);
  gl.linkProgram(program);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS))
    throw new Error(gl.getProgramInfoLog(program) ?? "CRT link failed");
  gl.useProgram(program);
  const buffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const position = gl.getAttribLocation(program, "aPos");
  gl.enableVertexAttribArray(position);
  gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
  const uniform = (name: string) => gl.getUniformLocation(program, name);
  const uTexture = uniform("uTex"),
    uResolution = uniform("uRes"),
    uTime = uniform("uTime"),
    uMotion = uniform("uMotion"),
    uCurve = uniform("uCurve"),
    uScan = uniform("uScan"),
    uScanDepth = uniform("uScanDepth"),
    uTriad = uniform("uTriad"),
    uGrille = uniform("uGrille"),
    uChroma = uniform("uChroma"),
    uBar = uniform("uBar"),
    uFlicker = uniform("uFlicker"),
    uGrain = uniform("uGrain"),
    uNoise = uniform("uNoise"),
    uVignette = uniform("uVignette"),
    uMono = uniform("uMono"),
    uGain = uniform("uGain"),
    uHalo = uniform("uHalo"),
    uSheen = uniform("uSheen"),
    uRoom = uniform("uRoom");
  const texture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, texture);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
  gl.uniform1i(uTexture, 0);
  let width = 1,
    height = 1,
    cssWidth = 1,
    cssHeight = 1,
    fontSize = 14,
    lineHeight = 20,
    startY = 0,
    charWidth = 8,
    caretX = 0,
    caretY = 0,
    typed = 0,
    done = reduced,
    textDirty = true,
    lastTextAt = 0,
    lastReveal = -1,
    lastBlink = -1,
    variant: PhosphorTubeVariant = "terminal",
    style = crtStyle(variant);
  const startedAt = performance.now();
  const applyStyle = () => {
    gl.useProgram(program);
    gl.uniform2f(uCurve, style.curve[0], style.curve[1]);
    gl.uniform1f(uScanDepth, style.scanDepth);
    gl.uniform1f(uGrille, style.grille);
    gl.uniform1f(uChroma, style.chroma);
    gl.uniform1f(uBar, style.bar);
    gl.uniform1f(uFlicker, style.flicker);
    gl.uniform1f(uGrain, style.grain);
    gl.uniform1f(uNoise, style.noise);
    gl.uniform1f(uVignette, style.vignette);
    gl.uniform1f(uMono, style.mono);
    gl.uniform1f(uGain, style.gain);
    gl.uniform1f(uHalo, style.halo);
    gl.uniform3f(uSheen, style.sheen[0], style.sheen[1], style.sheen[2]);
    gl.uniform3f(uRoom, style.room[0], style.room[1], style.room[2]);
    const filter = style.filtering === "nearest" ? gl.NEAREST : gl.LINEAR;
    gl.bindTexture(gl.TEXTURE_2D, texture);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
  };
  const layout = () => {
    startY = height * 0.135;
    lineHeight = (height * 0.74) / LOG.length;
    fontSize = Math.max(
      5,
      Math.min(lineHeight * 0.8, (width * 0.88) / (Math.max(MAX_CHARS, 1) * 0.62)),
    );
    textContext.font = `600 ${fontSize.toFixed(2)}px ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace`;
    charWidth = textContext.measureText("M").width || fontSize * 0.6;
  };
  const setStyle = (key: Segment["c"], glow: boolean) => {
    const color = COLORS[key];
    textContext.fillStyle = color.fill;
    textContext.shadowColor = glow ? color.glow : "transparent";
    textContext.shadowBlur = glow ? fontSize * 0.38 : 0;
  };
  /* two passes per glyph: a soft phosphor halo, then the same glyph re-filled with
     the shadow off so the stroke core stays crisp at any backing resolution */
  const drawScreen = (reveal: number) => {
    textContext.setTransform(1, 0, 0, 1, 0, 0);
    textContext.fillStyle = "#03100a";
    textContext.fillRect(0, 0, width, height);
    textContext.textAlign = "left";
    textContext.textBaseline = "top";
    textContext.font = `600 ${fontSize.toFixed(2)}px ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace`;
    let remaining = reveal,
      y = startY;
    caretX = Math.floor((width - MAX_CHARS * charWidth) / 2);
    caretY = startY;
    for (const line of LOG) {
      const length = lineLength(line),
        visible = reveal === Infinity ? Infinity : Math.min(remaining, length);
      let x = Math.floor((width - MAX_CHARS * charWidth) / 2),
        drawn = 0;
      for (const item of line) {
        let text = item.t;
        if (visible !== Infinity) {
          const left = visible - drawn;
          if (left <= 0) break;
          if (left < text.length) text = text.slice(0, left);
        }
        if (text.length) {
          setStyle(item.c, true);
          textContext.fillText(text, x, y);
          setStyle(item.c, false);
          textContext.fillText(text, x, y);
          x += charWidth * text.length;
        }
        drawn += item.t.length;
        if (visible !== Infinity && drawn >= visible) break;
      }
      caretX = x;
      caretY = y;
      if (visible !== Infinity) remaining -= visible;
      y += lineHeight;
      if (visible !== Infinity && remaining <= 0) break;
    }
  };
  const drawCursor = () => {
    textContext.shadowColor = COLORS.p.glow;
    textContext.shadowBlur = fontSize * 0.42;
    textContext.fillStyle = "#bdf8d2";
    textContext.fillRect(
      caretX,
      caretY + fontSize * 0.06,
      Math.max(charWidth * 0.92, 4),
      fontSize * 0.96,
    );
    textContext.shadowBlur = 0;
    textContext.fillRect(
      caretX,
      caretY + fontSize * 0.06,
      Math.max(charWidth * 0.92, 4),
      fontSize * 0.96,
    );
  };
  const uploadTexture = () => {
    gl.bindTexture(gl.TEXTURE_2D, texture);
    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, textCanvas);
    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
    textDirty = false;
  };
  const resize = () => {
    const bounds = host.getBoundingClientRect();
    cssWidth = Math.max(1, bounds.width);
    cssHeight = Math.max(1, bounds.height);
    const density = Math.min(typeof window === "undefined" ? 1 : window.devicePixelRatio || 1, 2);
    let nextWidth = Math.max(
        MIN_BUFFER_WIDTH,
        Math.round(Math.min(cssWidth * density, MAX_BUFFER_WIDTH)),
      ),
      nextHeight = Math.max(1, Math.round((nextWidth * cssHeight) / cssWidth));
    if (nextWidth * nextHeight > MAX_BUFFER_PIXELS) {
      const fit = Math.sqrt(MAX_BUFFER_PIXELS / (nextWidth * nextHeight));
      nextWidth = Math.round(nextWidth * fit);
      nextHeight = Math.round(nextHeight * fit);
    }
    const surface = style.surface,
      screenWidth =
        surface.mode === "fixed"
          ? surface.width
          : surface.mode === "cap"
            ? Math.min(nextWidth, surface.width)
            : nextWidth,
      screenHeight =
        surface.mode === "fixed"
          ? surface.height
          : Math.max(1, Math.round((screenWidth * nextHeight) / nextWidth));
    if (canvas.width !== nextWidth || canvas.height !== nextHeight) {
      canvas.width = nextWidth;
      canvas.height = nextHeight;
    }
    if (textCanvas.width !== screenWidth || textCanvas.height !== screenHeight) {
      textCanvas.width = screenWidth;
      textCanvas.height = screenHeight;
      width = screenWidth;
      height = screenHeight;
      layout();
      lastReveal = -1;
      lastBlink = -1;
      lastTextAt = 0;
      textDirty = true;
    }
    gl.useProgram(program);
    gl.viewport(0, 0, nextWidth, nextHeight);
    gl.uniform2f(uResolution, nextWidth, nextHeight);
    gl.uniform1f(uScan, Math.max(120, Math.min(cssHeight * style.scanDensity, 900)));
    gl.uniform1f(uTriad, Math.max(2, (style.triadCss * nextWidth) / cssWidth));
  };
  const maybeRedrawText = (now: number) => {
    const reveal = done ? Infinity : Math.floor(typed),
      blink = Math.floor((now - startedAt) / 420) % 2 === 0 ? 1 : 0,
      due = !done ? now - lastTextAt > 42 : blink !== lastBlink;
    if (reveal === lastReveal && blink === lastBlink && !due) return;
    if (!done && now - lastTextAt <= 42 && reveal === lastReveal && blink === lastBlink) return;
    drawScreen(reveal);
    if (blink) drawCursor();
    lastTextAt = now;
    lastReveal = reveal;
    lastBlink = blink;
    textDirty = true;
  };
  applyStyle();
  return {
    resize,
    render(now: number) {
      const options = getOptions(),
        requested = CRT_STYLES[options.variant] ? options.variant : "terminal";
      if (requested !== variant) {
        variant = requested;
        style = crtStyle(variant);
        applyStyle();
        typed = 0;
        done = reduced;
        lastReveal = -1;
        lastBlink = -1;
        lastTextAt = 0;
        resize();
      }
      const seconds = (now - startedAt) * 0.001 * options.speed;
      if (variant === "terminal") {
        if (!done) {
          typed += 4.4 * options.typeSpeed;
          if (typed >= TOTAL) {
            typed = TOTAL;
            done = true;
          }
        }
        maybeRedrawText(now);
      } else if (now - lastTextAt >= style.redrawMs || textDirty) {
        CRT_SCREENS[variant](textContext, width, height, seconds);
        lastTextAt = now;
        textDirty = true;
      }
      if (textDirty) uploadTexture();
      gl.useProgram(program);
      gl.uniform1f(uTime, seconds);
      gl.uniform1f(uMotion, reduced ? 0 : options.motion);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    },
    dispose() {
      gl.deleteBuffer(buffer);
      gl.deleteTexture(texture);
      gl.deleteProgram(program);
      gl.deleteShader(vertex);
      gl.deleteShader(fragment);
    },
  };
}

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

/** Resolves any CSS colour to 0..1 RGB channels. */
function toRgb(color: string): [number, number, number] {
  const ctx = document.createElement("canvas").getContext("2d");
  if (!ctx) return [0, 0, 0];
  ctx.fillStyle = color;
  ctx.fillRect(0, 0, 1, 1);
  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
  return [r / 255, g / 255, b / 255];
}

export interface PhosphorTubeProps {
  variant?: PhosphorTubeVariant;
  /** `theme` tints the tube's light with the theme tokens; `original` keeps the source phosphor colours. */
  palette?: "theme" | "original";
  speed?: number;
  typeSpeed?: number;
  motion?: number;
  brightness?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  className?: string;
}

export function PhosphorTube({
  variant = "countdown",
  palette = "theme",
  speed = 1,
  typeSpeed = 1,
  motion = 1,
  brightness = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  className,
}: PhosphorTubeProps) {
  const prefersReducedMotion = useReducedMotion();
  const filterId = `tube-${useId().replace(/:/g, "")}`;
  const tokens = useTokens();
  // A screen stays dark in both modes: the darkest ink maps to black level, primary to the
  // phosphor's mid tones and the lightest token to its highlights.
  const ramp = useMemo(() => {
    if (palette !== "theme" || !tokens) return null;
    if (tokens.dark) return [tokens.background, tokens.primary, tokens.foreground].map(toRgb);
    // Light themes often have a near-black primary: lift the mid tones with the muted ink.
    const [ink, primary, muted, paper] = [
      tokens.foreground,
      tokens.primary,
      tokens.muted,
      tokens.background,
    ].map(toRgb);
    const mid = primary.map((c, i) => (c + muted[i] * 2) / 3) as [number, number, number];
    return [ink, mid, paper];
  }, [palette, tokens]);
  const table = (channel: number) => (ramp ?? []).map((rgb) => rgb[channel].toFixed(3)).join(" ");
  useEffect(() => {
    const heading = getComputedStyle(document.documentElement).getPropertyValue("--font-heading");
    if (heading.trim()) headingStack = `${heading.trim()}, ${GROTESQUE_STACK}`;
  }, [tokens]);
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options: CrtOptions = {
    variant,
    speed,
    typeSpeed,
    motion,
    brightness,
    opacity,
    hue,
    saturation,
  };
  const optionsRef = useRef(options);
  optionsRef.current = options;

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return undefined;
    const reduced = Boolean(prefersReducedMotion);
    let renderer: ReturnType<typeof createCrtRenderer>;
    try {
      renderer = createCrtRenderer(host, canvas, () => optionsRef.current, reduced);
    } catch {
      return undefined;
    }
    let frame = 0;
    let visible = true;
    const resize = () => {
      renderer.resize();
      renderer.render(performance.now());
    };
    const tick = (now: number) => {
      renderer.render(now);
      frame = visible && !document.hidden && !reduced ? requestAnimationFrame(tick) : 0;
    };
    const onVisibility = () => {
      if (!document.hidden && visible && !frame && !reduced) frame = requestAnimationFrame(tick);
    };
    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible && !frame) frame = requestAnimationFrame(tick);
      if (!visible && frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    resizeObserver.observe(host);
    intersection.observe(host);
    document.addEventListener("visibilitychange", onVisibility);
    resize();
    frame = requestAnimationFrame(tick);
    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      renderer.dispose();
    };
    // Recreated on variant change so a still (reduced-motion) screen repaints.
  }, [prefersReducedMotion, variant]);

  return (
    <div
      ref={hostRef}
      className={cn("relative h-full min-h-0 w-full min-w-0 overflow-hidden", className)}
      style={{
        background: ramp ? "black" : crtStyle(variant).background,
        opacity,
        filter: `${ramp ? `url(#${filterId}) ` : ""}hue-rotate(${hue}deg) saturate(${saturation}) brightness(${brightness})`,
      }}
    >
      {ramp && (
        <svg aria-hidden="true" className="absolute h-0 w-0">
          <filter id={filterId} colorInterpolationFilters="sRGB">
            <feColorMatrix
              type="matrix"
              values="0.3 0.59 0.11 0 0  0.3 0.59 0.11 0 0  0.3 0.59 0.11 0 0  0 0 0 1 0"
            />
            <feComponentTransfer>
              <feFuncR type="table" tableValues={table(0)} />
              <feFuncG type="table" tableValues={table(1)} />
              <feFuncB type="table" tableValues={table(2)} />
            </feComponentTransfer>
          </filter>
        </svg>
      )}
      <canvas ref={canvasRef} aria-hidden="true" className="absolute inset-0 block h-full w-full" />
    </div>
  );
}
```

---

# Folio Title

> A journal index whose italic serif titles decode from scrambled glyphs, set in your theme.

Install: `npx @modus-ui/cli add folio-title`

A numbered journal index on the page ground: mono caption, numerals in `--primary`, italic serif titles and pill-shaped meta tags, all drawn from the theme tokens so it follows light, dark and every palette. On mount each title decodes left to right, one after another. A short band of scrambled glyphs leads the reveal while a few characters further along flicker, then the title settles. Type scales with the container, the meta column drops away on narrow screens, and titles appear as-is when the user prefers reduced motion. The component fills its parent, so give it a sized container.

## Installation

### CLI

```bash
npx @modus-ui/cli add folio-title
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/folio-title.tsx`.
4. Paste the code.

## Usage

```tsx
import { FolioTitle } from "@/components/ui/folio-title";

export default function Example() {
  return (
    <div className="h-[420px] w-full">
      <FolioTitle
        entries={[
          { title: "A Grid Is a Promise You Keep", meta: "ESSAY · 6 MIN" },
          { title: "Tokens Before Pixels", meta: "WORKSHOP · 9 MIN" },
        ]}
      />
    </div>
  );
}
```

## Props

| Prop             | Type                                | Default                     | Description                                         |
| :--------------- | :---------------------------------- | :-------------------------- | :-------------------------------------------------- |
| `duration`       | `number`                            | `560`                       | Length of each decode in milliseconds.              |
| `stagger`        | `number`                            | `140`                       | Delay between headings in milliseconds.             |
| `scrambleLength` | `number`                            | `10`                        | Number of scrambled glyphs leading the reveal.      |
| `preserveChance` | `number`                            | `0.3`                       | Chance a leading glyph shows its real character.    |
| `tailChance`     | `number`                            | `0.18`                      | Chance an unrevealed character flickers to a glyph. |
| `label`          | `string`                            | `"MODUS JOURNAL"`           | Header caption on the left.                         |
| `entries`        | `{ title: string; meta: string }[]` | Three Modus journal entries | Rows to list; each is numbered automatically.       |

## Source

`components/ui/folio-title.tsx`

```tsx
"use client";

// Ported from ThreeUI Community's Article Headings (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface FolioTitleEntry {
  title: string;
  meta: string;
}

interface FolioTitleProps {
  duration?: number;
  stagger?: number;
  scrambleLength?: number;
  preserveChance?: number;
  tailChance?: number;
  label?: string;
  entries?: FolioTitleEntry[];
  className?: string;
}

const DEFAULT_ENTRIES: FolioTitleEntry[] = [
  { title: "A Grid Is a Promise You Keep", meta: "ESSAY · 6 MIN" },
  { title: "Motion Should Explain, Not Decorate", meta: "PRINCIPLE · 4 MIN" },
  { title: "Tokens Before Pixels", meta: "WORKSHOP · 9 MIN" },
];

const DECODE_POOL = "#%&@$/\\<>*+=~ABCDEFGHKMNPRSTUVWXYZ0123456789";
const NOISE =
  "url(\"data:image/svg+xml,%3Csvg viewBox='0 0 180 180' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.85' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='.16'/%3E%3C/svg%3E\")";

const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));
const easeOut = (value: number) => 1 - Math.pow(1 - value, 2);
const randomGlyph = () => DECODE_POOL[(Math.random() * DECODE_POOL.length) | 0];

export function FolioTitle({
  duration = 560,
  stagger = 140,
  scrambleLength = 10,
  preserveChance = 0.3,
  tailChance = 0.18,
  label = "MODUS JOURNAL",
  entries = DEFAULT_ENTRIES,
  className,
}: FolioTitleProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const titles = entries.map((entry) => entry.title).join("\n");

  useEffect(() => {
    const root = rootRef.current;
    if (!root || prefersReducedMotion) return;
    const frames = new Set<number>();
    const originals = new Map<Text, string>();

    const decodeElement = (element: HTMLElement, delay: number) => {
      const nodes: Array<{ node: Text; original: string }> = [];
      const walk = (node: Node) => {
        node.childNodes.forEach((child) => {
          if (child.nodeType === Node.TEXT_NODE && child.textContent?.trim()) {
            const text = child as Text;
            const original = text.textContent ?? "";
            originals.set(text, original);
            nodes.push({ node: text, original });
          } else if (child.nodeType === Node.ELEMENT_NODE) {
            walk(child);
          }
        });
      };
      walk(element);

      const total = nodes.reduce((sum, node) => sum + node.original.length, 0);
      const start = performance.now() + delay;
      const frame = (now: number) => {
        const progress = clamp((now - start) / Math.max(1, duration), 0, 1);
        if (now < start) {
          frames.add(requestAnimationFrame(frame));
          return;
        }

        let budget = Math.floor(easeOut(progress) * total);
        for (const textNode of nodes) {
          const length = textNode.original.length;
          const revealed = clamp(budget, 0, length);
          budget -= revealed;
          if (revealed >= length) {
            textNode.node.textContent = textNode.original;
            continue;
          }

          let output = textNode.original.slice(0, revealed);
          const scramble = Math.min(length - revealed, Math.round(scrambleLength));
          for (let index = 0; index < scramble; index += 1) {
            const original = textNode.original[revealed + index];
            output += original === " " || Math.random() < preserveChance ? original : randomGlyph();
          }
          output += textNode.original
            .slice(revealed + scramble)
            .replace(/\S/g, (character) =>
              Math.random() < tailChance ? randomGlyph() : character,
            );
          textNode.node.textContent = output;
        }

        if (progress < 1) frames.add(requestAnimationFrame(frame));
      };
      frames.add(requestAnimationFrame(frame));
    };

    root.querySelectorAll<HTMLElement>("[data-article-heading]").forEach((element, index) => {
      decodeElement(element, index * stagger);
    });

    return () => {
      frames.forEach(cancelAnimationFrame);
      originals.forEach((original, node) => {
        node.textContent = original;
      });
    };
  }, [duration, stagger, scrambleLength, preserveChance, tailChance, titles, prefersReducedMotion]);

  const small = "text-[clamp(8px,0.85cqw,10px)] font-normal";

  return (
    <div
      ref={rootRef}
      className={cn(
        "relative isolate grid h-full min-h-0 w-full min-w-0 overflow-hidden [container-type:inline-size]",
        "px-[clamp(20px,6.2cqw,86px)] py-[clamp(20px,5.4cqw,74px)] max-[600px]:p-[18px]",
        "bg-background font-sans text-foreground",
        className,
      )}
      style={{
        gridTemplateRows: `auto${" 1fr".repeat(entries.length)}`,
      }}
    >
      <div
        className={cn(
          small,
          "flex justify-between pb-[clamp(14px,2.6cqw,30px)] font-mono uppercase leading-none tracking-[0.18em] text-muted-foreground",
        )}
      >
        <span>{label}</span>
        <span>{String(entries.length).padStart(2, "0")} ENTRIES</span>
      </div>
      {entries.map((entry, index) => (
        <article
          key={`${index}-${entry.title}`}
          className="grid grid-cols-[clamp(28px,4cqw,56px)_minmax(0,1fr)_auto] items-center gap-[clamp(10px,2.2cqw,30px)] border-t border-solid border-border max-[600px]:grid-cols-[24px_minmax(0,1fr)]"
        >
          <span
            className={cn(
              small,
              "font-mono leading-[1.3] tracking-[0.06em] text-[hsl(var(--primary))]",
            )}
          >
            {String(index + 1).padStart(2, "0")}
          </span>
          <h2
            data-article-heading
            className="m-0 font-serif text-[clamp(20px,3.6cqw,50px)] font-normal italic leading-[1.05] tracking-[-0.01em] text-foreground max-[600px]:text-[clamp(18px,6vw,28px)]"
          >
            {entry.title}
          </h2>
          <span
            className={cn(
              small,
              "rounded-full border border-border px-2.5 py-1 text-right font-mono leading-[1.3] tracking-[0.12em] text-muted-foreground max-[600px]:hidden",
            )}
          >
            {entry.meta}
          </span>
        </article>
      ))}
      <div
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 z-[5] opacity-[0.08] mix-blend-multiply dark:mix-blend-screen"
        style={{ backgroundImage: NOISE }}
      />
    </div>
  );
}
```

---

# Gravity Text Swap

> Text that detaches and falls away with simulated gravity when swapped.

Install: `npx @modus-ui/cli add gravity-text-swap`

A physics-based typography component. The old characters physically drop out of the layout with staggered gravity logic, allowing the new characters to spring into place from above.

## Installation

### CLI

```bash
npx @modus-ui/cli add gravity-text-swap
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/gravity-text-swap.tsx`.
3. Paste the code.

## Usage

```tsx
import { GravityTextSwap } from "@/components/ui/gravity-text-swap";

export default function Example() {
  return <GravityTextSwap texts={["Hello", "World", "Build"]} duration={0.6} />;
}
```

## Props

| Prop            | Type       | Default | Description                        |
| :-------------- | :--------- | :------ | :--------------------------------- |
| `texts`         | `string[]` | -       | The strings to cycle through.      |
| `duration`      | `number`   | `0.5`   | Seconds each swap animation takes. |
| `pauseDuration` | `number`   | `2`     | Seconds each string stays visible. |

## Source

`components/ui/gravity-text-swap.tsx`

```tsx
"use client";

import { motion, useReducedMotion, AnimatePresence } from "framer-motion";
import { useEffect, useState } from "react";
import { cn } from "@/lib/utils";

interface GravityTextSwapProps {
  texts: string[];
  duration?: number;
  pauseDuration?: number;
  className?: string;
}

export function GravityTextSwap({
  texts,
  duration = 0.5,
  pauseDuration = 2,
  className = "",
}: GravityTextSwapProps) {
  const [, setCurrentIndex] = useState(0);
  const [currentText, setCurrentText] = useState(texts[0]);
  const prefersReducedMotion = useReducedMotion();

  useEffect(() => {
    if (texts.length <= 1) return;

    const intervalId = setInterval(
      () => {
        setCurrentIndex((prevIndex) => {
          const nextIndex = (prevIndex + 1) % texts.length;
          setCurrentText(texts[nextIndex] ?? "");
          return nextIndex;
        });
      },
      (duration + pauseDuration) * 1000,
    );

    return () => clearInterval(intervalId);
  }, [texts, duration, pauseDuration]);

  return (
    <div className={cn("inline-block overflow-hidden", className)}>
      <AnimatePresence mode="wait">
        <motion.span
          key={currentText}
          className="inline-block"
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
          transition={{ duration: duration / 2 }}
        >
          {prefersReducedMotion
            ? currentText
            : (currentText ?? "").split("").map((char, index) => (
                <motion.span
                  key={index}
                  className="inline-block"
                  initial={{ y: -20, opacity: 0 }}
                  animate={{
                    y: 0,
                    opacity: 1,
                    transition: {
                      type: "spring",
                      damping: 12,
                      stiffness: 200,
                      delay: index * 0.03,
                    },
                  }}
                  exit={{
                    y: 20,
                    opacity: 0,
                    transition: {
                      duration: duration / 2,
                      delay: index * 0.02,
                    },
                  }}
                >
                  {char === " " ? "\u00A0" : char}
                </motion.span>
              ))}
        </motion.span>
      </AnimatePresence>
    </div>
  );
}
```

---

# Flip Words

> A sleek text rotator that flips individual words sequentially using 3D perspective.

Install: `npx @modus-ui/cli add flip-words`

A typography component. It utilizes Framer Motion's `AnimatePresence` with `mode="popLayout"` to smoothly slide adjacent text over as the rotating word changes length, preventing the jarring layout jumps seen in most word rotators.

## Installation

### CLI

```bash
npx @modus-ui/cli add flip-words
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/flip-words.tsx`.
3. Paste the code.

## Usage

```tsx
import { FlipWords } from "@/components/ui/flip-words";

export default function Example() {
  return (
    <h2>
      Build <FlipWords words={["fast", "beautiful", "modern"]} /> websites.
    </h2>
  );
}
```

## Props

| Prop       | Type       | Default | Description                        |
| :--------- | :--------- | :------ | :--------------------------------- |
| `words`    | `string[]` | -       | The words to cycle through.        |
| `interval` | `number`   | `2`     | Seconds each word stays visible.   |
| `duration` | `number`   | `0.5`   | Seconds each flip animation takes. |

## Source

`components/ui/flip-words.tsx`

```tsx
"use client";

import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { useEffect, useState } from "react";
import { cn } from "@/lib/utils";

interface FlipWordsProps {
  words: string[];
  interval?: number;
  duration?: number;
  className?: string;
}

export function FlipWords({ words, interval = 2, duration = 0.5, className = "" }: FlipWordsProps) {
  const prefersReducedMotion = useReducedMotion();
  const [index, setIndex] = useState(0);

  useEffect(() => {
    if (prefersReducedMotion || words.length < 2) return;

    const id = setInterval(
      () => setIndex((current) => (current + 1) % words.length),
      interval * 1000,
    );
    return () => clearInterval(id);
  }, [interval, prefersReducedMotion, words.length]);

  const word = words[index % Math.max(words.length, 1)] ?? "";

  return (
    <motion.span
      layout={!prefersReducedMotion}
      className={cn("relative inline-flex overflow-visible", className)}
    >
      <AnimatePresence mode="popLayout" initial={false}>
        <motion.span
          key={word}
          initial={prefersReducedMotion ? false : { opacity: 0, y: "0.4em", filter: "blur(8px)" }}
          animate={{ opacity: 1, y: "0em", filter: "blur(0px)" }}
          exit={prefersReducedMotion ? undefined : { opacity: 0, y: "-0.4em", filter: "blur(8px)" }}
          transition={{
            duration: prefersReducedMotion ? 0 : duration,
            ease: [0.22, 1, 0.36, 1],
          }}
          className="whitespace-nowrap"
        >
          {word}
        </motion.span>
      </AnimatePresence>
    </motion.span>
  );
}
```

---

# Static Type

> Serif display type that tears into horizontal static, harder when you hover it.

Install: `npx @modus-ui/cli add static-type`

Drawn on a canvas in the Modus heading face and the foreground ink, each frame shifts pixel rows sideways like a weak broadcast signal. Reduced motion draws a single still frame.

## Installation

### CLI

```bash
npx @modus-ui/cli add static-type
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/static-type.tsx`.
3. Paste the code.

## Usage

```tsx
import { StaticType } from "@/components/ui/static-type";

export default function Example() {
  return <StaticType>Modus</StaticType>;
}
```

## Props

| Prop           | Type    | Default                  | Description |
| :------------- | :------ | :----------------------- | :---------- |
| children       | any     | -                        | -           |
| fontSize       | string  | "clamp(3rem, 8vw, 6rem)" | -           |
| fontWeight     | number  | 400                      | -           |
| fontFamily     | string  | ""                       | -           |
| color          | string  | "hsl(var(--foreground))" | -           |
| enableHover    | boolean | true                     | -           |
| baseIntensity  | number  | 0.12                     | -           |
| hoverIntensity | number  | 0.6                      | -           |

## Source

`components/ui/static-type.tsx`

```tsx
"use client";
// Display type drawn on a canvas whose pixel rows jitter sideways like a weak signal.

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface StaticTypeProps {
  children?: React.ReactNode;
  fontSize?: string;
  fontWeight?: number;
  fontFamily?: string;
  color?: string;
  enableHover?: boolean;
  baseIntensity?: number;
  hoverIntensity?: number;
  className?: string;
}

const BAND = 3; // pixel rows that move together

export function StaticType({
  children,
  fontSize = "clamp(3rem, 8vw, 6rem)",
  fontWeight = 400,
  fontFamily = "",
  color = "hsl(var(--foreground))",
  enableHover = true,
  baseIntensity = 0.12,
  hoverIntensity = 0.6,
  className,
}: StaticTypeProps) {
  const probeRef = useRef<HTMLSpanElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const hoverRef = useRef(false);
  const [box, setBox] = useState({ w: 0, h: 0 });
  const reduced = useReducedMotion();
  const text = String(children ?? "");

  useEffect(() => {
    const probe = probeRef.current;
    const canvas = canvasRef.current;
    if (!probe || !canvas) return;
    let frame = 0;
    let cancelled = false;

    const start = async () => {
      await document.fonts.ready;
      if (cancelled) return;
      const style = getComputedStyle(probe);
      const size = parseFloat(style.fontSize);
      const font = `${fontWeight} ${size}px ${style.fontFamily}`;
      const dpr = window.devicePixelRatio || 1;
      const pad = size * 0.4;

      const ink = document.createElement("canvas");
      const ictx = ink.getContext("2d")!;
      ictx.font = font;
      const w = Math.ceil(ictx.measureText(text).width + pad * 2);
      const h = Math.ceil(size * 1.3);
      ink.width = w * dpr;
      ink.height = h * dpr;
      ictx.scale(dpr, dpr);
      ictx.font = font;
      ictx.fillStyle = style.color;
      ictx.textBaseline = "middle";
      ictx.fillText(text, pad, h / 2);

      canvas.width = w * dpr;
      canvas.height = h * dpr;
      setBox({ w, h });
      const ctx = canvas.getContext("2d")!;
      const band = BAND * dpr;

      const draw = () => {
        const level = hoverRef.current && enableHover ? hoverIntensity : baseIntensity;
        ctx.clearRect(0, 0, canvas.width, canvas.height);
        for (let y = 0; y < canvas.height; y += band) {
          const kick = Math.random() < level * 0.5 ? (Math.random() - 0.5) * pad * 2 * level : 0;
          const shift = (Math.random() - 0.5) * pad * 0.15 * level + kick;
          ctx.drawImage(ink, 0, y, ink.width, band, shift * dpr, y, ink.width, band);
        }
        if (!reduced) frame = requestAnimationFrame(draw);
      };
      draw();
    };
    start();
    return () => {
      cancelled = true;
      cancelAnimationFrame(frame);
    };
  }, [
    text,
    fontSize,
    fontWeight,
    fontFamily,
    color,
    enableHover,
    baseIntensity,
    hoverIntensity,
    reduced,
  ]);

  return (
    <span
      className={cn("relative inline-block font-serif", className)}
      onPointerEnter={() => (hoverRef.current = true)}
      onPointerLeave={() => (hoverRef.current = false)}
    >
      <span
        ref={probeRef}
        aria-hidden
        className="pointer-events-none absolute opacity-0"
        style={{ fontSize, fontFamily: fontFamily || undefined, color }}
      />
      <span className="sr-only">{text}</span>
      <canvas
        ref={canvasRef}
        aria-hidden
        style={{ width: box.w, height: box.h, display: "block" }}
      />
    </span>
  );
}
```

---

# Scroll Velocity

> A marque text effect whose speed scales dynamically based on scroll velocity.

Install: `npx @modus-ui/cli add scroll-velocity`

A high-performance text marquee powered by `framer-motion`'s `useVelocity`, `useScroll`, and `useTransform`. As the user scrolls faster, the text marquee speed multiplies dynamically.

## Installation

### CLI

```bash
npx @modus-ui/cli add scroll-velocity
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/scroll-velocity.tsx`.
3. Paste the code.

## Usage

```tsx
import { ScrollVelocity } from "@/components/ui/scroll-velocity";

export default function Example() {
  return <ScrollVelocity texts={["FIRST LINE", "SECOND LINE", "THIRD LINE"]} velocity={50} />;
}
```

## Props

| Prop                 | Type                                    | Default                                | Description                                      |
| :------------------- | :-------------------------------------- | :------------------------------------- | :----------------------------------------------- |
| `scrollContainerRef` | `React.RefObject<HTMLElement>`          | -                                      | Scroll container to track instead of the window. |
| `texts`              | `string[]`                              | `[]`                                   | One scrolling row per string.                    |
| `velocity`           | `number`                                | `100`                                  | Base speed of the rows.                          |
| `damping`            | `number`                                | `50`                                   | Damping of the scroll-velocity spring.           |
| `stiffness`          | `number`                                | `400`                                  | Stiffness of the scroll-velocity spring.         |
| `numCopies`          | `number`                                | `6`                                    | Copies of the text per row.                      |
| `velocityMapping`    | `{ input: number[]; output: number[] }` | `{ input: [0, 1000], output: [0, 5] }` | Maps scroll velocity to the speed multiplier.    |
| `parallaxClassName`  | `string`                                | -                                      | Classes for each row's container.                |
| `scrollerClassName`  | `string`                                | -                                      | Classes for each moving row.                     |
| `parallaxStyle`      | `React.CSSProperties`                   | -                                      | Inline styles for each row's container.          |
| `scrollerStyle`      | `React.CSSProperties`                   | -                                      | Inline styles for each moving row.               |

## Source

`components/ui/scroll-velocity.tsx`

```tsx
"use client";
// Marquee rows that drift on their own and speed up with the scroll velocity.

import * as React from "react";
import {
  motion,
  useAnimationFrame,
  useMotionValue,
  useReducedMotion,
  useScroll,
  useSpring,
  useTransform,
  useVelocity,
  type MotionValue,
} from "framer-motion";
import { cn } from "@/lib/utils";

export interface ScrollVelocityProps extends React.HTMLAttributes<HTMLDivElement> {
  scrollContainerRef?: React.RefObject<HTMLElement>;
  texts?: string[];
  velocity?: number;
  damping?: number;
  stiffness?: number;
  numCopies?: number;
  velocityMapping?: { input: number[]; output: number[] };
  parallaxClassName?: string;
  scrollerClassName?: string;
  parallaxStyle?: React.CSSProperties;
  scrollerStyle?: React.CSSProperties;
}

interface RowProps {
  text: string;
  speed: number;
  boost: MotionValue<number>;
  numCopies: number;
  still: boolean;
  parallaxClassName?: string;
  scrollerClassName?: string;
  parallaxStyle?: React.CSSProperties;
  scrollerStyle?: React.CSSProperties;
}

function Row({ text, speed, boost, numCopies, still, ...styling }: RowProps) {
  const copyRef = React.useRef<HTMLSpanElement>(null);
  const offset = useMotionValue(0);
  const heading = React.useRef(1);

  useAnimationFrame((_, delta) => {
    const copy = copyRef.current?.offsetWidth;
    if (still || !copy) return;
    const b = boost.get();
    if (b !== 0) heading.current = Math.sign(b);
    const step = speed * heading.current * (1 + Math.abs(b)) * (delta / 1000);
    // Keep the offset within one copy's width so the loop is seamless.
    offset.set((((offset.get() - step) % copy) - copy) % copy);
  });

  return (
    <div
      className={cn("w-full overflow-hidden whitespace-nowrap", styling.parallaxClassName)}
      style={styling.parallaxStyle}
    >
      <motion.div
        className={cn(
          "flex w-max font-serif text-4xl font-bold tracking-tight md:text-7xl",
          styling.scrollerClassName,
        )}
        style={{ x: offset, ...styling.scrollerStyle }}
      >
        {Array.from({ length: numCopies }, (_, i) => (
          <span
            key={i}
            ref={i === 0 ? copyRef : undefined}
            aria-hidden={i > 0}
            className="pr-[0.5em]"
          >
            {text}
          </span>
        ))}
      </motion.div>
    </div>
  );
}

export function ScrollVelocity({
  scrollContainerRef,
  texts = [],
  velocity = 100,
  damping = 50,
  stiffness = 400,
  numCopies = 6,
  velocityMapping = { input: [0, 1000], output: [0, 5] },
  parallaxClassName,
  scrollerClassName,
  parallaxStyle,
  scrollerStyle,
  className,
  ...props
}: ScrollVelocityProps) {
  const reduceMotion = useReducedMotion();
  const { scrollY } = useScroll(scrollContainerRef ? { container: scrollContainerRef } : undefined);
  const smoothVelocity = useSpring(useVelocity(scrollY), { damping, stiffness });
  // Map the magnitude, then restore the sign so scrolling up reverses the rows.
  const boost = useTransform(smoothVelocity, (v) => {
    const { input, output } = velocityMapping;
    const t = Math.min(1, Math.max(0, (Math.abs(v) - input[0]) / (input[1] - input[0] || 1)));
    return Math.sign(v) * (output[0] + t * (output[1] - output[0]));
  });

  return (
    <div className={cn("flex flex-col gap-4", className)} {...props}>
      {texts.map((text, i) => (
        <Row
          key={i}
          text={text}
          speed={i % 2 === 0 ? velocity : -velocity}
          boost={boost}
          numCopies={numCopies}
          still={!!reduceMotion}
          parallaxClassName={parallaxClassName}
          scrollerClassName={scrollerClassName}
          parallaxStyle={parallaxStyle}
          scrollerStyle={scrollerStyle}
        />
      ))}
    </div>
  );
}
```

---

# Text Pressure

> A responsive variable-font typography effect that reacts fluidly to the cursor's proximity.

Install: `npx @modus-ui/cli add text-pressure`

A highly interactive variable-font typography component. It dynamically adjusts the weight, width, and italic properties of individual characters based on their distance to the user's mouse cursor.

## Installation

### CLI

```bash
npx @modus-ui/cli add text-pressure
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/text-pressure.tsx`.
3. Paste the code.

## Usage

```tsx
import { TextPressure } from "@/components/ui/text-pressure";

export default function Example() {
  return (
    <div className="h-64 w-full">
      <TextPressure text="Modus" width={true} weight={true} italic={true} />
    </div>
  );
}
```

## Props

| Prop          | Type      | Default                                                                                                       | Description                                          |
| :------------ | :-------- | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------- |
| `text`        | `string`  | `"Pressure"`                                                                                                  | The text to render.                                  |
| `fontFamily`  | `string`  | `"Roboto Flex"`                                                                                               | Variable font family to use.                         |
| `fontUrl`     | `string`  | `"https://fonts.googleapis.com/css2?family=Roboto+Flex:opsz,wdth,wght@8..144,25..151,100..1000&display=swap"` | Stylesheet URL that loads the variable font.         |
| `width`       | `boolean` | `true`                                                                                                        | Varies the font width with cursor distance.          |
| `weight`      | `boolean` | `true`                                                                                                        | Varies the font weight with cursor distance.         |
| `italic`      | `boolean` | `true`                                                                                                        | Varies the italic axis with cursor distance.         |
| `alpha`       | `boolean` | `false`                                                                                                       | Varies letter opacity with cursor distance.          |
| `flex`        | `boolean` | `true`                                                                                                        | Spreads the letters across the container.            |
| `stroke`      | `boolean` | `false`                                                                                                       | Draws an outline around the letters.                 |
| `scale`       | `boolean` | `false`                                                                                                       | Stretches the text vertically to fill the container. |
| `textColor`   | `string`  | `"hsl(var(--foreground))"`                                                                                    | Text colour.                                         |
| `strokeColor` | `string`  | `"hsl(var(--foreground))"`                                                                                    | Outline colour when `stroke` is on.                  |
| `strokeWidth` | `number`  | `2`                                                                                                           | Outline width in pixels.                             |
| `minFontSize` | `number`  | `24`                                                                                                          | Minimum font size in pixels.                         |

## Source

`components/ui/text-pressure.tsx`

```tsx
"use client";
// Variable-font letters that swell in width, weight and slant near the cursor.

import * as React from "react";
import { useAnimationFrame, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface TextPressureProps extends React.HTMLAttributes<HTMLDivElement> {
  text?: string;
  fontFamily?: string;
  fontUrl?: string;
  width?: boolean;
  weight?: boolean;
  italic?: boolean;
  alpha?: boolean;
  flex?: boolean;
  stroke?: boolean;
  scale?: boolean;
  textColor?: string;
  strokeColor?: string;
  strokeWidth?: number;
  minFontSize?: number;
}

export function TextPressure({
  text = "Pressure",
  fontFamily = "Roboto Flex",
  fontUrl = "https://fonts.googleapis.com/css2?family=Roboto+Flex:opsz,wdth,wght@8..144,25..151,100..1000&display=swap",
  width = true,
  weight = true,
  italic = true,
  alpha = false,
  flex = true,
  stroke = false,
  scale = false,
  textColor = "hsl(var(--foreground))",
  strokeColor = "hsl(var(--foreground))",
  strokeWidth = 2,
  minFontSize = 24,
  className,
  ...props
}: TextPressureProps) {
  const reduceMotion = useReducedMotion();
  const boxRef = React.useRef<HTMLDivElement>(null);
  const lineRef = React.useRef<HTMLDivElement>(null);
  const letters = React.useRef<(HTMLSpanElement | null)[]>([]);
  const target = React.useRef<{ x: number; y: number } | null>(null);
  const cursor = React.useRef({ x: 0, y: 0 });
  const [fontSize, setFontSize] = React.useState(minFontSize);
  const [stretch, setStretch] = React.useState(1);
  const chars = Array.from(text);

  React.useEffect(() => {
    if (document.querySelector(`link[href="${fontUrl}"]`)) return;
    const link = document.createElement("link");
    link.rel = "stylesheet";
    link.href = fontUrl;
    document.head.appendChild(link);
  }, [fontUrl]);

  React.useEffect(() => {
    const box = boxRef.current!;
    const fit = () => {
      const rect = box.getBoundingClientRect();
      setFontSize(
        Math.max(minFontSize, Math.min(rect.width / (chars.length / 2), rect.height || Infinity)),
      );
      cursor.current = { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
    };
    fit();
    const observer = new ResizeObserver(fit);
    observer.observe(box);
    const track = (e: PointerEvent) => (target.current = { x: e.clientX, y: e.clientY });
    window.addEventListener("pointermove", track);
    return () => {
      observer.disconnect();
      window.removeEventListener("pointermove", track);
    };
  }, [chars.length, minFontSize]);

  React.useLayoutEffect(() => {
    if (!scale) return setStretch(1);
    const lineHeight = lineRef.current!.getBoundingClientRect().height / stretch;
    setStretch(boxRef.current!.clientHeight / lineHeight || 1);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [scale, fontSize, text]);

  useAnimationFrame(() => {
    const box = boxRef.current;
    if (!box) return;
    const goal = target.current ?? cursor.current;
    const ease = reduceMotion ? 1 : 0.12;
    cursor.current.x += (goal.x - cursor.current.x) * ease;
    cursor.current.y += (goal.y - cursor.current.y) * ease;
    const reach = box.getBoundingClientRect().width / 2 || 1;

    for (const el of letters.current) {
      if (!el) continue;
      const r = el.getBoundingClientRect();
      const d = Math.hypot(
        cursor.current.x - (r.left + r.width / 2),
        cursor.current.y - (r.top + r.height / 2),
      );
      const pull = Math.max(0, 1 - d / reach);
      const wdth = width ? 25 + pull * 125 : 100;
      const wght = weight ? 100 + pull * 800 : 400;
      el.style.fontVariationSettings = `"wdth" ${wdth.toFixed(0)}, "wght" ${wght.toFixed(0)}, "ital" ${italic ? pull.toFixed(2) : 0}`;
      el.style.opacity = alpha ? pull.toFixed(2) : "1";
    }
  });

  return (
    <div
      ref={boxRef}
      className={cn("relative h-full w-full overflow-hidden", className)}
      {...props}
    >
      <div
        ref={lineRef}
        aria-label={text}
        role="img"
        className={cn("select-none whitespace-nowrap uppercase", flex && "flex justify-between")}
        style={{
          fontFamily,
          fontSize,
          lineHeight: 1,
          color: textColor,
          transform: `scaleY(${stretch})`,
          transformOrigin: "top center",
          WebkitTextStroke: stroke ? `${strokeWidth}px ${strokeColor}` : undefined,
        }}
      >
        {chars.map((char, i) => (
          <span
            key={i}
            aria-hidden
            ref={(el) => {
              letters.current[i] = el;
            }}
            className="inline-block"
          >
            {char === " " ? " " : char}
          </span>
        ))}
      </div>
    </div>
  );
}
```

---

# True Focus

> A typographic animation that moves a camera-like focus frame between words while blurring the rest.

Install: `npx @modus-ui/cli add true-focus`

A typographic animation that moves a camera-like focus frame between words while blurring the rest. It supports both automatic interval scrolling and manual hover modes.

## Installation

### CLI

```bash
npx @modus-ui/cli add true-focus
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/true-focus.tsx`.
3. Paste the code.

## Usage

```tsx
import { TrueFocus } from "@/components/ui/true-focus";

export default function Example() {
  return (
    <TrueFocus
      sentence="Focus On What Matters"
      manualMode={false}
      blurAmount={4}
      borderColor="hsl(var(--primary))"
      animationDuration={0.6}
      pauseBetweenAnimations={1.5}
    />
  );
}
```

## Props

| Prop                     | Type      | Default                       | Description                                                |
| :----------------------- | :-------- | :---------------------------- | :--------------------------------------------------------- |
| `sentence`               | `string`  | `"True Focus"`                | The sentence to render.                                    |
| `separator`              | `string`  | `" "`                         | String the sentence is split on.                           |
| `manualMode`             | `boolean` | `false`                       | Focuses the hovered word instead of cycling automatically. |
| `blurAmount`             | `number`  | `5`                           | Blur in pixels on unfocused words.                         |
| `borderColor`            | `string`  | `"hsl(var(--primary))"`       | Colour of the focus frame corners.                         |
| `glowColor`              | `string`  | `"hsl(var(--primary) / 0.6)"` | Glow colour around the focus frame.                        |
| `animationDuration`      | `number`  | `0.5`                         | Seconds the focus frame takes to move.                     |
| `pauseBetweenAnimations` | `number`  | `1`                           | Seconds between automatic moves.                           |

## Source

`components/ui/true-focus.tsx`

```tsx
"use client";
// Moves a corner-bracket focus frame between words, blurring the rest.
import { useEffect, useId, useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface TrueFocusProps {
  sentence?: string;
  separator?: string;
  manualMode?: boolean;
  blurAmount?: number;
  borderColor?: string;
  glowColor?: string;
  animationDuration?: number;
  pauseBetweenAnimations?: number;
  className?: string;
}

const CORNERS = [
  "left-0 top-0 border-l-[3px] border-t-[3px]",
  "right-0 top-0 border-r-[3px] border-t-[3px]",
  "bottom-0 left-0 border-b-[3px] border-l-[3px]",
  "bottom-0 right-0 border-b-[3px] border-r-[3px]",
];

export function TrueFocus({
  sentence = "True Focus",
  separator = " ",
  manualMode = false,
  blurAmount = 5,
  borderColor = "hsl(var(--primary))",
  glowColor = "hsl(var(--primary) / 0.6)",
  animationDuration = 0.5,
  pauseBetweenAnimations = 1,
  className,
}: TrueFocusProps) {
  const reduce = useReducedMotion();
  const frameId = useId();
  const words = sentence.split(separator);
  const [focus, setFocus] = useState(0);
  const duration = reduce ? 0 : animationDuration;

  useEffect(() => {
    if (manualMode) return;
    const id = setInterval(
      () => setFocus((f) => (f + 1) % words.length),
      (animationDuration + pauseBetweenAnimations) * 1000,
    );
    return () => clearInterval(id);
  }, [manualMode, animationDuration, pauseBetweenAnimations, words.length]);

  return (
    <p
      className={cn(
        "flex flex-wrap items-center justify-center gap-x-5 gap-y-3 text-5xl font-bold text-[hsl(var(--foreground))]",
        className,
      )}
      aria-label={sentence}
    >
      {words.map((word, i) => (
        <span
          key={i}
          aria-hidden
          className="relative px-2 py-1"
          onMouseEnter={manualMode ? () => setFocus(i) : undefined}
        >
          <motion.span
            className="block"
            animate={{ filter: `blur(${i === focus ? 0 : blurAmount}px)` }}
            transition={{ duration }}
          >
            {word}
          </motion.span>
          {i === focus && (
            <motion.span
              layoutId={frameId}
              transition={{ duration, ease: "easeInOut" }}
              className="pointer-events-none absolute -inset-1"
            >
              {CORNERS.map((pos) => (
                <span
                  key={pos}
                  className={cn("absolute h-4 w-4 rounded-[3px]", pos)}
                  style={{ borderColor, filter: `drop-shadow(0 0 4px ${glowColor})` }}
                />
              ))}
            </motion.span>
          )}
        </span>
      ))}
    </p>
  );
}
```

---

# Gradient Text

> Seamlessly looping animated gradient text that can optionally wrap its borders.

Install: `npx @modus-ui/cli add gradient-text`

Seamlessly looping animated gradient text driven by `framer-motion` animation frames. Includes support for horizontal, vertical, and diagonal sweeps, and an optional gradient border tracing mode.

## Installation

### CLI

```bash
npx @modus-ui/cli add gradient-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/gradient-text.tsx`.
3. Paste the code.

## Usage

```tsx
import { GradientText } from "@/components/ui/gradient-text";

export default function Example() {
  return (
    <GradientText
      className="text-4xl font-bold"
      colors={[
        "hsl(var(--primary))",
        "hsl(var(--primary))",
        "hsl(var(--primary))",
        "hsl(var(--primary))",
      ]}
      animationSpeed={5}
    >
      Fluid Gradient Text
    </GradientText>
  );
}
```

## Props

| Prop             | Type                                       | Default                                                                                                               | Description                                           |
| :--------------- | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
| `colors`         | `string[]`                                 | `["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"]` | Colours of the gradient.                              |
| `animationSpeed` | `number`                                   | `8`                                                                                                                   | Seconds for one gradient cycle.                       |
| `showBorder`     | `boolean`                                  | `false`                                                                                                               | Adds an animated gradient border.                     |
| `direction`      | `"horizontal" \| "vertical" \| "diagonal"` | `"horizontal"`                                                                                                        | Direction the gradient moves.                         |
| `pauseOnHover`   | `boolean`                                  | `false`                                                                                                               | Pauses the animation while hovered.                   |
| `yoyo`           | `boolean`                                  | `true`                                                                                                                | Reverses the animation each cycle instead of looping. |

## Source

`components/ui/gradient-text.tsx`

```tsx
"use client";
// Text filled with a gradient that sweeps continuously, with an optional matching border.

import { useRef, useState, type ReactNode } from "react";
import {
  motion,
  useAnimationFrame,
  useMotionValue,
  useReducedMotion,
  useTransform,
} from "framer-motion";
import { cn } from "@/lib/utils";

type Direction = "horizontal" | "vertical" | "diagonal";

export interface GradientTextProps {
  children: ReactNode;
  className?: string;
  colors?: string[];
  animationSpeed?: number;
  showBorder?: boolean;
  direction?: Direction;
  pauseOnHover?: boolean;
  yoyo?: boolean;
}

const SWEEP: Record<Direction, { angle: string; size: string; at: (p: number) => string }> = {
  horizontal: { angle: "to right", size: "200% 100%", at: (p) => `${p}% 50%` },
  vertical: { angle: "to bottom", size: "100% 200%", at: (p) => `50% ${p}%` },
  diagonal: { angle: "135deg", size: "200% 200%", at: (p) => `${p}% ${p}%` },
};

export function GradientText({
  children,
  className,
  colors = [
    "hsl(var(--primary))",
    "hsl(var(--primary))",
    "hsl(var(--primary))",
    "hsl(var(--primary))",
    "hsl(var(--primary))",
  ],
  animationSpeed = 8,
  showBorder = false,
  direction = "horizontal",
  pauseOnHover = false,
  yoyo = true,
}: GradientTextProps) {
  const reduceMotion = useReducedMotion();
  const [hovered, setHovered] = useState(false);
  const elapsed = useRef(0);
  const progress = useMotionValue(0);
  const sweep = SWEEP[direction];

  useAnimationFrame((_, delta) => {
    if (reduceMotion || (pauseOnHover && hovered)) return;
    elapsed.current += delta / 1000 / animationSpeed;
    const cycle = elapsed.current % (yoyo ? 2 : 1);
    progress.set(cycle > 1 ? 2 - cycle : cycle);
  });

  const backgroundPosition = useTransform(progress, (p) => sweep.at(p * 100));
  // The palette is laid out twice so the end of a loop lines up with its start.
  const stops = [...colors, ...colors, colors[0]].join(", ");
  const fill = {
    backgroundImage: `linear-gradient(${sweep.angle}, ${stops})`,
    backgroundSize: sweep.size,
    backgroundPosition,
  };

  const text = (
    <motion.span className="bg-clip-text text-transparent" style={fill}>
      {children}
    </motion.span>
  );

  return (
    <motion.span
      onHoverStart={() => setHovered(true)}
      onHoverEnd={() => setHovered(false)}
      className={cn("inline-flex max-w-full", showBorder && "rounded-full p-px", className)}
      style={showBorder ? fill : undefined}
    >
      {showBorder ? <span className="rounded-full bg-background px-5 py-2">{text}</span> : text}
    </motion.span>
  );
}
```

---

# Blur Text

> Smoothly unblurs text characters or words as they enter the viewport.

Install: `npx @modus-ui/cli add blur-text`

Smoothly unblurs text characters or words as they enter the viewport. A highly elegant and sophisticated text entrance animation powered entirely by Framer Motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add blur-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/blur-text.tsx`.
3. Paste the code.

## Usage

```tsx
import { BlurText } from "@/components/ui/blur-text";

export default function Example() {
  return (
    <BlurText
      text="Isn't this just beautiful?"
      delay={150}
      animateBy="words"
      direction="top"
      className="font-serif text-4xl"
    />
  );
}
```

## Props

| Prop                  | Type                                            | Default     | Description                                          |
| :-------------------- | :---------------------------------------------- | :---------- | :--------------------------------------------------- |
| `text`                | `string`                                        | `""`        | The text to animate.                                 |
| `delay`               | `number`                                        | `200`       | Milliseconds between each word or letter.            |
| `animateBy`           | `"words" \| "letters"`                          | `"words"`   | Whether to animate word by word or letter by letter. |
| `direction`           | `"top" \| "bottom"`                             | `"top"`     | Direction the text enters from.                      |
| `threshold`           | `number`                                        | `0.1`       | Fraction visible before the animation starts.        |
| `rootMargin`          | `string`                                        | `"0px"`     | Intersection observer root margin.                   |
| `animationFrom`       | `Record<string, any>`                           | -           | Starting animation values.                           |
| `animationTo`         | `Record<string, any>[]`                         | -           | Keyframes to animate through.                        |
| `easing`              | `string \| number[] \| ((t: number) => number)` | `"easeOut"` | Framer Motion easing.                                |
| `onAnimationComplete` | `() => void`                                    | -           | Called when the last segment finishes.               |
| `stepDuration`        | `number`                                        | `0.35`      | Seconds per keyframe step.                           |

## Source

`components/ui/blur-text.tsx`

```tsx
"use client";
// Words or letters sharpen out of a blur as the text scrolls into view.
import { useRef } from "react";
import { motion, useInView, useReducedMotion, type Easing } from "framer-motion";
import { cn } from "@/lib/utils";

interface BlurTextProps {
  text?: string;
  delay?: number;
  className?: string;
  animateBy?: "words" | "letters";
  direction?: "top" | "bottom";
  threshold?: number;
  rootMargin?: string;
  animationFrom?: Record<string, any>;
  animationTo?: Record<string, any>[];
  easing?: string | number[] | ((t: number) => number);
  onAnimationComplete?: () => void;
  stepDuration?: number;
}

export function BlurText({
  text = "",
  delay = 200,
  className,
  animateBy = "words",
  direction = "top",
  threshold = 0.1,
  rootMargin = "0px",
  animationFrom,
  animationTo,
  easing = "easeOut",
  onAnimationComplete,
  stepDuration = 0.35,
}: BlurTextProps) {
  const reduce = useReducedMotion();
  const ref = useRef<HTMLParagraphElement>(null);
  const inView = useInView(ref, {
    once: true,
    amount: threshold,
    margin: rootMargin as NonNullable<Parameters<typeof useInView>[1]>["margin"],
  });

  const offset = direction === "top" ? -1 : 1;
  const from = animationFrom ?? { filter: "blur(10px)", opacity: 0, y: 40 * offset };
  const steps = animationTo ?? [
    { filter: "blur(4px)", opacity: 0.5, y: 6 * offset },
    { filter: "blur(0px)", opacity: 1, y: 0 },
  ];
  // Merge the start state and each step into per-property keyframe arrays.
  const keyframes = Object.fromEntries(
    Object.keys(from).map((key) => [key, [from[key], ...steps.map((s) => s[key] ?? from[key])]]),
  );
  const times = keyframes[Object.keys(from)[0]]?.map((_: unknown, i: number) => i / steps.length);

  const parts = animateBy === "words" ? text.split(" ") : [...text];
  // Reduced motion jumps straight to the final state; the start state stays the same so the
  // first render matches the server's.
  const settled = steps[steps.length - 1];

  return (
    <p ref={ref} className={cn("flex flex-wrap", className)} aria-label={text}>
      {parts.map((part, i) => (
        <motion.span
          key={i}
          aria-hidden
          className="inline-block whitespace-pre will-change-[transform,filter,opacity]"
          initial={from}
          animate={reduce ? settled : inView ? keyframes : undefined}
          transition={
            reduce
              ? { duration: 0 }
              : {
                  duration: stepDuration * steps.length,
                  times,
                  delay: (i * delay) / 1000,
                  ease: easing as Easing,
                }
          }
          onAnimationComplete={i === parts.length - 1 ? onAnimationComplete : undefined}
        >
          {part}
          {animateBy === "words" && i < parts.length - 1 ? " " : ""}
        </motion.span>
      ))}
    </p>
  );
}
```

---

# Split Text

> Staggered text animations splitting by characters, words, or lines.

Install: `npx @modus-ui/cli add split-text`

Staggered text animations splitting by characters, words, or lines. A native Framer Motion implementation that achieves the same beautiful effect as GSAP's premium SplitText plugin without the cost or bundle size.

## Installation

### CLI

```bash
npx @modus-ui/cli add split-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/split-text.tsx`.
3. Paste the code.

## Usage

```tsx
import { SplitText } from "@/components/ui/split-text";

export default function Example() {
  return (
    <SplitText
      text="The details are not the details."
      delay={0.03}
      splitType="chars"
      className="font-serif text-3xl"
    />
  );
}
```

## Props

| Prop        | Type                                         | Default    | Description                                   |
| :---------- | :------------------------------------------- | :--------- | :-------------------------------------------- |
| `text`      | `string`                                     | -          | The text to animate.                          |
| `delay`     | `number`                                     | `0.05`     | Seconds between each segment.                 |
| `duration`  | `number`                                     | `0.5`      | Seconds each segment animates for.            |
| `splitType` | `"chars" \| "words" \| "lines"`              | `"chars"`  | How the text is split into segments.          |
| `threshold` | `number`                                     | `0.1`      | Fraction visible before the animation starts. |
| `textAlign` | `"left" \| "center" \| "right" \| "justify"` | `"center"` | Text alignment.                               |
| `as`        | `React.ElementType`                          | `"p"`      | Element to render as.                         |

## Source

`components/ui/split-text.tsx`

```tsx
"use client";

import { motion, useInView, useReducedMotion } from "framer-motion";
import { useRef } from "react";
import { cn } from "@/lib/utils";

interface SplitTextProps {
  text: string;
  className?: string;
  delay?: number;
  duration?: number;
  splitType?: "chars" | "words" | "lines";
  threshold?: number;
  textAlign?: "left" | "center" | "right" | "justify";
  as?: React.ElementType;
}

export function SplitText({
  text,
  className,
  delay = 0.05,
  duration = 0.5,
  splitType = "chars",
  threshold = 0.1,
  textAlign = "center",
  as: Tag = "p",
}: SplitTextProps) {
  const ref = useRef<HTMLElement>(null);
  const inView = useInView(ref, { once: true, amount: threshold });
  const prefersReducedMotion = useReducedMotion();

  const containerVariants = {
    hidden: { opacity: 0 },
    visible: {
      opacity: 1,
      transition: {
        staggerChildren: delay,
      },
    },
  };

  const itemVariants = {
    hidden: { opacity: 0, y: 40 },
    visible: {
      opacity: 1,
      y: 0,
      transition: { duration, ease: [0.25, 0.1, 0.25, 1] as any },
    },
  };

  const renderContent = () => {
    if (splitType === "words") {
      const words = text.split(" ");
      return words.map((word, i) => (
        <motion.span key={i} variants={itemVariants} className="inline-block whitespace-pre">
          {word}
          {i !== words.length - 1 ? " " : ""}
        </motion.span>
      ));
    }

    if (splitType === "chars") {
      const words = text.split(" ");
      return words.map((word, wordIndex) => (
        <span key={wordIndex} className="inline-block whitespace-pre">
          {word.split("").map((char, charIndex) => (
            <motion.span
              key={`${wordIndex}-${charIndex}`}
              variants={itemVariants}
              className="inline-block"
            >
              {char}
            </motion.span>
          ))}
          {wordIndex !== words.length - 1 ? " " : ""}
        </span>
      ));
    }

    // Lines are a bit tricky without JS width measurement,
    // but splitting by newline is a good fallback.
    const lines = text.split("\n");
    return lines.map((line, i) => (
      <motion.div key={i} variants={itemVariants} className="block">
        {line}
      </motion.div>
    ));
  };

  const MotionTag = motion.create(Tag);

  return (
    <MotionTag
      ref={ref}
      variants={containerVariants}
      // Reduced motion: render the settled text from the first frame.
      initial={prefersReducedMotion ? false : "hidden"}
      animate={prefersReducedMotion || inView ? "visible" : "hidden"}
      className={cn("overflow-hidden", className)}
      style={{ textAlign }}
    >
      {renderContent()}
    </MotionTag>
  );
}
```

---

# Decrypted Text

> A hacker-style text decryption matrix effect that scrambles text before revealing it.

Install: `npx @modus-ui/cli add decrypted-text`

A hacker-style text decryption matrix effect that scrambles text before revealing it. Can trigger on hover or when scrolled into view.

## Installation

### CLI

```bash
npx @modus-ui/cli add decrypted-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/decrypted-text.tsx`.
3. Paste the code.

## Usage

```tsx
import { DecryptedText } from "@/components/ui/decrypted-text";

export default function Example() {
  return (
    <DecryptedText
      text="Hover over me to decrypt"
      animateOn="hover"
      speed={40}
      className="font-mono text-4xl"
    />
  );
}
```

## Props

| Prop                   | Type                           | Default                                                              | Description                                           |
| :--------------------- | :----------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------- |
| `text`                 | `string`                       | -                                                                    | The text to reveal.                                   |
| `speed`                | `number`                       | `50`                                                                 | Milliseconds between scramble frames.                 |
| `maxIterations`        | `number`                       | `10`                                                                 | Scramble frames before revealing when not sequential. |
| `sequential`           | `boolean`                      | `false`                                                              | Reveals one character at a time.                      |
| `revealDirection`      | `"start" \| "end" \| "center"` | `"start"`                                                            | Where sequential reveal starts.                       |
| `useOriginalCharsOnly` | `boolean`                      | `false`                                                              | Scrambles using only the text's own characters.       |
| `characters`           | `string`                       | `"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#$%^&*()_+"` | Characters used for scrambling.                       |
| `parentClassName`      | `string`                       | -                                                                    | Classes for the wrapper.                              |
| `encryptedClassName`   | `string`                       | -                                                                    | Classes for still-scrambled characters.               |
| `animateOn`            | `"view" \| "hover"`            | `"hover"`                                                            | Whether to run on hover or when scrolled into view.   |
| `delay`                | `number`                       | `0`                                                                  | Milliseconds to wait before starting.                 |

## Source

`components/ui/decrypted-text.tsx`

```tsx
"use client";
// Scrambles text with random glyphs, then resolves it on hover or when in view.
import { useEffect, useMemo, useRef, useState } from "react";
import { useInView, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface DecryptedTextProps {
  text: string;
  speed?: number;
  maxIterations?: number;
  sequential?: boolean;
  revealDirection?: "start" | "end" | "center";
  useOriginalCharsOnly?: boolean;
  characters?: string;
  className?: string;
  parentClassName?: string;
  encryptedClassName?: string;
  animateOn?: "view" | "hover";
  delay?: number;
}

export function DecryptedText({
  text,
  speed = 50,
  maxIterations = 10,
  sequential = false,
  revealDirection = "start",
  useOriginalCharsOnly = false,
  characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#$%^&*()_+",
  className,
  parentClassName,
  encryptedClassName,
  animateOn = "hover",
  delay = 0,
}: DecryptedTextProps) {
  const reduce = useReducedMotion();
  const ref = useRef<HTMLSpanElement>(null);
  const inView = useInView(ref, { once: true, amount: 0.5 });
  const [active, setActive] = useState(false);
  // Frames elapsed since the run started; -1 means idle (plain text shown).
  const [frame, setFrame] = useState(-1);

  const pool = useMemo(
    () => (useOriginalCharsOnly ? [...new Set(text.replace(/\s/g, ""))].join("") : characters),
    [useOriginalCharsOnly, text, characters],
  );

  // Indices in the order they resolve during a sequential reveal.
  const order = useMemo(() => {
    const idx = [...text].map((_, i) => i);
    if (revealDirection === "end") return idx.reverse();
    if (revealDirection === "center") {
      const mid = (text.length - 1) / 2;
      return idx.sort((a, b) => Math.abs(a - mid) - Math.abs(b - mid));
    }
    return idx;
  }, [text, revealDirection]);

  const totalFrames = sequential ? text.length : maxIterations;

  useEffect(() => {
    if (animateOn === "view" && inView) setActive(true);
  }, [animateOn, inView]);

  useEffect(() => {
    if (!active || reduce) return setFrame(-1);
    let tick: ReturnType<typeof setInterval>;
    const start = setTimeout(() => {
      setFrame(0);
      tick = setInterval(() => {
        setFrame((f) => {
          if (f + 1 < totalFrames) return f + 1;
          clearInterval(tick);
          return -1;
        });
      }, speed);
    }, delay);
    return () => {
      clearTimeout(start);
      clearInterval(tick);
    };
  }, [active, reduce, speed, delay, totalFrames]);

  const resolved = useMemo(
    () => new Set(sequential && frame >= 0 ? order.slice(0, frame) : []),
    [sequential, frame, order],
  );

  return (
    <span
      ref={ref}
      className={cn("inline-block whitespace-pre-wrap", parentClassName)}
      onMouseEnter={animateOn === "hover" ? () => setActive(true) : undefined}
      onMouseLeave={animateOn === "hover" ? () => setActive(false) : undefined}
    >
      <span className="sr-only">{text}</span>
      <span aria-hidden className={className}>
        {[...text].map((char, i) => {
          const scrambled = frame >= 0 && char.trim() !== "" && !resolved.has(i);
          return (
            <span key={i} className={scrambled ? encryptedClassName : undefined}>
              {scrambled ? pool[Math.floor(Math.random() * pool.length)] : char}
            </span>
          );
        })}
      </span>
    </span>
  );
}
```

---

# Shimmer Text

> Animated text that shimmers with a flowing gradient effect.

Install: `npx @modus-ui/cli add shimmer-text`

Animated text that shimmers with a flowing gradient effect. Great for highlighting new features, primary calls-to-action, or hero section headlines.

## Installation

### CLI

```bash
npx @modus-ui/cli add shimmer-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/shimmer-text.tsx`.
3. Paste the code.

## Usage

```tsx
import { ShimmerText } from "@/components/ui/shimmer-text";

export default function Example() {
  return (
    <h1>
      <ShimmerText text="Build Interfaces Faster" />
    </h1>
  );
}
```

## Props

| Prop           | Type     | Default                          | Description                        |
| :------------- | :------- | :------------------------------- | :--------------------------------- |
| `text`         | `string` | -                                | The text to display and animate.   |
| `baseColor`    | `string` | `"hsl(var(--muted-foreground))"` | The main text color.               |
| `shimmerColor` | `string` | `"hsl(var(--foreground))"`       | The color of the shimmer gradient. |
| `speed`        | `number` | `3`                              | Animation duration in seconds.     |
| `spread`       | `number` | `120`                            | The angle of the linear gradient.  |

## Source

`components/ui/shimmer-text.tsx`

```tsx
"use client";

import React from "react";
import { motion, HTMLMotionProps, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ShimmerTextProps extends HTMLMotionProps<"span"> {
  text: string;
  className?: string;
  baseColor?: string;
  shimmerColor?: string;
  speed?: number;
  spread?: number;
}

export function ShimmerText({
  text,
  className,
  baseColor = "hsl(var(--muted-foreground))",
  shimmerColor = "hsl(var(--foreground))",
  speed = 3,
  spread = 120,
  ...props
}: ShimmerTextProps) {
  const prefersReducedMotion = useReducedMotion();

  const gradientStyle = {
    backgroundImage: `linear-gradient(${spread}deg, ${baseColor} 0%, ${baseColor} 35%, ${shimmerColor} 50%, ${baseColor} 65%, ${baseColor} 100%)`,
    backgroundSize: "200% auto",
    WebkitBackgroundClip: "text",
    backgroundClip: "text",
    color: "transparent",
  };

  return (
    <motion.span
      className={cn("inline-block font-medium", className)}
      style={gradientStyle}
      // Reduced motion: hold a still frame with the highlight centred on the text.
      initial={prefersReducedMotion ? false : { backgroundPosition: "200% center" }}
      animate={
        prefersReducedMotion
          ? { backgroundPosition: "50% center" }
          : { backgroundPosition: "-50% center" }
      }
      transition={
        prefersReducedMotion
          ? { duration: 0 }
          : { repeat: Infinity, duration: speed, ease: "linear" }
      }
      {...props}
    >
      {text}
    </motion.span>
  );
}
```

---

# Floating Text

> A text component that floats and drifts subtly, creating an editorial, high-end feel.

Install: `npx @modus-ui/cli add floating-text`

A text component that floats and drifts subtly, creating an editorial, high-end feel. Use it for hero sections or decorative atmospheric text.

## Installation

### CLI

```bash
npx @modus-ui/cli add floating-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/floating-text.tsx`.
3. Paste the code.

## Usage

```tsx
import { FloatingText } from "@/components/ui/floating-text";

export default function Example() {
  return <FloatingText className="font-serif text-4xl">Editorial Atmosphere</FloatingText>;
}
```

## Props

| Prop        | Type        | Default | Description                          |
| :---------- | :---------- | :------ | :----------------------------------- |
| `children`  | `ReactNode` | -       | The text or elements to float.       |
| `className` | `string`    | -       | Additional CSS classes for the text. |

## Source

`components/ui/floating-text.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

interface FloatingTextProps {
  children: React.ReactNode;
  className?: string;
}

export function FloatingText({ children, className }: FloatingTextProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      className={cn("inline-block", className)}
      animate={prefersReducedMotion ? { y: 0 } : { y: [0, -10, 0] }}
      transition={
        prefersReducedMotion
          ? { duration: 0 }
          : { duration: 2, repeat: Infinity, ease: "easeInOut" }
      }
    >
      {children}
    </motion.div>
  );
}
```

---

# Animated Beam

> A dynamic SVG beam animation that traces paths between elements.

Install: `npx @modus-ui/cli add animated-beam`

A beautiful component that shoots a glowing gradient pulse along an SVG path connecting two HTML elements. It mathematically calculates the path curves automatically based on the live geometry and position of the DOM nodes using `ResizeObserver`.

## Installation

### CLI

```bash
npx @modus-ui/cli add animated-beam
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/animated-beam.tsx`.
3. Paste the code.

## Usage

```tsx
import { useRef } from "react";
import { AnimatedBeam } from "@/components/ui/animated-beam";

export default function Example() {
  const containerRef = useRef<HTMLDivElement>(null);
  const fromRef = useRef<HTMLDivElement>(null);
  const toRef = useRef<HTMLDivElement>(null);

  return (
    <div ref={containerRef} className="relative flex justify-between p-10">
      <div ref={fromRef}>Node A</div>
      <div ref={toRef}>Node B</div>
      <AnimatedBeam containerRef={containerRef} fromRef={fromRef} toRef={toRef} curvature={-50} />
    </div>
  );
}
```

## Props

| Prop            | Type                             | Default                 | Description                         |
| :-------------- | :------------------------------- | :---------------------- | :---------------------------------- |
| `containerRef`  | `RefObject<HTMLElement \| null>` | -                       | The container both elements sit in. |
| `fromRef`       | `RefObject<HTMLElement \| null>` | -                       | The element the beam starts at.     |
| `toRef`         | `RefObject<HTMLElement \| null>` | -                       | The element the beam ends at.       |
| `curvature`     | `number`                         | `0`                     | Bend of the path in pixels.         |
| `reverse`       | `boolean`                        | `false`                 | Runs the beam from end to start.    |
| `duration`      | `number`                         | `3`                     | Seconds for one beam pass.          |
| `delay`         | `number`                         | `0`                     | Seconds before the beam starts.     |
| `pathColor`     | `string`                         | `"hsl(var(--border))"`  | Colour of the static path.          |
| `gradientStart` | `string`                         | `"hsl(var(--primary))"` | Start colour of the beam.           |
| `gradientStop`  | `string`                         | `"hsl(var(--primary))"` | End colour of the beam.             |

## Source

`components/ui/animated-beam.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";
import { useCallback, useEffect, useId, useState, type RefObject } from "react";
import { cn } from "@/lib/utils";

interface AnimatedBeamProps {
  containerRef: RefObject<HTMLElement | null>;
  fromRef: RefObject<HTMLElement | null>;
  toRef: RefObject<HTMLElement | null>;
  curvature?: number;
  reverse?: boolean;
  duration?: number;
  delay?: number;
  pathColor?: string;
  gradientStart?: string;
  gradientStop?: string;
  className?: string;
}

export function AnimatedBeam({
  containerRef,
  fromRef,
  toRef,
  curvature = 0,
  reverse = false,
  duration = 3,
  delay = 0,
  pathColor = "hsl(var(--border))",
  gradientStart = "hsl(var(--primary))",
  gradientStop = "hsl(var(--primary))",
  className = "",
}: AnimatedBeamProps) {
  const gradientId = useId();
  const [path, setPath] = useState("");
  const [size, setSize] = useState({ width: 0, height: 0 });
  const prefersReducedMotion = useReducedMotion();

  const measure = useCallback(() => {
    const container = containerRef.current;
    const from = fromRef.current;
    const to = toRef.current;
    if (!container || !from || !to) return;

    const containerRect = container.getBoundingClientRect();
    const fromRect = from.getBoundingClientRect();
    const toRect = to.getBoundingClientRect();

    setSize({ width: containerRect.width, height: containerRect.height });

    const startX = fromRect.left - containerRect.left + fromRect.width / 2;
    const startY = fromRect.top - containerRect.top + fromRect.height / 2;
    const endX = toRect.left - containerRect.left + toRect.width / 2;
    const endY = toRect.top - containerRect.top + toRect.height / 2;

    const controlX = (startX + endX) / 2;
    const controlY = (startY + endY) / 2 - curvature;

    setPath(`M ${startX},${startY} Q ${controlX},${controlY} ${endX},${endY}`);
  }, [containerRef, fromRef, toRef, curvature]);

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

    const observer = new ResizeObserver(measure);
    observer.observe(container);
    if (fromRef.current) observer.observe(fromRef.current);
    if (toRef.current) observer.observe(toRef.current);

    return () => observer.disconnect();
  }, [measure, containerRef, fromRef, toRef]);

  if (!path) return null;

  return (
    <svg
      fill="none"
      width={size.width}
      height={size.height}
      viewBox={`0 0 ${size.width} ${size.height}`}
      aria-hidden="true"
      className={cn("pointer-events-none absolute left-0 top-0 overflow-visible", className)}
    >
      <path d={path} stroke={pathColor} strokeWidth={2} strokeLinecap="round" strokeOpacity={0.4} />
      <path d={path} stroke={`url(#${gradientId})`} strokeWidth={2} strokeLinecap="round" />
      <defs>
        <motion.linearGradient
          id={gradientId}
          gradientUnits="userSpaceOnUse"
          initial={{ x1: "0%", x2: "0%", y1: "0%", y2: "0%" }}
          animate={
            prefersReducedMotion
              ? { x1: "0%", x2: "100%", y1: "0%", y2: "0%" }
              : {
                  x1: reverse ? ["100%", "-10%"] : ["-10%", "100%"],
                  x2: reverse ? ["110%", "0%"] : ["0%", "110%"],
                  y1: ["0%", "0%"],
                  y2: ["0%", "0%"],
                }
          }
          transition={{
            duration,
            delay,
            repeat: prefersReducedMotion ? 0 : Infinity,
            repeatDelay: 0.4,
            ease: "easeInOut",
          }}
        >
          <stop stopColor={gradientStart} stopOpacity="0" />
          <stop stopColor={gradientStart} />
          <stop offset="32.5%" stopColor={gradientStop} />
          <stop offset="100%" stopColor={gradientStop} stopOpacity="0" />
        </motion.linearGradient>
      </defs>
    </svg>
  );
}
```

---

# Border Beam

> A glowing, animated gradient beam that endlessly traces the perimeter.

Install: `npx @modus-ui/cli add border-beam`

A popular SaaS design element. It wraps any container and mathematically rotates a glowing `conic-gradient` beam perfectly along its edge borders without bleeding into the background.

## Installation

### CLI

```bash
npx @modus-ui/cli add border-beam
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/border-beam.tsx`.
3. Paste the code.

## Usage

```tsx
import { BorderBeam } from "@/components/ui/border-beam";

export default function Example() {
  return (
    <div className="relative rounded-xl border bg-card p-6">
      <h3>Card Content</h3>
      <BorderBeam size={100} duration={6} />
    </div>
  );
}
```

## Props

| Prop          | Type     | Default                 | Description                                  |
| :------------ | :------- | :---------------------- | :------------------------------------------- |
| `duration`    | `number` | `8`                     | Seconds for one full trip around the border. |
| `borderWidth` | `number` | `1.5`                   | Thickness of the beam in pixels.             |
| `size`        | `number` | `200`                   | Length of the beam in pixels.                |
| `colorFrom`   | `string` | `"hsl(var(--primary))"` | Start colour of the beam gradient.           |
| `colorTo`     | `string` | `"transparent"`         | End colour of the beam gradient.             |
| `delay`       | `number` | `0`                     | Seconds before the animation starts.         |

## Source

`components/ui/border-beam.tsx`

```tsx
"use client";

import { cn } from "@/lib/utils";
import { motion, useReducedMotion } from "framer-motion";

interface BorderBeamProps {
  /** The duration of the full perimeter rotation in seconds. */
  duration?: number;
  /** Thickness of the beam in pixels. */
  borderWidth?: number;
  /** Width of the beam gradient in pixels. */
  size?: number;
  /** CSS color values for the beam gradient. */
  colorFrom?: string;
  colorTo?: string;
  /** Optional delay before starting the animation. */
  delay?: number;
  className?: string;
}

export function BorderBeam({
  duration = 8,
  borderWidth = 1.5,
  size = 200,
  colorFrom = "hsl(var(--primary))",
  colorTo = "transparent",
  delay = 0,
  className,
}: BorderBeamProps) {
  // Null during SSR, so the tree must not branch on it: only the animation does.
  const prefersReducedMotion = useReducedMotion();

  return (
    <div
      className={cn(
        "pointer-events-none absolute inset-0 overflow-hidden rounded-[inherit]",
        className,
      )}
    >
      <div
        className="absolute inset-0 rounded-[inherit] border"
        style={{
          borderWidth,
          borderColor: "transparent",
          maskImage: `linear-gradient(to right, transparent, black ${size}px, black)`,
          maskComposite: "intersect",
          WebkitMaskComposite: "source-in",
        }}
      />

      {/* We use a large rotating rect that's masked out by the parent div to trace the edge. */}
      <motion.div
        className="absolute -left-1/2 -top-1/2 aspect-square h-[200%] w-[200%]"
        style={{
          background: `conic-gradient(from 90deg at 50% 50%, ${colorTo} 0%, ${colorFrom} 50%, ${colorTo} 100%)`,
        }}
        animate={prefersReducedMotion ? undefined : { rotate: 360 }}
        transition={{
          repeat: Infinity,
          duration,
          ease: "linear",
          delay,
        }}
      />
      {/* Cut out the inside */}
      <div
        className="absolute m-px rounded-[inherit] bg-background"
        style={{ inset: borderWidth }}
      />
    </div>
  );
}
```

---

# Bento Grid

> A highly structured, responsive layout primitive for creating asymmetric grid layouts.

Install: `npx @modus-ui/cli add bento-grid`

A layout primitive that perfectly solves the "Bento Box" design trend. It uses custom CSS properties to manage grid spans, ensuring that asymmetric layouts smoothly degrade to a single column on mobile devices without hard-coded media queries breaking the flow.

## Installation

### CLI

```bash
npx @modus-ui/cli add bento-grid
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/bento-grid.tsx`.
3. Paste the code.

## Usage

```tsx
import { BentoGrid, BentoCard } from "@/components/ui/bento-grid";

export default function Example() {
  return (
    <BentoGrid columns={3} gap={16}>
      <BentoCard colSpan={2}>Wide Card</BentoCard>
      <BentoCard colSpan={1}>Standard Card</BentoCard>
      <BentoCard colSpan={1} rowSpan={2}>
        Tall Card
      </BentoCard>
      <BentoCard colSpan={2}>Bottom Wide</BentoCard>
    </BentoGrid>
  );
}
```

## Props

| Prop      | Type     | Default | Description                  |
| :-------- | :------- | :------ | :--------------------------- |
| `columns` | `number` | `3`     | Number of grid columns.      |
| `gap`     | `number` | `16`    | Gap between cards in pixels. |

## Source

`components/ui/bento-grid.tsx`

```tsx
"use client";

import type { CSSProperties, ReactNode } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface BentoGridProps {
  children: ReactNode;
  columns?: number;
  gap?: number;
  className?: string;
}

interface BentoCardProps {
  children: ReactNode;
  colSpan?: number;
  rowSpan?: number;
  className?: string;
}

export function BentoGrid({ children, columns = 3, gap = 16, className = "" }: BentoGridProps) {
  return (
    <div
      className={cn(
        "grid grid-cols-1 sm:[grid-template-columns:repeat(var(--bento-columns),minmax(0,1fr))]",
        className,
      )}
      style={{ "--bento-columns": String(columns), gap } as CSSProperties}
    >
      {children}
    </div>
  );
}

export function BentoCard({ children, colSpan = 1, rowSpan = 1, className = "" }: BentoCardProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      className={cn(
        "relative flex flex-col overflow-hidden rounded-xl border border-border bg-card p-6 shadow-sm",
        "sm:[grid-column:span_var(--bento-col-span)] sm:[grid-row:span_var(--bento-row-span)]",
        className,
      )}
      style={
        {
          "--bento-col-span": String(colSpan),
          "--bento-row-span": String(rowSpan),
        } as CSSProperties
      }
      whileHover={prefersReducedMotion ? undefined : { y: -4 }}
      transition={{ type: "spring", stiffness: 320, damping: 26 }}
    >
      {children}
    </motion.div>
  );
}
```

---

# Erosion Plate

> A matted image plate that erodes under turbulence as the cursor moves.

Install: `npx @modus-ui/cli add erosion-plate`

Erosion Plate sets an image inside a bordered paper mat and follows the cursor with a gentle drift. The faster the pointer travels, the harder an `feTurbulence` displacement erodes the picture. Caption text sits on a theme-tinted fade.

## Installation

### CLI

```bash
npx @modus-ui/cli add erosion-plate
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/erosion-plate.tsx`.
3. Paste the code.

## Usage

```tsx
import { ErosionPlate } from "@/components/ui/erosion-plate";

export default function Example() {
  return (
    <ErosionPlate image="/your-image.jpg">
      <h2>Hover Me</h2>
    </ErosionPlate>
  );
}
```

## Props

| Prop              | Type     | Default                                                                                        | Description                                                      |
| :---------------- | :------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| `width`           | `number` | `300`                                                                                          | Card width in pixels.                                            |
| `height`          | `number` | `400`                                                                                          | Card height in pixels.                                           |
| `image`           | `string` | "https://images.unsplash.com/photo-1579546929518-9e396f3cc809?q=80&w=600&auto=format&fit=crop" | Image URL.                                                       |
| `baseFrequency`   | `number` | 0.022                                                                                          | Base frequency of the turbulence filter.                         |
| `numOctaves`      | `number` | 3                                                                                              | Octaves of the turbulence filter.                                |
| `seed`            | `number` | 11                                                                                             | Seed of the turbulence filter.                                   |
| `maxDisplacement` | `number` | 260                                                                                            | Maximum displacement of the distortion.                          |
| `movementBound`   | `number` | `50`                                                                                           | Distance in pixels the card follows the cursor before resisting. |

## Source

`components/ui/erosion-plate.tsx`

```tsx
"use client";
// A matted picture that drifts after the cursor and erodes harder the faster the pointer moves.
import { useEffect, useId, useRef, type ReactNode } from "react";
import { motion, useMotionValue, useReducedMotion, useSpring } from "framer-motion";
import { cn } from "@/lib/utils";

interface ErosionPlateProps {
  width?: number;
  height?: number;
  image?: string;
  baseFrequency?: number;
  numOctaves?: number;
  seed?: number;
  maxDisplacement?: number;
  movementBound?: number;
  children?: ReactNode;
  className?: string;
}

export function ErosionPlate({
  width = 300,
  height = 400,
  image = "https://images.unsplash.com/photo-1579546929518-9e396f3cc809?q=80&w=600&auto=format&fit=crop",
  baseFrequency = 0.022,
  numOctaves = 3,
  seed = 11,
  maxDisplacement = 260,
  movementBound = 50,
  children,
  className,
}: ErosionPlateProps) {
  const reduce = useReducedMotion();
  const filterId = `erode-${useId().replace(/:/g, "")}`;
  const plate = useRef<HTMLDivElement>(null);
  const displace = useRef<SVGFEDisplacementMapElement>(null);
  const dx = useMotionValue(0);
  const dy = useMotionValue(0);
  const x = useSpring(dx, { stiffness: 90, damping: 18 });
  const y = useSpring(dy, { stiffness: 90, damping: 18 });

  useEffect(() => {
    if (reduce) return;
    let wear = 0;
    let last: { x: number; y: number; t: number } | null = null;
    let frame = requestAnimationFrame(function decay() {
      wear *= 0.92;
      displace.current?.setAttribute("scale", wear.toFixed(1));
      frame = requestAnimationFrame(decay);
    });
    const onMove = (e: PointerEvent) => {
      const box = plate.current?.getBoundingClientRect();
      if (!box) return;
      const ox = e.clientX - (box.left + box.width / 2 - x.get());
      const oy = e.clientY - (box.top + box.height / 2 - y.get());
      // Soft leash: follows freely near the plate, then flattens out at movementBound.
      dx.set(movementBound * Math.tanh(ox / (movementBound * 6)));
      dy.set(movementBound * Math.tanh(oy / (movementBound * 6)));
      const now = performance.now();
      if (last) {
        const speed =
          Math.hypot(e.clientX - last.x, e.clientY - last.y) / Math.max(1, now - last.t);
        wear = Math.min(maxDisplacement, Math.max(wear, speed * maxDisplacement * 0.25));
      }
      last = { x: e.clientX, y: e.clientY, t: now };
    };
    window.addEventListener("pointermove", onMove);
    return () => {
      window.removeEventListener("pointermove", onMove);
      cancelAnimationFrame(frame);
    };
  }, [reduce, maxDisplacement, movementBound, dx, dy, x, y]);

  return (
    <motion.div
      ref={plate}
      className={cn(
        "relative overflow-hidden rounded-lg border border-border bg-card p-3 shadow-sm",
        className,
      )}
      style={{ width, height, x: reduce ? 0 : x, y: reduce ? 0 : y }}
    >
      <svg className="absolute h-0 w-0" aria-hidden>
        <filter id={filterId} x="-10%" y="-10%" width="120%" height="120%">
          <feTurbulence
            type="fractalNoise"
            baseFrequency={baseFrequency}
            numOctaves={numOctaves}
            seed={seed}
            result="grain"
          />
          <feDisplacementMap
            ref={displace}
            in="SourceGraphic"
            in2="grain"
            scale="0"
            xChannelSelector="R"
            yChannelSelector="G"
          />
        </filter>
      </svg>
      <div className="relative h-full w-full overflow-hidden rounded-md">
        <img
          src={image}
          alt=""
          draggable={false}
          className="h-full w-full scale-110 object-cover"
          style={{ filter: `url(#${filterId})` }}
        />
        {children && (
          <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-[hsl(var(--background))] via-[hsl(var(--background)/0.85)] to-transparent p-5 pt-16 text-foreground">
            {children}
          </div>
        )}
      </div>
    </motion.div>
  );
}
```

---

# Scratch to Reveal

> An interactive canvas component that lets users scratch off an overlay to reveal the content underneath.

Install: `npx @modus-ui/cli add scratch-to-reveal`

A highly optimized HTML5 `<canvas>` interaction. As the user scrubs their mouse across the container, it visually erases the overlay and calculates the cleared percentage of the bounding box. Once the threshold is crossed, it snaps the rest of the overlay away.

## Installation

### CLI

```bash
npx @modus-ui/cli add scratch-to-reveal
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/scratch-to-reveal.tsx`.
3. Paste the code.

## Usage

```tsx
import { ScratchToReveal } from "@/components/ui/scratch-to-reveal";

export default function Example() {
  return (
    <ScratchToReveal width={300} height={300} threshold={0.5}>
      <div className="flex h-full w-full items-center justify-center rounded-xl bg-muted p-8">
        <h2 className="text-xl font-bold">Hidden Treasure</h2>
      </div>
    </ScratchToReveal>
  );
}
```

## Props

| Prop           | Type     | Default                 | Description                                           |
| :------------- | :------- | :---------------------- | :---------------------------------------------------- |
| `width`        | `number` | -                       | Width of the scratch area in pixels.                  |
| `height`       | `number` | -                       | Height of the scratch area in pixels.                 |
| `brushSize`    | `number` | `40`                    | Radius of the scratch brush in pixels.                |
| `threshold`    | `number` | `0.5`                   | Fraction cleared before the rest is revealed.         |
| `overlayImage` | `string` | -                       | Image drawn on the scratch surface.                   |
| `overlayColor` | `string` | `"hsl(var(--primary))"` | Colour of the scratch surface when there is no image. |

## Source

`components/ui/scratch-to-reveal.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";
import { useEffect, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
import { cn } from "@/lib/utils";

interface ScratchToRevealProps {
  /** Size of the scratch area. Required. */
  width: number;
  height: number;
  /** Radius of the "coin" clearing the surface. */
  brushSize?: number;
  /** Minimum percent cleared before revealing everything. */
  threshold?: number;
  children: React.ReactNode;
  /** Optional overlay image source */
  overlayImage?: string;
  /** Fallback background color if no overlay image is provided */
  overlayColor?: string;
  className?: string;
}

export function ScratchToReveal({
  width,
  height,
  brushSize = 40,
  threshold = 0.5,
  children,
  overlayImage,
  overlayColor = "hsl(var(--primary))",
  className,
}: ScratchToRevealProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [revealed, setRevealed] = useState(false);

  // Points tracking for smooth lines
  const lastPoint = useRef<{ x: number; y: number } | null>(null);
  const moveCount = useRef(0);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;

    // Use a high-density canvas for retina screens
    const dpr = window.devicePixelRatio || 1;
    canvas.width = width * dpr;
    canvas.height = height * dpr;

    const ctx = canvas.getContext("2d");
    if (!ctx) return;
    ctx.scale(dpr, dpr);

    if (overlayImage) {
      const img = new Image();
      img.onload = () => {
        ctx.drawImage(img, 0, 0, width, height);
      };
      img.src = overlayImage;
    } else {
      // Canvas cannot resolve CSS variables; let the browser compute the color.
      canvas.style.color = overlayColor;
      ctx.fillStyle = getComputedStyle(canvas).color;
      ctx.fillRect(0, 0, width, height);
    }

    // Add noise texture for realism if using flat color
    if (!overlayImage) {
      for (let i = 0; i < width * height * 0.05; i++) {
        const x = Math.random() * width;
        const y = Math.random() * height;
        ctx.fillStyle = `rgba(255, 255, 255, ${Math.random() * 0.1})`;
        ctx.fillRect(x, y, 1, 1);
      }
    }
  }, [width, height, overlayImage, overlayColor]);

  const clearedFraction = () => {
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return 0;

    const pixels = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
    let emptyCount = 0;

    // Check alpha channel (every 4th value)
    for (let i = 3; i < pixels.length; i += 4) {
      if (pixels[i] === 0) emptyCount++;
    }

    return emptyCount / (canvas.width * canvas.height);
  };

  const finish = () => {
    if (revealed) return;
    setRevealed(true);
  };

  const scratch = (x: number, y: number) => {
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return;

    ctx.globalCompositeOperation = "destination-out";
    ctx.lineJoin = "round";
    ctx.lineCap = "round";
    ctx.lineWidth = brushSize;

    if (lastPoint.current) {
      ctx.beginPath();
      ctx.moveTo(lastPoint.current.x, lastPoint.current.y);
      ctx.lineTo(x, y);
      ctx.stroke();
    } else {
      ctx.beginPath();
      ctx.arc(x, y, brushSize / 2, 0, Math.PI * 2);
      ctx.fill();
    }
    lastPoint.current = { x, y };
  };

  const handlePointerDown = (event: PointerEvent<HTMLCanvasElement>) => {
    if (revealed) return;
    event.currentTarget.setPointerCapture(event.pointerId);
    const bounds = event.currentTarget.getBoundingClientRect();
    scratch(event.clientX - bounds.left, event.clientY - bounds.top);
  };

  const handlePointerMove = (event: PointerEvent<HTMLCanvasElement>) => {
    if (!event.currentTarget.hasPointerCapture(event.pointerId) || revealed) return;

    const bounds = event.currentTarget.getBoundingClientRect();
    scratch(event.clientX - bounds.left, event.clientY - bounds.top);

    if (++moveCount.current % 8 === 0 && clearedFraction() >= threshold) {
      finish();
    }
  };

  const handlePointerUp = (event: PointerEvent<HTMLCanvasElement>) => {
    event.currentTarget.releasePointerCapture(event.pointerId);
    lastPoint.current = null;
    if (!revealed && clearedFraction() >= threshold) finish();
  };

  const handleKeyDown = (event: KeyboardEvent<HTMLCanvasElement>) => {
    if (event.key !== "Enter" && event.key !== " ") return;
    event.preventDefault();
    finish();
  };

  return (
    <div
      style={{ width, height }}
      className={cn(
        "relative isolate overflow-hidden rounded-xl border border-border shadow-sm",
        className,
      )}
    >
      <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
        {children}
      </div>

      <motion.canvas
        ref={canvasRef}
        role="button"
        tabIndex={revealed ? -1 : 0}
        aria-label={revealed ? "Revealed" : "Scratch to reveal"}
        aria-pressed={revealed}
        onPointerDown={handlePointerDown}
        onPointerMove={handlePointerMove}
        onPointerUp={handlePointerUp}
        onPointerCancel={handlePointerUp}
        onKeyDown={handleKeyDown}
        style={{ width, height, touchAction: "none" }}
        animate={{ opacity: revealed ? 0 : 1, scale: revealed ? 1.06 : 1 }}
        transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.5, ease: "easeOut" }}
        className={cn(
          "absolute inset-0 rounded-[inherit]",
          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
          revealed ? "pointer-events-none" : "cursor-crosshair",
        )}
      />
    </div>
  );
}
```

---

# Stack

> A 3D interactive stack of cards that can be dragged and rearranged.

Install: `npx @modus-ui/cli add stack`

An interactive deck of cards utilizing Framer Motion's `useTransform` and `drag`. Cards can be thrown to the back of the stack by dragging them off-center, or by clicking them (configurable).

## Installation

### CLI

```bash
npx @modus-ui/cli add stack
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/stack.tsx`.
3. Paste the code.

## Usage

```tsx
import { Stack } from "@/components/ui/stack";

export default function Example() {
  const cards = [
    <div key="1" className="h-full w-full rounded-2xl bg-blue-500">
      Card 1
    </div>,
    <div key="2" className="h-full w-full rounded-2xl bg-red-500">
      Card 2
    </div>,
  ];

  return (
    <div className="h-[400px] w-[300px]">
      <Stack cards={cards} randomRotation={true} sendToBackOnClick={true} />
    </div>
  );
}
```

## Props

| Prop                | Type                                     | Default                           | Description                                              |
| :------------------ | :--------------------------------------- | :-------------------------------- | :------------------------------------------------------- |
| `cards`             | `React.ReactNode[]`                      | -                                 | The cards in the stack.                                  |
| `randomRotation`    | `boolean`                                | `false`                           | Gives each card a slight random rotation.                |
| `sensitivity`       | `number`                                 | `200`                             | Drag distance in pixels that sends a card to the back.   |
| `animationConfig`   | `{ stiffness: number; damping: number }` | `{ stiffness: 260, damping: 20 }` | Spring settings for card movement.                       |
| `sendToBackOnClick` | `boolean`                                | `false`                           | Sends the top card to the back on click.                 |
| `autoplay`          | `boolean`                                | `false`                           | Cycles the cards automatically.                          |
| `autoplayDelay`     | `number`                                 | `3000`                            | Milliseconds between automatic cycles.                   |
| `pauseOnHover`      | `boolean`                                | `false`                           | Pauses autoplay while hovered.                           |
| `mobileClickOnly`   | `boolean`                                | `false`                           | Uses click instead of drag on mobile.                    |
| `mobileBreakpoint`  | `number`                                 | `768`                             | Width in pixels below which the device counts as mobile. |

## Source

`components/ui/stack.tsx`

```tsx
"use client";
// A fanned deck of cards; drag or tap the top card to send it to the back.

import * as React from "react";
import { motion, useReducedMotion, type PanInfo } from "framer-motion";
import { cn } from "@/lib/utils";

export interface StackProps extends React.HTMLAttributes<HTMLDivElement> {
  cards: React.ReactNode[];
  randomRotation?: boolean;
  sensitivity?: number;
  animationConfig?: { stiffness: number; damping: number };
  sendToBackOnClick?: boolean;
  autoplay?: boolean;
  autoplayDelay?: number;
  pauseOnHover?: boolean;
  mobileClickOnly?: boolean;
  mobileBreakpoint?: number;
}

export function Stack({
  cards,
  randomRotation = false,
  sensitivity = 200,
  animationConfig = { stiffness: 260, damping: 20 },
  sendToBackOnClick = false,
  autoplay = false,
  autoplayDelay = 3000,
  pauseOnHover = false,
  mobileClickOnly = false,
  mobileBreakpoint = 768,
  className,
  ...props
}: StackProps) {
  const reduceMotion = useReducedMotion();
  // order[0] is the top card (the last one passed); values are indices into `cards`.
  const [order, setOrder] = React.useState(() => cards.map((_, i) => cards.length - 1 - i));
  const [tilts, setTilts] = React.useState<number[]>([]);
  const [hovered, setHovered] = React.useState(false);
  const [mobile, setMobile] = React.useState(false);
  // A drag also ends in a tap; this keeps it from counting as a click.
  const dragged = React.useRef(false);

  React.useEffect(() => {
    setOrder(cards.map((_, i) => cards.length - 1 - i));
    // Random tilts are rolled after mount so server and client markup match.
    setTilts(cards.map(() => (randomRotation ? Math.random() * 10 - 5 : 0)));
  }, [cards.length, randomRotation]); // eslint-disable-line react-hooks/exhaustive-deps

  React.useEffect(() => {
    const query = window.matchMedia(`(max-width: ${mobileBreakpoint - 1}px)`);
    const update = () => setMobile(query.matches);
    update();
    query.addEventListener("change", update);
    return () => query.removeEventListener("change", update);
  }, [mobileBreakpoint]);

  const cycle = React.useCallback(() => setOrder(([top, ...rest]) => [...rest, top]), []);

  React.useEffect(() => {
    if (!autoplay || (pauseOnHover && hovered) || cards.length < 2) return;
    const id = window.setInterval(cycle, autoplayDelay);
    return () => window.clearInterval(id);
  }, [autoplay, autoplayDelay, pauseOnHover, hovered, cycle, cards.length]);

  const clickOnly = mobileClickOnly && mobile;
  const canClick = sendToBackOnClick || clickOnly;
  const transition = reduceMotion
    ? { duration: 0 }
    : { type: "spring" as const, ...animationConfig };

  const release = (_: unknown, info: PanInfo) => {
    if (Math.abs(info.offset.x) > sensitivity || Math.abs(info.offset.y) > sensitivity) cycle();
  };

  return (
    <div
      className={cn("relative h-full w-full", className)}
      style={{ perspective: 600 }}
      {...props}
      onPointerEnter={() => setHovered(true)}
      onPointerLeave={() => setHovered(false)}
    >
      {order.map((cardIndex, depth) => {
        const top = depth === 0;
        return (
          <motion.div
            key={cardIndex}
            className={cn(
              "absolute inset-0 select-none",
              top && "cursor-grab active:cursor-grabbing",
            )}
            style={{ zIndex: order.length - depth, transformOrigin: "50% 90%" }}
            initial={false}
            animate={{
              rotate: (tilts[cardIndex] ?? 0) + depth * 4,
              scale: 1 - depth * 0.05,
              x: 0,
              y: 0,
            }}
            transition={transition}
            drag={top && !clickOnly}
            dragSnapToOrigin
            dragElastic={0.6}
            onDragStart={() => (dragged.current = true)}
            onDragEnd={release}
            onTapStart={() => (dragged.current = false)}
            onTap={top && canClick ? () => !dragged.current && cycle() : undefined}
          >
            {cards[cardIndex]}
          </motion.div>
        );
      })}
    </div>
  );
}
```

---

# Star Border

> A glowing button border animation that circles the perimeter.

Install: `npx @modus-ui/cli add star-border`

A clean button with a dual-gradient beam that animates smoothly across the perimeter, utilizing Framer Motion instead of custom tailwind config.

## Installation

### CLI

```bash
npx @modus-ui/cli add star-border
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/star-border.tsx`.
3. Paste the code.

## Usage

```tsx
import { StarBorder } from "@/components/ui/star-border";

export default function Example() {
  return <StarBorder color="rgba(168, 85, 247, 0.8)">Premium Button</StarBorder>;
}
```

## Props

| Prop              | Type                | Default                      | Description                             |
| :---------------- | :------------------ | :--------------------------- | :-------------------------------------- |
| `as`              | `React.ElementType` | `"button"`                   | Element to render as.                   |
| `color`           | `string`            | `"rgba(255, 255, 255, 0.8)"` | Colour of the moving star.              |
| `speed`           | `number`            | `6`                          | Seconds for one trip around the border. |
| `thickness`       | `number`            | `1`                          | Border thickness in pixels.             |
| `backgroundColor` | `string`            | `"hsl(var(--background))"`   | Inner background colour.                |
| `textColor`       | `string`            | `"hsl(var(--foreground))"`   | Text colour.                            |
| `borderColor`     | `string`            | `"hsl(var(--border))"`       | Colour of the static border.            |

## Source

`components/ui/star-border.tsx`

```tsx
"use client";
// A pill whose border carries two light beams that circle the perimeter.

import type React from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export type StarBorderProps = React.HTMLAttributes<HTMLElement> & {
  as?: React.ElementType;
  color?: string;
  speed?: number;
  thickness?: number;
  backgroundColor?: string;
  textColor?: string;
  borderColor?: string;
};

export function StarBorder({
  as: Tag = "button",
  color = "rgba(255, 255, 255, 0.8)",
  speed = 6,
  thickness = 1,
  backgroundColor = "hsl(var(--background))",
  textColor = "hsl(var(--foreground))",
  borderColor = "hsl(var(--border))",
  className,
  children,
  ...props
}: StarBorderProps) {
  const reduceMotion = useReducedMotion();

  return (
    <Tag
      className={cn(
        "relative isolate inline-flex overflow-hidden rounded-full font-sans text-sm font-medium",
        className,
      )}
      style={{ padding: thickness, background: borderColor }}
      {...props}
    >
      <motion.span
        aria-hidden
        className="pointer-events-none absolute left-1/2 top-1/2 -z-10 aspect-square w-[max(300%,300px)]"
        style={{
          x: "-50%",
          y: "-50%",
          background: `conic-gradient(from 0deg, transparent 0deg, ${color} 30deg, transparent 60deg, transparent 180deg, ${color} 210deg, transparent 240deg)`,
        }}
        animate={reduceMotion ? undefined : { rotate: 360 }}
        transition={{ duration: speed, ease: "linear", repeat: Infinity }}
      />
      <span
        className="relative rounded-full px-6 py-3"
        style={{ background: backgroundColor, color: textColor }}
      >
        {children}
      </span>
    </Tag>
  );
}
```

---

# Tilted Card

> A 3D interactive card that physically tilts and pans relative to the cursor position.

Install: `npx @modus-ui/cli add tilted-card`

A highly responsive 3D card utilizing Framer Motion spring physics. It dynamically calculates cursor offsets to apply localized 3D rotations, complete with an attached tooltip that flows with cursor velocity.

## Installation

### CLI

```bash
npx @modus-ui/cli add tilted-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tilted-card.tsx`.
3. Paste the code.

## Usage

```tsx
import { TiltedCard } from "@/components/ui/tilted-card";

export default function Example() {
  return (
    <TiltedCard
      imageSrc="/path/to/image.jpg"
      altText="Description"
      captionText="Tooltip Content"
      containerHeight={400}
      containerWidth={300}
      imageHeight={400}
      imageWidth={300}
      rotateAmplitude={12}
      scaleOnHover={1.1}
      showTooltip={true}
      displayOverlayContent={true}
      overlayContent={
        <div className="flex h-[400px] w-[300px] flex-col justify-end rounded-xl p-6">
          <p className="text-2xl font-bold text-white">Overlay Text</p>
        </div>
      }
    />
  );
}
```

## Props

| Prop                    | Type               | Default               | Description                                   |
| :---------------------- | :----------------- | :-------------------- | :-------------------------------------------- |
| `imageSrc`              | `string`           | -                     | Image URL.                                    |
| `altText`               | `string`           | `"Tilted card image"` | Alt text for the image.                       |
| `captionText`           | `string`           | `""`                  | Tooltip text that follows the cursor.         |
| `containerHeight`       | `string \| number` | `"300px"`             | Height of the container.                      |
| `containerWidth`        | `string \| number` | `"100%"`              | Width of the container.                       |
| `imageHeight`           | `string \| number` | `"300px"`             | Height of the image.                          |
| `imageWidth`            | `string \| number` | `"300px"`             | Width of the image.                           |
| `scaleOnHover`          | `number`           | `1.1`                 | Scale applied while hovered.                  |
| `rotateAmplitude`       | `number`           | `14`                  | Maximum tilt in degrees.                      |
| `showMobileWarning`     | `boolean`          | `false`               | Shows a note that the effect needs a pointer. |
| `showTooltip`           | `boolean`          | `true`                | Shows the caption tooltip.                    |
| `overlayContent`        | `React.ReactNode`  | `null`                | Content layered over the image.               |
| `displayOverlayContent` | `boolean`          | `false`               | Shows `overlayContent`.                       |

## Source

`components/ui/tilted-card.tsx`

```tsx
"use client";
// Image card that tilts toward the pointer, with a caption that trails the cursor.

import * as React from "react";
import { motion, useMotionValue, useReducedMotion, useSpring } from "framer-motion";
import { cn } from "@/lib/utils";

export interface TiltedCardProps {
  imageSrc: string;
  altText?: string;
  captionText?: string;
  containerHeight?: string | number;
  containerWidth?: string | number;
  imageHeight?: string | number;
  imageWidth?: string | number;
  scaleOnHover?: number;
  rotateAmplitude?: number;
  showMobileWarning?: boolean;
  showTooltip?: boolean;
  overlayContent?: React.ReactNode;
  displayOverlayContent?: boolean;
  className?: string;
}

const spring = { stiffness: 120, damping: 18, mass: 1 };

export function TiltedCard({
  imageSrc,
  altText = "Tilted card image",
  captionText = "",
  containerHeight = "300px",
  containerWidth = "100%",
  imageHeight = "300px",
  imageWidth = "300px",
  scaleOnHover = 1.1,
  rotateAmplitude = 14,
  showMobileWarning = false,
  showTooltip = true,
  overlayContent = null,
  displayOverlayContent = false,
  className,
}: TiltedCardProps) {
  const reduceMotion = useReducedMotion();
  const tiltX = useSpring(0, spring);
  const tiltY = useSpring(0, spring);
  const scale = useSpring(1, spring);
  const captionX = useMotionValue(0);
  const captionY = useMotionValue(0);
  const captionOpacity = useSpring(0, spring);
  const captionTurn = useSpring(0, { stiffness: 300, damping: 30 });
  const lastY = React.useRef(0);

  const onPointerMove = (event: React.PointerEvent<HTMLElement>) => {
    const rect = event.currentTarget.getBoundingClientRect();
    const px = event.clientX - rect.left;
    const py = event.clientY - rect.top;
    if (!reduceMotion) {
      tiltX.set((0.5 - py / rect.height) * 2 * rotateAmplitude);
      tiltY.set((px / rect.width - 0.5) * 2 * rotateAmplitude);
      captionTurn.set(-(py - lastY.current) * 0.6);
    }
    captionX.set(px);
    captionY.set(py);
    lastY.current = py;
  };

  const onPointerEnter = () => {
    if (!reduceMotion) scale.set(scaleOnHover);
    captionOpacity.set(1);
  };

  const onPointerLeave = () => {
    tiltX.set(0);
    tiltY.set(0);
    scale.set(1);
    captionOpacity.set(0);
    captionTurn.set(0);
  };

  return (
    <figure
      className={cn("relative m-0 flex items-center justify-center [perspective:800px]", className)}
      style={{ width: containerWidth, height: containerHeight }}
      onPointerMove={onPointerMove}
      onPointerEnter={onPointerEnter}
      onPointerLeave={onPointerLeave}
    >
      {showMobileWarning && (
        <p className="absolute top-4 text-center text-sm text-muted-foreground sm:hidden">
          This effect works best with a mouse or trackpad.
        </p>
      )}
      <motion.div
        className="relative [transform-style:preserve-3d]"
        style={{ width: imageWidth, height: imageHeight, rotateX: tiltX, rotateY: tiltY, scale }}
      >
        <img
          src={imageSrc}
          alt={altText}
          draggable={false}
          className="absolute inset-0 h-full w-full rounded-xl object-cover shadow-lg"
        />
        {displayOverlayContent && overlayContent && (
          <div className="absolute inset-0 z-10">{overlayContent}</div>
        )}
      </motion.div>
      {showTooltip && captionText && (
        <motion.figcaption
          aria-hidden
          className="pointer-events-none absolute left-0 top-0 z-20 hidden whitespace-nowrap rounded-md bg-popover px-2.5 py-1 text-xs text-popover-foreground shadow-md sm:block"
          style={{
            x: captionX,
            y: captionY,
            opacity: captionOpacity,
            rotate: captionTurn,
            translateX: 12,
            translateY: 12,
          }}
        >
          {captionText}
        </motion.figcaption>
      )}
    </figure>
  );
}
```

---

# Pixel Card

> A card that reveals a pixelated, shimmering canvas pattern on hover.

Install: `npx @modus-ui/cli add pixel-card`

A stunning interaction component that draws a grid of shrinking and growing canvas pixels following your cursor focus.

## Installation

### CLI

```bash
npx @modus-ui/cli add pixel-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pixel-card.tsx`.
3. Paste the code.

## Usage

```tsx
import { PixelCard } from "@/components/ui/pixel-card";

export default function Example() {
  return (
    <PixelCard variant="blue">
      <div className="pointer-events-none absolute inset-0 flex items-center justify-center">
        <span className="text-xl font-bold text-blue-500">Hover Me</span>
      </div>
    </PixelCard>
  );
}
```

## Props

| Prop      | Type                                        | Default     | Description                                                   |
| :-------- | :------------------------------------------ | :---------- | :------------------------------------------------------------ |
| `variant` | `"default" \| "blue" \| "yellow" \| "pink"` | `"default"` | Preset for gap, speed, colours and focus behaviour.           |
| `gap`     | `number`                                    | -           | Gap between pixels; overrides the variant.                    |
| `speed`   | `number`                                    | -           | Shimmer speed; overrides the variant.                         |
| `colors`  | `string`                                    | -           | Comma-separated pixel colours; overrides the variant.         |
| `noFocus` | `boolean`                                   | -           | Skips the animation on keyboard focus; overrides the variant. |

## Source

`components/ui/pixel-card.tsx`

```tsx
"use client";
// Card whose canvas pixels bloom outward from the centre and shimmer while hovered or focused.

import * as React from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Variant = "default" | "blue" | "yellow" | "pink";

export interface PixelCardProps {
  variant?: Variant;
  gap?: number;
  speed?: number;
  colors?: string;
  noFocus?: boolean;
  className?: string;
  children?: React.ReactNode;
}

const PRESETS: Record<Variant, { gap: number; speed: number; colors: string; noFocus: boolean }> = {
  default: { gap: 5, speed: 35, colors: "#e2e8f0,#94a3b8,#64748b", noFocus: false },
  blue: { gap: 10, speed: 25, colors: "#e0f2fe,#7dd3fc,#0ea5e9", noFocus: false },
  yellow: { gap: 3, speed: 20, colors: "#fef08a,#fde047,#eab308", noFocus: false },
  pink: { gap: 6, speed: 80, colors: "#fecdd3,#fda4af,#e11d48", noFocus: true },
};

interface Pixel {
  x: number;
  y: number;
  color: string;
  delay: number;
  size: number;
  phase: number;
}

export function PixelCard({
  variant = "default",
  gap,
  speed,
  colors,
  noFocus,
  className,
  children,
}: PixelCardProps) {
  const preset = PRESETS[variant];
  const cellGap = Math.max(gap ?? preset.gap, 2);
  const shimmer = (speed ?? preset.speed) / 1000;
  const palette = colors ?? preset.colors;
  const skipFocus = noFocus ?? preset.noFocus;
  const reduceMotion = useReducedMotion();

  const canvasRef = React.useRef<HTMLCanvasElement>(null);
  const setActive = React.useRef<(on: boolean) => void>(() => {});

  React.useEffect(() => {
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return;
    const list = palette.split(",").map((c) => c.trim());
    const maxSize = 2;
    let pixels: Pixel[] = [];
    let width = 0;
    let height = 0;
    let active = false;
    let activeSince = 0;
    let frame = 0;

    const build = () => {
      const rect = canvas.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = window.devicePixelRatio || 1;
      canvas.width = width * dpr;
      canvas.height = height * dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      pixels = [];
      for (let x = 0; x < width; x += cellGap) {
        for (let y = 0; y < height; y += cellGap) {
          pixels.push({
            x,
            y,
            color: list[Math.floor(Math.random() * list.length)],
            delay: reduceMotion ? 0 : Math.hypot(x - width / 2, y - height / 2) * 2,
            size: 0,
            phase: Math.random() * Math.PI * 2,
          });
        }
      }
    };

    const tick = (now: number) => {
      ctx.clearRect(0, 0, width, height);
      const elapsed = now - activeSince;
      let visible = false;
      for (const p of pixels) {
        const target =
          active && elapsed > p.delay
            ? reduceMotion
              ? maxSize * 0.75
              : maxSize * (0.6 + 0.4 * Math.sin(now * shimmer * 0.1 + p.phase))
            : 0;
        p.size += reduceMotion ? target - p.size : (target - p.size) * 0.12;
        if (p.size < 0.05) continue;
        visible = true;
        const offset = (maxSize - p.size) / 2;
        ctx.fillStyle = p.color;
        ctx.fillRect(p.x + offset, p.y + offset, p.size, p.size);
      }
      frame = active || visible ? requestAnimationFrame(tick) : 0;
    };

    setActive.current = (on) => {
      active = on;
      activeSince = performance.now();
      if (!frame) frame = requestAnimationFrame(tick);
    };

    const observer = new ResizeObserver(build);
    observer.observe(canvas);
    build();
    return () => {
      cancelAnimationFrame(frame);
      observer.disconnect();
    };
  }, [cellGap, shimmer, palette, reduceMotion]);

  return (
    <div
      tabIndex={skipFocus ? -1 : 0}
      className={cn(
        "relative isolate aspect-[4/5] w-[300px] overflow-hidden rounded-[25px] border border-border bg-card outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
        className,
      )}
      onPointerEnter={() => setActive.current(true)}
      onPointerLeave={() => setActive.current(false)}
      onFocus={(event) => {
        if (!skipFocus && event.target === event.currentTarget) setActive.current(true);
      }}
      onBlur={() => !skipFocus && setActive.current(false)}
    >
      <canvas ref={canvasRef} aria-hidden className="absolute inset-0 h-full w-full" />
      {children}
    </div>
  );
}
```

---

# Click Spark

> A physics-based canvas effect that bursts colorful sparks wherever the user clicks.

Install: `npx @modus-ui/cli add click-spark`

A physics-based canvas effect that creates a burst of colorful sparks originating from the exact coordinates of a user's click.

## Installation

### CLI

```bash
npx @modus-ui/cli add click-spark
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/click-spark.tsx`.
3. Paste the code.

## Usage

Wrap any container with `ClickSpark`.

```tsx
import { ClickSpark } from "@/components/ui/click-spark";

export default function Example() {
  return (
    <ClickSpark sparkColor="hsl(var(--primary))" sparkCount={8}>
      <button>Click me for sparks</button>
    </ClickSpark>
  );
}
```

## Props

| Prop          | Type                                                   | Default                 | Description                             |
| :------------ | :----------------------------------------------------- | :---------------------- | :-------------------------------------- |
| `sparkColor`  | `string`                                               | `"hsl(var(--primary))"` | Colour of the sparks.                   |
| `sparkSize`   | `number`                                               | `10`                    | Length of each spark in pixels.         |
| `sparkRadius` | `number`                                               | `25`                    | Distance the sparks travel in pixels.   |
| `sparkCount`  | `number`                                               | `8`                     | Number of sparks per click.             |
| `duration`    | `number`                                               | `500`                   | Milliseconds the sparks last.           |
| `easing`      | `"linear" \| "ease-in" \| "ease-out" \| "ease-in-out"` | `"ease-out"`            | Easing of the spark motion.             |
| `extraScale`  | `number`                                               | `1`                     | Multiplier for spark distance and size. |

## Source

`components/ui/click-spark.tsx`

```tsx
"use client";
// Wrapper that bursts radiating spark lines from every click.

import * as React from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Easing = "linear" | "ease-in" | "ease-out" | "ease-in-out";

export interface ClickSparkProps extends React.HTMLAttributes<HTMLDivElement> {
  sparkColor?: string;
  sparkSize?: number;
  sparkRadius?: number;
  sparkCount?: number;
  duration?: number;
  easing?: Easing;
  extraScale?: number;
}

const EASE: Record<Easing, (t: number) => number> = {
  linear: (t) => t,
  "ease-in": (t) => t * t,
  "ease-out": (t) => 1 - (1 - t) * (1 - t),
  "ease-in-out": (t) => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2),
};

interface Burst {
  x: number;
  y: number;
  born: number;
}

export function ClickSpark({
  sparkColor = "hsl(var(--primary))",
  sparkSize = 10,
  sparkRadius = 25,
  sparkCount = 8,
  duration = 500,
  easing = "ease-out",
  extraScale = 1,
  className,
  children,
  ...props
}: ClickSparkProps) {
  const reduceMotion = useReducedMotion();
  const canvasRef = React.useRef<HTMLCanvasElement>(null);
  const bursts = React.useRef<Burst[]>([]);
  const frame = React.useRef(0);

  React.useEffect(() => () => cancelAnimationFrame(frame.current), []);

  const render = () => {
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!canvas || !ctx) return;
    const dpr = window.devicePixelRatio || 1;
    const { width, height } = canvas.getBoundingClientRect();
    if (canvas.width !== Math.round(width * dpr)) canvas.width = Math.round(width * dpr);
    if (canvas.height !== Math.round(height * dpr)) canvas.height = Math.round(height * dpr);
    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
    ctx.clearRect(0, 0, width, height);
    // The canvas cannot read CSS variables, so let the browser resolve the colour.
    canvas.style.color = sparkColor;
    ctx.strokeStyle = getComputedStyle(canvas).color;
    ctx.lineWidth = 2;
    ctx.lineCap = "round";

    const now = performance.now();
    bursts.current = bursts.current.filter((b) => now - b.born < duration);
    for (const burst of bursts.current) {
      const t = EASE[easing]((now - burst.born) / duration);
      const reach = t * sparkRadius * extraScale;
      const length = (1 - t) * sparkSize * extraScale;
      for (let i = 0; i < sparkCount; i++) {
        const angle = (i / sparkCount) * Math.PI * 2;
        const cos = Math.cos(angle);
        const sin = Math.sin(angle);
        ctx.beginPath();
        ctx.moveTo(burst.x + cos * reach, burst.y + sin * reach);
        ctx.lineTo(burst.x + cos * (reach + length), burst.y + sin * (reach + length));
        ctx.stroke();
      }
    }
    frame.current = bursts.current.length ? requestAnimationFrame(render) : 0;
  };

  return (
    <div
      {...props}
      className={cn("relative", className)}
      onClick={(event) => {
        props.onClick?.(event);
        if (reduceMotion) return;
        const rect = event.currentTarget.getBoundingClientRect();
        bursts.current.push({
          x: event.clientX - rect.left,
          y: event.clientY - rect.top,
          born: performance.now(),
        });
        if (!frame.current) frame.current = requestAnimationFrame(render);
      }}
    >
      {children}
      <canvas
        ref={canvasRef}
        aria-hidden
        className="pointer-events-none absolute inset-0 h-full w-full"
      />
    </div>
  );
}
```

---

# Spotlight Card

> A card with a subtle spotlight gradient that follows the user's mouse cursor on hover.

Install: `npx @modus-ui/cli add spotlight-card`

A card component that creates an ambient spotlight effect tracking the user's mouse cursor across its surface. Perfect for subtle emphasis and giving depth to interfaces.

## Installation

### CLI

```bash
npx @modus-ui/cli add spotlight-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/spotlight-card.tsx`.
3. Paste the code.

## Usage

```tsx
import { SpotlightCard } from "@/components/ui/spotlight-card";

export default function Example() {
  return (
    <SpotlightCard className="max-w-sm">
      <h3 className="text-xl font-semibold">Hover me</h3>
    </SpotlightCard>
  );
}
```

## Props

| Prop             | Type     | Default                        | Description                                                                                                                         |
| :--------------- | :------- | :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `spotlightColor` | `string` | `"hsl(var(--primary) / 0.14)"` | Colour of the spotlight that follows the cursor. Defaults to a soft tint of the theme primary, so it shows on light and dark cards. |

## Source

`components/ui/spotlight-card.tsx`

```tsx
"use client";
// Card with a soft radial light that tracks the pointer.

import * as React from "react";
import { motion, useMotionTemplate, useMotionValue, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface SpotlightCardProps extends React.HTMLAttributes<HTMLDivElement> {
  spotlightColor?: string;
}

export function SpotlightCard({
  spotlightColor = "hsl(var(--primary) / 0.14)",
  className,
  children,
  ...props
}: SpotlightCardProps) {
  const reduceMotion = useReducedMotion();
  const x = useMotionValue(-1000);
  const y = useMotionValue(-1000);
  const [lit, setLit] = React.useState(false);
  const background = useMotionTemplate`radial-gradient(circle at ${x}px ${y}px, ${spotlightColor}, transparent 70%)`;

  return (
    <div
      {...props}
      className={cn(
        "relative overflow-hidden rounded-2xl border border-border bg-card p-8 text-card-foreground",
        className,
      )}
      onPointerMove={(event) => {
        const rect = event.currentTarget.getBoundingClientRect();
        x.set(event.clientX - rect.left);
        y.set(event.clientY - rect.top);
      }}
      onPointerEnter={() => setLit(true)}
      onPointerLeave={() => setLit(false)}
      onFocus={() => setLit(true)}
      onBlur={() => setLit(false)}
    >
      <motion.div
        aria-hidden
        className="pointer-events-none absolute inset-0"
        style={{ background }}
        initial={false}
        animate={{ opacity: lit ? 1 : 0 }}
        transition={{ duration: reduceMotion ? 0 : 0.4, ease: "easeOut" }}
      />
      {children}
    </div>
  );
}
```

---

# Border Glow

> An interactive card wrapper with an ambient glowing mesh gradient that mathematically tracks the mouse.

Install: `npx @modus-ui/cli add border-glow`

An interactive card wrapper with an ambient glowing mesh gradient that mathematically tracks the mouse. The glow traces the borders exactly and cascades over the inner padding realistically.

## Installation

### CLI

```bash
npx @modus-ui/cli add border-glow
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/border-glow.tsx`.
3. Paste the code.

## Usage

```tsx
import { BorderGlow } from "@/components/ui/border-glow";

export default function Example() {
  return (
    <BorderGlow
      className="h-[350px] w-[300px] p-8"
      glowColor="200 100 65"
      colors={["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"]}
      animated={true}
      backgroundColor="hsl(var(--primary))"
    >
      <h3 className="text-xl font-medium text-white">Interactive Glow</h3>
      <p className="text-zinc-400">Content goes here.</p>
    </BorderGlow>
  );
}
```

## Props

| Prop              | Type       | Default                                                                 | Description                                       |
| :---------------- | :--------- | :---------------------------------------------------------------------- | :------------------------------------------------ |
| `edgeSensitivity` | `number`   | `30`                                                                    | How close in pixels to the edge the glow appears. |
| `glowColor`       | `string`   | `"266 100 65"`                                                          | Glow colour as space-separated HSL values.        |
| `backgroundColor` | `string`   | `"hsl(var(--card))"`                                                    | Card background colour.                           |
| `borderRadius`    | `number`   | `28`                                                                    | Corner radius in pixels.                          |
| `glowRadius`      | `number`   | `40`                                                                    | Size of the glow in pixels.                       |
| `glowIntensity`   | `number`   | `1`                                                                     | Strength of the glow.                             |
| `coneSpread`      | `number`   | `25`                                                                    | Angular spread of the glow in degrees.            |
| `animated`        | `boolean`  | `false`                                                                 | Runs an intro sweep of the glow.                  |
| `colors`          | `string[]` | `["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"]` | Colours of the border gradient.                   |
| `fillOpacity`     | `number`   | `0.5`                                                                   | Opacity of the inner glow fill.                   |

## Source

`components/ui/border-glow.tsx`

```tsx
"use client";
// Card whose border lights up in a cone aimed at the cursor as it nears an edge.
import { useEffect, useRef, type PointerEvent, type ReactNode } from "react";
import {
  animate,
  motion,
  useMotionTemplate,
  useMotionValue,
  useReducedMotion,
  useTransform,
} from "framer-motion";
import { cn } from "@/lib/utils";

interface BorderGlowProps {
  children?: ReactNode;
  className?: string;
  edgeSensitivity?: number;
  glowColor?: string;
  backgroundColor?: string;
  borderRadius?: number;
  glowRadius?: number;
  glowIntensity?: number;
  coneSpread?: number;
  animated?: boolean;
  colors?: string[];
  fillOpacity?: number;
}

const RING_MASK = {
  WebkitMask: "linear-gradient(black 0 0) content-box, linear-gradient(black 0 0)",
  WebkitMaskComposite: "xor",
  maskComposite: "exclude",
} as const;

export function BorderGlow({
  children,
  className,
  edgeSensitivity = 30,
  glowColor = "266 100 65",
  backgroundColor = "hsl(var(--card))",
  borderRadius = 28,
  glowRadius = 40,
  glowIntensity = 1,
  coneSpread = 25,
  animated = false,
  colors = ["hsl(var(--primary))", "hsl(var(--primary))", "hsl(var(--primary))"],
  fillOpacity = 0.5,
}: BorderGlowProps) {
  const reduce = useReducedMotion();
  const card = useRef<HTMLDivElement>(null);
  const angle = useMotionValue(0);
  const strength = useMotionValue(0);
  const x = useMotionValue(50);
  const y = useMotionValue(50);

  const [h, s, l] = glowColor.split(/\s+/);
  const glow = `hsl(${h} ${s}% ${l}%`;
  const ringColors = [...colors, colors[0]].join(", ");

  const cone = useMotionTemplate`conic-gradient(from ${useTransform(angle, (a) => a - coneSpread)}deg, transparent 0deg, black ${coneSpread}deg, transparent ${coneSpread * 2}deg)`;
  const fill = useMotionTemplate`radial-gradient(${glowRadius * 4}px circle at ${x}% ${y}%, ${glow} / ${fillOpacity * 0.25}), transparent 70%)`;
  const ringOpacity = useTransform(strength, (v) => v * glowIntensity);

  useEffect(() => {
    if (!animated || reduce) return;
    strength.set(1);
    const sweep = animate(angle, [0, 360], { duration: 1.6, ease: "easeInOut" });
    const fade = animate(strength, 0, { delay: 1.2, duration: 0.6 });
    return () => {
      sweep.stop();
      fade.stop();
    };
  }, [animated, reduce, angle, strength]);

  const onPointerMove = (e: PointerEvent) => {
    const r = card.current!.getBoundingClientRect();
    const px = e.clientX - r.left;
    const py = e.clientY - r.top;
    const edge = Math.min(px, py, r.width - px, r.height - py);
    angle.set((Math.atan2(px - r.width / 2, r.height / 2 - py) * 180) / Math.PI);
    x.set((px / r.width) * 100);
    y.set((py / r.height) * 100);
    strength.set(Math.max(0, Math.min(1, 1 - edge / edgeSensitivity)));
  };

  const layer = { borderRadius, maskImage: cone, WebkitMaskImage: cone } as const;

  return (
    <div
      ref={card}
      onPointerMove={onPointerMove}
      onPointerLeave={() => animate(strength, 0, { duration: reduce ? 0 : 0.4 })}
      className={cn("relative isolate border border-[hsl(var(--border))]", className)}
      style={{ borderRadius, background: backgroundColor }}
    >
      {/* Soft halo outside the border, padded so the shadow is not clipped by the mask. */}
      <motion.div
        aria-hidden
        className="pointer-events-none absolute -z-10"
        style={{ inset: -glowRadius, maskImage: cone, WebkitMaskImage: cone, opacity: ringOpacity }}
      >
        <div
          className="absolute"
          style={{
            inset: glowRadius,
            borderRadius,
            boxShadow: `0 0 ${glowRadius}px ${glowRadius / 4}px ${glow} / 0.7)`,
          }}
        />
      </motion.div>
      {/* Gradient ring on the border itself. */}
      <motion.div
        aria-hidden
        className="pointer-events-none absolute -inset-px"
        style={{ ...layer, opacity: ringOpacity }}
      >
        <div
          className="absolute inset-0 p-[1.5px]"
          style={{ borderRadius, ...RING_MASK, background: `conic-gradient(${ringColors})` }}
        />
      </motion.div>
      {/* Inner wash following the cursor. */}
      <motion.div
        aria-hidden
        className="pointer-events-none absolute inset-0"
        style={{ borderRadius, background: fill, opacity: strength }}
      />
      <div className="relative">{children}</div>
    </div>
  );
}
```

---

# Comparison Slider

> Two layers stacked, with a divider the user drags to compare them.

Install: `npx @modus-ui/cli add comparison-slider`

A buttery smooth, accessible image/layer comparison slider. It supports both horizontal and vertical orientations and is fully keyboard navigable.

## Installation

### CLI

```bash
npx @modus-ui/cli add comparison-slider
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/comparison-slider.tsx`.
3. Paste the code.

## Usage

```tsx
import { ComparisonSlider } from "@/components/ui/comparison-slider";

export default function Example() {
  return (
    <div className="h-[300px] w-[500px]">
      <ComparisonSlider
        before={<img src="/before.jpg" alt="Before" className="h-full w-full object-cover" />}
        after={<img src="/after.jpg" alt="After" className="h-full w-full object-cover" />}
      />
    </div>
  );
}
```

## Props

| Prop            | Type                       | Default                    | Description                                                    |
| :-------------- | :------------------------- | :------------------------- | :------------------------------------------------------------- |
| before          | ReactNode                  | -                          | The layer revealed on the leading side of the divider.         |
| after           | ReactNode                  | -                          | The layer underneath, revealed as the divider moves across it. |
| defaultPosition | number                     | 50                         | Where the divider starts, 0 to 100.                            |
| orientation     | "horizontal" \| "vertical" | "horizontal"               | The orientation of the slider.                                 |
| label           | string                     | "Compare before and after" | Accessible name for the divider.                               |
| className       | string                     | ""                         | -                                                              |

## Source

`components/ui/comparison-slider.tsx`

```tsx
"use client";

import { ChevronsLeftRight, ChevronsUpDown } from "lucide-react";
import {
  useCallback,
  useRef,
  useState,
  type KeyboardEvent,
  type PointerEvent,
  type ReactNode,
} from "react";
import { cn } from "@/lib/utils";

interface ComparisonSliderProps {
  /** The layer revealed on the leading side of the divider. */
  before: ReactNode;
  /** The layer underneath, revealed as the divider moves across it. */
  after: ReactNode;
  /** Where the divider starts, 0 to 100. */
  defaultPosition?: number;
  orientation?: "horizontal" | "vertical";
  /** Accessible name for the divider. */
  label?: string;
  className?: string;
}

const clamp = (value: number) => Math.min(100, Math.max(0, value));

/**
 * Two layers stacked, with a divider the reader drags to compare them.
 *
 * The top layer is revealed with `clip-path` rather than a width. A clipped
 * layer is laid out at full size and only painted in part, so both sides stay
 * pinned to the same geometry. Resize a width instead and the top copy
 * reflows as it narrows, which turns a comparison of two designs into a
 * comparison of one design against itself at a different width.
 *
 * It is a real slider to anything that is not a mouse: `role="slider"` with a
 * live value, arrow keys for fine steps, Home and End for the extremes. A
 * comparison that can only be operated by dragging is one a keyboard user
 * cannot see the other half of.
 *
 * No Motion here. The divider tracks the pointer exactly, because anything
 * easing toward the cursor would feel broken, so the only animated case is a
 * keyboard step, which is a CSS transition that `motion-reduce` turns off.
 */
export function ComparisonSlider({
  before,
  after,
  defaultPosition = 50,
  orientation = "horizontal",
  label = "Compare before and after",
  className = "",
}: ComparisonSliderProps) {
  const [position, setPosition] = useState(clamp(defaultPosition));
  const [dragging, setDragging] = useState(false);
  const frameRef = useRef<HTMLDivElement>(null);

  const isHorizontal = orientation === "horizontal";

  const positionFromPointer = useCallback(
    (event: PointerEvent<HTMLDivElement>) => {
      const frame = frameRef.current;
      if (!frame) return;

      const bounds = frame.getBoundingClientRect();
      const next = isHorizontal
        ? ((event.clientX - bounds.left) / bounds.width) * 100
        : ((event.clientY - bounds.top) / bounds.height) * 100;

      setPosition(clamp(next));
    },
    [isHorizontal],
  );

  const handlePointerDown = (event: PointerEvent<HTMLDivElement>) => {
    // Capture on the frame, so a drag that leaves the component still tracks
    // until the button is released.
    event.currentTarget.setPointerCapture(event.pointerId);
    setDragging(true);
    positionFromPointer(event);
  };

  const handlePointerMove = (event: PointerEvent<HTMLDivElement>) => {
    if (!dragging) return;
    positionFromPointer(event);
  };

  const stopDragging = (event: PointerEvent<HTMLDivElement>) => {
    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
      event.currentTarget.releasePointerCapture(event.pointerId);
    }
    setDragging(false);
  };

  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    const steps: Record<string, number> = {
      ArrowLeft: -2,
      ArrowRight: 2,
      ArrowUp: -2,
      ArrowDown: 2,
      PageDown: -10,
      PageUp: 10,
    };

    if (event.key === "Home" || event.key === "End") {
      event.preventDefault();
      setPosition(event.key === "Home" ? 0 : 100);
      return;
    }

    const step = steps[event.key];
    if (step === undefined) return;

    event.preventDefault();
    setPosition((current) => clamp(current + step));
  };

  // `inset()` trims from each edge, so the value is how much to hide.
  const clipPath = isHorizontal
    ? `inset(0 ${100 - position}% 0 0)`
    : `inset(0 0 ${100 - position}% 0)`;

  const Grip = isHorizontal ? ChevronsLeftRight : ChevronsUpDown;

  return (
    <div
      ref={frameRef}
      onPointerDown={handlePointerDown}
      onPointerMove={handlePointerMove}
      onPointerUp={stopDragging}
      onPointerCancel={stopDragging}
      className={cn(
        "relative touch-none select-none overflow-hidden",
        isHorizontal ? "cursor-ew-resize" : "cursor-ns-resize",
        className,
      )}
    >
      <div className="size-full">{after}</div>

      <div
        className={cn(
          "absolute inset-0",
          dragging
            ? ""
            : "transition-[clip-path] duration-150 ease-out motion-reduce:transition-none",
        )}
        style={{ clipPath }}
      >
        {before}
      </div>

      <div
        role="slider"
        tabIndex={0}
        aria-label={label}
        aria-orientation={isHorizontal ? "horizontal" : "vertical"}
        aria-valuemin={0}
        aria-valuemax={100}
        aria-valuenow={Math.round(position)}
        onKeyDown={handleKeyDown}
        className={cn(
          "absolute flex items-center justify-center focus-visible:outline-none",
          isHorizontal
            ? "bottom-0 top-0 w-8 -translate-x-1/2"
            : "left-0 right-0 h-8 -translate-y-1/2",
          dragging
            ? ""
            : "transition-[left,top] duration-150 ease-out motion-reduce:transition-none",
        )}
        style={isHorizontal ? { left: `${position}%` } : { top: `${position}%` }}
      >
        <span
          aria-hidden="true"
          className={cn(
            "absolute bg-background/90",
            isHorizontal ? "inset-y-0 w-0.5" : "inset-x-0 h-0.5",
          )}
        />
        <span className="relative flex size-8 items-center justify-center rounded-full border bg-background text-foreground shadow-md">
          <Grip className="size-4" aria-hidden="true" />
        </span>
      </div>
    </div>
  );
}

export default ComparisonSlider;
```

---

# Dock

> A highly interactive macOS-style dock that magnifies items on hover.

Install: `npx @modus-ui/cli add dock`

A beautiful icon dock. Built with Framer Motion, it applies complex physics interpolation to surrounding icons, smoothly magnifying them as the cursor approaches to create a realistic macOS dock effect.

## Installation

### CLI

```bash
npx @modus-ui/cli add dock
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/dock.tsx`.
3. Paste the code.

## Usage

```tsx
import { Dock, DockItem } from "@/components/ui/dock";
import { Home, Settings } from "lucide-react";

export default function Example() {
  return (
    <Dock>
      <DockItem label="Home" href="/">
        <Home />
      </DockItem>
      <DockItem label="Settings" href="/settings">
        <Settings />
      </DockItem>
    </Dock>
  );
}
```

## Props

| Prop          | Type      | Default | Description                                      |
| :------------ | :-------- | :------ | :----------------------------------------------- |
| children      | ReactNode | -       | The DockItem components.                         |
| size          | number    | 44      | Resting size of each item, in pixels.            |
| magnification | number    | 76      | Size an item reaches directly under the pointer. |
| reach         | number    | 130     | How far, in pixels, the magnification reaches.   |
| className     | string    | ""      | -                                                |

## Source

`components/ui/dock.tsx`

```tsx
"use client";

import { cn } from "@/lib/utils";

import {
  AnimatePresence,
  motion,
  useMotionValue,
  useReducedMotion,
  useSpring,
  useTransform,
  type MotionValue,
} from "framer-motion";
import { createContext, useContext, useRef, useState, type ReactNode } from "react";

interface DockContextValue {
  mouseX: MotionValue<number>;
  size: number;
  magnification: number;
  reach: number;
}

const DockContext = createContext<DockContextValue | null>(null);

function useDock(component: string) {
  const context = useContext(DockContext);
  if (!context) {
    throw new Error(`<${component}> must be rendered inside a <Dock>.`);
  }
  return context;
}

interface DockProps {
  children: ReactNode;
  /** Resting size of each item, in pixels. */
  size?: number;
  /** Size an item reaches directly under the pointer. */
  magnification?: number;
  /** How far, in pixels, the magnification reaches along the dock. */
  reach?: number;
  className?: string;
}

/**
 * A macOS-style dock: items swell as the pointer approaches and settle back
 * on a spring as it leaves.
 *
 * The pointer's x position is held in a motion value and read by each item
 * through context, so magnification runs entirely off the main thread: no
 * state updates and no re-renders per frame, however many items the dock
 * holds.
 */
export function Dock({
  children,
  size = 44,
  magnification = 76,
  reach = 130,
  className = "",
}: DockProps) {
  // Infinity parks every item at its resting size until the pointer arrives.
  const mouseX = useMotionValue(Number.POSITIVE_INFINITY);
  const prefersReducedMotion = useReducedMotion();

  return (
    <DockContext.Provider
      value={{
        mouseX,
        size,
        magnification: prefersReducedMotion ? size : magnification,
        reach,
      }}
    >
      <div
        role="toolbar"
        aria-label="Dock"
        onPointerMove={(event) => {
          if (event.pointerType === "touch" || prefersReducedMotion) return;
          mouseX.set(event.clientX);
        }}
        onPointerLeave={() => mouseX.set(Number.POSITIVE_INFINITY)}
        style={{ height: magnification + 16 }}
        className={`flex items-end gap-3 rounded-2xl border bg-card/70 px-4 pb-3 backdrop-blur-xl ${className}`}
      >
        {children}
      </div>
    </DockContext.Provider>
  );
}

interface DockItemProps {
  children: ReactNode;
  /** Name shown in the tooltip above the item, and its accessible name. */
  label: string;
  onClick?: () => void;
  /** Render as a link instead of a button. */
  href?: string;
  className?: string;
}

/**
 * A single dock entry.
 *
 * The label appears on focus as well as hover; a dock whose names only exist
 * on pointer hover is unusable by keyboard and invisible on touch.
 */
export function DockItem({ children, label, onClick, href, className = "" }: DockItemProps) {
  const { mouseX, size, magnification, reach } = useDock("DockItem");
  const ref = useRef<HTMLDivElement>(null);
  const [open, setOpen] = useState(false);

  // Horizontal distance from the pointer to this item's centre.
  const distance = useTransform(mouseX, (x) => {
    const bounds = ref.current?.getBoundingClientRect();
    if (!bounds) return Number.POSITIVE_INFINITY;
    return x - bounds.x - bounds.width / 2;
  });

  const targetSize = useTransform(distance, [-reach, 0, reach], [size, magnification, size], {
    clamp: true,
  });

  const width = useSpring(targetSize, {
    mass: 0.1,
    stiffness: 170,
    damping: 14,
  });

  const Interactive = href ? "a" : "button";

  return (
    <motion.div
      ref={ref}
      style={{ width, height: width }}
      onHoverStart={() => setOpen(true)}
      onHoverEnd={() => setOpen(false)}
      onFocus={() => setOpen(true)}
      onBlur={() => setOpen(false)}
      className="relative flex aspect-square shrink-0 items-end justify-center"
    >
      <AnimatePresence>
        {open ? (
          <motion.span
            role="tooltip"
            initial={{ opacity: 0, y: 6, scale: 0.9 }}
            animate={{ opacity: 1, y: 0, scale: 1 }}
            exit={{ opacity: 0, y: 6, scale: 0.9 }}
            transition={{ duration: 0.15 }}
            // Centred on the item and lifted clear of it, so it never covers
            // the icon it is naming.
            className="shadow-subtle pointer-events-none absolute -top-9 left-1/2 z-10 -translate-x-1/2 whitespace-nowrap rounded-md border bg-popover px-2 py-1 text-xs text-popover-foreground"
          >
            {label}
          </motion.span>
        ) : null}
      </AnimatePresence>

      <Interactive
        type={href ? undefined : "button"}
        href={href}
        onClick={onClick}
        aria-label={label}
        className={cn(
          "shadow-subtle flex size-full items-center justify-center rounded-xl border bg-background/80 transition-colors hover:bg-accent",
          className,
        )}
      >
        {children}
      </Interactive>
    </motion.div>
  );
}

export default Dock;
```

---

# Progress Ring

> A circular ring that smoothly sweeps to a value, with a live numeric readout.

Install: `npx @modus-ui/cli add progress-ring`

A highly precise, animated progress ring. It animates both the SVG `pathLength` and the numeric label smoothly using Framer Motion, avoiding the standard dash-array visual glitches on large stroke widths.

## Installation

### CLI

```bash
npx @modus-ui/cli add progress-ring
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/progress-ring.tsx`.
3. Paste the code.

## Usage

```tsx
import { ProgressRing } from "@/components/ui/progress-ring";

export default function Example() {
  return <ProgressRing value={75} size={120} strokeWidth={8} showLabel={true} />;
}
```

## Props

| Prop        | Type    | Default | Description                         |
| :---------- | :------ | :------ | :---------------------------------- |
| value       | number  | 72      | How far round to sweep, 0 to 100.   |
| size        | number  | 120     | Outer diameter, in pixels.          |
| strokeWidth | number  | 10      | Thickness of the ring, in pixels.   |
| duration    | number  | 1.2     | Seconds the sweep takes.            |
| showLabel   | boolean | true    | Print the percentage in the middle. |
| className   | string  | ""      | -                                   |

## Source

`components/ui/progress-ring.tsx`

```tsx
"use client";

import {
  animate,
  motion,
  useMotionValue,
  useMotionValueEvent,
  useReducedMotion,
} from "framer-motion";
import { useEffect, useState } from "react";
import { cn } from "@/lib/utils";

interface ProgressRingProps {
  /** How far round to sweep, 0 to 100. */
  value?: number;
  /** Outer diameter, in pixels. */
  size?: number;
  /** Thickness of the ring, in pixels. */
  strokeWidth?: number;
  /** Seconds the sweep takes. */
  duration?: number;
  /** Print the percentage in the middle. */
  showLabel?: boolean;
  className?: string;
}

/**
 * A ring that sweeps round to a value, with the number counting up beneath it.
 *
 * The arc is drawn by animating `pathLength`, which Motion resolves against
 * the circle's real measured length. The usual version of this computes
 * `2 * Math.PI * r` by hand into `strokeDasharray`, which is correct right up
 * until the stroke width changes the radius the arc is actually drawn at, and
 * then the ring stops short of its own end by a few pixels.
 *
 * The label is driven by the same animation rather than a second timer, so the
 * number cannot finish ahead of the arc it is describing. It is read from a
 * motion value into state, because text content is the one thing a motion
 * value cannot write without a render.
 *
 * Under reduced motion both arrive at their final value immediately: the ring
 * is a readout, and a readout that withholds the reading is worse than one
 * that never animated.
 */
export function ProgressRing({
  value = 72,
  size = 120,
  strokeWidth = 10,
  duration = 1.2,
  showLabel = true,
  className = "",
}: ProgressRingProps) {
  const prefersReducedMotion = useReducedMotion();
  const count = useMotionValue(0);
  const [display, setDisplay] = useState(0);

  useMotionValueEvent(count, "change", (latest) => setDisplay(Math.round(latest)));

  useEffect(() => {
    const controls = animate(count, value, {
      duration: prefersReducedMotion ? 0 : duration,
      ease: "easeOut",
    });
    return () => controls.stop();
  }, [count, value, duration, prefersReducedMotion]);

  // The arc is drawn along the centre of the stroke, so the radius has to come
  // in by half of it or the ring is clipped by its own viewBox.
  const radius = (size - strokeWidth) / 2;
  const centre = size / 2;

  return (
    <div className={cn("relative inline-flex", className)} style={{ width: size, height: size }}>
      <svg
        width={size}
        height={size}
        viewBox={`0 0 ${size} ${size}`}
        role="img"
        aria-label={`${Math.round(value)} percent`}
      >
        {/* Rotated so the sweep starts at twelve o'clock rather than three. */}
        <g transform={`rotate(-90 ${centre} ${centre})`}>
          <circle
            cx={centre}
            cy={centre}
            r={radius}
            fill="none"
            stroke="currentColor"
            strokeWidth={strokeWidth}
            className="text-muted"
          />
          <motion.circle
            cx={centre}
            cy={centre}
            r={radius}
            fill="none"
            stroke="currentColor"
            strokeWidth={strokeWidth}
            strokeLinecap="round"
            className="text-primary"
            initial={{ pathLength: 0 }}
            animate={{ pathLength: Math.min(Math.max(value, 0), 100) / 100 }}
            transition={{
              duration: prefersReducedMotion ? 0 : duration,
              ease: "easeOut",
            }}
          />
        </g>
      </svg>

      {showLabel ? (
        <span
          aria-hidden="true"
          className="absolute inset-0 flex items-center justify-center text-xl font-semibold tabular-nums"
        >
          {display}%
        </span>
      ) : null}
    </div>
  );
}

export default ProgressRing;
```

---

# Marquee

> A seamless, infinitely scrolling row of elements.

Install: `npx @modus-ui/cli add marquee`

A highly resilient marquee. Instead of using fragile CSS keyframes, it drives the scroll with Framer Motion's `useAnimationFrame` against a measured bounding box. This guarantees perfectly seamless wrapping without visual jumps, and allows you to pause the scroll instantly on hover.

## Installation

### CLI

```bash
npx @modus-ui/cli add marquee
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/marquee.tsx`.
3. Paste the code.

## Usage

```tsx
import { Marquee } from "@/components/ui/marquee";

export default function Example() {
  return (
    <Marquee speed={50} direction="left" pauseOnHover>
      <div className="mx-4">Logo 1</div>
      <div className="mx-4">Logo 2</div>
      <div className="mx-4">Logo 3</div>
    </Marquee>
  );
}
```

## Props

| Prop         | Type              | Default | Description                                              |
| :----------- | :---------------- | :------ | :------------------------------------------------------- |
| children     | ReactNode         | -       | The elements to scroll.                                  |
| speed        | number            | 60      | Pixels travelled per second.                             |
| direction    | "left" \| "right" | "left"  | The direction to scroll.                                 |
| pauseOnHover | boolean           | true    | Pause the scrolling when hovered.                        |
| fadeEdges    | boolean           | true    | Fade the leading and trailing edges into the background. |
| className    | string            | ""      | -                                                        |

## Source

`components/ui/marquee.tsx`

```tsx
"use client";

import { motion, useAnimationFrame, useMotionValue, useReducedMotion } from "framer-motion";
import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
import { cn } from "@/lib/utils";

interface MarqueeProps {
  children: ReactNode;
  /** Pixels travelled per second. */
  speed?: number;
  direction?: "left" | "right";
  pauseOnHover?: boolean;
  /** Fade the leading and trailing edges into the background. */
  fadeEdges?: boolean;
  className?: string;
}

/**
 * A seamless, infinitely scrolling row.
 *
 * Driven by `useAnimationFrame` against a motion value rather than a CSS
 * keyframe. That costs nothing extra and buys two things a keyframe cannot:
 * pausing mid-travel without a jump, and a wrap point measured from the real
 * rendered width, so any content loops seamlessly without hand-tuned timings.
 */
export function Marquee({
  children,
  speed = 60,
  direction = "left",
  pauseOnHover = true,
  fadeEdges = true,
  className = "",
}: MarqueeProps) {
  const trackRef = useRef<HTMLDivElement>(null);
  const x = useMotionValue(0);
  const [paused, setPaused] = useState(false);
  const [halfWidth, setHalfWidth] = useState(0);
  const prefersReducedMotion = useReducedMotion();

  const measure = useCallback(() => {
    const track = trackRef.current;
    if (!track) return;
    // The content is rendered twice, so one loop is half the track.
    setHalfWidth(track.scrollWidth / 2);
  }, []);

  useEffect(() => {
    measure();
    const track = trackRef.current;
    if (!track) return;

    const observer = new ResizeObserver(measure);
    observer.observe(track);
    return () => observer.disconnect();
  }, [measure]);

  useAnimationFrame((_, delta) => {
    if (paused || halfWidth === 0 || prefersReducedMotion) return;

    // delta is milliseconds since the last frame, so movement stays constant
    // regardless of refresh rate.
    const step = (speed * delta) / 1000;
    let next = x.get() + (direction === "left" ? -step : step);

    // Wrap by exactly one copy's width; the seam is never visible.
    if (next <= -halfWidth) next += halfWidth;
    if (next >= 0) next -= halfWidth;

    x.set(next);
  });

  return (
    <div
      className={cn("relative w-full overflow-hidden", className)}
      style={
        fadeEdges
          ? {
              maskImage:
                "linear-gradient(to right, transparent, black 12%, black 88%, transparent)",
              WebkitMaskImage:
                "linear-gradient(to right, transparent, black 12%, black 88%, transparent)",
            }
          : undefined
      }
      onPointerEnter={pauseOnHover ? () => setPaused(true) : undefined}
      onPointerLeave={pauseOnHover ? () => setPaused(false) : undefined}
    >
      <motion.div ref={trackRef} style={{ x }} className="flex w-max">
        <div className="flex shrink-0 items-center">{children}</div>
        {/* The duplicate is decorative; screen readers should hear the list
            once, not twice. */}
        <div className="flex shrink-0 items-center" aria-hidden="true">
          {children}
        </div>
      </motion.div>
    </div>
  );
}

export default Marquee;
```

---

# Mirror Plate

> A member pass whose surface mirrors the webcam through a metallic glass filter.

Install: `npx @modus-ui/cli add mirror-plate`

The plate is tinted from the theme background, with a serif name and mono meta lines.

## Installation

### CLI

```bash
npx @modus-ui/cli add mirror-plate
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/mirror-plate.tsx`.
3. Paste the code.

## Usage

```tsx
import { MirrorPlate } from "@/components/ui/mirror-plate";

export default function Example() {
  return <MirrorPlate />;
}
```

## Props

| Prop                 | Type   | Default                         | Description                                 |
| :------------------- | :----- | :------------------------------ | :------------------------------------------ |
| blurStrength         | number | 12                              | The strength of the blur effect.            |
| color                | string | "hsl(var(--foreground))"        | Text color overlay.                         |
| metalness            | number | 1                               | The metallic effect intensity.              |
| roughness            | number | 0.4                             | The roughness of the reflection.            |
| overlayColor         | string | "hsl(var(--background) / 0.35)" | Background overlay color.                   |
| displacementStrength | number | 20                              | How much the glass distorts the background. |
| noiseScale           | number | 1                               | The scale of the noise filter.              |
| specularConstant     | number | 1.2                             | The shininess of the reflection.            |
| grayscale            | number | 1                               | Grayscale strength of the webcam feed.      |
| glassDistortion      | number | 0                               | The glass displacement effect.              |
| className            | string | -                               | -                                           |

## Source

`components/ui/mirror-plate.tsx`

```tsx
"use client";
// A member pass whose face reflects the webcam through a brushed-metal glass filter.
import { useEffect, useId, useRef, useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { Activity, Fingerprint, Lock } from "lucide-react";
import { cn } from "@/lib/utils";

interface MirrorPlateProps {
  blurStrength?: number;
  color?: string;
  metalness?: number;
  roughness?: number;
  overlayColor?: string;
  displacementStrength?: number;
  noiseScale?: number;
  specularConstant?: number;
  grayscale?: number;
  glassDistortion?: number;
  className?: string;
}

export function MirrorPlate({
  blurStrength = 12,
  color = "hsl(var(--foreground))",
  metalness = 1,
  roughness = 0.4,
  overlayColor = "hsl(var(--background) / 0.35)",
  displacementStrength = 20,
  noiseScale = 1,
  specularConstant = 1.2,
  grayscale = 1,
  glassDistortion = 0,
  className,
}: MirrorPlateProps) {
  const prefersReduced = useReducedMotion();
  // Follow the setting only after hydration, so the first render matches the server's.
  const [reduce, setReduce] = useState(false);
  useEffect(() => setReduce(Boolean(prefersReduced)), [prefersReduced]);
  const filterId = `mirror-${useId().replace(/:/g, "")}`;
  const video = useRef<HTMLVideoElement>(null);
  const [live, setLive] = useState(false);

  useEffect(() => {
    let stream: MediaStream | undefined;
    let cancelled = false;
    navigator.mediaDevices
      ?.getUserMedia({ video: { facingMode: "user" } })
      .then((s) => {
        if (cancelled) return s.getTracks().forEach((t) => t.stop());
        stream = s;
        if (video.current) video.current.srcObject = s;
        setLive(true);
      })
      .catch(() => setLive(false));
    return () => {
      cancelled = true;
      stream?.getTracks().forEach((t) => t.stop());
    };
  }, []);

  const blur = (blurStrength * roughness) / 2;

  return (
    <div
      className={cn(
        "relative h-[440px] w-[300px] overflow-hidden rounded-2xl border border-border shadow-xl",
        className,
      )}
      style={{
        color,
        background:
          "linear-gradient(135deg, hsl(var(--muted)), hsl(var(--background)) 55%, hsl(var(--muted)))",
      }}
    >
      <svg className="absolute h-0 w-0" aria-hidden>
        <filter id={filterId}>
          <feTurbulence
            type="fractalNoise"
            baseFrequency={0.012 * noiseScale}
            numOctaves={2}
            seed={3}
            result="noise"
          />
          <feDisplacementMap
            in="SourceGraphic"
            in2="noise"
            scale={displacementStrength + glassDistortion}
            xChannelSelector="R"
            yChannelSelector="B"
            result="glass"
          />
          <feSpecularLighting
            in="noise"
            surfaceScale={3 * metalness}
            specularConstant={specularConstant}
            specularExponent={4 + 36 * (1 - roughness)}
            lightingColor="white"
            result="shine"
          >
            <feDistantLight azimuth={225} elevation={40} />
          </feSpecularLighting>
          <feComposite in="shine" in2="SourceAlpha" operator="in" result="shineMasked" />
          <feComposite
            in="glass"
            in2="shineMasked"
            operator="arithmetic"
            k2={1}
            k3={0.35 * metalness}
          />
        </filter>
      </svg>
      <video
        ref={video}
        autoPlay
        muted
        playsInline
        aria-hidden
        className={cn(
          "absolute inset-0 h-full w-full -scale-x-100 object-cover transition-opacity duration-500",
          !live && "opacity-0",
        )}
        style={{ filter: `grayscale(${grayscale}) blur(${blur}px) url(#${filterId})` }}
      />
      {!reduce && (
        <motion.div
          aria-hidden
          className="pointer-events-none absolute inset-0"
          style={{
            background:
              "linear-gradient(115deg, transparent 35%, hsl(var(--background) / 0.45) 50%, transparent 65%)",
            backgroundSize: "250% 100%",
          }}
          animate={{ backgroundPosition: ["120% 0%", "-20% 0%"] }}
          transition={{ duration: 5, repeat: Infinity, ease: "easeInOut", repeatDelay: 1.5 }}
        />
      )}
      <div className="absolute inset-0" style={{ background: overlayColor }} />
      <div className="relative flex h-full flex-col justify-between p-7">
        <div className="border-current/20 flex items-center justify-between border-b pb-4">
          <span className="border-current/30 inline-flex items-center gap-1.5 rounded-full border px-3 py-1 font-mono text-[10px] uppercase tracking-[0.2em]">
            <Lock className="size-3" /> Modus pass
          </span>
          <Activity className="size-5 opacity-80" />
        </div>
        <div className="text-center">
          <p className="font-serif text-3xl">Ada Moreno</p>
          <p className="mt-3 font-mono text-[10px] uppercase tracking-[0.25em] opacity-70">
            Studio member
          </p>
        </div>
        <div className="border-current/20 flex items-end justify-between border-t pt-4">
          <div>
            <p className="font-mono text-[9px] uppercase tracking-[0.2em] opacity-60">Member no.</p>
            <p className="mt-1 font-mono text-sm tracking-wider">MD-0427-1188</p>
          </div>
          <Fingerprint className="size-8 opacity-70" />
        </div>
      </div>
    </div>
  );
}
```

---

# Fluid Glass

> TODO one sentence on what Fluid Glass does.

Install: `npx @modus-ui/cli add fluid-glass`

TODO 2-3 sentences on why this component is useful.

## Installation

### CLI

```bash
npx @modus-ui/cli add fluid-glass
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/fluid-glass.tsx`.
3. Paste the code.

## Usage

```tsx
import { FluidGlass } from "@/components/ui/fluid-glass";

export default function Example() {
  return <FluidGlass />;
}
```

## Props

| Prop        | Type     | Default         | Description             |
| :---------- | :------- | :-------------- | :---------------------- |
| `text`      | `string` | `"Fluid Glass"` | TODO                    |
| `className` | `string` | -               | Additional CSS classes. |

## Source

`components/ui/fluid-glass.tsx`

```tsx
"use client";

import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface FluidGlassProps {
  text?: string;
  className?: string;
}

// TODO: Replace this stub with the real component.
export function FluidGlass({ text = "Fluid Glass", className }: FluidGlassProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <motion.div
      initial={prefersReducedMotion ? false : { opacity: 0, y: 8 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.4, ease: "easeOut" }}
      className={cn("font-serif text-4xl text-foreground", className)}
    >
      {text}
    </motion.div>
  );
}
```

---

# Dome Gallery

> An immersive 3D gallery dome.

Install: `npx @modus-ui/cli add dome-gallery`

An interactive 3D sphere of images.

## Installation

### CLI

```bash
npx @modus-ui/cli add dome-gallery
```

## Props

| Prop                    | Type    | Default                  | Description                         |
| :---------------------- | :------ | :----------------------- | :---------------------------------- |
| images                  | any[]   | []                       | Array of images to display.         |
| fit                     | number  | 0.5                      | Object fit.                         |
| fitBasis                | string  | "auto"                   | Object fit basis.                   |
| minRadius               | number  | 600                      | Min zoom radius.                    |
| maxRadius               | number  | Infinity                 | Max zoom radius.                    |
| padFactor               | number  | 0.25                     | Padding factor.                     |
| overlayBlurColor        | string  | "hsl(var(--background))" | Overlay color.                      |
| maxVerticalRotationDeg  | number  | 45                       | Max vertical rotation limit.        |
| dragSensitivity         | number  | 0.5                      | Sensitivity of drag.                |
| enlargeTransitionMs     | number  | 300                      | Transition timing.                  |
| segments                | number  | 8                        | Tiles per quarter turn of the dome. |
| dragDampening           | number  | 2                        | Dampening on drag.                  |
| openedImageWidth        | string  | "400px"                  | Width.                              |
| openedImageHeight       | string  | "400px"                  | Height.                             |
| imageBorderRadius       | string  | "30px"                   | Border radius of closed images.     |
| openedImageBorderRadius | string  | "30px"                   | Border radius of opened image.      |
| grayscale               | boolean | true                     | Whether the images are grayscale.   |

## Source

`components/ui/dome-gallery.tsx`

```tsx
"use client";
// The viewer stands inside a sphere tiled with images: drag to look around, click a tile to open it.

import { useEffect, useMemo, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
import {
  AnimatePresence,
  animate,
  motion,
  useMotionTemplate,
  useMotionValue,
  useReducedMotion,
} from "framer-motion";
import { cn } from "@/lib/utils";

type GalleryImage = string | { src: string; alt?: string };

export interface DomeGalleryProps {
  images?: GalleryImage[];
  fit?: number;
  fitBasis?: string;
  minRadius?: number;
  maxRadius?: number;
  padFactor?: number;
  overlayBlurColor?: string;
  maxVerticalRotationDeg?: number;
  dragSensitivity?: number;
  enlargeTransitionMs?: number;
  segments?: number;
  dragDampening?: number;
  openedImageWidth?: string;
  openedImageHeight?: string;
  imageBorderRadius?: string;
  openedImageBorderRadius?: string;
  grayscale?: boolean;
  className?: string;
}

const photo = (id: string) =>
  `https://images.unsplash.com/photo-${id}?auto=format&fit=crop&w=480&q=70`;

const SAMPLE_IMAGES: GalleryImage[] = [
  "1525625293386-3f8f99389edd",
  "1508964942454-1a56651d54ac",
  "1600664356348-10686526af4f",
  "1506351421178-63b52a2d2562",
  "1542114740389-9b46fb1e5be7",
  "1555217851-6141535bd771",
  "1496939376851-89342e90adcd",
  "1565967511849-76a60a516170",
].map((id) => ({ src: photo(id), alt: "" }));

const toImage = (image: GalleryImage) =>
  typeof image === "string" ? { src: image, alt: "" } : { src: image.src, alt: image.alt ?? "" };

function sizeBasis(width: number, height: number, basis: string) {
  if (basis === "width") return width;
  if (basis === "height") return height;
  if (basis === "max") return Math.max(width, height);
  return Math.min(width, height);
}

export function DomeGallery({
  images = [],
  fit = 0.5,
  fitBasis = "auto",
  minRadius = 600,
  maxRadius = Infinity,
  padFactor = 0.25,
  overlayBlurColor = "hsl(var(--background))",
  maxVerticalRotationDeg = 45,
  dragSensitivity = 0.5,
  enlargeTransitionMs = 300,
  segments = 8,
  dragDampening = 2,
  openedImageWidth = "400px",
  openedImageHeight = "400px",
  imageBorderRadius = "30px",
  openedImageBorderRadius = "30px",
  grayscale = true,
  className,
}: DomeGalleryProps) {
  const reduceMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const [radius, setRadius] = useState(minRadius);
  const [opened, setOpened] = useState<{ src: string; alt: string } | null>(null);
  const tiltX = useMotionValue(0);
  const turnY = useMotionValue(0);
  const wasDrag = useRef(false);
  const drag = useRef<{
    x: number;
    y: number;
    t: number;
    vx: number;
    vy: number;
    moved: boolean;
  } | null>(null);

  useEffect(() => {
    const el = rootRef.current;
    if (!el) return;
    const observer = new ResizeObserver(([entry]) => {
      const { width, height } = entry.contentRect;
      const r = sizeBasis(width, height, fitBasis) * fit;
      setRadius(Math.min(maxRadius, Math.max(minRadius, r)));
    });
    observer.observe(el);
    return () => observer.disconnect();
  }, [fit, fitBasis, minRadius, maxRadius]);

  // `segments` tiles per quarter turn; rows reach past the tilt limit so the dome never shows a gap.
  const step = 90 / segments;
  const tiles = useMemo(() => {
    const pool = (images.length ? images : SAMPLE_IMAGES).map(toImage);
    const rowReach = Math.ceil((maxVerticalRotationDeg + 30) / step);
    const out: { key: string; lon: number; lat: number; image: { src: string; alt: string } }[] =
      [];
    for (let row = -rowReach; row <= rowReach; row++) {
      for (let col = 0; col < segments * 4; col++) {
        const lon = col * step + (row % 2 ? step / 2 : 0);
        const index = (col * 3 + (row + rowReach) * 5) % pool.length;
        out.push({ key: `${row}:${col}`, lon, lat: row * step, image: pool[index] });
      }
    }
    return out;
  }, [images, segments, step, maxVerticalRotationDeg]);

  const tileSize = ((radius * step * Math.PI) / 180) * (1 - padFactor);
  const clampTilt = (deg: number) =>
    Math.max(-maxVerticalRotationDeg, Math.min(maxVerticalRotationDeg, deg));

  const onPointerDown = (event: PointerEvent) => {
    wasDrag.current = false;
    tiltX.stop();
    turnY.stop();
    drag.current = {
      x: event.clientX,
      y: event.clientY,
      t: event.timeStamp,
      vx: 0,
      vy: 0,
      moved: false,
    };
  };

  const onPointerMove = (event: PointerEvent) => {
    const d = drag.current;
    if (!d) return;
    const dx = (event.clientX - d.x) * dragSensitivity * 0.2;
    const dy = (event.clientY - d.y) * dragSensitivity * 0.2;
    if (!d.moved && Math.hypot(event.clientX - d.x, event.clientY - d.y) > 4) {
      d.moved = true;
      (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
    }
    if (!d.moved) return;
    const dt = Math.max(1, event.timeStamp - d.t);
    turnY.set(turnY.get() + dx);
    tiltX.set(clampTilt(tiltX.get() - dy));
    Object.assign(d, {
      x: event.clientX,
      y: event.clientY,
      t: event.timeStamp,
      vx: (dx / dt) * 1000,
      vy: (-dy / dt) * 1000,
    });
  };

  const onPointerUp = () => {
    const d = drag.current;
    drag.current = null;
    wasDrag.current = !!d?.moved;
    if (!d?.moved || reduceMotion) return;
    const glide = { type: "inertia" as const, timeConstant: 120 * dragDampening, power: 0.3 };
    animate(turnY, turnY.get(), { ...glide, velocity: d.vx });
    animate(tiltX, tiltX.get(), {
      ...glide,
      velocity: d.vy,
      min: -maxVerticalRotationDeg,
      max: maxVerticalRotationDeg,
    });
  };

  const onKeyDown = (event: KeyboardEvent) => {
    const turn = {
      ArrowLeft: [0, step],
      ArrowRight: [0, -step],
      ArrowUp: [-step, 0],
      ArrowDown: [step, 0],
    }[event.key];
    if (!turn) return;
    event.preventDefault();
    const transition = reduceMotion
      ? { duration: 0 }
      : { type: "spring" as const, stiffness: 200, damping: 30 };
    animate(tiltX, clampTilt(tiltX.get() + turn[0]), transition);
    animate(turnY, turnY.get() + turn[1], transition);
  };

  useEffect(() => {
    if (!opened) return;
    const close = (event: globalThis.KeyboardEvent) => event.key === "Escape" && setOpened(null);
    window.addEventListener("keydown", close);
    return () => window.removeEventListener("keydown", close);
  }, [opened]);

  // The camera sits 1px off the sphere's centre: exactly on it, browsers stop hit-testing the tiles.
  const sphere = useMotionTemplate`translateZ(${radius - 1}px) rotateX(${tiltX}deg) rotateY(${turnY}deg)`;
  const fade = reduceMotion ? 0 : enlargeTransitionMs / 1000;

  return (
    <div
      ref={rootRef}
      tabIndex={0}
      role="region"
      aria-label="Image dome. Drag or use the arrow keys to look around."
      onKeyDown={onKeyDown}
      className={cn(
        "relative h-full w-full touch-none select-none overflow-hidden outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
        className,
      )}
    >
      <div
        className="absolute inset-0 cursor-grab active:cursor-grabbing"
        style={{ perspective: radius }}
        onPointerDown={onPointerDown}
        onPointerMove={onPointerMove}
        onPointerUp={onPointerUp}
        onPointerCancel={onPointerUp}
      >
        <motion.div
          className="absolute left-1/2 top-1/2 h-0 w-0"
          style={{ transform: sphere, transformStyle: "preserve-3d" }}
        >
          {tiles.map(({ key, lon, lat, image }) => (
            <button
              key={key}
              type="button"
              tabIndex={-1}
              aria-label={image.alt || "Open image"}
              onClick={() => !wasDrag.current && setOpened(image)}
              className="absolute overflow-hidden bg-[hsl(var(--muted))] [backface-visibility:hidden]"
              style={{
                width: tileSize,
                height: tileSize,
                left: -tileSize / 2,
                top: -tileSize / 2,
                borderRadius: imageBorderRadius,
                transform: `rotateY(${lon}deg) rotateX(${lat}deg) translateZ(${-radius}px)`,
              }}
            >
              <img
                src={image.src}
                alt=""
                draggable={false}
                className={cn("block h-full w-full object-cover", grayscale && "grayscale")}
              />
            </button>
          ))}
        </motion.div>
      </div>

      <div
        aria-hidden
        className="pointer-events-none absolute inset-0"
        style={{
          background: `radial-gradient(ellipse at center, transparent 45%, ${overlayBlurColor} 95%)`,
        }}
      />

      <AnimatePresence>
        {opened && (
          <motion.div
            key="opened"
            className="absolute inset-0 z-10 flex items-center justify-center p-4 backdrop-blur-md"
            style={{ background: `color-mix(in srgb, ${overlayBlurColor} 60%, transparent)` }}
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            transition={{ duration: fade }}
            onClick={() => setOpened(null)}
          >
            <motion.img
              src={opened.src}
              alt={opened.alt}
              className="max-h-full max-w-full object-cover shadow-2xl"
              style={{
                width: openedImageWidth,
                height: openedImageHeight,
                borderRadius: openedImageBorderRadius,
              }}
              initial={{ scale: reduceMotion ? 1 : 0.6 }}
              animate={{ scale: 1 }}
              exit={{ scale: reduceMotion ? 1 : 0.6 }}
              transition={{ duration: fade, ease: [0.22, 1, 0.36, 1] }}
            />
          </motion.div>
        )}
      </AnimatePresence>
    </div>
  );
}
```

---

# Portrait Wall

> A wall of paper-toned portrait cards where colour returns only under the pointer.

Install: `npx @modus-ui/cli add portrait-wall`

A wall of paper-toned portrait cards with serif names; colour returns only under the pointer.

## Installation

### CLI

```bash
npx @modus-ui/cli add portrait-wall
```

## Props

| Prop      | Type               | Default | Description                                                      |
| :-------- | :----------------- | :------ | :--------------------------------------------------------------- |
| items     | PortraitWallItem[] | -       | Array of items to render.                                        |
| radius    | number             | 300     | Radius of the hover spotlight effect.                            |
| columns   | number             | 3       | Maximum number of grid columns; narrow containers wrap to fewer. |
| rows      | number             | 2       | Number of grid rows; items beyond columns × rows are not shown.  |
| damping   | number             | 15      | Spring damping for the spotlight movement.                       |
| className | string             | -       | Classes merged onto the grid root.                               |

## Source

`components/ui/portrait-wall.tsx`

```tsx
"use client";
// Portrait cards held in grey; a soft lens under the pointer lets their colour back in.
import type { PointerEvent } from "react";
import {
  motion,
  useMotionTemplate,
  useMotionValue,
  useReducedMotion,
  useSpring,
} from "framer-motion";
import { cn } from "@/lib/utils";

export interface PortraitWallItem {
  image: string;
  name: string;
  handle?: string;
  role?: string;
}

interface PortraitWallProps {
  items?: PortraitWallItem[];
  radius?: number;
  columns?: number;
  rows?: number;
  damping?: number;
  className?: string;
}

const photo = (id: string) =>
  `https://images.unsplash.com/photo-${id}?w=480&q=80&auto=format&fit=crop`;

const PEOPLE: PortraitWallItem[] = [
  {
    image: photo("1534528741775-53994a69daeb"),
    name: "Ines Okafor",
    handle: "@inesok",
    role: "Type designer",
  },
  {
    image: photo("1507003211169-0a1dd7228f2d"),
    name: "Theo Marchetti",
    handle: "@theom",
    role: "Bookbinder",
  },
  {
    image: photo("1494790108377-be9c29b29330"),
    name: "Hana Sato",
    handle: "@hanasato",
    role: "Letterpress printer",
  },
  {
    image: photo("1500648767791-00dcc994a43e"),
    name: "Arlo Venn",
    handle: "@arlovenn",
    role: "Paper maker",
  },
  {
    image: photo("1438761681033-6461ffad8d80"),
    name: "Mira Holt",
    handle: "@mirah",
    role: "Illustrator",
  },
  {
    image: photo("1472099645785-5658abf4ff4e"),
    name: "Jonas Ekberg",
    handle: "@jonase",
    role: "Archivist",
  },
];

export function PortraitWall({
  items = PEOPLE,
  radius = 300,
  columns = 3,
  rows = 2,
  damping = 15,
  className,
}: PortraitWallProps) {
  const reduce = useReducedMotion();
  const rawX = useMotionValue(-9999);
  const rawY = useMotionValue(-9999);
  const springX = useSpring(rawX, { stiffness: 160, damping });
  const springY = useSpring(rawY, { stiffness: 160, damping });
  const x = reduce ? rawX : springX;
  const y = reduce ? rawY : springY;
  const mask = useMotionTemplate`radial-gradient(circle ${radius / 2}px at ${x}px ${y}px, transparent 0%, transparent 35%, black 100%)`;

  const onMove = (e: PointerEvent<HTMLDivElement>) => {
    const box = e.currentTarget.getBoundingClientRect();
    if (rawX.get() < -999) {
      springX.jump(e.clientX - box.left);
      springY.jump(e.clientY - box.top);
    }
    rawX.set(e.clientX - box.left);
    rawY.set(e.clientY - box.top);
  };

  const onLeave = () => {
    rawX.set(-9999);
    rawY.set(-9999);
    springX.jump(-9999);
    springY.jump(-9999);
  };

  return (
    <div
      onPointerMove={onMove}
      onPointerLeave={onLeave}
      className={cn("relative grid w-full gap-3", className)}
      style={{
        maxWidth: columns * 240,
        gridTemplateColumns: `repeat(auto-fit, minmax(max(160px, calc((100% - ${(columns - 1) * 12}px) / ${columns})), 1fr))`,
      }}
    >
      {items.slice(0, columns * rows).map((p) => (
        <figure
          key={p.name}
          className="overflow-hidden rounded-lg border border-border bg-card p-3"
        >
          <img
            src={p.image}
            alt={p.name}
            loading="lazy"
            className="aspect-[4/5] w-full rounded-md object-cover"
          />
          <figcaption className="mt-3 space-y-1">
            <p className="font-serif text-lg leading-none text-foreground">{p.name}</p>
            {p.handle && <p className="font-sans text-xs text-muted-foreground">{p.handle}</p>}
            {p.role && (
              <p className="font-mono text-[10px] uppercase tracking-[0.18em] text-muted-foreground">
                {p.role}
              </p>
            )}
          </figcaption>
        </figure>
      ))}
      <motion.div
        aria-hidden
        className="pointer-events-none absolute inset-0 rounded-lg backdrop-grayscale"
        style={{
          background: "hsl(var(--background) / 0.12)",
          maskImage: mask,
          WebkitMaskImage: mask,
        }}
      />
    </div>
  );
}
```

---

# Chime Switch

> A square-shouldered subscribe switch whose bell chimes as it flips to the theme ink.

Install: `npx @modus-ui/cli add chime-switch`

Chime Switch is a subscribe toggle: switching it on fills it with the theme's primary ink, swings the bell in a decaying chime and shows a count badge. It is a real switch with `aria-checked`, so keyboard and screen readers treat it as one.

## Installation

### CLI

```bash
npx @modus-ui/cli add chime-switch
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/chime-switch.tsx`.
3. Paste the code.

## Usage

```tsx
import { ChimeSwitch } from "@/components/ui/chime-switch";

export default function Example() {
  return <ChimeSwitch />;
}
```

## Props

| Prop           | Type    | Default                                | Description                                     |
| :------------- | :------ | :------------------------------------- | :---------------------------------------------- |
| offLabel       | string  | `"Keep me posted"`                     | Label while off.                                |
| onLabel        | string  | `"On the list"`                        | Label while on.                                 |
| icon           | any     | -                                      | Replaces the bell.                              |
| label          | any     | -                                      | Replaces both labels.                           |
| color          | string  | `"hsl(var(--foreground))"`             | Text colour while off.                          |
| background     | string  | `"hsl(var(--muted))"`                  | Background while off.                           |
| onColor        | string  | `"hsl(var(--primary-foreground))"`     | Text colour while on.                           |
| onBackground   | string  | `"hsl(var(--primary))"`                | Background while on.                            |
| size           | string  | "md"                                   | Size: "sm", "md" or "lg".                       |
| radius         | number  | `8`                                    | Corner radius in pixels.                        |
| ringAmplitude  | number  | 17                                     | First swing angle in degrees.                   |
| ringPasses     | number  | 5                                      | Number of swings.                               |
| ringDecay      | number  | 1                                      | How quickly swings shrink.                      |
| ringDuration   | number  | 820                                    | Chime duration in milliseconds.                 |
| ringPivot      | number  | 16                                     | Swing pivot, as a percentage from the bell top. |
| crossfadeMs    | number  | 200                                    | Label and colour crossfade in milliseconds.     |
| revealBounce   | number  | 0                                      | Spring bounce of the label and badge.           |
| count          | number  | `3`                                    | Number shown in the badge.                      |
| badge          | boolean | true                                   | Shows the badge while on.                       |
| badgeColor     | string  | `"hsl(var(--destructive))"`            | Badge background.                               |
| badgeTextColor | string  | `"hsl(var(--destructive-foreground))"` | Badge text colour.                              |
| waves          | boolean | true                                   | Shows sound waves while ringing.                |
| clapper        | boolean | `true`                                 | Draws the swinging clapper.                     |
| pressed        | any     | -                                      | Controlled state.                               |
| defaultPressed | boolean | false                                  | Initial state when uncontrolled.                |
| onChange       | any     | -                                      | Called with the new state.                      |
| disabled       | boolean | false                                  | Disables the switch.                            |

## Source

`components/ui/chime-switch.tsx`

```tsx
"use client";
// Subscribe toggle: switching on fills it with the theme ink and swings the bell in a decaying chime.

import { useState, type ReactNode } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const SIZES = {
  sm: { box: "h-8 px-3 text-[10px] gap-2", bell: 14 },
  md: { box: "h-10 px-4 text-[11px] gap-2.5", bell: 16 },
  lg: { box: "h-12 px-5 text-xs gap-3", bell: 19 },
};

/** Swing angles that alternate sides and shrink toward rest. */
function chime(amplitude: number, passes: number, decay: number) {
  const n = Math.max(1, Math.round(passes));
  const angles = [0];
  for (let i = 0; i < n; i++)
    angles.push((i % 2 ? -1 : 1) * amplitude * Math.pow(1 - i / n, decay));
  angles.push(0);
  return angles;
}

export interface ChimeSwitchProps {
  offLabel?: string;
  onLabel?: string;
  icon?: ReactNode;
  label?: ReactNode;
  color?: string;
  background?: string;
  onColor?: string;
  onBackground?: string;
  size?: keyof typeof SIZES;
  radius?: number;
  ringAmplitude?: number;
  ringPasses?: number;
  ringDecay?: number;
  ringDuration?: number;
  ringPivot?: number;
  crossfadeMs?: number;
  revealBounce?: number;
  count?: number;
  badge?: boolean;
  badgeColor?: string;
  badgeTextColor?: string;
  waves?: boolean;
  clapper?: boolean;
  pressed?: boolean;
  defaultPressed?: boolean;
  onChange?: (pressed: boolean) => void;
  disabled?: boolean;
  className?: string;
}

export function ChimeSwitch({
  offLabel = "Keep me posted",
  onLabel = "On the list",
  icon,
  label,
  color = "hsl(var(--foreground))",
  background = "hsl(var(--muted))",
  onColor = "hsl(var(--primary-foreground))",
  onBackground = "hsl(var(--primary))",
  size = "md",
  radius = 8,
  ringAmplitude = 17,
  ringPasses = 5,
  ringDecay = 1,
  ringDuration = 820,
  ringPivot = 16,
  crossfadeMs = 200,
  revealBounce = 0,
  count = 3,
  badge = true,
  badgeColor = "hsl(var(--destructive))",
  badgeTextColor = "hsl(var(--destructive-foreground))",
  waves = true,
  clapper = true,
  pressed,
  defaultPressed = false,
  onChange,
  disabled = false,
  className,
}: ChimeSwitchProps) {
  const reduce = useReducedMotion();
  const [inner, setInner] = useState(defaultPressed);
  const [rings, setRings] = useState(0);
  const on = pressed ?? inner;
  const s = SIZES[size];
  const ringing = on && rings > 0 && !reduce;
  const angles = chime(ringAmplitude, ringPasses, ringDecay);
  const swing = { duration: ringDuration / 1000, ease: "easeInOut" as const };
  const fade = reduce ? 0 : crossfadeMs / 1000;
  const reveal = reduce
    ? { duration: 0 }
    : { type: "spring" as const, duration: 0.4, bounce: revealBounce };

  const toggle = () => {
    const next = !on;
    if (pressed === undefined) setInner(next);
    if (next) setRings((n) => n + 1);
    onChange?.(next);
  };

  return (
    <motion.button
      type="button"
      role="switch"
      aria-checked={on}
      disabled={disabled}
      onClick={toggle}
      whileTap={reduce ? undefined : { scale: 0.97 }}
      animate={{ backgroundColor: on ? onBackground : background, color: on ? onColor : color }}
      transition={{ duration: fade }}
      className={cn(
        "relative inline-flex select-none items-center font-mono uppercase tracking-[0.18em] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 focus-visible:ring-offset-[hsl(var(--background))] disabled:opacity-50",
        s.box,
        className,
      )}
      style={{ borderRadius: radius }}
    >
      <span className="relative grid place-items-center" style={{ width: s.bell, height: s.bell }}>
        {waves && ringing && (
          <span key={rings} aria-hidden className="pointer-events-none absolute inset-0">
            {[-1, 1].map((side) => (
              <motion.span
                key={side}
                className="absolute top-1/2 h-2/3 w-1/3 -translate-y-1/2 rounded-full border-current"
                style={{
                  [side < 0 ? "right" : "left"]: "100%",
                  borderLeftWidth: side > 0 ? 1.5 : 0,
                  borderRightWidth: side < 0 ? 1.5 : 0,
                }}
                initial={{ opacity: 0.9, x: 0 }}
                animate={{ opacity: 0, x: side * s.bell * 0.4 }}
                transition={{ duration: ringDuration / 1000, ease: "easeOut" }}
              />
            ))}
          </span>
        )}
        {icon ?? (
          <motion.svg
            key={`bell-${rings}`}
            viewBox="0 0 24 24"
            width={s.bell}
            height={s.bell}
            fill="none"
            stroke="currentColor"
            strokeWidth={1.8}
            strokeLinecap="round"
            strokeLinejoin="round"
            style={{ originX: "50%", originY: `${ringPivot}%` }}
            initial={false}
            animate={ringing ? { rotate: angles } : { rotate: 0 }}
            transition={swing}
            aria-hidden
          >
            <path d="M6 16.5V11a6 6 0 0 1 12 0v5.5l1.5 1.5h-15z" />
            <path d="M12 3v2" />
            {clapper && (
              <motion.circle
                cx={12}
                cy={20.5}
                r={1.6}
                fill="currentColor"
                style={{ originX: "50%", originY: "0%" }}
                animate={ringing ? { x: angles.map((a) => -a / 12) } : { x: 0 }}
                transition={swing}
              />
            )}
          </motion.svg>
        )}
        <AnimatePresence>
          {badge && on && count > 0 && (
            <motion.span
              className="absolute -right-2 -top-2 grid h-4 min-w-4 place-items-center rounded-full px-1 text-[9px] font-semibold tracking-normal"
              style={{ background: badgeColor, color: badgeTextColor }}
              initial={{ scale: 0 }}
              animate={{ scale: 1 }}
              exit={{ scale: 0 }}
              transition={reveal}
            >
              {count}
            </motion.span>
          )}
        </AnimatePresence>
      </span>
      {label ?? (
        <span className="relative grid">
          <AnimatePresence initial={false} mode="popLayout">
            <motion.span
              key={on ? "on" : "off"}
              className="col-start-1 row-start-1 whitespace-nowrap"
              initial={{ opacity: 0, y: reduce ? 0 : 6 }}
              animate={{ opacity: 1, y: 0 }}
              exit={{ opacity: 0, y: reduce ? 0 : -6 }}
              transition={
                reveal.duration === 0 ? { duration: 0 } : { ...reveal, opacity: { duration: fade } }
              }
            >
              {on ? onLabel : offLabel}
            </motion.span>
          </AnimatePresence>
        </span>
      )}
    </motion.button>
  );
}
```

---

# Root Nav

> A docs-style navigation tree whose hairline roots draw out to each open chapter.

Install: `npx @modus-ui/cli add root-nav`

Chapters open and fold under mono headings, and a hairline root draws from the trunk to each page, with the active page's root inked in the accent colour. Use it as the sidebar of a docs site or any shallow two-level tree.

## Installation

### CLI

```bash
npx @modus-ui/cli add root-nav
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/root-nav.tsx`.
3. Paste the code.

## Usage

```tsx
import { RootNav } from "@/components/ui/root-nav";

export default function Example() {
  return <RootNav />;
}
```

## Props

| Prop          | Type   | Default                    | Description |
| :------------ | :----- | :------------------------- | :---------- |
| items         | any    | DEFAULT_ITEMS              | -           |
| defaultOpen   | number | 0                          | -           |
| defaultActive | string | ""                         | -           |
| onSelect      | any    | -                          | -           |
| onToggle      | any    | -                          | -           |
| color         | string | `"hsl(var(--foreground))"` | -           |
| accentColor   | string | `"hsl(var(--primary))"`    | -           |
| lineColor     | string | `"hsl(var(--border))"`     | -           |
| width         | number | 240                        | -           |
| rowHeight     | number | 36                         | -           |
| indent        | number | `36`                       | -           |
| trunk         | number | 14                         | -           |
| radius        | number | `4`                        | -           |
| lineWidth     | number | 1.5                        | -           |
| fontSize      | number | 14                         | -           |
| drawDuration  | number | 400                        | -           |
| foldDuration  | number | 300                        | -           |

## Source

`components/ui/root-nav.tsx`

```tsx
"use client";
// A docs navigation tree whose hairline roots draw out to each open chapter's pages.

import { useState } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { HugeiconsIcon, type IconSvgElement } from "@hugeicons/react";
import {
  Download01Icon,
  Layers01Icon,
  Notification01Icon,
  PaintBoardIcon,
  Rocket01Icon,
  Settings01Icon,
  SquareIcon,
  TextFontIcon,
} from "@hugeicons/core-free-icons";
import { cn } from "@/lib/utils";

export interface RootNavPage {
  id: string;
  label: string;
  icon?: IconSvgElement;
}

export interface RootNavChapter {
  title: string;
  pages: RootNavPage[];
}

const DEFAULT_ITEMS: RootNavChapter[] = [
  {
    title: "Foundations",
    pages: [
      { id: "installation", label: "Installation", icon: Download01Icon },
      { id: "quick-start", label: "Quick start", icon: Rocket01Icon },
      { id: "configuration", label: "Configuration", icon: Settings01Icon },
      { id: "theming", label: "Theming", icon: PaintBoardIcon },
    ],
  },
  {
    title: "Library",
    pages: [
      { id: "buttons", label: "Buttons", icon: SquareIcon },
      { id: "typography", label: "Typography", icon: TextFontIcon },
      { id: "overlays", label: "Overlays", icon: Layers01Icon },
      { id: "toasts", label: "Toasts", icon: Notification01Icon },
    ],
  },
];

export interface RootNavProps {
  items?: RootNavChapter[];
  defaultOpen?: number;
  defaultActive?: string;
  onSelect?: (id: string) => void;
  onToggle?: (index: number, open: boolean) => void;
  color?: string;
  accentColor?: string;
  lineColor?: string;
  width?: number;
  rowHeight?: number;
  indent?: number;
  trunk?: number;
  radius?: number;
  lineWidth?: number;
  fontSize?: number;
  drawDuration?: number;
  foldDuration?: number;
  className?: string;
}

export function RootNav({
  items = DEFAULT_ITEMS,
  defaultOpen = 0,
  defaultActive = "",
  onSelect,
  onToggle,
  color = "hsl(var(--foreground))",
  accentColor = "hsl(var(--primary))",
  lineColor = "hsl(var(--border))",
  width = 240,
  rowHeight = 36,
  indent = 36,
  trunk = 14,
  radius = 4,
  lineWidth = 1.5,
  fontSize = 14,
  drawDuration = 400,
  foldDuration = 300,
  className,
}: RootNavProps) {
  const reduce = useReducedMotion();
  const [open, setOpen] = useState<Set<number>>(() => new Set([defaultOpen]));
  const [active, setActive] = useState(defaultActive || items[defaultOpen]?.pages[0]?.id || "");

  const toggle = (i: number) => {
    const next = new Set(open);
    const isOpen = !next.has(i);
    if (isOpen) next.add(i);
    else next.delete(i);
    setOpen(next);
    onToggle?.(i, isOpen);
  };

  return (
    <nav className={cn("select-none", className)} style={{ width, color, fontSize }}>
      {items.map((chapter, ci) => {
        const isOpen = open.has(ci);
        const listId = `root-nav-${ci}`;
        return (
          <div key={chapter.title} className="relative">
            <button
              type="button"
              aria-expanded={isOpen}
              aria-controls={listId}
              onClick={() => toggle(ci)}
              className={cn(
                "flex w-full items-center font-mono text-[10px] uppercase tracking-[0.18em] transition-opacity focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
                !isOpen && "opacity-50 hover:opacity-80",
              )}
              style={{ height: rowHeight, paddingLeft: trunk + 10 }}
            >
              {chapter.title}
            </button>
            {/* Tick marking the chapter; it inks in when the chapter is open. */}
            <span
              aria-hidden
              className="absolute transition-colors"
              style={{
                left: trunk - lineWidth / 2,
                top: rowHeight * 0.3,
                height: isOpen ? rowHeight * 0.7 : rowHeight * 0.4,
                width: lineWidth,
                background: isOpen ? color : lineColor,
              }}
            />
            <AnimatePresence initial={false}>
              {isOpen && (
                <motion.ul
                  id={listId}
                  className="relative m-0 list-none overflow-hidden p-0"
                  initial={{ height: 0, opacity: 0 }}
                  animate={{ height: "auto", opacity: 1 }}
                  exit={{ height: 0, opacity: 0 }}
                  transition={{
                    duration: reduce ? 0 : foldDuration / 1000,
                    ease: [0.4, 0, 0.2, 1],
                  }}
                >
                  {chapter.pages.map((page, pi) => {
                    const on = page.id === active;
                    const y = rowHeight / 2;
                    const bend = Math.min(radius, y);
                    const start = pi === 0 ? 0 : -y;
                    const root = `M ${trunk} ${start} V ${y - bend} Q ${trunk} ${y} ${trunk + bend} ${y} H ${indent - 6}`;
                    return (
                      <li key={page.id} className="relative m-0 p-0" style={{ height: rowHeight }}>
                        <svg
                          aria-hidden
                          className="pointer-events-none absolute left-0 top-0 overflow-visible"
                          width={indent}
                          height={rowHeight}
                        >
                          <motion.path
                            d={root}
                            fill="none"
                            stroke={on ? accentColor : lineColor}
                            strokeWidth={lineWidth}
                            initial={{ pathLength: reduce ? 1 : 0 }}
                            animate={{ pathLength: 1 }}
                            transition={{
                              duration: reduce ? 0 : drawDuration / 1000,
                              delay: reduce ? 0 : (pi * drawDuration) / 4000,
                              ease: "easeOut",
                            }}
                          />
                        </svg>
                        <button
                          type="button"
                          aria-current={on ? "page" : undefined}
                          onClick={() => {
                            setActive(page.id);
                            onSelect?.(page.id);
                          }}
                          className={cn(
                            "flex h-full w-full items-center gap-2 text-left transition-opacity focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
                            on ? "font-medium" : "opacity-55 hover:opacity-90",
                          )}
                          style={{ paddingLeft: indent }}
                        >
                          {page.icon && (
                            <HugeiconsIcon
                              icon={page.icon}
                              size={fontSize}
                              color={on ? accentColor : "currentColor"}
                            />
                          )}
                          {page.label}
                        </button>
                      </li>
                    );
                  })}
                </motion.ul>
              )}
            </AnimatePresence>
          </div>
        );
      })}
    </nav>
  );
}
```

---

# Run Tag

> A monospace run tag that fills with theme ink while a command runs, then settles to done or retry.

Install: `npx @modus-ui/cli add run-tag`

Show a command's progress inline: the tag fills with ink toward its expected duration while running, washes to the done colour on success, and shakes with a retry action on failure. A live elapsed timer and a screen-reader status line come built in.

## Installation

### CLI

```bash
npx @modus-ui/cli add run-tag
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/run-tag.tsx`.
3. Paste the code.

## Usage

```tsx
import { RunTag } from "@/components/ui/run-tag";

export default function Example() {
  return <RunTag />;
}
```

## Props

| Prop            | Type    | Default                     | Description |
| :-------------- | :------ | :-------------------------- | :---------- |
| icon            | string  | "terminal"                  | -           |
| name            | string  | `"pnpm"`                    | -           |
| argument        | string  | `"build --filter docs"`     | -           |
| status          | string  | "running"                   | -           |
| expectedMs      | number  | 2500                        | -           |
| size            | number  | 34                          | -           |
| radius          | number  | `6`                         | -           |
| color           | string  | `"hsl(var(--foreground))"`  | -           |
| surfaceColor    | string  | `"hsl(var(--muted))"`       | -           |
| progressColor   | string  | `"hsl(var(--primary))"`     | -           |
| progressOpacity | number  | `0.16`                      | -           |
| doneColor       | string  | `"hsl(var(--primary))"`     | -           |
| errorColor      | string  | `"hsl(var(--destructive))"` | -           |
| washOpacity     | number  | 0.14                        | -           |
| shake           | number  | 6                           | -           |
| showTimer       | boolean | true                        | -           |
| onRetry         | any     | -                           | -           |
| style           | any     | -                           | -           |

## Source

`components/ui/run-tag.tsx`

```tsx
"use client";
// A monospace command tag that fills with ink while it runs, then settles to done or retry.

import { useEffect, useState, type CSSProperties } from "react";
import { motion, useMotionValue, useReducedMotion, useTransform } from "framer-motion";
import { HugeiconsIcon } from "@hugeicons/react";
import {
  Alert02Icon,
  CommandLineIcon,
  ComputerTerminal01Icon,
  RefreshIcon,
  Tick02Icon,
} from "@hugeicons/core-free-icons";
import { cn } from "@/lib/utils";

const ICONS = { terminal: ComputerTerminal01Icon, command: CommandLineIcon };

export interface RunTagProps {
  icon?: keyof typeof ICONS;
  name?: string;
  argument?: string;
  status?: "running" | "done" | "error";
  expectedMs?: number;
  size?: number;
  radius?: number;
  color?: string;
  surfaceColor?: string;
  progressColor?: string;
  progressOpacity?: number;
  doneColor?: string;
  errorColor?: string;
  washOpacity?: number;
  shake?: number;
  showTimer?: boolean;
  onRetry?: () => void;
  style?: CSSProperties;
  className?: string;
}

export function RunTag({
  icon = "terminal",
  name = "pnpm",
  argument = "build --filter docs",
  status = "running",
  expectedMs = 2500,
  size = 34,
  radius = 6,
  color = "hsl(var(--foreground))",
  surfaceColor = "hsl(var(--muted))",
  progressColor = "hsl(var(--primary))",
  progressOpacity = 0.16,
  doneColor = "hsl(var(--primary))",
  errorColor = "hsl(var(--destructive))",
  washOpacity = 0.14,
  shake = 6,
  showTimer = true,
  onRetry,
  style,
  className,
}: RunTagProps) {
  const reduce = useReducedMotion();
  const [elapsed, setElapsed] = useState(0);
  const progress = useMotionValue(0);
  const width = useTransform(progress, (p) => `${p * 100}%`);

  useEffect(() => {
    if (status !== "running") {
      progress.set(status === "done" ? 1 : progress.get());
      return;
    }
    const start = performance.now();
    progress.set(0);
    let frame = 0;
    const tick = () => {
      const ms = performance.now() - start;
      setElapsed(Math.round(ms));
      // Eases towards the end but never arrives until the run does.
      progress.set(1 - Math.exp(-ms / expectedMs));
      frame = requestAnimationFrame(tick);
    };
    frame = requestAnimationFrame(tick);
    return () => cancelAnimationFrame(frame);
  }, [status, expectedMs, progress]);

  const settled = status !== "running";
  const tone = status === "done" ? doneColor : status === "error" ? errorColor : progressColor;

  return (
    <motion.div
      className={cn(
        "relative inline-flex items-center gap-2 overflow-hidden whitespace-nowrap px-3 font-mono text-xs",
        className,
      )}
      style={{ height: size, borderRadius: radius, background: surfaceColor, color, ...style }}
      animate={
        status === "error" && !reduce
          ? { x: [0, -shake, shake, -shake / 2, shake / 2, 0] }
          : { x: 0 }
      }
      transition={{ duration: 0.4 }}
    >
      <motion.span
        aria-hidden
        className="absolute inset-y-0 left-0"
        style={{ width: settled ? "100%" : width, background: tone }}
        initial={false}
        animate={{ opacity: settled ? washOpacity : progressOpacity }}
        transition={{ duration: reduce ? 0 : 0.3 }}
      />
      <span className="relative flex items-center gap-2" aria-hidden>
        <HugeiconsIcon icon={ICONS[icon] ?? ComputerTerminal01Icon} size={size * 0.4} />
        <span className="font-semibold">{name}</span>
        <span className="opacity-70">{argument}</span>
        {showTimer && <span className="tabular-nums opacity-50">{elapsed} ms</span>}
        {status === "done" && (
          <HugeiconsIcon icon={Tick02Icon} size={size * 0.4} color={doneColor} />
        )}
        {status === "error" && (
          <HugeiconsIcon icon={Alert02Icon} size={size * 0.4} color={errorColor} />
        )}
      </span>
      {status === "error" && onRetry && (
        <button
          type="button"
          onClick={onRetry}
          className="relative -mr-1.5 flex items-center gap-1 rounded px-1.5 py-1 uppercase tracking-[0.12em] hover:bg-[hsl(var(--background)/0.6)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
          style={{ color: errorColor }}
        >
          <HugeiconsIcon icon={RefreshIcon} size={size * 0.35} />
          Retry
        </button>
      )}
      <span className="sr-only" role="status">
        {`${name} ${argument}, ${status}`}
      </span>
    </motion.div>
  );
}
```

---

# Cipher Reel

> A one-time code field of paper slots with serif numerals that drop in and seal on success.

Install: `npx @modus-ui/cli add cipher-reel`

Cipher Reel is a one-time code field. A single hidden input does the typing, pasting and autofill, while serif numerals drop into paper slots; set `status` to seal the slots on success or shake them on error.

## Installation

### CLI

```bash
npx @modus-ui/cli add cipher-reel
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/cipher-reel.tsx`.
3. Paste the code.

## Usage

```tsx
import { CipherReel } from "@/components/ui/cipher-reel";

export default function Example() {
  return <CipherReel />;
}
```

## Props

| Prop         | Type    | Default                     | Description                                               |
| :----------- | :------ | :-------------------------- | :-------------------------------------------------------- |
| length       | number  | 6                           | Number of slots.                                          |
| value        | any     | -                           | Controlled code.                                          |
| defaultValue | string  | ""                          | Initial code when uncontrolled.                           |
| onChange     | any     | -                           | Called with the code on every edit.                       |
| onComplete   | any     | -                           | Called once every slot is filled.                         |
| status       | string  | "idle"                      | "idle", "success" (slots seal) or "error" (field shakes). |
| mask         | boolean | false                       | Shows dots instead of digits.                             |
| caret        | boolean | true                        | Blinks a caret in the active slot.                        |
| disabled     | boolean | false                       | Disables input.                                           |
| autoFocus    | boolean | false                       | Focuses on mount.                                         |
| accentColor  | string  | `"hsl(var(--primary))"`     | Seal outline on success.                                  |
| inkColor     | string  | `"hsl(var(--foreground))"`  | Active slot outline and caret.                            |
| slotColor    | string  | `"hsl(var(--muted))"`       | Slot fill.                                                |
| digitColor   | string  | `"hsl(var(--foreground))"`  | Numeral colour.                                           |
| dangerColor  | string  | `"hsl(var(--destructive))"` | Outline on error.                                         |
| slotSize     | number  | `48`                        | Slot width in pixels.                                     |
| gap          | number  | `10`                        | Space between slots in pixels.                            |
| radius       | number  | `6`                         | Slot corner radius in pixels.                             |
| bounce       | number  | 0.2                         | Spring bounce as a digit lands.                           |
| settle       | number  | 0.3                         | Seal pulse duration in seconds.                           |
| rise         | number  | 8                           | Height digits drop from, in pixels.                       |
| cascade      | number  | 20                          | Delay between slots sealing, in milliseconds.             |
| ariaLabel    | string  | "One-time code"             | Accessible label.                                         |

## Source

`components/ui/cipher-reel.tsx`

```tsx
"use client";
// One-time code field: serif numerals drop into paper slots, which seal in a cascade on success.

import { useState } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface CipherReelProps {
  length?: number;
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
  onComplete?: (value: string) => void;
  status?: "idle" | "success" | "error";
  mask?: boolean;
  caret?: boolean;
  disabled?: boolean;
  autoFocus?: boolean;
  accentColor?: string;
  inkColor?: string;
  slotColor?: string;
  digitColor?: string;
  dangerColor?: string;
  slotSize?: number;
  gap?: number;
  radius?: number;
  bounce?: number;
  settle?: number;
  rise?: number;
  cascade?: number;
  ariaLabel?: string;
  className?: string;
}

export function CipherReel({
  length = 6,
  value,
  defaultValue = "",
  onChange,
  onComplete,
  status = "idle",
  mask = false,
  caret = true,
  disabled = false,
  autoFocus = false,
  accentColor = "hsl(var(--primary))",
  inkColor = "hsl(var(--foreground))",
  slotColor = "hsl(var(--muted))",
  digitColor = "hsl(var(--foreground))",
  dangerColor = "hsl(var(--destructive))",
  slotSize = 48,
  gap = 10,
  radius = 6,
  bounce = 0.2,
  settle = 0.3,
  rise = 8,
  cascade = 20,
  ariaLabel = "One-time code",
  className,
}: CipherReelProps) {
  const reduce = useReducedMotion();
  const [inner, setInner] = useState(defaultValue);
  const [focused, setFocused] = useState(false);
  const code = (value ?? inner).slice(0, length);

  const write = (raw: string) => {
    const next = raw.replace(/\D/g, "").slice(0, length);
    if (value === undefined) setInner(next);
    onChange?.(next);
    if (next.length === length && next !== code) onComplete?.(next);
  };

  const edge =
    status === "success" ? accentColor : status === "error" ? dangerColor : "transparent";

  return (
    <motion.label
      className={cn("relative inline-flex cursor-text", disabled && "opacity-50", className)}
      style={{ gap }}
      animate={status === "error" && !reduce ? { x: [0, -6, 6, -4, 4, 0] } : { x: 0 }}
      transition={{ duration: 0.4 }}
    >
      <input
        aria-label={ariaLabel}
        value={code}
        onChange={(e) => write(e.target.value)}
        onFocus={() => setFocused(true)}
        onBlur={() => setFocused(false)}
        inputMode="numeric"
        autoComplete="one-time-code"
        maxLength={length}
        disabled={disabled}
        autoFocus={autoFocus}
        aria-invalid={status === "error" || undefined}
        className="absolute inset-0 h-full w-full cursor-text opacity-0"
      />
      {Array.from({ length }, (_, i) => {
        const ch = code[i];
        const active = focused && i === Math.min(code.length, length - 1);
        return (
          <motion.span
            key={i}
            aria-hidden
            className="relative grid place-items-center overflow-hidden font-serif tabular-nums"
            style={{
              width: slotSize,
              height: slotSize * 1.18,
              borderRadius: radius,
              background: slotColor,
              color: digitColor,
              fontSize: slotSize * 0.55,
              boxShadow: `inset 0 0 0 1.5px ${active ? inkColor : edge}`,
            }}
            animate={status === "success" && !reduce ? { scale: [1, 1.06, 1] } : { scale: 1 }}
            transition={{ duration: settle, delay: (i * cascade) / 1000 }}
          >
            <AnimatePresence initial={false}>
              {ch && (
                <motion.span
                  key={ch + i}
                  className="absolute"
                  initial={reduce ? false : { y: -rise, opacity: 0 }}
                  animate={{ y: 0, opacity: 1 }}
                  exit={{ opacity: 0, transition: { duration: 0.1 } }}
                  transition={{ type: "spring", duration: 0.35, bounce }}
                >
                  {mask ? "•" : ch}
                </motion.span>
              )}
            </AnimatePresence>
            {caret && active && !ch && (
              <motion.span
                className="absolute w-px"
                style={{ height: slotSize * 0.5, background: inkColor }}
                animate={reduce ? { opacity: 1 } : { opacity: [1, 0, 1] }}
                transition={{ duration: 1, repeat: Infinity, ease: "linear" }}
              />
            )}
          </motion.span>
        );
      })}
    </motion.label>
  );
}
```

---

# Orbit Knob

> A flickable rotary knob with a tracer tail in theme ink and a serif readout.

Install: `npx @modus-ui/cli add orbit-knob`

Drag up or down to turn it, flick to let it coast, or tap a point on the track to jump there. While it moves, a primary-coloured tail chases the head; arrow keys, Page Up/Down, Home and End work when focused.

## Installation

### CLI

```bash
npx @modus-ui/cli add orbit-knob
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/orbit-knob.tsx`.
3. Paste the code.

## Usage

```tsx
import { OrbitKnob } from "@/components/ui/orbit-knob";

export default function Example() {
  return <OrbitKnob />;
}
```

## Props

| Prop         | Type    | Default                    | Description |
| :----------- | :------ | :------------------------- | :---------- |
| value        | any     | -                          | -           |
| defaultValue | number  | `38`                       | -           |
| min          | number  | 0                          | -           |
| max          | number  | 100                        | -           |
| step         | number  | 1                          | -           |
| unit         | string  | "%"                        | -           |
| label        | string  | `"Gain"`                   | -           |
| accent       | string  | `"hsl(var(--primary))"`    | -           |
| ink          | string  | `"hsl(var(--foreground))"` | -           |
| size         | number  | 250                        | -           |
| sweep        | number  | `270`                      | -           |
| thickness    | number  | `3`                        | -           |
| speed        | number  | 25                         | -           |
| tapBounce    | number  | 0.2                        | -           |
| flickBounce  | number  | 0.1                        | -           |
| momentum     | number  | 1                          | -           |
| cometReach   | number  | 180                        | -           |
| cometWidth   | number  | 12                         | -           |
| disabled     | boolean | false                      | -           |
| onChange     | any     | -                          | -           |
| onChangeEnd  | any     | -                          | -           |

## Source

`components/ui/orbit-knob.tsx`

```tsx
"use client";
// Rotary knob: drag vertically or flick it; a tracer tail chases the head while it moves.

import { useEffect, useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
import {
  animate,
  useMotionValue,
  useMotionValueEvent,
  useReducedMotion,
  useVelocity,
} from "framer-motion";
import { cn } from "@/lib/utils";

const SEGMENTS = 14;

interface OrbitKnobProps {
  value?: number;
  defaultValue?: number;
  min?: number;
  max?: number;
  step?: number;
  unit?: string;
  label?: string;
  accent?: string;
  ink?: string;
  size?: number;
  /** Degrees of arc the knob travels from min to max. */
  sweep?: number;
  thickness?: number;
  /** Value units per 100px of vertical drag. */
  speed?: number;
  /** Spring bounce when clicking a point on the track. */
  tapBounce?: number;
  /** Spring bounce when a flick lands. */
  flickBounce?: number;
  /** How far a flick carries past the release point (0 = none). */
  momentum?: number;
  /** Longest tail, in degrees. */
  cometReach?: number;
  cometWidth?: number;
  disabled?: boolean;
  onChange?: (value: number) => void;
  onChangeEnd?: (value: number) => void;
  className?: string;
}

export function OrbitKnob({
  value,
  defaultValue = 38,
  min = 0,
  max = 100,
  step = 1,
  unit = "%",
  label = "Gain",
  accent = "hsl(var(--primary))",
  ink = "hsl(var(--foreground))",
  size = 250,
  sweep = 270,
  thickness = 3,
  speed = 25,
  tapBounce = 0.2,
  flickBounce = 0.1,
  momentum = 1,
  cometReach = 180,
  cometWidth = 12,
  disabled = false,
  onChange,
  onChangeEnd,
  className,
}: OrbitKnobProps) {
  const reduce = useReducedMotion();
  const pos = useMotionValue(value ?? defaultValue);
  const velocity = useVelocity(pos);
  const [shown, setShown] = useState(pos.get());
  const [tail, setTail] = useState(0);
  const drag = useRef<{ y: number; from: number; moved: boolean } | null>(null);

  const clamp = (v: number) => Math.min(max, Math.max(min, v));
  const snap = (v: number) => clamp(Math.round((v - min) / step) * step + min);
  const degPerUnit = sweep / (max - min);

  useEffect(() => {
    if (value !== undefined && !drag.current && !pos.isAnimating()) pos.set(value);
  }, [value, pos]);

  useMotionValueEvent(pos, "change", (v) => {
    setShown(v);
    const next = snap(v);
    if (next !== snap(shown)) onChange?.(next);
  });
  useMotionValueEvent(velocity, "change", (v) =>
    setTail(reduce ? 0 : Math.min(cometReach, Math.abs(v) * degPerUnit * 0.12)),
  );

  const settle = (target: number, bounce: number) =>
    animate(pos, snap(target), {
      type: "spring",
      bounce,
      duration: reduce ? 0 : 0.6,
      onComplete: () => {
        setTail(0);
        onChangeEnd?.(snap(target));
      },
    });

  const r = size / 2 - cometWidth;
  const c = size / 2;
  const start = 90 + (360 - sweep) / 2; // svg degrees, clockwise from +x
  const point = (deg: number, radius = r) => {
    const a = (deg * Math.PI) / 180;
    return [c + radius * Math.cos(a), c + radius * Math.sin(a)];
  };
  const arc = (from: number, to: number) => {
    const [x1, y1] = point(from);
    const [x2, y2] = point(to);
    return `M${x1} ${y1}A${r} ${r} 0 ${to - from > 180 ? 1 : 0} 1 ${x2} ${y2}`;
  };
  const head = start + (shown - min) * degPerUnit;
  const dir = Math.sign(velocity.get()) || 1;
  const [hx, hy] = point(head);

  const onDown = (e: PointerEvent<SVGSVGElement>) => {
    if (disabled) return;
    e.currentTarget.setPointerCapture(e.pointerId);
    pos.stop();
    drag.current = { y: e.clientY, from: pos.get(), moved: false };
  };
  const onMove = (e: PointerEvent) => {
    const d = drag.current;
    if (!d) return;
    const dy = d.y - e.clientY;
    if (Math.abs(dy) > 3) d.moved = true;
    if (d.moved) pos.set(clamp(d.from + (dy / 100) * speed));
  };
  const onUp = (e: PointerEvent<SVGSVGElement>) => {
    const d = drag.current;
    drag.current = null;
    if (!d) return;
    if (d.moved) return settle(pos.get() + velocity.get() * 0.15 * momentum, flickBounce);
    // A tap jumps to the touched point on the track.
    const box = e.currentTarget.getBoundingClientRect();
    const deg = (Math.atan2(e.clientY - box.top - c, e.clientX - box.left - c) * 180) / Math.PI;
    const along = (((deg - start) % 360) + 360) % 360;
    if (along <= sweep) settle(min + along / degPerUnit, tapBounce);
  };
  const onKey = (e: KeyboardEvent) => {
    const big = (max - min) / 10;
    const delta = {
      ArrowUp: step,
      ArrowRight: step,
      ArrowDown: -step,
      ArrowLeft: -step,
      PageUp: big,
      PageDown: -big,
      Home: -Infinity,
      End: Infinity,
    }[e.key];
    if (delta === undefined || disabled) return;
    e.preventDefault();
    settle(clamp(snap(pos.get()) + delta), tapBounce);
  };

  const current = snap(shown);

  return (
    <div
      role="slider"
      tabIndex={disabled ? -1 : 0}
      aria-label={label}
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={current}
      aria-valuetext={`${current}${unit}`}
      aria-disabled={disabled || undefined}
      onKeyDown={onKey}
      className={cn(
        "relative inline-grid select-none place-items-center rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring",
        disabled && "opacity-50",
        className,
      )}
      style={{ width: size, height: size }}
    >
      <svg
        width={size}
        height={size}
        className={cn(
          "absolute inset-0 touch-none",
          disabled ? "cursor-not-allowed" : "cursor-ns-resize",
        )}
        onPointerDown={onDown}
        onPointerMove={onMove}
        onPointerUp={onUp}
        onPointerCancel={onUp}
        fill="none"
        strokeLinecap="round"
      >
        <path
          d={arc(start, start + sweep)}
          stroke={ink}
          strokeOpacity={0.18}
          strokeWidth={thickness}
        />
        <path d={arc(start, Math.max(start + 0.01, head))} stroke={ink} strokeWidth={thickness} />
        {tail > 1 &&
          Array.from({ length: SEGMENTS }, (_, i) => {
            const a = head - (dir * (tail * i)) / SEGMENTS;
            const b = head - (dir * (tail * (i + 1))) / SEGMENTS;
            const [x1, y1] = point(a);
            const [x2, y2] = point(b);
            return (
              <line
                key={i}
                x1={x1}
                y1={y1}
                x2={x2}
                y2={y2}
                stroke={accent}
                strokeOpacity={1 - i / SEGMENTS}
                strokeWidth={cometWidth * (1 - i / SEGMENTS) + 1}
              />
            );
          })}
        <circle cx={hx} cy={hy} r={thickness + 3} fill={tail > 1 ? accent : ink} />
      </svg>
      <div className="pointer-events-none flex flex-col items-center" style={{ color: ink }}>
        <span className="font-serif tabular-nums leading-none" style={{ fontSize: size * 0.16 }}>
          {current}
          <span className="ml-0.5 align-top text-[0.4em] opacity-50">{unit}</span>
        </span>
        <span className="mt-2 font-mono text-[10px] uppercase tracking-[0.18em] opacity-60">
          {label}
        </span>
      </div>
    </div>
  );
}
```

---

# Coy Key

> A dashed mono key that edges away from the cursor until it relents.

Install: `npx @modus-ui/cli add coy-key`

Coy Key backs away from an approaching pointer inside its field, swapping its mono caption with every near miss, then gives in after a set patience. Ink and contrast follow the Modus theme.

## Installation

### CLI

```bash
npx @modus-ui/cli add coy-key
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/coy-key.tsx`.
3. Paste the code.

## Usage

```tsx
import { CoyKey } from "@/components/ui/coy-key";

export default function Example() {
  return <CoyKey />;
}
```

## Props

| Prop           | Type    | Default                                                            | Description                                                   |
| :------------- | :------ | :----------------------------------------------------------------- | :------------------------------------------------------------ |
| children       | any     | -                                                                  | Key label, or a render function receiving the dodge state.    |
| taunts         | any     | ["Reach for it", "Not quite", "Closer", "Patience", "Fine, yours"] | Labels shown in turn as the key dodges.                       |
| notice         | string  | ""                                                                 | Caption shown beneath the field.                              |
| inkColor       | string  | "hsl(var(--foreground))"                                           | Key fill colour.                                              |
| contrastColor  | string  | "hsl(var(--background))"                                           | Key text colour.                                              |
| fieldHeight    | number  | 240                                                                | Height of the play field in pixels.                           |
| reach          | number  | 72                                                                 | Distance the key flees per dodge, in pixels.                  |
| radius         | number  | 120                                                                | Pointer distance at which the key starts fleeing.             |
| falloff        | number  | 2                                                                  | How sharply the flee strength drops with distance.            |
| fleeDuration   | number  | 130                                                                | Duration of a dodge in milliseconds.                          |
| returnDuration | number  | 620                                                                | Duration of the return to rest in milliseconds.               |
| returnBounce   | number  | 0.1                                                                | Spring bounce on the return to rest.                          |
| axis           | string  | "both"                                                             | Axes the key may move along: "x", "y" or "both".              |
| wall           | string  | "clamp"                                                            | Edge behaviour: "clamp" stops at the edge, "bounce" rebounds. |
| patience       | number  | 4                                                                  | Dodges before the key gives in and can be caught.             |
| disabled       | boolean | false                                                              | Disables dodging and clicks.                                  |
| onDodge        | any     | -                                                                  | Called with the dodge count after each dodge.                 |
| onRelent       | any     | -                                                                  | Called when the key gives in.                                 |
| onCatch        | any     | -                                                                  | Called when the key is clicked.                               |
| style          | any     | -                                                                  | Inline styles for the root.                                   |

## Source

`components/ui/coy-key.tsx`

```tsx
"use client";
// A key that sidesteps the pointer inside its field, teasing as it goes, until its patience runs out.

import { useRef, useState, type CSSProperties, type PointerEvent, type ReactNode } from "react";
import { animate, motion, useMotionValue, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface CoyKeyState {
  dodges: number;
  relented: boolean;
}

const TAUNTS = ["Reach for it", "Not quite", "Closer", "Patience", "Fine, yours"];

export interface CoyKeyProps {
  children?: ReactNode | ((state: CoyKeyState) => ReactNode);
  taunts?: string[];
  notice?: string;
  inkColor?: string;
  contrastColor?: string;
  fieldHeight?: number;
  reach?: number;
  radius?: number;
  falloff?: number;
  fleeDuration?: number;
  returnDuration?: number;
  returnBounce?: number;
  axis?: "x" | "y" | "both";
  wall?: "clamp" | "bounce";
  patience?: number;
  disabled?: boolean;
  onDodge?: (dodges: number) => void;
  onRelent?: () => void;
  onCatch?: () => void;
  style?: CSSProperties;
  className?: string;
}

export function CoyKey({
  children,
  taunts = TAUNTS,
  notice = "",
  inkColor = "hsl(var(--foreground))",
  contrastColor = "hsl(var(--background))",
  fieldHeight = 240,
  reach = 72,
  radius = 120,
  falloff = 2,
  fleeDuration = 130,
  returnDuration = 620,
  returnBounce = 0.1,
  axis = "both",
  wall = "clamp",
  patience = 4,
  disabled = false,
  onDodge,
  onRelent,
  onCatch,
  style,
  className,
}: CoyKeyProps) {
  const reduce = useReducedMotion();
  const field = useRef<HTMLDivElement>(null);
  const key = useRef<HTMLButtonElement>(null);
  const x = useMotionValue(0);
  const y = useMotionValue(0);
  const busy = useRef(false);
  const [dodges, setDodges] = useState(0);
  const relented = dodges >= patience;

  const home = () => {
    const spring = {
      type: "spring" as const,
      duration: returnDuration / 1000,
      bounce: returnBounce,
    };
    animate(x, 0, spring);
    animate(y, 0, spring);
  };

  // Keeps an offset inside the field; "bounce" reflects off the wall instead of stopping at it.
  const fit = (v: number, limit: number) => {
    if (Math.abs(v) <= limit) return v;
    return wall === "bounce" ? Math.sign(v) * (2 * limit - Math.abs(v)) : Math.sign(v) * limit;
  };

  const onMove = (e: PointerEvent) => {
    if (disabled || relented || busy.current || !field.current || !key.current) return;
    const k = key.current.getBoundingClientRect();
    const dx = k.left + k.width / 2 - e.clientX;
    const dy = k.top + k.height / 2 - e.clientY;
    const d = Math.hypot(dx, dy);
    if (d > radius) return;
    const f = field.current.getBoundingClientRect();
    const strength = 0.4 + 0.6 * Math.pow(1 - d / radius, 1 / Math.max(falloff, 0.1));
    const len = d || 1;
    const nx = axis === "y" ? 0 : (dx || 1) / len;
    const ny = axis === "x" ? 0 : dy / len;
    const tx = fit(x.get() + nx * reach * strength, (f.width - k.width) / 2);
    const ty = fit(y.get() + ny * reach * strength, (f.height - k.height) / 2);
    const flee = { duration: reduce ? 0 : fleeDuration / 1000, ease: "easeOut" as const };
    busy.current = true;
    animate(x, tx, flee);
    animate(y, ty, { ...flee, onComplete: () => (busy.current = false) });
    const next = dodges + 1;
    setDodges(next);
    onDodge?.(next);
    if (next >= patience) {
      onRelent?.();
      home();
    }
  };

  const state = { dodges, relented };
  const caption = taunts[Math.min(dodges, taunts.length - 1)] ?? "";

  return (
    <div className={cn("w-full", className)} style={style}>
      <div
        ref={field}
        onPointerMove={onMove}
        onPointerLeave={() => !relented && home()}
        className="relative grid w-full touch-none place-items-center overflow-hidden"
        style={{ height: fieldHeight }}
      >
        <motion.button
          ref={key}
          type="button"
          disabled={disabled}
          onClick={() => onCatch?.()}
          style={{
            x,
            y,
            background: inkColor,
            color: contrastColor,
            outline: relented ? "none" : `1px dashed ${contrastColor}`,
            outlineOffset: -5,
          }}
          className="rounded-md px-6 py-3 font-mono text-xs uppercase tracking-[0.2em] transition-[outline-color] focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] disabled:opacity-50 motion-reduce:transition-none"
        >
          {typeof children === "function" ? children(state) : (children ?? caption)}
        </motion.button>
      </div>
      {notice && (
        <p className="mt-2 text-center font-mono text-[11px] uppercase tracking-[0.16em] text-[hsl(var(--muted-foreground))]">
          {notice}
        </p>
      )}
    </div>
  );
}
```

---

# Turn Leaf

> A paper leaf you drag, click or key-press to turn over, with a soft tilt and sheen.

Install: `npx @modus-ui/cli add turn-leaf`

Turn Leaf presents two faces, recto and verso, on a bordered card-coloured sheet. It tilts toward the pointer, turns with spring physics when dragged or pressed, and fades instead of rotating under reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add turn-leaf
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/turn-leaf.tsx`.
3. Paste the code.

## Usage

```tsx
import { TurnLeaf } from "@/components/ui/turn-leaf";

export default function Example() {
  return <TurnLeaf />;
}
```

## Props

| Prop           | Type    | Default                  | Description                                                      |
| :------------- | :------ | :----------------------- | :--------------------------------------------------------------- |
| front          | any     | null                     | Content of the front face.                                       |
| back           | any     | null                     | Content of the back face.                                        |
| flipped        | any     | -                        | Controlled flipped state.                                        |
| defaultFlipped | boolean | false                    | Initial flipped state when uncontrolled.                         |
| onFlipChange   | any     | -                        | Called with the new flipped state.                               |
| axis           | string  | "y"                      | Axis the leaf turns around: "x" or "y".                          |
| flipOnClick    | boolean | true                     | Turn the leaf on click.                                          |
| draggable      | boolean | true                     | Allow turning the leaf by dragging.                              |
| dragDistance   | number  | 0                        | Drag distance in pixels to commit a turn; 0 uses half the width. |
| tilt           | boolean | true                     | Tilt the leaf toward the pointer on hover.                       |
| tiltMax        | number  | 8                        | Maximum hover tilt in degrees.                                   |
| glare          | boolean | true                     | Show a moving glare highlight.                                   |
| glareOpacity   | number  | 0.22                     | Opacity of the glare highlight.                                  |
| hoverScale     | number  | 1.03                     | Scale applied on hover.                                          |
| perspective    | number  | 1100                     | CSS perspective in pixels.                                       |
| stiffness      | number  | 170                      | Spring stiffness of the turn.                                    |
| damping        | number  | 20                       | Spring damping of the turn.                                      |
| width          | number  | 280                      | Leaf width in pixels.                                            |
| height         | number  | 380                      | Leaf height in pixels.                                           |
| radius         | number  | 10                       | Corner radius in pixels.                                         |
| background     | string  | "hsl(var(--card))"       | Face background colour.                                          |
| color          | string  | "hsl(var(--foreground))" | Face text colour.                                                |
| shadow         | boolean | true                     | Show a drop shadow.                                              |
| shadowColor    | string  | "hsl(var(--foreground))" | Drop shadow colour.                                              |
| shadowOpacity  | number  | 0.3                      | Drop shadow opacity.                                             |
| disabled       | boolean | false                    | Disables turning and tilt.                                       |
| ariaLabel      | string  | "Turn leaf"              | Accessible label for the leaf.                                   |

## Source

`components/ui/turn-leaf.tsx`

```tsx
"use client";
// A two-sided sheet you turn by click, drag or key, with a pointer tilt and moving sheen.
import {
  useEffect,
  useRef,
  useState,
  type KeyboardEvent,
  type PointerEvent,
  type ReactNode,
} from "react";
import {
  animate,
  motion,
  useMotionTemplate,
  useMotionValue,
  useReducedMotion,
  useSpring,
} from "framer-motion";
import { cn } from "@/lib/utils";

interface TurnLeafProps {
  front?: ReactNode;
  back?: ReactNode;
  flipped?: boolean;
  defaultFlipped?: boolean;
  onFlipChange?: (flipped: boolean) => void;
  axis?: "x" | "y";
  flipOnClick?: boolean;
  draggable?: boolean;
  dragDistance?: number;
  tilt?: boolean;
  tiltMax?: number;
  glare?: boolean;
  glareOpacity?: number;
  hoverScale?: number;
  perspective?: number;
  stiffness?: number;
  damping?: number;
  width?: number;
  height?: number;
  radius?: number;
  background?: string;
  color?: string;
  shadow?: boolean;
  shadowColor?: string;
  shadowOpacity?: number;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

export function TurnLeaf({
  front = null,
  back = null,
  flipped,
  defaultFlipped = false,
  onFlipChange,
  axis = "y",
  flipOnClick = true,
  draggable = true,
  dragDistance = 0,
  tilt = true,
  tiltMax = 8,
  glare = true,
  glareOpacity = 0.22,
  hoverScale = 1.03,
  perspective = 1100,
  stiffness = 170,
  damping = 20,
  width = 280,
  height = 380,
  radius = 10,
  background = "hsl(var(--card))",
  color = "hsl(var(--foreground))",
  shadow = true,
  shadowColor = "hsl(var(--foreground))",
  shadowOpacity = 0.3,
  disabled = false,
  ariaLabel = "Turn leaf",
  className,
}: TurnLeafProps) {
  const prefersReduced = useReducedMotion();
  // Follow the setting only after hydration, so the first render matches the server's.
  const [reduce, setReduce] = useState(false);
  useEffect(() => setReduce(Boolean(prefersReduced)), [prefersReduced]);
  const [ownFlipped, setOwnFlipped] = useState(defaultFlipped);
  const isFlipped = flipped ?? ownFlipped;
  const turn = useMotionValue(isFlipped ? 180 : 0);
  const tiltX = useSpring(0, { stiffness: 200, damping: 20 });
  const tiltY = useSpring(0, { stiffness: 200, damping: 20 });
  const scale = useSpring(1, { stiffness: 260, damping: 22 });
  const glareX = useMotionValue(50);
  const glareY = useMotionValue(50);
  const glareAlpha = useSpring(0, { stiffness: 200, damping: 30 });
  const sheen = useMotionTemplate`radial-gradient(circle at ${glareX}% ${glareY}%, hsl(var(--background) / ${glareAlpha}), transparent 60%)`;
  const drag = useRef<{ start: number; moved: number } | null>(null);
  const along = axis === "y" ? width : height;
  const commitAt = dragDistance || along / 2;

  useEffect(() => {
    if (drag.current) return;
    const controls = animate(turn, isFlipped ? 180 : 0, { type: "spring", stiffness, damping });
    return () => controls.stop();
  }, [isFlipped, stiffness, damping, turn]);

  const set = (next: boolean) => {
    if (flipped === undefined) setOwnFlipped(next);
    onFlipChange?.(next);
  };

  const pos = (e: PointerEvent) => (axis === "y" ? e.clientX : -e.clientY);

  const onPointerDown = (e: PointerEvent<HTMLDivElement>) => {
    if (disabled) return;
    drag.current = { start: pos(e), moved: 0 };
    e.currentTarget.setPointerCapture(e.pointerId);
  };

  const onPointerMove = (e: PointerEvent<HTMLDivElement>) => {
    if (disabled) return;
    const box = e.currentTarget.getBoundingClientRect();
    const px = (e.clientX - box.left) / box.width;
    const py = (e.clientY - box.top) / box.height;
    if (tilt && !reduce) {
      tiltY.set((px - 0.5) * 2 * tiltMax);
      tiltX.set((0.5 - py) * 2 * tiltMax);
    }
    glareX.set(px * 100);
    glareY.set(py * 100);
    const d = drag.current;
    if (!d || !draggable || reduce) return;
    d.moved = pos(e) - d.start;
    const base = isFlipped ? 180 : 0;
    turn.set(base + Math.max(-180, Math.min(180, (d.moved / along) * 180)));
  };

  const onPointerUp = () => {
    const d = drag.current;
    drag.current = null;
    if (!d) return;
    if (Math.abs(d.moved) < 4) {
      if (flipOnClick) set(!isFlipped);
      return;
    }
    if (draggable && Math.abs(d.moved) >= commitAt) set(!isFlipped);
    else animate(turn, isFlipped ? 180 : 0, { type: "spring", stiffness, damping });
  };

  const onEnter = () => {
    if (disabled) return;
    if (!reduce) scale.set(hoverScale);
    if (glare) glareAlpha.set(glareOpacity);
  };

  const onLeave = () => {
    tiltX.set(0);
    tiltY.set(0);
    scale.set(1);
    glareAlpha.set(0);
  };

  const onKeyDown = (e: KeyboardEvent) => {
    if (disabled || (e.key !== "Enter" && e.key !== " ")) return;
    e.preventDefault();
    set(!isFlipped);
  };

  const rotateKey = axis === "y" ? "rotateY" : "rotateX";
  const face = cn(
    "absolute inset-0 overflow-hidden border border-border [backface-visibility:hidden]",
  );
  const faceStyle = { borderRadius: radius, background, color };

  return (
    <div className={cn("inline-block select-none", className)} style={{ perspective }}>
      <motion.div
        role="button"
        tabIndex={disabled ? -1 : 0}
        aria-label={ariaLabel}
        aria-pressed={isFlipped}
        aria-disabled={disabled}
        onPointerDown={onPointerDown}
        onPointerMove={onPointerMove}
        onPointerUp={onPointerUp}
        onPointerCancel={onPointerUp}
        onPointerEnter={onEnter}
        onPointerLeave={onLeave}
        onKeyDown={onKeyDown}
        className={cn(
          "relative touch-none outline-none [transform-style:preserve-3d] focus-visible:ring-2 focus-visible:ring-ring",
          disabled ? "cursor-not-allowed opacity-60" : "cursor-grab active:cursor-grabbing",
        )}
        style={{
          width,
          height,
          borderRadius: radius,
          rotateX: tiltX,
          rotateY: tiltY,
          scale,
          boxShadow: shadow
            ? `0 18px 40px -16px color-mix(in hsl, ${shadowColor} ${shadowOpacity * 100}%, transparent)`
            : undefined,
        }}
      >
        {reduce ? (
          <>
            <motion.div className={face} style={faceStyle} animate={{ opacity: isFlipped ? 0 : 1 }}>
              {front}
            </motion.div>
            <motion.div className={face} style={faceStyle} animate={{ opacity: isFlipped ? 1 : 0 }}>
              {back}
            </motion.div>
          </>
        ) : (
          <motion.div
            className="absolute inset-0 [transform-style:preserve-3d]"
            style={{ [rotateKey]: turn }}
          >
            <div className={face} style={faceStyle}>
              {front}
            </div>
            <div className={face} style={{ ...faceStyle, transform: `${rotateKey}(180deg)` }}>
              {back}
            </div>
          </motion.div>
        )}
        {glare && (
          <motion.div
            aria-hidden
            className="pointer-events-none absolute inset-0 mix-blend-soft-light"
            style={{ borderRadius: radius, background: sheen, transform: "translateZ(1px)" }}
          />
        )}
      </motion.div>
    </div>
  );
}
```

---

# Paper Stack

> A paper sleeve that fans out draggable note slips when opened.

Install: `npx @modus-ui/cli add paper-stack`

Paper Stack holds a set of short notes behind a serif-labelled sleeve. Hover or click to open it and the slips rise out as mono-set tags that can be dragged and picked. Every surface comes from the Modus theme tokens.

## Installation

### CLI

```bash
npx @modus-ui/cli add paper-stack
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/paper-stack.tsx`.
3. Paste the code.

## Usage

```tsx
import { PaperStack } from "@/components/ui/paper-stack";

export default function Example() {
  return <PaperStack />;
}
```

## Props

| Prop          | Type    | Default                  | Description                                       |
| :------------ | :------ | :----------------------- | :------------------------------------------------ |
| items         | any     | DEFAULT_ITEMS            | Papers in the stack, as strings or item objects.  |
| label         | string  | "Margin notes"           | Folder label.                                     |
| sublabel      | string  | ""                       | Secondary line under the label.                   |
| trigger       | string  | "hover"                  | Opens on "hover" or "click".                      |
| defaultOpen   | boolean | false                    | Start with the folder open.                       |
| closeOnSelect | boolean | true                     | Close the folder after a paper is chosen.         |
| physics       | boolean | true                     | Let open papers sway with the pointer.            |
| drift         | number  | 0.5                      | Strength of the idle drift of the papers.         |
| onSelect      | any     | -                        | Called with the chosen value and index.           |
| onOpenChange  | any     | -                        | Called with the new open state.                   |
| folderColor   | string  | "hsl(var(--muted))"      | Back panel colour.                                |
| frontColor    | string  | "hsl(var(--card))"       | Front flap colour.                                |
| paperColor    | string  | "hsl(var(--background))" | Paper colour inside the folder.                   |
| itemColor     | string  | "hsl(var(--foreground))" | Fanned paper colour.                              |
| itemTextColor | string  | "hsl(var(--background))" | Fanned paper text colour.                         |
| labelColor    | string  | "hsl(var(--foreground))" | Label text colour.                                |
| width         | number  | 200                      | Folder width in pixels.                           |
| height        | number  | 148                      | Folder height in pixels.                          |
| radius        | number  | 14                       | Corner radius in pixels.                          |
| spread        | number  | 180                      | Horizontal spread of the fanned papers in pixels. |
| lift          | number  | 26                       | How far papers rise when open, in pixels.         |
| tilt          | number  | 8                        | Maximum paper rotation in degrees.                |
| flapAngle     | number  | 34                       | Front flap angle when open, in degrees.           |
| restAngle     | number  | 16                       | Front flap angle at rest, in degrees.             |
| openDuration  | number  | 520                      | Open animation duration in milliseconds.          |
| stagger       | number  | 45                       | Delay between papers in milliseconds.             |
| bounce        | number  | 0.3                      | Spring bounce of the open animation.              |

## Source

`components/ui/paper-stack.tsx`

```tsx
"use client";
// A paper sleeve whose note slips fan out above it when opened.

import { useState, type PointerEvent } from "react";
import { motion, useMotionValue, useReducedMotion, useSpring, useTransform } from "framer-motion";
import { cn } from "@/lib/utils";

type PaperItem = string | { label: string; value?: string };

const DEFAULT_ITEMS: PaperItem[] = [
  "Set the serif larger",
  "Loosen the leading",
  "Proof the colophon",
  "Approve the cover",
];

export interface PaperStackProps {
  items?: PaperItem[];
  label?: string;
  sublabel?: string;
  trigger?: "hover" | "click";
  defaultOpen?: boolean;
  closeOnSelect?: boolean;
  physics?: boolean;
  drift?: number;
  onSelect?: (value: string, index: number) => void;
  onOpenChange?: (open: boolean) => void;
  folderColor?: string;
  frontColor?: string;
  paperColor?: string;
  itemColor?: string;
  itemTextColor?: string;
  labelColor?: string;
  width?: number;
  height?: number;
  radius?: number;
  spread?: number;
  lift?: number;
  tilt?: number;
  flapAngle?: number;
  restAngle?: number;
  openDuration?: number;
  stagger?: number;
  bounce?: number;
  className?: string;
}

export function PaperStack({
  items = DEFAULT_ITEMS,
  label = "Margin notes",
  sublabel = "",
  trigger = "hover",
  defaultOpen = false,
  closeOnSelect = true,
  physics = true,
  drift = 0.5,
  onSelect,
  onOpenChange,
  folderColor = "hsl(var(--muted))",
  frontColor = "hsl(var(--card))",
  paperColor = "hsl(var(--background))",
  itemColor = "hsl(var(--foreground))",
  itemTextColor = "hsl(var(--background))",
  labelColor = "hsl(var(--foreground))",
  width = 200,
  height = 148,
  radius = 14,
  spread = 180,
  lift = 26,
  tilt = 8,
  flapAngle = 34,
  restAngle = 16,
  openDuration = 520,
  stagger = 45,
  bounce = 0.3,
  className,
}: PaperStackProps) {
  const reduce = useReducedMotion();
  const [open, setOpenState] = useState(defaultOpen);
  const setOpen = (next: boolean) => {
    if (next === open) return;
    setOpenState(next);
    onOpenChange?.(next);
  };

  // Pointer offset from the centre, -1..1, drives the sway.
  const pointer = useMotionValue(0);
  const sway = useSpring(pointer, { stiffness: 120, damping: 14 });
  const swayDeg = useTransform(sway, (v) => v * tilt * 0.6);
  const swayX = useTransform(sway, (v) => v * 8);

  const track = (e: PointerEvent<HTMLDivElement>) => {
    if (!physics || reduce) return;
    const box = e.currentTarget.getBoundingClientRect();
    pointer.set(((e.clientX - box.left) / box.width) * 2 - 1);
  };

  const n = items.length;
  const spring = (i: number) =>
    reduce
      ? { duration: 0 }
      : {
          type: "spring" as const,
          duration: openDuration / 1000,
          bounce,
          delay: open ? (i * stagger) / 1000 : 0,
        };

  return (
    <div
      className={cn("relative select-none", className)}
      style={{ width, height, perspective: 800 }}
      onPointerEnter={() => trigger === "hover" && setOpen(true)}
      onPointerLeave={() => {
        pointer.set(0);
        if (trigger === "hover") setOpen(false);
      }}
      onPointerMove={track}
    >
      {/* Back panel with a tab. */}
      <div
        className="absolute inset-0"
        style={{ background: folderColor, borderRadius: radius, borderTopLeftRadius: 4 }}
      />
      <div
        className="absolute -top-3 left-0 h-5 w-2/5"
        style={{ background: folderColor, borderRadius: `${radius}px ${radius}px 0 0` }}
      />

      {/* Slips. Closed: tucked inside. Open: fanned out above. */}
      {items.map((item, i) => {
        const text = typeof item === "string" ? item : item.label;
        const value = typeof item === "string" ? item : (item.value ?? item.label);
        const t = n > 1 ? i / (n - 1) - 0.5 : 0;
        const bob = drift && open && !reduce ? [0, -3 * drift, 0] : 0;
        return (
          <motion.div
            key={text}
            className="absolute left-1/2 top-2"
            style={{ x: swayX, rotate: swayDeg, zIndex: 1 }}
            initial={false}
            animate={{ y: bob }}
            transition={{ duration: 2.4 + i * 0.3, repeat: Infinity, ease: "easeInOut" }}
          >
            <motion.button
              type="button"
              drag={open}
              dragSnapToOrigin
              dragElastic={0.4}
              whileDrag={{ scale: 1.06, zIndex: 10 }}
              tabIndex={open ? 0 : -1}
              aria-hidden={!open}
              onClick={() => {
                onSelect?.(value, i);
                if (closeOnSelect) setOpen(false);
              }}
              initial={false}
              animate={
                open
                  ? {
                      x: `calc(-50% + ${t * spread}px)`,
                      y: -lift - height * 0.55 - Math.abs(t) * 12 - (i % 2) * 30,
                      rotate: t * tilt * 2,
                      background: itemColor,
                      color: itemTextColor,
                    }
                  : {
                      x: `calc(-50% + ${t * 18}px)`,
                      y: i * 3,
                      rotate: t * 3,
                      background: paperColor,
                      color: paperColor,
                    }
              }
              transition={spring(i)}
              className="cursor-grab whitespace-nowrap rounded-[4px] px-2.5 py-1.5 font-mono text-[10px] uppercase tracking-[0.14em] shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] active:cursor-grabbing"
            >
              {text}
            </motion.button>
          </motion.div>
        );
      })}

      {/* Front flap hinged on its bottom edge. */}
      <motion.button
        type="button"
        aria-expanded={open}
        aria-label={label}
        onClick={() => setOpen(trigger === "hover" || !open)}
        className="absolute inset-x-0 bottom-0 flex h-[78%] flex-col items-start justify-end p-4 text-left shadow-[0_-1px_0_hsl(var(--border))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
        style={{
          background: frontColor,
          borderRadius: radius,
          transformOrigin: "50% 100%",
          zIndex: 2,
          color: labelColor,
        }}
        initial={false}
        animate={{ rotateX: -(open ? flapAngle : restAngle) }}
        transition={
          reduce ? { duration: 0 } : { type: "spring", duration: openDuration / 1000, bounce }
        }
      >
        <span className="font-serif text-lg leading-tight">{label}</span>
        {sublabel && (
          <span className="mt-0.5 font-mono text-[10px] uppercase tracking-[0.16em] opacity-60">
            {sublabel}
          </span>
        )}
      </motion.button>
    </div>
  );
}
```

---

# Cinder Trigger

> A commit button that burns down an undo window along its edge before it settles.

Install: `npx @modus-ui/cli add cinder-trigger`

Cinder Trigger commits an action and then offers a short recall window, drawn as a line burning along the bottom edge. Hover pauses it and Escape recalls. Label type is mono uppercase, colours come from primary tokens.

## Installation

### CLI

```bash
npx @modus-ui/cli add cinder-trigger
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/cinder-trigger.tsx`.
3. Paste the code.

## Usage

```tsx
import { CinderTrigger } from "@/components/ui/cinder-trigger";

export default function Example() {
  return <CinderTrigger />;
}
```

## Props

| Prop          | Type    | Default                          | Description                                                 |
| :------------ | :------ | :------------------------------- | :---------------------------------------------------------- |
| label         | string  | "Send proof"                     | Label before committing.                                    |
| undoLabel     | string  | "Recall"                         | Label while the undo window is open.                        |
| doneLabel     | string  | "Sent"                           | Label after the fuse burns out.                             |
| icon          | any     | -                                | Optional leading icon.                                      |
| color         | string  | "hsl(var(--primary-foreground))" | Text colour.                                                |
| background    | string  | "hsl(var(--primary))"            | Button background colour.                                   |
| fuseColor     | string  | "hsl(var(--primary-foreground))" | Colour of the burning fuse.                                 |
| size          | string  | "md"                             | Button size: "sm", "md" or "lg".                            |
| radius        | number  | 8                                | Corner radius in pixels.                                    |
| undoWindow    | number  | 4000                             | Time to undo in milliseconds.                               |
| fuse          | string  | "bottom"                         | Where the fuse burns: "outline", "top" or "bottom".         |
| fuseThickness | number  | 1.5                              | Fuse stroke width in pixels.                                |
| crossfadeMs   | number  | 200                              | Label crossfade duration in milliseconds.                   |
| commitOn      | string  | "press"                          | Fire onCommit on "press" or when the fuse ends ("fuseEnd"). |
| pauseOnHover  | boolean | true                             | Pause the fuse while hovered.                               |
| settle        | string  | "reset"                          | After finishing, "reset" to idle or "stay" done.            |
| disabled      | boolean | false                            | Disables the button.                                        |
| onCommit      | any     | -                                | Called when the action commits.                             |
| onUndo        | any     | -                                | Called when the action is undone.                           |
| onFuseEnd     | any     | -                                | Called when the fuse burns out.                             |
| onPhaseChange | any     | -                                | Called with each new phase.                                 |
| type          | string  | "button"                         | Native button type.                                         |

## Source

`components/ui/cinder-trigger.tsx`

```tsx
"use client";
// Commit button with a recall window drawn as a fuse that burns along its edge.

import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  animate,
  AnimatePresence,
  motion,
  useMotionValue,
  useReducedMotion,
  type AnimationPlaybackControls,
} from "framer-motion";
import { cn } from "@/lib/utils";

export type CinderPhase = "idle" | "armed" | "done";

const SIZES = { sm: "h-8 px-3 text-[11px]", md: "h-10 px-4 text-xs", lg: "h-12 px-6 text-sm" };

export interface CinderTriggerProps {
  label?: string;
  undoLabel?: string;
  doneLabel?: string;
  icon?: ReactNode;
  color?: string;
  background?: string;
  fuseColor?: string;
  size?: keyof typeof SIZES;
  radius?: number;
  undoWindow?: number;
  fuse?: "outline" | "top" | "bottom";
  fuseThickness?: number;
  crossfadeMs?: number;
  commitOn?: "press" | "fuseEnd";
  pauseOnHover?: boolean;
  settle?: "reset" | "stay";
  disabled?: boolean;
  onCommit?: () => void;
  onUndo?: () => void;
  onFuseEnd?: () => void;
  onPhaseChange?: (phase: CinderPhase) => void;
  type?: "button" | "submit" | "reset";
  className?: string;
}

export function CinderTrigger({
  label = "Send proof",
  undoLabel = "Recall",
  doneLabel = "Sent",
  icon,
  color = "hsl(var(--primary-foreground))",
  background = "hsl(var(--primary))",
  fuseColor = "hsl(var(--primary-foreground))",
  size = "md",
  radius = 8,
  undoWindow = 4000,
  fuse = "bottom",
  fuseThickness = 1.5,
  crossfadeMs = 200,
  commitOn = "press",
  pauseOnHover = true,
  settle = "reset",
  disabled = false,
  onCommit,
  onUndo,
  onFuseEnd,
  onPhaseChange,
  type = "button",
  className,
}: CinderTriggerProps) {
  const reduce = useReducedMotion();
  const [phase, setPhase] = useState<CinderPhase>("idle");
  const left = useMotionValue(1);
  const burn = useRef<AnimationPlaybackControls | null>(null);
  const latest = useRef({ onCommit, onFuseEnd, onPhaseChange, commitOn });
  latest.current = { onCommit, onFuseEnd, onPhaseChange, commitOn };

  const go = (next: CinderPhase) => {
    setPhase(next);
    latest.current.onPhaseChange?.(next);
  };

  useEffect(() => {
    if (phase !== "armed") return;
    left.set(1);
    burn.current = animate(left, 0, {
      duration: undoWindow / 1000,
      ease: "linear",
      onComplete: () => {
        const l = latest.current;
        l.onFuseEnd?.();
        if (l.commitOn === "fuseEnd") l.onCommit?.();
        setPhase("done");
        l.onPhaseChange?.("done");
      },
    });
    return () => burn.current?.stop();
  }, [phase, undoWindow, left]);

  useEffect(() => {
    if (phase !== "done" || settle !== "reset") return;
    const t = setTimeout(() => {
      setPhase("idle");
      latest.current.onPhaseChange?.("idle");
    }, 1400);
    return () => clearTimeout(t);
  }, [phase, settle]);

  const undo = () => {
    burn.current?.stop();
    onUndo?.();
    go("idle");
  };

  const press = () => {
    if (phase === "idle") {
      if (commitOn === "press") onCommit?.();
      go("armed");
    } else if (phase === "armed") undo();
  };

  const text = phase === "idle" ? label : phase === "armed" ? undoLabel : doneLabel;
  const fade = reduce ? 0 : crossfadeMs / 2000;

  return (
    <motion.button
      type={type}
      disabled={disabled || (phase === "done" && settle === "stay")}
      onClick={press}
      onKeyDown={(e) => {
        if (e.key === "Escape" && phase === "armed") undo();
      }}
      onHoverStart={() => pauseOnHover && burn.current?.pause()}
      onHoverEnd={() => pauseOnHover && phase === "armed" && burn.current?.play()}
      whileTap={reduce ? undefined : { scale: 0.97 }}
      aria-live="polite"
      className={cn(
        "relative inline-flex select-none items-center justify-center gap-2 overflow-hidden font-mono uppercase tracking-[0.16em] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 focus-visible:ring-offset-[hsl(var(--background))] disabled:opacity-60",
        SIZES[size],
        className,
      )}
      style={{ borderRadius: radius, background, color }}
    >
      {icon}
      <AnimatePresence mode="wait" initial={false}>
        <motion.span
          key={phase}
          initial={{ opacity: 0, y: reduce ? 0 : 4 }}
          animate={{ opacity: 1, y: 0 }}
          exit={{ opacity: 0, y: reduce ? 0 : -4 }}
          transition={{ duration: fade }}
        >
          {text}
        </motion.span>
      </AnimatePresence>
      {phase === "armed" &&
        (fuse === "outline" ? (
          <svg
            className="pointer-events-none absolute overflow-visible"
            style={{
              inset: fuseThickness / 2,
              width: `calc(100% - ${fuseThickness}px)`,
              height: `calc(100% - ${fuseThickness}px)`,
            }}
            aria-hidden
          >
            <motion.rect
              width="100%"
              height="100%"
              rx={Math.max(0, radius - fuseThickness / 2)}
              fill="none"
              stroke={fuseColor}
              strokeWidth={fuseThickness}
              style={{ pathLength: left }}
            />
          </svg>
        ) : (
          <motion.span
            aria-hidden
            className={cn(
              "pointer-events-none absolute inset-x-0 origin-left",
              fuse === "top" ? "top-0" : "bottom-0",
            )}
            style={{ height: fuseThickness, background: fuseColor, scaleX: left }}
          />
        ))}
    </motion.button>
  );
}
```

---

# Tray Picker

> A compact select whose tray slides open from its chip with serif options.

Install: `npx @modus-ui/cli add tray-picker`

Tray Picker expands a single chip into a tray of options, keeps full keyboard support and sets each option in the Modus serif. Surfaces and highlights follow the active palette.

## Installation

### CLI

```bash
npx @modus-ui/cli add tray-picker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tray-picker.tsx`.
3. Paste the code.

## Usage

```tsx
import { TrayPicker } from "@/components/ui/tray-picker";

export default function Example() {
  return <TrayPicker />;
}
```

## Props

| Prop             | Type    | Default                  | Description                                    |
| :--------------- | :------ | :----------------------- | :--------------------------------------------- |
| options          | any     | DEFAULT_OPTIONS          | Options, as strings or option objects.         |
| value            | any     | -                        | Controlled selected value.                     |
| defaultValue     | any     | -                        | Initial value when uncontrolled.               |
| onChange         | any     | -                        | Called with the new value and option.          |
| placeholder      | string  | "Choose a face…"         | Text shown when nothing is selected.           |
| showTags         | boolean | true                     | Show option tags in the menu.                  |
| accentColor      | string  | "hsl(var(--foreground))" | Accent colour for the selection.               |
| surfaceColor     | string  | "hsl(var(--card))"       | Trigger and menu surface colour.               |
| highlightColor   | string  | "hsl(var(--muted))"      | Colour of the gliding highlight.               |
| textColor        | string  | "hsl(var(--foreground))" | Text colour.                                   |
| size             | string  | "md"                     | Trigger size: "sm", "md" or "lg".              |
| radius           | number  | 10                       | Corner radius in pixels.                       |
| menuWidth        | number  | 176                      | Menu width in pixels.                          |
| placement        | string  | "bottom"                 | Open the menu "bottom" or "top".               |
| align            | string  | "left"                   | Align the menu "left" or "right".              |
| popDuration      | number  | 180                      | Menu open duration in milliseconds.            |
| glideDuration    | number  | 220                      | Highlight glide duration in milliseconds.      |
| rememberPosition | boolean | true                     | Keep the highlight on the last hovered option. |
| disabled         | boolean | false                    | Disables the picker.                           |
| ariaLabel        | string  | "Choose"                 | Accessible label for the trigger.              |

## Source

`components/ui/tray-picker.tsx`

```tsx
"use client";
// A chip that opens a tray of serif options with a gliding highlight and full keyboard control.
import { useEffect, useId, useRef, useState, type KeyboardEvent } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { HugeiconsIcon } from "@hugeicons/react";
import { ArrowDown01Icon, Tick02Icon } from "@hugeicons/core-free-icons";
import { cn } from "@/lib/utils";

export interface TrayOption {
  value: string;
  label?: string;
  tag?: string;
}

interface TrayPickerProps {
  options?: (string | TrayOption)[];
  value?: string;
  defaultValue?: string;
  onChange?: (value: string, option: TrayOption) => void;
  placeholder?: string;
  showTags?: boolean;
  accentColor?: string;
  surfaceColor?: string;
  highlightColor?: string;
  textColor?: string;
  size?: "sm" | "md" | "lg";
  radius?: number;
  menuWidth?: number;
  placement?: "bottom" | "top";
  align?: "left" | "right";
  popDuration?: number;
  glideDuration?: number;
  rememberPosition?: boolean;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

const DEFAULT_OPTIONS: TrayOption[] = [
  { value: "garamond", label: "Garamond", tag: "Old style" },
  { value: "bodoni", label: "Bodoni", tag: "Didone" },
  { value: "caslon", label: "Caslon", tag: "Old style" },
  { value: "baskerville", label: "Baskerville", tag: "Transitional" },
  { value: "clarendon", label: "Clarendon", tag: "Slab" },
];

const SIZES = { sm: "h-8 px-3 text-xs", md: "h-9 px-3.5 text-sm", lg: "h-11 px-4 text-base" };

export function TrayPicker({
  options = DEFAULT_OPTIONS,
  value,
  defaultValue,
  onChange,
  placeholder = "Choose a face…",
  showTags = true,
  accentColor = "hsl(var(--foreground))",
  surfaceColor = "hsl(var(--card))",
  highlightColor = "hsl(var(--muted))",
  textColor = "hsl(var(--foreground))",
  size = "md",
  radius = 10,
  menuWidth = 176,
  placement = "bottom",
  align = "left",
  popDuration = 180,
  glideDuration = 220,
  rememberPosition = true,
  disabled = false,
  ariaLabel = "Choose",
  className,
}: TrayPickerProps) {
  const reduce = useReducedMotion();
  const id = useId();
  const items = options.map((o) => (typeof o === "string" ? { value: o } : o));
  const [own, setOwn] = useState(defaultValue);
  const selected = value ?? own;
  const [open, setOpen] = useState(false);
  const [active, setActive] = useState(-1);
  const root = useRef<HTMLDivElement>(null);
  const trigger = useRef<HTMLButtonElement>(null);
  const current = items.find((o) => o.value === selected);

  useEffect(() => {
    if (!open) return;
    root.current?.querySelector<HTMLElement>("[role=listbox]")?.focus();
    const away = (e: PointerEvent) => {
      if (!root.current?.contains(e.target as Node)) setOpen(false);
    };
    document.addEventListener("pointerdown", away);
    return () => document.removeEventListener("pointerdown", away);
  }, [open]);

  const show = () => {
    if (disabled) return;
    setActive(
      Math.max(
        0,
        items.findIndex((o) => o.value === selected),
      ),
    );
    setOpen(true);
  };

  const close = () => {
    setOpen(false);
    trigger.current?.focus();
  };

  const choose = (i: number) => {
    const option = items[i];
    if (!option) return;
    if (value === undefined) setOwn(option.value);
    onChange?.(option.value, option);
    close();
  };

  const onTriggerKey = (e: KeyboardEvent) => {
    if (["ArrowDown", "ArrowUp", "Enter", " "].includes(e.key)) {
      e.preventDefault();
      show();
    }
  };

  const onListKey = (e: KeyboardEvent) => {
    const last = items.length - 1;
    const moves: Record<string, number> = {
      ArrowDown: Math.min(last, active + 1),
      ArrowUp: Math.max(0, active - 1),
      Home: 0,
      End: last,
    };
    if (e.key in moves) setActive(moves[e.key]);
    else if (e.key === "Enter" || e.key === " ") choose(active);
    else if (e.key === "Escape" || e.key === "Tab") close();
    else return;
    e.preventDefault();
  };

  const dir = placement === "top" ? 1 : -1;

  return (
    <div ref={root} className={cn("relative inline-block", className)} style={{ color: textColor }}>
      <button
        ref={trigger}
        type="button"
        disabled={disabled}
        aria-label={ariaLabel}
        aria-haspopup="listbox"
        aria-expanded={open}
        aria-controls={`${id}-list`}
        onClick={() => (open ? close() : show())}
        onKeyDown={onTriggerKey}
        className={cn(
          "inline-flex items-center gap-2 border border-border font-sans shadow-sm outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
          SIZES[size],
        )}
        style={{ borderRadius: radius, background: surfaceColor }}
      >
        <span className={cn(!current && "opacity-60", current && "font-serif")}>
          {current ? (current.label ?? current.value) : placeholder}
        </span>
        <motion.span
          animate={{ rotate: open ? 180 : 0 }}
          transition={{ duration: reduce ? 0 : 0.2 }}
          className="opacity-60"
        >
          <HugeiconsIcon icon={ArrowDown01Icon} size={14} />
        </motion.span>
      </button>
      <AnimatePresence>
        {open && (
          <motion.ul
            id={`${id}-list`}
            role="listbox"
            tabIndex={-1}
            aria-label={ariaLabel}
            aria-activedescendant={active >= 0 ? `${id}-${active}` : undefined}
            onKeyDown={onListKey}
            onPointerLeave={() => !rememberPosition && setActive(-1)}
            initial={{ opacity: 0, y: reduce ? 0 : dir * 6, scaleY: reduce ? 1 : 0.85 }}
            animate={{ opacity: 1, y: 0, scaleY: 1 }}
            exit={{ opacity: 0, y: reduce ? 0 : dir * 4, scaleY: reduce ? 1 : 0.92 }}
            transition={{ duration: reduce ? 0 : popDuration / 1000, ease: [0.2, 0.8, 0.2, 1] }}
            className={cn(
              "absolute z-50 border border-border p-1 shadow-lg outline-none",
              placement === "top" ? "bottom-full mb-2 origin-bottom" : "top-full mt-2 origin-top",
              align === "right" ? "right-0" : "left-0",
            )}
            style={{ width: menuWidth, borderRadius: radius, background: surfaceColor }}
          >
            {items.map((o, i) => (
              <li
                key={o.value}
                id={`${id}-${i}`}
                role="option"
                aria-selected={o.value === selected}
                onPointerEnter={() => setActive(i)}
                onClick={() => choose(i)}
                className="relative flex cursor-pointer items-center justify-between gap-2 px-2.5 py-1.5"
              >
                {active === i && (
                  <motion.span
                    layoutId={`${id}-glide`}
                    className="absolute inset-0"
                    style={{ background: highlightColor, borderRadius: Math.max(0, radius - 4) }}
                    transition={{
                      duration: reduce ? 0 : glideDuration / 1000,
                      ease: [0.2, 0.8, 0.2, 1],
                    }}
                  />
                )}
                <span className="relative font-serif text-base leading-tight">
                  {o.label ?? o.value}
                </span>
                <span className="relative flex items-center gap-1.5">
                  {showTags && o.tag && (
                    <span className="font-mono text-[9px] uppercase tracking-[0.14em] opacity-55">
                      {o.tag}
                    </span>
                  )}
                  {o.value === selected && (
                    <HugeiconsIcon icon={Tick02Icon} size={13} color={accentColor} />
                  )}
                </span>
              </li>
            ))}
          </motion.ul>
        )}
      </AnimatePresence>
    </div>
  );
}
```

---

# Steady Press

> A press-and-hold confirm button that fills from below with a wavy crest.

Install: `npx @modus-ui/cli add steady-press`

Steady Press guards a deliberate action: hold it and a primary tint rises with a wave on its crest until the action completes. Letting go early drains it. Mono uppercase label on a secondary surface.

## Installation

### CLI

```bash
npx @modus-ui/cli add steady-press
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/steady-press.tsx`.
3. Paste the code.

## Usage

```tsx
import { SteadyPress } from "@/components/ui/steady-press";

export default function Example() {
  return <SteadyPress />;
}
```

## Props

| Prop            | Type    | Default                            | Description                                               |
| :-------------- | :------ | :--------------------------------- | :-------------------------------------------------------- |
| children        | string  | "Hold to publish"                  | Button label.                                             |
| doneLabel       | string  | "Published"                        | Label shown after a completed hold.                       |
| icon            | any     | null                               | Optional leading icon.                                    |
| doneIcon        | any     | null                               | Icon shown after a completed hold.                        |
| backgroundColor | string  | "hsl(var(--secondary))"            | Button background colour.                                 |
| fillColor       | string  | "hsl(var(--primary))"              | Colour of the rising fill.                                |
| textColor       | string  | "hsl(var(--secondary-foreground))" | Label colour over the background.                         |
| fillTextColor   | string  | "hsl(var(--primary-foreground))"   | Label colour over the fill.                               |
| size            | string  | "md"                               | Button size: "sm", "md" or "lg".                          |
| radius          | number  | 14                                 | Corner radius in pixels.                                  |
| fillDirection   | string  | "up"                               | Fill direction: "up" or "right".                          |
| holdTime        | number  | 2000                               | Hold duration to complete, in milliseconds.               |
| releaseTime     | number  | 200                                | Drain duration after an early release, in milliseconds.   |
| pressScale      | number  | 0.97                               | Scale applied while pressed.                              |
| wave            | boolean | true                               | Draw a wave on the fill edge.                             |
| waveAmplitude   | number  | 6                                  | Wave height in pixels.                                    |
| glow            | boolean | true                               | Glow when the hold completes.                             |
| resetAfter      | number  | 1200                               | Delay before resetting after completion, in milliseconds. |
| disabled        | boolean | false                              | Disables the button.                                      |
| onHold          | any     | -                                  | Called when the hold completes.                           |
| onTap           | any     | -                                  | Called on a short press.                                  |

## Source

`components/ui/steady-press.tsx`

```tsx
"use client";
// Press-and-hold confirm button: a tint rises (with a wavy crest) while held, and drains if released early.

import { useEffect, useRef, useState } from "react";
import {
  animate,
  motion,
  useMotionValue,
  useMotionTemplate,
  useReducedMotion,
  useTransform,
  type AnimationPlaybackControls,
} from "framer-motion";
import { cn } from "@/lib/utils";

interface SteadyPressProps {
  children?: string;
  doneLabel?: string;
  icon?: React.ReactNode;
  doneIcon?: React.ReactNode;
  backgroundColor?: string;
  fillColor?: string;
  textColor?: string;
  fillTextColor?: string;
  size?: "sm" | "md" | "lg";
  radius?: number;
  fillDirection?: "up" | "right";
  holdTime?: number;
  releaseTime?: number;
  pressScale?: number;
  wave?: boolean;
  waveAmplitude?: number;
  glow?: boolean;
  resetAfter?: number;
  disabled?: boolean;
  onHold?: () => void;
  onTap?: () => void;
  className?: string;
}

const SIZES = { sm: "h-9 px-4 text-[10px]", md: "h-11 px-6 text-xs", lg: "h-14 px-8 text-sm" };
const TAP_MS = 250;

export function SteadyPress({
  children = "Hold to publish",
  doneLabel = "Published",
  icon = null,
  doneIcon = null,
  backgroundColor = "hsl(var(--secondary))",
  fillColor = "hsl(var(--primary))",
  textColor = "hsl(var(--secondary-foreground))",
  fillTextColor = "hsl(var(--primary-foreground))",
  size = "md",
  radius = 14,
  fillDirection = "up",
  holdTime = 2000,
  releaseTime = 200,
  pressScale = 0.97,
  wave = true,
  waveAmplitude = 6,
  glow = true,
  resetAfter = 1200,
  disabled = false,
  onHold,
  onTap,
  className,
}: SteadyPressProps) {
  const prefersReduced = useReducedMotion();
  // Follow the setting only after hydration, so the first render matches the server's.
  const [reduced, setReduced] = useState(false);
  useEffect(() => setReduced(Boolean(prefersReduced)), [prefersReduced]);
  const level = useMotionValue(0); // 0–100
  const run = useRef<AnimationPlaybackControls | null>(null);
  const pressedAt = useRef(0);
  const [pressed, setPressed] = useState(false);
  const [done, setDone] = useState(false);
  const up = fillDirection === "up";
  const hidden = useTransform(level, (v) => 100 - v);
  const clip = useMotionTemplate`inset(${up ? hidden : 0}% ${up ? 0 : hidden}% 0% 0%)`;
  const crest = useTransform(level, (v) => `${v}%`);

  useEffect(() => {
    if (!done) return;
    const t = setTimeout(() => {
      setDone(false);
      run.current = animate(level, 0, { duration: reduced ? 0 : 0.4 });
    }, resetAfter);
    return () => clearTimeout(t);
  }, [done, resetAfter, level, reduced]);

  const press = () => {
    if (disabled || done) return;
    pressedAt.current = Date.now();
    setPressed(true);
    run.current?.stop();
    run.current = animate(level, 100, {
      duration: (holdTime / 1000) * (1 - level.get() / 100),
      ease: "linear",
      onComplete: () => {
        setPressed(false);
        setDone(true);
        onHold?.();
      },
    });
  };
  const release = () => {
    if (!pressed) return;
    setPressed(false);
    if (Date.now() - pressedAt.current < TAP_MS) onTap?.();
    run.current?.stop();
    run.current = animate(level, 0, { duration: releaseTime / 1000, ease: "easeOut" });
  };

  const label = (
    <span className="inline-flex items-center gap-2">
      {done ? doneIcon : icon}
      {done ? doneLabel : children}
    </span>
  );
  const amp = wave && !reduced ? waveAmplitude : 0;

  return (
    <motion.button
      type="button"
      disabled={disabled}
      aria-label={done ? doneLabel : children}
      onPointerDown={press}
      onPointerUp={release}
      onPointerLeave={release}
      onKeyDown={(e) =>
        (e.key === " " || e.key === "Enter") && !e.repeat && (e.preventDefault(), press())
      }
      onKeyUp={(e) => (e.key === " " || e.key === "Enter") && release()}
      animate={{
        scale: pressed && !reduced ? pressScale : 1,
        boxShadow: done && glow ? `0 0 24px -4px ${fillColor}` : "0 0 0 0 transparent",
      }}
      className={cn(
        "relative select-none overflow-hidden font-mono uppercase tracking-[0.16em] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] disabled:opacity-50",
        SIZES[size],
        className,
      )}
      style={{
        background: backgroundColor,
        color: textColor,
        borderRadius: radius,
        touchAction: "none",
      }}
    >
      <motion.span
        aria-hidden
        className="absolute"
        style={
          up
            ? { left: 0, right: 0, bottom: 0, height: crest, background: fillColor }
            : { top: 0, bottom: 0, left: 0, width: crest, background: fillColor }
        }
      >
        {amp > 0 && (
          <motion.svg
            className="absolute"
            viewBox={up ? "0 0 40 10" : "0 0 10 40"}
            preserveAspectRatio="none"
            style={
              up
                ? { bottom: "100%", left: 0, width: "200%", height: amp }
                : { left: "100%", top: 0, height: "200%", width: amp }
            }
            animate={up ? { x: ["0%", "-50%"] } : { y: ["0%", "-50%"] }}
            transition={{ duration: 1.2, ease: "linear", repeat: Infinity }}
          >
            <path
              d={up ? "M0 10V5Q5 0 10 5T20 5T30 5T40 5V10Z" : "M0 0H5Q10 5 5 10T5 20T5 30T5 40H0Z"}
              fill={fillColor}
            />
          </motion.svg>
        )}
      </motion.span>
      <span className="relative">{label}</span>
      <motion.span
        aria-hidden
        className="absolute inset-0 flex items-center justify-center"
        style={{ color: fillTextColor, clipPath: clip }}
      >
        {label}
      </motion.span>
    </motion.button>
  );
}
```

---

# Bloom Choice

> A row of mono chips where the chosen one swells with a springy pop.

Install: `npx @modus-ui/cli add bloom-choice`

Bloom Choice is a single-choice radio group of mono uppercase chips. Picking one makes it swell softly into the primary colour while its neighbours yield. Arrow keys, Home and End all work.

## Installation

### CLI

```bash
npx @modus-ui/cli add bloom-choice
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/bloom-choice.tsx`.
3. Paste the code.

## Usage

```tsx
import { BloomChoice } from "@/components/ui/bloom-choice";

export default function Example() {
  return <BloomChoice />;
}
```

## Props

| Prop            | Type    | Default                          | Description                                        |
| :-------------- | :------ | :------------------------------- | :------------------------------------------------- |
| items           | any     | DEFAULT_ITEMS                    | Choices, as strings or item objects.               |
| value           | any     | -                                | Controlled selected value.                         |
| defaultValue    | any     | -                                | Initial value when uncontrolled.                   |
| onChange        | any     | -                                | Called with the new value and index.               |
| chipColor       | string  | "hsl(var(--muted))"              | Chip background colour.                            |
| activeColor     | string  | "hsl(var(--primary))"            | Selected chip colour.                              |
| textColor       | string  | "hsl(var(--muted-foreground))"   | Chip text colour.                                  |
| activeTextColor | string  | "hsl(var(--primary-foreground))" | Selected chip text colour.                         |
| size            | string  | "md"                             | Chip size: "sm", "md" or "lg".                     |
| gap             | number  | 8                                | Space between chips in pixels.                     |
| radius          | number  | 18                               | Chip corner radius in pixels.                      |
| swell           | number  | 0.2                              | How much the chosen chip grows.                    |
| barge           | number  | 6                                | How far neighbours are pushed aside, in pixels.    |
| shrink          | number  | 0.05                             | How much neighbours shrink.                        |
| jelly           | number  | 1                                | Strength of the wobble.                            |
| bounce          | number  | 0.25                             | Spring bounce.                                     |
| stagger         | number  | 22                               | Delay between neighbour reactions in milliseconds. |
| stiffness       | number  | 580                              | Spring stiffness.                                  |
| disabled        | boolean | false                            | Disables selection.                                |
| ariaLabel       | string  | "Options"                        | Accessible label for the group.                    |

## Source

`components/ui/bloom-choice.tsx`

```tsx
"use client";
// Single-choice chip row: the picked chip swells on a spring and its neighbours lean away.

import { useRef, useState, type KeyboardEvent } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export type BloomItem = string | { value: string; label?: string; disabled?: boolean };

const DEFAULT_ITEMS: BloomItem[] = ["Draft", "Proof", "Press", "Print"];

const PAD = { sm: "h-7 px-3 text-[10px]", md: "h-9 px-4 text-xs", lg: "h-11 px-5 text-sm" };

export interface BloomChoiceProps {
  items?: BloomItem[];
  value?: string;
  defaultValue?: string;
  onChange?: (value: string, index: number) => void;
  chipColor?: string;
  activeColor?: string;
  textColor?: string;
  activeTextColor?: string;
  size?: keyof typeof PAD;
  gap?: number;
  radius?: number;
  swell?: number;
  barge?: number;
  shrink?: number;
  jelly?: number;
  bounce?: number;
  stagger?: number;
  stiffness?: number;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

export function BloomChoice({
  items = DEFAULT_ITEMS,
  value,
  defaultValue,
  onChange,
  chipColor = "hsl(var(--muted))",
  activeColor = "hsl(var(--primary))",
  textColor = "hsl(var(--muted-foreground))",
  activeTextColor = "hsl(var(--primary-foreground))",
  size = "md",
  gap = 8,
  radius = 18,
  swell = 0.2,
  barge = 6,
  shrink = 0.05,
  jelly = 1,
  bounce = 0.25,
  stagger = 22,
  stiffness = 580,
  disabled = false,
  ariaLabel = "Options",
  className,
}: BloomChoiceProps) {
  const reduce = useReducedMotion();
  const options = items.map((it) => (typeof it === "string" ? { value: it } : it));
  const [inner, setInner] = useState(defaultValue);
  const current = value ?? inner;
  const active = options.findIndex((o) => o.value === current);
  const refs = useRef<(HTMLButtonElement | null)[]>([]);
  // Critical damping is 2√k; bounce (scaled by jelly) eases off from it.
  const damping = 2 * Math.sqrt(stiffness) * Math.max(0.08, 1 - bounce * jelly);

  const pick = (i: number) => {
    const o = options[i];
    if (disabled || !o || o.disabled) return;
    if (value === undefined) setInner(o.value);
    onChange?.(o.value, i);
    refs.current[i]?.focus();
  };

  const onKey = (e: KeyboardEvent) => {
    const from = active < 0 ? 0 : active;
    const n = options.length;
    const to =
      e.key === "ArrowRight" || e.key === "ArrowDown"
        ? (from + 1) % n
        : e.key === "ArrowLeft" || e.key === "ArrowUp"
          ? (from - 1 + n) % n
          : e.key === "Home"
            ? 0
            : e.key === "End"
              ? n - 1
              : -1;
    if (to < 0) return;
    e.preventDefault();
    pick(to);
  };

  return (
    <div
      role="radiogroup"
      aria-label={ariaLabel}
      aria-disabled={disabled || undefined}
      onKeyDown={onKey}
      className={cn("inline-flex flex-wrap items-center", disabled && "opacity-50", className)}
      style={{ gap }}
    >
      {options.map((o, i) => {
        const on = i === active;
        const d = active < 0 ? 0 : i - active;
        return (
          <motion.button
            key={o.value}
            ref={(el) => {
              refs.current[i] = el;
            }}
            type="button"
            role="radio"
            aria-checked={on}
            tabIndex={on || (active < 0 && i === 0) ? 0 : -1}
            disabled={disabled || o.disabled}
            onClick={() => pick(i)}
            className={cn(
              "relative shrink-0 font-mono uppercase tracking-[0.14em] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 focus-visible:ring-offset-[hsl(var(--background))]",
              PAD[size],
            )}
            style={{ borderRadius: radius }}
            animate={{
              scale: on ? 1 + swell : d === 0 ? 1 : 1 - shrink / Math.abs(d),
              x: d === 0 ? 0 : (Math.sign(d) * barge) / Math.abs(d),
              backgroundColor: on ? activeColor : chipColor,
              color: on ? activeTextColor : textColor,
            }}
            transition={
              reduce
                ? { duration: 0 }
                : {
                    type: "spring",
                    stiffness,
                    damping,
                    delay: (Math.abs(d) * stagger) / 1000,
                    backgroundColor: { duration: 0.18 },
                    color: { duration: 0.18 },
                  }
            }
          >
            {o.label ?? o.value}
          </motion.button>
        );
      })}
    </div>
  );
}
```

---

# Tile Wait

> A dot-grid progress indicator with a ticking timer and a mono caption.

Install: `npx @modus-ui/cli add tile-wait`

Tiles ripple outward from the centre while work runs, then resolve into a check or a cross with the elapsed time. Colours follow `currentColor` and the Modus theme tokens.

## Installation

### CLI

```bash
npx @modus-ui/cli add tile-wait
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tile-wait.tsx`.
3. Paste the code.

## Usage

```tsx
import { TileWait } from "@/components/ui/tile-wait";

export default function Example() {
  return <TileWait />;
}
```

## Props

| Prop        | Type    | Default                   | Description |
| :---------- | :------ | :------------------------ | :---------- |
| label       | string  | "Composing"               | -           |
| doneLabel   | string  | "Done in"                 | -           |
| errorLabel  | string  | "Failed after"            | -           |
| status      | string  | "working"                 | -           |
| pattern     | string  | "ripple"                  | -           |
| grid        | number  | 3                         | -           |
| shape       | string  | "square"                  | -           |
| color       | string  | "currentColor"            | -           |
| doneColor   | string  | "hsl(var(--primary))"     | -           |
| errorColor  | string  | "hsl(var(--destructive))" | -           |
| cellSize    | number  | 5                         | -           |
| gap         | number  | 3                         | -           |
| fontSize    | number  | 12                        | -           |
| step        | number  | 90                        | -           |
| idleOpacity | number  | 0.15                      | -           |
| glow        | boolean | false                     | -           |
| glowColor   | string  | ""                        | -           |
| showTimer   | boolean | true                      | -           |
| elapsed     | any     | -                         | -           |
| style       | any     | -                         | -           |

## Source

`components/ui/tile-wait.tsx`

```tsx
"use client";
// A small tile grid that pulses while work runs, then settles into a check or cross.
import { useEffect, useRef, useState, type CSSProperties } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Status = "working" | "done" | "error";
type Pattern = "ripple" | "sweep" | "scatter";

interface TileWaitProps {
  label?: string;
  doneLabel?: string;
  errorLabel?: string;
  status?: Status;
  pattern?: Pattern;
  grid?: number;
  shape?: "square" | "circle";
  color?: string;
  doneColor?: string;
  errorColor?: string;
  cellSize?: number;
  gap?: number;
  fontSize?: number;
  step?: number;
  idleOpacity?: number;
  glow?: boolean;
  glowColor?: string;
  showTimer?: boolean;
  /** Elapsed seconds; when set it replaces the internal timer. */
  elapsed?: number;
  style?: CSSProperties;
  className?: string;
}

/** Which "phase" each tile belongs to; the lit phase advances every tick. */
function phaseOf(pattern: Pattern, row: number, col: number, grid: number) {
  const mid = (grid - 1) / 2;
  if (pattern === "sweep") return row + col;
  if (pattern === "scatter") return (row * 7 + col * 13) % (grid + 1);
  return Math.round(Math.max(Math.abs(row - mid), Math.abs(col - mid)));
}

export function TileWait({
  label = "Composing",
  doneLabel = "Done in",
  errorLabel = "Failed after",
  status = "working",
  pattern = "ripple",
  grid = 3,
  shape = "square",
  color = "currentColor",
  doneColor = "hsl(var(--primary))",
  errorColor = "hsl(var(--destructive))",
  cellSize = 5,
  gap = 3,
  fontSize = 12,
  step = 90,
  idleOpacity = 0.15,
  glow = false,
  glowColor = "",
  showTimer = true,
  elapsed,
  style,
  className,
}: TileWaitProps) {
  const reduce = useReducedMotion();
  const [tick, setTick] = useState(0);
  const [seconds, setSeconds] = useState(0);
  const startedAt = useRef(0);
  const working = status === "working";

  useEffect(() => {
    if (!working || reduce) return;
    const id = setInterval(() => setTick((t) => t + 1), step);
    return () => clearInterval(id);
  }, [working, reduce, step]);

  useEffect(() => {
    if (!working) return;
    startedAt.current = performance.now();
    setSeconds(0);
    const id = setInterval(() => setSeconds((performance.now() - startedAt.current) / 1000), 100);
    return () => clearInterval(id);
  }, [working]);

  const phases =
    pattern === "sweep" ? grid * 2 - 1 : pattern === "scatter" ? grid + 1 : Math.ceil(grid / 2);
  const lit = tick % phases;
  const tone = status === "done" ? doneColor : status === "error" ? errorColor : color;
  const box = grid * cellSize + (grid - 1) * gap;
  const time = `${(elapsed ?? seconds).toFixed(1)}s`;
  const caption = working ? label : status === "done" ? doneLabel : errorLabel;
  const shadow = glow ? `drop-shadow(0 0 ${cellSize}px ${glowColor || tone})` : undefined;

  return (
    <span
      role="status"
      aria-live="polite"
      className={cn(
        "inline-flex items-center gap-2.5 font-mono uppercase tracking-[0.18em]",
        className,
      )}
      style={{ fontSize, ...style }}
    >
      <span
        className="relative inline-block shrink-0"
        style={{ width: box, height: box, filter: shadow }}
      >
        <AnimatePresence mode="wait" initial={false}>
          {working ? (
            <motion.span
              key="grid"
              className="absolute inset-0 grid"
              style={{ gridTemplateColumns: `repeat(${grid}, ${cellSize}px)`, gap }}
              exit={{ opacity: 0, scale: 0.6 }}
              transition={{ duration: reduce ? 0 : 0.18 }}
            >
              {Array.from({ length: grid * grid }, (_, i) => {
                const on =
                  !reduce && phaseOf(pattern, Math.floor(i / grid), i % grid, grid) === lit;
                return (
                  <motion.span
                    key={i}
                    animate={{ opacity: reduce ? 0.6 : on ? 1 : idleOpacity }}
                    transition={{ duration: (step / 1000) * 1.5 }}
                    style={{
                      width: cellSize,
                      height: cellSize,
                      background: tone,
                      borderRadius: shape === "circle" ? "50%" : 1,
                    }}
                  />
                );
              })}
            </motion.span>
          ) : (
            <motion.svg
              key={status}
              viewBox="0 0 16 16"
              className="absolute inset-0 h-full w-full"
              fill="none"
              stroke={tone}
              strokeWidth={2.4}
              strokeLinecap="round"
              strokeLinejoin="round"
              initial={{ opacity: 0, scale: reduce ? 1 : 0.5 }}
              animate={{ opacity: 1, scale: 1 }}
              transition={{ duration: reduce ? 0 : 0.25 }}
            >
              <motion.path
                d={status === "done" ? "M3 8.5 6.5 12 13 4.5" : "M4 4l8 8M12 4l-8 8"}
                initial={{ pathLength: reduce ? 1 : 0 }}
                animate={{ pathLength: 1 }}
                transition={{ duration: reduce ? 0 : 0.3 }}
              />
            </motion.svg>
          )}
        </AnimatePresence>
      </span>
      <span>{caption}</span>
      {showTimer && (
        <span
          className="tabular-nums tracking-normal opacity-60"
          style={{ fontSize: fontSize * 0.85 }}
        >
          {time}
        </span>
      )}
    </span>
  );
}
```

---

# Folio Crush

> A WebGL print you can hold to crush into a ball and drag around.

Install: `npx @modus-ui/cli add folio-crush`

The sheet backs onto the theme's muted paper tone, resolved live from the palette, and sits slightly askew on the page.

## Installation

### CLI

```bash
npx @modus-ui/cli add folio-crush
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/folio-crush.tsx`.
3. Paste the code.

## Usage

```tsx
import { FolioCrush } from "@/components/ui/folio-crush";

export default function Example() {
  return <FolioCrush src="/print.jpg" />;
}
```

## Props

| Prop            | Type     | Default             | Description                                        |
| :-------------- | :------- | :------------------ | :------------------------------------------------- |
| src             | string   | -                   | The image URL to display on the paper front.       |
| alt             | string   | "Folio print"       | Accessible alt text.                               |
| backSrc         | string   | ""                  | Optional back face image URL.                      |
| width           | number   | 320                 | Width of the paper in pixels.                      |
| height          | number   | 400                 | Height of the paper in pixels.                     |
| sceneHeight     | number   | 560                 | Height of the container scene.                     |
| imageFit        | string   | "cover"             | CSS object-fit for the image.                      |
| releaseBehavior | string   | "restore"           | What happens on release: "restore" or "stay".      |
| crumpleAmount   | number   | 0.85                | How much the paper crumples (0–1).                 |
| crumpleDuration | number   | 0.55                | Duration of crumple animation in seconds.          |
| releaseDuration | number   | 0.4                 | Duration of release animation in seconds.          |
| foldCount       | number   | 6                   | Number of fold lines.                              |
| foldSharpness   | number   | 0.6                 | Sharpness of the fold creases.                     |
| wrinkleDepth    | number   | 0.65                | Depth of the wrinkle displacement.                 |
| creaseStrength  | number   | 0.18                | Strength of crease shadowing.                      |
| paperColor      | string   | "hsl(var(--muted))" | Color of the paper.                                |
| roughness       | number   | 0.92                | Material roughness (0–1).                          |
| paperTexture    | number   | 0.08                | Paper texture noise intensity.                     |
| lightIntensity  | number   | 1.8                 | Light intensity on the paper.                      |
| lightAngle      | number   | -35                 | Angle of the directional light in degrees.         |
| shadow          | boolean  | true                | Whether to show a drop shadow.                     |
| shadowOpacity   | number   | 0.08                | Opacity of the drop shadow.                        |
| draggable       | boolean  | true                | Whether the paper can be dragged.                  |
| dragRotation    | number   | 10                  | Max rotation on drag in degrees.                   |
| dragRadius      | number   | 180                 | Max drag displacement radius.                      |
| returnToOrigin  | boolean  | true                | Whether the paper snaps back on release.           |
| rotation        | number   | -4                  | Initial rotation of the paper in degrees.          |
| seed            | number   | 7                   | Random seed for wrinkle generation.                |
| detail          | number   | 64                  | Mesh subdivision detail level.                     |
| disabled        | boolean  | false               | Disables interaction.                              |
| resetKey        | number   | 0                   | Change this value to programmatically reset state. |
| onStateChange   | function | -                   | Callback fired on status change.                   |
| onError         | function | -                   | Callback fired on load error.                      |
| style           | object   | -                   | Inline style for the container.                    |

## Source

`components/ui/folio-crush.tsx`

```tsx
"use client";
// A printed sheet in WebGL: press and hold to crush it into a ball, drag it around, let go to smooth it out.

import { useEffect, useRef, type CSSProperties } from "react";
import { animate, useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

type CrushState = "flat" | "crushing" | "crushed" | "restoring";

interface FolioCrushProps {
  src: string;
  alt?: string;
  backSrc?: string;
  width?: number;
  height?: number;
  sceneHeight?: number;
  imageFit?: "cover" | "contain";
  releaseBehavior?: "restore" | "stay";
  crumpleAmount?: number;
  crumpleDuration?: number;
  releaseDuration?: number;
  foldCount?: number;
  foldSharpness?: number;
  wrinkleDepth?: number;
  creaseStrength?: number;
  paperColor?: string;
  roughness?: number;
  paperTexture?: number;
  lightIntensity?: number;
  lightAngle?: number;
  shadow?: boolean;
  shadowOpacity?: number;
  draggable?: boolean;
  dragRotation?: number;
  dragRadius?: number;
  returnToOrigin?: boolean;
  rotation?: number;
  seed?: number;
  detail?: number;
  disabled?: boolean;
  resetKey?: number;
  onStateChange?: (state: CrushState) => void;
  onError?: (error: unknown) => void;
  style?: CSSProperties;
  className?: string;
}

/** Small deterministic PRNG so a seed always gives the same crumple. */
function mulberry(seed: number) {
  return () => {
    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;
  };
}

/** Turns any CSS colour (theme tokens included) into a THREE.Color. */
function resolveColor(el: HTMLElement, css: string) {
  const probe = document.createElement("span");
  probe.style.color = css;
  el.appendChild(probe);
  const rgb = getComputedStyle(probe).color;
  probe.remove();
  return new THREE.Color(rgb.replace(/\s*\/\s*[\d.]+\)/, ")"));
}

function grainTexture(rand: () => number) {
  const size = 128;
  const data = new Uint8Array(size * size * 4);
  for (let i = 0; i < data.length; i += 4) {
    const v = 128 + (rand() - 0.5) * 255;
    data[i] = data[i + 1] = data[i + 2] = v;
    data[i + 3] = 255;
  }
  const tex = new THREE.DataTexture(data, size, size);
  tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
  tex.repeat.set(4, 4);
  tex.needsUpdate = true;
  return tex;
}

export function FolioCrush({
  src,
  alt = "Folio print",
  backSrc = "",
  width = 320,
  height = 400,
  sceneHeight = 560,
  imageFit = "cover",
  releaseBehavior = "restore",
  crumpleAmount = 0.85,
  crumpleDuration = 0.55,
  releaseDuration = 0.4,
  foldCount = 6,
  foldSharpness = 0.6,
  wrinkleDepth = 0.65,
  creaseStrength = 0.18,
  paperColor = "hsl(var(--muted))",
  roughness = 0.92,
  paperTexture = 0.08,
  lightIntensity = 1.8,
  lightAngle = -35,
  shadow = true,
  shadowOpacity = 0.08,
  draggable = true,
  dragRotation = 10,
  dragRadius = 180,
  returnToOrigin = true,
  rotation = -4,
  seed = 7,
  detail = 64,
  disabled = false,
  resetKey = 0,
  onStateChange,
  onError,
  style,
  className,
}: FolioCrushProps) {
  const reduce = useReducedMotion();
  const host = useRef<HTMLDivElement>(null);
  const callbacks = useRef({ onStateChange, onError });
  callbacks.current = { onStateChange, onError };

  useEffect(() => {
    const el = host.current;
    if (!el) return;
    const rand = mulberry(seed);
    const time = (s: number) => (reduce ? 0 : s);

    // Scene, with a camera placed so one world unit is one CSS pixel at z = 0.
    const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
    renderer.setPixelRatio(Math.min(2, window.devicePixelRatio));
    el.appendChild(renderer.domElement);
    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(30, 1, 1, 5000);
    camera.position.z = sceneHeight / 2 / Math.tan((15 * Math.PI) / 180);
    scene.add(new THREE.AmbientLight(0xffffff, 1.2));
    const sun = new THREE.DirectionalLight(0xffffff, lightIntensity);
    const a = (lightAngle * Math.PI) / 180;
    sun.position.set(Math.sin(a) * 400, Math.cos(a) * 400, 500);
    scene.add(sun);

    // Geometry: precompute flat, creased and balled positions per vertex.
    const geo = new THREE.PlaneGeometry(width, height, detail, detail);
    const pos = geo.attributes.position as THREE.BufferAttribute;
    const count = pos.count;
    const flat = Float32Array.from(pos.array as Float32Array);
    const relief = new Float32Array(count);
    const ball = new Float32Array(count * 3);
    const folds = Array.from({ length: foldCount }, () => {
      const t = rand() * Math.PI;
      return {
        nx: Math.cos(t),
        ny: Math.sin(t),
        c: (rand() - 0.5) * width,
        amp: (rand() < 0.5 ? -1 : 1) * (8 + rand() * 14),
      };
    });
    const waves = Array.from({ length: 4 }, () => ({
      k: 0.02 + rand() * 0.04,
      p: rand() * 6.28,
      t: rand() * 6.28,
    }));
    const reach = 4 + (1 - foldSharpness) * 30;
    const radius = Math.sqrt((width * height) / (4 * Math.PI)) * 0.8;
    for (let i = 0; i < count; i++) {
      const x = flat[i * 3];
      const y = flat[i * 3 + 1];
      let z = 0;
      for (const f of folds) z += f.amp * Math.exp(-Math.abs(x * f.nx + y * f.ny - f.c) / reach);
      for (const w of waves)
        z += 4 * wrinkleDepth * Math.sin(w.k * (x * Math.cos(w.t) + y * Math.sin(w.t)) + w.p);
      relief[i] = z;
      const lon = (x / (width / 2)) * Math.PI;
      const lat = (y / (height / 2)) * (Math.PI / 2) * 0.96;
      const r = radius * (1 + (z / 40) * wrinkleDepth);
      ball[i * 3] = r * Math.sin(lon) * Math.cos(lat);
      ball[i * 3 + 1] = r * Math.sin(lat);
      ball[i * 3 + 2] = r * Math.cos(lon) * Math.cos(lat);
    }
    const shade = new Float32Array(count * 3).fill(1);
    geo.setAttribute("color", new THREE.BufferAttribute(shade, 3));
    const maxRelief = Math.max(1, ...Array.from(relief, Math.abs));

    const paper = resolveColor(el, paperColor);
    const grain = paperTexture > 0 ? grainTexture(rand) : null;
    const material = (side: THREE.Side) =>
      new THREE.MeshStandardMaterial({
        color: paper,
        side,
        roughness,
        vertexColors: true,
        bumpMap: grain,
        bumpScale: paperTexture * 4,
      });
    const front = material(THREE.FrontSide);
    const back = material(THREE.BackSide);
    const sheet = new THREE.Group();
    sheet.add(new THREE.Mesh(geo, front), new THREE.Mesh(geo, back));
    sheet.rotation.z = (rotation * Math.PI) / 180;
    scene.add(sheet);

    const loader = new THREE.TextureLoader();
    loader.setCrossOrigin("anonymous");
    const load = (url: string, target: THREE.MeshStandardMaterial, mirror: boolean) =>
      loader.load(
        url,
        (tex) => {
          tex.colorSpace = THREE.SRGBColorSpace;
          const img = tex.image as HTMLImageElement;
          const ratio = img.width / img.height / (width / height);
          const fit = imageFit === "cover" ? ratio > 1 : ratio < 1;
          if (fit) tex.repeat.set(1 / ratio, 1);
          else tex.repeat.set(1, ratio);
          if (mirror) tex.repeat.x *= -1;
          tex.offset.set((1 - tex.repeat.x) / 2, (1 - tex.repeat.y) / 2);
          if (imageFit === "contain") tex.wrapS = tex.wrapT = THREE.ClampToEdgeWrapping;
          target.map = tex;
          target.color.set(0xffffff);
          target.needsUpdate = true;
          dirty = true;
        },
        undefined,
        (err) => callbacks.current.onError?.(err),
      );
    load(src, front, false);
    if (backSrc) load(backSrc, back, true);

    // State, animated with framer-motion and read each frame.
    let crush = 0;
    let dirty = true;
    const offset = { x: 0, y: 0, tilt: 0 };
    let state: CrushState = "flat";
    const setState = (s: CrushState) => {
      state = s;
      callbacks.current.onStateChange?.(s);
    };
    let crushAnim: ReturnType<typeof animate> | null = null;
    const crushTo = (to: number, duration: number, after: CrushState) => {
      crushAnim?.stop();
      crushAnim = animate(crush, to, {
        duration: time(duration),
        ease: to ? [0.5, 0, 0.2, 1] : [0.2, 0.8, 0.3, 1],
        onUpdate: (v) => {
          crush = v;
          dirty = true;
        },
        onComplete: () => setState(after),
      });
    };
    const moveTo = (x: number, y: number) => {
      animate(
        offset,
        { x, y, tilt: 0 },
        { type: "spring", bounce: 0.3, duration: time(0.6), onUpdate: () => (dirty = true) },
      );
    };

    const apply = () => {
      const t = crush * crumpleAmount;
      const e = t * t * (3 - 2 * t);
      const arr = pos.array as Float32Array;
      for (let i = 0; i < count; i++) {
        const j = i * 3;
        const fz = relief[i] * Math.min(1, crush * 3) * wrinkleDepth;
        arr[j] = flat[j] + (ball[j] - flat[j]) * e;
        arr[j + 1] = flat[j + 1] + (ball[j + 1] - flat[j + 1]) * e;
        arr[j + 2] = fz * (1 - e) + ball[j + 2] * e;
        const c = 1 - creaseStrength * crush * (Math.abs(relief[i]) / maxRelief);
        shade[j] = shade[j + 1] = shade[j + 2] = c;
      }
      pos.needsUpdate = true;
      geo.attributes.color.needsUpdate = true;
      geo.computeVertexNormals();
      sheet.position.set(offset.x, offset.y, 0);
      sheet.rotation.set(offset.tilt * 0.5, offset.tilt, (rotation * Math.PI) / 180 + offset.tilt);
    };

    let raf = 0;
    const frame = () => {
      if (dirty) {
        dirty = false;
        apply();
        renderer.render(scene, camera);
      }
      raf = requestAnimationFrame(frame);
    };
    raf = requestAnimationFrame(frame);

    const resize = () => {
      const w = el.clientWidth;
      renderer.setSize(w, sceneHeight);
      camera.aspect = w / sceneHeight;
      camera.updateProjectionMatrix();
      dirty = true;
    };
    const observer = new ResizeObserver(resize);
    observer.observe(el);
    resize();

    // Pointer: press to crush, drag while held, release to restore.
    const canvas = renderer.domElement;
    let grab: { x: number; y: number; ox: number; oy: number; lx: number; smooth: boolean } | null =
      null;
    const down = (e: PointerEvent) => {
      if (disabled) return;
      canvas.setPointerCapture(e.pointerId);
      grab = {
        x: e.clientX,
        y: e.clientY,
        ox: offset.x,
        oy: offset.y,
        lx: e.clientX,
        smooth: state === "crushed",
      };
      if (state === "flat" || state === "restoring") {
        setState("crushing");
        crushTo(1, crumpleDuration, "crushed");
      }
    };
    const move = (e: PointerEvent) => {
      if (!grab || !draggable) return;
      let x = grab.ox + e.clientX - grab.x;
      let y = grab.oy - (e.clientY - grab.y);
      const d = Math.hypot(x, y);
      if (d > dragRadius) {
        x *= dragRadius / d;
        y *= dragRadius / d;
      }
      const max = (dragRotation * Math.PI) / 180;
      offset.tilt = Math.max(-max, Math.min(max, (e.clientX - grab.lx) * 0.02));
      grab.lx = e.clientX;
      offset.x = x;
      offset.y = y;
      dirty = true;
    };
    const up = () => {
      if (!grab) return;
      const { smooth } = grab;
      grab = null;
      if (returnToOrigin) moveTo(0, 0);
      else moveTo(offset.x, offset.y);
      // With "stay", a second press smooths the ball back out.
      if (releaseBehavior === "restore" || smooth) {
        setState("restoring");
        crushTo(0, releaseDuration, "flat");
      }
    };
    canvas.addEventListener("pointerdown", down);
    canvas.addEventListener("pointermove", move);
    canvas.addEventListener("pointerup", up);
    canvas.addEventListener("pointercancel", up);
    canvas.style.touchAction = "none";
    canvas.style.cursor = disabled ? "default" : "grab";

    return () => {
      cancelAnimationFrame(raf);
      crushAnim?.stop();
      observer.disconnect();
      canvas.removeEventListener("pointerdown", down);
      canvas.removeEventListener("pointermove", move);
      canvas.removeEventListener("pointerup", up);
      canvas.removeEventListener("pointercancel", up);
      geo.dispose();
      front.map?.dispose();
      back.map?.dispose();
      grain?.dispose();
      front.dispose();
      back.dispose();
      renderer.dispose();
      canvas.remove();
    };
  }, [
    src,
    backSrc,
    width,
    height,
    sceneHeight,
    imageFit,
    releaseBehavior,
    crumpleAmount,
    crumpleDuration,
    releaseDuration,
    foldCount,
    foldSharpness,
    wrinkleDepth,
    creaseStrength,
    paperColor,
    roughness,
    paperTexture,
    lightIntensity,
    lightAngle,
    draggable,
    dragRotation,
    dragRadius,
    returnToOrigin,
    rotation,
    seed,
    detail,
    disabled,
    resetKey,
    reduce,
  ]);

  return (
    <div
      ref={host}
      role="img"
      aria-label={alt}
      className={cn("relative w-full overflow-hidden", className)}
      style={{
        height: sceneHeight,
        filter: shadow
          ? `drop-shadow(0 18px 22px hsl(var(--foreground) / ${shadowOpacity * 3}))`
          : undefined,
        ...style,
      }}
    />
  );
}
```

---

# Glance Score

> A rating row whose icons lift as you hover, with a mono label tip.

Install: `npx @modus-ui/cli add glance-score`

Unset marks sit in the border tone, filled marks take the primary colour and the tip prints in inverted ink.

## Installation

### CLI

```bash
npx @modus-ui/cli add glance-score
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/glance-score.tsx`.
3. Paste the code.

## Usage

```tsx
import { GlanceScore } from "@/components/ui/glance-score";

export default function Example() {
  return <GlanceScore />;
}
```

## Props

| Prop         | Type    | Default                  | Description |
| :----------- | :------ | :----------------------- | :---------- |
| value        | any     | -                        | -           |
| defaultValue | number  | 0                        | -           |
| onChange     | any     | -                        | -           |
| onPreview    | any     | -                        | -           |
| count        | number  | 5                        | -           |
| shape        | string  | "star"                   | -           |
| icon         | any     | -                        | -           |
| labels       | any     | []                       | -           |
| activeColor  | string  | "hsl(var(--primary))"    | -           |
| idleColor    | string  | "hsl(var(--border))"     | -           |
| tipColor     | string  | "hsl(var(--foreground))" | -           |
| tipTextColor | string  | "hsl(var(--background))" | -           |
| size         | number  | 26                       | -           |
| lift         | number  | 4                        | -           |
| magnify      | number  | 1.25                     | -           |
| riseDuration | number  | 320                      | -           |
| popScale     | number  | 1.3                      | -           |
| showTip      | boolean | true                     | -           |
| allowClear   | boolean | true                     | -           |
| readOnly     | boolean | false                    | -           |
| disabled     | boolean | false                    | -           |
| ariaLabel    | string  | "Rating"                 | -           |

## Source

`components/ui/glance-score.tsx`

```tsx
"use client";
// Rating row: marks rise toward the pointer and a mono tip names the hovered score.

import { useState, type KeyboardEvent, type ReactNode } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const SHAPES = {
  star: "M12 2.5l2.9 6 6.6.8-4.9 4.6 1.3 6.6L12 17.3l-5.9 3.2 1.3-6.6-4.9-4.6 6.6-.8z",
  heart: "M12 20.5S3 15 3 8.8A4.6 4.6 0 0 1 12 6.6a4.6 4.6 0 0 1 9 2.2C21 15 12 20.5 12 20.5z",
  circle: "M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18z",
};

interface GlanceScoreProps {
  value?: number;
  defaultValue?: number;
  onChange?: (value: number) => void;
  /** Fires with the hovered score, or null when the pointer leaves. */
  onPreview?: (value: number | null) => void;
  count?: number;
  shape?: keyof typeof SHAPES;
  /** Custom mark; drawn in currentColor. Overrides `shape`. */
  icon?: ReactNode;
  labels?: string[];
  activeColor?: string;
  idleColor?: string;
  tipColor?: string;
  tipTextColor?: string;
  size?: number;
  lift?: number;
  magnify?: number;
  riseDuration?: number;
  popScale?: number;
  showTip?: boolean;
  allowClear?: boolean;
  readOnly?: boolean;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

export function GlanceScore({
  value,
  defaultValue = 0,
  onChange,
  onPreview,
  count = 5,
  shape = "star",
  icon,
  labels = [],
  activeColor = "hsl(var(--primary))",
  idleColor = "hsl(var(--border))",
  tipColor = "hsl(var(--foreground))",
  tipTextColor = "hsl(var(--background))",
  size = 26,
  lift = 4,
  magnify = 1.25,
  riseDuration = 320,
  popScale = 1.3,
  showTip = true,
  allowClear = true,
  readOnly = false,
  disabled = false,
  ariaLabel = "Rating",
  className,
}: GlanceScoreProps) {
  const reduce = useReducedMotion();
  const [inner, setInner] = useState(defaultValue);
  const [hover, setHover] = useState<number | null>(null);
  const [popped, setPopped] = useState(0);
  const score = value ?? inner;
  const shown = hover ?? score;
  const locked = readOnly || disabled;

  const preview = (n: number | null) => {
    if (locked) return;
    setHover(n);
    onPreview?.(n);
  };
  const commit = (n: number) => {
    if (locked) return;
    const next = allowClear && n === score ? 0 : Math.max(0, Math.min(count, n));
    setInner(next);
    setPopped(next);
    onChange?.(next);
  };
  const onKey = (e: KeyboardEvent) => {
    const step = { ArrowRight: 1, ArrowUp: 1, ArrowLeft: -1, ArrowDown: -1 }[e.key];
    if (step) {
      e.preventDefault();
      const next = Math.max(0, Math.min(count, score + step));
      if (next !== score) commit(next);
    } else if (e.key === "Home" || e.key === "End") {
      e.preventDefault();
      commit(e.key === "Home" ? 0 : count);
    }
  };

  const ease = { duration: reduce ? 0 : riseDuration / 1000, ease: [0.2, 0.9, 0.3, 1] as const };

  return (
    <div
      role="slider"
      aria-label={ariaLabel}
      aria-valuemin={0}
      aria-valuemax={count}
      aria-valuenow={score}
      aria-valuetext={labels[score - 1] ?? `${score} of ${count}`}
      aria-readonly={readOnly || undefined}
      aria-disabled={disabled || undefined}
      tabIndex={disabled ? -1 : 0}
      onKeyDown={locked ? undefined : onKey}
      onPointerLeave={() => preview(null)}
      className={cn(
        "relative inline-flex items-end gap-1 rounded-md outline-none focus-visible:ring-2 focus-visible:ring-ring",
        disabled && "opacity-50",
        className,
      )}
      style={{ paddingTop: lift * 2 }}
    >
      {Array.from({ length: count }, (_, i) => {
        const n = i + 1;
        // Neighbours of the hovered mark rise a little too, fading with distance.
        const near = hover === null ? 0 : Math.max(0, 1 - Math.abs(hover - n) / 2);
        return (
          <motion.button
            key={n}
            type="button"
            tabIndex={-1}
            aria-hidden
            disabled={locked}
            onPointerEnter={() => preview(n)}
            onClick={() => commit(n)}
            className={cn("relative block", locked ? "cursor-default" : "cursor-pointer")}
            style={{ width: size, height: size, color: n <= shown ? activeColor : idleColor }}
            animate={{ y: -lift * near, scale: 1 + (magnify - 1) * near }}
            transition={ease}
          >
            <motion.span
              key={popped === n ? `pop-${score}` : "rest"}
              className="block h-full w-full"
              initial={popped === n && !reduce ? { scale: popScale } : false}
              animate={{ scale: 1 }}
              transition={{ type: "spring", stiffness: 500, damping: 18 }}
            >
              {icon ?? (
                <svg viewBox="0 0 24 24" className="h-full w-full" fill="currentColor">
                  <path d={SHAPES[shape]} />
                </svg>
              )}
            </motion.span>
            <AnimatePresence>
              {showTip && hover === n && labels[i] && (
                <motion.span
                  className="pointer-events-none absolute bottom-full left-1/2 mb-2 whitespace-nowrap rounded-[3px] px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-[0.14em]"
                  style={{ background: tipColor, color: tipTextColor, x: "-50%" }}
                  initial={{ opacity: 0, y: reduce ? 0 : 4 }}
                  animate={{ opacity: 1, y: 0 }}
                  exit={{ opacity: 0 }}
                  transition={{ duration: reduce ? 0 : 0.16 }}
                >
                  {labels[i]}
                </motion.span>
              )}
            </AnimatePresence>
          </motion.button>
        );
      })}
    </div>
  );
}
```

---

# Query Well

> A composer for AI requests with sources, commands, model and effort menus.

Install: `npx @modus-ui/cli add query-well`

It sits on the card surface with a hairline ring, and its send spark tints from the primary token.

## Installation

### CLI

```bash
npx @modus-ui/cli add query-well
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/query-well.tsx`.
3. Paste the code.

## Usage

```tsx
import { QueryWell } from "@/components/ui/query-well";

export default function Example() {
  return <QueryWell />;
}
```

## Props

| Prop           | Type    | Default                  | Description |
| :------------- | :------ | :----------------------- | :---------- |
| placeholder    | string  | "Draft a request"        | -           |
| sources        | any     | DEFAULT_SOURCES          | -           |
| commands       | any     | DEFAULT_COMMANDS         | -           |
| models         | any     | DEFAULT_MODELS           | -           |
| defaultModel   | string  | ""                       | -           |
| efforts        | any     | DEFAULT_EFFORTS          | -           |
| defaultEffort  | string  | ""                       | -           |
| onEffortChange | any     | -                        | -           |
| busy           | boolean | false                    | -           |
| onSend         | any     | -                        | -           |
| onStop         | any     | -                        | -           |
| onAttach       | any     | -                        | -           |
| onDictate      | any     | -                        | -           |
| background     | string  | "hsl(var(--card))"       | -           |
| color          | string  | "hsl(var(--foreground))" | -           |
| menuBackground | string  | "hsl(var(--popover))"    | -           |
| sparkColor     | string  | "hsl(var(--primary))"    | -           |
| sparkBoost     | number  | 1                        | -           |
| width          | number  | 440                      | -           |
| radius         | number  | 12                       | -           |
| maxRows        | number  | 5                        | -           |
| morphDuration  | number  | 240                      | -           |
| squash         | number  | 0.12                     | -           |
| tilt           | number  | 8                        | -           |
| pressScale     | number  | 0.96                     | -           |

## Source

`components/ui/query-well.tsx`

```tsx
"use client";
// A prompt composer with source, slash-command, model and effort menus.

import { useEffect, useRef, useState, type ReactNode } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { HugeiconsIcon } from "@hugeicons/react";
import {
  Add01Icon,
  ArrowDown01Icon,
  ArrowUp02Icon,
  FlashIcon,
  Mic01Icon,
  SquareIcon,
} from "@hugeicons/core-free-icons";
import { cn } from "@/lib/utils";

export interface QueryOption {
  id: string;
  label: string;
  hint?: string;
}

const DEFAULT_SOURCES: QueryOption[] = [
  { id: "file", label: "Upload a file" },
  { id: "drive", label: "From the drive" },
  { id: "web", label: "Search the web" },
];
const DEFAULT_COMMANDS: QueryOption[] = [
  { id: "summarize", label: "/summarize", hint: "Condense the thread" },
  { id: "rewrite", label: "/rewrite", hint: "Rework the tone" },
  { id: "outline", label: "/outline", hint: "Draft a structure" },
];
const DEFAULT_MODELS: QueryOption[] = [
  { id: "nova-3", label: "Nova 3" },
  { id: "nova-3-mini", label: "Nova 3 Mini" },
  { id: "atlas", label: "Atlas" },
];
const DEFAULT_EFFORTS: QueryOption[] = [
  { id: "low", label: "Low" },
  { id: "medium", label: "Medium" },
  { id: "high", label: "High" },
];

export interface QueryWellProps {
  placeholder?: string;
  sources?: QueryOption[];
  commands?: QueryOption[];
  models?: QueryOption[];
  defaultModel?: string;
  efforts?: QueryOption[];
  defaultEffort?: string;
  onEffortChange?: (effort: string) => void;
  busy?: boolean;
  onSend?: (text: string, options: { model: string; effort: string }) => void;
  onStop?: () => void;
  onAttach?: (source: string) => void;
  onDictate?: () => void;
  background?: string;
  color?: string;
  menuBackground?: string;
  sparkColor?: string;
  sparkBoost?: number;
  width?: number;
  radius?: number;
  maxRows?: number;
  morphDuration?: number;
  squash?: number;
  tilt?: number;
  pressScale?: number;
  className?: string;
}

type MenuName = "sources" | "model" | "effort" | null;

export function QueryWell({
  placeholder = "Draft a request",
  sources = DEFAULT_SOURCES,
  commands = DEFAULT_COMMANDS,
  models = DEFAULT_MODELS,
  defaultModel = "",
  efforts = DEFAULT_EFFORTS,
  defaultEffort = "",
  onEffortChange,
  busy = false,
  onSend,
  onStop,
  onAttach,
  onDictate,
  background = "hsl(var(--card))",
  color = "hsl(var(--foreground))",
  menuBackground = "hsl(var(--popover))",
  sparkColor = "hsl(var(--primary))",
  sparkBoost = 1,
  width = 440,
  radius = 12,
  maxRows = 5,
  morphDuration = 240,
  squash = 0.12,
  tilt = 8,
  pressScale = 0.96,
  className,
}: QueryWellProps) {
  const reduce = useReducedMotion();
  const [text, setText] = useState("");
  const [menu, setMenu] = useState<MenuName>(null);
  const [model, setModel] = useState(defaultModel || models[0]?.id || "");
  const [effort, setEffort] = useState(defaultEffort || efforts[efforts.length - 1]?.id || "");
  const area = useRef<HTMLTextAreaElement>(null);
  const root = useRef<HTMLDivElement>(null);

  // Grow the textarea up to maxRows.
  useEffect(() => {
    const el = area.current;
    if (!el) return;
    const line = parseFloat(getComputedStyle(el).lineHeight) || 20;
    el.style.height = "auto";
    el.style.height = `${Math.min(el.scrollHeight, line * maxRows)}px`;
  }, [text, maxRows]);

  useEffect(() => {
    if (!menu) return;
    const close = (e: PointerEvent) => {
      if (!root.current?.contains(e.target as Node)) setMenu(null);
    };
    document.addEventListener("pointerdown", close);
    return () => document.removeEventListener("pointerdown", close);
  }, [menu]);

  const slash = /^\/\S*$/.test(text) ? commands.filter((c) => c.label.startsWith(text)) : [];
  const ready = text.trim().length > 0;
  const nameOf = (list: QueryOption[], id: string) => list.find((o) => o.id === id)?.label;

  const send = () => {
    if (busy) return onStop?.();
    if (!ready) return;
    onSend?.(text.trim(), { model, effort });
    setText("");
  };

  const spring = reduce ? { duration: 0 } : { duration: morphDuration / 1000 };

  return (
    <div
      ref={root}
      className={cn("relative max-w-full ring-1 ring-[hsl(var(--border))]", className)}
      style={{ width, borderRadius: radius, background, color }}
    >
      <textarea
        ref={area}
        rows={1}
        value={text}
        placeholder={placeholder}
        aria-label={placeholder}
        onChange={(e) => setText(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === "Enter" && !e.shiftKey) {
            e.preventDefault();
            if (slash[0]) setText(`${slash[0].label} `);
            else send();
          }
          if (e.key === "Escape") setMenu(null);
        }}
        className="block w-full resize-none bg-transparent px-3.5 pt-3 text-sm leading-5 outline-none placeholder:text-muted-foreground"
      />

      <div className="flex items-center gap-1 px-2 pb-2 pt-1.5">
        <Chip onClick={() => setMenu(menu === "sources" ? null : "sources")} label="Add source">
          <HugeiconsIcon icon={Add01Icon} size={14} />
        </Chip>
        <Chip onClick={() => setMenu(menu === "model" ? null : "model")} label="Model">
          {nameOf(models, model)}
          <HugeiconsIcon icon={ArrowDown01Icon} size={12} />
        </Chip>
        <Chip onClick={() => setMenu(menu === "effort" ? null : "effort")} label="Effort">
          <HugeiconsIcon icon={FlashIcon} size={12} />
          {nameOf(efforts, effort)}
        </Chip>
        <div className="flex-1" />
        {onDictate && (
          <Chip onClick={onDictate} label="Dictate">
            <HugeiconsIcon icon={Mic01Icon} size={14} />
          </Chip>
        )}
        <motion.button
          type="button"
          aria-label={busy ? "Stop" : "Send"}
          disabled={!busy && !ready}
          onClick={send}
          whileTap={reduce ? undefined : { scale: pressScale, scaleY: pressScale - squash / 2 }}
          whileHover={reduce || (!busy && !ready) ? undefined : { rotate: -tilt }}
          animate={{
            borderRadius: busy ? 6 : 999,
            opacity: busy || ready ? 1 : 0.45,
            boxShadow:
              ready && !busy && !reduce
                ? `0 0 ${10 * sparkBoost}px ${2 * sparkBoost}px color-mix(in srgb, ${sparkColor} 35%, transparent)`
                : "0 0 0 0 transparent",
          }}
          transition={spring}
          className="grid size-7 place-items-center text-[hsl(var(--primary-foreground))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
          style={{ background: sparkColor }}
        >
          <AnimatePresence mode="popLayout" initial={false}>
            <motion.span
              key={busy ? "stop" : "send"}
              initial={{ opacity: 0, scale: 0.5 }}
              animate={{ opacity: 1, scale: 1 }}
              exit={{ opacity: 0, scale: 0.5 }}
              transition={spring}
            >
              <HugeiconsIcon icon={busy ? SquareIcon : ArrowUp02Icon} size={14} />
            </motion.span>
          </AnimatePresence>
        </motion.button>
      </div>

      <AnimatePresence>
        {(menu || slash.length > 0) && (
          <motion.ul
            key={menu ?? "commands"}
            role="listbox"
            initial={{ opacity: 0, y: reduce ? 0 : 4 }}
            animate={{ opacity: 1, y: 0 }}
            exit={{ opacity: 0 }}
            transition={{ duration: reduce ? 0 : 0.15 }}
            className="absolute bottom-full left-2 z-20 m-0 mb-2 min-w-44 list-none rounded-md p-1 text-sm shadow-lg ring-1 ring-[hsl(var(--border))]"
            style={{ background: menuBackground }}
          >
            {(menu === "sources"
              ? sources
              : menu === "model"
                ? models
                : menu === "effort"
                  ? efforts
                  : slash
            ).map((o) => (
              <li key={o.id} className="m-0 p-0">
                <button
                  type="button"
                  role="option"
                  aria-selected={
                    (menu === "model" && o.id === model) || (menu === "effort" && o.id === effort)
                  }
                  onClick={() => {
                    if (menu === "sources") onAttach?.(o.id);
                    else if (menu === "model") setModel(o.id);
                    else if (menu === "effort") {
                      setEffort(o.id);
                      onEffortChange?.(o.id);
                    } else {
                      setText(`${o.label} `);
                      area.current?.focus();
                    }
                    setMenu(null);
                  }}
                  className="flex w-full items-baseline justify-between gap-4 rounded px-2 py-1.5 text-left hover:bg-[hsl(var(--muted))] focus-visible:bg-[hsl(var(--muted))] focus-visible:outline-none"
                >
                  <span>{o.label}</span>
                  {o.hint && <span className="text-xs text-muted-foreground">{o.hint}</span>}
                </button>
              </li>
            ))}
          </motion.ul>
        )}
      </AnimatePresence>
    </div>
  );
}

function Chip({
  children,
  onClick,
  label,
}: {
  children: ReactNode;
  onClick: () => void;
  label: string;
}) {
  return (
    <button
      type="button"
      aria-label={label}
      onClick={onClick}
      className="flex h-7 items-center gap-1 rounded-md px-2 text-xs text-muted-foreground transition-colors hover:bg-[hsl(var(--muted))] hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
    >
      {children}
    </button>
  );
}
```

---

# Beat Mark

> A like button whose icon bursts and whose counter rolls on press.

Install: `npx @modus-ui/cli add beat-mark`

The default is a squared mono pill with a star mark on the muted surface.

## Installation

### CLI

```bash
npx @modus-ui/cli add beat-mark
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/beat-mark.tsx`.
3. Paste the code.

## Usage

```tsx
import { BeatMark } from "@/components/ui/beat-mark";

export default function Example() {
  return <BeatMark />;
}
```

## Props

| Prop         | Type    | Default                        | Description                               |
| :----------- | :------ | :----------------------------- | :---------------------------------------- |
| liked        | any     | -                              | Controlled liked state.                   |
| defaultLiked | boolean | false                          | Initial liked state when uncontrolled.    |
| count        | number  | 128                            | Count before your like.                   |
| onChange     | any     | -                              | Called with the new liked state.          |
| showCount    | boolean | true                           | Shows the rolling counter.                |
| icon         | string  | "star"                         | Mark shape: "star" or "heart".            |
| idleOutline  | boolean | true                           | Draws the idle mark as an outline.        |
| size         | number  | 40                             | Mark box size in pixels.                  |
| corner       | number  | 10                             | Pill corner radius in pixels.             |
| likedColor   | string  | "hsl(var(--primary))"          | Mark and burst colour when liked.         |
| idleColor    | string  | "hsl(var(--muted-foreground))" | Mark colour when idle.                    |
| pillColor    | string  | "hsl(var(--muted))"            | Pill background colour.                   |
| textColor    | string  | "hsl(var(--foreground))"       | Counter colour.                           |
| duration     | number  | 560                            | Pop and burst duration in milliseconds.   |
| dotSize      | number  | 0.3                            | Burst dot size as a fraction of the mark. |
| overshoot    | number  | 1.7                            | How far the mark overshoots as it pops.   |
| beat         | number  | 3                              | Burst dots per quarter turn.              |
| rollDuration | number  | 350                            | Counter roll duration in milliseconds.    |
| disabled     | boolean | false                          | Disables the button.                      |
| label        | string  | "Like"                         | Accessible label.                         |

## Source

`components/ui/beat-mark.tsx`

```tsx
"use client";
// Like pill: the mark pops with a ring of dots and the count rolls to its new value.

import { useState } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const MARKS = {
  star: "M12 2.8l2.8 5.7 6.3.9-4.55 4.43 1.07 6.27L12 17.1l-5.62 2.97 1.07-6.27L2.9 9.4l6.3-.9z",
  heart:
    "M12 20.5s-7.5-4.6-9.2-9.3C1.7 8 3.6 4.5 7.1 4.5c2 0 3.4 1.1 4.9 2.9 1.5-1.8 2.9-2.9 4.9-2.9 3.5 0 5.4 3.5 4.3 6.7-1.7 4.7-9.2 9.3-9.2 9.3z",
};

export interface BeatMarkProps {
  liked?: boolean;
  defaultLiked?: boolean;
  count?: number;
  onChange?: (liked: boolean) => void;
  showCount?: boolean;
  icon?: keyof typeof MARKS;
  idleOutline?: boolean;
  size?: number;
  corner?: number;
  likedColor?: string;
  idleColor?: string;
  pillColor?: string;
  textColor?: string;
  duration?: number;
  dotSize?: number;
  overshoot?: number;
  beat?: number;
  rollDuration?: number;
  disabled?: boolean;
  label?: string;
  className?: string;
}

export function BeatMark({
  liked,
  defaultLiked = false,
  count = 128,
  onChange,
  showCount = true,
  icon = "star",
  idleOutline = true,
  size = 40,
  corner = 10,
  likedColor = "hsl(var(--primary))",
  idleColor = "hsl(var(--muted-foreground))",
  pillColor = "hsl(var(--muted))",
  textColor = "hsl(var(--foreground))",
  duration = 560,
  dotSize = 0.3,
  overshoot = 1.7,
  beat = 3,
  rollDuration = 350,
  disabled = false,
  label = "Like",
  className,
}: BeatMarkProps) {
  const reduce = useReducedMotion();
  const [inner, setInner] = useState(defaultLiked);
  const [pops, setPops] = useState(0);
  const on = liked ?? inner;
  const shown = count + (on ? 1 : 0);
  const glyph = size * 0.6;
  const dots = Math.max(1, Math.round(beat)) * 4;
  const seconds = duration / 1000;

  const toggle = () => {
    const next = !on;
    if (liked === undefined) setInner(next);
    if (next) setPops((n) => n + 1);
    onChange?.(next);
  };

  return (
    <button
      type="button"
      aria-pressed={on}
      aria-label={label}
      disabled={disabled}
      onClick={toggle}
      className={cn(
        "inline-flex select-none items-center gap-2 pr-3 font-mono text-sm font-medium tabular-nums outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] disabled:opacity-50",
        className,
      )}
      style={{
        height: size + 10,
        paddingLeft: 5,
        borderRadius: corner,
        background: pillColor,
        color: textColor,
      }}
    >
      <span className="relative grid place-items-center" style={{ width: size, height: size }}>
        <AnimatePresence>
          {on && !reduce && (
            <span key={pops} className="pointer-events-none absolute inset-0">
              {Array.from({ length: dots }, (_, i) => {
                const a = (i / dots) * Math.PI * 2;
                const r = size * (i % 2 ? 0.62 : 0.78);
                return (
                  <motion.span
                    key={i}
                    className="absolute left-1/2 top-1/2 rounded-full"
                    style={{
                      width: glyph * dotSize,
                      height: glyph * dotSize,
                      marginLeft: (-glyph * dotSize) / 2,
                      marginTop: (-glyph * dotSize) / 2,
                      background: likedColor,
                    }}
                    initial={{ x: 0, y: 0, scale: 0.4, opacity: 1 }}
                    animate={{ x: Math.cos(a) * r, y: Math.sin(a) * r, scale: 0, opacity: 0 }}
                    transition={{ duration: seconds, ease: [0.2, 0.7, 0.3, 1] }}
                  />
                );
              })}
            </span>
          )}
        </AnimatePresence>
        <motion.svg
          key={on ? `on-${pops}` : "off"}
          viewBox="0 0 24 24"
          width={glyph}
          height={glyph}
          initial={on && !reduce ? { scale: 0.4 } : false}
          animate={{ scale: [0.4, 1 + (overshoot - 1) * 0.35, 1] }}
          transition={{ duration: reduce ? 0 : seconds * 0.8, times: [0, 0.45, 1] }}
        >
          <path
            d={MARKS[icon]}
            fill={on ? likedColor : idleOutline ? "none" : idleColor}
            stroke={on ? likedColor : idleColor}
            strokeWidth={1.6}
            strokeLinejoin="round"
          />
        </motion.svg>
      </span>
      {showCount && (
        <span className="relative inline-flex overflow-hidden" aria-live="polite">
          <AnimatePresence initial={false} mode="popLayout" custom={on}>
            <motion.span
              key={shown}
              custom={on}
              variants={{
                in: (up: boolean) => ({ y: up ? "100%" : "-100%", opacity: 0 }),
                rest: { y: 0, opacity: 1 },
                out: (up: boolean) => ({ y: up ? "-100%" : "100%", opacity: 0 }),
              }}
              initial="in"
              animate="rest"
              exit="out"
              transition={{ duration: reduce ? 0 : rollDuration / 1000, ease: [0.3, 0, 0.2, 1] }}
            >
              {shown}
            </motion.span>
          </AnimatePresence>
        </span>
      )}
    </button>
  );
}
```

---

# Polish Pane

> A frame that resolves an image from pixel mosaic to sharp as generation progresses.

Install: `npx @modus-ui/cli add polish-pane`

Status prints in a mono pill and the frame rests on the muted surface with tight corners.

## Installation

### CLI

```bash
npx @modus-ui/cli add polish-pane
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/polish-pane.tsx`.
3. Paste the code.

## Usage

```tsx
import { PolishPane } from "@/components/ui/polish-pane";

export default function Example() {
  return <PolishPane />;
}
```

## Props

| Prop          | Type    | Default                  | Description |
| :------------ | :------ | :----------------------- | :---------- |
| status        | string  | "generating"             | -           |
| children      | any     | -                        | -           |
| aspectRatio   | string  | "1 / 1"                  | -           |
| width         | number  | 320                      | -           |
| radius        | number  | 6                        | -           |
| background    | string  | "hsl(var(--muted))"      | -           |
| color         | string  | "hsl(var(--foreground))" | -           |
| stageDuration | number  | 400                      | -           |
| sweep         | boolean | true                     | -           |
| showStatus    | boolean | true                     | -           |
| hideAfter     | number  | 1200                     | -           |
| labels        | any     | DEFAULT_LABELS           | -           |
| retryLabel    | string  | "Retry"                  | -           |
| onRetry       | any     | -                        | -           |

## Source

`components/ui/polish-pane.tsx`

```tsx
"use client";
// An image frame that sharpens from a coarse mosaic as a generation advances.

import { useEffect, useState, type ReactNode } from "react";
import { AnimatePresence, motion, useReducedMotion } from "framer-motion";
import { HugeiconsIcon } from "@hugeicons/react";
import { RefreshIcon } from "@hugeicons/core-free-icons";
import { cn } from "@/lib/utils";

type Status = "generating" | "refining" | "done" | "error";

const DEFAULT_LABELS: Record<Status, string> = {
  generating: "Generating",
  refining: "Refining",
  done: "Done",
  error: "Failed",
};

// Mosaic cell sizes in px, coarse to fine. Each status walks its own slice.
const CELLS = [28, 20, 14, 10, 7, 5];
const RANGE: Record<Status, [number, number]> = {
  generating: [0, 2],
  refining: [3, 5],
  done: [6, 6],
  error: [2, 2],
};

export interface PolishPaneProps {
  status?: string;
  children?: ReactNode;
  aspectRatio?: string;
  width?: number;
  radius?: number;
  background?: string;
  color?: string;
  stageDuration?: number;
  sweep?: boolean;
  showStatus?: boolean;
  hideAfter?: number;
  labels?: Partial<Record<Status, string>>;
  retryLabel?: string;
  onRetry?: () => void;
  className?: string;
}

export function PolishPane({
  status = "generating",
  children,
  aspectRatio = "1 / 1",
  width = 320,
  radius = 6,
  background = "hsl(var(--muted))",
  color = "hsl(var(--foreground))",
  stageDuration = 400,
  sweep = true,
  showStatus = true,
  hideAfter = 1200,
  labels = DEFAULT_LABELS,
  retryLabel = "Retry",
  onRetry,
  className,
}: PolishPaneProps) {
  const prefersReduced = useReducedMotion();
  // Follow the setting only after hydration, so the first render matches the server's.
  const [reduce, setReduce] = useState(false);
  useEffect(() => setReduce(Boolean(prefersReduced)), [prefersReduced]);
  const state = (status in RANGE ? status : "generating") as Status;
  const [from, to] = RANGE[state];
  const [step, setStep] = useState(from);
  const [pillVisible, setPillVisible] = useState(true);

  useEffect(() => {
    setStep(from);
    if (from === to) return;
    const id = setInterval(() => setStep((s) => (s >= to ? from : s + 1)), stageDuration);
    return () => clearInterval(id);
  }, [from, to, stageDuration]);

  useEffect(() => {
    setPillVisible(true);
    if (state !== "done") return;
    const id = setTimeout(() => setPillVisible(false), hideAfter);
    return () => clearTimeout(id);
  }, [state, hideAfter]);

  const cell = CELLS[step];
  const busy = state === "generating" || state === "refining";
  const label = { ...DEFAULT_LABELS, ...labels }[state];

  return (
    <div
      className={cn("relative overflow-hidden", className)}
      style={{ width, aspectRatio, borderRadius: radius, background, color }}
      aria-busy={busy}
    >
      <div className="absolute inset-0">{children}</div>

      {/* Mosaic: a blur scaled to the cell size under a matching hairline grid. */}
      <motion.div
        aria-hidden
        className="pointer-events-none absolute inset-0"
        initial={false}
        animate={{ opacity: cell ? 1 : 0 }}
        transition={{ duration: reduce ? 0 : 0.4 }}
        style={{
          backdropFilter: `blur(${(cell ?? 0) / 2}px)`,
          WebkitBackdropFilter: `blur(${(cell ?? 0) / 2}px)`,
          backgroundImage: `linear-gradient(to right, hsl(var(--background) / 0.18) 1px, transparent 1px), linear-gradient(to bottom, hsl(var(--background) / 0.18) 1px, transparent 1px)`,
          backgroundSize: `${cell ?? 1}px ${cell ?? 1}px`,
        }}
      />

      {sweep && busy && !reduce && (
        <motion.div
          aria-hidden
          className="pointer-events-none absolute inset-y-0 w-1/3"
          style={{
            background:
              "linear-gradient(90deg, transparent, hsl(var(--background) / 0.35), transparent)",
          }}
          initial={{ left: "-35%" }}
          animate={{ left: "110%" }}
          transition={{ duration: 1.6, repeat: Infinity, ease: "easeInOut" }}
        />
      )}

      <AnimatePresence>
        {showStatus && pillVisible && (
          <motion.div
            key={state}
            initial={{ opacity: 0, y: reduce ? 0 : -4 }}
            animate={{ opacity: 1, y: 0 }}
            exit={{ opacity: 0 }}
            transition={{ duration: reduce ? 0 : 0.2 }}
            className="absolute left-2 top-2 flex items-center gap-2 rounded-[4px] bg-background/85 px-2 py-1 font-mono text-[10px] uppercase tracking-[0.16em] backdrop-blur"
            role="status"
          >
            <span
              className="size-1.5 rounded-full"
              style={{
                background:
                  state === "error"
                    ? "hsl(var(--destructive))"
                    : state === "done"
                      ? "hsl(var(--primary))"
                      : "currentColor",
              }}
            />
            {label}
          </motion.div>
        )}
      </AnimatePresence>

      {state === "error" && onRetry && (
        <button
          type="button"
          onClick={onRetry}
          className="absolute inset-x-0 bottom-3 mx-auto flex w-fit items-center gap-1.5 rounded-[4px] bg-background px-3 py-1.5 font-mono text-[11px] uppercase tracking-[0.12em] text-foreground shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
        >
          <HugeiconsIcon icon={RefreshIcon} size={12} />
          {retryLabel}
        </button>
      )}
    </div>
  );
}
```

---

# Stretch Toggle

> A segmented control whose thumb stretches and squashes as it travels.

Install: `npx @modus-ui/cli add stretch-toggle`

Mono uppercase labels sit on the muted track, and the thumb takes the page background.

## Installation

### CLI

```bash
npx @modus-ui/cli add stretch-toggle
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/stretch-toggle.tsx`.
3. Paste the code.

## Usage

```tsx
import { StretchToggle } from "@/components/ui/stretch-toggle";

export default function Example() {
  return <StretchToggle items={["Draft", "Review", "Publish"]} />;
}
```

## Props

| Prop            | Type    | Default                        | Description |
| :-------------- | :------ | :----------------------------- | :---------- |
| items           | any     | -                              | -           |
| value           | any     | -                              | -           |
| defaultValue    | any     | -                              | -           |
| onChange        | any     | -                              | -           |
| trackColor      | string  | "hsl(var(--muted))"            | -           |
| thumbColor      | string  | "hsl(var(--background))"       | -           |
| textColor       | string  | "hsl(var(--muted-foreground))" | -           |
| activeTextColor | string  | "hsl(var(--foreground))"       | -           |
| size            | string  | "md"                           | -           |
| radius          | number  | 6                              | -           |
| inset           | number  | 3                              | -           |
| equalSlots      | boolean | true                           | -           |
| stretch         | number  | 100                            | -           |
| squash          | number  | 3                              | -           |
| speed           | number  | 1                              | -           |
| glide           | number  | 75                             | -           |
| draggable       | boolean | true                           | -           |
| disabled        | boolean | false                          | -           |
| ariaLabel       | string  | "Toggle group"                 | -           |

## Source

`components/ui/stretch-toggle.tsx`

```tsx
"use client";
// Segmented control whose thumb stretches along its path and squashes as it travels.

import { useLayoutEffect, useRef, useState } from "react";
import { motion, useReducedMotion, useSpring, useTransform, useVelocity } from "framer-motion";
import { cn } from "@/lib/utils";

interface StretchToggleProps {
  items: string[];
  value?: string;
  defaultValue?: string;
  onChange?: (value: string) => void;
  trackColor?: string;
  thumbColor?: string;
  textColor?: string;
  activeTextColor?: string;
  size?: "sm" | "md" | "lg";
  radius?: number;
  inset?: number;
  equalSlots?: boolean;
  /** How much the thumb lengthens with speed, in percent. */
  stretch?: number;
  /** How much it thins with speed, in percent. */
  squash?: number;
  speed?: number;
  /** Higher glides longer before settling (0–100). */
  glide?: number;
  draggable?: boolean;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

const SIZES = { sm: "h-8 px-3 text-[10px]", md: "h-10 px-4 text-xs", lg: "h-12 px-6 text-sm" };

export function StretchToggle({
  items,
  value,
  defaultValue,
  onChange,
  trackColor = "hsl(var(--muted))",
  thumbColor = "hsl(var(--background))",
  textColor = "hsl(var(--muted-foreground))",
  activeTextColor = "hsl(var(--foreground))",
  size = "md",
  radius = 6,
  inset = 3,
  equalSlots = true,
  stretch = 100,
  squash = 3,
  speed = 1,
  glide = 75,
  draggable = true,
  disabled = false,
  ariaLabel = "Toggle group",
  className,
}: StretchToggleProps) {
  const reduced = useReducedMotion();
  const [inner, setInner] = useState(defaultValue ?? items[0]);
  const current = value ?? inner;
  const slots = useRef<(HTMLButtonElement | null)[]>([]);
  const dragging = useRef(false);

  const spring = reduced
    ? { duration: 0 }
    : { stiffness: 380 * speed * speed, damping: 42 - glide * 0.3, mass: 1 };
  const x = useSpring(0, spring);
  const width = useSpring(0, spring);
  const pace = useTransform(useVelocity(x), (v) => Math.min(Math.abs(v) / 2000, 1));
  const scaleX = useTransform(pace, (p) => 1 + (p * stretch) / 200);
  const scaleY = useTransform(pace, (p) => 1 - (p * squash) / 10);

  const select = (next: string) => {
    if (disabled || next === current) return;
    if (value === undefined) setInner(next);
    onChange?.(next);
  };

  useLayoutEffect(() => {
    const el = slots.current[items.indexOf(current)];
    if (!el) return;
    if (width.get() === 0) {
      x.jump(el.offsetLeft);
      width.jump(el.offsetWidth);
    } else {
      x.set(el.offsetLeft);
      width.set(el.offsetWidth);
    }
  }, [current, items, x, width, size, equalSlots]);

  const pick = (clientX: number) => {
    const hit = slots.current.findIndex((el) => {
      const r = el?.getBoundingClientRect();
      return r && clientX >= r.left && clientX <= r.right;
    });
    if (hit >= 0) select(items[hit]);
  };

  return (
    <div
      role="radiogroup"
      aria-label={ariaLabel}
      aria-disabled={disabled}
      className={cn(
        "relative font-mono uppercase tracking-[0.16em]",
        equalSlots ? "inline-grid auto-cols-fr grid-flow-col" : "inline-flex",
        disabled && "opacity-50",
        className,
      )}
      style={{
        background: trackColor,
        borderRadius: radius + inset,
        padding: inset,
        touchAction: "pan-y",
      }}
      onPointerDown={() => draggable && (dragging.current = true)}
      onPointerMove={(e) => dragging.current && pick(e.clientX)}
      onPointerUp={() => (dragging.current = false)}
      onPointerLeave={() => (dragging.current = false)}
      onKeyDown={(e) => {
        const step = e.key === "ArrowRight" ? 1 : e.key === "ArrowLeft" ? -1 : 0;
        if (!step) return;
        e.preventDefault();
        const i = (items.indexOf(current) + step + items.length) % items.length;
        select(items[i]);
        slots.current[i]?.focus();
      }}
    >
      <motion.span
        aria-hidden
        className="absolute left-0 shadow-sm"
        style={{
          top: inset,
          bottom: inset,
          x,
          width,
          scaleX,
          scaleY,
          background: thumbColor,
          borderRadius: radius,
        }}
      />
      {items.map((item, i) => (
        <button
          key={item}
          ref={(el) => {
            slots.current[i] = el;
          }}
          type="button"
          role="radio"
          aria-checked={item === current}
          tabIndex={item === current ? 0 : -1}
          disabled={disabled}
          onClick={() => select(item)}
          className={cn(
            "relative z-10 whitespace-nowrap outline-none transition-colors focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
            SIZES[size],
          )}
          style={{ color: item === current ? activeTextColor : textColor, borderRadius: radius }}
        >
          {item}
        </button>
      ))}
    </div>
  );
}
```

---

# Drag Number

> A compact number chip you scrub sideways to change, with a rubber-band edge and a delta tag.

Install: `npx @modus-ui/cli add drag-number`

Labels sit in mono caps on a muted chip; the fill and change tag follow your theme's primary colour. Hold Shift for coarse steps, Alt for fine ones, or click to type a value.

## Installation

### CLI

```bash
npx @modus-ui/cli add drag-number
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/drag-number.tsx`.
3. Paste the code.

## Usage

```tsx
import { DragNumber } from "@/components/ui/drag-number";

export default function Example() {
  return <DragNumber />;
}
```

## Props

| Prop             | Type    | Default               | Description                                            |
| :--------------- | :------ | :-------------------- | :----------------------------------------------------- |
| label            | string  | "Weight"              | Caption on the chip.                                   |
| suffix           | string  | "pt"                  | Unit after the value.                                  |
| value            | any     | -                     | Controlled value.                                      |
| defaultValue     | number  | 42                    | Initial value; also the clean value for the dirty dot. |
| min              | number  | 0                     | Lowest value.                                          |
| max              | number  | 100                   | Highest value.                                         |
| step             | number  | 1                     | Change per step.                                       |
| size             | string  | "md"                  | Size: "sm", "md" or "lg".                              |
| sensitivity      | number  | 2                     | Pixels of drag per step.                               |
| rubberReach      | number  | 8                     | Furthest stretch past a limit, in pixels.              |
| returnDuration   | number  | 300                   | Spring back duration in milliseconds.                  |
| coarseMultiplier | number  | 10                    | Step multiplier while Shift is held.                   |
| fineMultiplier   | number  | 0.1                   | Step multiplier while Alt is held.                     |
| showDelta        | boolean | true                  | Shows the change while dragging.                       |
| showDirty        | boolean | true                  | Marks a value that differs from the default.           |
| showFill         | boolean | true                  | Shows the value as a fill.                             |
| accent           | string  | "hsl(var(--primary))" | Fill, delta and dot colour.                            |
| chipColor        | string  | "hsl(var(--muted))"   | Chip background.                                       |
| disabled         | boolean | false                 | Disables the chip.                                     |
| onChange         | any     | -                     | Called with each new value.                            |
| onCommit         | any     | -                     | Called when a drag, key step or typed value lands.     |

## Source

`components/ui/drag-number.tsx`

```tsx
"use client";
// Scrubbable number chip: drag sideways to change, stretch past the limits, click to type.

import { useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
import { animate, AnimatePresence, motion, useMotionValue, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const SIZES = {
  sm: "h-7 gap-2 px-2 text-[10px]",
  md: "h-8 gap-3 px-2.5 text-[11px]",
  lg: "h-10 gap-3 px-3 text-xs",
};

const decimals = (n: number) => (String(n).split(".")[1] ?? "").length;
const show = (n: number) => String(Number(n.toFixed(6)));

export interface DragNumberProps {
  label?: string;
  suffix?: string;
  value?: number;
  defaultValue?: number;
  min?: number;
  max?: number;
  step?: number;
  size?: keyof typeof SIZES;
  sensitivity?: number;
  rubberReach?: number;
  returnDuration?: number;
  coarseMultiplier?: number;
  fineMultiplier?: number;
  showDelta?: boolean;
  showDirty?: boolean;
  showFill?: boolean;
  accent?: string;
  chipColor?: string;
  disabled?: boolean;
  onChange?: (value: number) => void;
  onCommit?: (value: number) => void;
  className?: string;
}

export function DragNumber({
  label = "Weight",
  suffix = "pt",
  value,
  defaultValue = 42,
  min = 0,
  max = 100,
  step = 1,
  size = "md",
  sensitivity = 2,
  rubberReach = 8,
  returnDuration = 300,
  coarseMultiplier = 10,
  fineMultiplier = 0.1,
  showDelta = true,
  showDirty = true,
  showFill = true,
  accent = "hsl(var(--primary))",
  chipColor = "hsl(var(--muted))",
  disabled = false,
  onChange,
  onCommit,
  className,
}: DragNumberProps) {
  const reduce = useReducedMotion();
  const [inner, setInner] = useState(defaultValue);
  const [draft, setDraft] = useState<string | null>(null);
  const [delta, setDelta] = useState<number | null>(null);
  const current = value ?? inner;
  const stretch = useMotionValue(0);
  const drag = useRef<{ x: number; start: number; moved: boolean } | null>(null);
  const places = decimals(step) + decimals(fineMultiplier);

  const set = (n: number) => {
    const next = Number(Math.min(max, Math.max(min, n)).toFixed(places));
    if (value === undefined) setInner(next);
    if (next !== current) onChange?.(next);
    return next;
  };

  const unit = (e: { shiftKey: boolean; altKey: boolean }) =>
    step * (e.shiftKey ? coarseMultiplier : e.altKey ? fineMultiplier : 1);

  const down = (e: PointerEvent<HTMLDivElement>) => {
    if (disabled || draft !== null) return;
    e.currentTarget.setPointerCapture(e.pointerId);
    drag.current = { x: e.clientX, start: current, moved: false };
  };

  const move = (e: PointerEvent) => {
    const d = drag.current;
    if (!d) return;
    const px = e.clientX - d.x;
    if (Math.abs(px) > 3) d.moved = true;
    if (!d.moved) return;
    const u = unit(e);
    const raw = d.start + Math.round(px / sensitivity) * u;
    const next = set(Math.round(raw / u) * u);
    setDelta(next - d.start);
    // Past a limit the chip stretches, easing toward rubberReach pixels.
    const over = raw < min ? raw - min : raw > max ? raw - max : 0;
    stretch.set(rubberReach * Math.tanh(((over / u) * sensitivity) / (rubberReach * 4)));
  };

  const up = () => {
    const d = drag.current;
    drag.current = null;
    if (!d) return;
    animate(
      stretch,
      0,
      reduce ? { duration: 0 } : { type: "spring", duration: returnDuration / 1000, bounce: 0.3 },
    );
    setDelta(null);
    if (d.moved) onCommit?.(current);
    else setDraft(show(current));
  };

  const finish = (keep: boolean) => {
    if (keep && draft !== null && draft.trim() !== "" && !Number.isNaN(Number(draft)))
      onCommit?.(set(Number(draft)));
    setDraft(null);
  };

  const key = (e: KeyboardEvent) => {
    const dir =
      e.key === "ArrowRight" || e.key === "ArrowUp"
        ? 1
        : e.key === "ArrowLeft" || e.key === "ArrowDown"
          ? -1
          : 0;
    if (e.key === "Enter") return setDraft(show(current));
    if (!dir) return;
    e.preventDefault();
    onCommit?.(set(current + dir * unit(e)));
  };

  const pct = ((current - min) / (max - min || 1)) * 100;

  return (
    <motion.div
      role="slider"
      tabIndex={disabled ? -1 : 0}
      aria-label={label}
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={current}
      aria-disabled={disabled || undefined}
      onPointerDown={down}
      onPointerMove={move}
      onPointerUp={up}
      onPointerCancel={up}
      onKeyDown={draft === null ? key : undefined}
      style={{ x: stretch, background: chipColor }}
      className={cn(
        "relative inline-flex w-36 cursor-ew-resize touch-none select-none items-center overflow-hidden rounded-md font-mono uppercase tracking-[0.14em] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
        SIZES[size],
        disabled && "cursor-not-allowed opacity-50",
        className,
      )}
    >
      {showFill && (
        <motion.span
          aria-hidden
          className="absolute inset-y-0 left-0 opacity-20"
          style={{ background: accent }}
          animate={{ width: `${pct}%` }}
          transition={{ duration: reduce ? 0 : 0.12 }}
        />
      )}
      <span className="relative flex items-center gap-1.5 text-[hsl(var(--muted-foreground))]">
        {label}
        {showDirty && current !== defaultValue && (
          <span className="size-1 rounded-full" style={{ background: accent }} />
        )}
      </span>
      <span className="relative ml-auto flex items-baseline gap-1 normal-case tracking-normal">
        <AnimatePresence>
          {showDelta && delta !== null && delta !== 0 && (
            <motion.span
              className="text-[9px] tabular-nums"
              style={{ color: accent }}
              initial={{ opacity: 0, y: reduce ? 0 : 4 }}
              animate={{ opacity: 1, y: 0 }}
              exit={{ opacity: 0 }}
            >
              {delta > 0 ? "+" : ""}
              {show(delta)}
            </motion.span>
          )}
        </AnimatePresence>
        {draft !== null ? (
          <input
            autoFocus
            value={draft}
            onChange={(e) => setDraft(e.target.value)}
            onBlur={() => finish(true)}
            onKeyDown={(e) => {
              if (e.key === "Enter") finish(true);
              if (e.key === "Escape") finish(false);
            }}
            inputMode="decimal"
            aria-label={`${label} value`}
            className="w-12 bg-transparent text-right tabular-nums text-[hsl(var(--foreground))] outline-none"
          />
        ) : (
          <span className="tabular-nums text-[hsl(var(--foreground))]">{show(current)}</span>
        )}
        <span className="text-[hsl(var(--muted-foreground))]">{suffix}</span>
      </span>
    </motion.div>
  );
}
```

---

# Paper Mill

> A list of cards you drag into a slot that cuts them into falling strips.

Install: `npx @modus-ui/cli add paper-mill`

Built for discarding drafts with a little ceremony: the slot and strips take the foreground ink, and the cards are whatever you render. Reordering and keyboard delete are built in.

## Installation

### CLI

```bash
npx @modus-ui/cli add paper-mill
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/paper-mill.tsx`.
3. Paste the code.

## Usage

```tsx
import { PaperMill } from "@/components/ui/paper-mill";

export default function Example() {
  return <PaperMill />;
}
```

## Props

| Prop            | Type    | Default                  | Description |
| :-------------- | :------ | :----------------------- | :---------- |
| items           | any     | []                       | -           |
| renderItem      | any     | -                        | -           |
| onShred         | any     | -                        | -           |
| onReorder       | any     | -                        | -           |
| width           | number  | 340                      | -           |
| height          | number  | 460                      | -           |
| inset           | number  | 14                       | -           |
| gap             | number  | 10                       | -           |
| slitHeight      | number  | 4                        | -           |
| fallHeight      | number  | 140                      | -           |
| feedSpeed       | number  | 180                      | -           |
| bite            | number  | 18                       | -           |
| autoFeed        | boolean | true                     | -           |
| stripWidth      | number  | 10                       | -           |
| curl            | number  | 1                        | -           |
| autoAnimate     | boolean | false                    | -           |
| loop            | boolean | false                    | -           |
| loopAfterDelete | boolean | false                    | -           |
| dragTilt        | number  | 6                        | -           |
| lift            | number  | 1.02                     | -           |
| slitColor       | string  | "hsl(var(--foreground))" | -           |
| color           | string  | "hsl(var(--foreground))" | -           |
| disabled        | boolean | false                    | -           |

## Source

`components/ui/paper-mill.tsx`

```tsx
"use client";
// A reorderable stack of cards; drop one on the slot (or press Delete) and it is fed through into falling strips.

import { useEffect, useRef, useState, type ReactNode } from "react";
import { AnimatePresence, Reorder, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type MillItem = { id: string | number };

interface Shred<T> {
  item: T;
  top: number;
  height: number;
  key: number;
}

interface PaperMillProps<T extends MillItem> {
  items?: T[];
  renderItem?: (item: T) => ReactNode;
  onShred?: (item: T) => void;
  onReorder?: (items: T[]) => void;
  width?: number;
  height?: number;
  inset?: number;
  gap?: number;
  slitHeight?: number;
  /** Space under the slot the strips fall through. */
  fallHeight?: number;
  /** Feed rate through the slot, in px per second. */
  feedSpeed?: number;
  /** How far (px) the slot snatches a card the moment it lands. */
  bite?: number;
  /** Feed on its own after the bite; off waits for a click on the bitten card. */
  autoFeed?: boolean;
  stripWidth?: number;
  /** How much the strips twist as they fall. */
  curl?: number;
  /** Shred the bottom card on its own shortly after mount; with `loop`, keep going. */
  autoAnimate?: boolean;
  /** Refill from `items` when the stack runs out during auto-animation. */
  loop?: boolean;
  /** Refill from `items` when you empty the stack yourself. */
  loopAfterDelete?: boolean;
  dragTilt?: number;
  lift?: number;
  slitColor?: string;
  color?: string;
  disabled?: boolean;
  className?: string;
}

const defaultRender = (item: MillItem) => (
  <div className="rounded-md border border-border bg-card px-4 py-3 font-serif text-foreground">
    Item {String(item.id)}
  </div>
);

export function PaperMill<T extends MillItem>({
  items = [],
  renderItem = defaultRender,
  onShred,
  onReorder,
  width = 340,
  height = 460,
  inset = 14,
  gap = 10,
  slitHeight = 4,
  fallHeight = 140,
  feedSpeed = 180,
  bite = 18,
  autoFeed = true,
  stripWidth = 10,
  curl = 1,
  autoAnimate = false,
  loop = false,
  loopAfterDelete = false,
  dragTilt = 6,
  lift = 1.02,
  slitColor = "hsl(var(--foreground))",
  color = "hsl(var(--foreground))",
  disabled = false,
  className,
}: PaperMillProps<T>) {
  const reduce = useReducedMotion();
  const [stack, setStack] = useState(items);
  const [shreds, setShreds] = useState<(Shred<T> & { fed: boolean })[]>([]);
  const box = useRef<HTMLDivElement>(null);
  const nodes = useRef(new Map<T["id"], HTMLElement>());
  const serial = useRef(0);
  const slitY = height - fallHeight;
  const cardWidth = width - inset * 2;

  useEffect(() => setStack(items), [items]);

  const shred = (item: T, auto = false) => {
    const node = nodes.current.get(item.id);
    const frame = box.current?.getBoundingClientRect();
    const rect = node?.getBoundingClientRect();
    const top = rect && frame ? rect.top - frame.top : slitY - 60;
    const next = stack.filter((s) => s.id !== item.id);
    setStack(next.length === 0 && (auto ? loop : loopAfterDelete) ? items : next);
    setShreds((s) => [
      ...s,
      { item, top, height: rect?.height ?? 60, key: serial.current++, fed: autoFeed },
    ]);
    onShred?.(item);
  };

  const showed = useRef(false);
  useEffect(() => {
    if (!autoAnimate || disabled || (showed.current && !loop)) return;
    const id = setTimeout(() => {
      if (!stack.length) return;
      showed.current = true;
      shred(stack[stack.length - 1], true);
    }, 1800);
    return () => clearTimeout(id);
    // re-arms after every change to the stack
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [autoAnimate, disabled, loop, stack]);

  return (
    <div ref={box} className={cn("relative select-none", className)} style={{ width, height }}>
      <Reorder.Group
        axis="y"
        values={stack}
        onReorder={(next) => {
          setStack(next);
          onReorder?.(next);
        }}
        className="absolute m-0 flex list-none flex-col p-0"
        style={{ left: inset, right: inset, top: inset, gap, maxHeight: slitY - inset * 2 }}
      >
        {stack.map((item) => (
          <Reorder.Item
            key={item.id}
            value={item}
            ref={(el: HTMLLIElement | null) => {
              if (el) nodes.current.set(item.id, el);
              else nodes.current.delete(item.id);
            }}
            drag={!disabled}
            tabIndex={0}
            aria-label="Card. Press Delete to shred."
            onKeyDown={(e) => {
              if (!disabled && (e.key === "Delete" || e.key === "Backspace")) shred(item);
            }}
            onDragEnd={(_, info) => {
              const frame = box.current?.getBoundingClientRect();
              if (frame && info.point.y - window.scrollY > frame.top + slitY - 30) shred(item);
            }}
            whileDrag={reduce ? { scale: lift } : { scale: lift, rotate: dragTilt }}
            className="relative z-10 cursor-grab list-none rounded-md outline-none focus-visible:ring-2 focus-visible:ring-ring active:cursor-grabbing"
          >
            {renderItem(item)}
          </Reorder.Item>
        ))}
      </Reorder.Group>

      {/* The slot */}
      <div
        aria-hidden
        className="absolute rounded-full"
        style={{
          left: inset / 2,
          right: inset / 2,
          top: slitY,
          height: slitHeight,
          background: slitColor,
        }}
      />

      <AnimatePresence>
        {shreds.map((s) => {
          const feedTime = reduce ? 0 : s.height / feedSpeed;
          const strips = Math.max(1, Math.floor(cardWidth / stripWidth));
          return (
            <motion.div
              key={s.key}
              className="pointer-events-none absolute inset-0"
              exit={{ opacity: 0 }}
            >
              {/* Card above the slot, slid down and clipped at the slit. */}
              <div className="absolute inset-x-0 top-0 overflow-hidden" style={{ height: slitY }}>
                <motion.div
                  className="pointer-events-auto absolute"
                  style={{ left: inset, width: cardWidth }}
                  initial={{ top: s.top }}
                  animate={{ top: s.fed ? slitY : slitY - s.height + bite }}
                  transition={{
                    top: s.fed
                      ? { duration: feedTime + 0.25, ease: [0.4, 0, 0.6, 1] }
                      : { duration: 0.25 },
                  }}
                  onClick={() =>
                    setShreds((all) => all.map((o) => (o.key === s.key ? { ...o, fed: true } : o)))
                  }
                  onAnimationComplete={() => {
                    if (s.fed)
                      setTimeout(() => setShreds((all) => all.filter((o) => o.key !== s.key)), 900);
                  }}
                >
                  {renderItem(s.item)}
                </motion.div>
              </div>
              {/* Strips spilling out under the slot. */}
              {s.fed && (
                <div
                  className="absolute flex overflow-hidden"
                  style={{
                    left: inset,
                    width: cardWidth,
                    top: slitY + slitHeight,
                    height: fallHeight,
                  }}
                >
                  {Array.from({ length: strips }, (_, i) => (
                    <motion.span
                      key={i}
                      className="block shrink-0 origin-top"
                      style={{
                        width: stripWidth - 1,
                        marginRight: 1,
                        height: s.height * 0.8,
                        background: color,
                      }}
                      initial={{ y: -s.height * 0.8, opacity: 0.85 }}
                      animate={{
                        // Pushed out at feed speed, then dropped.
                        y: [-s.height * 0.8, 0, fallHeight],
                        opacity: [0.85, 0.85, 0],
                        rotate: reduce ? 0 : [0, 0, curl * (((i * 37) % 11) - 5)],
                      }}
                      transition={{
                        duration: feedTime + 0.8,
                        times: [0, feedTime / (feedTime + 0.8), 1],
                        delay: 0.25 + ((i * 13) % 7) * 0.02,
                        ease: ["linear", "easeIn"],
                      }}
                    />
                  ))}
                </div>
              )}
            </motion.div>
          );
        })}
      </AnimatePresence>
    </div>
  );
}
```

---

# Swipe Confirm

> A drag-to-confirm track for actions that should not happen by accident.

Install: `npx @modus-ui/cli add swipe-confirm`

The track sits on muted paper with a hairline border and mono caps. Return a promise from onConfirm to show a pending state, then a signed or failed state.

## Installation

### CLI

```bash
npx @modus-ui/cli add swipe-confirm
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/swipe-confirm.tsx`.
3. Paste the code.

## Usage

```tsx
import { SwipeConfirm } from "@/components/ui/swipe-confirm";

export default function Example() {
  return <SwipeConfirm />;
}
```

## Props

| Prop         | Type    | Default                         | Description |
| :----------- | :------ | :------------------------------ | :---------- |
| label        | string  | "Slide to sign"                 | -           |
| doneLabel    | string  | "Signed"                        | -           |
| errorLabel   | string  | "Could not sign"                | -           |
| onConfirm    | any     | -                               | -           |
| onDone       | any     | -                               | -           |
| onError      | any     | -                               | -           |
| trackColor   | string  | "hsl(var(--muted))"             | -           |
| handleColor  | string  | "hsl(var(--primary))"           | -           |
| successColor | string  | "hsl(var(--accent-foreground))" | -           |
| dangerColor  | string  | "hsl(var(--destructive))"       | -           |
| width        | number  | 280                             | -           |
| height       | number  | 56                              | -           |
| radius       | number  | 10                              | -           |
| speed        | number  | 50                              | -           |
| returnBounce | number  | 0.38                            | -           |
| landingDip   | number  | 0.026                           | -           |
| holdMs       | number  | 1500                            | -           |
| disabled     | boolean | false                           | -           |
| icon         | any     | -                               | -           |

## Source

`components/ui/swipe-confirm.tsx`

```tsx
"use client";
// Drag-to-confirm track; a promise from onConfirm drives pending, signed and failed states.

import { useEffect, useState } from "react";
import { animate, motion, useMotionValue, useReducedMotion, useTransform } from "framer-motion";
import { cn } from "@/lib/utils";

type Phase = "idle" | "pending" | "done" | "error";

interface SwipeConfirmProps {
  label?: string;
  doneLabel?: string;
  errorLabel?: string;
  onConfirm?: () => unknown;
  onDone?: () => void;
  onError?: (error: unknown) => void;
  trackColor?: string;
  handleColor?: string;
  successColor?: string;
  dangerColor?: string;
  width?: number;
  height?: number;
  radius?: number;
  /** Spring speed of the handle returning, 0–100. */
  speed?: number;
  returnBounce?: number;
  /** How far the handle dips in scale when it lands at the end. */
  landingDip?: number;
  holdMs?: number;
  disabled?: boolean;
  icon?: React.ReactNode;
  className?: string;
}

const PAD = 4;

export function SwipeConfirm({
  label = "Slide to sign",
  doneLabel = "Signed",
  errorLabel = "Could not sign",
  onConfirm,
  onDone,
  onError,
  trackColor = "hsl(var(--muted))",
  handleColor = "hsl(var(--primary))",
  successColor = "hsl(var(--accent-foreground))",
  dangerColor = "hsl(var(--destructive))",
  width = 280,
  height = 56,
  radius = 10,
  speed = 50,
  returnBounce = 0.38,
  landingDip = 0.026,
  holdMs = 1500,
  disabled = false,
  icon,
  className,
}: SwipeConfirmProps) {
  const reduced = useReducedMotion();
  const [phase, setPhase] = useState<Phase>("idle");
  const knob = height - PAD * 2;
  const travel = width - knob - PAD * 2;
  const x = useMotionValue(0);
  const labelOpacity = useTransform(x, [0, travel * 0.6], [1, 0]);
  const scale = useMotionValue(1);
  const back = reduced
    ? { duration: 0 }
    : { type: "spring" as const, visualDuration: 0.9 - speed * 0.007, bounce: returnBounce };

  useEffect(() => {
    if (phase !== "done" && phase !== "error") return;
    const t = setTimeout(() => {
      setPhase("idle");
      animate(x, 0, back);
    }, holdMs);
    return () => clearTimeout(t);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [phase, holdMs]);

  const confirm = async () => {
    animate(x, travel, reduced ? { duration: 0 } : { duration: 0.15 });
    if (!reduced) animate(scale, [1, 1 - landingDip * 4, 1], { duration: 0.3 });
    setPhase("pending");
    try {
      await onConfirm?.();
      setPhase("done");
      onDone?.();
    } catch (error) {
      setPhase("error");
      onError?.(error);
    }
  };

  const locked = disabled || phase !== "idle";
  const tone = phase === "done" ? successColor : phase === "error" ? dangerColor : handleColor;
  const text = phase === "done" ? doneLabel : phase === "error" ? errorLabel : label;

  return (
    <div
      className={cn(
        "relative select-none border border-[hsl(var(--border))] font-mono text-xs uppercase tracking-[0.16em]",
        disabled && "opacity-50",
        className,
      )}
      style={{ width, height, borderRadius: radius, background: trackColor }}
    >
      <motion.span
        aria-live="polite"
        className="absolute inset-0 flex items-center justify-center text-[hsl(var(--muted-foreground))]"
        style={{
          opacity: phase === "idle" ? labelOpacity : 1,
          paddingLeft: knob,
          color: phase === "idle" ? undefined : tone,
        }}
      >
        {phase === "pending" ? "…" : text}
      </motion.span>
      <motion.button
        type="button"
        role="slider"
        aria-label={label}
        aria-valuemin={0}
        aria-valuemax={100}
        aria-valuenow={phase === "idle" ? 0 : 100}
        disabled={locked}
        drag={locked ? false : "x"}
        dragConstraints={{ left: 0, right: travel }}
        dragElastic={0}
        dragMomentum={false}
        onDragEnd={() => (x.get() > travel * 0.9 ? confirm() : animate(x, 0, back))}
        onKeyDown={(e) => (e.key === "Enter" || e.key === "ArrowRight") && !locked && confirm()}
        className="absolute flex cursor-grab items-center justify-center outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] active:cursor-grabbing disabled:cursor-default"
        style={{
          left: PAD,
          top: PAD,
          width: knob,
          height: knob,
          x,
          scale,
          borderRadius: Math.max(0, radius - PAD),
          background: tone,
          color: "hsl(var(--primary-foreground))",
          touchAction: "none",
        }}
      >
        {phase === "pending" ? (
          <motion.span
            className="block h-4 w-4 rounded-full border-2 border-current border-t-transparent"
            animate={reduced ? {} : { rotate: 360 }}
            transition={{ duration: 0.8, ease: "linear", repeat: Infinity }}
          />
        ) : (
          (icon ?? (
            <svg
              width="18"
              height="18"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              strokeWidth="2"
              strokeLinecap="round"
              strokeLinejoin="round"
              aria-hidden
            >
              {phase === "done" ? (
                <path d="M5 12.5l4.5 4.5L19 7.5" />
              ) : phase === "error" ? (
                <path d="M7 7l10 10M17 7L7 17" />
              ) : (
                <path d="M5 12h14M13 6l6 6-6 6" />
              )}
            </svg>
          ))
        )}
      </motion.button>
    </div>
  );
}
```

---

# Pull Launch

> A send button you can pull back like a slingshot and release.

Install: `npx @modus-ui/cli add pull-launch`

A squircle pad in the primary colour stretches a band across a muted well, then fires a burst of particles when sent. Tapping or Enter sends too.

## Installation

### CLI

```bash
npx @modus-ui/cli add pull-launch
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pull-launch.tsx`.
3. Paste the code.

## Usage

```tsx
import { PullLaunch } from "@/components/ui/pull-launch";

export default function Example() {
  return <PullLaunch />;
}
```

## Props

| Prop        | Type    | Default                          | Description |
| :---------- | :------ | :------------------------------- | :---------- |
| children    | any     | -                                | -           |
| onSend      | any     | -                                | -           |
| padColor    | string  | "hsl(var(--primary))"            | -           |
| iconColor   | string  | "hsl(var(--primary-foreground))" | -           |
| accentColor | string  | "hsl(var(--primary))"            | -           |
| wellColor   | string  | "hsl(var(--muted))"              | -           |
| bandColor   | string  | "hsl(var(--muted-foreground))"   | -           |
| size        | number  | 56                               | -           |
| strokeWidth | number  | 3                                | -           |
| armAt       | number  | 48                               | -           |
| maxPull     | number  | 160                              | -           |
| launchSpeed | number  | 2600                             | -           |
| recoil      | number  | 0.2                              | -           |
| flight      | number  | 120                              | -           |
| particles   | number  | 14                               | -           |
| spread      | number  | 60                               | -           |
| axis        | string  | "any"                            | -           |
| tapSends    | boolean | true                             | -           |
| disabled    | boolean | false                            | -           |
| ariaLabel   | string  | "Send"                           | -           |

## Source

`components/ui/pull-launch.tsx`

```tsx
"use client";
// A send pad you pull back like a slingshot; releasing past the arm point fires it.

import { useRef, useState, type ReactNode } from "react";
import { animate, motion, useMotionValue, useReducedMotion, useTransform } from "framer-motion";
import { HugeiconsIcon } from "@hugeicons/react";
import { ArrowUp02Icon } from "@hugeicons/core-free-icons";
import { cn } from "@/lib/utils";

export interface PullLaunchProps {
  children?: ReactNode;
  onSend?: () => void;
  padColor?: string;
  iconColor?: string;
  accentColor?: string;
  wellColor?: string;
  bandColor?: string;
  size?: number;
  strokeWidth?: number;
  armAt?: number;
  maxPull?: number;
  launchSpeed?: number;
  recoil?: number;
  flight?: number;
  particles?: number;
  spread?: number;
  axis?: "any" | "x" | "y";
  tapSends?: boolean;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

interface Burst {
  key: number;
  angle: number; // radians, direction of travel
}

export function PullLaunch({
  children,
  onSend,
  padColor = "hsl(var(--primary))",
  iconColor = "hsl(var(--primary-foreground))",
  accentColor = "hsl(var(--primary))",
  wellColor = "hsl(var(--muted))",
  bandColor = "hsl(var(--muted-foreground))",
  size = 56,
  strokeWidth = 3,
  armAt = 48,
  maxPull = 160,
  launchSpeed = 2600,
  recoil = 0.2,
  flight = 120,
  particles = 14,
  spread = 60,
  axis = "any",
  tapSends = true,
  disabled = false,
  ariaLabel = "Send",
  className,
}: PullLaunchProps) {
  const reduce = useReducedMotion();
  const x = useMotionValue(0);
  const y = useMotionValue(0);
  const dist = useTransform([x, y], ([a, b]: number[]) => Math.hypot(a, b));
  const bandOpacity = useTransform(dist, [0, 6], [0, 1]);
  const bandX = useTransform(x, (v) => size * 1.1 + v);
  const bandY = useTransform(y, (v) => size * 1.1 + v);
  const [burst, setBurst] = useState<Burst | null>(null);
  const flying = useRef(false);
  const box = size * 2.2;
  const c = box / 2;

  const home = () =>
    Promise.all([
      animate(x, 0, { type: "spring", bounce: recoil, duration: 0.5 }),
      animate(y, 0, { type: "spring", bounce: recoil, duration: 0.5 }),
    ]);

  const fire = async (angle: number) => {
    if (disabled || flying.current) return;
    flying.current = true;
    onSend?.();
    setBurst({ key: Date.now(), angle });
    if (!reduce) {
      const t = Math.max(0.08, (flight + Math.hypot(x.get(), y.get())) / launchSpeed);
      await Promise.all([
        animate(x, Math.cos(angle) * flight, { duration: t, ease: "easeIn" }),
        animate(y, Math.sin(angle) * flight, { duration: t, ease: "easeIn" }),
      ]);
      x.jump(0);
      y.jump(0);
    } else {
      await home();
    }
    flying.current = false;
  };

  const release = () => {
    const d = Math.hypot(x.get(), y.get());
    if (d >= armAt) fire(Math.atan2(-y.get(), -x.get()));
    else home();
  };

  return (
    <div
      className={cn("relative grid place-items-center", className)}
      style={{ width: box, height: box }}
    >
      <div
        className="absolute rounded-full"
        style={{ width: size * 1.3, height: size * 1.3, background: wellColor }}
      />
      <svg
        className="pointer-events-none absolute inset-0 overflow-visible"
        width={box}
        height={box}
      >
        <motion.line
          x1={c}
          y1={c}
          x2={bandX}
          y2={bandY}
          stroke={bandColor}
          strokeWidth={strokeWidth}
          strokeLinecap="round"
          style={{ opacity: bandOpacity }}
        />
      </svg>

      {burst &&
        Array.from({ length: particles }, (_, i) => {
          const a = burst.angle + ((i / Math.max(particles - 1, 1) - 0.5) * spread * Math.PI) / 180;
          const r = flight * (0.5 + ((i * 37) % 10) / 20);
          return (
            <motion.span
              key={`${burst.key}-${i}`}
              aria-hidden
              className="pointer-events-none absolute size-1.5 rounded-full"
              style={{ background: accentColor, left: c - 3, top: c - 3 }}
              initial={{ x: 0, y: 0, opacity: 1, scale: 1 }}
              animate={
                reduce
                  ? { opacity: 0 }
                  : { x: Math.cos(a) * r, y: Math.sin(a) * r, opacity: 0, scale: 0.3 }
              }
              transition={{ duration: 0.6, ease: "easeOut" }}
            />
          );
        })}

      <motion.button
        type="button"
        aria-label={ariaLabel}
        title="Press Enter to send, or drag away and release."
        disabled={disabled}
        drag={disabled ? false : axis === "any" ? true : axis}
        dragConstraints={{ left: -maxPull, right: maxPull, top: -maxPull, bottom: maxPull }}
        dragElastic={0.15}
        dragMomentum={false}
        onDragEnd={release}
        onTap={() => tapSends && fire(-Math.PI / 2)}
        onKeyDown={(e) => {
          if (e.key === "Enter") {
            e.preventDefault();
            fire(-Math.PI / 2);
          }
        }}
        whileTap={reduce ? undefined : { scale: 0.94 }}
        className="relative grid touch-none place-items-center shadow-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 disabled:opacity-50"
        style={{
          x,
          y,
          width: size,
          height: size,
          borderRadius: size * 0.32,
          background: padColor,
          color: iconColor,
        }}
      >
        {children ?? <HugeiconsIcon icon={ArrowUp02Icon} size={size * 0.4} />}
      </motion.button>
    </div>
  );
}
```

---

# Tide Meter

> A vertical level meter whose fill sloshes as it moves.

Install: `npx @modus-ui/cli add tide-meter`

The vessel is a muted column with a hairline edge, filled with the primary colour and read out in mono numerals. Drag or use arrow keys to set the level.

## Installation

### CLI

```bash
npx @modus-ui/cli add tide-meter
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tide-meter.tsx`.
3. Paste the code.

## Usage

```tsx
import { TideMeter } from "@/components/ui/tide-meter";

export default function Example() {
  return <TideMeter />;
}
```

## Props

| Prop         | Type    | Default               | Description |
| :----------- | :------ | :-------------------- | :---------- |
| value        | any     | -                     | -           |
| defaultValue | number  | 60                    | -           |
| onChange     | any     | -                     | -           |
| interactive  | boolean | true                  | -           |
| showValue    | boolean | true                  | -           |
| disabled     | boolean | false                 | -           |
| liquidColor  | string  | "hsl(var(--primary))" | -           |
| glassColor   | string  | "hsl(var(--muted))"   | -           |
| width        | number  | 76                    | -           |
| height       | number  | 200                   | -           |
| radius       | number  | 12                    | -           |
| ticks        | number  | 4                     | -           |
| viscosity    | number  | 0.15                  | -           |
| tilt         | number  | 0.45                  | -           |
| splash       | number  | 0.42                  | -           |
| unit         | string  | "%"                   | -           |
| ariaLabel    | string  | "Level"               | -           |

## Source

`components/ui/tide-meter.tsx`

```tsx
"use client";
// Vertical level meter whose liquid surface tilts and sloshes as the level moves.

import { useEffect, useState } from "react";
import { motion, useReducedMotion, useSpring, useTransform, useVelocity } from "framer-motion";
import { cn } from "@/lib/utils";

interface TideMeterProps {
  value?: number;
  defaultValue?: number;
  onChange?: (value: number) => void;
  interactive?: boolean;
  showValue?: boolean;
  disabled?: boolean;
  liquidColor?: string;
  glassColor?: string;
  width?: number;
  height?: number;
  radius?: number;
  ticks?: number;
  /** 0–1: higher settles more slowly and heavily. */
  viscosity?: number;
  /** How far the surface leans with speed. */
  tilt?: number;
  /** How much the surface bulges with speed. */
  splash?: number;
  unit?: string;
  ariaLabel?: string;
  className?: string;
}

const clamp = (v: number) => Math.round(Math.max(0, Math.min(100, v)));

export function TideMeter({
  value,
  defaultValue = 60,
  onChange,
  interactive = true,
  showValue = true,
  disabled = false,
  liquidColor = "hsl(var(--primary))",
  glassColor = "hsl(var(--muted))",
  width = 76,
  height = 200,
  radius = 12,
  ticks = 4,
  viscosity = 0.15,
  tilt = 0.45,
  splash = 0.42,
  unit = "%",
  ariaLabel = "Level",
  className,
}: TideMeterProps) {
  const reduced = useReducedMotion();
  const [inner, setInner] = useState(defaultValue);
  const level = clamp(value ?? inner);
  const live = interactive && !disabled;

  const shown = useSpring(level, {
    stiffness: 120,
    damping: 6 + viscosity * 40,
    mass: 1 + viscosity * 3,
  });
  useEffect(() => {
    if (reduced) shown.jump(level);
    else shown.set(level);
  }, [level, reduced, shown]);
  const speed = useVelocity(shown);
  const surface = useTransform(() => {
    const y = height * (1 - shown.get() / 100);
    const v = Math.max(-1, Math.min(1, speed.get() / 300));
    const lean = v * tilt * width * 0.5;
    const bulge = -Math.abs(v) * splash * 16;
    return `M0 ${y + lean} Q${width / 2} ${y + bulge} ${width} ${y - lean} V${height} H0Z`;
  });
  const overClip = useTransform(shown, (v) => `inset(${100 - v}% 0 0 0)`);
  const readout = useTransform(shown, (v) => `${Math.round(v)}${unit}`);

  const set = (next: number) => {
    const v = clamp(next);
    if (value === undefined) setInner(v);
    onChange?.(v);
  };
  const fromPointer = (e: React.PointerEvent<HTMLDivElement>) => {
    const b = e.currentTarget.getBoundingClientRect();
    set(((b.bottom - e.clientY) / b.height) * 100);
  };

  return (
    <div
      role="slider"
      aria-label={ariaLabel}
      aria-valuemin={0}
      aria-valuemax={100}
      aria-valuenow={level}
      aria-valuetext={`${level}${unit}`}
      aria-disabled={disabled}
      aria-readonly={!interactive}
      tabIndex={live ? 0 : -1}
      className={cn(
        "relative overflow-hidden border border-[hsl(var(--border))] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
        live && "cursor-ns-resize",
        disabled && "opacity-50",
        className,
      )}
      style={{ width, height, borderRadius: radius, background: glassColor, touchAction: "none" }}
      onPointerDown={(e) => {
        if (!live) return;
        e.currentTarget.setPointerCapture(e.pointerId);
        fromPointer(e);
      }}
      onPointerMove={(e) =>
        live && e.currentTarget.hasPointerCapture(e.pointerId) && fromPointer(e)
      }
      onKeyDown={(e) => {
        if (!live) return;
        const step = {
          ArrowUp: 1,
          ArrowRight: 1,
          ArrowDown: -1,
          ArrowLeft: -1,
          PageUp: 10,
          PageDown: -10,
        }[e.key];
        if (e.key === "Home") set(0);
        else if (e.key === "End") set(100);
        else if (!step) return;
        else set(level + step * (e.shiftKey ? 10 : 1));
        e.preventDefault();
      }}
    >
      <svg className="absolute inset-0" width={width} height={height} aria-hidden>
        <motion.path d={surface} fill={liquidColor} />
        {Array.from({ length: ticks }, (_, i) => {
          const y = (height * (i + 1)) / (ticks + 1);
          return (
            <line
              key={i}
              x1={width - 12}
              x2={width}
              y1={y}
              y2={y}
              stroke="hsl(var(--muted-foreground))"
              strokeOpacity={0.4}
            />
          );
        })}
      </svg>
      {showValue &&
        [false, true].map((over) => (
          <motion.span
            key={String(over)}
            aria-hidden
            className="absolute inset-0 flex items-center justify-center font-mono text-xs tabular-nums"
            style={{
              color: over ? "hsl(var(--primary-foreground))" : "hsl(var(--foreground))",
              clipPath: over ? overClip : undefined,
            }}
          >
            {readout}
          </motion.span>
        ))}
    </div>
  );
}
```

---

# Tally Box

> A checkbox whose box springs full and strikes through its label.

Install: `npx @modus-ui/cli add tally-box`

Labels are set in the heading serif, the box is a near-square in the primary colour. Good for checklists where finishing an item should feel satisfying.

## Installation

### CLI

```bash
npx @modus-ui/cli add tally-box
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tally-box.tsx`.
3. Paste the code.

## Usage

```tsx
import { TallyBox } from "@/components/ui/tally-box";

export default function Example() {
  return <TallyBox />;
}
```

## Props

| Prop           | Type    | Default                          | Description |
| :------------- | :------ | :------------------------------- | :---------- |
| label          | string  | "Proof the galleys"              | -           |
| checked        | any     | -                                | -           |
| defaultChecked | boolean | false                            | -           |
| onChange       | any     | -                                | -           |
| disabled       | boolean | false                            | -           |
| color          | string  | "hsl(var(--foreground))"         | -           |
| fillColor      | string  | "hsl(var(--primary))"            | -           |
| checkColor     | string  | "hsl(var(--primary-foreground))" | -           |
| boxSize        | number  | 28                               | -           |
| boxRadius      | number  | 4                                | -           |
| fontSize       | number  | 20                               | -           |
| bounce         | number  | 0.2                              | -           |
| strikeLag      | number  | 0.12                             | -           |
| doneOpacity    | number  | 0.42                             | -           |
| strike         | string  | "left"                           | -           |
| ariaLabel      | any     | -                                | -           |

## Source

`components/ui/tally-box.tsx`

```tsx
"use client";
// Checkbox whose box springs full of colour and strikes through its serif label.

import { useId, useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface TallyBoxProps {
  label?: string;
  checked?: boolean;
  defaultChecked?: boolean;
  onChange?: (checked: boolean) => void;
  disabled?: boolean;
  color?: string;
  fillColor?: string;
  checkColor?: string;
  boxSize?: number;
  boxRadius?: number;
  fontSize?: number;
  bounce?: number;
  /** Seconds the strike waits after the box fills. */
  strikeLag?: number;
  doneOpacity?: number;
  /** Where the strike line grows from: "left", "right" or "center". */
  strike?: "left" | "right" | "center";
  ariaLabel?: string;
  className?: string;
}

export function TallyBox({
  label = "Proof the galleys",
  checked,
  defaultChecked = false,
  onChange,
  disabled = false,
  color = "hsl(var(--foreground))",
  fillColor = "hsl(var(--primary))",
  checkColor = "hsl(var(--primary-foreground))",
  boxSize = 28,
  boxRadius = 4,
  fontSize = 20,
  bounce = 0.2,
  strikeLag = 0.12,
  doneOpacity = 0.42,
  strike = "left",
  ariaLabel,
  className,
}: TallyBoxProps) {
  const reduced = useReducedMotion();
  const id = useId();
  const [inner, setInner] = useState(defaultChecked);
  const on = checked ?? inner;
  const spring = reduced ? { duration: 0 } : { type: "spring" as const, duration: 0.45, bounce };
  const origin = strike === "right" ? 1 : strike === "center" ? 0.5 : 0;

  const toggle = () => {
    if (disabled) return;
    if (checked === undefined) setInner(!on);
    onChange?.(!on);
  };

  return (
    <label
      htmlFor={id}
      className={cn(
        "inline-flex cursor-pointer select-none items-center gap-3 font-serif",
        disabled && "cursor-not-allowed opacity-50",
        className,
      )}
      style={{ color, fontSize }}
    >
      <input
        id={id}
        type="checkbox"
        className="peer sr-only"
        checked={on}
        disabled={disabled}
        onChange={toggle}
        aria-label={ariaLabel}
      />
      <span
        aria-hidden
        className="relative grid shrink-0 place-items-center overflow-hidden border-2 peer-focus-visible:ring-2 peer-focus-visible:ring-[hsl(var(--ring))] peer-focus-visible:ring-offset-2"
        style={{
          width: boxSize,
          height: boxSize * 0.94,
          borderRadius: boxRadius,
          borderColor: fillColor,
        }}
      >
        <motion.span
          className="absolute inset-0"
          style={{ background: fillColor }}
          initial={false}
          animate={{ scale: on ? 1 : 0 }}
          transition={spring}
        />
        <svg
          className="relative"
          width="62%"
          height="62%"
          viewBox="0 0 24 24"
          fill="none"
          stroke={checkColor}
          strokeWidth={3.2}
          strokeLinecap="round"
          strokeLinejoin="round"
        >
          <motion.path
            d="M4 12.5l5 5L20 6.5"
            initial={false}
            animate={{ pathLength: on ? 1 : 0, opacity: on ? 1 : 0 }}
            transition={{ duration: reduced ? 0 : 0.25, delay: on && !reduced ? 0.08 : 0 }}
          />
        </svg>
      </span>
      <motion.span
        className="relative"
        initial={false}
        animate={{ opacity: on ? doneOpacity : 1 }}
        transition={{ duration: reduced ? 0 : 0.3, delay: on && !reduced ? strikeLag : 0 }}
      >
        {label}
        <motion.span
          aria-hidden
          className="absolute inset-x-0 top-[55%] h-[2px]"
          style={{ background: "currentColor", originX: origin }}
          initial={false}
          animate={{ scaleX: on ? 1 : 0 }}
          transition={reduced ? { duration: 0 } : { ...spring, delay: on ? strikeLag : 0 }}
        />
      </motion.span>
    </label>
  );
}
```

---

# Press Toggle

> A switch whose thumb squashes and stretches as you drag or tap it.

Install: `npx @modus-ui/cli add press-toggle`

A rounded-rectangle track on muted paper fills with the primary colour when on; the label is set in mono caps.

## Installation

### CLI

```bash
npx @modus-ui/cli add press-toggle
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/press-toggle.tsx`.
3. Paste the code.

## Usage

```tsx
import { PressToggle } from "@/components/ui/press-toggle";

export default function Example() {
  return <PressToggle />;
}
```

## Props

| Prop           | Type    | Default               | Description |
| :------------- | :------ | :-------------------- | :---------- |
| checked        | any     | -                     | -           |
| defaultChecked | boolean | false                 | -           |
| onChange       | any     | -                     | -           |
| label          | string  | "Draft mode"          | -           |
| disabled       | boolean | false                 | -           |
| trackColor     | string  | "hsl(var(--muted))"   | -           |
| trackOnColor   | string  | "hsl(var(--primary))" | -           |
| thumbColor     | string  | ""                    | -           |
| thumbOnColor   | string  | ""                    | -           |
| width          | number  | 76                    | -           |
| height         | number  | 38                    | -           |
| radius         | number  | 10                    | -           |
| speed          | number  | 50                    | -           |
| stretch        | number  | 36                    | -           |
| hoverScale     | number  | 1.035                 | -           |
| colorDuration  | number  | 320                   | -           |
| ariaLabel      | any     | -                     | -           |
| id             | any     | -                     | -           |

## Source

`components/ui/press-toggle.tsx`

```tsx
"use client";
// A switch whose thumb squashes on press and stretches as it travels.

import { useEffect, useId, useRef, useState } from "react";
import { animate, motion, useMotionValue, useReducedMotion, useTransform } from "framer-motion";
import { cn } from "@/lib/utils";

export interface PressToggleProps {
  checked?: boolean;
  defaultChecked?: boolean;
  onChange?: (checked: boolean) => void;
  label?: string;
  disabled?: boolean;
  trackColor?: string;
  trackOnColor?: string;
  thumbColor?: string;
  thumbOnColor?: string;
  width?: number;
  height?: number;
  radius?: number;
  speed?: number;
  stretch?: number;
  hoverScale?: number;
  colorDuration?: number;
  ariaLabel?: string;
  id?: string;
  className?: string;
}

export function PressToggle({
  checked,
  defaultChecked = false,
  onChange,
  label = "Draft mode",
  disabled = false,
  trackColor = "hsl(var(--muted))",
  trackOnColor = "hsl(var(--primary))",
  thumbColor = "",
  thumbOnColor = "",
  width = 76,
  height = 38,
  radius = 10,
  speed = 50,
  stretch = 36,
  hoverScale = 1.035,
  colorDuration = 320,
  ariaLabel,
  id,
  className,
}: PressToggleProps) {
  const reduce = useReducedMotion();
  const autoId = useId();
  const [inner, setInner] = useState(defaultChecked);
  const on = checked ?? inner;

  const pad = 4;
  const thumb = height - pad * 2;
  const travel = width - thumb - pad * 2;

  const x = useMotionValue(on ? travel : 0);
  const press = useMotionValue(0); // 0 rest, 1 held
  // Stretch with distance from either end, squash while held.
  const scaleX = useTransform([x, press], ([v, p]: number[]) => {
    const mid = 1 - Math.abs((v / travel) * 2 - 1);
    return 1 + (mid * stretch) / 100 + p * 0.12;
  });
  const scaleY = useTransform(scaleX, (s) => 1 / Math.sqrt(s));
  const dragged = useRef(false);

  const settle = (next: boolean) => {
    const spring = { type: "spring" as const, stiffness: speed * 8, damping: 22 };
    animate(x, next ? travel : 0, reduce ? { duration: 0 } : spring);
    animate(press, 0, { duration: 0.15 });
  };

  useEffect(() => {
    settle(on);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [on, travel]);

  const commit = (next: boolean) => {
    settle(next);
    if (next === on) return;
    setInner(next);
    onChange?.(next);
  };

  const fill = on ? trackOnColor : trackColor;
  const knob = on
    ? thumbOnColor || "hsl(var(--primary-foreground))"
    : thumbColor || "hsl(var(--foreground))";
  const fade = { duration: reduce ? 0 : colorDuration / 1000 };

  return (
    <label
      htmlFor={id ?? autoId}
      className={cn(
        "inline-flex items-center gap-3",
        disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer",
        className,
      )}
    >
      <motion.button
        id={id ?? autoId}
        type="button"
        role="switch"
        aria-checked={on}
        aria-label={ariaLabel}
        disabled={disabled}
        onClick={() => {
          if (dragged.current) return;
          commit(!on);
        }}
        onPointerDown={() => {
          dragged.current = false;
          if (!disabled) animate(press, 1, { duration: reduce ? 0 : 0.12 });
        }}
        onPointerUp={() => !dragged.current && animate(press, 0, { duration: 0.15 })}
        whileHover={disabled || reduce ? undefined : { scale: hoverScale }}
        initial={false}
        animate={{ backgroundColor: fill }}
        transition={fade}
        className="relative shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 focus-visible:ring-offset-[hsl(var(--background))]"
        style={{ width, height, borderRadius: radius, padding: pad }}
      >
        <motion.span
          drag={disabled ? false : "x"}
          dragConstraints={{ left: 0, right: travel }}
          dragElastic={0.08}
          dragMomentum={false}
          onDragStart={() => (dragged.current = true)}
          onDragEnd={() => commit(x.get() > travel / 2)}
          initial={false}
          animate={{ backgroundColor: knob }}
          transition={fade}
          className="block touch-none shadow-sm"
          style={{
            x,
            scaleX,
            scaleY,
            width: thumb,
            height: thumb,
            borderRadius: Math.max(radius - pad, 2),
            originX: on ? 1 : 0,
          }}
        />
      </motion.button>
      {label && (
        <span className="font-mono text-[11px] uppercase tracking-[0.18em] text-foreground">
          {label}
        </span>
      )}
    </label>
  );
}
```

---

# State Glyph

> A small ring that shows pending, running, done, failed or cancelled with drawn transitions.

Install: `npx @modus-ui/cli add state-glyph`

Marks take the foreground ink, turn to the primary colour when done and the destructive colour on failure, with mono labels that strike through on completion.

## Installation

### CLI

```bash
npx @modus-ui/cli add state-glyph
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/state-glyph.tsx`.
3. Paste the code.

## Usage

```tsx
import { StateGlyph } from "@/components/ui/state-glyph";

export default function Example() {
  return <StateGlyph />;
}
```

## Props

| Prop         | Type    | Default                   | Description |
| :----------- | :------ | :------------------------ | :---------- |
| status       | string  | "pending"                 | -           |
| progress     | any     | -                         | -           |
| label        | any     | -                         | -           |
| color        | string  | "hsl(var(--foreground))"  | -           |
| doneColor    | string  | "hsl(var(--primary))"     | -           |
| errorColor   | string  | "hsl(var(--destructive))" | -           |
| size         | number  | 20                        | -           |
| strokeWidth  | number  | 2                         | -           |
| dashes       | number  | 12                        | -           |
| fontSize     | number  | 14                        | -           |
| spinDuration | number  | 1100                      | -           |
| arcLength    | number  | 0.68                      | -           |
| drawDuration | number  | 240                       | -           |
| fillOpacity  | number  | 0.14                      | -           |
| strike       | boolean | true                      | -           |
| strikeDelay  | number  | 60                        | -           |
| style        | any     | -                         | -           |

## Source

`components/ui/state-glyph.tsx`

```tsx
"use client";
// A small status ring (pending, running, done, failed, cancelled) with drawn marks and a mono label.

import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Status = "pending" | "running" | "done" | "failed" | "cancelled";

interface StateGlyphProps {
  status?: Status;
  /** 0–1 while running; omit for an indeterminate spinner. */
  progress?: number;
  label?: React.ReactNode;
  color?: string;
  doneColor?: string;
  errorColor?: string;
  size?: number;
  strokeWidth?: number;
  dashes?: number;
  fontSize?: number;
  spinDuration?: number;
  arcLength?: number;
  drawDuration?: number;
  fillOpacity?: number;
  strike?: boolean;
  strikeDelay?: number;
  style?: React.CSSProperties;
  className?: string;
}

const R = 9; // ring radius in a 24-unit viewBox
const CIRC = 2 * Math.PI * R;

export function StateGlyph({
  status = "pending",
  progress,
  label,
  color = "hsl(var(--foreground))",
  doneColor = "hsl(var(--primary))",
  errorColor = "hsl(var(--destructive))",
  size = 20,
  strokeWidth = 2,
  dashes = 12,
  fontSize = 14,
  spinDuration = 1100,
  arcLength = 0.68,
  drawDuration = 240,
  fillOpacity = 0.14,
  strike = true,
  strikeDelay = 60,
  style,
  className,
}: StateGlyphProps) {
  const reduced = useReducedMotion();
  const tint = status === "done" ? doneColor : status === "failed" ? errorColor : color;
  const draw = { duration: reduced ? 0 : drawDuration / 1000, ease: "easeOut" as const };
  const sw = (strokeWidth * 24) / size;
  const determinate = typeof progress === "number";
  const closed = status === "done" || status === "failed" || status === "cancelled";
  const mark = (d: string, delay = 0) => (
    <motion.path
      key={d}
      d={d}
      fill="none"
      strokeLinecap="round"
      initial={{ pathLength: 0 }}
      animate={{ pathLength: 1 }}
      transition={{ ...draw, delay: reduced ? 0 : delay }}
    />
  );

  return (
    <span
      role="status"
      aria-label={typeof label === "string" ? `${label}: ${status}` : status}
      className={cn(
        "inline-flex items-center gap-2 font-mono uppercase tracking-[0.14em]",
        className,
      )}
      style={{
        fontSize,
        color: status === "pending" ? "hsl(var(--muted-foreground))" : color,
        ...style,
      }}
    >
      <svg
        width={size}
        height={size}
        viewBox="0 0 24 24"
        stroke={tint}
        strokeWidth={sw}
        aria-hidden
      >
        {status === "pending" && (
          <circle
            cx={12}
            cy={12}
            r={R}
            fill="none"
            strokeDasharray={`${CIRC / dashes / 2} ${CIRC / dashes / 2}`}
            opacity={0.6}
          />
        )}
        {status === "running" &&
          (determinate ? (
            <>
              <circle cx={12} cy={12} r={R} fill="none" opacity={0.2} />
              <motion.circle
                cx={12}
                cy={12}
                r={R}
                fill="none"
                strokeLinecap="round"
                transform="rotate(-90 12 12)"
                animate={{ pathLength: Math.min(1, Math.max(0, progress)) }}
                transition={draw}
              />
            </>
          ) : (
            <motion.circle
              cx={12}
              cy={12}
              r={R}
              fill="none"
              strokeLinecap="round"
              style={{ originX: "50%", originY: "50%" }}
              initial={{ pathLength: arcLength }}
              animate={reduced ? {} : { rotate: 360 }}
              transition={{ duration: spinDuration / 1000, ease: "linear", repeat: Infinity }}
            />
          ))}
        {closed && (
          <>
            <motion.circle
              cx={12}
              cy={12}
              r={R}
              fill={tint}
              fillOpacity={fillOpacity}
              initial={{ pathLength: 0 }}
              animate={{ pathLength: 1 }}
              transition={draw}
            />
            {status === "done" && mark("M8 12.5l2.7 2.7L16 9.5", drawDuration / 1000)}
            {status === "failed" && [
              mark("M9 9l6 6", drawDuration / 1000),
              mark("M15 9l-6 6", drawDuration / 700),
            ]}
            {status === "cancelled" && mark("M8.5 12h7", drawDuration / 1000)}
          </>
        )}
      </svg>
      {label != null && (
        <span className="relative">
          {label}
          {strike && status === "done" && (
            <motion.span
              aria-hidden
              className="absolute inset-x-0 top-1/2 h-px origin-left"
              style={{ background: "currentColor" }}
              initial={{ scaleX: 0 }}
              animate={{ scaleX: 1 }}
              transition={{ ...draw, delay: reduced ? 0 : (drawDuration + strikeDelay) / 1000 }}
            />
          )}
        </span>
      )}
    </span>
  );
}
```

---

# Ledger Row

> A list row that glides aside on a swipe to reveal a drawer of actions, set like an entry in a printed ledger.

Install: `npx @modus-ui/cli add glide-ledger-row`

Card-coloured rows with serif copy and mono action labels sit on the paper; the drawer is a muted tone and the action takes the theme's primary ink. Swipe past the commit point to fire the first action outright.

## Installation

### CLI

```bash
npx @modus-ui/cli add glide-ledger-row
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/glide-ledger-row.tsx`.
3. Paste the code.

## Usage

```tsx
import { GlideLedgerRow } from "@/components/ui/glide-ledger-row";

export default function Example() {
  return (
    <GlideLedgerRow label="Folio 12">
      <span className="px-4 font-serif">Proof returned with notes</span>
    </GlideLedgerRow>
  );
}
```

## Props

| Prop          | Type    | Default                  | Description |
| :------------ | :------ | :----------------------- | :---------- |
| children      | any     | -                        | -           |
| actions       | any     | DEFAULT_ACTIONS          | -           |
| actionColor   | string  | "hsl(var(--primary))"    | -           |
| drawerColor   | string  | "hsl(var(--muted))"      | -           |
| rowColor      | string  | "hsl(var(--card))"       | -           |
| textColor     | string  | "hsl(var(--foreground))" | -           |
| height        | number  | 64                       | -           |
| radius        | number  | 16                       | -           |
| actionWidth   | number  | 80                       | -           |
| direction     | string  | "left"                   | -           |
| snapBounce    | number  | 0.2                      | -           |
| resistance    | number  | 0.55                     | -           |
| collapseMs    | number  | 200                      | -           |
| commitAt      | number  | 0.6                      | -           |
| fullSwipe     | boolean | true                     | -           |
| disabled      | boolean | false                    | -           |
| open          | any     | -                        | -           |
| onOpenChange  | any     | -                        | -           |
| onAction      | any     | -                        | -           |
| onCommit      | any     | -                        | -           |
| closeOnAction | boolean | true                     | -           |
| haptic        | boolean | true                     | -           |
| label         | string  | "Ledger entry"           | -           |
| style         | any     | -                        | -           |

## Source

`components/ui/glide-ledger-row.tsx`

```tsx
"use client";
// A ledger entry that slides aside on a swipe to show its actions; swipe far enough to fire the first one.

import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
import { animate, motion, useMotionValue, useReducedMotion, useTransform } from "framer-motion";
import { cn } from "@/lib/utils";

export interface LedgerAction {
  id: string;
  label: string;
}

const DEFAULT_ACTIONS: LedgerAction[] = [
  { id: "archive", label: "Archive" },
  { id: "flag", label: "Flag" },
];

interface GlideLedgerRowProps {
  children: ReactNode;
  actions?: LedgerAction[];
  actionColor?: string;
  drawerColor?: string;
  rowColor?: string;
  textColor?: string;
  height?: number;
  radius?: number;
  actionWidth?: number;
  /** Which way the row slides to open. */
  direction?: "left" | "right";
  snapBounce?: number;
  /** Rubber-band resistance past the drawer (0 = rigid, 1 = free). */
  resistance?: number;
  collapseMs?: number;
  /** Fraction of the row width past which a release fires the first action. */
  commitAt?: number;
  fullSwipe?: boolean;
  disabled?: boolean;
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  onAction?: (action: LedgerAction) => void;
  onCommit?: (action: LedgerAction) => void;
  closeOnAction?: boolean;
  haptic?: boolean;
  label?: string;
  style?: CSSProperties;
  className?: string;
}

export function GlideLedgerRow({
  children,
  actions = DEFAULT_ACTIONS,
  actionColor = "hsl(var(--primary))",
  drawerColor = "hsl(var(--muted))",
  rowColor = "hsl(var(--card))",
  textColor = "hsl(var(--foreground))",
  height = 64,
  radius = 16,
  actionWidth = 80,
  direction = "left",
  snapBounce = 0.2,
  resistance = 0.55,
  collapseMs = 200,
  commitAt = 0.6,
  fullSwipe = true,
  disabled = false,
  open,
  onOpenChange,
  onAction,
  onCommit,
  closeOnAction = true,
  haptic = true,
  label = "Ledger entry",
  style,
  className,
}: GlideLedgerRowProps) {
  const reduce = useReducedMotion();
  const box = useRef<HTMLDivElement>(null);
  const x = useMotionValue(0);
  const [innerOpen, setInnerOpen] = useState(false);
  const [gone, setGone] = useState(false);
  const isOpen = open ?? innerOpen;
  const sign = direction === "left" ? -1 : 1;
  const drawer = actionWidth * actions.length;
  const reveal = useTransform(x, (v) => Math.min(1, Math.abs(v) / drawer));

  const spring = reduce
    ? { duration: 0 }
    : { type: "spring" as const, bounce: snapBounce, duration: 0.4 };

  useEffect(() => {
    animate(x, isOpen ? sign * drawer : 0, spring);
    // spring is derived from props already listed
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [isOpen, sign, drawer]);

  const setOpen = (next: boolean) => {
    if (next === isOpen) return animate(x, next ? sign * drawer : 0, spring);
    setInnerOpen(next);
    onOpenChange?.(next);
  };

  const commit = async () => {
    const first = actions[0];
    if (!first) return;
    if (haptic) navigator.vibrate?.(12);
    await animate(x, sign * (box.current?.offsetWidth ?? 400), spring);
    onCommit?.(first);
    onAction?.(first);
    setGone(true);
  };

  const choose = (action: LedgerAction) => {
    onAction?.(action);
    if (closeOnAction) setOpen(false);
  };

  const release = (offset: number, velocity: number) => {
    const travel = Math.max(0, sign * x.get());
    const width = box.current?.offsetWidth ?? 400;
    if (fullSwipe && travel > width * commitAt) return void commit();
    const flicked = Math.abs(velocity) > 400 ? Math.sign(velocity) === sign : null;
    setOpen(flicked ?? (offset !== 0 && travel > drawer / 2));
  };

  return (
    <motion.div
      ref={box}
      aria-label={label}
      className={cn("relative w-full overflow-hidden", className)}
      style={{ borderRadius: radius, ...style }}
      initial={false}
      animate={gone ? { height: 0, opacity: 0 } : { height, opacity: 1 }}
      transition={{ duration: reduce ? 0 : collapseMs / 1000 }}
    >
      <motion.div
        className={cn(
          "absolute inset-y-0 flex",
          direction === "left" ? "right-0 flex-row-reverse" : "left-0",
        )}
        style={{ background: drawerColor, opacity: reveal }}
      >
        {actions.map((action, i) => (
          <button
            key={action.id}
            type="button"
            tabIndex={isOpen ? 0 : -1}
            onClick={() => choose(action)}
            className="h-full font-mono text-[10px] uppercase tracking-[0.14em] outline-none focus-visible:underline"
            style={{
              width: actionWidth,
              height,
              background: i === 0 ? actionColor : undefined,
              color: i === 0 ? "hsl(var(--primary-foreground))" : textColor,
            }}
          >
            {action.label}
          </button>
        ))}
      </motion.div>
      <motion.div
        role="button"
        tabIndex={disabled ? -1 : 0}
        aria-expanded={isOpen}
        aria-label={`${label}: ${isOpen ? "hide" : "show"} actions`}
        drag={disabled ? false : "x"}
        dragDirectionLock
        dragConstraints={
          direction === "left" ? { left: -drawer, right: 0 } : { left: 0, right: drawer }
        }
        dragElastic={resistance}
        dragMomentum={false}
        onDragEnd={(_, info) => release(info.offset.x, info.velocity.x)}
        onKeyDown={(e) => {
          if (e.key === "Enter" || e.key === " ") {
            e.preventDefault();
            setOpen(!isOpen);
          } else if (e.key === "Escape") setOpen(false);
        }}
        className="relative flex h-full cursor-grab touch-pan-y items-center outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring active:cursor-grabbing"
        style={{ x, background: rowColor, color: textColor, borderRadius: radius }}
      >
        {children}
      </motion.div>
    </motion.div>
  );
}
```

---

# Flick Notice

> A card-stock notice that slides in, burns down a thin primary fuse and flicks away under a swipe.

Install: `npx @modus-ui/cli add flick-notice`

The surface follows the theme's card and border tokens with a serif title, so it reads as a slip of paper rather than a system pill. Drag it past the swipe distance to dismiss, or hover to pause the fuse.

## Installation

### CLI

```bash
npx @modus-ui/cli add flick-notice
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/flick-notice.tsx`.
3. Paste the code.

## Usage

```tsx
import { FlickNotice } from "@/components/ui/flick-notice";

export default function Example() {
  return <FlickNotice title="Draft filed to the folio" />;
}
```

## Props

| Prop          | Type    | Default                    | Description                                      |
| :------------ | :------ | :------------------------- | :----------------------------------------------- |
| title         | string  | "Draft filed to the folio" | Serif headline.                                  |
| description   | string  | ""                         | Supporting line.                                 |
| icon          | any     | -                          | Optional leading icon.                           |
| actionLabel   | string  | ""                         | Label of the action button; empty hides it.      |
| onAction      | any     | -                          | Called when the action is pressed.               |
| open          | boolean | true                       | Whether the notice is shown.                     |
| onClose       | any     | -                          | Called when the notice leaves.                   |
| background    | string  | "hsl(var(--card))"         | Card colour.                                     |
| color         | string  | "hsl(var(--foreground))"   | Text colour.                                     |
| fuseColor     | string  | "hsl(var(--primary))"      | Fuse colour.                                     |
| width         | number  | 356                        | Width in pixels.                                 |
| radius        | number  | 12                         | Corner radius in pixels.                         |
| slideMs       | number  | 400                        | Entrance duration in milliseconds.               |
| settleBounce  | number  | 0.2                        | Entrance spring bounce.                          |
| swipeDistance | number  | 40                         | Drag distance that dismisses, in pixels.         |
| duration      | number  | 4000                       | Time before it leaves, in milliseconds; 0 stays. |
| fuse          | string  | "bottom"                   | Fuse edge: "top", "bottom" or "none".            |
| pauseOnHover  | boolean | true                       | Pauses the fuse while hovered.                   |
| closeButton   | boolean | false                      | Shows a close button.                            |
| inline        | boolean | false                      | Renders in flow instead of fixed to the corner.  |
| dismissible   | boolean | true                       | Allows swiping away.                             |

## Source

`components/ui/flick-notice.tsx`

```tsx
"use client";
// Paper notice that slides in, burns a fuse down to dismissal and can be swiped away sideways.

import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  animate,
  AnimatePresence,
  motion,
  useMotionValue,
  useReducedMotion,
  type AnimationPlaybackControls,
} from "framer-motion";
import { cn } from "@/lib/utils";

export interface FlickNoticeProps {
  title?: string;
  description?: string;
  icon?: ReactNode;
  actionLabel?: string;
  onAction?: () => void;
  open?: boolean;
  onClose?: () => void;
  background?: string;
  color?: string;
  fuseColor?: string;
  width?: number;
  radius?: number;
  slideMs?: number;
  settleBounce?: number;
  swipeDistance?: number;
  duration?: number;
  fuse?: "top" | "bottom" | "none";
  pauseOnHover?: boolean;
  closeButton?: boolean;
  inline?: boolean;
  dismissible?: boolean;
  className?: string;
}

export function FlickNotice({
  title = "Draft filed to the folio",
  description = "",
  icon,
  actionLabel = "",
  onAction,
  open = true,
  onClose,
  background = "hsl(var(--card))",
  color = "hsl(var(--foreground))",
  fuseColor = "hsl(var(--primary))",
  width = 356,
  radius = 12,
  slideMs = 400,
  settleBounce = 0.2,
  swipeDistance = 40,
  duration = 4000,
  fuse = "bottom",
  pauseOnHover = true,
  closeButton = false,
  inline = false,
  dismissible = true,
  className,
}: FlickNoticeProps) {
  const reduce = useReducedMotion();
  const [gone, setGone] = useState<0 | -1 | 1 | null>(null);
  const left = useMotionValue(1);
  const burn = useRef<AnimationPlaybackControls | null>(null);
  const closeRef = useRef(onClose);
  closeRef.current = onClose;
  const shown = open && gone === null;

  const close = (dir: -1 | 0 | 1) => {
    burn.current?.stop();
    setGone(dir);
    closeRef.current?.();
  };

  useEffect(() => {
    if (!open || duration <= 0) return;
    left.set(1);
    burn.current = animate(left, 0, {
      duration: duration / 1000,
      ease: "linear",
      onComplete: () => {
        setGone(0);
        closeRef.current?.();
      },
    });
    return () => burn.current?.stop();
  }, [open, duration, left]);

  const slide = reduce
    ? { duration: 0 }
    : { type: "spring" as const, duration: slideMs / 1000, bounce: settleBounce };

  return (
    <AnimatePresence custom={gone}>
      {shown && (
        <motion.div
          role="status"
          custom={gone}
          drag={dismissible ? "x" : false}
          dragSnapToOrigin
          dragElastic={0.6}
          onDragEnd={(_, info) => {
            if (Math.abs(info.offset.x) > swipeDistance) close(info.offset.x > 0 ? 1 : -1);
          }}
          onHoverStart={() => pauseOnHover && burn.current?.pause()}
          onHoverEnd={() => pauseOnHover && burn.current?.play()}
          initial={reduce ? { opacity: 0 } : { opacity: 0, y: 16, scale: 0.98 }}
          animate={{ opacity: 1, y: 0, scale: 1 }}
          variants={{
            out: (dir: number) =>
              reduce || !dir
                ? { opacity: 0, transition: { duration: reduce ? 0 : 0.2 } }
                : { x: dir * (width + 40), opacity: 0, transition: { duration: 0.22 } },
          }}
          exit="out"
          transition={slide}
          className={cn(
            "relative flex cursor-grab touch-pan-y items-center gap-3 overflow-hidden border border-[hsl(var(--border))] px-4 py-3 shadow-[0_8px_24px_-12px_hsl(var(--foreground)/0.25)] active:cursor-grabbing",
            !inline && "fixed bottom-6 right-6 z-50",
            className,
          )}
          style={{
            width,
            maxWidth: inline ? "100%" : "calc(100vw - 32px)",
            borderRadius: radius,
            background,
            color,
          }}
        >
          {icon && <span className="shrink-0">{icon}</span>}
          <div className="min-w-0 flex-1">
            <p className="font-serif text-[15px] leading-snug">{title}</p>
            {description && (
              <p className="mt-0.5 text-[13px] text-[hsl(var(--muted-foreground))]">
                {description}
              </p>
            )}
          </div>
          {actionLabel && (
            <button
              type="button"
              onClick={() => {
                onAction?.();
                close(0);
              }}
              className="shrink-0 rounded-md bg-[hsl(var(--primary))] px-2.5 py-1 text-xs font-medium text-[hsl(var(--primary-foreground))] outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
            >
              {actionLabel}
            </button>
          )}
          {closeButton && (
            <button
              type="button"
              aria-label="Dismiss"
              onClick={() => close(0)}
              className="shrink-0 rounded p-1 text-[hsl(var(--muted-foreground))] outline-none hover:text-[hsl(var(--foreground))] focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]"
            >
              <svg
                viewBox="0 0 12 12"
                width={12}
                height={12}
                stroke="currentColor"
                strokeWidth={1.5}
              >
                <path d="M2 2l8 8M10 2l-8 8" />
              </svg>
            </button>
          )}
          {fuse !== "none" && duration > 0 && (
            <motion.span
              aria-hidden
              className={cn(
                "pointer-events-none absolute inset-x-0 h-0.5 origin-left",
                fuse === "top" ? "top-0" : "bottom-0",
              )}
              style={{ background: fuseColor, scaleX: left }}
            />
          )}
        </motion.div>
      )}
    </AnimatePresence>
  );
}
```

---

# Stub Pass

> A perforated card with a primary-ink stub you can drag and tear clean off.

Install: `npx @modus-ui/cli add stub-pass`

The body takes the card token and the stub is printed in the theme's primary, so the perforation reads as a clear seam in any palette. The card tilts toward the pointer and the stub resists before it rips.

## Installation

### CLI

```bash
npx @modus-ui/cli add stub-pass
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/stub-pass.tsx`.
3. Paste the code.

## Usage

```tsx
import { StubPass } from "@/components/ui/stub-pass";

export default function Example() {
  return (
    <StubPass stub={<span className="font-serif">14C</span>}>
      <span className="font-serif">The Quiet Press</span>
    </StubPass>
  );
}
```

## Props

| Prop           | Type    | Default                  | Description |
| :------------- | :------ | :----------------------- | :---------- |
| children       | any     | null                     | -           |
| stub           | any     | null                     | -           |
| image          | string  | ""                       | -           |
| imageAlt       | string  | ""                       | -           |
| scrim          | boolean | true                     | -           |
| imageRadius    | number  | 8                        | -           |
| orientation    | string  | "horizontal"             | -           |
| torn           | any     | -                        | -           |
| defaultTorn    | boolean | false                    | -           |
| onTear         | any     | -                        | -           |
| width          | number  | 460                      | -           |
| height         | number  | 250                      | -           |
| stubSize       | number  | 150                      | -           |
| radius         | number  | 16                       | -           |
| holes          | number  | 12                       | -           |
| holeSize       | number  | 6                        | -           |
| notch          | number  | 3                        | -           |
| roughness      | number  | 0                        | -           |
| tearAngle      | number  | 30                       | -           |
| stretch        | number  | 30                       | -           |
| resistance     | number  | 0.45                     | -           |
| rotate         | number  | 4                        | -           |
| tilt           | boolean | true                     | -           |
| tiltMax        | number  | 9                        | -           |
| tiltReach      | number  | 260                      | -           |
| parallax       | number  | 6                        | -           |
| perspective    | number  | 1000                     | -           |
| background     | string  | "hsl(var(--card))"       | -           |
| color          | string  | "hsl(var(--foreground))" | -           |
| border         | boolean | true                     | -           |
| borderColor    | string  | ""                       | -           |
| borderWidth    | number  | 1                        | -           |
| stubBackground | string  | "hsl(var(--primary))"    | -           |
| recenter       | boolean | true                     | -           |
| disabled       | boolean | false                    | -           |
| ariaLabel      | string  | "Tear off the stub"      | -           |

## Source

`components/ui/stub-pass.tsx`

```tsx
"use client";
// A perforated card whose stub can be pulled and torn off; the card tilts toward the pointer.

import { useMemo, useRef, useState } from "react";
import {
  animate,
  motion,
  useMotionValue,
  useReducedMotion,
  useSpring,
  useTransform,
} from "framer-motion";
import { cn } from "@/lib/utils";

interface StubPassProps {
  children?: React.ReactNode;
  stub?: React.ReactNode;
  image?: string;
  imageAlt?: string;
  scrim?: boolean;
  imageRadius?: number;
  orientation?: "horizontal" | "vertical";
  torn?: boolean;
  defaultTorn?: boolean;
  onTear?: () => void;
  width?: number;
  height?: number;
  stubSize?: number;
  radius?: number;
  holes?: number;
  holeSize?: number;
  /** Seam end notch radius, as a multiple of the hole radius. */
  notch?: number;
  /** Jaggedness of the torn edges, in pixels. */
  roughness?: number;
  /** Angle the stub flies off at once torn, in degrees. */
  tearAngle?: number;
  /** Pull distance, in pixels, before the stub tears. */
  stretch?: number;
  resistance?: number;
  rotate?: number;
  tilt?: boolean;
  tiltMax?: number;
  tiltReach?: number;
  parallax?: number;
  perspective?: number;
  background?: string;
  color?: string;
  border?: boolean;
  borderColor?: string;
  borderWidth?: number;
  stubBackground?: string;
  recenter?: boolean;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

const clamp = (v: number) => Math.max(-1, Math.min(1, v));

/** Mask punching half-holes along one edge plus a larger notch at each end of it. */
function seamMask(
  edge: "left" | "right" | "top" | "bottom",
  length: number,
  holes: number,
  r: number,
  notchR: number,
) {
  const across = edge === "left" || edge === "right";
  const pitch = length / holes;
  const at = `${edge === "left" ? "0%" : edge === "right" ? "100%" : "50%"} ${edge === "top" ? "0%" : edge === "bottom" ? "100%" : "50%"}`;
  const hole = `radial-gradient(circle at ${at}, transparent ${r}px, black ${r + 0.5}px)`;
  const ends = ["0%", "100%"].map((p) => {
    const pos = across
      ? `${edge === "left" ? "0%" : "100%"} ${p}`
      : `${p} ${edge === "top" ? "0%" : "100%"}`;
    return `radial-gradient(circle at ${pos}, transparent ${notchR}px, black ${notchR + 0.5}px)`;
  });
  return {
    maskImage: [hole, ...ends].join(","),
    maskSize: `${across ? `100% ${pitch}px` : `${pitch}px 100%`}, 100% 100%, 100% 100%`,
    maskRepeat: `${across ? "repeat-y" : "repeat-x"}, no-repeat, no-repeat`,
    maskComposite: "intersect",
    WebkitMaskComposite: "source-in",
  } as React.CSSProperties;
}

/** A jagged polygon edge for torn pieces. */
function jagged(edge: "left" | "right" | "top" | "bottom", amp: number, seed: number) {
  if (!amp) return undefined;
  const pts: string[] = [];
  const n = 24;
  for (let i = 0; i <= n; i++) {
    const t = (i / n) * 100;
    const d = Math.abs(Math.sin((i + 1) * seed * 12.9898) * amp);
    pts.push(
      edge === "right"
        ? `calc(100% - ${d}px) ${t}%`
        : edge === "left"
          ? `${d}px ${100 - t}%`
          : edge === "bottom"
            ? `${100 - t}% calc(100% - ${d}px)`
            : `${t}% ${d}px`,
    );
  }
  const frame = {
    right: ["0% 100%", "0% 0%"],
    left: ["100% 0%", "100% 100%"],
    bottom: ["0% 0%", "100% 0%"],
    top: ["100% 100%", "0% 100%"],
  }[edge];
  return `polygon(${[frame[1], ...pts, frame[0]].join(",")})`;
}

export function StubPass({
  children = null,
  stub = null,
  image = "",
  imageAlt = "",
  scrim = true,
  imageRadius = 8,
  orientation = "horizontal",
  torn,
  defaultTorn = false,
  onTear,
  width = 460,
  height = 250,
  stubSize = 150,
  radius = 16,
  holes = 12,
  holeSize = 6,
  notch = 3,
  roughness = 0,
  tearAngle = 30,
  stretch = 30,
  resistance = 0.45,
  rotate = 4,
  tilt = true,
  tiltMax = 9,
  tiltReach = 260,
  parallax = 6,
  perspective = 1000,
  background = "hsl(var(--card))",
  color = "hsl(var(--foreground))",
  border = true,
  borderColor = "",
  borderWidth = 1,
  stubBackground = "hsl(var(--primary))",
  recenter = true,
  disabled = false,
  ariaLabel = "Tear off the stub",
  className,
}: StubPassProps) {
  const reduced = useReducedMotion();
  const [innerTorn, setInnerTorn] = useState(defaultTorn);
  const isTorn = torn ?? innerTorn;
  const across = orientation === "horizontal";
  const seamLength = across ? height : width;
  const r = holeSize / 2;

  const rx = useSpring(0, { stiffness: 160, damping: 18 });
  const ry = useSpring(0, { stiffness: 160, damping: 18 });
  const shiftX = useTransform(ry, (v) => (tiltMax ? (v / tiltMax) * parallax : 0));
  const shiftY = useTransform(rx, (v) => (tiltMax ? (-v / tiltMax) * parallax : 0));
  const pull = useMotionValue(0);
  const stubRotate = useTransform(pull, (p) =>
    stretch ? (Math.min(p, stretch) / stretch) * rotate : 0,
  );
  const pullX = useTransform(pull, (p) => (across ? p : 0));
  const pullY = useTransform(pull, (p) => (across ? 0 : p));
  const start = useRef<number | null>(null);

  const tear = () => {
    if (isTorn || disabled) return;
    if (torn === undefined) setInnerTorn(true);
    onTear?.();
  };

  const edge = {
    border: border ? `${borderWidth}px solid ${borderColor || "hsl(var(--border))"}` : undefined,
  };
  const bodyMask = useMemo(
    () => seamMask(across ? "right" : "bottom", seamLength, holes, r, r * notch),
    [across, seamLength, holes, r, notch],
  );
  const stubMask = useMemo(
    () => seamMask(across ? "left" : "top", seamLength, holes, r, r * notch),
    [across, seamLength, holes, r, notch],
  );
  const flyRad = (tearAngle * Math.PI) / 180;
  const fly = 1.5 * stubSize;
  const centerShift = isTorn && recenter ? stubSize / 2 : 0;

  return (
    <div
      className={cn("relative", className)}
      style={{ width, height, perspective, color }}
      onPointerMove={(e) => {
        if (!tilt || reduced) return;
        const b = e.currentTarget.getBoundingClientRect();
        ry.set(clamp((e.clientX - b.left - b.width / 2) / tiltReach) * tiltMax);
        rx.set(-clamp((e.clientY - b.top - b.height / 2) / tiltReach) * tiltMax);
      }}
      onPointerLeave={() => {
        rx.set(0);
        ry.set(0);
      }}
    >
      <motion.div
        className={cn("relative flex h-full w-full", !across && "flex-col")}
        style={{ rotateX: rx, rotateY: ry, transformStyle: "preserve-3d" }}
        animate={across ? { x: centerShift } : { y: centerShift }}
        transition={reduced ? { duration: 0 } : { type: "spring", stiffness: 200, damping: 24 }}
      >
        <div
          className="relative min-h-0 min-w-0 flex-1 overflow-hidden"
          style={{
            background,
            ...edge,
            ...(across ? { borderRightWidth: 0 } : { borderBottomWidth: 0 }),
            borderRadius: across ? `${radius}px 0 0 ${radius}px` : `${radius}px ${radius}px 0 0`,
            ...(isTorn
              ? { clipPath: jagged(across ? "right" : "bottom", roughness, 1) }
              : bodyMask),
          }}
        >
          {image && (
            <div className="absolute inset-2 overflow-hidden" style={{ borderRadius: imageRadius }}>
              <img src={image} alt={imageAlt} className="h-full w-full object-cover" />
              {scrim && (
                <div
                  className="absolute inset-0"
                  style={{
                    background: "linear-gradient(to top, hsl(var(--card) / 0.85), transparent 70%)",
                  }}
                />
              )}
            </div>
          )}
          <motion.div className="relative h-full" style={{ x: shiftX, y: shiftY }}>
            {children}
          </motion.div>
        </div>

        <motion.div
          role="button"
          tabIndex={disabled || isTorn ? -1 : 0}
          aria-label={ariaLabel}
          aria-disabled={disabled || isTorn}
          aria-pressed={isTorn}
          className={cn(
            "relative shrink-0 outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))]",
            !disabled && !isTorn && (across ? "cursor-ew-resize" : "cursor-ns-resize"),
          )}
          style={{
            [across ? "width" : "height"]: stubSize,
            x: pullX,
            y: pullY,
            rotate: stubRotate,
            originX: across ? 0 : 0.5,
            originY: across ? 1 : 0,
            touchAction: "none",
          }}
          onKeyDown={(e) => {
            if (e.key === "Enter" || e.key === " ") {
              e.preventDefault();
              tear();
            }
          }}
          onPointerDown={(e) => {
            if (disabled || isTorn) return;
            e.currentTarget.setPointerCapture(e.pointerId);
            start.current = across ? e.clientX : e.clientY;
          }}
          onPointerMove={(e) => {
            if (start.current === null) return;
            const raw = Math.max(0, (across ? e.clientX : e.clientY) - start.current);
            pull.set(raw * (1 - resistance));
            if (raw > stretch / (1 - resistance)) {
              start.current = null;
              tear();
            }
          }}
          onPointerUp={() => {
            start.current = null;
            if (!isTorn) animate(pull, 0, { type: "spring", stiffness: 500, damping: 20 });
          }}
        >
          <motion.div
            className="h-full w-full"
            style={{
              background: stubBackground,
              borderRadius: across ? `0 ${radius}px ${radius}px 0` : `0 0 ${radius}px ${radius}px`,
              ...(isTorn ? { clipPath: jagged(across ? "left" : "top", roughness, 2) } : stubMask),
            }}
            initial={false}
            animate={
              isTorn
                ? {
                    x: across ? fly * Math.cos(flyRad) : fly * Math.sin(flyRad),
                    y: across ? fly * Math.sin(flyRad) : fly * Math.cos(flyRad),
                    rotate: tearAngle / 2,
                    opacity: 0,
                  }
                : { x: 0, y: 0, rotate: 0, opacity: 1 }
            }
            transition={reduced ? { duration: 0 } : { duration: 0.6, ease: [0.3, 0, 0.4, 1] }}
          >
            {stub}
          </motion.div>
        </motion.div>
      </motion.div>
    </div>
  );
}
```

---

# Ink Murmur

> A mono status line that breathes while work is in progress and settles into a timed summary.

Install: `npx @modus-ui/cli add ink-murmur`

Set in small uppercase mono with a pulsing dot, it sits under a heading like a typesetter's margin note. Expanding it reveals the steps taken so far.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-murmur
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ink-murmur.tsx`.
3. Paste the code.

## Usage

```tsx
import { InkMurmur } from "@/components/ui/ink-murmur";

export default function Example() {
  return <InkMurmur steps={["Reading the brief", "Pulling a proof"]} />;
}
```

## Props

| Prop             | Type    | Default        | Description |
| :--------------- | :------ | :------------- | :---------- |
| label            | string  | "Composing…"   | -           |
| doneLabel        | string  | ""             | -           |
| renderLabel      | any     | -              | -           |
| glyph            | string  | "dot"          | -           |
| steps            | any     | EMPTY_STEPS    | -           |
| collapsible      | boolean | true           | -           |
| collapseOnSettle | boolean | true           | -           |
| color            | string  | "currentColor" | -           |
| glyphColor       | string  | ""             | -           |
| fontSize         | number  | 13             | -           |
| breathPeriod     | number  | 1.6            | -           |
| breathDepth      | number  | 0.45           | -           |
| shimmer          | boolean | true           | -           |
| shimmerDuration  | number  | 1.8            | -           |
| settleDuration   | number  | 350            | -           |
| settleBlur       | number  | 2              | -           |
| working          | boolean | true           | -           |
| settleAfter      | number  | 0              | -           |
| elapsed          | any     | -              | -           |
| showTimer        | boolean | true           | -           |
| onSettle         | any     | -              | -           |
| style            | any     | -              | -           |

## Source

`components/ui/ink-murmur.tsx`

```tsx
"use client";
// A breathing mono status line that settles into a timed summary, with an expandable list of steps.

import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
import {
  AnimatePresence,
  animate,
  motion,
  useMotionTemplate,
  useMotionValue,
  useReducedMotion,
} from "framer-motion";
import { cn } from "@/lib/utils";

const EMPTY_STEPS: string[] = [];

interface InkMurmurProps {
  label?: string;
  /** Shown once settled; defaults to "Done in {time}". */
  doneLabel?: string;
  /** Replaces the label text: receives elapsed seconds and whether work is ongoing. */
  renderLabel?: (elapsed: number, working: boolean) => ReactNode;
  glyph?: "dot" | "ring" | "none";
  steps?: string[];
  collapsible?: boolean;
  collapseOnSettle?: boolean;
  color?: string;
  glyphColor?: string;
  fontSize?: number;
  /** Seconds per breath of the glyph. */
  breathPeriod?: number;
  /** How far the glyph fades on each breath (0–1). */
  breathDepth?: number;
  shimmer?: boolean;
  shimmerDuration?: number;
  settleDuration?: number;
  settleBlur?: number;
  working?: boolean;
  /** Seconds after which it settles on its own; 0 waits for `working` to turn false. */
  settleAfter?: number;
  /** Controlled elapsed seconds. */
  elapsed?: number;
  showTimer?: boolean;
  onSettle?: (elapsed: number) => void;
  style?: CSSProperties;
  className?: string;
}

export function InkMurmur({
  label = "Composing…",
  doneLabel = "",
  renderLabel,
  glyph = "dot",
  steps = EMPTY_STEPS,
  collapsible = true,
  collapseOnSettle = true,
  color = "currentColor",
  glyphColor = "",
  fontSize = 13,
  breathPeriod = 1.6,
  breathDepth = 0.45,
  shimmer = true,
  shimmerDuration = 1.8,
  settleDuration = 350,
  settleBlur = 2,
  working = true,
  settleAfter = 0,
  elapsed,
  showTimer = true,
  onSettle,
  style,
  className,
}: InkMurmurProps) {
  const reduce = useReducedMotion();
  const [clock, setClock] = useState(0);
  const [expanded, setExpanded] = useState(true);
  const started = useRef(0);
  const seconds = elapsed ?? clock;
  const busy = working && !(settleAfter > 0 && seconds >= settleAfter);

  useEffect(() => {
    if (!busy || elapsed !== undefined) return;
    if (!started.current) started.current = performance.now();
    const id = setInterval(() => setClock((performance.now() - started.current) / 1000), 100);
    return () => clearInterval(id);
  }, [busy, elapsed]);

  const settledOnce = useRef(false);
  useEffect(() => {
    if (busy || settledOnce.current) return;
    settledOnce.current = true;
    if (collapseOnSettle) setExpanded(false);
    onSettle?.(seconds);
  }, [busy, collapseOnSettle, onSettle, seconds]);

  const time = `${seconds.toFixed(1)}s`;
  const text = renderLabel
    ? renderLabel(seconds, busy)
    : busy
      ? label
      : doneLabel || `Done in ${time}`;
  const ink = glyphColor || color;
  const sweep = busy && shimmer && !reduce;
  const shift = useMotionValue(100);
  const maskPosition = useMotionTemplate`${shift}% 0%`;
  useEffect(() => {
    if (!sweep) return;
    const run = animate(shift, [100, 0], {
      duration: shimmerDuration,
      repeat: Infinity,
      ease: "linear",
    });
    return () => run.stop();
  }, [sweep, shimmerDuration, shift]);
  const canToggle = collapsible && steps.length > 0;

  return (
    <div
      className={cn("inline-flex flex-col font-mono uppercase tracking-[0.16em]", className)}
      style={{ color: color === "currentColor" ? undefined : color, fontSize, ...style }}
    >
      <button
        type="button"
        disabled={!canToggle}
        aria-expanded={canToggle ? expanded : undefined}
        onClick={() => setExpanded((v) => !v)}
        className="inline-flex items-center gap-2.5 text-left uppercase outline-none focus-visible:underline disabled:cursor-default"
        style={{ fontSize: "1em" }}
      >
        {glyph !== "none" && (
          <motion.span
            aria-hidden
            className={cn(
              "inline-block h-[0.5em] w-[0.5em] rounded-full",
              glyph === "ring" && "border",
            )}
            style={glyph === "ring" ? { borderColor: ink } : { background: ink }}
            animate={
              busy && !reduce
                ? { opacity: [1, 1 - breathDepth, 1], scale: [1, 1 - breathDepth / 3, 1] }
                : { opacity: 1, scale: 1 }
            }
            transition={
              busy && !reduce
                ? { duration: breathPeriod, repeat: Infinity, ease: "easeInOut" }
                : undefined
            }
          />
        )}
        <AnimatePresence mode="wait" initial={false}>
          <motion.span
            key={busy ? "busy" : "done"}
            initial={{ opacity: 0, filter: `blur(${settleBlur}px)` }}
            animate={{ opacity: 1, filter: "blur(0px)" }}
            exit={{ opacity: 0, filter: `blur(${settleBlur}px)` }}
            transition={{ duration: reduce ? 0 : settleDuration / 1000 }}
          >
            {sweep ? (
              <motion.span
                // A soft dip in opacity travels across the words.
                style={{
                  maskImage: "linear-gradient(90deg, black 35%, rgba(0,0,0,0.3) 50%, black 65%)",
                  maskSize: "250% 100%",
                  maskPosition,
                }}
              >
                {text}
              </motion.span>
            ) : (
              text
            )}
          </motion.span>
        </AnimatePresence>
        {showTimer && busy && <span className="tabular-nums opacity-60">{time}</span>}
        {canToggle && (
          <motion.span aria-hidden className="opacity-60" animate={{ rotate: expanded ? 0 : 180 }}>
            ˄
          </motion.span>
        )}
      </button>
      <AnimatePresence initial={false}>
        {canToggle && expanded && (
          <motion.ol
            className="overflow-hidden pl-[1.1em] text-[0.8em]"
            initial={{ height: 0, opacity: 0 }}
            animate={{ height: "auto", opacity: 1 }}
            exit={{ height: 0, opacity: 0 }}
            transition={{ duration: reduce ? 0 : settleDuration / 1000 }}
          >
            {steps.map((step, i) => {
              const current = busy && i === steps.length - 1;
              return (
                <li key={step} className={cn("mt-1 flex gap-2", !current && "opacity-50")}>
                  <span aria-hidden>{current ? "›" : "✓"}</span>
                  {step}
                </li>
              );
            })}
          </motion.ol>
        )}
      </AnimatePresence>
    </div>
  );
}
```

---

# Hum Capsule

> A dictation button that opens into a capsule with a live level meter and a running clock.

Install: `npx @modus-ui/cli add hum-capsule`

At rest it is a soft muted square in foreground ink; while listening it widens and its meter and timer take the primary token. Slide left to cancel, or hold to talk.

## Installation

### CLI

```bash
npx @modus-ui/cli add hum-capsule
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/hum-capsule.tsx`.
3. Paste the code.

## Usage

```tsx
import { HumCapsule } from "@/components/ui/hum-capsule";

export default function Example() {
  return <HumCapsule />;
}
```

## Props

| Prop           | Type    | Default                  | Description |
| :------------- | :------ | :----------------------- | :---------- |
| accentColor    | string  | "hsl(var(--primary))"    | -           |
| iconColor      | string  | "hsl(var(--foreground))" | -           |
| background     | string  | "hsl(var(--muted))"      | -           |
| size           | number  | 28                       | -           |
| shape          | string  | "rounded"                | -           |
| reach          | number  | 8                        | -           |
| showTime       | boolean | true                     | -           |
| waveform       | boolean | true                     | -           |
| slideToCancel  | boolean | true                     | -           |
| cancelDistance | number  | 64                       | -           |
| attack         | number  | 40                       | -           |
| release        | number  | 240                      | -           |
| sensitivity    | number  | 1                        | -           |
| floor          | number  | 0.1                      | -           |
| openDuration   | number  | 200                      | -           |
| pressScale     | number  | 0.95                     | -           |
| mode           | string  | "auto"                   | -           |
| holdAfter      | number  | 300                      | -           |
| reactive       | string  | "simulated"              | -           |
| disabled       | boolean | false                    | -           |
| ariaLabel      | string  | "Dictate"                | -           |
| onStart        | any     | -                        | -           |
| onStop         | any     | -                        | -           |

## Source

`components/ui/hum-capsule.tsx`

```tsx
"use client";
// Dictation button that widens into a capsule with a scrolling level meter and a running clock.

import { useEffect, useRef, useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface HumCapsuleProps {
  accentColor?: string;
  iconColor?: string;
  background?: string;
  /** Height of the button, and its width at rest, in px. */
  size?: number;
  shape?: "rounded" | "circle";
  /** Number of bars in the scrolling meter. */
  reach?: number;
  showTime?: boolean;
  /** Scrolling bars; off shows a single pulsing dot. */
  waveform?: boolean;
  slideToCancel?: boolean;
  /** Pixels to slide left before a held press cancels. */
  cancelDistance?: number;
  /** Meter rise time in ms. */
  attack?: number;
  /** Meter fall time in ms. */
  release?: number;
  sensitivity?: number;
  /** Lowest bar height, as a fraction of the meter. */
  floor?: number;
  openDuration?: number;
  pressScale?: number;
  /** "toggle" taps on and off, "hold" is push-to-talk, "auto" does both. */
  mode?: "auto" | "toggle" | "hold";
  /** In auto mode, a press longer than this (ms) becomes push-to-talk. */
  holdAfter?: number;
  /** "microphone" meters the real input; "simulated" fakes a voice. */
  reactive?: "simulated" | "microphone";
  disabled?: boolean;
  ariaLabel?: string;
  onStart?: () => void;
  onStop?: (seconds: number, cancelled: boolean) => void;
  className?: string;
}

function MicGlyph() {
  return (
    <svg
      viewBox="0 0 24 24"
      className="h-[55%] w-[55%]"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.8}
      strokeLinecap="round"
    >
      <rect x="9" y="3" width="6" height="11" rx="3" />
      <path d="M5.5 11a6.5 6.5 0 0 0 13 0M12 17.5V21" />
    </svg>
  );
}

/** Returns a 0–1 loudness sampler: the real microphone or a voice-like fake. */
async function openSource(kind: "simulated" | "microphone") {
  if (kind === "microphone") {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
    const ctx = new AudioContext();
    const analyser = ctx.createAnalyser();
    analyser.fftSize = 512;
    ctx.createMediaStreamSource(stream).connect(analyser);
    const buf = new Float32Array(analyser.fftSize);
    return {
      read() {
        analyser.getFloatTimeDomainData(buf);
        return Math.min(1, Math.sqrt(buf.reduce((s, v) => s + v * v, 0) / buf.length) * 4);
      },
      close() {
        stream.getTracks().forEach((t) => t.stop());
        void ctx.close();
      },
    };
  }
  return {
    read() {
      const t = performance.now() / 1000;
      const syllable = Math.max(0, Math.sin(t * 7.3) * Math.sin(t * 2.1 + 1));
      return Math.min(1, syllable * 0.8 + Math.random() * 0.25);
    },
    close() {},
  };
}

export function HumCapsule({
  accentColor = "hsl(var(--primary))",
  iconColor = "hsl(var(--foreground))",
  background = "hsl(var(--muted))",
  size = 28,
  shape = "rounded",
  reach = 8,
  showTime = true,
  waveform = true,
  slideToCancel = true,
  cancelDistance = 64,
  attack = 40,
  release = 240,
  sensitivity = 1,
  floor = 0.1,
  openDuration = 200,
  pressScale = 0.95,
  mode = "auto",
  holdAfter = 300,
  reactive = "simulated",
  disabled = false,
  ariaLabel = "Dictate",
  onStart,
  onStop,
  className,
}: HumCapsuleProps) {
  const reduce = useReducedMotion();
  const [live, setLive] = useState(false);
  const [bars, setBars] = useState<number[]>(() => Array(reach).fill(floor));
  const [elapsed, setElapsed] = useState(0);
  const [slide, setSlide] = useState(0);
  const press = useRef<{ x: number; at: number; wasLive: boolean } | null>(null);
  const began = useRef(0);

  useEffect(() => {
    if (!live) return;
    let raf = 0;
    let level = 0;
    let last = performance.now();
    let lastPush = 0;
    let source: Awaited<ReturnType<typeof openSource>> | null = null;
    let stopped = false;
    openSource(reactive)
      .then((s) => (stopped ? s.close() : (source = s)))
      .catch(() => setLive(false));
    const tick = (now: number) => {
      const dt = now - last;
      last = now;
      const target = Math.min(1, (source?.read() ?? 0) * sensitivity);
      const tau = target > level ? attack : release;
      level += (target - level) * (1 - Math.exp(-dt / Math.max(1, tau)));
      setElapsed((now - began.current) / 1000);
      if (now - lastPush > 70) {
        lastPush = now;
        setBars((prev) => [...prev.slice(1 - reach), Math.max(floor, level)]);
      }
      raf = requestAnimationFrame(tick);
    };
    raf = requestAnimationFrame(tick);
    return () => {
      stopped = true;
      cancelAnimationFrame(raf);
      source?.close();
    };
  }, [live, reactive, sensitivity, attack, release, floor, reach]);

  const start = () => {
    began.current = performance.now();
    setElapsed(0);
    setBars(Array(reach).fill(floor));
    setLive(true);
    onStart?.();
  };
  const stop = (cancelled: boolean) => {
    setLive(false);
    setSlide(0);
    onStop?.((performance.now() - began.current) / 1000, cancelled);
  };

  const radius = shape === "circle" ? size / 2 : size * 0.3;
  const clock = `${Math.floor(elapsed / 60)}:${String(Math.floor(elapsed % 60)).padStart(2, "0")}`;
  const cancelling = slideToCancel && slide > cancelDistance;

  return (
    <motion.button
      type="button"
      layout
      disabled={disabled}
      aria-label={ariaLabel}
      aria-pressed={live}
      onPointerDown={(e) => {
        if (disabled || e.button !== 0) return;
        e.currentTarget.setPointerCapture(e.pointerId);
        press.current = { x: e.clientX, at: performance.now(), wasLive: live };
        if (!live && mode !== "toggle") start();
      }}
      onPointerMove={(e) => {
        if (press.current && live && slideToCancel)
          setSlide(Math.max(0, press.current.x - e.clientX));
      }}
      onPointerUp={() => {
        const p = press.current;
        press.current = null;
        if (!p) return;
        const held = performance.now() - p.at > holdAfter;
        if (cancelling) return stop(true);
        setSlide(0);
        if (mode === "hold" || (mode === "auto" && held && !p.wasLive)) return live && stop(false);
        if (p.wasLive) return stop(false);
        if (mode === "toggle") start();
      }}
      onKeyDown={(e) => {
        if (e.key === "Escape" && live) stop(true);
      }}
      onClick={(e) => {
        // Keyboard activation (pointer presses are handled above).
        if (e.detail === 0) live ? stop(false) : start();
      }}
      whileTap={reduce ? undefined : { scale: pressScale }}
      transition={{ duration: reduce ? 0 : openDuration / 1000, ease: [0.2, 0.8, 0.2, 1] }}
      className={cn(
        "inline-flex touch-none select-none items-center overflow-hidden outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50",
        className,
      )}
      style={{
        height: size,
        minWidth: size,
        borderRadius: radius,
        background,
        color: iconColor,
        x: live ? -Math.min(slide, cancelDistance) / 3 : 0,
        opacity: cancelling ? 0.6 : 1,
      }}
    >
      <motion.span
        layout
        className="grid shrink-0 place-items-center"
        style={{ width: size, height: size }}
      >
        <MicGlyph />
      </motion.span>
      {live && (
        <motion.span
          layout
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          className="flex items-center gap-2 pr-3"
          style={{ height: size, color: accentColor }}
        >
          {waveform ? (
            <span className="flex items-center gap-[2px]" style={{ height: size * 0.5 }}>
              {bars.map((b, i) => (
                <span
                  key={i}
                  className="w-[2px] rounded-full"
                  style={{
                    height: `${b * 100}%`,
                    background: accentColor,
                    transition: reduce ? undefined : "height 70ms linear",
                  }}
                />
              ))}
            </span>
          ) : (
            <span
              className="rounded-full"
              style={{
                width: size * 0.25,
                height: size * 0.25,
                background: accentColor,
                transform: reduce ? undefined : `scale(${0.6 + bars[bars.length - 1]})`,
              }}
            />
          )}
          {showTime && (
            <span className="font-mono text-[11px] tabular-nums">
              {cancelling ? "Release" : clock}
            </span>
          )}
        </motion.span>
      )}
    </motion.button>
  );
}
```

---

# Rouse Track

> A range input drawn as a field of bars that rise into a crest around the thumb.

Install: `npx @modus-ui/cli add rouse-track`

Bars rest on the border token and fill with the primary ink up to the value, which is printed alongside. The crest follows the pointer and glides as you drag.

## Installation

### CLI

```bash
npx @modus-ui/cli add rouse-track
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/rouse-track.tsx`.
3. Paste the code.

## Usage

```tsx
import { RouseTrack } from "@/components/ui/rouse-track";

export default function Example() {
  return <RouseTrack ariaLabel="Leading" />;
}
```

## Props

| Prop         | Type    | Default               | Description |
| :----------- | :------ | :-------------------- | :---------- |
| value        | any     | -                     | -           |
| defaultValue | number  | 50                    | -           |
| onChange     | any     | -                     | -           |
| min          | number  | 0                     | -           |
| max          | number  | 100                   | -           |
| step         | number  | 1                     | -           |
| bars         | number  | 48                    | -           |
| height       | number  | 56                    | -           |
| restHeight   | number  | 12                    | -           |
| gap          | number  | 4                     | -           |
| fillColor    | string  | "hsl(var(--primary))" | -           |
| trackColor   | string  | "hsl(var(--border))"  | -           |
| crestColor   | string  | ""                    | -           |
| sensitivity  | number  | 1                     | -           |
| reach        | number  | 6                     | -           |
| skew         | number  | 0.6                   | -           |
| glide        | number  | 0.3                   | -           |
| smoothing    | number  | 100                   | -           |
| showValue    | boolean | true                  | -           |
| formatValue  | any     | -                     | -           |
| disabled     | boolean | false                 | -           |
| ariaLabel    | string  | "Value"               | -           |

## Source

`components/ui/rouse-track.tsx`

```tsx
"use client";
// A range input drawn as bars that swell into a crest around the thumb.

import { useEffect, useState, type ReactNode } from "react";
import {
  motion,
  useMotionValue,
  useReducedMotion,
  useSpring,
  useTransform,
  type MotionValue,
} from "framer-motion";
import { cn } from "@/lib/utils";

export interface RouseTrackProps {
  value?: number;
  defaultValue?: number;
  onChange?: (value: number) => void;
  min?: number;
  max?: number;
  step?: number;
  bars?: number;
  height?: number;
  restHeight?: number;
  gap?: number;
  fillColor?: string;
  trackColor?: string;
  crestColor?: string;
  sensitivity?: number;
  reach?: number;
  skew?: number;
  glide?: number;
  smoothing?: number;
  showValue?: boolean;
  formatValue?: (value: number) => ReactNode;
  disabled?: boolean;
  ariaLabel?: string;
  className?: string;
}

export function RouseTrack({
  value,
  defaultValue = 50,
  onChange,
  min = 0,
  max = 100,
  step = 1,
  bars = 48,
  height = 56,
  restHeight = 12,
  gap = 4,
  fillColor = "hsl(var(--primary))",
  trackColor = "hsl(var(--border))",
  crestColor = "",
  sensitivity = 1,
  reach = 6,
  skew = 0.6,
  glide = 0.3,
  smoothing = 100,
  showValue = true,
  formatValue,
  disabled = false,
  ariaLabel = "Value",
  className,
}: RouseTrackProps) {
  const reduce = useReducedMotion();
  const [inner, setInner] = useState(defaultValue);
  const current = value ?? inner;
  const ratio = (current - min) / (max - min || 1);
  const filled = Math.round(ratio * bars);

  // Crest centre in bar units; it follows the pointer while hovered, else the value.
  const target = useMotionValue(ratio * (bars - 1));
  const [hover, setHover] = useState<number | null>(null);
  const goal = hover ?? ratio * (bars - 1);
  useEffect(() => target.set(goal), [target, goal]);
  const crest = useSpring(target, {
    stiffness: reduce ? 10000 : 400 * (1 - glide) + 40,
    damping: reduce ? 200 : 30,
  });
  // The crest swells while engaged, and sinks back at rest.
  const strength = useSpring(hover === null ? 0.45 : 1, {
    duration: reduce ? 0 : smoothing / 1000,
    bounce: 0,
  });

  const set = (v: number) => {
    setInner(v);
    onChange?.(v);
  };

  return (
    <div className={cn("flex items-center gap-4", disabled && "opacity-50", className)}>
      <div
        className="relative flex flex-1 items-center"
        style={{ height, gap }}
        onPointerMove={(e) => {
          const box = e.currentTarget.getBoundingClientRect();
          setHover(((e.clientX - box.left) / box.width) * (bars - 1));
        }}
        onPointerLeave={() => setHover(null)}
      >
        {Array.from({ length: bars }, (_, i) => (
          <Bar
            key={i}
            index={i}
            crest={crest}
            strength={strength}
            color={i < filled ? fillColor : trackColor}
            crestColor={crestColor}
            rest={restHeight}
            peak={height}
            reach={reach}
            skew={skew}
            sensitivity={sensitivity}
          />
        ))}
        <input
          type="range"
          min={min}
          max={max}
          step={step}
          value={current}
          disabled={disabled}
          aria-label={ariaLabel}
          onChange={(e) => set(Number(e.target.value))}
          className="peer absolute inset-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed"
        />
        <span className="pointer-events-none absolute -inset-1 rounded-md ring-[hsl(var(--ring))] peer-focus-visible:ring-2" />
      </div>
      {showValue && (
        <output className="min-w-[3ch] text-right font-mono text-xs tabular-nums text-muted-foreground">
          {formatValue ? formatValue(current) : current}
        </output>
      )}
    </div>
  );
}

function Bar({
  index,
  crest,
  strength,
  color,
  crestColor,
  rest,
  peak,
  reach,
  skew,
  sensitivity,
}: {
  index: number;
  crest: MotionValue<number>;
  strength: MotionValue<number>;
  color: string;
  crestColor: string;
  rest: number;
  peak: number;
  reach: number;
  skew: number;
  sensitivity: number;
}) {
  // A bell around the crest; bars behind the crest fall off more slowly by `skew`.
  const lift = useTransform([crest, strength], ([c, s]: number[]) => {
    const d = index - c;
    const width = Math.max(reach, 0.5) * (d < 0 ? 1 + skew * 0.5 : 1 - skew * 0.3);
    return Math.exp(-(d * d) / (2 * width * width)) * s * Math.min(sensitivity, 2);
  });
  const h = useTransform(
    lift,
    (l) => Math.round(Math.min(peak, rest + (peak - rest) * l) * 10) / 10,
  );
  const glow = useTransform(lift, [0.4, 0.8], [0, 1]);

  return (
    <motion.span
      aria-hidden
      className="relative flex-1 overflow-hidden rounded-full"
      style={{ height: h, background: color }}
    >
      {crestColor && (
        <motion.span
          className="absolute inset-0"
          style={{ background: crestColor, opacity: glow }}
        />
      )}
    </motion.span>
  );
}
```

---

# Ember Hint

> An inverted ink tooltip that stays warm, so moving between triggers glides from one label to the next.

Install: `npx @modus-ui/cli add ember-hint`

Labels are small uppercase mono on a foreground slab, matching the theme in light and dark. After the first one opens, neighbours show instantly and the tooltip travels across. Wrap triggers in `EmberHintGroup` to share that warm state.

## Installation

### CLI

```bash
npx @modus-ui/cli add ember-hint
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ember-hint.tsx`.
3. Paste the code.

## Usage

```tsx
import { EmberHint } from "@/components/ui/ember-hint";

export default function Example() {
  return (
    <EmberHint content="Bold">
      <button>Bold</button>
    </EmberHint>
  );
}
```

## Props

| Prop         | Type    | Default                  | Description |
| :----------- | :------ | :----------------------- | :---------- |
| content      | any     | -                        | -           |
| shortcut     | any     | -                        | -           |
| children     | any     | -                        | -           |
| side         | string  | "top"                    | -           |
| delay        | any     | -                        | -           |
| warmWindow   | any     | -                        | -           |
| surfaceColor | string  | "hsl(var(--foreground))" | -           |
| inkColor     | string  | "hsl(var(--background))" | -           |
| size         | string  | "md"                     | -           |
| radius       | number  | 3                        | -           |
| gap          | number  | 8                        | -           |
| arrow        | boolean | true                     | -           |
| popDuration  | number  | 160                      | -           |
| popScale     | number  | 0.94                     | -           |
| popBlur      | number  | 4                        | -           |
| showFuse     | boolean | false                    | -           |
| longPress    | number  | 500                      | -           |
| disabled     | boolean | false                    | -           |

## Source

`components/ui/ember-hint.tsx`

```tsx
"use client";
// Inverted tooltip that stays warm: once one opens, neighbours open instantly and the slab glides across.

import {
  createContext,
  useContext,
  useEffect,
  useId,
  useRef,
  useState,
  useSyncExternalStore,
  type ReactNode,
} from "react";
import { AnimatePresence, LayoutGroup, motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

/** Which hint is showing, and until when the group stays warm. */
function createWarmth() {
  let shown: string | null = null;
  let warmUntil = 0;
  const listeners = new Set<() => void>();
  return {
    get: () => shown,
    isWarm: () => performance.now() < warmUntil,
    subscribe(fn: () => void) {
      listeners.add(fn);
      return () => listeners.delete(fn);
    },
    show(id: string | null, warmWindow: number) {
      if (shown && !id) warmUntil = performance.now() + warmWindow;
      shown = id;
      listeners.forEach((fn) => fn());
    },
  };
}

const WarmthContext = createContext(createWarmth());

/** Shares warm state (and the glide) between the hints inside it. */
export function EmberHintGroup({ children }: { children: ReactNode }) {
  const [warmth] = useState(createWarmth);
  return (
    <WarmthContext.Provider value={warmth}>
      <LayoutGroup id={useId()}>{children}</LayoutGroup>
    </WarmthContext.Provider>
  );
}

const SIZES = {
  sm: "px-1.5 py-0.5 text-[9px]",
  md: "px-2 py-1 text-[10px]",
  lg: "px-2.5 py-1.5 text-[11px]",
};

const PLACE = {
  top: { box: "bottom-full left-1/2 -translate-x-1/2", pad: "paddingBottom", y: 4, x: 0 },
  bottom: { box: "top-full left-1/2 -translate-x-1/2", pad: "paddingTop", y: -4, x: 0 },
  left: { box: "right-full top-1/2 -translate-y-1/2", pad: "paddingRight", y: 0, x: 4 },
  right: { box: "left-full top-1/2 -translate-y-1/2", pad: "paddingLeft", y: 0, x: -4 },
} as const;

const ARROW = {
  top: "-bottom-[3px] left-1/2 -ml-[3px]",
  bottom: "-top-[3px] left-1/2 -ml-[3px]",
  left: "-right-[3px] top-1/2 -mt-[3px]",
  right: "-left-[3px] top-1/2 -mt-[3px]",
};

interface EmberHintProps {
  content: ReactNode;
  shortcut?: string;
  children: ReactNode;
  side?: keyof typeof PLACE;
  /** Cold open delay in ms. */
  delay?: number;
  /** How long (ms) after closing the next hint still opens instantly. */
  warmWindow?: number;
  surfaceColor?: string;
  inkColor?: string;
  size?: keyof typeof SIZES;
  radius?: number;
  gap?: number;
  arrow?: boolean;
  popDuration?: number;
  popScale?: number;
  popBlur?: number;
  /** Draws a hairline under the trigger that burns down while the cold delay runs. */
  showFuse?: boolean;
  /** Touch hold, in ms, that opens the hint. */
  longPress?: number;
  disabled?: boolean;
  className?: string;
}

export function EmberHint({
  content,
  shortcut,
  children,
  side = "top",
  delay,
  warmWindow,
  surfaceColor = "hsl(var(--foreground))",
  inkColor = "hsl(var(--background))",
  size = "md",
  radius = 3,
  gap = 8,
  arrow = true,
  popDuration = 160,
  popScale = 0.94,
  popBlur = 4,
  showFuse = false,
  longPress = 500,
  disabled = false,
  className,
}: EmberHintProps) {
  const warmth = useContext(WarmthContext);
  const id = useId();
  const reduce = useReducedMotion();
  const open = useSyncExternalStore(warmth.subscribe, warmth.get, () => null) === id;
  const [fusing, setFusing] = useState(false);
  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);
  const coldDelay = delay ?? 500;
  const warmMs = warmWindow ?? 400;

  const clear = () => {
    clearTimeout(timer.current);
    setFusing(false);
  };
  const show = (wait: number) => {
    if (disabled) return;
    clear();
    if (warmth.get() || warmth.isWarm()) return warmth.show(id, warmMs);
    setFusing(true);
    timer.current = setTimeout(() => {
      setFusing(false);
      warmth.show(id, warmMs);
    }, wait);
  };
  const hide = () => {
    clear();
    if (warmth.get() === id) warmth.show(null, warmMs);
  };

  useEffect(() => () => clearTimeout(timer.current), []);

  const place = PLACE[side];
  const seconds = popDuration / 1000;

  return (
    <span
      className={cn("relative inline-flex", className)}
      onPointerEnter={(e) => e.pointerType === "mouse" && show(coldDelay)}
      onPointerLeave={hide}
      onPointerDown={(e) => e.pointerType !== "mouse" && show(longPress)}
      onPointerUp={(e) => e.pointerType !== "mouse" && clear()}
      onFocus={() => show(0)}
      onBlur={hide}
      onKeyDown={(e) => e.key === "Escape" && hide()}
    >
      {children}
      {showFuse && fusing && (
        <motion.span
          aria-hidden
          className="pointer-events-none absolute -bottom-1 left-0 h-px w-full origin-left"
          style={{ background: surfaceColor }}
          initial={{ scaleX: 1 }}
          animate={{ scaleX: 0 }}
          transition={{ duration: reduce ? 0 : coldDelay / 1000, ease: "linear" }}
        />
      )}
      <AnimatePresence>
        {open && (
          <span
            role="tooltip"
            className={cn("pointer-events-none absolute z-50", place.box)}
            style={{ [place.pad]: gap }}
          >
            <motion.span
              layoutId="ember-hint"
              className={cn(
                "relative flex items-center gap-2 whitespace-nowrap font-mono uppercase tracking-[0.14em]",
                SIZES[size],
              )}
              style={{ background: surfaceColor, color: inkColor, borderRadius: radius }}
              initial={
                reduce
                  ? { opacity: 0 }
                  : {
                      opacity: 0,
                      scale: popScale,
                      x: place.x,
                      y: place.y,
                      filter: `blur(${popBlur}px)`,
                    }
              }
              animate={{ opacity: 1, scale: 1, x: 0, y: 0, filter: "blur(0px)" }}
              exit={{ opacity: 0, transition: { duration: seconds / 2 } }}
              transition={{ duration: reduce ? 0 : seconds, ease: [0.2, 0.8, 0.2, 1] }}
            >
              {content}
              {shortcut && <kbd className="font-mono opacity-60">{shortcut}</kbd>}
              {arrow && (
                <span
                  aria-hidden
                  className={cn("absolute h-1.5 w-1.5 rotate-45", ARROW[side])}
                  style={{ background: surfaceColor }}
                />
              )}
            </motion.span>
          </span>
        )}
      </AnimatePresence>
    </span>
  );
}
```

---

# Bough Study

> A painterly canvas tree that grows, sways and regrows in ink drawn from your theme.

Install: `npx @modus-ui/cli add bough-study`

A branching tree drawn on a 2D canvas in an ink ramp from the foreground up to the palette's primary, on the page ground. It grows from the trunk outwards, sways with layered wind, bends towards the pointer and shakes on click, then fades and grows a new one while motes drift around the canopy. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add bough-study
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/bough-study.tsx`.
3. Paste the code.

## Usage

```tsx
import { BoughStudy } from "@/components/ui/bough-study";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <BoughStudy />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                                   | Description                                               |
| :---------------- | :------- | :---------------------------------------- | :-------------------------------------------------------- |
| `speed`           | `number` | `1`                                       | Animation speed multiplier (0 to 3).                      |
| `size`            | `number` | `1`                                       | Tree size (0.65 to 1.5). Below 1 the tree is centred.     |
| `particleAmount`  | `number` | `1`                                       | Particle count multiplier (0 to 2, 50 particles at 1).    |
| `opacity`         | `number` | `1`                                       | Canvas opacity.                                           |
| `hue`             | `number` | `0`                                       | Hue rotation in degrees.                                  |
| `saturation`      | `number` | `1`                                       | Saturation multiplier.                                    |
| `brightness`      | `number` | `1`                                       | Brightness multiplier.                                    |
| `backgroundColor` | `string` | `hsl(var(--background))`                  | Colour behind the tree, any CSS colour.                   |
| `colors`          | `RGB[]`  | Theme ramp (`--foreground` → `--primary`) | Branch inks from trunk to tips, as `{ r, g, b }` objects. |

## Source

`components/ui/bough-study.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Generative Tree (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type RGB = { r: number; g: number; b: number };

type Branch = {
  x0: number;
  y0: number;
  angle: number;
  length: number;
  thickness: number;
  depth: number;
  growthProgress: number;
  growthSpeed: number;
  children: Branch[];
  spawned: boolean;
  swayPhase: number;
  swayAmp: number;
  curvature: number;
  colorShift: number;
  hueShift: number;
  parent: Branch | null;
  strokeSeeds: number[];
  tipDots: { ox: number; oy: number; size: number; alpha: number }[];
};

type Particle = {
  x: number;
  y: number;
  vx: number;
  vy: number;
  size: number;
  alpha: number;
  phase: number;
  freq: number;
  life: number;
  lifeSpeed: number;
};

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** HSL channels to sRGB 0–1 for shader uniforms. */
function toUnit([h, s, l]: Hsl): [number, number, number] {
  const sat = Math.min(100, Math.max(0, s)) / 100;
  const lig = Math.min(100, Math.max(0, l)) / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = sat * Math.min(lig, 1 - lig);
  const f = (n: number) => lig - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}

const rgb = (c: Hsl): RGB => {
  const [r, g, b] = toUnit(c);
  return { r: r * 255, g: g * 255, b: b * 255 };
};

/** Six inks from trunk to blossom: foreground ink at the base, the primary hue at the tips. */
function themePalette(): { palette: RGB[]; glow: RGB; ground: string } {
  const theme = readTheme();
  const [fh, fs, fl] = theme.foreground;
  const [ph, ps, pl] = theme.primary;
  const tipL = theme.dark ? Math.max(pl, 62) : Math.min(Math.max(pl, 34), 50);
  const palette = [0, 0.2, 0.4, 0.6, 0.8, 1].map((t) =>
    rgb([fh + (ph + 18 - fh) * t, fs + (Math.max(ps, 45) - fs) * t, fl + (tipL - fl) * t]),
  );
  return { palette, glow: rgb([ph, Math.max(ps, 40), tipL]), ground: hsl(theme.background) };
}

export interface BoughStudyProps {
  speed?: number;
  size?: number;
  particleAmount?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour behind the tree; defaults to the theme background. */
  backgroundColor?: string;
  /** Branch inks from trunk to tips; defaults to a ramp from the foreground to the primary. */
  colors?: RGB[];
  className?: string;
}

const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
const rand = (lo: number, hi: number) => Math.random() * (hi - lo) + lo;
const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
function smoothstep(a: number, b: number, t: number) {
  t = Math.max(0, Math.min(1, (t - a) / (b - a)));
  return t * t * (3 - 2 * t);
}

export function BoughStudy({
  speed = 1,
  size = 1,
  particleAmount = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
  colors,
  className,
}: BoughStudyProps) {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const prefersReducedMotion = useReducedMotion();
  const themeVersion = useThemeVersion();
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    const ctx = canvas.getContext("2d");
    if (!ctx) return;

    const themed = themePalette();
    const PALETTE = colors?.length ? colors : themed.palette;
    const ground = backgroundColor ?? themed.ground;
    const glowInk = `${themed.glow.r | 0}, ${themed.glow.g | 0}, ${themed.glow.b | 0}`;
    const MAX_DEPTH = 10;
    const GROWTH_SPEED_BASE = 0.006;
    const HOLD_DURATION = 400;
    const FADE_DURATION = 180;
    const WAIT_DURATION = 80;
    const PARTICLE_COUNT = Math.max(0, Math.round(50 * clamp(particleAmount, 0, 2)));
    const _pad = 1 / clamp(size, 0.65, 1.5);
    let W = 0;
    let H = 0;

    const particleSprite = document.createElement("canvas");
    particleSprite.width = 32;
    particleSprite.height = 32;
    const pctx = particleSprite.getContext("2d")!;
    const sg = pctx.createRadialGradient(16, 16, 0, 16, 16, 16);
    sg.addColorStop(0, `rgba(${glowInk}, 1)`);
    sg.addColorStop(0.3, `rgba(${glowInk}, 0.5)`);
    sg.addColorStop(1, `rgba(${glowInk}, 0)`);
    pctx.fillStyle = sg;
    pctx.fillRect(0, 0, 32, 32);

    function resize() {
      const rect = canvas!.getBoundingClientRect();
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      W = rect.width;
      H = rect.height;
      canvas!.width = Math.max(1, Math.round(W * dpr));
      canvas!.height = Math.max(1, Math.round(H * dpr));
      ctx!.setTransform(dpr, 0, 0, dpr, 0, 0);
    }

    let particles: Particle[] = [];
    function createParticle(fullRandom: boolean): Particle {
      return {
        x: rand(W * 0.15, W * 0.85),
        y: fullRandom ? rand(H * 0.1, H * 0.9) : rand(H * 0.5, H),
        vx: rand(-0.12, 0.12),
        vy: rand(-0.35, -0.06),
        size: rand(0.6, 2.2),
        alpha: rand(0.04, 0.2),
        phase: rand(0, Math.PI * 2),
        freq: rand(0.0004, 0.0015),
        life: fullRandom ? rand(0, 1) : 0,
        lifeSpeed: rand(0.0006, 0.0025),
      };
    }
    function initParticles() {
      particles = [];
      for (let i = 0; i < PARTICLE_COUNT; i++) particles.push(createParticle(true));
    }
    function updateParticles(time: number) {
      for (let i = 0; i < particles.length; i++) {
        const p = particles[i];
        p.x += p.vx + Math.sin(time * p.freq + p.phase) * 0.25;
        p.y += p.vy;
        p.life += p.lifeSpeed;
        if (p.life > 1 || p.y < -10 || p.x < -10 || p.x > W + 10) {
          particles[i] = createParticle(false);
        }
      }
    }
    function drawParticles(globalAlpha: number) {
      for (const p of particles) {
        const lifeFade = p.life < 0.15 ? p.life / 0.15 : p.life > 0.8 ? (1 - p.life) / 0.2 : 1;
        const a = p.alpha * lifeFade * globalAlpha;
        if (a < 0.004) continue;
        const s = p.size * 3;
        ctx!.globalAlpha = a;
        ctx!.drawImage(particleSprite, p.x - s, p.y - s, s * 2, s * 2);
      }
      ctx!.globalAlpha = 1;
    }

    function colorForDepth(depth: number, hueShift: number): RGB {
      const t = depth / MAX_DEPTH;
      const idx = t * (PALETTE.length - 1);
      const i0 = Math.floor(idx);
      const i1 = Math.min(PALETTE.length - 1, i0 + 1);
      const f = idx - i0;
      let r = lerp(PALETTE[i0].r, PALETTE[i1].r, f);
      let g = lerp(PALETTE[i0].g, PALETTE[i1].g, f);
      let b = lerp(PALETTE[i0].b, PALETTE[i1].b, f);
      const strength = t * t * 22;
      r += hueShift * strength * 1.0;
      g += hueShift * strength * -0.5;
      b += hueShift * strength * -0.15;
      return { r, g, b };
    }

    let allBranches: Branch[] = [];
    let treeAlpha = 1;
    let treeState: "growing" | "holding" | "fading" | "waiting" = "growing";
    let holdTimer = 0;
    let fadeTimer = 0;
    let waitTimer = 0;
    let mouseActive = false;
    let windForce = 0;
    let shakeAmount = 0;

    const seeds = () => [rand(-1, 1), rand(-1, 1), rand(-1, 1), rand(-1, 1), rand(-1, 1)];

    function createTree() {
      allBranches = [];
      const trunkLen = (H * rand(0.23, 0.28)) / _pad;
      const trunkThick = Math.max(8, W * 0.015) / _pad;
      const trunkAngle = -Math.PI / 2 + rand(-0.05, 0.05);
      const approxTreeH = trunkLen * 3.5;
      const baseY = _pad > 1 ? (H + approxTreeH) / 2 : H + trunkThick * 0.5;
      allBranches.push({
        x0: W * 0.62 + rand(-W * 0.03, W * 0.03),
        y0: baseY,
        angle: trunkAngle,
        length: trunkLen,
        thickness: trunkThick,
        depth: 0,
        growthProgress: 0,
        growthSpeed: GROWTH_SPEED_BASE * rand(0.9, 1.1),
        children: [],
        spawned: false,
        swayPhase: rand(0, Math.PI * 2),
        swayAmp: 0.0008,
        curvature: rand(-0.015, 0.015),
        colorShift: rand(-8, 8),
        hueShift: 0,
        parent: null,
        strokeSeeds: seeds(),
        tipDots: [],
      });
      treeState = "growing";
      holdTimer = fadeTimer = waitTimer = 0;
      treeAlpha = 1;
      initParticles();
    }

    function spawnChildren(parent: Branch) {
      if (parent.depth >= MAX_DEPTH) return;
      let numChildren: number;
      if (parent.depth < 1) numChildren = 2 + (Math.random() < 0.35 ? 1 : 0);
      else if (parent.depth < 3) numChildren = 2 + (Math.random() < 0.4 ? 1 : 0);
      else numChildren = Math.random() < 0.25 ? 3 : 2;
      const pruneChance =
        parent.depth <= 3 ? 0 : parent.depth <= 5 ? 0.1 : parent.depth <= 7 ? 0.22 : 0.35;
      if (Math.random() < pruneChance) numChildren = Math.max(1, numChildren - 1);
      const spread = parent.depth < 2 ? rand(0.32, 0.48) : rand(0.38, 0.6);

      for (let i = 0; i < numChildren; i++) {
        let angleOffset: number;
        if (numChildren === 1) angleOffset = rand(-0.25, 0.25);
        else if (numChildren === 2) angleOffset = (i === 0 ? -1 : 1) * rand(0.18, spread);
        else angleOffset = (i - 1) * spread + rand(-0.1, 0.1);

        const ep = getBranchEnd(parent, 1, 0);
        const tipDots: Branch["tipDots"] = [];
        const childDepth = parent.depth + 1;
        if (childDepth >= MAX_DEPTH) {
          const count = Math.random() < 0.4 ? 2 : 1;
          for (let d = 0; d < count; d++) {
            tipDots.push({
              ox: rand(-2, 2),
              oy: rand(-2, 2),
              size: rand(0.8, 1.6),
              alpha: rand(0.08, 0.2),
            });
          }
        }
        const child: Branch = {
          x0: ep.x,
          y0: ep.y,
          angle: parent.angle + angleOffset,
          length: parent.length * rand(0.58, 0.76),
          thickness: Math.max(0.4, parent.thickness * rand(0.48, 0.67)),
          depth: childDepth,
          growthProgress: 0,
          growthSpeed: GROWTH_SPEED_BASE * rand(1.0, 1.5) * (1 + parent.depth * 0.1),
          children: [],
          spawned: false,
          swayPhase: rand(0, Math.PI * 2),
          swayAmp: 0.0018 * (parent.depth + 1) * rand(0.7, 1.3),
          curvature: rand(-0.04, 0.04) * (1 + parent.depth * 0.12),
          colorShift: rand(-12, 12),
          hueShift: Math.max(-1, Math.min(1, parent.hueShift + rand(-0.35, 0.35))),
          parent,
          strokeSeeds: seeds(),
          tipDots,
        };
        parent.children.push(child);
        allBranches.push(child);
      }
    }

    function getSwayAngle(branch: Branch, time: number) {
      let total = 0;
      let b: Branch | null = branch;
      let depth = 0;
      while (b) {
        const a = b.swayAmp;
        total += Math.sin(time * 0.0005 + b.swayPhase) * a;
        total += Math.sin(time * 0.0003 + b.swayPhase * 1.7) * a * 0.6;
        total += Math.sin(time * 0.00012 + b.swayPhase * 0.4) * a * 0.35;
        depth++;
        b = b.parent;
      }
      if (mouseActive) total += windForce * 0.04 * depth;
      if (shakeAmount > 0.01) {
        total += Math.sin(time * 0.015 + branch.swayPhase * 3) * shakeAmount * 0.06 * depth;
      }
      return total;
    }

    function getBranchEnd(branch: Branch, progress: number, time: number) {
      const angle = branch.angle + getSwayAngle(branch, time);
      const len = branch.length * progress;
      const perpX = -Math.sin(angle);
      const perpY = Math.cos(angle);
      const curveOff = branch.curvature * len;
      return {
        x: branch.x0 + Math.cos(angle) * len + perpX * curveOff,
        y: branch.y0 + Math.sin(angle) * len + perpY * curveOff,
      };
    }

    function recalcPositions(time: number) {
      for (const b of allBranches) {
        if (b.parent) {
          const pe = getBranchEnd(b.parent, 1, time);
          b.x0 = pe.x;
          b.y0 = pe.y;
        }
      }
    }

    function updateBranches(step: number) {
      let allDone = true;
      for (const b of allBranches) {
        if (b.growthProgress < 1) {
          b.growthProgress = Math.min(1, b.growthProgress + b.growthSpeed * step);
          allDone = false;
        }
        if (b.growthProgress >= 0.65 && !b.spawned) {
          b.spawned = true;
          spawnChildren(b);
        }
      }
      return allDone;
    }

    function drawBranch(b: Branch, time: number) {
      if (b.growthProgress <= 0) return;
      const c = ctx!;
      const angle = b.angle + getSwayAngle(b, time);
      const progress = easeOutCubic(b.growthProgress);
      const len = b.length * progress;
      const x1 = b.x0;
      const y1 = b.y0;
      const perpX = -Math.sin(angle);
      const perpY = Math.cos(angle);
      const curveOff = b.curvature * len * 1.4;
      const cpx1 = x1 + Math.cos(angle) * len * 0.33 + perpX * curveOff * 0.4;
      const cpy1 = y1 + Math.sin(angle) * len * 0.33 + perpY * curveOff * 0.4;
      const cpx2 = x1 + Math.cos(angle) * len * 0.66 + perpX * curveOff * 0.85;
      const cpy2 = y1 + Math.sin(angle) * len * 0.66 + perpY * curveOff * 0.85;
      const x2 = x1 + Math.cos(angle) * len + perpX * curveOff * 0.7;
      const y2 = y1 + Math.sin(angle) * len + perpY * curveOff * 0.7;

      const col = colorForDepth(b.depth, b.hueShift);
      const depthT = b.depth / MAX_DEPTH;
      const baseAlpha =
        b.depth <= 1
          ? 0.95
          : b.depth <= 5
            ? lerp(0.92, 0.7, depthT)
            : lerp(0.7, 0.35, (depthT - 0.5) * 2);
      const strokeCount = b.depth < 3 ? 5 : b.depth < 6 ? 3 : 2;
      const thickBase = b.thickness;
      const thickTaper = lerp(thickBase, thickBase * 0.3, progress);

      for (let s = 0; s < strokeCount; s++) {
        const seed = b.strokeSeeds[s] || 0;
        const normalizedS = strokeCount > 1 ? s / (strokeCount - 1) - 0.5 : 0;
        const offsetAmt = normalizedS * thickBase * 0.35 + seed * thickBase * 0.08;
        const ox = perpX * offsetAmt;
        const oy = perpY * offsetAmt;
        const shift = normalizedS * 22 + b.colorShift * 0.3;
        const r = Math.max(0, Math.min(255, col.r + shift));
        const g = Math.max(0, Math.min(255, col.g + shift * 0.65));
        const bb = Math.max(0, Math.min(255, col.b + shift * 0.4));
        const isCore = s === Math.floor(strokeCount / 2);
        const alpha = baseAlpha * (isCore ? 1.0 : 0.5);
        const thick = thickTaper * (isCore ? 1.0 : lerp(0.65, 0.45, Math.abs(normalizedS)));
        c.beginPath();
        c.moveTo(x1 + ox, y1 + oy);
        c.bezierCurveTo(cpx1 + ox, cpy1 + oy, cpx2 + ox, cpy2 + oy, x2 + ox, y2 + oy);
        c.strokeStyle = `rgba(${r | 0}, ${g | 0}, ${bb | 0}, ${alpha})`;
        c.lineWidth = thick;
        c.lineCap = "round";
        c.stroke();
      }

      if (b.depth >= 4 && b.depth < MAX_DEPTH - 1 && b.growthProgress > 0.8) {
        const glowAlpha = smoothstep(0.8, 1.0, b.growthProgress) * 0.06 * (b.depth / MAX_DEPTH);
        const glowR = Math.max(4, thickBase * 2);
        const grd = c.createRadialGradient(x2, y2, 0, x2, y2, glowR);
        grd.addColorStop(
          0,
          `rgba(${Math.min(255, col.r + 30) | 0}, ${Math.min(255, col.g + 20) | 0}, ${Math.min(255, col.b + 15) | 0}, ${glowAlpha})`,
        );
        grd.addColorStop(
          0.5,
          `rgba(${col.r | 0}, ${col.g | 0}, ${col.b | 0}, ${glowAlpha * 0.25})`,
        );
        grd.addColorStop(1, `rgba(${col.r | 0}, ${col.g | 0}, ${col.b | 0}, 0)`);
        c.fillStyle = grd;
        c.beginPath();
        c.arc(x2, y2, glowR, 0, Math.PI * 2);
        c.fill();
      }

      if (b.tipDots.length > 0 && b.growthProgress > 0.92) {
        const tipFade = smoothstep(0.92, 1.0, b.growthProgress);
        const tr = Math.min(255, col.r * 1.3 + 30);
        const tg2 = Math.min(255, col.g * 1.3 + 25);
        const tb = Math.min(255, col.b * 1.2 + 20);
        for (const dot of b.tipDots) {
          const dx = x2 + dot.ox;
          const dy = y2 + dot.oy;
          const da = tipFade * dot.alpha;
          const ds = dot.size;
          const tg = c.createRadialGradient(dx, dy, 0, dx, dy, ds * 2);
          tg.addColorStop(0, `rgba(${tr | 0}, ${tg2 | 0}, ${tb | 0}, ${da * 0.6})`);
          tg.addColorStop(0.5, `rgba(${col.r | 0}, ${col.g | 0}, ${col.b | 0}, ${da * 0.15})`);
          tg.addColorStop(1, `rgba(${col.r | 0}, ${col.g | 0}, ${col.b | 0}, 0)`);
          c.fillStyle = tg;
          c.beginPath();
          c.arc(dx, dy, ds * 2, 0, Math.PI * 2);
          c.fill();
        }
      }
    }

    function drawScene(time: number, animateParticles: boolean) {
      const c = ctx!;
      c.clearRect(0, 0, W, H);
      c.fillStyle = ground;
      c.fillRect(0, 0, W, H);

      if (treeAlpha > 0.05) {
        const cx = W * 0.62;
        const cy = H * 0.38;
        const canopyGlow = c.createRadialGradient(cx, cy, 0, cx, cy, H * 0.42);
        canopyGlow.addColorStop(0, `rgba(${glowInk}, ${0.12 * treeAlpha})`);
        canopyGlow.addColorStop(0.5, `rgba(${glowInk}, ${0.04 * treeAlpha})`);
        canopyGlow.addColorStop(1, `rgba(${glowInk}, 0)`);
        c.fillStyle = canopyGlow;
        c.fillRect(0, 0, W, H);

        const groundGrad = c.createRadialGradient(W * 0.62, H, 0, W * 0.62, H, H * 0.3);
        groundGrad.addColorStop(0, `rgba(${glowInk}, ${0.08 * treeAlpha})`);
        groundGrad.addColorStop(1, `rgba(${glowInk}, 0)`);
        c.fillStyle = groundGrad;
        c.fillRect(0, H * 0.55, W, H * 0.45);
      }

      recalcPositions(time);
      c.save();
      c.globalAlpha = treeAlpha;
      for (const b of allBranches) drawBranch(b, time);
      c.restore();

      if (animateParticles) updateParticles(time);
      c.save();
      drawParticles(treeAlpha);
      c.restore();
    }

    let clock = 0;
    let last: number | null = null;
    function frame(realTime: number) {
      const s = speedRef.current;
      if (last !== null) clock += (realTime - last) * s;
      last = realTime;
      const time = clock;

      if (shakeAmount > 0.01) shakeAmount *= 0.95;
      else shakeAmount = 0;

      switch (treeState) {
        case "growing": {
          const done = updateBranches(s);
          drawScene(time, true);
          if (done) {
            treeState = "holding";
            holdTimer = 0;
          }
          break;
        }
        case "holding": {
          drawScene(time, true);
          holdTimer += s;
          if (holdTimer >= HOLD_DURATION) {
            treeState = "fading";
            fadeTimer = 0;
          }
          break;
        }
        case "fading": {
          fadeTimer += s;
          treeAlpha = Math.max(0, 1 - fadeTimer / FADE_DURATION);
          drawScene(time, true);
          if (fadeTimer >= FADE_DURATION) {
            treeState = "waiting";
            waitTimer = 0;
          }
          break;
        }
        case "waiting": {
          ctx!.clearRect(0, 0, W, H);
          ctx!.fillStyle = ground;
          ctx!.fillRect(0, 0, W, H);
          waitTimer += s;
          if (waitTimer >= WAIT_DURATION) createTree();
          break;
        }
      }
    }

    function renderStill() {
      while (!updateBranches(1)) {
        /* grow the full tree instantly */
      }
      drawScene(0, false);
    }

    resize();
    createTree();

    let raf = 0;
    let inView = true;
    const loop = (t: number) => {
      frame(t);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      if (raf || prefersReducedMotion || !inView || document.hidden) return;
      last = null;
      raf = requestAnimationFrame(loop);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };

    if (prefersReducedMotion) renderStill();
    else start();

    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) {
        createTree();
        renderStill();
      }
    });
    ro.observe(canvas);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry?.isIntersecting ?? true;
      if (inView) start();
      else stop();
    });
    io.observe(canvas);
    const onVisibility = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVisibility);

    const toLocalX = (clientX: number) => clientX - canvas.getBoundingClientRect().left;
    const onMove = (e: MouseEvent) => {
      mouseActive = true;
      windForce = (toLocalX(e.clientX) - W / 2) / (W / 2);
    };
    const onLeave = () => {
      mouseActive = false;
      windForce = 0;
    };
    const onClick = () => {
      shakeAmount = 1.0;
    };
    const onTouchStart = (e: TouchEvent) => {
      e.preventDefault();
      mouseActive = true;
      windForce = (toLocalX(e.touches[0].clientX) - W / 2) / (W / 2);
      shakeAmount = 1.0;
    };
    const onTouchMove = (e: TouchEvent) => {
      e.preventDefault();
      windForce = (toLocalX(e.touches[0].clientX) - W / 2) / (W / 2);
    };
    canvas.addEventListener("mousemove", onMove);
    canvas.addEventListener("mouseleave", onLeave);
    canvas.addEventListener("click", onClick);
    canvas.addEventListener("touchstart", onTouchStart, { passive: false });
    canvas.addEventListener("touchmove", onTouchMove, { passive: false });
    canvas.addEventListener("touchend", onLeave);

    return () => {
      stop();
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      canvas.removeEventListener("mousemove", onMove);
      canvas.removeEventListener("mouseleave", onLeave);
      canvas.removeEventListener("click", onClick);
      canvas.removeEventListener("touchstart", onTouchStart);
      canvas.removeEventListener("touchmove", onTouchMove);
      canvas.removeEventListener("touchend", onLeave);
    };
  }, [size, particleAmount, backgroundColor, colors, prefersReducedMotion, themeVersion]);

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))" }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="block h-full w-full"
        style={{
          opacity: clamp(opacity, 0.05, 1),
          filter: `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.8)})`,
        }}
      />
    </div>
  );
}
```

---

# Sigil Weather

> A WebGL2 background where lightning, water or flame plays around a sigil, toned in the active theme colours.

Install: `npx @modus-ui/cli add sigil-weather`

A full-bleed WebGL2 scene built around a signed distance field of a sigil. Lightning crawls fBm arcs along its contour by default; water refracts it beneath pointer-driven ripples, and flame licks noise-driven tongues and embers upward from its edge. The whole scene is mapped through a duotone of the theme tokens (background, primary, foreground), so it reads as ink on paper in light mode, glows in dark mode and follows the palette; set `palette="original"` to keep the source colours. It fills its positioned parent, pauses when off screen or when the tab is hidden, and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add sigil-weather
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/sigil-weather.tsx`.
3. Paste the code.

## Usage

```tsx
import { SigilWeather } from "@/components/ui/sigil-weather";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SigilWeather variant="lightning" />
    </div>
  );
}
```

## Props

| Prop              | Type                                | Default                                                                                      | Description                                                                         |
| :---------------- | :---------------------------------- | :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
| `variant`         | `"water" \| "lightning" \| "flame"` | `"lightning"`                                                                                | Which element plays around the sigil.                                               |
| `palette`         | `"theme" \| "original"`             | `"theme"`                                                                                    | `theme` tones the scene with the theme tokens; `original` keeps the source colours. |
| `markPath`        | `string`                            | `"M12 0C12.9 7 17 11.1 24 12C17 12.9 12.9 17 12 24C11.1 17 7 12.9 0 12C7 11.1 11.1 7 12 0Z"` | SVG path data in a 24×24 viewBox used as the central mark.                          |
| `speed`           | `number`                            | `1`                                                                                          | Animation speed multiplier (0 to 3).                                                |
| `size`            | `number`                            | `1`                                                                                          | Mark size multiplier (0.65 to 1.5).                                                 |
| `particleAmount`  | `number`                            | `1`                                                                                          | Particle count multiplier (0 to 2).                                                 |
| `opacity`         | `number`                            | `1`                                                                                          | Canvas opacity (0.05 to 1).                                                         |
| `hue`             | `number`                            | `0`                                                                                          | Hue rotation in degrees (-180 to 180).                                              |
| `saturation`      | `number`                            | `1`                                                                                          | Saturation multiplier (0 to 2).                                                     |
| `brightness`      | `number`                            | `1`                                                                                          | Brightness multiplier (0.35 to 1.8).                                                |
| `backgroundColor` | `string`                            | `--background`                                                                               | Darkest tone of the scene (theme token by default).                                 |

## Source

`components/ui/sigil-weather.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Elemental Marks (MIT, © 2026 Meng To).

import { useEffect, useId, useMemo, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

export type SigilWeatherVariant = "water" | "lightning" | "flame";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

/** Resolves any CSS colour to 0..1 RGB channels. */
function toRgb(color: string): [number, number, number] {
  const ctx = document.createElement("canvas").getContext("2d");
  if (!ctx) return [0, 0, 0];
  ctx.fillStyle = color;
  ctx.fillRect(0, 0, 1, 1);
  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
  return [r / 255, g / 255, b / 255];
}

export interface SigilWeatherProps {
  variant?: SigilWeatherVariant;
  /** `theme` maps the scene's light onto the background → primary → foreground tokens; `original` keeps the source colours. */
  palette?: "theme" | "original";
  /** SVG path data (24×24 viewBox) for the mark the element plays around. */
  markPath?: string;
  speed?: number;
  size?: number;
  particleAmount?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Darkest tone of the scene. Defaults to the theme's `--background`. */
  backgroundColor?: string;
  className?: string;
}

const DEFAULT_MARK =
  "M12 0C12.9 7 17 11.1 24 12C17 12.9 12.9 17 12 24C11.1 17 7 12.9 0 12C7 11.1 11.1 7 12 0Z";

const SDF_SIZE = 768;
const SDF_SPREAD = 192;
const D_RANGE = (SDF_SPREAD * 2) / SDF_SIZE;
const SIM_RES = 512;

const BASE_ZOOM: Record<SigilWeatherVariant, number> = {
  water: 1.56,
  lightning: 1.66,
  flame: 1.82,
};

const BASE_PARTICLES: Record<SigilWeatherVariant, number> = {
  water: 160,
  lightning: 360,
  flame: 560,
};

type ParticleCfg = {
  travel: number;
  lifeMin: number;
  lifeMax: number;
  alongNormal: number;
  wiggle: number;
  sizeMin: number;
  sizeMax: number;
  sparse: number;
  colA: [number, number, number];
  colB: [number, number, number];
};

const VARIANT_OPTS: Record<
  SigilWeatherVariant,
  { sim: boolean; shift: [number, number]; particles: ParticleCfg }
> = {
  water: {
    sim: true,
    shift: [0, 0],
    particles: {
      travel: 0.1,
      lifeMin: 4.0,
      lifeMax: 8.0,
      alongNormal: 0.15,
      wiggle: 0.02,
      sizeMin: 1.5,
      sizeMax: 3.5,
      sparse: 0.5,
      colA: [0.1, 0.24, 0.3],
      colB: [0.22, 0.4, 0.48],
    },
  },
  lightning: {
    sim: false,
    shift: [0, 0],
    particles: {
      travel: 0.075,
      lifeMin: 0.28,
      lifeMax: 0.82,
      alongNormal: 0.92,
      wiggle: 0.022,
      sizeMin: 0.8,
      sizeMax: 2.0,
      sparse: 0.72,
      colA: [0.45, 0.5, 1.0],
      colB: [0.95, 0.95, 1.0],
    },
  },
  flame: {
    sim: false,
    shift: [0, -0.11],
    particles: {
      travel: 0.34,
      lifeMin: 1.1,
      lifeMax: 2.7,
      alongNormal: 0.3,
      wiggle: 0.046,
      sizeMin: 0.9,
      sizeMax: 3.6,
      sparse: 0.42,
      colA: [1.0, 0.62, 0.28],
      colB: [1.0, 0.3, 0.1],
    },
  },
};

function clamp(v: number, lo: number, hi: number) {
  return Math.min(hi, Math.max(lo, v));
}

/* ---------------- rasterize -> SDF (chamfer) + edge point extraction ---------------- */
function rasterizeLogo(pathStr: string) {
  const c = document.createElement("canvas");
  c.width = c.height = SDF_SIZE;
  const ctx = c.getContext("2d")!;
  const box = SDF_SIZE * 0.6;
  const s = box / 24;
  const off = (SDF_SIZE - box) / 2;
  ctx.setTransform(s, 0, 0, s, off, off);
  ctx.fillStyle = "white";
  ctx.fill(new Path2D(pathStr));
  return ctx.getImageData(0, 0, SDF_SIZE, SDF_SIZE);
}

function chamfer(d: Float32Array, w: number, h: number) {
  const D1 = 1,
    D2 = Math.SQRT2;
  for (let y = 0; y < h; y++)
    for (let x = 0; x < w; x++) {
      const i = y * w + x;
      let v = d[i];
      if (x > 0) v = Math.min(v, d[i - 1] + D1);
      if (y > 0) {
        v = Math.min(v, d[i - w] + D1);
        if (x > 0) v = Math.min(v, d[i - w - 1] + D2);
        if (x < w - 1) v = Math.min(v, d[i - w + 1] + D2);
      }
      d[i] = v;
    }
  for (let y = h - 1; y >= 0; y--)
    for (let x = w - 1; x >= 0; x--) {
      const i = y * w + x;
      let v = d[i];
      if (x < w - 1) v = Math.min(v, d[i + 1] + D1);
      if (y < h - 1) {
        v = Math.min(v, d[i + w] + D1);
        if (x < w - 1) v = Math.min(v, d[i + w + 1] + D2);
        if (x > 0) v = Math.min(v, d[i + w - 1] + D2);
      }
      d[i] = v;
    }
}

function buildSDF(img: ImageData) {
  const n = SDF_SIZE * SDF_SIZE;
  const dOut = new Float32Array(n),
    dIn = new Float32Array(n);
  for (let i = 0; i < n; i++) {
    const inside = img.data[i * 4 + 3] > 127;
    dOut[i] = inside ? 0 : 1e9;
    dIn[i] = inside ? 1e9 : 0;
  }
  chamfer(dOut, SDF_SIZE, SDF_SIZE);
  chamfer(dIn, SDF_SIZE, SDF_SIZE);
  const enc = new Uint8Array(n);
  for (let i = 0; i < n; i++) {
    const d = dOut[i] - dIn[i];
    enc[i] = Math.max(0, Math.min(255, Math.round((0.5 + (0.5 * d) / SDF_SPREAD) * 255)));
  }
  return enc;
}

function edgePoints(img: ImageData) {
  const S = SDF_SIZE,
    pts: number[] = [];
  const a = (x: number, y: number) => img.data[(y * S + x) * 4 + 3] > 127;
  for (let y = 1; y < S - 1; y++) {
    for (let x = 1; x < S - 1; x++) {
      if (!a(x, y)) continue;
      const l = a(x - 1, y),
        r = a(x + 1, y),
        u = a(x, y - 1),
        dn = a(x, y + 1);
      if (l && r && u && dn) continue;
      const gx = (r ? 1 : 0) - (l ? 1 : 0);
      const gy = (dn ? 1 : 0) - (u ? 1 : 0);
      let nx = -gx,
        ny = gy;
      const len = Math.hypot(nx, ny);
      if (!len) {
        nx = 0;
        ny = 1;
      } else {
        nx /= len;
        ny /= len;
      }
      pts.push((x + 0.5) / S, 1 - (y + 0.5) / S, nx, ny);
    }
  }
  return pts;
}

function makeParticleData(pts: number[], count: number) {
  const data = new Float32Array(count * 5);
  const nPts = pts.length / 4;
  for (let i = 0; i < count; i++) {
    const j = (Math.random() * nPts) | 0;
    data[i * 5] = pts[j * 4];
    data[i * 5 + 1] = pts[j * 4 + 1];
    data[i * 5 + 2] = pts[j * 4 + 2];
    data[i * 5 + 3] = pts[j * 4 + 3];
    data[i * 5 + 4] = Math.random() * 100 + i * 0.618;
  }
  return data;
}

/* ---------------- shaders ---------------- */
const VERT = `#version 300 es
out vec2 vUv;
void main(){
  vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
  vUv = p;
  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
}`;

const GLSL_COMMON = `
precision highp float;
uniform sampler2D uSDF;
uniform float uTime;
uniform float uAspect;
uniform vec2  uScale;
uniform vec2  uShift;
uniform vec3  uPointer;
in vec2 vUv;
out vec4 frag;

float hash21(vec2 p){
  p = fract(p * vec2(123.34, 456.21));
  p += dot(p, p + 45.32);
  return fract(p.x * p.y);
}
float vnoise(vec2 p){
  vec2 i = floor(p), f = fract(p);
  f = f * f * (3.0 - 2.0 * f);
  float a = hash21(i), b = hash21(i + vec2(1,0));
  float c = hash21(i + vec2(0,1)), d = hash21(i + vec2(1,1));
  return mix(mix(a,b,f.x), mix(c,d,f.x), f.y);
}
float fbm(vec2 p){
  float v = 0.0, a = 0.5;
  mat2 r = mat2(0.8, -0.6, 0.6, 0.8);
  for (int i = 0; i < 5; i++){ v += a * vnoise(p); p = r * p * 2.03; a *= 0.5; }
  return v;
}
float sdf(vec2 uv){
  vec2 m = 0.5 + (uv - 0.5 - uShift) * uScale;
  vec2 mc = clamp(m, 0.0, 1.0);
  float d = (texture(uSDF, vec2(mc.x, 1.0 - mc.y)).r - 0.5) * ${D_RANGE.toFixed(4)};
  return d + length(m - mc);
}
float edgeFade(vec2 uv){
  return smoothstep(0.0, 0.05, uv.x) * smoothstep(1.0, 0.95, uv.x)
       * smoothstep(0.0, 0.05, uv.y) * smoothstep(1.0, 0.95, uv.y);
}
`;

const FRAG_SIM = `#version 300 es
precision highp float;
uniform sampler2D uState;
uniform vec2 uTexel;
uniform vec3 uDrop;
in vec2 vUv;
out vec4 frag;
void main(){
  vec2 s = texture(uState, vUv).rg;
  float l = texture(uState, vUv - vec2(uTexel.x, 0.0)).r;
  float r = texture(uState, vUv + vec2(uTexel.x, 0.0)).r;
  float u = texture(uState, vUv + vec2(0.0, uTexel.y)).r;
  float d = texture(uState, vUv - vec2(0.0, uTexel.y)).r;
  float next = (l + r + u + d) * 0.5 - s.g;
  next *= 0.984;
  if (uDrop.z != 0.0){
    float dd = distance(vUv, uDrop.xy);
    next += uDrop.z * exp(-dd * dd * 3800.0);
  }
  frag = vec4(next, s.r, 0.0, 1.0);
}`;

const FRAG_WATER = `#version 300 es
${GLSL_COMMON}
uniform sampler2D uState;
uniform vec2 uSimTexel;
vec2 simUV(vec2 uv){
  return 0.5 + (uv - 0.5) * vec2(uAspect, 1.0) / max(uAspect, 1.0);
}
void main(){
  vec2 suv = simUV(vUv);
  float h  = texture(uState, suv).r;
  float hx = texture(uState, suv + vec2(uSimTexel.x, 0.0)).r - texture(uState, suv - vec2(uSimTexel.x, 0.0)).r;
  float hy = texture(uState, suv + vec2(0.0, uSimTexel.y)).r - texture(uState, suv - vec2(0.0, uSimTexel.y)).r;
  vec2 grad = vec2(hx, hy);
  vec3 nrm = normalize(vec3(-grad * 30.0, 1.0));

  vec2 ruv = vUv + grad * 0.22;
  float d  = sdf(ruv);

  vec3 col = mix(vec3(0.006, 0.030, 0.055), vec3(0.012, 0.078, 0.125), vUv.y * 0.8 + h * 0.25);
  col += vec3(0.02, 0.10, 0.13) * fbm(vUv * vec2(uAspect, 1.0) * 3.0 + uTime * 0.05) * 0.3;

  float logo = smoothstep(0.005, -0.005, d);
  float glow = exp(-max(d, 0.0) / 0.09) * 0.26;
  vec3 markCol = mix(vec3(0.55, 0.92, 1.0), vec3(0.95, 1.0, 1.0), logo * 0.6);
  col += markCol * (logo * 0.92 + glow);

  col += vec3(0.09, 0.30, 0.40) * clamp(h * 1.8, -0.06, 1.0);
  col += vec3(0.25, 0.55, 0.65) * pow(clamp(h * 2.6, 0.0, 1.0), 2.0) * 0.5;

  vec3 L = normalize(vec3(-0.35, 0.55, 0.75));
  vec3 H = normalize(L + vec3(0.0, 0.0, 1.0));
  float spec = pow(max(dot(nrm, H), 0.0), 150.0);
  col += spec * vec3(0.65, 0.9, 1.0) * 0.9;

  col *= 0.35 + 0.65 * edgeFade(vUv);
  col += (hash21(vUv * 617.0 + uTime) - 0.5) / 128.0;
  frag = vec4(col, 1.0);
}`;

const FRAG_LIGHTNING = `#version 300 es
${GLSL_COMMON}
void main(){
  float t = uTime;
  float d = sdf(vUv);
  vec2 pp = vUv * vec2(uAspect, 1.0);

  vec3 col = vec3(0.010, 0.011, 0.024);
  col += vec3(0.035, 0.04, 0.075) * fbm(pp * 2.2 + vec2(t * 0.04, t * 0.01));

  float slot = floor(t * 0.45);
  float ph   = fract(t * 0.45);
  float big  = step(0.68, hash21(vec2(slot, 3.7))) * exp(-ph * 16.0);

  float inside = smoothstep(0.0025, -0.0025, d);
  vec3 body = vec3(0.055, 0.06, 0.10) + big * vec3(0.55, 0.58, 0.85);
  col = mix(col, body, inside);
  float rim = exp(-abs(d) / 0.0075) * 0.56;
  col += rim * vec3(0.35, 0.4, 0.8);

  vec2 dp = (vUv - uPointer.xy) * vec2(uAspect, 1.0);
  float pb = 1.0 + 2.4 * uPointer.z * exp(-dot(dp, dp) * 34.0);

  float fade = edgeFade(vUv);
  for (int i = 0; i < 5; i++){
    float fi = float(i);
    float layer = fi / 4.0;
    float coarse = fbm(pp * mix(4.0, 13.0, layer) + vec2(t * (1.3 + fi * 0.78), fi * 17.7)) - 0.5;
    float detail = fbm(pp * mix(17.0, 31.0, layer) + vec2(-t * (2.9 + fi * 0.55), fi * 31.7)) - 0.5;
    float n = coarse * mix(0.82, 0.58, layer) + detail * mix(0.18, 0.42, layer);
    float e = abs(d + n * mix(0.09, 0.038, layer));
    float fl = hash21(vec2(floor(t * (7.0 + fi * 3.4)), fi));
    fl = mix(0.12, 1.0, smoothstep(0.22, 0.94, fl));
    float width = mix(0.0034, 0.0012, layer);
    float bolt = pow(width * pb / (e + mix(0.0018, 0.0008, layer)), mix(1.42, 1.78, layer)) * fl;
    bolt = min(bolt, 7.0);
    col += bolt * mix(vec3(0.34, 0.39, 1.0), vec3(0.96, 0.94, 1.0), pow(layer, 0.75)) * fade;
  }

  float n0 = fbm(pp * 6.5 + vec2(t * 2.8, 7.7)) - 0.5;
  n0 += (fbm(pp * 23.0 + vec2(-t * 4.1, 18.2)) - 0.5) * 0.22;
  float e0 = abs(d + n0 * 0.075);
  float corefl = mix(0.22, 1.2, hash21(vec2(floor(t * 10.0), 11.0)));
  col += min(pow(0.00175 * pb / (e0 + 0.0009), 1.78), 9.0) * corefl * vec3(1.0) * fade;

  float branchNoise = fbm(pp * 16.0 + vec2(t * 3.7, -13.4)) - 0.5;
  float branchEdge = abs(d + n0 * 0.052 + branchNoise * 0.026);
  float branchLife = smoothstep(0.35, 0.92, hash21(vec2(floor(t * 13.0), 23.0)));
  col += min(pow(0.0011 * pb / (branchEdge + 0.00075), 1.72), 5.0)
       * branchLife * vec3(0.64, 0.70, 1.0) * fade;

  col += big * vec3(0.30, 0.32, 0.55) * (0.25 + 0.75 * inside);
  col = col / (1.0 + col * 0.18);
  col *= 0.4 + 0.6 * edgeFade(vUv);
  col += (hash21(vUv * 431.0 + uTime) - 0.5) / 128.0;
  frag = vec4(col, 1.0);
}`;

const FRAG_FIRE = `#version 300 es
${GLSL_COMMON}
uniform float uWind;

vec3 fireRamp(float x){
  x = clamp(x, 0.0, 1.0);
  vec3 c = mix(vec3(0.0), vec3(0.45, 0.06, 0.02), smoothstep(0.02, 0.30, x));
  c = mix(c, vec3(0.95, 0.34, 0.08), smoothstep(0.28, 0.55, x));
  c = mix(c, vec3(1.0, 0.68, 0.22), smoothstep(0.52, 0.78, x));
  c = mix(c, vec3(1.0, 0.97, 0.88), smoothstep(0.78, 0.97, x));
  return c;
}

void main(){
  float t = uTime;
  float d0 = sdf(vUv);
  vec2 pp = vUv * vec2(uAspect, 1.0);

  float e = 0.012;
  vec2 g = vec2(sdf(vUv + vec2(e, 0.0)) - sdf(vUv - vec2(e, 0.0)),
                sdf(vUv + vec2(0.0, e)) - sdf(vUv - vec2(0.0, e)));
  float upw = smoothstep(-0.2, 0.9, normalize(g + 1e-5).y);

  vec2 dp = (vUv - uPointer.xy) * vec2(uAspect, 1.0);
  float stoke = uPointer.z * exp(-dot(dp, dp) * 26.0);

  float n1 = fbm(vec2(pp.x * 11.0,        pp.y * 3.2 - t * 2.2));
  float n2 = fbm(vec2(pp.x * 6.5 + 41.3,  pp.y * 1.8 - t * 1.3));
  float n3 = fbm(vec2(pp.x * 27.0 - t * 0.7, pp.y * 7.5 - t * 4.0));
  float d0f = d0 + (hash21(vUv * 771.0 + t * 1.3) - 0.5) * 0.0025;
  float rise = max(0.0, n1 * 0.98 + n2 * 0.54 + n3 * 0.38 - 0.58) * 1.48;
  float adv  = smoothstep(-0.025, 0.24, d0f);
  float lick = 0.31 * (1.0 + stoke * 0.82);
  vec2 offs = vec2((n2 - 0.5) * 0.042 + (n3 - 0.5) * 0.018 + uWind * 0.05, -rise * lick * adv);
  float df = sdf(vUv + offs);
  float micro = fbm(pp * vec2(34.0, 9.0) + vec2(t * 1.1, -t * 5.2));
  df += (micro - 0.5) * 0.011 * adv;
  df += (hash21(vUv * 997.0 + uTime) - 0.5) * 0.0025;

  float heat = clamp(1.0 - df / 0.064, 0.0, 1.0);
  heat *= mix(0.08, 1.0, upw);
  heat *= 1.0 - 0.52 * smoothstep(0.07, 0.27, d0f);
  heat *= 0.84 + n3 * 0.24;
  float tongue = smoothstep(0.29, 0.69, heat);
  float filament = smoothstep(0.58, 0.91, heat + (n3 - 0.5) * 0.20);
  float split = smoothstep(0.38, 0.82, n3) * smoothstep(0.015, 0.23, d0f);
  float body = pow(heat, 2.35) * 0.36;
  float f = max(max(tongue * (0.72 + 0.28 * n3), filament * split * 0.88), body)
          * (0.95 + 0.25 * stoke);

  vec3 col = vec3(0.012, 0.006, 0.004);
  col += fireRamp(f * (1.05 - 0.4 * smoothstep(0.02, 0.25, d0)));
  float vein = pow(clamp(1.0 - abs(df) / 0.026, 0.0, 1.0), 3.2)
             * smoothstep(0.55, 0.9, n3) * upw * (0.35 + 0.65 * adv);
  col += fireRamp(0.82) * vein * 0.34;

  float inside = smoothstep(0.0025, -0.0025, d0);
  float core   = smoothstep(0.0, -0.016, d0);
  vec3 markCol = mix(vec3(1.0, 0.92, 0.78), vec3(1.0, 1.0, 0.98), core);
  col = mix(col, markCol, inside);
  col += exp(-max(d0, 0.0) / 0.026) * vec3(1.0, 0.55, 0.22) * 0.30 * (1.0 - inside * 0.92);
  col += exp(-max(d0, 0.0) / 0.09)  * vec3(0.55, 0.14, 0.03) * 0.28 * (0.55 + 0.45 * n2);

  col = col / (1.0 + col * 0.12);
  col *= 0.35 + 0.65 * edgeFade(vUv);
  col += (hash21(vUv * 523.0 + uTime) - 0.5) / 128.0;
  frag = vec4(col, 1.0);
}`;

const PART_VERT = `#version 300 es
precision highp float;
layout(location=0) in vec2 aPos;
layout(location=1) in vec2 aNorm;
layout(location=2) in float aSeed;
uniform float uTime;
uniform vec2  uScale;
uniform vec2  uShift;
uniform float uDpr;
uniform float uWind;
uniform vec4  uCfgA;
uniform vec4  uCfgB;
out float vFade;
out float vMixC;
float h1(float n){ return fract(sin(n) * 43758.5453); }
void main(){
  float hs   = h1(aSeed * 1.31);
  float life = mix(uCfgA.y, uCfgA.z, hs);
  float tt   = uTime / life + aSeed * 13.7;
  float ph   = fract(tt);
  float cyc  = floor(tt);
  float r1 = h1(aSeed + cyc * 0.317);
  float r2 = h1(aSeed * 2.13 + cyc * 0.771);
  float on = step(uCfgB.w, r2);

  vec2 dir = normalize(mix(vec2(0.0, 1.0), aNorm, uCfgA.w) + (vec2(r1, h1(r1 * 7.0)) - 0.5) * 0.8);
  float trav = uCfgA.x * (0.45 + 0.9 * r1);
  vec2 p = aPos + aNorm * 0.004 + dir * trav * ph;
  p.x += sin(ph * 10.0 + r1 * 40.0 + uTime * 0.5) * uCfgB.x * ph;
  p.x += uWind * 0.08 * ph;

  vec2 uv = 0.5 + uShift + (p - 0.5) / uScale;
  vFade = on * smoothstep(0.0, 0.12, ph) * smoothstep(1.0, 0.5, ph) * mix(0.35, 1.0, r2);
  vMixC = h1(aSeed * 3.7 + cyc);
  gl_Position = vec4(uv * 2.0 - 1.0, 0.0, 1.0);
  gl_PointSize = mix(uCfgB.y, uCfgB.z, h1(aSeed * 5.11 + cyc)) * uDpr * (1.0 - 0.45 * ph);
}`;

const PART_FRAG = `#version 300 es
precision highp float;
uniform vec3 uColA;
uniform vec3 uColB;
in float vFade;
in float vMixC;
out vec4 frag;
void main(){
  vec2 q = gl_PointCoord * 2.0 - 1.0;
  float r2 = dot(q, q);
  if (r2 > 1.0) discard;
  float a = exp(-r2 * 3.5) * (1.0 - r2);
  frag = vec4(mix(uColA, uColB, vMixC) * a * vFade, 1.0);
}`;

const FRAGS: Record<SigilWeatherVariant, string> = {
  water: FRAG_WATER,
  lightning: FRAG_LIGHTNING,
  flame: FRAG_FIRE,
};

function compile(gl: WebGL2RenderingContext, type: number, src: string) {
  const sh = gl.createShader(type)!;
  gl.shaderSource(sh, src);
  gl.compileShader(sh);
  if (!gl.getShaderParameter(sh, gl.COMPILE_STATUS)) {
    console.error(gl.getShaderInfoLog(sh));
    gl.deleteShader(sh);
    return null;
  }
  return sh;
}

function program(gl: WebGL2RenderingContext, vs: string, fs: string) {
  const v = compile(gl, gl.VERTEX_SHADER, vs);
  const f = compile(gl, gl.FRAGMENT_SHADER, fs);
  if (!v || !f) return null;
  const p = gl.createProgram()!;
  gl.attachShader(p, v);
  gl.attachShader(p, f);
  gl.linkProgram(p);
  gl.deleteShader(v);
  gl.deleteShader(f);
  if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
    console.error(gl.getProgramInfoLog(p));
    return null;
  }
  return p;
}

export function SigilWeather({
  variant = "lightning",
  palette = "theme",
  markPath = DEFAULT_MARK,
  speed = 1,
  size = 1,
  particleAmount = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
  className,
}: SigilWeatherProps) {
  const filterId = `sigil-${useId().replace(/:/g, "")}`;
  const tokens = useTokens();
  const ground = backgroundColor ?? tokens?.background;
  // A three-stop duotone: dark scene → ground, mid light → primary, highlights → foreground.
  const ramp = useMemo(
    () =>
      palette === "theme" && tokens && ground
        ? [ground, tokens.primary, tokens.foreground].map(toRgb)
        : null,
    [palette, tokens, ground],
  );
  const table = (channel: number) => (ramp ?? []).map((rgb) => rgb[channel].toFixed(3)).join(" ");
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);
  const prefersReducedMotion = useReducedMotion();

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    const gl = canvas.getContext("webgl2", { alpha: false, antialias: false });
    if (!gl) return;

    const opts = VARIANT_OPTS[variant] ?? VARIANT_OPTS.water;
    const P = opts.particles;
    const zoom = BASE_ZOOM[variant] / clamp(size, 0.65, 1.5);
    const count = Math.max(0, Math.round(BASE_PARTICLES[variant] * clamp(particleAmount, 0, 2)));
    const DPR = Math.min(Math.max(window.devicePixelRatio || 1, 1.5), 2);
    const reduced = !!prefersReducedMotion;

    const img = rasterizeLogo(markPath);
    const sdfData = buildSDF(img);
    const edges = edgePoints(img);

    const prog = program(gl, VERT, FRAGS[variant]);
    if (!prog) return;
    const uni: Record<string, WebGLUniformLocation | null> = {};
    for (const n of [
      "uSDF",
      "uTime",
      "uAspect",
      "uScale",
      "uShift",
      "uPointer",
      "uState",
      "uSimTexel",
      "uWind",
    ])
      uni[n] = gl.getUniformLocation(prog, n);

    const sdfTex = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, sdfTex);
    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
    gl.texImage2D(
      gl.TEXTURE_2D,
      0,
      gl.R8,
      SDF_SIZE,
      SDF_SIZE,
      0,
      gl.RED,
      gl.UNSIGNED_BYTE,
      sdfData,
    );
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);

    let sim = opts.sim;
    let simProg: WebGLProgram | null = null;
    const simUni: Record<string, WebGLUniformLocation | null> = {};
    const simTex: WebGLTexture[] = [];
    const simFbo: WebGLFramebuffer[] = [];
    let simSrc = 0;
    if (sim) {
      simProg = gl.getExtension("EXT_color_buffer_float") ? program(gl, VERT, FRAG_SIM) : null;
      if (!simProg) sim = false;
      else {
        for (const n of ["uState", "uTexel", "uDrop"])
          simUni[n] = gl.getUniformLocation(simProg, n);
        for (let i = 0; i < 2; i++) {
          const t = gl.createTexture()!;
          gl.bindTexture(gl.TEXTURE_2D, t);
          gl.texImage2D(
            gl.TEXTURE_2D,
            0,
            gl.RG16F,
            SIM_RES,
            SIM_RES,
            0,
            gl.RG,
            gl.HALF_FLOAT,
            null,
          );
          gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
          gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
          gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
          gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
          const f = gl.createFramebuffer()!;
          gl.bindFramebuffer(gl.FRAMEBUFFER, f);
          gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, t, 0);
          simTex.push(t);
          simFbo.push(f);
        }
        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
      }
    }

    const partProg = count > 0 ? program(gl, PART_VERT, PART_FRAG) : null;
    const partUni: Record<string, WebGLUniformLocation | null> = {};
    let partVao: WebGLVertexArrayObject | null = null;
    let partBuf: WebGLBuffer | null = null;
    if (partProg) {
      for (const n of [
        "uTime",
        "uScale",
        "uShift",
        "uDpr",
        "uWind",
        "uCfgA",
        "uCfgB",
        "uColA",
        "uColB",
      ])
        partUni[n] = gl.getUniformLocation(partProg, n);
      partVao = gl.createVertexArray();
      gl.bindVertexArray(partVao);
      partBuf = gl.createBuffer();
      gl.bindBuffer(gl.ARRAY_BUFFER, partBuf);
      gl.bufferData(gl.ARRAY_BUFFER, makeParticleData(edges, count), gl.STATIC_DRAW);
      gl.enableVertexAttribArray(0);
      gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 20, 0);
      gl.enableVertexAttribArray(1);
      gl.vertexAttribPointer(1, 2, gl.FLOAT, false, 20, 8);
      gl.enableVertexAttribArray(2);
      gl.vertexAttribPointer(2, 1, gl.FLOAT, false, 20, 16);
      gl.bindVertexArray(null);
    }

    const pointer = { x: 0.5, y: 0.5, active: 0 };
    let wind = 0;
    let windTarget = 0;
    const dropQueue: { x: number; y: number; s: number }[] = [];
    let nextAutoDrop = 0.6;
    let aspect = 1;
    let needsResize = false;

    const resize = () => {
      const r = host.getBoundingClientRect();
      const w = Math.max(2, Math.round(r.width * DPR));
      const h = Math.max(2, Math.round(r.height * DPR));
      if (canvas.width !== w || canvas.height !== h) {
        canvas.width = w;
        canvas.height = h;
      }
      aspect = w / h;
    };

    const toSimUV = (x: number, y: number) => {
      const m = Math.max(aspect, 1);
      return { x: 0.5 + ((x - 0.5) * aspect) / m, y: 0.5 + (y - 0.5) / m };
    };

    const stepSim = (t: number) => {
      if (t > nextAutoDrop) {
        dropQueue.push({
          x: 0.12 + Math.random() * 0.76,
          y: 0.12 + Math.random() * 0.76,
          s: 0.12 + Math.random() * 0.3,
        });
        nextAutoDrop = t + 0.5 + Math.random() * 1.4;
      }
      gl.useProgram(simProg);
      gl.viewport(0, 0, SIM_RES, SIM_RES);
      gl.uniform2f(simUni.uTexel, 1 / SIM_RES, 1 / SIM_RES);
      for (let i = 0; i < 2; i++) {
        const drop = dropQueue.shift();
        if (drop) {
          const s = toSimUV(drop.x, drop.y);
          gl.uniform3f(simUni.uDrop, s.x, s.y, drop.s);
        } else gl.uniform3f(simUni.uDrop, 0, 0, 0);
        gl.bindFramebuffer(gl.FRAMEBUFFER, simFbo[1 - simSrc]);
        gl.activeTexture(gl.TEXTURE1);
        gl.bindTexture(gl.TEXTURE_2D, simTex[simSrc]);
        gl.uniform1i(simUni.uState, 1);
        gl.drawArrays(gl.TRIANGLES, 0, 3);
        simSrc = 1 - simSrc;
      }
      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
    };

    const draw = (t: number) => {
      if (needsResize) {
        needsResize = false;
        resize();
      }
      if (sim) stepSim(t);
      wind += (windTarget - wind) * 0.04;
      windTarget *= 0.97;

      gl.useProgram(prog);
      gl.viewport(0, 0, canvas.width, canvas.height);
      const fit = Math.min(aspect, 1);
      const sc = [(aspect / fit) * zoom, (1 / fit) * zoom];
      gl.uniform1f(uni.uTime, t);
      gl.uniform1f(uni.uAspect, aspect);
      gl.uniform2f(uni.uScale, sc[0], sc[1]);
      gl.uniform2f(uni.uShift, opts.shift[0], opts.shift[1]);
      gl.uniform3f(uni.uPointer, pointer.x, pointer.y, pointer.active);
      if (uni.uWind) gl.uniform1f(uni.uWind, wind);
      gl.activeTexture(gl.TEXTURE0);
      gl.bindTexture(gl.TEXTURE_2D, sdfTex);
      gl.uniform1i(uni.uSDF, 0);
      if (sim) {
        gl.activeTexture(gl.TEXTURE1);
        gl.bindTexture(gl.TEXTURE_2D, simTex[simSrc]);
        gl.uniform1i(uni.uState, 1);
        gl.uniform2f(uni.uSimTexel, 1 / SIM_RES, 1 / SIM_RES);
      }
      gl.drawArrays(gl.TRIANGLES, 0, 3);

      if (partProg) {
        gl.useProgram(partProg);
        gl.uniform1f(partUni.uTime, t);
        gl.uniform2f(partUni.uScale, sc[0], sc[1]);
        gl.uniform2f(partUni.uShift, opts.shift[0], opts.shift[1]);
        gl.uniform1f(partUni.uDpr, DPR);
        gl.uniform1f(partUni.uWind, wind);
        gl.uniform4f(partUni.uCfgA, P.travel, P.lifeMin, P.lifeMax, P.alongNormal);
        gl.uniform4f(partUni.uCfgB, P.wiggle, P.sizeMin, P.sizeMax, P.sparse);
        gl.uniform3f(partUni.uColA, ...P.colA);
        gl.uniform3f(partUni.uColB, ...P.colB);
        gl.enable(gl.BLEND);
        gl.blendFunc(gl.ONE, gl.ONE);
        gl.bindVertexArray(partVao);
        gl.drawArrays(gl.POINTS, 0, count);
        gl.bindVertexArray(null);
        gl.disable(gl.BLEND);
      }
    };

    resize();

    const uv = (e: PointerEvent) => {
      const r = host.getBoundingClientRect();
      return {
        x: (e.clientX - r.left) / r.width,
        y: 1 - (e.clientY - r.top) / r.height,
      };
    };
    let last: { x: number; y: number } | null = null;
    let lastT = 0;
    const onMove = (e: PointerEvent) => {
      const p = uv(e);
      const now = performance.now();
      pointer.x = p.x;
      pointer.y = p.y;
      pointer.active = 1;
      if (last) {
        const dt = Math.max(8, now - lastT);
        const dx = p.x - last.x,
          dy = p.y - last.y;
        const sp = Math.hypot(dx, dy) / (dt / 1000);
        if (sim && sp > 0.05 && dropQueue.length < 6)
          dropQueue.push({ x: p.x, y: p.y, s: Math.min(sp * 0.14, 0.55) });
        windTarget = Math.max(-1, Math.min(1, (dx / (dt / 1000)) * 0.55));
      }
      last = p;
      lastT = now;
    };
    const onDown = (e: PointerEvent) => {
      const p = uv(e);
      if (sim) dropQueue.push({ x: p.x, y: p.y, s: 0.9 });
      pointer.x = p.x;
      pointer.y = p.y;
      pointer.active = 1.6;
    };
    const onUp = () => {
      pointer.active = 1;
    };
    const onLeave = () => {
      pointer.active = 0;
      last = null;
      windTarget = 0;
    };
    host.addEventListener("pointermove", onMove);
    host.addEventListener("pointerdown", onDown);
    host.addEventListener("pointerup", onUp);
    host.addEventListener("pointerleave", onLeave);

    let raf = 0;
    let visible = true;
    let virtual = 0;
    let prev = performance.now();
    const loop = () => {
      const now = performance.now();
      virtual += ((now - prev) / 1000) * speedRef.current;
      prev = now;
      draw(virtual);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      if (reduced || raf || !visible || document.hidden) return;
      prev = performance.now();
      raf = requestAnimationFrame(loop);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };

    const ro = new ResizeObserver(() => {
      if (reduced) {
        resize();
        draw(0.001);
      } else needsResize = true;
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else stop();
    });
    io.observe(host);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);

    if (reduced) draw(0.001);
    else start();

    return () => {
      stop();
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVis);
      host.removeEventListener("pointermove", onMove);
      host.removeEventListener("pointerdown", onDown);
      host.removeEventListener("pointerup", onUp);
      host.removeEventListener("pointerleave", onLeave);
      gl.deleteProgram(prog);
      if (simProg) gl.deleteProgram(simProg);
      if (partProg) gl.deleteProgram(partProg);
      gl.deleteTexture(sdfTex);
      simTex.forEach((t) => gl.deleteTexture(t));
      simFbo.forEach((f) => gl.deleteFramebuffer(f));
      if (partVao) gl.deleteVertexArray(partVao);
      if (partBuf) gl.deleteBuffer(partBuf);
    };
  }, [variant, markPath, size, particleAmount, prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      data-element={variant}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: ground ?? "hsl(var(--background))" }}
    >
      {ramp && (
        <svg aria-hidden="true" className="absolute h-0 w-0">
          <filter id={filterId} colorInterpolationFilters="sRGB">
            <feColorMatrix
              type="matrix"
              values="0.3 0.59 0.11 0 0  0.3 0.59 0.11 0 0  0.3 0.59 0.11 0 0  0 0 0 1 0"
            />
            <feComponentTransfer>
              <feFuncR type="table" tableValues={table(0)} />
              <feFuncG type="table" tableValues={table(1)} />
              <feFuncB type="table" tableValues={table(2)} />
            </feComponentTransfer>
          </filter>
        </svg>
      )}
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{
          opacity: clamp(opacity, 0.05, 1),
          filter: `${ramp ? `url(#${filterId}) ` : ""}hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.8)})`,
        }}
      />
    </div>
  );
}
```

---

# Crown Bar

> A proximity-spring navigation bar in four fits — a masthead command bar, a centred pill, a dithered pixel strip and a refracting glass rail.

Install: `npx @modus-ui/cli add crown-bar`

A navigation bar whose items swell, drop and settle on a damped spring as the pointer moves across them, with keyboard focus driving the same motion. The default `modern` fit is a masthead with an italic serif wordmark, the dock and actions over a serif headline; `pill` is a centred dock, `retro` a fitted strip over an ordered-dither WebGL field ramped from paper through the primary to ink, and `glass` a vertical rail over a Three.js field of refracting beads on a primary-tinted paper wash. Every colour comes from theme tokens (the shaders re-read them when the mode or palette changes), so it follows light and dark mode and the palette picker. The spring is disabled for reduced motion, coarse pointers and narrow viewports, and the shader fields pause off screen.

## Installation

### CLI

```bash
npx @modus-ui/cli add crown-bar
```

### Manual

1. Install `three` and `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/crown-bar.tsx`.
4. Paste the code.

## Usage

```tsx
import { CrownBar } from "@/components/ui/crown-bar";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <CrownBar variant="glass" />
    </div>
  );
}
```

## Props

| Prop           | Type                                       | Default    | Description                                                   |
| :------------- | :----------------------------------------- | :--------- | :------------------------------------------------------------ |
| `variant`      | `"pill" \| "modern" \| "retro" \| "glass"` | `"modern"` | Which fit to render.                                          |
| `proximity`    | `number`                                   | `122`      | Distance in pixels over which the pointer influences an item. |
| `spring`       | `number`                                   | `0.19`     | Spring stiffness of the item motion.                          |
| `damping`      | `number`                                   | `0.7`      | Velocity damping per frame.                                   |
| `widthGrowth`  | `number`                                   | `17`       | Extra width in pixels an item gains at full influence.        |
| `heightGrowth` | `number`                                   | `16`       | Extra height in pixels an item gains at full influence.       |
| `drop`         | `number`                                   | `3.5`      | How far an active item drops (or leans out on the rail).      |
| `pixelSize`    | `number`                                   | `4`        | Retro: screen pixels per field pixel.                         |
| `speed`        | `number`                                   | `1`        | Retro: field animation speed.                                 |
| `noise`        | `number`                                   | `1`        | Retro: weather noise and grain strength.                      |
| `levels`       | `number`                                   | `7`        | Retro: number of palette steps.                               |
| `scanlines`    | `number`                                   | `0.32`     | Retro: scanline overlay strength.                             |
| `particles`    | `number`                                   | `22`       | Glass: number of visible beads (4–34).                        |
| `thickness`    | `number`                                   | `0.115`    | Glass: refraction offset strength.                            |
| `dispersion`   | `number`                                   | `0.05`     | Glass: chromatic split between colour channels.               |
| `specular`     | `number`                                   | `0.85`     | Glass: highlight intensity.                                   |
| `rim`          | `number`                                   | `0.5`      | Glass: fresnel rim intensity.                                 |
| `drift`        | `number`                                   | `1`        | Glass: bead drift and spin speed.                             |

## Source

`components/ui/crown-bar.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Animated Top Dock (MIT, © 2026 Meng To).

import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export type CrownBarVariant = "pill" | "modern" | "retro" | "glass";

export interface CrownBarProps {
  variant?: CrownBarVariant;
  proximity?: number;
  spring?: number;
  damping?: number;
  widthGrowth?: number;
  heightGrowth?: number;
  drop?: number;
  /* retro field */
  pixelSize?: number;
  speed?: number;
  noise?: number;
  levels?: number;
  scanlines?: number;
  /* glass field */
  particles?: number;
  thickness?: number;
  dispersion?: number;
  specular?: number;
  rim?: number;
  drift?: number;
  className?: string;
}

type DockOptions = Required<Omit<CrownBarProps, "className">>;

type DockItem = { id: string; label: string; icon: ReactNode };

const ITEMS: readonly DockItem[] = [
  {
    id: "system",
    label: "SYSTEM",
    icon: (
      <>
        <rect x="2.25" y="2.25" width="4.5" height="4.5" rx=".8" />
        <rect x="9.25" y="2.25" width="4.5" height="4.5" rx=".8" />
        <rect x="2.25" y="9.25" width="4.5" height="4.5" rx=".8" />
        <rect x="9.25" y="9.25" width="4.5" height="4.5" rx=".8" />
      </>
    ),
  },
  {
    id: "method",
    label: "METHOD",
    icon: (
      <>
        <circle cx="3" cy="8" r="1.5" />
        <circle cx="12.5" cy="3.5" r="1.5" />
        <circle cx="12.5" cy="12.5" r="1.5" />
        <path d="M4.5 7.3 11 4.2M4.5 8.7l6.5 3.1" />
      </>
    ),
  },
  {
    id: "work",
    label: "WORK",
    icon: (
      <>
        <rect x="2" y="3" width="12" height="10" rx="1.5" />
        <path d="M2 6h12M5 4.5h.01M7 4.5h.01" />
      </>
    ),
  },
  {
    id: "access",
    label: "ACCESS",
    icon: (
      <>
        <circle cx="5.2" cy="6.2" r="2.7" />
        <path d="m7.2 8.2 5.9 5.1M10.2 10.8l1.5-1.5M12 12.4l1.4-1.4" />
      </>
    ),
  },
  {
    id: "notes",
    label: "NOTES",
    icon: (
      <>
        <path d="M4 2.25h5.4L12 4.85v8.9H4z" />
        <path d="M9.25 2.25V5h2.7M6 8h4M6 10.5h4" />
      </>
    ),
  },
];

const MODERN_ITEMS: readonly DockItem[] = [
  {
    id: "product",
    label: "Product",
    icon: (
      <>
        <path d="M8 1.9 14.1 5v6L8 14.1 1.9 11V5z" />
        <path d="M1.9 5 8 8.1 14.1 5M8 8.1v6" />
      </>
    ),
  },
  {
    id: "solutions",
    label: "Solutions",
    icon: (
      <>
        <path d="M8 1.9 14.4 5.6 8 9.3 1.6 5.6z" />
        <path d="m2.6 8 5.4 3.1L13.4 8M2.6 10.7 8 13.8l5.4-3.1" />
      </>
    ),
  },
  {
    id: "docs",
    label: "Docs",
    icon: (
      <>
        <path d="M3.4 2.4h5.4l3.8 3.8v7.4H3.4z" />
        <path d="M8.8 2.4v3.8h3.8M5.9 9h4.2M5.9 11.2h3" />
      </>
    ),
  },
  {
    id: "pricing",
    label: "Pricing",
    icon: (
      <>
        <path d="M8.6 2.2H13v4.4l-6.6 6.6a1.2 1.2 0 0 1-1.7 0L2.2 10.5a1.2 1.2 0 0 1 0-1.7z" />
        <circle cx="10.6" cy="4.6" r=".9" />
      </>
    ),
  },
  {
    id: "changelog",
    label: "Changelog",
    icon: (
      <>
        <circle cx="8" cy="8" r="5.9" />
        <path d="M8 4.6V8l2.4 1.5" />
      </>
    ),
  },
];

/* every retro glyph is drawn on a 7x7 lattice of whole units so the icons stay
   on the same pixel grid as the dithered field behind them */
const RETRO_ITEMS: readonly DockItem[] = [
  {
    id: "system",
    label: "SYSTEM",
    icon: (
      <>
        <rect x="1" y="1" width="2" height="2" />
        <rect x="4" y="1" width="2" height="2" />
        <rect x="1" y="4" width="2" height="2" />
        <rect x="4" y="4" width="2" height="2" />
      </>
    ),
  },
  {
    id: "files",
    label: "FILES",
    icon: (
      <>
        <rect x="1" y="0" width="4" height="1" />
        <rect x="1" y="1" width="1" height="5" />
        <rect x="5" y="1" width="1" height="5" />
        <rect x="1" y="6" width="5" height="1" />
        <rect x="2" y="2" width="3" height="1" />
        <rect x="2" y="4" width="3" height="1" />
      </>
    ),
  },
  {
    id: "net",
    label: "NET",
    icon: (
      <>
        <rect x="3" y="0" width="1" height="7" />
        <rect x="0" y="3" width="7" height="1" />
        <rect x="1" y="1" width="1" height="1" />
        <rect x="5" y="1" width="1" height="1" />
        <rect x="1" y="5" width="1" height="1" />
        <rect x="5" y="5" width="1" height="1" />
      </>
    ),
  },
  {
    id: "disk",
    label: "DISK",
    icon: (
      <>
        <rect x="0" y="1" width="7" height="5" />
        <rect x="2" y="0" width="3" height="2" />
        <rect x="1" y="4" width="5" height="1" />
      </>
    ),
  },
  {
    id: "help",
    label: "HELP",
    icon: (
      <>
        <rect x="2" y="0" width="3" height="1" />
        <rect x="4" y="1" width="2" height="2" />
        <rect x="3" y="3" width="2" height="1" />
        <rect x="3" y="4" width="1" height="1" />
        <rect x="3" y="6" width="1" height="1" />
      </>
    ),
  },
];

const GLASS_ITEMS: readonly DockItem[] = [
  {
    id: "overview",
    label: "Overview",
    icon: (
      <>
        <circle cx="8" cy="8" r="5.8" />
        <path d="M2.4 8c2.4-3.5 9-3.5 11.3 0" />
      </>
    ),
  },
  {
    id: "studio",
    label: "Studio",
    icon: (
      <>
        <rect x="2.2" y="2.2" width="11.6" height="11.6" rx="3.6" />
        <circle cx="8" cy="8" r="2.5" />
      </>
    ),
  },
  {
    id: "library",
    label: "Library",
    icon: (
      <>
        <rect x="2.1" y="2.6" width="3" height="10.8" rx="1" />
        <rect x="6.4" y="2.6" width="3" height="10.8" rx="1" />
        <path d="m10.9 3.7 2.9 1-2.4 8.6-2.2-.8" />
      </>
    ),
  },
  {
    id: "motion",
    label: "Motion",
    icon: (
      <>
        <path d="M1.8 10.6c2.6 0 3-5.2 6.2-5.2s3.6 5.2 6.2 5.2" />
        <circle cx="8" cy="5.4" r=".9" />
      </>
    ),
  },
  {
    id: "labs",
    label: "Labs",
    icon: (
      <>
        <path d="M6.4 2.2v4L3 12.1a1.3 1.3 0 0 0 1.1 2h7.8a1.3 1.3 0 0 0 1.1-2L9.6 6.2v-4" />
        <path d="M5.6 2.2h4.8M4.9 9.6h6.2" />
      </>
    ),
  },
];

const VARIANT_ITEMS: Record<CrownBarVariant, readonly DockItem[]> = {
  pill: ITEMS,
  modern: MODERN_ITEMS,
  retro: RETRO_ITEMS,
  glass: GLASS_ITEMS,
};

const BRAND_MARK = (
  <svg viewBox="0 0 24 24" aria-hidden="true">
    <rect width="24" height="24" rx="4.5" fill="currentColor" />
    <path d="M6 6h8.6L18 9.35v8.15H9.15L6 14.35V6Z" fill="hsl(var(--background))" />
    <path d="M9 9h5.15L15 9.85V15H9.85L9 14.15V9Z" fill="currentColor" />
    <path d="M12 9v6M9 12h6" stroke="hsl(var(--background))" strokeWidth=".7" />
  </svg>
);

/* ── Proximity spring controller ─────────────────────────────────────────── */

type ControllerOptions = DockOptions & {
  axis: "x" | "y";
  distribute: boolean;
  lockTrack: boolean;
  reduced: boolean;
};

type DockItemState = {
  element: HTMLElement;
  baseWidth: number;
  baseHeight: number;
  value: number;
  velocity: number;
  target: number;
};

const clamp = (value: number, min: number, max: number) => Math.max(min, Math.min(max, value));

function createTopDockController(root: HTMLElement, getOptions: () => ControllerOptions) {
  const precisionQuery = window.matchMedia("(hover:hover) and (pointer:fine)");
  const items: DockItemState[] = Array.from(
    root.querySelectorAll<HTMLElement>("[data-dock-item]"),
  ).map((element) => ({
    element,
    baseWidth: 0,
    baseHeight: 0,
    value: 0,
    velocity: 0,
    target: 0,
  }));

  let enabled = false;
  let pointerActive = false;
  let dirty = false;
  let frame = 0;

  const canAnimate = () =>
    !getOptions().reduced &&
    root.clientWidth > 0 &&
    window.innerWidth > 600 &&
    precisionQuery.matches;

  /* the only place item geometry is written, so the three fits stay one
     behaviour with three ways of spending the same spring value */
  const applyLayout = () => {
    const options = getOptions();
    if (options.distribute && options.axis !== "y") {
      const weights = items.map(
        (state) => state.baseWidth + options.widthGrowth * clamp(state.value, 0, 1.08),
      );
      const total = weights.reduce((sum, weight) => sum + weight, 0);
      const natural = items.reduce((sum, state) => sum + state.baseWidth, 0);
      const track = root.clientWidth >= natural ? root.clientWidth : 0;
      items.forEach((state, index) => {
        state.element.style.width = track
          ? `${((track * weights[index]) / total).toFixed(2)}px`
          : "";
        state.element.style.height = "";
        state.element.style.transform = "";
      });
      return;
    }
    for (const state of items) {
      const value = clamp(state.value, 0, 1.08);
      if (options.axis === "y") {
        state.element.style.width = "";
        state.element.style.height = `${(state.baseHeight + options.heightGrowth * value).toFixed(2)}px`;
        state.element.style.transform = `translateX(${(value * options.drop).toFixed(2)}px)`;
        continue;
      }
      const isLogo = state.element.classList.contains("animated-top-dock__logo");
      const extraWidth = isLogo
        ? options.widthGrowth * (14 / 17)
        : Math.min(options.widthGrowth, state.baseWidth * 0.24);
      const extraHeight = isLogo ? options.heightGrowth * (14 / 16) : options.heightGrowth;
      state.element.style.width = `${(state.baseWidth + extraWidth * value).toFixed(2)}px`;
      state.element.style.height = `${(state.baseHeight + extraHeight * value).toFixed(2)}px`;
      state.element.style.transform = `translateY(${(value * options.drop).toFixed(2)}px)`;
    }
  };

  const measure = () => {
    enabled = canAnimate();
    /* released first, so the rest width is measured against the track's own
       content rather than against the width the last measurement pinned */
    if (getOptions().lockTrack) root.style.width = "";
    for (const state of items) {
      state.element.style.width = "";
      state.element.style.height = "";
      state.element.style.transform = "";
      state.element.dataset.dockNear = "false";
    }
    for (const state of items) {
      const rect = state.element.getBoundingClientRect();
      state.baseWidth = rect.width;
      state.baseHeight = rect.height;
      state.value = 0;
      state.velocity = 0;
      state.target = 0;
    }
    pointerActive = false;
    dirty = false;
    if (getOptions().distribute) applyLayout();
    if (getOptions().lockTrack)
      root.style.width = `${root.getBoundingClientRect().width.toFixed(2)}px`;
    root.dataset.dockState = enabled ? "idle" : "static";
    root.dataset.dockMax = "0.00";
  };

  const setTargets = (clientX: number, clientY: number) => {
    if (!enabled) return;
    const options = getOptions();
    const vertical = options.axis === "y";
    const pointer = vertical ? clientY : clientX;
    const rects = items.map((state) => state.element.getBoundingClientRect());
    for (let index = 0; index < items.length; index += 1) {
      const rect = rects[index];
      const center = vertical ? rect.top + rect.height * 0.5 : rect.left + rect.width * 0.5;
      const proximity = clamp(
        1 - Math.abs(pointer - center) / Math.max(1, options.proximity),
        0,
        1,
      );
      const influence = proximity * proximity * (3 - 2 * proximity);
      items[index].target = influence;
      items[index].element.dataset.dockNear = influence > 0.08 ? "true" : "false";
    }
    pointerActive = true;
    dirty = true;
    root.dataset.dockState = "active";
  };

  const focusItem = (item: HTMLElement) => {
    if (!enabled) return;
    const index = items.findIndex((state) => state.element === item);
    if (index < 0) return;
    items.forEach((state, itemIndex) => {
      state.target = itemIndex === index ? 1 : Math.abs(itemIndex - index) === 1 ? 0.24 : 0;
      state.element.dataset.dockNear = state.target > 0.08 ? "true" : "false";
    });
    pointerActive = false;
    dirty = true;
    root.dataset.dockState = "focus";
  };

  const reset = () => {
    pointerActive = false;
    dirty = true;
    items.forEach((state) => {
      state.target = 0;
      state.element.dataset.dockNear = "false";
    });
  };

  const draw = () => {
    if (enabled && dirty) {
      const options = getOptions();
      let moving = false;
      let maxValue = 0;
      for (const state of items) {
        state.velocity += (state.target - state.value) * options.spring;
        state.velocity *= options.damping;
        state.value += state.velocity;
        if (Math.abs(state.target - state.value) < 0.001 && Math.abs(state.velocity) < 0.001) {
          state.value = state.target;
          state.velocity = 0;
        } else {
          moving = true;
        }
        maxValue = Math.max(maxValue, clamp(state.value, 0, 1.08));
      }
      applyLayout();
      root.dataset.dockMax = maxValue.toFixed(2);
      if (!moving) {
        dirty = false;
        if (items.every((state) => state.target === 0)) root.dataset.dockState = "idle";
      }
    }
    frame = requestAnimationFrame(draw);
  };

  const onPointerMove = (event: PointerEvent) => setTargets(event.clientX, event.clientY);
  const onWindowPointerMove = (event: PointerEvent) => {
    if (!pointerActive) return;
    const rootRect = root.getBoundingClientRect();
    const itemRects = items.map((state) => state.element.getBoundingClientRect());
    const bottom = Math.max(rootRect.bottom, ...itemRects.map((rect) => rect.bottom));
    const outside =
      event.clientX < rootRect.left ||
      event.clientX > rootRect.right ||
      event.clientY < rootRect.top ||
      event.clientY > bottom;
    if (outside) reset();
  };
  const onFocusIn = (event: FocusEvent) => {
    const item = (event.target as HTMLElement | null)?.closest<HTMLElement>("[data-dock-item]");
    if (item) focusItem(item);
  };
  const onFocusOut = () =>
    requestAnimationFrame(() => {
      if (!root.contains(document.activeElement)) reset();
    });
  const onKeyDown = (event: KeyboardEvent) => {
    const item = (event.target as HTMLElement | null)?.closest<HTMLElement>("[data-dock-item]");
    if (item && (event.key === "Enter" || event.key === " ")) {
      event.preventDefault();
      item.click();
    }
  };
  const onClick = () => reset();

  /* measured after the label font is available, so auto-width items do not
     lock in a box their own text then overflows */
  let released = false;
  const remeasure = () => {
    if (!released) measure();
  };
  document.fonts?.ready.then(remeasure);

  const resizeObserver = new ResizeObserver(measure);
  resizeObserver.observe(
    root.closest<HTMLElement>("[data-dock-frame]") ?? root.parentElement ?? root,
  );
  root.addEventListener("pointermove", onPointerMove);
  root.addEventListener("pointerleave", reset);
  root.addEventListener("focusin", onFocusIn);
  root.addEventListener("focusout", onFocusOut);
  root.addEventListener("keydown", onKeyDown);
  root.addEventListener("click", onClick);
  window.addEventListener("pointermove", onWindowPointerMove, { passive: true });
  precisionQuery.addEventListener("change", measure);
  measure();
  frame = requestAnimationFrame(draw);

  return () => {
    released = true;
    root.style.width = "";
    cancelAnimationFrame(frame);
    resizeObserver.disconnect();
    root.removeEventListener("pointermove", onPointerMove);
    root.removeEventListener("pointerleave", reset);
    root.removeEventListener("focusin", onFocusIn);
    root.removeEventListener("focusout", onFocusOut);
    root.removeEventListener("keydown", onKeyDown);
    root.removeEventListener("click", onClick);
    window.removeEventListener("pointermove", onWindowPointerMove);
    precisionQuery.removeEventListener("change", measure);
  };
}

/* ── Retro pixel field (raw WebGL) ───────────────────────────────────────── */

type ShaderField = {
  resize: (width: number, height: number) => void;
  render: (now: number) => void;
  setPointer?: (x: number, y: number) => void;
  dispose: () => void;
};

const RETRO_VERTEX = "attribute vec2 aPos;\nvoid main(){ gl_Position = vec4(aPos, 0.0, 1.0); }";

/* the scene is a single luminance field, dithered with an ordered 8x8 Bayer
   threshold, snapped to uLevels steps, then mapped through an eight-stop dusk ramp */
const RETRO_FRAGMENT = `precision highp float;
uniform vec2 uRes;
uniform float uTime;
uniform float uNoise;
uniform float uLevels;
uniform vec3 uPaper;
uniform vec3 uAccent;
uniform vec3 uInk;

float hash(vec2 p){ p = fract(p * vec2(127.1, 311.7)); p += dot(p, p + 34.23); return fract(p.x * p.y); }

float vnoise(vec2 p){
  vec2 i = floor(p), f = fract(p);
  f = f * f * (3.0 - 2.0 * f);
  float a = hash(i), b = hash(i + vec2(1.0, 0.0)), c = hash(i + vec2(0.0, 1.0)), d = hash(i + vec2(1.0, 1.0));
  return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
}

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

float bayer2(vec2 a){ a = floor(a); return fract(a.x * 0.5 + a.y * a.y * 0.75); }
float bayer4(vec2 a){ return bayer2(a * 0.5) * 0.25 + bayer2(a); }
float bayer8(vec2 a){ return bayer4(a * 0.5) * 0.25 + bayer2(a); }

vec3 stop(float index){
  float t = index / 7.0;
  return t < 0.6 ? mix(uPaper, uAccent, t / 0.6) : mix(uAccent, uInk, (t - 0.6) / 0.4 * 0.7);
}

void main(){
  vec2 uv = gl_FragCoord.xy / uRes;
  float t = uTime;

  vec2 cloud = vec2(uv.x * 3.4, uv.y * 2.1);
  float weather = fbm(cloud + vec2(t * 0.055, t * -0.021));
  weather = mix(weather, fbm(cloud * 1.9 + vec2(-t * 0.032, t * 0.044)), 0.42);

  float sky = smoothstep(0.98, 0.20, uv.y) * 0.36;
  float heat = smoothstep(0.60, 0.16, uv.y) * 0.32;
  float ground = smoothstep(0.26, 0.08, uv.y);
  float sun = smoothstep(0.38, 0.0, length((uv - vec2(0.5, 0.29)) * vec2(0.70, 1.5))) * 0.20;
  float field = 0.11 + sky + heat + sun - ground * 0.80 + (weather - 0.5) * 0.82 * uNoise;

  float grain = hash(floor(gl_FragCoord.xy) + floor(t * 12.0)) - 0.5;
  field += grain * 0.055 * uNoise;
  field *= 1.0 - 0.34 * smoothstep(0.45, 1.05, length((uv - vec2(0.5, 0.46)) * vec2(1.06, 1.0)));

  float levels = max(uLevels, 2.0);
  float dither = bayer8(gl_FragCoord.xy) - 0.5;
  float quantised = clamp(field + dither / levels, 0.0, 0.9999);
  gl_FragColor = vec4(stop(floor(quantised * levels) * (7.0 / (levels - 1.0))), 1.0);
}`;

type Rgb = [number, number, number];
type Palette = { paper: Rgb; ink: Rgb; accent: Rgb };

/* theme tokens are bare HSL channels; resolve them to linear 0-1 RGB for the shaders */
function readToken(name: string): Rgb {
  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  const [h = 0, sat = 0, l = 50] = raw.split(/[\s,/]+/).map((part) => parseFloat(part) || 0);
  const s = sat / 100;
  const li = l / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = s * Math.min(li, 1 - li);
  const f = (n: number) => li - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}

function readPalette(): Palette {
  return {
    paper: readToken("--background"),
    ink: readToken("--foreground"),
    accent: readToken("--primary"),
  };
}

const INERT: ShaderField = { resize: () => {}, render: () => {}, dispose: () => {} };

function compileShader(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) return null;
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    gl.deleteShader(shader);
    return null;
  }
  return shader;
}

function createRetroPixelField(
  canvas: HTMLCanvasElement,
  getOptions: () => DockOptions,
  getPalette: () => Palette,
): ShaderField {
  const gl = canvas.getContext("webgl", {
    antialias: false,
    alpha: false,
    depth: false,
    preserveDrawingBuffer: false,
  });
  if (!gl) return INERT;

  const program = gl.createProgram();
  const vertex = compileShader(gl, gl.VERTEX_SHADER, RETRO_VERTEX);
  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, RETRO_FRAGMENT);
  if (!program || !vertex || !fragment) return INERT;
  gl.attachShader(program, vertex);
  gl.attachShader(program, fragment);
  gl.linkProgram(program);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) return INERT;
  gl.useProgram(program);

  const buffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const position = gl.getAttribLocation(program, "aPos");

  const uRes = gl.getUniformLocation(program, "uRes");
  const uTime = gl.getUniformLocation(program, "uTime");
  const uNoise = gl.getUniformLocation(program, "uNoise");
  const uLevels = gl.getUniformLocation(program, "uLevels");
  const uPaper = gl.getUniformLocation(program, "uPaper");
  const uAccent = gl.getUniformLocation(program, "uAccent");
  const uInk = gl.getUniformLocation(program, "uInk");

  let width = 1;
  let height = 1;
  let clock = 0;
  let lastAt = performance.now();

  const resize = (cssWidth: number, cssHeight: number) => {
    const { pixelSize } = getOptions();
    /* the drawing buffer is the low-resolution artwork; CSS blows it up with
       nearest-neighbour sampling, so every pixel stays square and hard-edged */
    width = Math.max(2, Math.round(cssWidth / Math.max(1, pixelSize)));
    height = Math.max(2, Math.round(cssHeight / Math.max(1, pixelSize)));
    if (canvas.width === width && canvas.height === height) return;
    canvas.width = width;
    canvas.height = height;
    gl.viewport(0, 0, width, height);
  };

  const render = (now: number) => {
    const options = getOptions();
    clock += Math.min(96, now - lastAt) * 0.001 * options.speed;
    lastAt = now;
    gl.useProgram(program);
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.enableVertexAttribArray(position);
    gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
    gl.uniform2f(uRes, width, height);
    gl.uniform1f(uTime, clock);
    gl.uniform1f(uNoise, options.noise);
    gl.uniform1f(uLevels, options.levels);
    const palette = getPalette();
    gl.uniform3fv(uPaper, palette.paper);
    gl.uniform3fv(uAccent, palette.accent);
    gl.uniform3fv(uInk, palette.ink);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
  };

  const dispose = () => {
    gl.deleteBuffer(buffer);
    gl.deleteProgram(program);
    gl.deleteShader(vertex);
    gl.deleteShader(fragment);
  };

  return { resize, render, dispose };
}

/* ── Glass bead field (Three.js) ─────────────────────────────────────────── */

const MAX_BEADS = 34;

const QUAD_VERTEX = "void main(){ gl_Position = vec4(position.xy, 0.0, 1.0); }";

const BACKDROP_FRAGMENT = `precision highp float;
uniform vec2 uRes;
uniform float uTime;
uniform vec2 uPointer;
uniform vec3 uPaper;
uniform vec3 uAccent;
uniform vec3 uInk;


void main(){
  vec2 uv = gl_FragCoord.xy / uRes;
  float t = uTime * 0.17;
  vec3 col = uPaper;
  vec3 deep = mix(uAccent, uInk, 0.35);
  col = mix(col, uAccent, smoothstep(0.86, 0.0, length((uv - vec2(0.23 + 0.055 * sin(t * 0.9), 0.76 + 0.045 * cos(t * 0.7))) * vec2(uRes.x / max(uRes.y, 1.0), 1.0))) * 0.55);
  col = mix(col, deep, smoothstep(0.80, 0.0, length((uv - vec2(0.82 + 0.05 * cos(t * 0.8), 0.34 + 0.055 * sin(t * 1.1))) * vec2(uRes.x / max(uRes.y, 1.0), 1.0))) * 0.5);
  col = mix(col, uInk, smoothstep(0.5, 0.0, length((uv - vec2(0.5 + uPointer.x * 0.20, 0.56 + uPointer.y * 0.16)) * vec2(uRes.x / max(uRes.y, 1.0), 1.0))) * 0.12);
  float stripes = step(0.5, fract((gl_FragCoord.x + gl_FragCoord.y) / 14.0));
  col = mix(col, uInk, stripes * 0.025);
  float vignette = smoothstep(1.34, 0.30, length((uv - 0.5) * vec2(1.05, 1.0)));
  col = mix(col * 0.9, col, vignette);
  gl_FragColor = vec4(col, 1.0);
}`;

const GLASS_VERTEX = `varying vec3 vNormalView;
varying vec3 vViewPos;
varying vec4 vScreen;

void main(){
  vec4 mvPosition = modelViewMatrix * vec4(position, 1.0);
  vNormalView = normalize(normalMatrix * normal);
  vViewPos = mvPosition.xyz;
  vScreen = projectionMatrix * mvPosition;
  gl_Position = vScreen;
}`;

/* screen-space refraction with a slightly different index per channel, so the
   bead edges split into colour the way real glass does */
const GLASS_FRAGMENT = `precision highp float;
uniform sampler2D uBackdrop;
uniform float uThickness;
uniform float uDispersion;
uniform float uSpecular;
uniform float uRim;
uniform vec3 uTint;
uniform vec3 uLight;
varying vec3 vNormalView;
varying vec3 vViewPos;
varying vec4 vScreen;

void main(){
  vec2 screenUV = (vScreen.xy / vScreen.w) * 0.5 + 0.5;
  vec3 N = normalize(vNormalView);
  vec3 V = normalize(-vViewPos);
  vec3 I = -V;
  float fresnel = pow(1.0 - clamp(dot(N, V), 0.0, 1.0), 3.4);

  vec2 offsetR = refract(I, N, 1.0 / (1.44 - uDispersion)).xy * uThickness;
  vec2 offsetG = refract(I, N, 1.0 / 1.44).xy * uThickness;
  vec2 offsetB = refract(I, N, 1.0 / (1.44 + uDispersion)).xy * uThickness;

  vec3 col;
  col.r = texture2D(uBackdrop, clamp(screenUV + offsetR, 0.002, 0.998)).r;
  col.g = texture2D(uBackdrop, clamp(screenUV + offsetG, 0.002, 0.998)).g;
  col.b = texture2D(uBackdrop, clamp(screenUV + offsetB, 0.002, 0.998)).b;
  col *= uTint;

  vec3 L = normalize(uLight);
  vec3 H = normalize(L + V);
  float ndoth = max(dot(N, H), 0.0);
  col += pow(ndoth, 150.0) * uSpecular;
  col += pow(ndoth, 16.0) * uSpecular * 0.11;
  vec3 H2 = normalize(normalize(vec3(0.55, -0.7, 0.45)) + V);
  col += pow(max(dot(N, H2), 0.0), 44.0) * uSpecular * 0.22;
  col += fresnel * uRim * vec3(0.86, 0.90, 1.0);

  float haze = smoothstep(7.4, 11.4, -vViewPos.z);
  col = mix(col, texture2D(uBackdrop, screenUV).rgb, haze * 0.7);
  gl_FragColor = vec4(col, 1.0);
}`;

type Bead = {
  mesh: THREE.Mesh;
  material: THREE.ShaderMaterial;
  origin: THREE.Vector3;
  bob: number;
  phase: number;
  spin: THREE.Vector3;
  radius: number;
};

/* one deterministic sequence so the arrangement is identical on every load */
function seeded(seed: number) {
  let state = seed;
  return () => {
    state = (state * 1664525 + 1013904223) % 4294967296;
    return state / 4294967296;
  };
}

function createGlassParticleField(
  canvas: HTMLCanvasElement,
  getOptions: () => DockOptions,
  getPalette: () => Palette,
): ShaderField {
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));

  const backdropScene = new THREE.Scene();
  const backdropCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
  const backdropUniforms = {
    uRes: { value: new THREE.Vector2(1, 1) },
    uTime: { value: 0 },
    uPointer: { value: new THREE.Vector2() },
    uPaper: { value: new THREE.Vector3() },
    uAccent: { value: new THREE.Vector3() },
    uInk: { value: new THREE.Vector3() },
  };
  const backdropMaterial = new THREE.ShaderMaterial({
    uniforms: backdropUniforms,
    vertexShader: QUAD_VERTEX,
    fragmentShader: BACKDROP_FRAGMENT,
    depthTest: false,
    depthWrite: false,
  });
  const backdropGeometry = new THREE.PlaneGeometry(2, 2);
  backdropScene.add(new THREE.Mesh(backdropGeometry, backdropMaterial));

  const target = new THREE.WebGLRenderTarget(2, 2, {
    minFilter: THREE.LinearFilter,
    magFilter: THREE.LinearFilter,
    format: THREE.RGBAFormat,
  });

  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(42, 1, 0.1, 100);
  camera.position.set(0, 0, 7.4);
  const group = new THREE.Group();
  scene.add(group);

  const geometries = [
    new THREE.SphereGeometry(1, 44, 30),
    new THREE.IcosahedronGeometry(1, 1),
    new THREE.TorusGeometry(0.78, 0.3, 22, 56),
  ];
  const tints = [
    new THREE.Color(1.04, 1.0, 1.02),
    new THREE.Color(0.97, 1.0, 1.06),
    new THREE.Color(1.05, 0.99, 0.97),
  ];

  const random = seeded(20260826);
  const beads: Bead[] = [];
  for (let index = 0; index < MAX_BEADS; index += 1) {
    const hero = index < 8;
    const radius = hero ? 0.4 + random() * 0.34 : 0.09 + random() * 0.18;
    const geometry = geometries[hero ? (index === 3 ? 1 : index === 6 ? 2 : 0) : 0];
    const material = new THREE.ShaderMaterial({
      uniforms: {
        uBackdrop: { value: target.texture },
        uThickness: { value: 0.1 },
        uDispersion: { value: 0.05 },
        uSpecular: { value: 0.85 },
        uRim: { value: 0.5 },
        uTint: { value: tints[index % tints.length] },
        uLight: { value: new THREE.Vector3(-0.45, 0.86, 0.62) },
      },
      vertexShader: GLASS_VERTEX,
      fragmentShader: GLASS_FRAGMENT,
    });
    const mesh = new THREE.Mesh(geometry, material);
    mesh.scale.setScalar(radius);
    /* hero beads are rejection-sampled so two large spheres never intersect */
    const origin = new THREE.Vector3();
    for (let attempt = 0; attempt < 48; attempt += 1) {
      origin.set(
        (random() - 0.5) * 8.4,
        (random() - 0.5) * 5.0 - 0.25,
        hero ? -1.4 + random() * 2.6 : -3.6 + random() * 2.4,
      );
      if (!hero) break;
      const clear = beads.every((placed) => {
        const dx = placed.origin.x - origin.x;
        const dy = placed.origin.y - origin.y;
        return Math.hypot(dx, dy) > (placed.radius + radius) * 1.25 + 0.3;
      });
      if (clear) break;
    }
    mesh.position.copy(origin);
    mesh.rotation.set(random() * 6.28, random() * 6.28, random() * 6.28);
    group.add(mesh);
    beads.push({
      mesh,
      material,
      origin,
      radius,
      bob: 0.14 + random() * 0.34,
      phase: random() * 6.28,
      spin: new THREE.Vector3(
        (random() - 0.5) * 0.28,
        (random() - 0.5) * 0.34,
        (random() - 0.5) * 0.2,
      ),
    });
  }

  const pointer = new THREE.Vector2();
  const pointerTarget = new THREE.Vector2();
  let width = 1;
  let height = 1;
  let clock = 0;
  let lastAt = performance.now();

  const resize = (cssWidth: number, cssHeight: number) => {
    const nextWidth = Math.max(1, Math.round(cssWidth));
    const nextHeight = Math.max(1, Math.round(cssHeight));
    if (nextWidth === width && nextHeight === height) return;
    width = nextWidth;
    height = nextHeight;
    const ratio = Math.min(window.devicePixelRatio, 2);
    renderer.setSize(width, height, false);
    target.setSize(Math.round(width * ratio), Math.round(height * ratio));
    backdropUniforms.uRes.value.set(width * ratio, height * ratio);
    camera.aspect = width / height;
    camera.fov = camera.aspect > 1 ? 42 : 42 / Math.max(0.62, camera.aspect);
    camera.updateProjectionMatrix();
    for (const bead of beads) bead.material.uniforms.uBackdrop.value = target.texture;
  };

  const setPointer = (x: number, y: number) => pointerTarget.set(x, y);

  const render = (now: number) => {
    const options = getOptions();
    clock += Math.min(96, now - lastAt) * 0.001;
    lastAt = now;
    pointer.lerp(pointerTarget, 0.045);

    const visible = Math.max(4, Math.min(MAX_BEADS, Math.round(options.particles)));
    for (let index = 0; index < beads.length; index += 1) {
      const bead = beads[index];
      bead.mesh.visible = index < visible;
      if (!bead.mesh.visible) continue;
      const uniforms = bead.material.uniforms;
      uniforms.uThickness.value = options.thickness * (0.55 + bead.radius * 0.9);
      uniforms.uDispersion.value = options.dispersion;
      uniforms.uSpecular.value = options.specular;
      uniforms.uRim.value = options.rim;
      const t = clock * options.drift;
      bead.mesh.position.set(
        bead.origin.x + Math.sin(t * 0.21 + bead.phase) * bead.bob * 0.9,
        bead.origin.y + Math.cos(t * 0.27 + bead.phase * 1.3) * bead.bob,
        bead.origin.z + Math.sin(t * 0.17 + bead.phase * 0.7) * bead.bob * 0.5,
      );
      bead.mesh.rotation.x += bead.spin.x * 0.0075 * options.drift;
      bead.mesh.rotation.y += bead.spin.y * 0.0075 * options.drift;
      bead.mesh.rotation.z += bead.spin.z * 0.0075 * options.drift;
    }

    group.rotation.y = pointer.x * 0.14;
    group.rotation.x = -pointer.y * 0.1;
    group.position.x = pointer.x * 0.28;
    group.position.y = pointer.y * 0.2;

    const palette = getPalette();
    backdropUniforms.uPaper.value.fromArray(palette.paper);
    backdropUniforms.uAccent.value.fromArray(palette.accent);
    backdropUniforms.uInk.value.fromArray(palette.ink);
    backdropUniforms.uTime.value = clock;
    backdropUniforms.uPointer.value.set(pointer.x, pointer.y);

    renderer.setRenderTarget(target);
    renderer.render(backdropScene, backdropCamera);
    renderer.setRenderTarget(null);
    renderer.render(backdropScene, backdropCamera);
    renderer.autoClear = false;
    renderer.render(scene, camera);
    renderer.autoClear = true;
  };

  const dispose = () => {
    for (const bead of beads) bead.material.dispose();
    for (const geometry of geometries) geometry.dispose();
    backdropGeometry.dispose();
    backdropMaterial.dispose();
    target.dispose();
    renderer.dispose();
  };

  return { resize, render, setPointer, dispose };
}

/* shared host lifecycle: measure from the shell, pause off-screen and on a
   hidden tab, and hand the renderer a css-pixel box */
function useShaderField(
  active: boolean,
  reduced: boolean,
  create: (canvas: HTMLCanvasElement) => ShaderField,
) {
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const createRef = useRef(create);
  createRef.current = create;

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!active || !host || !canvas) return undefined;
    const field = createRef.current(canvas);
    let frame = 0;
    let visible = true;
    let bounds = host.getBoundingClientRect();
    const resize = () => {
      bounds = host.getBoundingClientRect();
      field.resize(bounds.width, bounds.height);
      if (reduced) field.render(performance.now());
    };
    const tick = (now: number) => {
      field.resize(bounds.width, bounds.height);
      field.render(now);
      frame = visible && !document.hidden && !reduced ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!frame && visible && !document.hidden) frame = requestAnimationFrame(tick);
    };
    const onPointerMove = (event: PointerEvent) => {
      field.setPointer?.(
        ((event.clientX - bounds.left) / Math.max(1, bounds.width)) * 2 - 1,
        -(((event.clientY - bounds.top) / Math.max(1, bounds.height)) * 2 - 1),
      );
    };
    const onVisibility = () => {
      if (!reduced) start();
    };
    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible && !reduced) start();
      if (!visible && frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    resizeObserver.observe(host);
    intersection.observe(host);
    host.addEventListener("pointermove", onPointerMove, { passive: true });
    document.addEventListener("visibilitychange", onVisibility);
    resize();
    frame = requestAnimationFrame(tick);
    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      host.removeEventListener("pointermove", onPointerMove);
      document.removeEventListener("visibilitychange", onVisibility);
      field.dispose();
    };
  }, [active, reduced]);

  return { hostRef, canvasRef };
}

export function CrownBar({
  variant = "modern",
  proximity = 122,
  spring = 0.19,
  damping = 0.7,
  widthGrowth = 17,
  heightGrowth = 16,
  drop = 3.5,
  pixelSize = 4,
  speed = 1,
  noise = 1,
  levels = 7,
  scanlines = 0.32,
  particles = 22,
  thickness = 0.115,
  dispersion = 0.05,
  specular = 0.85,
  rim = 0.5,
  drift = 1,
  className,
}: CrownBarProps) {
  const prefersReducedMotion = useReducedMotion();
  const reduced = Boolean(prefersReducedMotion);
  const options: DockOptions = {
    variant,
    proximity,
    spring,
    damping,
    widthGrowth,
    heightGrowth,
    drop,
    pixelSize,
    speed,
    noise,
    levels,
    scanlines,
    particles,
    thickness,
    dispersion,
    specular,
    rim,
    drift,
  };
  const optionsRef = useRef(options);
  optionsRef.current = options;
  const reducedRef = useRef(reduced);
  reducedRef.current = reduced;

  const items = VARIANT_ITEMS[variant] ?? ITEMS;
  const [active, setActive] = useState(items[0].id);
  useEffect(() => setActive(items[0].id), [items]);

  /* one spring, three fits: the command bar pins its track, the terminal
     renormalises its cells across the strip, and the glass rail runs the
     proximity field down the y axis */
  const rootRef = useRef<HTMLElement>(null);
  useEffect(() => {
    const root = rootRef.current;
    if (!root) return undefined;
    return createTopDockController(root, () => ({
      ...optionsRef.current,
      axis: variant === "glass" ? "y" : "x",
      distribute: variant === "retro",
      lockTrack: variant === "modern",
      reduced: reducedRef.current,
    }));
  }, [variant, reduced]);

  /* shader colours follow the theme tokens and re-resolve when <html> switches mode or palette */
  const paletteRef = useRef<Palette | null>(null);
  useEffect(() => {
    paletteRef.current = readPalette();
    const observer = new MutationObserver(() => {
      paletteRef.current = readPalette();
    });
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "style"],
    });
    return () => observer.disconnect();
  }, []);
  const getPalette = () => (paletteRef.current ??= readPalette());

  const retro = useShaderField(variant === "retro", reduced, (canvas) =>
    createRetroPixelField(canvas, () => optionsRef.current, getPalette),
  );
  const glass = useShaderField(variant === "glass", reduced, (canvas) =>
    createGlassParticleField(canvas, () => optionsRef.current, getPalette),
  );

  const dockItems = (itemClass: string, iconClass: string, viewBox: string) =>
    items.map((item) => (
      <button
        key={item.id}
        className={itemClass}
        data-dock-item
        type="button"
        aria-pressed={active === item.id}
        onClick={() => setActive(item.id)}
      >
        <span className={iconClass} aria-hidden="true">
          <svg viewBox={viewBox}>{item.icon}</svg>
        </span>
        <span>{item.label}</span>
      </button>
    ));

  const styles = <style dangerouslySetInnerHTML={{ __html: CROWN_BAR_CSS }} />;

  if (variant === "modern") {
    return (
      <div className={cn("animated-top-dock-component atd-modern", className)}>
        {styles}
        <div className="atd-modern__aurora" aria-hidden="true" />
        <header className="atd-modern__bar">
          <a
            className="atd-modern__brand"
            href="#crown-bar"
            onClick={(event) => event.preventDefault()}
          >
            <span className="atd-modern__mark" aria-hidden="true">
              {BRAND_MARK}
            </span>
            <span className="atd-modern__word">Modus</span>
          </a>
          <nav
            ref={rootRef}
            className="atd-modern__dock"
            aria-label="Primary"
            data-dock-state="idle"
            data-dock-max="0.00"
          >
            {dockItems("atd-modern__item", "atd-modern__icon", "0 0 16 16")}
          </nav>
          <div className="atd-modern__actions">
            <button className="atd-modern__ghost" type="button">
              Sign in
            </button>
            <button className="atd-modern__cta" type="button">
              <span>Read the issue</span>
              <svg viewBox="0 0 16 16" aria-hidden="true">
                <path d="M3.2 8h9.1M8.6 4.3 12.4 8l-3.8 3.7" />
              </svg>
            </button>
          </div>
        </header>
        <div className="atd-modern__stage" aria-hidden="true">
          <p className="atd-modern__eyebrow">Issue 04 · Navigation</p>
          <p className="atd-modern__headline">Set in the house style</p>
        </div>
        <p className="animated-top-dock-component__caption">
          LOGO LEFT · DOCK CENTRE · ACTION RIGHT
        </p>
      </div>
    );
  }

  if (variant === "retro") {
    return (
      <div
        ref={retro.hostRef}
        className={cn("animated-top-dock-component atd-retro", className)}
        style={{ "--atd-retro-scan": scanlines } as CSSProperties}
      >
        {styles}
        <canvas ref={retro.canvasRef} className="atd-retro__field" aria-hidden="true" />
        <div className="atd-retro__vignette" aria-hidden="true" />
        <header className="atd-retro__bar">
          <div className="atd-retro__brand">
            <span className="atd-retro__badge" aria-hidden="true">
              <svg viewBox="0 0 7 7">
                <rect x="0" y="2" width="7" height="3" />
                <rect x="2" y="0" width="3" height="7" />
              </svg>
            </span>
            MODUS//OS
          </div>
          <nav
            ref={rootRef}
            className="atd-retro__dock"
            aria-label="Primary"
            data-dock-state="idle"
            data-dock-max="0.00"
          >
            {dockItems("atd-retro__item", "atd-retro__icon", "0 0 7 7")}
          </nav>
          <button className="atd-retro__cta" type="button">
            <span aria-hidden="true">▶</span>
            RUN
          </button>
        </header>
        <p className="atd-retro__readout">
          <span>MEM 640K</span>
          <span>DITHER 8×8</span>
          <span>PAL 8</span>
        </p>
        <p className="animated-top-dock-component__caption">FITTED STRIP · ORDERED DITHER</p>
      </div>
    );
  }

  if (variant === "glass") {
    return (
      <div
        ref={glass.hostRef}
        className={cn("animated-top-dock-component atd-glass", className)}
        data-dock-frame
      >
        {styles}
        <canvas ref={glass.canvasRef} className="atd-glass__field" aria-hidden="true" />
        <header className="atd-glass__rail">
          <a
            className="atd-glass__brand"
            href="#crown-bar"
            onClick={(event) => event.preventDefault()}
          >
            <span className="atd-glass__mark" aria-hidden="true">
              {BRAND_MARK}
            </span>
            <span className="atd-glass__word">Modus</span>
          </a>
          <span className="atd-glass__hairline" aria-hidden="true" />
          <nav
            ref={rootRef}
            className="atd-glass__dock"
            aria-label="Primary"
            data-dock-state="idle"
            data-dock-max="0.00"
          >
            {dockItems("atd-glass__item", "atd-glass__icon", "0 0 16 16")}
          </nav>
          <span className="atd-glass__hairline" aria-hidden="true" />
          <button className="atd-glass__cta" type="button">
            Get the app
            <svg viewBox="0 0 16 16" aria-hidden="true">
              <path d="M3.4 8h9.2M8.8 4.2 12.6 8l-3.8 3.8" />
            </svg>
          </button>
        </header>
        <p className="animated-top-dock-component__caption">
          VERTICAL RAIL · SCREEN-SPACE DISPERSION
        </p>
      </div>
    );
  }

  return (
    <div className={cn("animated-top-dock-component", className)}>
      {styles}
      <nav
        ref={rootRef}
        className="animated-top-dock__nav"
        aria-label="Animated top dock"
        data-dock-state="idle"
        data-dock-max="0.00"
      >
        <button
          className="animated-top-dock__item animated-top-dock__logo"
          data-dock-item
          type="button"
          aria-label="Home"
          onClick={() => setActive("system")}
        >
          {BRAND_MARK}
        </button>
        {items.map((item) => (
          <button
            key={item.id}
            className="animated-top-dock__item animated-top-dock__link"
            data-dock-item
            type="button"
            aria-pressed={active === item.id}
            onClick={() => setActive(item.id)}
          >
            <span className="animated-top-dock__icon" aria-hidden="true">
              <svg viewBox="0 0 16 16">{item.icon}</svg>
            </span>
            <span>{item.label}</span>
          </button>
        ))}
      </nav>
      <p className="animated-top-dock-component__caption">MOVE ACROSS THE DOCK · FOCUS WITH TAB</p>
    </div>
  );
}

/* the original stylesheet, ported verbatim: the dock's container-query scale,
   pseudo-element overlays and attribute-driven states do not map to utilities */
const CROWN_BAR_CSS = `
.animated-top-dock-component {
  position: relative;
  width: 100%;
  height: 100%;
  min-width: 0;
  min-height: 0;
  overflow: hidden;
  container-type: inline-size;
  color: hsl(var(--foreground));
  background: hsl(var(--background));
  font-family: var(--font-body), ui-sans-serif, system-ui, sans-serif;
}
.animated-top-dock-component::after {
  position: absolute;
  inset: 0;
  z-index: 5;
  pointer-events: none;
  content: "";
  opacity: 0.12;
  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 180 180' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.85' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='.16'/%3E%3C/svg%3E");
  mix-blend-mode: soft-light;
}
.animated-top-dock-component__caption {
  position: absolute;
  z-index: 6;
  color: hsl(var(--muted-foreground));
  font: 400 9px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.1em;
}
.animated-top-dock-component {
  position: relative;
  display: grid;
  place-items: center;
  isolation: isolate;
  background:
    radial-gradient(circle at 50% 20%, hsl(var(--foreground) / 0.035), transparent 34%),
    hsl(var(--background));
}

.animated-top-dock__nav {
  position: absolute;
  top: clamp(24px, 5cqw, 46px);
  left: 50%;
  z-index: 10;
  display: flex;
  align-items: flex-start;
  gap: 3px;
  height: 38px;
  padding: 4px;
  overflow: visible;
  border: 1px solid hsl(var(--card));
  border-radius: 11px;
  background: hsl(var(--background) / 0.86);
  box-shadow: 0 12px 34px rgba(0, 0, 0, 0.48), inset 0 1px hsl(var(--foreground) / 0.035);
  backdrop-filter: blur(18px) saturate(75%);
  transform: translateX(-50%);
  isolation: isolate;
}

.animated-top-dock__item {
  position: relative;
  z-index: 6;
  display: inline-flex;
  flex: none;
  align-items: center;
  justify-content: center;
  height: 28px;
  min-width: 0;
  padding: 0;
  border: 1px solid transparent;
  border-radius: 7px;
  outline: none;
  color: hsl(var(--muted-foreground));
  background: hsl(var(--background) / 0.9);
  font: 400 10px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.1em;
  white-space: nowrap;
  backdrop-filter: blur(14px) saturate(70%);
  transform-origin: 50% 0;
  transition: color 0.15s, border-color 0.18s, background 0.18s, box-shadow 0.18s;
  will-change: width, height, transform;
  cursor: pointer;
}

.animated-top-dock__item[data-dock-near="true"],
.animated-top-dock__item:focus-visible {
  z-index: 7;
  color: hsl(var(--foreground));
  border-color: hsl(var(--border));
  background: hsl(var(--card) / 0.94);
  box-shadow: 0 7px 16px rgba(0, 0, 0, 0.26);
}

.animated-top-dock__logo {
  width: 28px;
  height: 28px;
  overflow: hidden;
  background: hsl(var(--foreground));
}

.animated-top-dock__logo svg {
  display: block;
  width: 100%;
  height: 100%;
}

.animated-top-dock__link {
  gap: 6px;
  width: 94px;
  padding: 0 9px;
}

.animated-top-dock__link[aria-pressed="true"] {
  color: hsl(var(--background));
  border-color: hsl(var(--foreground));
  background: hsl(var(--foreground));
  box-shadow: 0 7px 18px rgba(0, 0, 0, 0.28);
}

.animated-top-dock__icon {
  display: inline-flex;
  flex: none;
  align-items: center;
  justify-content: center;
  width: 13px;
  height: 13px;
  opacity: 0.62;
  transition: opacity 0.16s;
}

.animated-top-dock__icon svg {
  display: block;
  width: 100%;
  height: 100%;
  fill: none;
  stroke: currentColor;
  stroke-width: 1.2;
  stroke-linecap: round;
  stroke-linejoin: round;
}

.animated-top-dock__item[data-dock-near="true"] .animated-top-dock__icon,
.animated-top-dock__item:focus-visible .animated-top-dock__icon {
  opacity: 1;
}

.animated-top-dock-component__caption {
  right: 18px;
  bottom: 16px;
}

@media (max-width: 600px) {

  .animated-top-dock__nav {
    top: 24px;
    gap: 2px;
    height: 36px;
  }

  .animated-top-dock__item {
    height: 26px !important;
    transform: none !important;
  }

  .animated-top-dock__logo {
    width: 26px !important;
    height: 26px !important;
  }

  .animated-top-dock__link {
    width: auto !important;
    padding: 0 7px;
    font-size: 8px;
    letter-spacing: 0.07em;
  }

  .animated-top-dock__icon {
    display: none;
  }
}
@media (prefers-reduced-motion: reduce) {
  .animated-top-dock__item {
    transform: none !important;
  }
}

/* ── Top dock variants ────────────────────────────────────────────────────
   Every dimension below is a container query unit with a clamp, because these
   bars are shown at anything from a 600 px card to a 1920 px capture frame: a
   fixed 56 px bar that reads correctly in the catalogue frame becomes a thin
   strip of small type at full width. One scale block feeds all three. */

.animated-top-dock-component.atd-modern,
.animated-top-dock-component.atd-retro,
.animated-top-dock-component.atd-glass {
  --atd-top: clamp(16px, 2.6cqw, 46px);
  --atd-bar-width: min(1460px, calc(100% - clamp(24px, 4.2cqw, 96px)));
  --atd-bar-height: clamp(48px, 3.4cqw, 68px);
  --atd-bar-pad: clamp(5px, 0.42cqw, 9px);
  --atd-bar-lead: clamp(14px, 1.15cqw, 25px);
  --atd-item-height: clamp(30px, 2.2cqw, 44px);
  --atd-item-pad: clamp(10px, 0.86cqw, 18px);
  --atd-label: clamp(12px, 0.78cqw, 17px);
  --atd-icon: clamp(13px, 0.92cqw, 19px);
  --atd-gap: clamp(5px, 0.44cqw, 9px);
  --atd-brand: clamp(13px, 0.94cqw, 20px);
  --atd-mark: clamp(22px, 1.55cqw, 33px);
  --atd-action-height: clamp(34px, 2.5cqw, 50px);
  display: block;
  overflow: hidden;
}

.atd-modern__bar,
.atd-retro__bar {
  position: absolute;
  top: var(--atd-top);
  left: 50%;
  z-index: 10;
  display: flex;
  align-items: center;
  justify-content: space-between;
  width: var(--atd-bar-width);
  height: var(--atd-bar-height);
  transform: translateX(-50%);
}

/* Command bar: the bar hugs its own content — brand, dock and actions sit in
   one flow with a gap between them rather than being pushed to the far edges of
   a full-bleed strip. That only holds because the dock's track is locked to its
   rest width (lockTrack in the controller): the spring then grows its items
   outside that track instead of widening the bar and shoving the brand and the
   actions around on every pointer move. */
.atd-modern__bar {
  /* space-between is inherited rather than centred on purpose: at its natural
     width the three groups already fill the box, and in a shell too narrow for
     them the overflow then runs off the right instead of taking the brand off
     the left as well */
  width: max-content;
  max-width: var(--atd-bar-width);
  padding: var(--atd-bar-pad) var(--atd-bar-pad) var(--atd-bar-pad) var(--atd-bar-lead);
}

.atd-modern__dock {
  display: flex;
  flex: none;
  gap: clamp(2px, 0.2cqw, 5px);
  align-items: flex-start;
  /* the track is one item tall and its rest width wide, and the row is centred
     inside it, so a growing item overflows evenly on all four sides without
     moving a single neighbour in the bar */
  justify-content: center;
  height: var(--atd-item-height);
}

.atd-modern__item,
.atd-retro__item,
.atd-glass__item {
  display: inline-flex;
  flex: none;
  gap: var(--atd-gap);
  align-items: center;
  justify-content: center;
  height: var(--atd-item-height);
  padding: 0 var(--atd-item-pad);
  outline: none;
  white-space: nowrap;
  transform-origin: 50% 0;
  will-change: width, height, transform;
  cursor: pointer;
}

.atd-modern__brand,
.atd-glass__brand,
.atd-retro__brand {
  display: inline-flex;
  flex: none;
  gap: clamp(7px, 0.6cqw, 13px);
  align-items: center;
  text-decoration: none;
}

.atd-modern__mark,
.atd-glass__mark {
  display: block;
  width: var(--atd-mark);
  height: var(--atd-mark);
  overflow: hidden;
}

.atd-modern__mark svg,
.atd-glass__mark svg {
  display: block;
  width: 100%;
  height: 100%;
}

.atd-modern__word,
.atd-glass__word {
  font-family: var(--font-heading), ui-serif, Georgia, serif;
  font-size: calc(var(--atd-brand) * 1.25);
  font-style: italic;
  font-weight: 400;
  letter-spacing: -0.01em;
}

.atd-modern__actions {
  display: inline-flex;
  flex: none;
  gap: clamp(4px, 0.34cqw, 8px);
  align-items: center;
}

.atd-modern__ghost {
  height: var(--atd-action-height);
  padding: 0 clamp(12px, 0.95cqw, 20px);
  border: 0;
  border-radius: 999px;
  background: transparent;
  font: 500 var(--atd-label) / 1 inherit;
  transition: color 0.16s, background 0.16s;
  cursor: pointer;
}

.atd-modern__cta,
.atd-glass__cta {
  height: var(--atd-action-height);
  border-radius: 999px;
  font: 600 var(--atd-label) / 1 inherit;
  letter-spacing: -0.01em;
  white-space: nowrap;
  transition: transform 0.18s cubic-bezier(0.22, 1, 0.36, 1), box-shadow 0.18s;
  cursor: pointer;
}

/* ── Modern command bar ─────────────────────────────────────────────────── */

.animated-top-dock-component.atd-modern {
  /* a ceiling rather than a width: the command bar sizes itself to its own
     cluster, and only falls back to an inset strip in a shell too narrow to
     hold it */
  --atd-bar-width: min(1240px, calc(100% - clamp(24px, 5cqw, 120px)));
  background: hsl(var(--background));
}

.atd-modern__aurora {
  position: absolute;
  inset: -24% -12% auto -12%;
  z-index: 1;
  height: 82%;
  pointer-events: none;
  background:
    radial-gradient(58% 62% at 22% 36%, hsl(var(--primary) / 0.4), transparent 68%),
    radial-gradient(46% 56% at 78% 20%, hsl(var(--primary) / 0.3), transparent 70%),
    radial-gradient(40% 48% at 52% 6%, hsl(var(--primary) / 0.2), transparent 72%),
    radial-gradient(34% 40% at 50% 14%, hsl(var(--foreground) / 0.07), transparent 76%);
  filter: blur(8px);
}

.atd-modern__bar {
  gap: clamp(14px, 2.4cqw, 40px);
  border: 1px solid hsl(var(--foreground) / 0.045);
  border-radius: 999px;
  background: linear-gradient(180deg, hsl(var(--card) / 0.86), hsl(var(--background) / 0.82));
  box-shadow: 0 22px 52px -24px rgba(0, 0, 0, 0.92), inset 0 1px hsl(var(--foreground) / 0.045);
  backdrop-filter: blur(22px) saturate(150%);
  -webkit-backdrop-filter: blur(22px) saturate(150%);
}

.atd-modern__brand {
  color: hsl(var(--foreground));
}

.atd-modern__mark {
  /* a full circle: the shared brand mark is a rounded square, so the disc is cut
     from it by the mark box's own clip rather than by a second svg */
  border-radius: 50%;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.42);
}

.atd-modern__item {
  border: 1px solid transparent;
  border-radius: 999px;
  color: hsl(var(--muted-foreground));
  background: transparent;
  font: 500 var(--atd-label) / 1 inherit;
  letter-spacing: -0.005em;
  transition: color 0.16s, border-color 0.18s, background 0.18s, box-shadow 0.18s, backdrop-filter 0.18s;
}

/* :hover is carried alongside the proximity flag so the glass still lands when
   the spring is off — reduced motion, a coarse pointer, a narrow viewport */
.atd-modern__item[data-dock-near="true"],
.atd-modern__item:hover,
.atd-modern__item:focus-visible {
  color: hsl(var(--foreground));
  border-color: hsl(var(--foreground) / 0.055);
  background: hsl(var(--foreground) / 0.055);
  box-shadow: 0 8px 20px -14px rgba(0, 0, 0, 0.9), inset 0 1px hsl(var(--foreground) / 0.05);
  backdrop-filter: blur(18px) saturate(170%);
  -webkit-backdrop-filter: blur(18px) saturate(170%);
}

.atd-modern__item[aria-pressed="true"] {
  color: hsl(var(--background));
  border-color: transparent;
  background: linear-gradient(180deg, hsl(var(--foreground)), hsl(var(--foreground)));
  box-shadow: 0 10px 24px -12px hsl(var(--primary) / 0.75), inset 0 -1px rgba(0, 0, 0, 0.14);
}

.atd-modern__icon,
.atd-glass__icon {
  display: inline-flex;
  flex: none;
  align-items: center;
  justify-content: center;
  width: var(--atd-icon);
  height: var(--atd-icon);
  opacity: 0.72;
  transition: opacity 0.16s;
}

.atd-modern__icon svg,
.atd-glass__icon svg {
  display: block;
  width: 100%;
  height: 100%;
  fill: none;
  stroke: currentColor;
  stroke-width: 1.25;
  stroke-linecap: round;
  stroke-linejoin: round;
}

.atd-modern__item[data-dock-near="true"] .atd-modern__icon,
.atd-modern__item[aria-pressed="true"] .atd-modern__icon,
.atd-glass__item[data-dock-near="true"] .atd-glass__icon,
.atd-glass__item[aria-pressed="true"] .atd-glass__icon {
  opacity: 1;
}

.atd-modern__ghost {
  color: hsl(var(--muted-foreground));
}

.atd-modern__ghost:hover {
  color: hsl(var(--foreground));
  background: hsl(var(--foreground) / 0.06);
}

.atd-modern__cta {
  display: inline-flex;
  gap: var(--atd-gap);
  align-items: center;
  padding: 0 var(--atd-bar-pad) 0 clamp(14px, 1.1cqw, 24px);
  border: 0;
  color: hsl(var(--background));
  background: linear-gradient(180deg, hsl(var(--foreground)), hsl(var(--foreground)));
  box-shadow: 0 10px 26px -14px hsl(var(--primary) / 0.95), inset 0 -1px rgba(0, 0, 0, 0.16);
}

.atd-modern__cta svg {
  box-sizing: border-box;
  width: calc(var(--atd-action-height) - clamp(12px, 0.9cqw, 20px));
  height: calc(var(--atd-action-height) - clamp(12px, 0.9cqw, 20px));
  padding: clamp(4px, 0.3cqw, 7px);
  border-radius: 999px;
  background: hsl(var(--background) / 0.1);
  fill: none;
  stroke: currentColor;
  stroke-width: 1.4;
  stroke-linecap: round;
  stroke-linejoin: round;
}

.atd-modern__cta:hover {
  box-shadow: 0 16px 32px -14px hsl(var(--primary)), inset 0 -1px rgba(0, 0, 0, 0.16);
  transform: translateY(-1px);
}

.atd-modern__stage {
  position: absolute;
  top: 58%;
  left: 50%;
  z-index: 4;
  width: min(88cqw, 1120px);
  text-align: center;
  pointer-events: none;
  transform: translate(-50%, -50%);
}

.atd-modern__eyebrow {
  margin: 0 0 clamp(8px, 0.9cqw, 18px);
  color: hsl(var(--muted-foreground));
  font: 400 clamp(8px, 0.62cqw, 13px) / 1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.22em;
  text-transform: uppercase;
}

.atd-modern__headline {
  /* background-clip: text paints only inside the element box, so at this size a
     1.0-ish line-height would cut the ascenders and descenders out of the fill.
     The padding buys the ink its own room back. */
  margin: 0;
  padding: 0.08em 0 0.14em;
  color: transparent;
  background: linear-gradient(180deg, hsl(var(--foreground)) 16%, hsl(var(--foreground) / 0.3));
  background-clip: text;
  -webkit-background-clip: text;
  font-family: var(--font-heading), ui-serif, Georgia, serif;
  font-size: clamp(30px, 7.6cqw, 150px);
  font-weight: 400;
  line-height: 1.04;
  letter-spacing: -0.03em;
  text-wrap: balance;
}

/* ── Retro pixel terminal ───────────────────────────────────────────────────
   The field canvas is a small drawing buffer stretched by CSS with
   nearest-neighbour sampling, so its dither pattern arrives as real square
   pixels. Every chrome edge here is square to sit on that same grid. */

.animated-top-dock-component.atd-retro {
  --atd-label: clamp(9px, 0.68cqw, 15px);
  --atd-icon: clamp(10px, 0.78cqw, 17px);
  --atd-brand: clamp(11px, 0.8cqw, 18px);
  background: hsl(var(--background));
}

.atd-retro__field {
  position: absolute;
  inset: 0;
  z-index: 0;
  display: block;
  width: 100%;
  height: 100%;
  image-rendering: pixelated;
}

.atd-retro__vignette {
  position: absolute;
  inset: 0;
  z-index: 1;
  pointer-events: none;
  background:
    radial-gradient(124% 90% at 50% 34%, transparent 28%, hsl(var(--background) / 0.62) 100%),
    linear-gradient(180deg, hsl(var(--background) / 0.6) 0%, transparent 24%, transparent 62%, hsl(var(--background) / 0.58) 100%);
}

/* the raster runs at screen resolution, not at the field's pixel scale, so the
   line structure stays a raster instead of banding the chunky artwork */
.atd-retro::before {
  position: absolute;
  inset: 0;
  z-index: 11;
  pointer-events: none;
  content: "";
  opacity: calc(var(--atd-retro-scan, 0.32) * 1.5);
  background: repeating-linear-gradient(180deg, rgba(0, 0, 0, 0.42) 0 1px, transparent 1px 3px);
}

/* Horizontal fit: the bar is one continuous strip and the menu cells own all of
   it. There are no gaps and no rounded ends — every cell is separated by a rule
   and runs the full height, and the controller renormalises the widths so
   opening one cell takes its room from the neighbours. */
.atd-retro__bar {
  gap: 0;
  padding: 0;
  overflow: hidden;
  border: 2px solid hsl(var(--foreground));
  background: hsl(var(--background));
  box-shadow: 6px 6px 0 hsl(var(--background) / 0.62);
}

.atd-retro__brand {
  height: 100%;
  padding: 0 clamp(12px, 1.1cqw, 26px);
  border-right: 2px solid color-mix(in hsl, hsl(var(--primary)) 38%, hsl(var(--background)));
  color: hsl(var(--primary));
  background: hsl(var(--background));
  font: 400 var(--atd-brand) / 1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.12em;
}

.atd-retro__dock {
  display: flex;
  flex: 1 1 0;
  gap: 0;
  align-items: stretch;
  min-width: 0;
  height: 100%;
}

.atd-retro__badge {
  display: inline-flex;
  width: var(--atd-icon);
  height: var(--atd-icon);
}

.atd-retro__badge svg,
.atd-retro__icon svg {
  display: block;
  width: 100%;
  height: 100%;
  fill: currentColor;
  shape-rendering: crispEdges;
}

.atd-retro__item {
  height: 100%;
  min-width: 0;
  padding: 0 clamp(6px, 0.5cqw, 12px);
  overflow: hidden;
  border: 0;
  border-right: 2px solid color-mix(in hsl, hsl(var(--primary)) 38%, hsl(var(--background)));
  color: hsl(var(--primary));
  background: hsl(var(--card));
  font: 400 var(--atd-label) / 1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.14em;
  transition: color 0.1s steps(2), background 0.1s steps(2);
}

.atd-retro__item[data-dock-near="true"],
.atd-retro__item:focus-visible {
  color: hsl(var(--foreground));
  background: color-mix(in hsl, hsl(var(--primary)) 32%, hsl(var(--background)));
}

.atd-retro__item[aria-pressed="true"] {
  color: hsl(var(--background));
  background: hsl(var(--primary));
}

.atd-retro__icon {
  display: inline-flex;
  flex: none;
  width: var(--atd-icon);
  height: var(--atd-icon);
}

.atd-retro__cta {
  display: inline-flex;
  flex: none;
  gap: var(--atd-gap);
  align-items: center;
  height: 100%;
  padding: 0 clamp(14px, 1.2cqw, 28px);
  border: 0;
  border-left: 2px solid hsl(var(--foreground));
  color: hsl(var(--background));
  background: hsl(var(--primary));
  font: 400 var(--atd-label) / 1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.16em;
  transition: background 0.1s steps(2), color 0.1s steps(2);
  cursor: pointer;
}

.atd-retro__cta:hover {
  color: hsl(var(--background));
  background: hsl(var(--primary));
}

.atd-retro__readout {
  position: absolute;
  bottom: clamp(30px, 4.2cqw, 74px);
  left: 50%;
  z-index: 8;
  display: flex;
  gap: clamp(12px, 2.4cqw, 42px);
  margin: 0;
  color: hsl(var(--primary));
  font: 400 clamp(9px, 0.62cqw, 13px) / 1 ui-monospace, SFMono-Regular, Menlo, monospace;
  letter-spacing: 0.2em;
  transform: translateX(-50%);
}

/* ── Liquid glass ───────────────────────────────────────────────────────────
   Vertical fit: the dock leaves the top edge for a rail down the left side. The
   proximity field runs on the y axis, so an item grows taller and leans out to
   the right instead of widening and dropping. The rail is a real
   backdrop-filter panel over the refracting Three.js bead field, so its blur
   samples the same pixels the glass shader refracts. */

.animated-top-dock-component.atd-glass {
  --atd-rail-width: clamp(158px, 12.5cqw, 250px);
  background: hsl(var(--background));
}

.atd-glass__field {
  position: absolute;
  inset: 0;
  z-index: 0;
  display: block;
  width: 100%;
  height: 100%;
}

/* a scrim behind the rail: the bead field is bright enough in places to swallow
   the wordmark, and the panel's own blur cannot darken what it samples */
.atd-glass::before {
  position: absolute;
  inset: 0 auto 0 0;
  z-index: 5;
  width: 42%;
  pointer-events: none;
  content: "";
  background: linear-gradient(90deg, hsl(var(--background) / 0.66), hsl(var(--background) / 0));
}

.atd-glass__rail {
  position: absolute;
  top: 50%;
  left: clamp(20px, 3.4cqw, 68px);
  z-index: 10;
  display: flex;
  flex-direction: column;
  gap: clamp(6px, 0.5cqw, 11px);
  align-items: stretch;
  width: var(--atd-rail-width);
  padding: var(--atd-bar-pad);
  border-radius: clamp(20px, 1.7cqw, 34px);
  background: linear-gradient(160deg, hsl(var(--foreground) / 0.15), hsl(var(--foreground) / 0.05));
  box-shadow:
    0 30px 64px -26px rgba(0, 0, 0, 0.92),
    inset 0 1px 0 hsl(var(--foreground) / 0.44),
    inset 0 -1px 0 hsl(var(--foreground) / 0.12),
    inset 0 0 0 1px hsl(var(--foreground) / 0.14);
  backdrop-filter: blur(26px) saturate(190%);
  -webkit-backdrop-filter: blur(26px) saturate(190%);
  transform: translateY(-50%);
}

.atd-glass__rail::before {
  position: absolute;
  inset: 0;
  pointer-events: none;
  content: "";
  border-radius: inherit;
  background: linear-gradient(168deg, hsl(var(--foreground) / 0.22) 0%, hsl(var(--foreground) / 0) 30%, hsl(var(--foreground) / 0) 76%, hsl(var(--foreground) / 0.14) 100%);
}

.atd-glass__brand {
  position: relative;
  padding: clamp(6px, 0.5cqw, 12px) clamp(8px, 0.7cqw, 15px);
  color: hsl(var(--foreground));
}

.atd-glass__mark {
  border-radius: clamp(7px, 0.5cqw, 11px);
  box-shadow: 0 3px 10px rgba(0, 0, 0, 0.42), inset 0 0 0 1px hsl(var(--foreground) / 0.3);
}

.atd-glass__hairline {
  height: 1px;
  margin: clamp(2px, 0.2cqw, 5px) clamp(6px, 0.5cqw, 12px);
  background: linear-gradient(90deg, hsl(var(--foreground) / 0.04), hsl(var(--foreground) / 0.26), hsl(var(--foreground) / 0.04));
}

.atd-glass__dock {
  position: relative;
  display: flex;
  flex-direction: column;
  gap: clamp(2px, 0.2cqw, 5px);
  align-items: stretch;
}

.atd-glass__item {
  justify-content: flex-start;
  width: 100%;
  border: 1px solid transparent;
  border-radius: clamp(12px, 1cqw, 22px);
  color: hsl(var(--foreground) / 0.66);
  background: transparent;
  font: 500 var(--atd-label) / 1 inherit;
  letter-spacing: -0.005em;
  /* the rail grows downward from each item's own top edge */
  transform-origin: 0 50%;
  transition: color 0.18s, border-color 0.2s, background 0.2s, box-shadow 0.2s;
}

.atd-glass__item[data-dock-near="true"],
.atd-glass__item:focus-visible {
  color: hsl(var(--foreground));
  border-color: hsl(var(--foreground) / 0.24);
  background: linear-gradient(180deg, hsl(var(--foreground) / 0.22), hsl(var(--foreground) / 0.07));
  box-shadow: inset 0 1px 0 hsl(var(--foreground) / 0.46), 0 8px 18px -10px rgba(0, 0, 0, 0.8);
}

.atd-glass__item[aria-pressed="true"] {
  color: hsl(var(--background));
  border-color: hsl(var(--foreground) / 0.6);
  background: linear-gradient(180deg, hsl(var(--foreground)), hsl(var(--foreground)));
  box-shadow: 0 10px 24px -12px hsl(var(--foreground) / 0.5), inset 0 -1px rgba(0, 0, 0, 0.14);
}

.atd-glass__cta {
  display: inline-flex;
  gap: var(--atd-gap);
  align-items: center;
  justify-content: space-between;
  width: 100%;
  padding: 0 clamp(12px, 1cqw, 22px);
  border: 1px solid hsl(var(--foreground) / 0.55);
  color: hsl(var(--background));
  background: linear-gradient(180deg, hsl(var(--foreground)), hsl(var(--foreground)));
  box-shadow: 0 12px 30px -14px hsl(var(--foreground) / 0.6), inset 0 -1px rgba(0, 0, 0, 0.16);
}

.atd-glass__cta svg {
  width: var(--atd-icon);
  height: var(--atd-icon);
  fill: none;
  stroke: currentColor;
  stroke-width: 1.5;
  stroke-linecap: round;
  stroke-linejoin: round;
}

.atd-glass__cta:hover {
  box-shadow: 0 16px 34px -14px hsl(var(--foreground) / 0.75), inset 0 -1px rgba(0, 0, 0, 0.16);
  transform: translateY(-1px);
}

.atd-modern .animated-top-dock-component__caption,
.atd-glass .animated-top-dock-component__caption {
  color: hsl(var(--foreground) / 0.34);
}

.atd-retro .animated-top-dock-component__caption {
  z-index: 12;
  color: hsl(var(--primary));
}

@container (max-width: 900px) {
  .atd-modern__ghost {
    display: none;
  }

  .atd-modern__item span:last-child,
  .atd-retro__item span:last-child {
    display: none;
  }

  /* the bar is sized by its content now, so a shell this narrow has to give the
     content back: the call to action drops to its glyph rather than pushing the
     cluster past the bar's own max width */
  .atd-modern__cta span {
    display: none;
  }

  .atd-modern__cta {
    padding: 0 var(--atd-bar-pad);
  }

  /* the rail collapses to its icons rather than keeping a 158 px column in a
     card that is only a few hundred pixels wide */
  .animated-top-dock-component.atd-glass {
    --atd-rail-width: auto;
  }

  .atd-glass__item {
    justify-content: center;
  }

  .atd-glass__item span:last-child,
  .atd-glass__word,
  .atd-glass__cta span {
    display: none;
  }

  .atd-glass__cta {
    justify-content: center;
  }
}

@media (max-width: 600px) {
  .atd-modern__word {
    display: none;
  }

  .atd-modern__item {
    height: 28px !important;
    transform: none !important;
  }

  .atd-glass__item {
    height: auto !important;
    transform: none !important;
  }

  /* the strip keeps its full-height cells on a phone; only the spring stops */
  .atd-retro__item {
    height: 100% !important;
    transform: none !important;
  }

  .atd-modern__stage {
    top: 62%;
  }

  .atd-retro__readout {
    display: none;
  }
}

@media (prefers-reduced-motion: reduce) {
  .atd-modern__item,
  .atd-retro__item,
  .atd-glass__item {
    transform: none !important;
  }
}
`;
```

---

# Mote Beacon

> Italic serif letters and marks sinking through the page while accent beams rise, threading themselves to your pointer.

Install: `npx @modus-ui/cli add mote-beacon`

About seventy italic letters and editorial marks (§ ¶ † &) set in the theme heading font sink down the page, swapping characters and linking to their neighbours with hairlines, while beams in `--primary` rise through them. Marks near the pointer take the accent and connect to it. Everything is drawn from theme tokens on `--background` and follows palette and mode changes live. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add mote-beacon
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/mote-beacon.tsx`.
3. Paste the code.

## Usage

```tsx
import { MoteBeacon } from "@/components/ui/mote-beacon";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <MoteBeacon />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                         |
| :---------------- | :------- | :------------------- | :-------------------------------------------------- |
| `speed`           | `number` | `1`                  | Animation speed multiplier (0–3).                   |
| `size`            | `number` | `1`                  | Stroke / scale multiplier.                          |
| `length`          | `number` | `1`                  | Length / reach multiplier (0.35–2.5).               |
| `density`         | `number` | `0.8`                | Glyph and beam count multiplier. (0.25–2.5).        |
| `opacity`         | `number` | `1`                  | Opacity of the effect layer (0.05–1).               |
| `hue`             | `number` | `0`                  | Hue rotation in degrees applied to the final frame. |
| `saturation`      | `number` | `1`                  | Saturation multiplier applied to the final frame.   |
| `brightness`      | `number` | `1`                  | Brightness multiplier applied to the final frame.   |
| `backgroundColor` | `string` | theme `--background` | Background colour behind the canvas.                |

## Source

`components/ui/mote-beacon.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Particle Drift (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface MoteBeaconProps {
  className?: string;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  backgroundColor?: string;
}

// Editorial marks rather than terminal characters.
const CHARS = "abcdefghmnorstuwxyz&§¶†‡*+·~".split("");
const root = () => getComputedStyle(document.documentElement);
const hsl = (channels: string, alpha = 1) => `hsl(${channels} / ${alpha})`;
const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
const scaleCount = (base: number, density: number, minimum: number) =>
  Math.max(minimum, Math.round(base * density));

export function MoteBeacon({
  className,
  speed = 1,
  size = 1,
  length = 1,
  density = 0.8,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
}: MoteBeaconProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const [themeKey, setThemeKey] = useState(0);
  const safeSize = clamp(size, 0.05, 200);
  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    const link = Math.round(120 * safeLength);
    const proximityAlpha = 0.2;
    const primary = root().getPropertyValue("--primary").trim();
    const muted = root().getPropertyValue("--muted-foreground").trim();
    const activeFill = hsl(primary);
    const idleFill = hsl(muted, 0.6);
    const fontFamily = root().getPropertyValue("--font-heading").trim() || "Georgia, serif";

    let width = 0;
    let height = 0;
    let nodes: { x: number; y: number; vy: number; char: string }[] = [];
    let beams: {
      x: number;
      y: number;
      length: number;
      speed: number;
      opacity: number;
    }[] = [];
    const mouse = { x: -1000, y: -1000 };

    const initParticles = () => {
      nodes = Array.from({ length: scaleCount(90, safeDensity, 12) }).map(() => ({
        x: Math.random() * width,
        y: Math.random() * height,
        vy: Math.random() * 0.4 + 0.1,
        char: CHARS[Math.floor(Math.random() * CHARS.length)],
      }));
      beams = Array.from({ length: scaleCount(25, safeDensity, 4) }).map(() => ({
        x: Math.random() * width,
        y: Math.random() * height,
        length: (Math.random() * 100 + 50) * safeLength,
        speed: Math.random() * 6 + 3,
        opacity: Math.random() * 0.5 + 0.3,
      }));
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      initParticles();
    };

    const draw = (animate: boolean) => {
      const s = animate ? speedRef.current : 0;
      ctx.clearRect(0, 0, width, height);

      beams.forEach((b) => {
        b.y -= b.speed * s;
        if (b.y + b.length < 0) {
          b.y = height + 100;
          b.x = Math.random() * width;
        }
        const g = ctx.createLinearGradient(b.x, b.y, b.x, b.y + b.length);
        g.addColorStop(0, hsl(primary, b.opacity));
        g.addColorStop(1, "transparent");
        ctx.strokeStyle = g;
        ctx.lineWidth = Number((1.5 * safeSize).toFixed(2));
        ctx.beginPath();
        ctx.moveTo(b.x, b.y);
        ctx.lineTo(b.x, b.y + b.length);
        ctx.stroke();
      });

      ctx.font = `italic 15px ${fontFamily}`;
      ctx.textAlign = "center";
      ctx.textBaseline = "middle";

      ctx.lineWidth = 0.5;
      for (let i = 0; i < nodes.length; i++) {
        const n1 = nodes[i];
        for (let j = i + 1; j < nodes.length; j++) {
          const n2 = nodes[j];
          const d = Math.hypot(n1.x - n2.x, n1.y - n2.y);
          if (d < link) {
            ctx.strokeStyle = hsl(muted, proximityAlpha * (1 - d / link));
            ctx.beginPath();
            ctx.moveTo(n1.x, n1.y);
            ctx.lineTo(n2.x, n2.y);
            ctx.stroke();
          }
        }
      }

      nodes.forEach((n) => {
        n.y += n.vy * s;
        if (n.y > height + 20) {
          n.y = -20;
          n.x = Math.random() * width;
        }
        const dist = Math.hypot(mouse.x - n.x, mouse.y - n.y);
        if (animate && (dist < 180 || Math.random() > 0.98))
          n.char = CHARS[Math.floor(Math.random() * CHARS.length)];
        if (dist < 180) {
          ctx.strokeStyle = hsl(primary, 0.5 * (1 - dist / 180));
          ctx.beginPath();
          ctx.moveTo(n.x, n.y);
          ctx.lineTo(mouse.x, mouse.y);
          ctx.stroke();
        }
        ctx.fillStyle = dist < 180 ? activeFill : idleFill;
        ctx.fillText(n.char, n.x, n.y);
      });
    };

    const onMove = (e: PointerEvent) => {
      const rect = canvas.getBoundingClientRect();
      mouse.x = e.clientX - rect.left;
      mouse.y = e.clientY - rect.top;
    };

    let raf = 0;
    let inView = true;
    const loop = () => {
      draw(true);
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (prefersReducedMotion) draw(false);
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) draw(false);
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    window.addEventListener("pointermove", onMove);
    sync();
    const themeObserver = new MutationObserver(() => setThemeKey((key) => key + 1));
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });

    return () => {
      themeObserver.disconnect();
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
      window.removeEventListener("pointermove", onMove);
    };
  }, [themeKey, safeSize, safeLength, safeDensity, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Ink Rush

> Rounded ink strokes rushing out of a high vanishing point, in the theme ink and accent.

Install: `npx @modus-ui/cli add ink-rush`

Two hundred rounded strokes fly out of a vanishing point set high in the frame, mixing `--foreground`, `--muted-foreground` and `--primary` and leaving short trails that fade into `--background`. In light mode it reads as ink on paper; it follows palette and mode changes live. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-rush
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ink-rush.tsx`.
3. Paste the code.

## Usage

```tsx
import { InkRush } from "@/components/ui/ink-rush";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <InkRush />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                         |
| :---------------- | :------- | :------------------- | :-------------------------------------------------- |
| `speed`           | `number` | `1`                  | Animation speed multiplier (0–3).                   |
| `size`            | `number` | `1`                  | Field-of-view scale multiplier.                     |
| `length`          | `number` | `1`                  | Length / reach multiplier (0.35–2.5).               |
| `density`         | `number` | `1`                  | Streak count multiplier. (0.25–2.5).                |
| `opacity`         | `number` | `1`                  | Opacity of the effect layer (0.05–1).               |
| `hue`             | `number` | `0`                  | Hue rotation in degrees applied to the final frame. |
| `saturation`      | `number` | `1`                  | Saturation multiplier applied to the final frame.   |
| `brightness`      | `number` | `1`                  | Brightness multiplier applied to the final frame.   |
| `backgroundColor` | `string` | theme `--background` | Background colour behind the canvas.                |

## Source

`components/ui/ink-rush.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Particle Network (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface InkRushProps {
  className?: string;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  backgroundColor?: string;
}

const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
const scaleCount = (base: number, density: number, minimum: number) =>
  Math.max(minimum, Math.round(base * density));

const SPEED_MULTIPLIER = 1.1;
const readToken = (name: string) =>
  getComputedStyle(document.documentElement).getPropertyValue(name).trim();

export function InkRush({
  className,
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
}: InkRushProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const [themeKey, setThemeKey] = useState(0);
  const safeSize = clamp(size, 0.05, 200);
  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    const particleCount = scaleCount(200, safeDensity, 40);
    const fov = Math.round(300 / Math.max(0.4, safeSize));
    // Trails fade into the page colour; streaks alternate between ink and accent.
    const fade = `hsl(${readToken("--background")} / 0.5)`;
    const hues = [
      readToken("--foreground"),
      readToken("--primary"),
      readToken("--muted-foreground"),
    ];

    let width = 0;
    let height = 0;
    let originX = 0;
    let originY = 0;

    type P = {
      x: number;
      y: number;
      z: number;
      speed: number;
      rgb: string;
      length: number;
    };
    const reset = (p: P) => {
      const angle = Math.random() * Math.PI * 2;
      const radius = Math.random() * 600;
      p.x = Math.cos(angle) * radius;
      p.y = Math.sin(angle) * radius + 120;
      p.z = 1000;
      p.speed = (Math.random() * 2 + 1) * SPEED_MULTIPLIER;
      p.rgb = hues[Math.floor(Math.random() * hues.length)];
      p.length = (Math.random() * 2 + 0.5) * safeLength;
    };
    const particles: P[] = Array.from({ length: particleCount }, () => {
      const p = { x: 0, y: 0, z: 0, speed: 0, rgb: "", length: 0 };
      reset(p);
      p.z = Math.random() * 1000;
      return p;
    });

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      ctx.imageSmoothingEnabled = false;
      originX = width / 2;
      originY = height * 0.32;
    };

    const drawParticle = (p: P) => {
      const scale = fov / p.z;
      const px = originX + p.x * scale;
      const py = originY + p.y * scale;
      const prevZ = p.z + p.speed * p.length;
      const prevScale = fov / prevZ;
      const prevPx = originX + p.x * prevScale;
      const prevPy = originY + p.y * prevScale;

      let alpha = 1 - p.z / 1000;
      if (p.z < 100) alpha = p.z / 100;
      if (alpha < 0) alpha = 0;

      ctx.beginPath();
      ctx.moveTo(prevPx, prevPy);
      ctx.lineTo(px, py);
      ctx.strokeStyle = `hsl(${p.rgb} / ${alpha * 0.9})`;
      ctx.lineWidth = Math.max(0.4, (1 - p.z / 1000) * 1.2);
      ctx.lineCap = "round";
      ctx.lineJoin = "miter";
      ctx.stroke();
    };

    const frame = (s: number) => {
      ctx.fillStyle = fade;
      ctx.fillRect(0, 0, width, height);
      particles.forEach((p) => {
        p.z -= p.speed * s;
        if (p.z <= 0) reset(p);
        drawParticle(p);
      });
    };

    const still = () => {
      ctx.clearRect(0, 0, width, height);
      for (let i = 0; i < 6; i++) frame(1);
    };

    let raf = 0;
    let inView = true;
    const loop = () => {
      frame(speedRef.current);
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (prefersReducedMotion) still();
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) still();
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();
    const themeObserver = new MutationObserver(() => setThemeKey((key) => key + 1));
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });

    return () => {
      themeObserver.disconnect();
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
    };
  }, [themeKey, safeSize, safeLength, safeDensity, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Arch Current

> Dotted Bézier paths sweeping in from both edges to a low vanishing point, drawn in your theme's ink.

Install: `npx @modus-ui/cli add arch-current`

A canvas of dotted Bézier paths that sweep in from both edges and gather at a low point near the bottom of the frame, with beads of ink travelling along them. Click anywhere to send a shockwave through the beads. Guides use the theme's muted tone and beads its primary ink over the theme background, so it follows light, dark and the palette picker. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add arch-current
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/arch-current.tsx`.
3. Paste the code.

## Usage

```tsx
import { ArchCurrent } from "@/components/ui/arch-current";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ArchCurrent />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                                         |
| :---------------- | :------- | :------------------------- | :-------------------------------------------------- |
| `speed`           | `number` | `1`                        | Animation speed multiplier (0–3).                   |
| `size`            | `number` | `1`                        | Stroke / scale multiplier.                          |
| `density`         | `number` | `1`                        | Path count multiplier. (0.25–2.5).                  |
| `opacity`         | `number` | `1`                        | Opacity of the effect layer (0.05–1).               |
| `hue`             | `number` | `0`                        | Hue rotation in degrees applied to the final frame. |
| `saturation`      | `number` | `1`                        | Saturation multiplier applied to the final frame.   |
| `brightness`      | `number` | `1`                        | Brightness multiplier applied to the final frame.   |
| `backgroundColor` | `string` | `"hsl(var(--background))"` | Colour behind the canvas.                           |

## Source

`components/ui/arch-current.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Gateway Flow (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ArchCurrentProps {
  className?: string;
  speed?: number;
  size?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour behind the canvas; defaults to the theme background. */
  backgroundColor?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
const scaleCount = (base: number, density: number, minimum: number) =>
  Math.max(minimum, Math.round(base * density));

type Pt = { x: number; y: number };

function getBezierPoint(t: number, p0: Pt, p1: Pt, p2: Pt, p3: Pt): Pt {
  const u = 1 - t;
  return {
    x: u ** 3 * p0.x + 3 * u ** 2 * t * p1.x + 3 * u * t ** 2 * p2.x + t ** 3 * p3.x,
    y: u ** 3 * p0.y + 3 * u ** 2 * t * p1.y + 3 * u * t ** 2 * p2.y + t ** 3 * p3.y,
  };
}

export function ArchCurrent({
  className,
  speed = 1,
  size = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor = "hsl(var(--background))",
}: ArchCurrentProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const theme = useThemeVersion();
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const safeSize = clamp(size, 0.05, 200);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    // Dotted guides in the muted tone, travelling beads in the primary ink.
    const { dark, primary, muted } = readTheme();
    const stroke = hsl(muted, dark ? 0.4 : 0.5);
    const fill = hsl([primary[0], Math.max(primary[1], 30), dark ? 86 : 22], 0.85);
    const lineWidth = Number((1.2 * safeSize).toFixed(2));
    const numPaths = scaleCount(80, safeDensity, 12);

    let width = 0;
    let height = 0;
    let explosions: { x: number; y: number; radius: number; life: number }[] = [];
    const paths: {
      isLeft: boolean;
      startY: number;
      particles: { t: number; speed: number }[];
    }[] = [];

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      if (!paths.length && height > 0) {
        for (let i = 0; i < numPaths; i++) {
          paths.push({
            isLeft: i % 2 === 0,
            startY: (i / numPaths) * height * 1.4 - height * 0.2,
            particles: [{ t: Math.random(), speed: 0.0015 + Math.random() * 0.002 }],
          });
        }
      }
    };

    const render = (s: number) => {
      ctx.clearRect(0, 0, width, height);
      const centerX = width / 2;
      const centerY = height * 0.78;

      explosions.forEach((exp) => {
        exp.radius += 15;
        exp.life -= 0.015;
      });
      explosions = explosions.filter((exp) => exp.life > 0);

      paths.forEach((path) => {
        const p0 = { x: path.isLeft ? 0 : width, y: path.startY };
        const p1 = {
          x: path.isLeft ? centerX * 0.5 : width - centerX * 0.5,
          y: path.startY,
        };
        const p2 = {
          x: path.isLeft ? centerX * 0.8 : width - centerX * 0.8,
          y: centerY,
        };
        const p3 = { x: centerX, y: centerY };

        ctx.beginPath();
        ctx.moveTo(p0.x, p0.y);
        ctx.bezierCurveTo(p1.x, p1.y, p2.x, p2.y, p3.x, p3.y);
        ctx.strokeStyle = stroke;
        ctx.lineWidth = lineWidth;
        ctx.setLineDash([1, 4]);
        ctx.stroke();
        ctx.setLineDash([]);

        path.particles.forEach((p) => {
          p.t += p.speed * s;
          if (p.t > 1) {
            p.t = 0;
            path.startY += (Math.random() - 0.5) * 10;
          }
          const pos = getBezierPoint(p.t, p0, p1, p2, p3);
          let dxTotal = 0;
          let dyTotal = 0;
          explosions.forEach((exp) => {
            const dx = pos.x - exp.x;
            const dy = pos.y - exp.y;
            const dist = Math.hypot(dx, dy);
            if (dist < exp.radius + 120 && dist > exp.radius - 120) {
              const force = (1 - Math.abs(dist - exp.radius) / 120) * exp.life;
              dxTotal += (dx / dist) * force * 80;
              dyTotal += (dy / dist) * force * 80;
            }
          });
          pos.x += dxTotal;
          pos.y += dyTotal;
          ctx.fillStyle = fill;
          ctx.beginPath();
          ctx.arc(pos.x, pos.y, 1.6, 0, Math.PI * 2);
          ctx.fill();
        });
      });
    };

    const onClick = (e: MouseEvent) => {
      const rect = host.getBoundingClientRect();
      const x = e.clientX - rect.left;
      const y = e.clientY - rect.top;
      if (x < 0 || y < 0 || x > rect.width || y > rect.height) return;
      explosions.push({ x, y, radius: 0, life: 1 });
    };

    let raf = 0;
    let inView = true;
    const loop = () => {
      render(speedRef.current);
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (prefersReducedMotion) render(0);
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) render(0);
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    window.addEventListener("click", onClick);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
      window.removeEventListener("click", onClick);
    };
  }, [safeSize, safeDensity, prefersReducedMotion, theme]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor,
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Ink Fountain

> Primary ink strokes fanning rightward from a source on the left edge.

Install: `npx @modus-ui/cli add ink-fountain`

Hundreds of tapered strokes fan out rightward from a source just off the left edge, thickening as they travel, in the theme's primary with muted tails and foreground tips. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-fountain
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ink-fountain.tsx`.
3. Paste the code.

## Usage

```tsx
import { InkFountain } from "@/components/ui/ink-fountain";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <InkFountain />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default     | Description                                         |
| :---------------- | :------- | :---------- | :-------------------------------------------------- |
| `speed`           | `number` | `0.7`       | Animation speed multiplier (0–3).                   |
| `size`            | `number` | `0.8`       | Stroke width multiplier.                            |
| `length`          | `number` | `1.2`       | Stroke length multiplier (0.35–2.5).                |
| `density`         | `number` | `0.8`       | Stroke count multiplier (0.25–2.5).                 |
| `opacity`         | `number` | `1`         | Opacity of the effect layer (0.05–1).               |
| `hue`             | `number` | `0`         | Hue rotation in degrees applied to the final frame. |
| `saturation`      | `number` | `1`         | Saturation multiplier applied to the final frame.   |
| `brightness`      | `number` | `1`         | Brightness multiplier applied to the final frame.   |
| `backgroundColor` | `string` | `undefined` | CSS background. Defaults to the theme background.   |

## Source

`components/ui/ink-fountain.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Connectivity Graph (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface InkFountainProps {
  className?: string;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** CSS background. Defaults to the theme background. */
  backgroundColor?: string;
}

const TOKENS = [
  "primary",
  "foreground",
  "background",
  "muted-foreground",
  "border",
  "card",
] as const;
type Tokens = Record<(typeof TOKENS)[number], string>;

/** Bare HSL channels of the Modus theme tokens, re-read when the theme or palette changes. */
function useThemeTokens(): Tokens | null {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const next = Object.fromEntries(
        TOKENS.map((name) => [name, style.getPropertyValue(`--${name}`).trim()]),
      ) as Tokens;
      setTokens((prev) => (prev && TOKENS.every((k) => prev[k] === next[k]) ? prev : next));
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
const scaleCount = (base: number, density: number, minimum: number) =>
  Math.max(minimum, Math.round(base * density));

export function InkFountain({
  className,
  speed = 0.7,
  size = 0.8,
  length = 1.2,
  density = 0.8,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
}: InkFountainProps) {
  const tokens = useThemeTokens();
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const safeSize = clamp(size, 0.05, 200);
  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d", { alpha: true });
    if (!host || !canvas || !ctx || !tokens) return;
    const ink = tokens.primary;
    const tail = tokens["muted-foreground"];
    const head = tokens.foreground;

    let width = 0;
    let height = 0;

    type P = {
      angle: number;
      speed: number;
      distance: number;
      maxLength: number;
      length: number;
      alpha: number;
    };
    let particles: P[] = [];

    const reset = (p: P, initial = false) => {
      // Fan rightward from a source on the left edge.
      p.angle = -Math.PI * 0.5 + Math.random() * Math.PI;
      if (Math.random() > 0.3) {
        p.angle = -Math.PI * 0.22 + Math.random() * Math.PI * 0.36;
      }
      p.speed = 0.5 + Math.random() * 2.5;
      p.distance = initial ? Math.random() * (width * 1.1) : Math.random() * 50;
      p.maxLength = (20 + Math.random() * 180) * safeLength;
      p.length = 0;
      p.alpha = 0;
    };

    const update = (p: P, s: number) => {
      p.distance += p.speed * s;
      p.length = Math.min(p.maxLength, p.distance * 0.8);
      const normalizedDist = p.distance / (width * 1.1);
      p.alpha = Math.min(1, p.distance / 100) * Math.max(0, 1 - normalizedDist);
      if (p.distance > width * 1.3) reset(p);
    };

    const draw = (p: P) => {
      const originX = -40;
      const originY = height * 0.62;
      const startX = originX + Math.cos(p.angle) * p.distance;
      const startY = originY + Math.sin(p.angle) * p.distance;
      const endX = originX + Math.cos(p.angle) * (p.distance + p.length);
      const endY = originY + Math.sin(p.angle) * (p.distance + p.length);

      const distRatio = Math.min(1, p.distance / width);
      const color = `hsl(${ink} / ${p.alpha * 0.85})`;
      const tailColor = `hsl(${tail} / ${p.alpha * 0.06})`;

      ctx.beginPath();
      const gradient = ctx.createLinearGradient(startX, startY, endX, endY);
      gradient.addColorStop(0, tailColor);
      gradient.addColorStop(1, color);
      ctx.moveTo(startX, startY);
      ctx.lineTo(endX, endY);
      ctx.strokeStyle = gradient;
      ctx.lineWidth = (0.5 + distRatio * 2) * safeSize;
      ctx.stroke();

      ctx.beginPath();
      ctx.arc(endX, endY, 0.5 + distRatio * 1.5, 0, Math.PI * 2);
      ctx.fillStyle = `hsl(${head} / ${Math.min(1, p.alpha * 1.2)})`;
      ctx.fill();
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      const count =
        width < 768 ? scaleCount(150, safeDensity, 30) : scaleCount(400, safeDensity, 60);
      particles = Array.from({ length: count }, () => {
        const p = {
          angle: 0,
          speed: 0,
          distance: 0,
          maxLength: 0,
          length: 0,
          alpha: 0,
        };
        reset(p, true);
        return p;
      });
    };

    const frame = (s: number) => {
      ctx.clearRect(0, 0, width, height);
      particles.forEach((p) => {
        update(p, s);
        draw(p);
      });
    };

    let raf = 0;
    let inView = true;
    const loop = () => {
      frame(speedRef.current);
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (prefersReducedMotion) frame(0);
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) frame(0);
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
    };
  }, [tokens, safeSize, safeLength, safeDensity, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Wire Ledger

> Drifting points joined by hairlines when they come within reach, inked in your theme.

Install: `npx @modus-ui/cli add wire-ledger`

Points drift and bounce inside the frame and are joined by fine ink hairlines whenever they come within reach of each other, drawn from the theme's foreground and primary on the page ground. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add wire-ledger
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/wire-ledger.tsx`.
3. Paste the code.

## Usage

```tsx
import { WireLedger } from "@/components/ui/wire-ledger";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <WireLedger />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                  | Description                                         |
| :---------------- | :------- | :----------------------- | :-------------------------------------------------- |
| `speed`           | `number` | `1`                      | Animation speed multiplier (0–3).                   |
| `size`            | `number` | `1`                      | Stroke / scale multiplier.                          |
| `length`          | `number` | `1`                      | Length / reach multiplier (0.35–2.5).               |
| `density`         | `number` | `1`                      | Point count multiplier (0.25–2.5).                  |
| `opacity`         | `number` | `1`                      | Opacity of the effect layer (0.05–1).               |
| `hue`             | `number` | `0`                      | Hue rotation in degrees applied to the final frame. |
| `saturation`      | `number` | `1`                      | Saturation multiplier applied to the final frame.   |
| `brightness`      | `number` | `1`                      | Brightness multiplier applied to the final frame.   |
| `backgroundColor` | `string` | `hsl(var(--background))` | Colour behind the canvas, any CSS colour.           |

## Source

`components/ui/wire-ledger.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Interface Lines (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface WireLedgerProps {
  className?: string;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour behind the canvas; defaults to the theme background. */
  backgroundColor?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  return {
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(s)}%, ${Math.round(l)}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
const scaleCount = (base: number, density: number, minimum: number) =>
  Math.max(minimum, Math.round(base * density));

export function WireLedger({
  className,
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
}: WireLedgerProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const themeVersion = useThemeVersion();
  const safeSize = clamp(size, 0.05, 200);
  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    const link = Math.round(140 * safeLength);
    const theme = readTheme();
    const lineWidth = Number((1 * safeSize).toFixed(2));

    let width = 0;
    let height = 0;
    let particles: { x: number; y: number; vx: number; vy: number }[] = [];

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      ctx.imageSmoothingEnabled = false;
      const num = width < 640 ? scaleCount(22, safeDensity, 8) : scaleCount(46, safeDensity, 12);
      particles = Array.from({ length: num }, () => ({
        x: Math.random() * width,
        y: Math.random() * height,
        vx: (Math.random() - 0.5) * 0.5,
        vy: (Math.random() - 0.5) * 0.5,
      }));
    };

    const drawLines = (s: number) => {
      ctx.clearRect(0, 0, width, height);
      ctx.lineWidth = lineWidth;
      ctx.lineCap = "butt";
      ctx.lineJoin = "miter";

      for (let i = 0; i < particles.length; i++) {
        const p = particles[i];
        p.x += p.vx * s;
        p.y += p.vy * s;
        if (p.x < 0 || p.x > width) p.vx *= -1;
        if (p.y < 0 || p.y > height) p.vy *= -1;

        for (let j = i + 1; j < particles.length; j++) {
          const p2 = particles[j];
          const dx = p.x - p2.x;
          const dy = p.y - p2.y;
          const dist = Math.sqrt(dx * dx + dy * dy);
          if (dist < link) {
            // Elbow connectors: a circuit-like ledger rather than straight strands.
            const near = 1 - dist / link;
            ctx.beginPath();
            ctx.strokeStyle =
              near > 0.55
                ? hsl(theme.primary, 0.25 + near * 0.55)
                : hsl(theme.muted, 0.15 + near * 0.45);
            ctx.moveTo(p.x, p.y);
            ctx.lineTo(p2.x, p.y);
            ctx.lineTo(p2.x, p2.y);
            ctx.stroke();
          }
        }
      }
      for (const p of particles) {
        ctx.strokeStyle = hsl(theme.primary, 0.9);
        ctx.fillStyle = hsl(theme.border, 1);
        ctx.fillRect(p.x - 2.5, p.y - 2.5, 5, 5);
        ctx.strokeRect(p.x - 2.5, p.y - 2.5, 5, 5);
      }
    };

    let raf = 0;
    let inView = true;
    const loop = () => {
      drawLines(speedRef.current);
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (prefersReducedMotion) drawLines(0);
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) drawLines(0);
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
    };
  }, [themeVersion, safeSize, safeLength, safeDensity, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Rising Strokes

> Fine pen strokes rise through the frame, slowing, lengthening and taking the primary colour as they cross a low horizon.

Install: `npx @modus-ui/cli add rising-strokes`

Fine strokes rise through a 2D canvas with fading tails. As they cross a horizon line a little below the middle of the frame they slow, lengthen and switch from the muted ink colour to the primary colour. Colours and background come from the active theme, so it is ink on paper in light mode and follows the palette in dark mode. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add rising-strokes
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/rising-strokes.tsx`.
3. Paste the code.

## Usage

```tsx
import { RisingStrokes } from "@/components/ui/rising-strokes";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <RisingStrokes />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default        | Description                                             |
| :---------------- | :------- | :------------- | :------------------------------------------------------ |
| `speed`           | `number` | `1`            | Animation speed multiplier (0–3).                       |
| `size`            | `number` | `1`            | Stroke width multiplier (0.9px at 1).                   |
| `length`          | `number` | `1`            | Length / reach multiplier (0.35–2.5).                   |
| `density`         | `number` | `1`            | Streak count multiplier. (0.25–2.5).                    |
| `opacity`         | `number` | `1`            | Opacity of the effect layer (0.05–1).                   |
| `hue`             | `number` | `0`            | Hue rotation in degrees applied to the final frame.     |
| `saturation`      | `number` | `1`            | Saturation multiplier applied to the final frame.       |
| `brightness`      | `number` | `1`            | Brightness multiplier applied to the final frame.       |
| `backgroundColor` | `string` | `--background` | Background behind the strokes (theme token by default). |

## Source

`components/ui/rising-strokes.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Defense Lines (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

export interface RisingStrokesProps {
  className?: string;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Background behind the strokes. Defaults to the theme's `--background`. */
  backgroundColor?: string;
}

const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
/** `hsl(h, s%, l%)` with an alpha channel. */
const alpha = (color: string, a: number) =>
  color.replace(/^hsl\((.*)\)$/, `hsla($1, ${a.toFixed(3)})`);
const scaleCount = (base: number, density: number, minimum: number) =>
  Math.max(minimum, Math.round(base * density));

export function RisingStrokes({
  className,
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
}: RisingStrokesProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const tokens = useTokens();
  const ink = tokens?.primary;
  const thread = tokens?.muted;
  const safeSize = clamp(size, 0.05, 200);
  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx || !ink || !thread) return;

    const lineWidth = Number((0.9 * safeSize).toFixed(2));

    let width = 0;
    let height = 0;
    let particles: {
      x: number;
      y: number;
      baseLength: number;
      speedY: number;
      baseOpacity: number;
    }[] = [];

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      ctx.imageSmoothingEnabled = false;
      const count = width < 768 ? scaleCount(40, safeDensity, 8) : scaleCount(100, safeDensity, 16);
      particles = Array.from({ length: count }, () => ({
        x: Math.random() * width,
        y: Math.random() * height,
        baseLength: (Math.random() * 80 + 20) * safeLength,
        speedY: Math.random() * 0.8 + 0.2,
        baseOpacity: Math.random() * 0.2 + 0.05,
      }));
    };

    const frame = (s: number) => {
      ctx.clearRect(0, 0, width, height);
      // Strokes gather and brighten along a horizon line below the middle of the frame.
      const horizon = height * 0.62;
      ctx.lineCap = "butt";
      ctx.lineJoin = "miter";

      particles.forEach((p) => {
        const proximityY = Math.max(0, 1 - Math.abs(p.y - horizon) / (height * 0.45));
        const centerProximity = Math.pow(proximityY, 1.6);
        const currentLength = p.baseLength * (1 + centerProximity * 2.5);
        const currentOpacity = Math.min(1.0, p.baseOpacity * 2 + centerProximity * 1.2);
        const color = centerProximity > 0.45 ? ink : thread;

        ctx.beginPath();
        const grad = ctx.createLinearGradient(p.x, p.y, p.x, p.y + currentLength);
        grad.addColorStop(0, alpha(color, currentOpacity));
        grad.addColorStop(1, alpha(color, 0));
        ctx.strokeStyle = grad;
        ctx.lineWidth = lineWidth;
        ctx.moveTo(p.x, p.y);
        ctx.lineTo(p.x, p.y + currentLength);
        ctx.stroke();

        p.y -= p.speedY * 1.5 * (1 - centerProximity * 0.45) * s;
        if (p.y + currentLength < 0) {
          p.y = height;
          p.x = Math.random() * width;
        }
      });
    };

    let raf = 0;
    let inView = true;
    const loop = () => {
      frame(speedRef.current);
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (prefersReducedMotion) frame(0);
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) frame(0);
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
    };
  }, [ink, thread, safeSize, safeLength, safeDensity, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Contour Sheet

> A WebGL contour map drawn like a survey sheet: ink contours on paper, with every fifth index line in the theme primary.

Install: `npx @modus-ui/cli add contour-sheet`

A WebGL contour map drawn like a survey sheet: ink contours on paper, with every fifth index line in the theme primary. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add contour-sheet
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/contour-sheet.tsx`.
3. Paste the code.

## Usage

```tsx
import { ContourSheet } from "@/components/ui/contour-sheet";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ContourSheet />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default          | Description                                         |
| :---------------- | :------- | :--------------- | :-------------------------------------------------- |
| `speed`           | `number` | `0.7`            | Animation speed multiplier (0–3).                   |
| `length`          | `number` | `0.8`            | Length / reach multiplier (0.35–2.5).               |
| `density`         | `number` | `1.4`            | Contour band count multiplier (0.25–2.5).           |
| `opacity`         | `number` | `1`              | Opacity of the effect layer (0.05–1).               |
| `hue`             | `number` | `0`              | Hue rotation in degrees applied to the final frame. |
| `saturation`      | `number` | `1`              | Saturation multiplier applied to the final frame.   |
| `brightness`      | `number` | `1`              | Brightness multiplier applied to the final frame.   |
| `backgroundColor` | `string` | theme background | Paper colour.                                       |
| `lineColor`       | `string` | theme foreground | Contour ink.                                        |
| `accentColor`     | `string` | theme primary    | Colour of every fifth (index) contour.              |

## Source

`components/ui/contour-sheet.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Topo Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ContourSheetProps {
  className?: string;
  speed?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Paper colour. Defaults to the theme background. */
  backgroundColor?: string;
  /** Contour ink. Defaults to the theme foreground. */
  lineColor?: string;
  /** Colour of every fifth (index) contour. Defaults to the theme primary. */
  accentColor?: string;
}

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];

const clamp = (v: number, min: number, max: number) => Math.min(max, Math.max(min, v));
const glslFloat = (value: number, digits = 3) => {
  const fixed = Number(value).toFixed(digits);
  return fixed.includes(".") ? fixed : `${fixed}.0`;
};

const VERTEX = `
attribute vec2 a_position;
void main() { gl_Position = vec4(a_position, 0.0, 1.0); }
`;

function fragment(noiseScale: string, numBands: string) {
  return `
precision highp float;
uniform vec2 u_resolution;
uniform float u_time;
uniform float u_dpr;
uniform vec3 u_paper;
uniform vec3 u_ink;
uniform vec3 u_accent;
uniform vec3 u_grid;

vec3 permute(vec3 x) { return mod(((x*34.0)+1.0)*x, 289.0); }
float snoise(vec2 v){
  const vec4 C = vec4(0.211324865405187, 0.366025403784439, -0.577350269189626, 0.024390243902439);
  vec2 i  = floor(v + dot(v, C.yy) );
  vec2 x0 = v -   i + dot(i, C.xx);
  vec2 i1; i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
  vec4 x12 = x0.xyxy + C.xxzz; x12.xy -= i1;
  i = mod(i, 289.0);
  vec3 p = permute( permute( i.y + vec3(0.0, i1.y, 1.0 )) + i.x + vec3(0.0, i1.x, 1.0 ));
  vec3 m = max(0.5 - vec3(dot(x0,x0), dot(x12.xy,x12.xy), dot(x12.zw,x12.zw)), 0.0);
  m = m*m; m = m*m;
  vec3 x = 2.0 * fract(p * C.www) - 1.0;
  vec3 h = abs(x) - 0.5; vec3 ox = floor(x + 0.5);
  vec3 a0 = x - ox; m *= 1.79284291400159 - 0.85373472095314 * ( a0*a0 + h*h );
  vec3 g; g.x  = a0.x  * x0.x  + h.x  * x0.y; g.yz = a0.yz * x12.xz + h.yz * x12.yw;
  return 130.0 * dot(m, g);
}

void main() {
  vec2 st = gl_FragCoord.xy / u_resolution.xy;
  st.x *= u_resolution.x / u_resolution.y;

  // A survey grid of crosses rather than full rules.
  float gridSize = 64.0 * u_dpr;
  vec2 cell = abs(fract(gl_FragCoord.xy / gridSize + 0.5) - 0.5) * gridSize;
  float crossArm = 6.0 * u_dpr;
  float grid = (step(cell.x, 0.6 * u_dpr) * step(cell.y, crossArm)) +
    (step(cell.y, 0.6 * u_dpr) * step(cell.x, crossArm));
  grid = clamp(grid, 0.0, 1.0);

  float noiseScale = ${noiseScale};
  vec2 noisePos = st * noiseScale + vec2(u_time * 0.02, -u_time * 0.012);
  float n = snoise(noisePos) * 0.5 + 0.5;
  float numBands = ${numBands};
  float bandVal = n * numBands;
  float triangleWave = abs(fract(bandVal) - 0.5) * 2.0;

  // Every fifth contour is an index line: thicker and in the accent colour.
  float nearest = floor(bandVal + 0.5);
  bool isIndex = mod(nearest, 5.0) < 0.5;
  float width = isIndex ? 0.06 : 0.03;
  float contour = smoothstep(width, width * 0.25, triangleWave);

  vec3 color = mix(u_paper, u_grid, grid * 0.9);
  color = mix(color, isIndex ? u_accent : u_ink, contour * (isIndex ? 0.95 : 0.6));

  gl_FragColor = vec4(color, 1.0);
}
`;
}

export function ContourSheet({
  className,
  speed = 0.7,
  length = 0.8,
  density = 1.4,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
  lineColor,
  accentColor,
}: ContourSheetProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const gl = canvas?.getContext("webgl", {
      alpha: false,
      antialias: false,
      depth: false,
    });
    if (!host || !canvas || !gl || !theme) return;

    const compile = (type: number, source: string) => {
      const shader = gl.createShader(type)!;
      gl.shaderSource(shader, source);
      gl.compileShader(shader);
      return shader;
    };
    const vs = compile(gl.VERTEX_SHADER, VERTEX);
    const fs = compile(
      gl.FRAGMENT_SHADER,
      fragment(glslFloat(1.4 * safeLength, 3), glslFloat(10 * safeDensity, 2)),
    );
    const program = gl.createProgram()!;
    gl.attachShader(program, vs);
    gl.attachShader(program, fs);
    gl.linkProgram(program);
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), gl.STATIC_DRAW);
    const positionLocation = gl.getAttribLocation(program, "a_position");
    gl.enableVertexAttribArray(positionLocation);
    gl.vertexAttribPointer(positionLocation, 2, gl.FLOAT, false, 0, 0);

    const resolutionLocation = gl.getUniformLocation(program, "u_resolution");
    const timeLocation = gl.getUniformLocation(program, "u_time");
    const dprLocation = gl.getUniformLocation(program, "u_dpr");
    const paper = backgroundColor ? toRgb(backgroundColor) : theme.background;
    gl.uniform3fv(gl.getUniformLocation(program, "u_paper"), paper);
    gl.uniform3fv(
      gl.getUniformLocation(program, "u_ink"),
      lineColor ? toRgb(lineColor) : theme.foreground,
    );
    gl.uniform3fv(
      gl.getUniformLocation(program, "u_accent"),
      accentColor ? toRgb(accentColor) : theme.primary,
    );
    gl.uniform3fv(
      gl.getUniformLocation(program, "u_grid"),
      mix(paper, theme["muted-foreground"], 0.55),
    );

    let time = 0;
    const draw = () => {
      gl.uniform1f(timeLocation, time);
      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(rect.width * dpr));
      canvas.height = Math.max(1, Math.floor(rect.height * dpr));
      gl.viewport(0, 0, canvas.width, canvas.height);
      gl.uniform2f(resolutionLocation, canvas.width, canvas.height);
      gl.uniform1f(dprLocation, dpr);
      draw();
    };

    let raf = 0;
    let last = 0;
    let inView = true;
    const loop = (now: number) => {
      if (last) time += ((now - last) / 1000) * speedRef.current;
      last = now;
      draw();
      raf = requestAnimationFrame(loop);
    };
    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      last = 0;
      if (prefersReducedMotion) draw();
      else if (inView && !document.hidden) raf = requestAnimationFrame(loop);
    };

    resize();
    const ro = new ResizeObserver(resize);
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      inView = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
      gl.deleteBuffer(buffer);
      gl.deleteProgram(program);
      gl.deleteShader(vs);
      gl.deleteShader(fs);
    };
  }, [
    theme,
    backgroundColor,
    lineColor,
    accentColor,
    safeLength,
    safeDensity,
    prefersReducedMotion,
  ]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: backgroundColor ?? "hsl(var(--background))",
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Night Gate

> A serif link pill floating over a drifting field of ink specks and pulsing motes.

Install: `npx @modus-ui/cli add night-gate`

An italic serif link in a translucent pill with an inked arrow badge, floating over two canvas fields: a slow upward drift of ink specks and motes in the theme's primary and foreground colours that wander, bounce and pulse with a glow. Colours come from the theme tokens and are re-read when the theme or palette changes, so the field is ink on paper in light mode and light on dark in dark mode. It fills its positioned parent, pauses when off screen or the tab is hidden, and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add night-gate
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/night-gate.tsx`.
3. Paste the code.

## Usage

```tsx
import { NightGate } from "@/components/ui/night-gate";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <NightGate label="Begin the journey" href="/start" />
    </div>
  );
}
```

## Props

| Prop         | Type                                   | Default                                 | Description                                            |
| :----------- | :------------------------------------- | :-------------------------------------- | :----------------------------------------------------- |
| `label`      | `string`                               | `"Step inside"`                         | Button text.                                           |
| `hue`        | `number`                               | `0`                                     | Hue rotation in degrees (-180 to 180).                 |
| `saturation` | `number`                               | `1`                                     | Saturation multiplier (0 to 2).                        |
| `brightness` | `number`                               | `1`                                     | Brightness multiplier (0.35 to 1.65).                  |
| `starColors` | `string[]`                             | Theme primary, foreground and muted ink | CSS colours for the motes; alpha is applied per frame. |
| `href`       | `string`                               | `"#"`                                   | Link target. `"#"` does not navigate.                  |
| `onClick`    | `MouseEventHandler<HTMLAnchorElement>` | -                                       | Called when the link is clicked.                       |

## Source

`components/ui/night-gate.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Imaginie Star Portal (MIT, © 2026 Meng To).

import * as React from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface NightGateProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
  label?: string;
  hue?: number;
  saturation?: number;
  brightness?: number;
  starColors?: string[];
  className?: string;
}

/* Theme tokens are bare HSL channels, so wrap them for the canvas. */
const token = (name: string) =>
  `hsl(${getComputedStyle(document.documentElement).getPropertyValue(name).trim()})`;
const themeStarColors = () => [
  token("--primary"),
  token("--foreground"),
  token("--muted-foreground"),
  token("--primary"),
];

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

export function NightGate({
  label = "Step inside",
  hue = 0,
  saturation = 1,
  brightness = 1,
  starColors,
  className,
  onClick,
  href = "#",
  ...props
}: NightGateProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = React.useRef<HTMLDivElement>(null);
  const portalRef = React.useRef<HTMLCanvasElement>(null);
  const ambientRef = React.useRef<HTMLCanvasElement>(null);
  const colorsKey = starColors?.join("|") ?? "";

  React.useEffect(() => {
    const root = rootRef.current;
    const portalCanvas = portalRef.current;
    const ambientCanvas = ambientRef.current;
    if (!root || !portalCanvas || !ambientCanvas) return;
    const ctxPortal = portalCanvas.getContext("2d");
    const ctxAmbient = ambientCanvas.getContext("2d");
    if (!ctxPortal || !ctxAmbient) return;
    let colors = colorsKey ? colorsKey.split("|") : themeStarColors();
    let ink = token("--foreground");

    type Star = {
      x: number;
      y: number;
      radius: number;
      color: string;
      speed: number;
      angle: number;
      pulse: number;
    };
    type AmbientStar = {
      x: number;
      y: number;
      size: number;
      opacity: number;
      drift: number;
    };
    let stars: Star[] = [];
    let ambientStars: AmbientStar[] = [];
    let width = 0;
    let height = 0;

    const resize = () => {
      const rect = root.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      portalCanvas.width = width;
      portalCanvas.height = height;
      ambientCanvas.width = width;
      ambientCanvas.height = height;
      stars = [];
      for (let i = 0; i < 45; i++) {
        stars.push({
          x: Math.random() * width,
          y: Math.random() * height,
          radius: Math.random() * 1.5 + 0.5,
          color: colors[Math.floor(Math.random() * colors.length)],
          speed: Math.random() * 0.15 + 0.05,
          angle: Math.random() * Math.PI * 2,
          pulse: Math.random() * 0.02,
        });
      }
      ambientStars = [];
      for (let i = 0; i < 70; i++) {
        ambientStars.push({
          x: Math.random() * width,
          y: Math.random() * height,
          size: Math.random() * 0.8 + 0.2,
          opacity: Math.random() * 0.6 + 0.1,
          drift: Math.random() * 0.02 + 0.01,
        });
      }
    };

    const draw = (move: boolean) => {
      ctxPortal.clearRect(0, 0, width, height);
      stars.forEach((s) => {
        if (move) {
          s.x += Math.cos(s.angle) * s.speed;
          s.y += Math.sin(s.angle) * s.speed;
          if (s.x < 0 || s.x > width) s.angle = Math.PI - s.angle;
          if (s.y < 0 || s.y > height) s.angle = -s.angle;
          s.speed += (Math.random() - 0.5) * 0.01;
          s.speed = Math.max(0.02, Math.min(s.speed, 0.25));
        }
        ctxPortal.globalAlpha = 0.3 + Math.abs(Math.sin(Date.now() * s.pulse)) * 0.7;
        ctxPortal.beginPath();
        ctxPortal.arc(s.x, s.y, s.radius, 0, Math.PI * 2);
        ctxPortal.fillStyle = s.color;
        ctxPortal.shadowBlur = s.radius * 4;
        ctxPortal.shadowColor = s.color;
        ctxPortal.fill();
      });
      ctxPortal.globalAlpha = 1;
      ctxAmbient.clearRect(0, 0, width, height);
      ambientStars.forEach((s) => {
        if (move) {
          s.y -= s.drift;
          if (s.y < 0) s.y = height;
        }
        ctxAmbient.globalAlpha = s.opacity;
        ctxAmbient.fillStyle = ink;
        ctxAmbient.fillRect(s.x, s.y, s.size * 1.6, s.size * 1.6);
      });
      ctxAmbient.globalAlpha = 1;
    };

    resize();
    draw(false);

    const themeObserver = new MutationObserver(() => {
      if (!colorsKey) colors = themeStarColors();
      ink = token("--foreground");
      stars.forEach((star) => {
        star.color = colors[Math.floor(Math.random() * colors.length)];
      });
      draw(false);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });

    let raf = 0;
    let visible = true;
    const loop = () => {
      draw(true);
      raf = requestAnimationFrame(loop);
    };
    const update = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (!prefersReducedMotion && visible && !document.hidden) {
        raf = requestAnimationFrame(loop);
      }
    };
    const ro = new ResizeObserver(() => {
      resize();
      draw(false);
    });
    ro.observe(root);
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      update();
    });
    io.observe(root);
    document.addEventListener("visibilitychange", update);
    update();
    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", update);
    };
  }, [prefersReducedMotion, colorsKey]);

  const h = clamp(hue, -180, 180);
  const sat = clamp(saturation, 0, 2);
  const bri = clamp(brightness, 0.35, 1.65);
  const filter =
    h === 0 && sat === 1 && bri === 1
      ? undefined
      : `hue-rotate(${h}deg) saturate(${sat}) brightness(${bri})`;

  return (
    <div
      ref={rootRef}
      className={cn(
        "relative flex h-full min-h-[inherit] w-full items-center justify-center overflow-hidden",
        className,
      )}
      style={{ filter }}
    >
      <canvas
        ref={ambientRef}
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 z-0 h-full w-full"
      />
      <canvas
        ref={portalRef}
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 z-0 h-full w-full"
      />
      <a
        href={href}
        onClick={(event) => {
          if (href === "#") event.preventDefault();
          onClick?.(event);
        }}
        className="relative z-[2] flex items-center gap-3 rounded-full border border-[hsl(var(--primary)/0.4)] bg-[hsl(var(--background)/0.7)] py-3 pl-6 pr-3 font-serif text-[17px] italic text-foreground antialiased shadow-[0_0_0_6px_hsl(var(--primary)/0.06)] backdrop-blur-sm transition-all duration-[400ms] ease-[ease] hover:shadow-[0_0_0_10px_hsl(var(--primary)/0.1)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[hsl(var(--primary))]"
        {...props}
      >
        {label}
        <span className="grid h-7 w-7 place-items-center rounded-full bg-[hsl(var(--primary))] text-[hsl(var(--primary-foreground))]">
          <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24">
            <path
              fill="none"
              stroke="currentColor"
              strokeLinecap="round"
              strokeLinejoin="round"
              strokeWidth="1.5"
              d="M4 12h16m0 0l-6-6m6 6l-6 6"
            />
          </svg>
        </span>
      </a>
    </div>
  );
}
```

---

# Starstream Button

> A WebGL pill whose face carries a sideways stream of stars that stretches into streaks on hover.

Install: `npx @modus-ui/cli add starstream-button`

A raw-WebGL pill on a drifting paper field. Inside its primary-tinted face, layers of stars stream sideways; hovering or focusing stretches them into long streaks and clicking washes the face with the page colour. Colours come from the theme tokens and update when the theme or palette changes. It fills its positioned parent, pauses when off screen or when the tab is hidden, and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add starstream-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/starstream-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { StarstreamButton } from "@/components/ui/starstream-button";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <StarstreamButton />
    </div>
  );
}
```

## Props

| Prop           | Type                                   | Default    | Description                                       |
| :------------- | :------------------------------------- | :--------- | :------------------------------------------------ |
| `label`        | `string`                               | `"Engage"` | Button text.                                      |
| `onClick`      | `ButtonHTMLAttributes["onClick"]`      | -          | Called after the button's own click effect.       |
| `onMouseEnter` | `ButtonHTMLAttributes["onMouseEnter"]` | -          | Called after the button's own mouse enter effect. |
| `onMouseLeave` | `ButtonHTMLAttributes["onMouseLeave"]` | -          | Called after the button's own mouse leave effect. |
| `onFocus`      | `ButtonHTMLAttributes["onFocus"]`      | -          | Called after the button's own focus effect.       |
| `onBlur`       | `ButtonHTMLAttributes["onBlur"]`       | -          | Called after the button's own blur effect.        |

Any other `<button>` attribute is passed through to the inner button.

## Source

`components/ui/starstream-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Ignition Button (MIT, © 2026 Meng To).

import { useEffect, useRef, type ButtonHTMLAttributes } from "react";
import { useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

const VS = "attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}";

const BG_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform vec3 u_paper;
uniform vec3 u_ink;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
void main(){
  vec2 uv = gl_FragCoord.xy / u_res;
  float n = noise(uv * vec2(1.2, 6.0) + vec2(u_time * 0.04, 0.0));
  n += noise(uv * vec2(2.5, 12.0) - vec2(u_time * 0.03, 0.0)) * 0.5;
  float lane = exp(-pow((uv.y - 0.5) * 3.2, 2.0));
  vec3 col = mix(u_paper, u_ink, (n * 0.05 + 0.02) * lane);
  gl_FragColor = vec4(col, 1.0);
}
`;

const BTN_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform float u_warp;
uniform float u_flash;
uniform vec3 u_ink;
uniform vec3 u_paper;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
void main(){
  vec2 sc = gl_FragCoord.xy / u_res;
  vec2 uv = (gl_FragCoord.xy - 0.5 * u_res) / u_res.y;
  float t = u_time;
  // Keep the field dark in both themes so the white label stays legible.
  vec3 deep = u_ink * 0.06;
  vec3 col = deep + u_ink * 0.06 * noise(uv * vec2(1.5, 5.0) + vec2(t * 0.3, 0.0));
  vec3 star = mix(u_ink, vec3(1.0), 0.72);
  for (int i = 0; i < 3; i++) {
    float fi = float(i);
    float rows = 9.0 + fi * 5.0;
    vec2 sp = vec2(uv.x * (6.0 + fi * 3.0) - t * (3.0 + fi * 1.6), uv.y * rows);
    vec2 cell = floor(sp);
    vec2 f = fract(sp);
    float h = hash(cell + fi * 17.31);
    float on = step(0.62, h);
    vec2 c = vec2(0.5, 0.25 + 0.5 * hash(cell + 4.7));
    vec2 d = f - c;
    float sx = mix(90.0, 3.0, u_warp);
    float s = on * exp(-(d.x * d.x * sx + d.y * d.y * 260.0));
    float tw = mix(0.65 + 0.35 * sin(h * 81.0 + t * 7.0), 1.0, u_warp);
    col += star * s * tw * (0.5 + 0.7 * u_warp) * (0.4 + fi * 0.2);
  }
  col += star * u_warp * 0.18 * exp(-abs(uv.y) * 6.0);
  vec2 e = sc * (1.0 - sc);
  col *= 0.45 + 0.55 * pow(e.x * e.y * 16.0, 0.25);
  // The flash lifts the field toward the star tone but keeps it dark under the light label.
  col = mix(col, mix(col, star, 0.35), clamp(u_flash, 0.0, 1.0));
  gl_FragColor = vec4(col, 1.0);
}
`;

/** Resolve a bare-HSL theme token (e.g. `--primary`) to linear 0..1 RGB. */
function readToken(name: string): [number, number, number] {
  const probe = document.createElement("span");
  probe.style.color = `hsl(${getComputedStyle(document.documentElement).getPropertyValue(name).trim()})`;
  document.body.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return [Number(m[0]) / 255, Number(m[1]) / 255, Number(m[2]) / 255];
}

function createProgram(gl: WebGLRenderingContext, fs: string) {
  const compile = (type: number, src: string) => {
    const s = gl.createShader(type)!;
    gl.shaderSource(s, src);
    gl.compileShader(s);
    return s;
  };
  const prog = gl.createProgram()!;
  gl.attachShader(prog, compile(gl.VERTEX_SHADER, VS));
  gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
  gl.linkProgram(prog);
  gl.useProgram(prog);
  const buf = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buf);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const locP = gl.getAttribLocation(prog, "p");
  gl.enableVertexAttribArray(locP);
  gl.vertexAttribPointer(locP, 2, gl.FLOAT, false, 0, 0);
  return prog;
}

function resizeCanvas(gl: WebGLRenderingContext, canvas: HTMLCanvasElement) {
  const dpr = Math.min(window.devicePixelRatio || 1, 2);
  const w = Math.max(1, Math.round(canvas.clientWidth * dpr));
  const h = Math.max(1, Math.round(canvas.clientHeight * dpr));
  if (canvas.width !== w || canvas.height !== h) {
    canvas.width = w;
    canvas.height = h;
    gl.viewport(0, 0, w, h);
  }
}

export interface StarstreamButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /** Button label. */
  label?: string;
}

export function StarstreamButton({
  label = "Engage",
  className,
  onClick,
  onMouseEnter,
  onMouseLeave,
  onFocus,
  onBlur,
  ...props
}: StarstreamButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const bgRef = useRef<HTMLCanvasElement>(null);
  const glRef = useRef<HTMLCanvasElement>(null);
  const state = useRef({ warp: 0, warpTarget: 0, flash: 0, z: 0 });

  useEffect(() => {
    const root = rootRef.current;
    const bgCanvas = bgRef.current;
    const btnCanvas = glRef.current;
    if (!root || !bgCanvas || !btnCanvas) return;
    const bg = bgCanvas.getContext("webgl");
    const gl = btnCanvas.getContext("webgl");
    if (!bg || !gl) return;
    const bgProg = createProgram(bg, BG_FS);
    const btnProg = createProgram(gl, BTN_FS);
    const bgRes = bg.getUniformLocation(bgProg, "u_res");
    const bgTime = bg.getUniformLocation(bgProg, "u_time");
    const uRes = gl.getUniformLocation(btnProg, "u_res");
    const uTime = gl.getUniformLocation(btnProg, "u_time");
    const uWarp = gl.getUniformLocation(btnProg, "u_warp");
    const uFlash = gl.getUniformLocation(btnProg, "u_flash");
    const bgPaper = bg.getUniformLocation(bgProg, "u_paper");
    const bgInk = bg.getUniformLocation(bgProg, "u_ink");
    const uInk = gl.getUniformLocation(btnProg, "u_ink");
    const uPaper = gl.getUniformLocation(btnProg, "u_paper");
    const applyTheme = () => {
      const ink = readToken("--primary");
      const paper = readToken("--background");
      bg.useProgram(bgProg);
      bg.uniform3fv(bgPaper, paper);
      bg.uniform3fv(bgInk, readToken("--foreground"));
      gl.useProgram(btnProg);
      gl.uniform3fv(uInk, ink);
      gl.uniform3fv(uPaper, paper);
    };
    applyTheme();
    const themeObserver = new MutationObserver(() => {
      applyTheme();
      last = performance.now();
      frame(last);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "style"],
    });
    const s = state.current;

    let raf = 0;
    let visible = true;
    let last = performance.now();

    const frame = (now: number) => {
      const dt = Math.min(0.05, (now - last) / 1000);
      last = now;
      s.warp += (s.warpTarget - s.warp) * Math.min(1, dt * 2.6);
      s.flash *= Math.exp(-4.5 * dt);
      s.z += dt * (0.05 + s.warp * 1.35);
      resizeCanvas(bg, bgCanvas);
      bg.uniform2f(bgRes, bgCanvas.width, bgCanvas.height);
      bg.uniform1f(bgTime, prefersReducedMotion ? 0 : now / 1000);
      bg.drawArrays(bg.TRIANGLES, 0, 3);
      resizeCanvas(gl, btnCanvas);
      gl.uniform2f(uRes, btnCanvas.width, btnCanvas.height);
      gl.uniform1f(uTime, prefersReducedMotion ? 4.0 : s.z);
      gl.uniform1f(uWarp, s.warp);
      gl.uniform1f(uFlash, s.flash);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    };
    const loop = (now: number) => {
      frame(now);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(raf);
      if (!visible || document.hidden) return;
      last = performance.now();
      if (prefersReducedMotion) {
        // still frame, redrawn while hover/flash eases
        const settle = (now: number) => {
          frame(now);
          if (Math.abs(s.warpTarget - s.warp) > 0.002 || s.flash > 0.002)
            raf = requestAnimationFrame(settle);
          else raf = requestAnimationFrame(idle);
        };
        const idle = () => {
          if (Math.abs(s.warpTarget - s.warp) > 0.002 || s.flash > 0.002) {
            last = performance.now();
            raf = requestAnimationFrame(settle);
          } else raf = requestAnimationFrame(idle);
        };
        raf = requestAnimationFrame(settle);
      } else raf = requestAnimationFrame(loop);
    };
    const io = new IntersectionObserver(([e]) => {
      visible = e?.isIntersecting ?? true;
      start();
    });
    io.observe(root);
    const onVis = () => start();
    document.addEventListener("visibilitychange", onVis);
    start();
    return () => {
      cancelAnimationFrame(raf);
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVis);
      bg.deleteProgram(bgProg);
      gl.deleteProgram(btnProg);
    };
  }, [prefersReducedMotion]);

  return (
    <div
      ref={rootRef}
      className={cn(
        "absolute inset-0 flex items-center justify-center overflow-hidden bg-background",
        className,
      )}
    >
      <canvas
        ref={bgRef}
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 block h-full w-full"
      />
      <button
        type="button"
        {...props}
        onMouseEnter={(e) => {
          state.current.warpTarget = 1;
          onMouseEnter?.(e);
        }}
        onMouseLeave={(e) => {
          state.current.warpTarget = 0;
          onMouseLeave?.(e);
        }}
        onFocus={(e) => {
          state.current.warpTarget = 1;
          onFocus?.(e);
        }}
        onBlur={(e) => {
          state.current.warpTarget = 0;
          onBlur?.(e);
        }}
        onClick={(e) => {
          state.current.flash = 1;
          state.current.warp = 0;
          state.current.z = 0;
          onClick?.(e);
        }}
        className="relative z-[2] block h-[64px] w-[300px] flex-none cursor-pointer rounded-full border border-[hsl(var(--border))] bg-card p-[5px] shadow-[0_22px_44px_-18px_hsl(var(--foreground)/0.55)] outline-none transition-all duration-300 ease-[cubic-bezier(.34,1.4,.5,1)] hover:shadow-[0_28px_56px_-16px_hsl(var(--primary)/0.6)] focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-4 focus-visible:ring-offset-background"
      >
        <span className="relative flex h-full w-full items-center justify-between overflow-hidden rounded-full bg-[hsl(var(--primary))] px-6 shadow-[inset_0_2px_8px_rgb(0_0_0/0.6)]">
          <canvas ref={glRef} aria-hidden="true" className="absolute inset-0 block h-full w-full" />
          <span
            className="pointer-events-none relative z-10 font-serif text-lg italic text-white"
            style={{ textShadow: "0 1px 8px rgb(0 0 0 / 0.7)" }}
          >
            {label}
          </span>
          <span className="pointer-events-none relative z-10 font-mono text-[10px] uppercase tracking-[0.24em] text-white/70">
            →→
          </span>
        </span>
      </button>
    </div>
  );
}
```

---

# Arc Halo Button

> A WebGL card button traced by crawling ink arcs that multiply on hover and discharge on click.

Install: `npx @modus-ui/cli add arc-halo-button`

A raw-WebGL card-toned plate on a dotted paper field, its rounded edge traced by noisy arcs drawn in the theme's primary ink. Hover adds more arcs and clicking sends a discharge around the edge. Colours come from the theme tokens and update when the theme or palette changes. It fills its positioned parent, pauses when off screen or when the tab is hidden, and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add arc-halo-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/arc-halo-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { ArcHaloButton } from "@/components/ui/arc-halo-button";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <ArcHaloButton />
    </div>
  );
}
```

## Props

| Prop           | Type                                   | Default              | Description                                       |
| :------------- | :------------------------------------- | :------------------- | :------------------------------------------------ |
| `label`        | `string`                               | `"Charge the field"` | Button text.                                      |
| `onClick`      | `ButtonHTMLAttributes["onClick"]`      | -                    | Called after the button's own click effect.       |
| `onMouseEnter` | `ButtonHTMLAttributes["onMouseEnter"]` | -                    | Called after the button's own mouse enter effect. |
| `onMouseLeave` | `ButtonHTMLAttributes["onMouseLeave"]` | -                    | Called after the button's own mouse leave effect. |
| `onFocus`      | `ButtonHTMLAttributes["onFocus"]`      | -                    | Called after the button's own focus effect.       |
| `onBlur`       | `ButtonHTMLAttributes["onBlur"]`       | -                    | Called after the button's own blur effect.        |

Any other `<button>` attribute is passed through to the inner button.

## Source

`components/ui/arc-halo-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Induction Button (MIT, © 2026 Meng To).

import { useEffect, useRef, type ButtonHTMLAttributes } from "react";
import { useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

const VS = "attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}";

const BG_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform vec3 u_paper;
uniform vec3 u_ink;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
void main(){
  vec2 uv = gl_FragCoord.xy / u_res.y;
  float t = u_time * 0.1;
  float n = noise(uv * 2.0 + vec2(t, -t * 0.6));
  vec2 dots = fract(uv * 28.0) - 0.5;
  float dot = 1.0 - smoothstep(0.05, 0.09, length(dots));
  vec3 col = mix(u_paper, u_ink, dot * (0.06 + 0.1 * n));
  gl_FragColor = vec4(col, 1.0);
}
`;

const BTN_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform float u_arcs;
uniform float u_flash;
uniform vec3 u_ink;
uniform vec3 u_card;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
float fbm(vec2 p){
  float v=0.0; float a=0.5;
  for(int i=0;i<4;i++){ v+=a*noise(p); p=p*2.05+vec2(9.7,3.1); a*=0.5; }
  return v;
}
float sdRBox(vec2 p, vec2 b, float r){
  vec2 q = abs(p) - b + r;
  return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - r;
}
void main(){
  vec2 p = (gl_FragCoord.xy - 0.5 * u_res) / u_res.y;
  float ar = u_res.x / u_res.y;
  vec2 hs = vec2(ar * 0.5 - 0.2, 0.5 - 0.2);
  float d = sdRBox(p, hs, 0.14);
  float t = u_time;
  float hover = clamp(u_arcs / 6.0, 0.0, 1.0);
  // Premultiplied output: everything outside the plate stays transparent so
  // the dotted field shows through instead of a flat rectangle.
  float plate = 1.0 - smoothstep(-0.004, 0.004, d);
  vec3 plateCol = u_card * (0.94 + 0.08 * fbm(p * 9.0));
  plateCol = mix(plateCol, u_ink, exp(d * 9.0) * (0.12 + hover * 0.25));
  vec3 col = plateCol * plate;
  float alpha = plate;

  float a = atan(p.y, p.x);
  vec3 arcCol = vec3(0.0);
  for (int i = 0; i < 6; i++) {
    float fi = float(i);
    float w = clamp(u_arcs - fi, 0.0, 1.0);
    float n1 = fbm(vec2(a * 2.4 + fi * 11.3, t * (1.6 + fi * 0.27) + fi * 53.1));
    float off = (n1 - 0.5) * (0.11 + u_flash * 0.1);
    float seg = smoothstep(0.35, 0.75, noise(vec2(a * 1.8 + fi * 7.7, t * (0.9 + fi * 0.13) + fi * 19.0)));
    seg = 0.3 + 0.7 * seg;
    float g = 0.0026 / (abs(d + off) + 0.005);
    arcCol += min(g, 1.0) * w * seg;
  }
  float outerMask = 1.0 - smoothstep(0.04, 0.15, d);
  float ink = clamp(arcCol.x * (0.55 + 0.45 * hover), 0.0, 1.0) * outerMask;
  col = col * (1.0 - ink) + u_ink * ink;
  alpha = alpha * (1.0 - ink) + ink;
  float ring = 0.006 / (abs(d) + 0.006);
  float flash = clamp(ring * u_flash, 0.0, 1.0) * outerMask;
  col = col * (1.0 - flash) + u_ink * flash;
  alpha = alpha * (1.0 - flash) + flash;
  gl_FragColor = vec4(col, alpha);
}
`;

/** Resolve a bare-HSL theme token (e.g. `--primary`) to 0..1 RGB. */
function readToken(name: string): [number, number, number] {
  const probe = document.createElement("span");
  probe.style.color = `hsl(${getComputedStyle(document.documentElement).getPropertyValue(name).trim()})`;
  document.body.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return [Number(m[0]) / 255, Number(m[1]) / 255, Number(m[2]) / 255];
}

function createProgram(gl: WebGLRenderingContext, fs: string) {
  const compile = (type: number, src: string) => {
    const s = gl.createShader(type)!;
    gl.shaderSource(s, src);
    gl.compileShader(s);
    return s;
  };
  const prog = gl.createProgram()!;
  gl.attachShader(prog, compile(gl.VERTEX_SHADER, VS));
  gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
  gl.linkProgram(prog);
  gl.useProgram(prog);
  const buf = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buf);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const locP = gl.getAttribLocation(prog, "p");
  gl.enableVertexAttribArray(locP);
  gl.vertexAttribPointer(locP, 2, gl.FLOAT, false, 0, 0);
  return prog;
}

function resizeCanvas(gl: WebGLRenderingContext, canvas: HTMLCanvasElement) {
  const dpr = Math.min(window.devicePixelRatio || 1, 2);
  const w = Math.max(1, Math.round(canvas.clientWidth * dpr));
  const h = Math.max(1, Math.round(canvas.clientHeight * dpr));
  if (canvas.width !== w || canvas.height !== h) {
    canvas.width = w;
    canvas.height = h;
    gl.viewport(0, 0, w, h);
  }
}

export interface ArcHaloButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /** Button label. */
  label?: string;
}

export function ArcHaloButton({
  label = "Charge the field",
  className,
  onClick,
  onMouseEnter,
  onMouseLeave,
  onFocus,
  onBlur,
  ...props
}: ArcHaloButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const bgRef = useRef<HTMLCanvasElement>(null);
  const glRef = useRef<HTMLCanvasElement>(null);
  const state = useRef({ arcs: 2.4, arcsTarget: 2.4, flash: 0, crawl: 0 });

  useEffect(() => {
    const root = rootRef.current;
    const bgCanvas = bgRef.current;
    const btnCanvas = glRef.current;
    if (!root || !bgCanvas || !btnCanvas) return;
    const bg = bgCanvas.getContext("webgl", { alpha: false, antialias: false });
    const gl = btnCanvas.getContext("webgl", { alpha: true, antialias: true });
    if (!bg || !gl) return;
    const bgProg = createProgram(bg, BG_FS);
    const btnProg = createProgram(gl, BTN_FS);
    const bgRes = bg.getUniformLocation(bgProg, "u_res");
    const bgTime = bg.getUniformLocation(bgProg, "u_time");
    const uRes = gl.getUniformLocation(btnProg, "u_res");
    const uTime = gl.getUniformLocation(btnProg, "u_time");
    const uArcs = gl.getUniformLocation(btnProg, "u_arcs");
    const uFlash = gl.getUniformLocation(btnProg, "u_flash");
    const bgPaper = bg.getUniformLocation(bgProg, "u_paper");
    const bgInk = bg.getUniformLocation(bgProg, "u_ink");
    const uInk = gl.getUniformLocation(btnProg, "u_ink");
    const uCard = gl.getUniformLocation(btnProg, "u_card");
    const applyTheme = () => {
      const paper = readToken("--background");
      bg.useProgram(bgProg);
      bg.uniform3fv(bgPaper, paper);
      bg.uniform3fv(bgInk, readToken("--foreground"));
      gl.useProgram(btnProg);
      gl.uniform3fv(uInk, readToken("--primary"));
      gl.uniform3fv(uCard, readToken("--card"));
    };
    applyTheme();
    const themeObserver = new MutationObserver(() => {
      applyTheme();
      last = performance.now();
      frame(last);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "style"],
    });
    const s = state.current;

    let raf = 0;
    let visible = true;
    let last = performance.now();

    const frame = (now: number) => {
      const dt = Math.min(0.05, (now - last) / 1000);
      last = now;
      s.arcs += (s.arcsTarget - s.arcs) * Math.min(1, dt * 5);
      s.flash *= Math.exp(-3.6 * dt);
      s.crawl += dt * (0.6 + (s.arcs / 6) * 1.1 + s.flash * 2.0);
      resizeCanvas(bg, bgCanvas);
      bg.uniform2f(bgRes, bgCanvas.width, bgCanvas.height);
      bg.uniform1f(bgTime, prefersReducedMotion ? 0 : now / 1000);
      bg.drawArrays(bg.TRIANGLES, 0, 3);
      resizeCanvas(gl, btnCanvas);
      gl.uniform2f(uRes, btnCanvas.width, btnCanvas.height);
      gl.uniform1f(uTime, prefersReducedMotion ? 3.0 : s.crawl);
      gl.uniform1f(uArcs, s.arcs);
      gl.uniform1f(uFlash, s.flash);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    };
    const loop = (now: number) => {
      frame(now);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(raf);
      if (!visible || document.hidden) return;
      last = performance.now();
      if (prefersReducedMotion) {
        // still frame, redrawn while hover/flash eases
        const settle = (now: number) => {
          frame(now);
          if (Math.abs(s.arcsTarget - s.arcs) > 0.002 || s.flash > 0.002)
            raf = requestAnimationFrame(settle);
          else raf = requestAnimationFrame(idle);
        };
        const idle = () => {
          if (Math.abs(s.arcsTarget - s.arcs) > 0.002 || s.flash > 0.002) {
            last = performance.now();
            raf = requestAnimationFrame(settle);
          } else raf = requestAnimationFrame(idle);
        };
        raf = requestAnimationFrame(settle);
      } else raf = requestAnimationFrame(loop);
    };
    const io = new IntersectionObserver(([e]) => {
      visible = e?.isIntersecting ?? true;
      start();
    });
    io.observe(root);
    const onVis = () => start();
    document.addEventListener("visibilitychange", onVis);
    start();
    return () => {
      cancelAnimationFrame(raf);
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVis);
      bg.deleteProgram(bgProg);
      gl.deleteProgram(btnProg);
    };
  }, [prefersReducedMotion]);

  return (
    <div
      ref={rootRef}
      className={cn(
        "absolute inset-0 flex items-center justify-center overflow-hidden bg-background",
        className,
      )}
    >
      <canvas
        ref={bgRef}
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 block h-full w-full"
      />
      <button
        type="button"
        {...props}
        onMouseEnter={(e) => {
          state.current.arcsTarget = 5.8;
          onMouseEnter?.(e);
        }}
        onMouseLeave={(e) => {
          state.current.arcsTarget = 2.4;
          onMouseLeave?.(e);
        }}
        onFocus={(e) => {
          state.current.arcsTarget = 5.8;
          onFocus?.(e);
        }}
        onBlur={(e) => {
          state.current.arcsTarget = 2.4;
          onBlur?.(e);
        }}
        onClick={(e) => {
          state.current.flash = 1;
          onClick?.(e);
        }}
        className="group relative z-[2] flex h-[96px] w-[280px] flex-none cursor-pointer items-center justify-center rounded-[18px] bg-transparent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-2 focus-visible:ring-offset-background"
      >
        <canvas
          ref={glRef}
          aria-hidden="true"
          className="absolute inset-0 block h-full w-full rounded-[18px]"
        />
        <span className="pointer-events-none relative z-10 font-serif text-xl text-foreground">
          {label}
        </span>
      </button>
    </div>
  );
}
```

---

# Current Button

> A WebGL pill filled with a slow ink current that quickens on hover and flares on press.

Install: `npx @modus-ui/cli add current-button`

A raw-WebGL pill filled with a domain-warped current of ink, drawn from the theme's primary, foreground and background colours, over a faint paper-grain field. Hover quickens the current and pressing the button flares it toward the paper colour. The label is set in uppercase mono. Colours are re-read when the theme or palette changes, so it sits on paper in light mode and on the dark ground in dark mode. It fills its positioned parent, pauses when off screen or when the tab is hidden, and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add current-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/current-button.tsx`.
3. Paste the code.

## Usage

```tsx
import { CurrentButton } from "@/components/ui/current-button";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <CurrentButton />
    </div>
  );
}
```

## Props

| Prop           | Type                                   | Default           | Description                                       |
| :------------- | :------------------------------------- | :---------------- | :------------------------------------------------ |
| `label`        | `string`                               | `"Run the draft"` | Button text.                                      |
| `hue`          | `number`                               | `0`               | Hue rotation in degrees (-180 to 180).            |
| `saturation`   | `number`                               | `1`               | Saturation multiplier (0 to 2).                   |
| `brightness`   | `number`                               | `1`               | Brightness multiplier (0.35 to 1.65).             |
| `onMouseDown`  | `ButtonHTMLAttributes["onMouseDown"]`  | -                 | Called after the button's own mouse down effect.  |
| `onKeyDown`    | `ButtonHTMLAttributes["onKeyDown"]`    | -                 | Called after the button's own key down effect.    |
| `onMouseEnter` | `ButtonHTMLAttributes["onMouseEnter"]` | -                 | Called after the button's own mouse enter effect. |
| `onMouseLeave` | `ButtonHTMLAttributes["onMouseLeave"]` | -                 | Called after the button's own mouse leave effect. |
| `onFocus`      | `ButtonHTMLAttributes["onFocus"]`      | -                 | Called after the button's own focus effect.       |
| `onBlur`       | `ButtonHTMLAttributes["onBlur"]`       | -                 | Called after the button's own blur effect.        |

Any other `<button>` attribute is passed through to the inner button.

## Source

`components/ui/current-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Plasma Button (MIT, © 2026 Meng To).

import { useEffect, useRef, useState, type ButtonHTMLAttributes } from "react";
import { useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

const VS = "attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}";

const BG_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform vec3 u_c1;
uniform vec3 u_c2;
uniform vec3 u_c3;
uniform vec3 u_c4;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
float fbm(vec2 p){
  float v=0.0; float a=0.5;
  for(int i=0;i<5;i++){ v+=a*noise(p); p=p*2.02+vec2(17.3,9.1); a*=0.5; }
  return v;
}
void main(){
  vec2 uv = gl_FragCoord.xy / u_res;
  vec2 p = uv * vec2(u_res.x/u_res.y, 1.0) * 1.5;
  float t = u_time * 0.12;
  vec2 q = vec2(fbm(p + vec2(0.0, t*0.28)), fbm(p + vec2(4.1, t*0.23)));
  vec2 r = vec2(fbm(p + 1.5*q + vec2(2.1, 7.2) + t*0.1),
                fbm(p + 1.4*q + vec2(5.3, 3.1) + t*0.07));
  float v = fbm(p + 1.9*r);
  float m = v*1.3;
  vec3 col = mix(u_c1, mix(u_c1, u_c2, 0.025), smoothstep(0.1, 0.6, m));
  col = mix(col, mix(u_c1, u_c2, 0.05), smoothstep(0.6, 1.0, m));
  float vein = exp(-abs(q.x - q.y) * 5.0);
  col = mix(col, u_c2, vein * 0.025);
  gl_FragColor = vec4(col, 1.0);
}
`;

const BTN_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform float u_heat;
uniform float u_flash;
uniform vec3 u_c1;
uniform vec3 u_c2;
uniform vec3 u_c3;
uniform vec3 u_c4;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
float fbm(vec2 p){
  float v=0.0; float a=0.5;
  for(int i=0;i<5;i++){ v+=a*noise(p); p=p*2.02+vec2(17.3,9.1); a*=0.5; }
  return v;
}
void main(){
  vec2 uv = gl_FragCoord.xy / u_res;
  vec2 p = uv * vec2(u_res.x/u_res.y, 1.0) * 2.1;
  float t = u_time;
  float heat = u_heat + u_flash * 1.3;
  vec2 q = vec2(fbm(p + vec2(0.0, t*0.32)), fbm(p + vec2(5.2, t*0.27)));
  vec2 r = vec2(fbm(p + 1.7*q + vec2(1.7, 9.2) + t*0.12),
                fbm(p + 1.6*q + vec2(8.3, 2.8) + t*0.09));
  float v = fbm(p + 2.1*r);
  float m = v*1.4 + heat*0.22;
  vec3 c1 = u_c1; vec3 c2 = u_c2; vec3 c3 = u_c3; vec3 c4 = u_c4;
  vec3 col = mix(c1, c2, smoothstep(0.2, 0.52, m));
  col = mix(col, c3, smoothstep(0.52, 0.8, m));
  col = mix(col, c4, smoothstep(0.82, 1.02, m));
  float vein = exp(-abs(q.x - q.y) * 9.0);
  col += c3 * vein * (0.12 + heat * 0.25);
  vec2 e = uv * (1.0 - uv);
  float vig = pow(e.x * e.y * 16.0, 0.28);
  col = mix(c1, col, mix(0.55, 1.0, vig));
  col = mix(col, c4, u_flash * 0.35 * (0.3 + v));
  gl_FragColor = vec4(col, 1.0);
}
`;

/* Theme tokens are bare HSL channels ("222 47% 11%"); convert to linear-ish RGB for the shaders. */
type Rgb = [number, number, number];
function readToken(name: string): Rgb {
  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  const [h = 0, sat = 0, lig = 0] = raw.split(/[\s,/]+/).map((v) => parseFloat(v));
  const s = sat / 100;
  const l = lig / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = s * Math.min(l, 1 - l);
  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}
const mixRgb = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];
/* Field: paper + ink. Button ramp: deep ink -> primary -> a pale wash -> the paper itself. */
function themeRamp() {
  const primary = readToken("--primary");
  const paper = readToken("--background");
  const ink = readToken("--foreground");
  const deep = mixRgb(primary, ink, 0.35);
  return {
    field: [paper, ink] as Rgb[],
    button: [deep, primary, mixRgb(primary, paper, 0.22), mixRgb(primary, paper, 0.45)] as Rgb[],
  };
}

function createProgram(gl: WebGLRenderingContext, fs: string) {
  const compile = (type: number, src: string) => {
    const s = gl.createShader(type)!;
    gl.shaderSource(s, src);
    gl.compileShader(s);
    return s;
  };
  const prog = gl.createProgram()!;
  gl.attachShader(prog, compile(gl.VERTEX_SHADER, VS));
  gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
  gl.linkProgram(prog);
  gl.useProgram(prog);
  const buf = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buf);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const locP = gl.getAttribLocation(prog, "p");
  gl.enableVertexAttribArray(locP);
  gl.vertexAttribPointer(locP, 2, gl.FLOAT, false, 0, 0);
  return prog;
}

function resizeCanvas(gl: WebGLRenderingContext, canvas: HTMLCanvasElement, maxDpr = 2) {
  const dpr = Math.min(window.devicePixelRatio || 1, maxDpr);
  const w = Math.max(1, Math.round(canvas.clientWidth * dpr));
  const h = Math.max(1, Math.round(canvas.clientHeight * dpr));
  if (canvas.width !== w || canvas.height !== h) {
    canvas.width = w;
    canvas.height = h;
    gl.viewport(0, 0, w, h);
  }
}

export interface CurrentButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /** Button label. */
  label?: string;
  /** Hue rotation in degrees (-180 to 180). */
  hue?: number;
  /** Saturation multiplier (0 to 2). */
  saturation?: number;
  /** Brightness multiplier (0.35 to 1.65). */
  brightness?: number;
}

const clamp = (v: number, a: number, b: number) => Math.min(b, Math.max(a, v));

export function CurrentButton({
  label = "Run the draft",
  hue = 0,
  saturation = 1,
  brightness = 1,
  className,
  onMouseDown,
  onKeyDown,
  onMouseEnter,
  onMouseLeave,
  onFocus,
  onBlur,
  ...props
}: CurrentButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const bgRef = useRef<HTMLCanvasElement>(null);
  const glRef = useRef<HTMLCanvasElement>(null);
  const [hot, setHot] = useState(false);
  const state = useRef({ heat: 0, heatTarget: 0, flash: 0, churn: 0 });

  useEffect(() => {
    const root = rootRef.current;
    const bgCanvas = bgRef.current;
    const btnCanvas = glRef.current;
    if (!root || !bgCanvas || !btnCanvas) return;
    const bg = bgCanvas.getContext("webgl");
    const gl = btnCanvas.getContext("webgl");
    if (!bg || !gl) return;
    const bgProg = createProgram(bg, BG_FS);
    const btnProg = createProgram(gl, BTN_FS);
    const bgRes = bg.getUniformLocation(bgProg, "u_res");
    const bgTime = bg.getUniformLocation(bgProg, "u_time");
    const uRes = gl.getUniformLocation(btnProg, "u_res");
    const uTime = gl.getUniformLocation(btnProg, "u_time");
    const uHeat = gl.getUniformLocation(btnProg, "u_heat");
    const uFlash = gl.getUniformLocation(btnProg, "u_flash");
    const bgCols = ["u_c1", "u_c2"].map((n) => bg.getUniformLocation(bgProg, n));
    const btnCols = ["u_c1", "u_c2", "u_c3", "u_c4"].map((n) => gl.getUniformLocation(btnProg, n));
    const s = state.current;
    const applyTheme = () => {
      const ramp = themeRamp();
      bg.useProgram(bgProg);
      ramp.field.forEach((c, i) => bg.uniform3f(bgCols[i]!, c[0], c[1], c[2]));
      gl.useProgram(btnProg);
      ramp.button.forEach((c, i) => gl.uniform3f(btnCols[i]!, c[0], c[1], c[2]));
    };
    applyTheme();
    const themeObserver = new MutationObserver(() => {
      applyTheme();
      if (prefersReducedMotion) frame(performance.now());
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });

    let raf = 0;
    let visible = true;
    let last = performance.now();

    const frame = (now: number) => {
      const dt = Math.min(0.05, (now - last) / 1000);
      last = now;
      s.heat += (s.heatTarget - s.heat) * Math.min(1, dt * 6);
      s.flash *= Math.exp(-3.2 * dt);
      s.churn += dt * (0.35 + s.heat * 1.1 + s.flash * 2.2);
      resizeCanvas(bg, bgCanvas, 1);
      bg.uniform2f(bgRes, bgCanvas.width, bgCanvas.height);
      bg.uniform1f(bgTime, prefersReducedMotion ? 0 : now / 1000);
      bg.drawArrays(bg.TRIANGLES, 0, 3);
      resizeCanvas(gl, btnCanvas);
      gl.uniform2f(uRes, btnCanvas.width, btnCanvas.height);
      gl.uniform1f(uTime, prefersReducedMotion ? 6.0 : s.churn);
      gl.uniform1f(uHeat, s.heat);
      gl.uniform1f(uFlash, s.flash);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    };
    const loop = (now: number) => {
      frame(now);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(raf);
      if (!visible || document.hidden) return;
      last = performance.now();
      if (prefersReducedMotion) {
        // still frame, redrawn while hover/flash eases
        const settle = (now: number) => {
          frame(now);
          if (Math.abs(s.heatTarget - s.heat) > 0.002 || s.flash > 0.002)
            raf = requestAnimationFrame(settle);
          else raf = requestAnimationFrame(idle);
        };
        const idle = () => {
          if (Math.abs(s.heatTarget - s.heat) > 0.002 || s.flash > 0.002) {
            last = performance.now();
            raf = requestAnimationFrame(settle);
          } else raf = requestAnimationFrame(idle);
        };
        raf = requestAnimationFrame(settle);
      } else raf = requestAnimationFrame(loop);
    };
    const io = new IntersectionObserver(([e]) => {
      visible = e?.isIntersecting ?? true;
      start();
    });
    io.observe(root);
    const onVis = () => start();
    document.addEventListener("visibilitychange", onVis);
    start();
    return () => {
      cancelAnimationFrame(raf);
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVis);
      bg.deleteProgram(bgProg);
      gl.deleteProgram(btnProg);
    };
  }, [prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={rootRef}
      className={cn("absolute inset-0 flex items-center justify-center overflow-hidden", className)}
      style={{ filter }}
    >
      <canvas
        ref={bgRef}
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 block h-full w-full"
      />
      <button
        type="button"
        {...props}
        onMouseEnter={(e) => {
          state.current.heatTarget = 1;
          setHot(true);
          onMouseEnter?.(e);
        }}
        onMouseLeave={(e) => {
          state.current.heatTarget = 0;
          setHot(false);
          onMouseLeave?.(e);
        }}
        onFocus={(e) => {
          state.current.heatTarget = 1;
          setHot(true);
          onFocus?.(e);
        }}
        onBlur={(e) => {
          state.current.heatTarget = 0;
          setHot(false);
          onBlur?.(e);
        }}
        onMouseDown={(e) => {
          state.current.flash = 1;
          onMouseDown?.(e);
        }}
        onKeyDown={(e) => {
          if (e.key === "Enter" || e.key === " ") state.current.flash = 1;
          onKeyDown?.(e);
        }}
        className="group relative z-[2] flex h-14 w-[230px] flex-none cursor-pointer items-center justify-center overflow-hidden rounded-full border-0 bg-[hsl(var(--primary))] p-0 outline-none transition-all duration-[220ms] ease-[cubic-bezier(0.34,1.4,0.5,1)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[5px] focus-visible:outline-[hsl(var(--primary))]"
        style={{
          boxShadow:
            hot && !prefersReducedMotion
              ? "0 26px 50px -14px hsl(var(--primary) / 0.55), 0 0 0 1px hsl(var(--border))"
              : "0 18px 36px -16px hsl(var(--primary) / 0.4), 0 0 0 1px hsl(var(--border))",
        }}
      >
        <canvas ref={glRef} aria-hidden="true" className="absolute inset-0 block h-full w-full" />
        <span
          className="pointer-events-none relative z-10 font-mono text-[12px] font-medium uppercase tracking-[.22em] text-[hsl(var(--primary-foreground))] [text-indent:.22em]"
          style={{ textShadow: "0 1px 10px hsl(var(--primary) / .8)" }}
        >
          {label}
        </span>
      </button>
    </div>
  );
}
```

---

# Inkwell

> A round WebGL button holding a well of theme ink that tilts as you sweep the cursor and draws down on click.

Install: `npx @modus-ui/cli add inkwell`

A round raw-WebGL button: a card-coloured glass holding a well of the theme's primary ink, over a faint paper-grain field. Sweeping the cursor tilts and sloshes the surface, and clicking draws the level down before it refills. The label is uppercase mono. Colours come from the theme tokens and are re-read when the theme or palette changes, so it works on paper in light mode and on the dark ground in dark mode. It fills its positioned parent, pauses when off screen or when the tab is hidden, and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add inkwell
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/inkwell.tsx`.
3. Paste the code.

## Usage

```tsx
import { Inkwell } from "@/components/ui/inkwell";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <Inkwell />
    </div>
  );
}
```

## Props

| Prop           | Type                                   | Default  | Description                                       |
| :------------- | :------------------------------------- | :------- | :------------------------------------------------ |
| `label`        | `string`                               | `"Fill"` | Button text.                                      |
| `hue`          | `number`                               | `0`      | Hue rotation in degrees (-180 to 180).            |
| `saturation`   | `number`                               | `1`      | Saturation multiplier (0 to 2).                   |
| `brightness`   | `number`                               | `1`      | Brightness multiplier (0.35 to 1.65).             |
| `onClick`      | `ButtonHTMLAttributes["onClick"]`      | -        | Called after the button's own click effect.       |
| `onMouseMove`  | `ButtonHTMLAttributes["onMouseMove"]`  | -        | Called after the button's own mouse move effect.  |
| `onMouseLeave` | `ButtonHTMLAttributes["onMouseLeave"]` | -        | Called after the button's own mouse leave effect. |
| `onFocus`      | `ButtonHTMLAttributes["onFocus"]`      | -        | Called after the button's own focus effect.       |

Any other `<button>` attribute is passed through to the inner button.

## Source

`components/ui/inkwell.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Tactile Button (MIT, © 2026 Meng To).

import { useEffect, useRef, type ButtonHTMLAttributes } from "react";
import { useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

const VS = "attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}";

const BG_FS = `
precision mediump float;
uniform vec2 u_res;
uniform float u_time;
uniform vec3 u_paper;
uniform vec3 u_ink;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
float fbm(vec2 p) {
  float v = 0.0, a = 0.5;
  for (int i = 0; i < 4; i++) { v += a * noise(p); p = p * 2.0; a *= 0.5; }
  return v;
}
void main() {
  vec2 uv = gl_FragCoord.xy / u_res;
  uv.x *= u_res.x / u_res.y;
  float t = u_time * 0.15;
  vec2 q = vec2(fbm(uv + t), fbm(uv + vec2(1.0) + t));
  vec2 r = vec2(fbm(uv + 1.0*q + vec2(1.7, 9.2) + 0.15*t),
                fbm(uv + 1.0*q + vec2(8.3, 2.8) + 0.126*t));
  float f = fbm(uv + r);
  vec3 col = mix(u_paper, u_ink, 0.03 + 0.05 * f);
  col = mix(col, u_ink, 0.06 * clamp(length(q) * 0.5, 0.0, 1.0));
  gl_FragColor = vec4(col, 1.0);
}
`;

const BTN_FS = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform float u_level;
uniform float u_tilt;
uniform float u_slosh;
uniform vec3 u_glass;
uniform vec3 u_deep;
uniform vec3 u_ink;
uniform vec3 u_light;
float hash(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453123);}
float noise(vec2 p){
  vec2 i=floor(p), f=fract(p);
  vec2 u=f*f*(3.0-2.0*f);
  return mix(mix(hash(i),hash(i+vec2(1.,0.)),u.x),
             mix(hash(i+vec2(0.,1.)),hash(i+vec2(1.,1.)),u.x),u.y);
}
float fbm(vec2 p){
  float v=0.0; float a=0.5;
  for(int i=0;i<4;i++){ v+=a*noise(p); p=p*2.04+vec2(11.3,7.1); a*=0.5; }
  return v;
}
void main(){
  vec2 uv = gl_FragCoord.xy / u_res;
  float ar = u_res.x / u_res.y;
  float x = uv.x * ar;
  float t = u_time;
  float amp = 0.012 + u_slosh * 0.045;
  float surf = u_level
    + u_tilt * (uv.x - 0.5) * 0.34
    + amp * sin(x * 5.1 + t * 4.6)
    + amp * 0.62 * sin(x * 9.7 + t * (-6.8) + 1.7)
    + amp * 0.38 * sin(x * 14.3 + t * 8.9 + 4.2);
  float d = surf - uv.y;
  vec3 col = mix(u_glass, mix(u_glass, u_light, 0.25), uv.y);
  float inside = smoothstep(0.0, 0.012, d);
  float depth = clamp(d / max(u_level, 0.001), 0.0, 1.0);
  vec3 liq = mix(u_ink, u_deep, depth);
  float caust = fbm(vec2(x * 4.2, (uv.y + t * 0.14) * 4.2));
  liq = mix(liq, u_light, 0.12 * caust + 0.1 * pow(max(0.0, d * 3.0), 1.5) * u_slosh);
  col = mix(col, liq, inside);
  col = mix(col, u_light, exp(-abs(d) * 90.0) * 0.6);
  gl_FragColor = vec4(col, 1.0);
}
`;

const BASE = 0.42;

/* Theme tokens are bare HSL channels ("222 47% 11%"); convert to RGB for the shaders. */
type Rgb = [number, number, number];
function readToken(name: string): Rgb {
  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  const [h = 0, sat = 0, lig = 0] = raw.split(/[\s,/]+/).map((v) => parseFloat(v));
  const s = sat / 100;
  const l = lig / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = s * Math.min(l, 1 - l);
  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}
const mixRgb = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];
/* A well of the theme's primary ink inside a card-coloured glass, over a faint paper field. */
function themeColors() {
  const primary = readToken("--primary");
  const paper = readToken("--background");
  const ink = readToken("--foreground");
  const card = readToken("--card");
  return {
    u_paper: paper,
    u_ink: ink,
    u_glass: card,
    u_deep: mixRgb(primary, ink, 0.45),
    u_inkBtn: primary,
    u_light: mixRgb(primary, paper, 0.8),
  };
}

function createProgram(gl: WebGLRenderingContext, fs: string) {
  const compile = (type: number, src: string) => {
    const s = gl.createShader(type)!;
    gl.shaderSource(s, src);
    gl.compileShader(s);
    return s;
  };
  const prog = gl.createProgram()!;
  gl.attachShader(prog, compile(gl.VERTEX_SHADER, VS));
  gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, fs));
  gl.linkProgram(prog);
  gl.useProgram(prog);
  const buf = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buf);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const locP = gl.getAttribLocation(prog, "p");
  gl.enableVertexAttribArray(locP);
  gl.vertexAttribPointer(locP, 2, gl.FLOAT, false, 0, 0);
  return prog;
}

function resizeCanvas(gl: WebGLRenderingContext, canvas: HTMLCanvasElement) {
  const dpr = Math.min(window.devicePixelRatio || 1, 2);
  const w = Math.max(1, Math.round(canvas.clientWidth * dpr));
  const h = Math.max(1, Math.round(canvas.clientHeight * dpr));
  if (canvas.width !== w || canvas.height !== h) {
    canvas.width = w;
    canvas.height = h;
    gl.viewport(0, 0, w, h);
  }
}

export interface InkwellProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  /** Button label. */
  label?: string;
  /** Hue rotation in degrees (-180 to 180). */
  hue?: number;
  /** Saturation multiplier (0 to 2). */
  saturation?: number;
  /** Brightness multiplier (0.35 to 1.65). */
  brightness?: number;
}

const clamp = (v: number, a: number, b: number) => Math.min(b, Math.max(a, v));

export function Inkwell({
  label = "Fill",
  hue = 0,
  saturation = 1,
  brightness = 1,
  className,
  onClick,
  onMouseMove,
  onMouseLeave,
  onFocus,
  ...props
}: InkwellProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const bgRef = useRef<HTMLCanvasElement>(null);
  const glRef = useRef<HTMLCanvasElement>(null);
  const state = useRef({
    level: BASE,
    gulp: 0,
    slosh: 0.4,
    tilt: 0,
    tiltTarget: 0,
    lastX: null as number | null,
  });

  useEffect(() => {
    const root = rootRef.current;
    const bgCanvas = bgRef.current;
    const btnCanvas = glRef.current;
    if (!root || !bgCanvas || !btnCanvas) return;
    const bg = bgCanvas.getContext("webgl");
    const gl = btnCanvas.getContext("webgl");
    if (!bg || !gl) return;
    const bgProg = createProgram(bg, BG_FS);
    const btnProg = createProgram(gl, BTN_FS);
    const bgRes = bg.getUniformLocation(bgProg, "u_res");
    const bgTime = bg.getUniformLocation(bgProg, "u_time");
    const uRes = gl.getUniformLocation(btnProg, "u_res");
    const uTime = gl.getUniformLocation(btnProg, "u_time");
    const uLevel = gl.getUniformLocation(btnProg, "u_level");
    const uTilt = gl.getUniformLocation(btnProg, "u_tilt");
    const uSlosh = gl.getUniformLocation(btnProg, "u_slosh");
    const s = state.current;
    const applyTheme = () => {
      const c = themeColors();
      bg.useProgram(bgProg);
      bg.uniform3f(bg.getUniformLocation(bgProg, "u_paper"), ...c.u_paper);
      bg.uniform3f(bg.getUniformLocation(bgProg, "u_ink"), ...c.u_ink);
      gl.useProgram(btnProg);
      gl.uniform3f(gl.getUniformLocation(btnProg, "u_glass"), ...c.u_glass);
      gl.uniform3f(gl.getUniformLocation(btnProg, "u_deep"), ...c.u_deep);
      gl.uniform3f(gl.getUniformLocation(btnProg, "u_ink"), ...c.u_inkBtn);
      gl.uniform3f(gl.getUniformLocation(btnProg, "u_light"), ...c.u_light);
    };
    applyTheme();
    const themeObserver = new MutationObserver(() => {
      applyTheme();
      if (prefersReducedMotion) frame(performance.now());
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    const startTime = performance.now();

    let raf = 0;
    let visible = true;
    let last = performance.now();

    const frame = (now: number) => {
      const dt = Math.min(0.05, (now - last) / 1000);
      last = now;
      s.slosh *= Math.exp(-1.5 * dt);
      s.gulp *= Math.exp(-1.1 * dt);
      s.tilt += (s.tiltTarget - s.tilt) * Math.min(1, dt * 5);
      const levelTarget = BASE - 0.36 * s.gulp;
      s.level += (levelTarget - s.level) * Math.min(1, dt * 5.5);
      resizeCanvas(bg, bgCanvas);
      bg.uniform2f(bgRes, bgCanvas.width, bgCanvas.height);
      bg.uniform1f(bgTime, prefersReducedMotion ? 0 : (now - startTime) / 1000);
      bg.drawArrays(bg.TRIANGLES, 0, 3);
      resizeCanvas(gl, btnCanvas);
      gl.uniform2f(uRes, btnCanvas.width, btnCanvas.height);
      gl.uniform1f(uTime, prefersReducedMotion ? 2.0 : now / 1000);
      gl.uniform1f(uLevel, s.level);
      gl.uniform1f(uTilt, s.tilt);
      gl.uniform1f(uSlosh, prefersReducedMotion ? 0.25 : s.slosh);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    };
    const settling = () => Math.abs(s.tiltTarget - s.tilt) > 0.002 || s.gulp > 0.002;
    const loop = (now: number) => {
      frame(now);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(raf);
      if (!visible || document.hidden) return;
      last = performance.now();
      if (prefersReducedMotion) {
        // still frame, redrawn only while the level/tilt eases
        const tick = (now: number) => {
          if (settling()) frame(now);
          else last = now;
          raf = requestAnimationFrame(tick);
        };
        frame(last);
        raf = requestAnimationFrame(tick);
      } else raf = requestAnimationFrame(loop);
    };
    const io = new IntersectionObserver(([e]) => {
      visible = e?.isIntersecting ?? true;
      start();
    });
    io.observe(root);
    const onVis = () => start();
    document.addEventListener("visibilitychange", onVis);
    start();
    return () => {
      cancelAnimationFrame(raf);
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVis);
      bg.deleteProgram(bgProg);
      gl.deleteProgram(btnProg);
    };
  }, [prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={rootRef}
      className={cn("absolute inset-0 flex items-center justify-center overflow-hidden", className)}
      style={{ filter }}
    >
      <canvas
        ref={bgRef}
        aria-hidden="true"
        className="pointer-events-none absolute inset-0 block h-full w-full"
      />
      <button
        type="button"
        {...props}
        onMouseMove={(e) => {
          const s = state.current;
          const rect = e.currentTarget.getBoundingClientRect();
          const x = (e.clientX - rect.left) / Math.max(1, rect.width);
          if (s.lastX !== null) s.slosh = Math.min(1.4, s.slosh + Math.abs(x - s.lastX) * 2.6);
          s.lastX = x;
          s.tiltTarget = Math.max(-1, Math.min(1, (x - 0.5) * 2));
          onMouseMove?.(e);
        }}
        onMouseLeave={(e) => {
          state.current.lastX = null;
          state.current.tiltTarget = 0;
          onMouseLeave?.(e);
        }}
        onFocus={(e) => {
          state.current.slosh = Math.min(1.4, state.current.slosh + 0.5);
          onFocus?.(e);
        }}
        onClick={(e) => {
          state.current.gulp = 1;
          state.current.slosh = Math.min(1.4, state.current.slosh + 0.7);
          onClick?.(e);
        }}
        className="relative z-[2] flex h-[132px] w-[132px] flex-none cursor-pointer items-center justify-center overflow-hidden rounded-full border-0 bg-[hsl(var(--card))] p-0 shadow-[0_22px_44px_-18px_hsl(var(--foreground)/0.45),inset_0_0_0_1px_hsl(var(--border))] transition-all duration-300 ease-out hover:shadow-[0_26px_52px_-16px_hsl(var(--primary)/0.5),inset_0_0_0_1px_hsl(var(--primary)/0.4)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[5px] focus-visible:outline-[hsl(var(--primary))]"
      >
        <canvas ref={glRef} aria-hidden="true" className="absolute inset-0 block h-full w-full" />
        <span className="pointer-events-none relative z-10 flex flex-col items-center gap-1 font-mono text-[11px] font-medium uppercase tracking-[0.24em] text-foreground [text-indent:0.24em]">
          {label}
          <svg
            width="14"
            height="14"
            viewBox="0 0 24 24"
            aria-hidden="true"
            className="rotate-90 opacity-80"
          >
            <path
              fill="none"
              stroke="currentColor"
              strokeLinecap="round"
              strokeLinejoin="round"
              strokeWidth="1.5"
              d="M4 12h16m0 0l-6-6m6 6l-6 6"
            />
          </svg>
        </span>
      </button>
    </div>
  );
}
```

---

# Muse Button

> A canvas busy-state button in the theme's ink, with a comet tracing its border, a dot spinner and a shimmering serif label.

Install: `npx @modus-ui/cli add muse-button`

A Canvas 2D busy-state button inked in the theme's primary colour. A comet of the same colour laps the border, a six-dot spinner ticks beside the label, and a shimmer sweeps across an italic word set in the Modus heading face. The scene is transparent so it sits on the page, and colours are re-read when the theme or palette changes. It fills its positioned parent, pauses when off screen or when the tab is hidden, and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add muse-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/muse-button.tsx`.
3. Paste the code.

## Usage

```tsx
import { MuseButton } from "@/components/ui/muse-button";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <MuseButton />
    </div>
  );
}
```

## Props

| Prop              | Type                       | Default                       | Description                                        |
| :---------------- | :------------------------- | :---------------------------- | :------------------------------------------------- |
| `label`           | `string`                   | `"Composing"`                 | Word drawn on the button.                          |
| `backgroundColor` | `string`                   | `undefined`                   | Scene background colour; transparent when omitted. |
| `plateColors`     | `[string, string, string]` | a ramp of the theme's primary | Plate gradient stops, top to bottom.               |
| `hue`             | `number`                   | `0`                           | Hue rotation in degrees (-180 to 180).             |
| `saturation`      | `number`                   | `1`                           | Saturation multiplier (0 to 2).                    |
| `brightness`      | `number`                   | `1`                           | Brightness multiplier (0.35 to 1.65).              |

## Source

`components/ui/muse-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Thinking Button (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";

import { cn } from "@/lib/utils";

export interface MuseButtonProps {
  /** Word drawn on the button. */
  label?: string;
  /** Scene background colour. Transparent by default, so the page shows through. */
  backgroundColor?: string;
  /** Three plate gradient stops (top, middle, bottom). Defaults to a ramp of the theme's primary colour. */
  plateColors?: [string, string, string];
  /** Hue rotation in degrees (-180 to 180). */
  hue?: number;
  /** Saturation multiplier (0 to 2). */
  saturation?: number;
  /** Brightness multiplier (0.35 to 1.65). */
  brightness?: number;
  className?: string;
}

/* reference frame: everything authored in a 2048px square */
const REF = 2048;
const SCL = 0.72; /* hero button -> a larger, centred button */
const CX = (1024 - 22) / SCL;
const CY = (1024 + 11.5) / SCL;
const PW = 1010;
const PH = 345;
const PR = 100;
const GAP = 50;
const TW = PW + 2 * GAP;
const TH = PH + 2 * GAP;
const TR = PR + GAP;
const TRACK_W = 13;
const CORE_W = 14;
const GLOW_W = 12;
const DUR = 2.7; /* one lap of the trace = one loop */
const TAIL = 0.389; /* comet length, in laps */
const SHIM_OFF = 0.898;
const TXT_W = 450;
const TXT_CAP = 79;
const TXT_BASE = CY + 38;
const BR_R = 13;
const BR_SP = 40;
const BR_GAP = 78;
const BR_W = BR_SP + 2 * BR_R;
const BR_SHIFT = (BR_W + BR_GAP) / 2;
/* the terminal 'dots' spinner, as raised-dot masks: bit 0..2 = left column top->bottom, 3..5 = right */
const BRAILLE = [0x0b, 0x19, 0x39, 0x38, 0x3c, 0x34, 0x26, 0x27, 0x07, 0x0f];
const BR_STEPS = 30;
/* the label is set in the Modus heading face, read from --font-heading at runtime */
const FONT_TEMPLATE = "italic 400 100px ";

const SW = TW - 2 * TR;
const SH = TH - 2 * TR;
const ARC = (Math.PI * TR) / 2;
const PERIM = 2 * SW + 2 * SH + 4 * ARC;
const L = CX - TW / 2;
const T = CY - TH / 2;
const R = CX + TW / 2;
const B = CY + TH / 2;

const TAPER = [
  1.16, 1.09, 1.03, 1.0, 1.02, 1.0, 1.0, 1.0, 1.0, 0.98, 0.97, 0.94, 0.91, 0.89, 0.84, 0.77, 0.74,
  0.65, 0.61, 0.52, 0.43, 0.4, 0.27, 0.23, 0.17, 0.12, 0.075, 0.02, 0,
];
const TSTEP = TAIL / (TAPER.length - 1);

/* Theme tokens are bare HSL channels ("222 47% 11%"). */
type Rgb = [number, number, number];
function readToken(name: string): Rgb {
  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  const [h = 0, sat = 0, lig = 0] = raw.split(/[\s,/]+/).map((v) => parseFloat(v));
  const s = sat / 100;
  const l = lig / 100;
  const k = (n: number) => (n + h / 30) % 12;
  const a = s * Math.min(l, 1 - l);
  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0) * 255, f(8) * 255, f(4) * 255];
}
const rgba = (c: Rgb, a = 1) =>
  `rgba(${Math.round(c[0])},${Math.round(c[1])},${Math.round(c[2])},${a})`;
const mixRgb = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];
function readTheme() {
  const primary = readToken("--primary");
  const ink = readToken("--foreground");
  const on = readToken("--primary-foreground");
  const heading = getComputedStyle(document.documentElement)
    .getPropertyValue("--font-heading")
    .trim();
  return {
    primary,
    ink,
    on,
    plate: [rgba(mixRgb(primary, on, 0.14)), rgba(primary), rgba(mixRgb(primary, ink, 0.3))] as [
      string,
      string,
      string,
    ],
    font: FONT_TEMPLATE + (heading || "Georgia, serif"),
  };
}

function rrPath(
  c: CanvasRenderingContext2D,
  cx: number,
  cy: number,
  w: number,
  h: number,
  r: number,
) {
  const x = cx - w / 2;
  const y = cy - h / 2;
  c.beginPath();
  c.moveTo(x + r, y);
  c.lineTo(x + w - r, y);
  c.arcTo(x + w, y, x + w, y + r, r);
  c.lineTo(x + w, y + h - r);
  c.arcTo(x + w, y + h, x + w - r, y + h, r);
  c.lineTo(x + r, y + h);
  c.arcTo(x, y + h, x, y + h - r, r);
  c.lineTo(x, y + r);
  c.arcTo(x, y, x + r, y, r);
  c.closePath();
}

/* point on the track outline at arc length s, clockwise from the top-left tangent point */
function ptAt(s: number): [number, number] {
  s = s - Math.floor(s / PERIM) * PERIM;
  let a: number;
  if (s < SW) return [L + TR + s, T];
  s -= SW;
  if (s < ARC) {
    a = s / TR;
    return [R - TR + TR * Math.sin(a), T + TR - TR * Math.cos(a)];
  }
  s -= ARC;
  if (s < SH) return [R, T + TR + s];
  s -= SH;
  if (s < ARC) {
    a = s / TR;
    return [R - TR + TR * Math.cos(a), B - TR + TR * Math.sin(a)];
  }
  s -= ARC;
  if (s < SW) return [R - TR - s, B];
  s -= SW;
  if (s < ARC) {
    a = s / TR;
    return [L + TR - TR * Math.sin(a), B - TR + TR * Math.cos(a)];
  }
  s -= ARC;
  if (s < SH) return [L, B - TR - s];
  s -= SH;
  a = s / TR;
  return [L + TR - TR * Math.cos(a), T + TR - TR * Math.sin(a)];
}

function taper(u: number) {
  if (u < 0 || u >= TAIL) return 0;
  const f = u / TSTEP;
  const i = Math.floor(f);
  return TAPER[i] + (TAPER[i + 1] - TAPER[i]) * (f - i);
}

const clamp = (v: number, a: number, b: number) => Math.min(b, Math.max(a, v));

export function MuseButton({
  label = "Composing",
  backgroundColor,
  plateColors,
  hue = 0,
  saturation = 1,
  brightness = 1,
  className,
}: MuseButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  const stageRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const background = backgroundColor;
  const plateKey = plateColors?.join("|") ?? "";

  useEffect(() => {
    const stage = stageRef.current;
    const cv = canvasRef.current;
    const ctx = cv?.getContext("2d");
    if (!stage || !cv || !ctx) return;
    let theme = readTheme();
    const plateStops = () => (plateKey ? plateKey.split("|") : theme.plate);
    const glc = document.createElement("canvas");
    const gx = glc.getContext("2d")!; /* comet, glow tint */
    const co = document.createElement("canvas");
    const cox = co.getContext("2d")!; /* comet, core tint */
    let S = 0;
    let k = 1;
    let dpr = 1;
    const canFilter = (() => {
      const t = document.createElement("canvas").getContext("2d")!;
      t.filter = "blur(2px)";
      return t.filter !== "none";
    })();

    let glyphs: { ch: string; w: number }[] = [];
    let fontPx = 169;
    let tracking = 0;
    let textX = 0;
    let brailleX = 0;

    function fitText() {
      const word = label;
      const n = word.length;
      const probe = 200;
      if (!n) {
        glyphs = [];
        return;
      }
      ctx!.setTransform(1, 0, 0, 1, 0, 0);
      ctx!.font = theme.font.replace("100px", probe + "px");
      const cap = ctx!.measureText("U").actualBoundingBoxAscent || probe * 0.7;
      fontPx = (probe * (TXT_CAP * k)) / cap;
      ctx!.font = theme.font.replace("100px", fontPx + "px");
      glyphs = [];
      let advSum = 0;
      for (let i = 0; i < n; i++) {
        const m = ctx!.measureText(word[i]);
        glyphs.push({ ch: word[i], w: m.width });
        if (i < n - 1) advSum += m.width;
      }
      const lead = ctx!.measureText(word[0]).actualBoundingBoxLeft;
      const trail = ctx!.measureText(word[n - 1]).actualBoundingBoxRight;
      tracking = n > 1 ? (TXT_W * k - trail - lead - advSum) / (n - 1) : 0;
      textX = (CX + 4) * k - (TXT_W * k) / 2 + lead + BR_SHIFT * k;
      brailleX = (CX + 4) * k - ((BR_W + BR_GAP + TXT_W) * k) / 2 + BR_R * k;
    }

    function paintComet(
      c: CanvasRenderingContext2D,
      head: number,
      col: number[],
      hot: number[],
      width: number,
    ) {
      c.setTransform(1, 0, 0, 1, 0, 0);
      c.clearRect(0, 0, c.canvas.width, c.canvas.height);
      c.lineCap = "round";
      c.lineWidth = width * k;
      const step = 6;
      const n = Math.ceil((TAIL * PERIM) / step);
      for (let i = n; i >= 1; i--) {
        const s1 = head - i * step;
        const s0 = head - (i - 1) * step;
        const a = taper((i * step) / PERIM);
        if (a <= 0.002) continue;
        const f = Math.min(a, 1.3);
        const x = Math.max(0, f - 1);
        const r = Math.round(Math.min(255, col[0] * f + hot[0] * x));
        const g = Math.round(Math.min(255, col[1] * f + hot[1] * x));
        const b = Math.round(Math.min(255, col[2] * f + hot[2] * x));
        const p1 = ptAt(s1);
        const mid = ptAt((s1 + s0) / 2);
        const p0 = ptAt(s0);
        c.strokeStyle = "rgb(" + r + "," + g + "," + b + ")";
        c.beginPath();
        c.moveTo(p1[0] * k, p1[1] * k);
        c.lineTo(mid[0] * k, mid[1] * k);
        c.lineTo(p0[0] * k, p0[1] * k);
        c.stroke();
      }
    }

    function plate(c: CanvasRenderingContext2D) {
      const y = CY - PH / 2;
      const grd = c.createLinearGradient(0, y * k, 0, (y + PH) * k);
      const stops = plateStops();
      grd.addColorStop(0, stops[0]);
      grd.addColorStop(0.55, stops[1]);
      grd.addColorStop(1, stops[2]);
      rrPath(c, CX * k, CY * k, PW * k, PH * k, PR * k);
      c.fillStyle = grd;
      c.fill();
      c.lineWidth = 5 * k;
      const hg = c.createLinearGradient(0, y * k, 0, (y + PH) * k);
      hg.addColorStop(0, rgba(theme.on, 0.16));
      hg.addColorStop(0.1, rgba(theme.on, 0));
      hg.addColorStop(0.9, rgba(theme.ink, 0));
      hg.addColorStop(1, rgba(theme.ink, 0.2));
      rrPath(c, CX * k, CY * k, (PW - 13) * k, (PH - 13) * k, (PR - 6.5) * k);
      c.strokeStyle = hg;
      c.stroke();
    }

    /* the spinner is drawn as dots rather than braille glyphs */
    function braille(c: CanvasRenderingContext2D, ph: number) {
      const mask = BRAILLE[Math.floor(ph * BR_STEPS) % BRAILLE.length];
      const cy = (CY - 1.5) * k;
      const r = BR_R * k;
      const sp = BR_SP * k;
      for (let b = 0; b < 6; b++) {
        const on = (mask >> b) & 1;
        c.beginPath();
        c.arc(
          brailleX + (b < 3 ? 0 : sp),
          cy + ((b % 3) - 1) * sp,
          on ? r : r * 0.7,
          0,
          Math.PI * 2,
        );
        c.fillStyle = on ? rgba(theme.on, 0.95) : rgba(theme.on, 0.2);
        c.fill();
      }
    }

    function drawLabel(c: CanvasRenderingContext2D, ph: number) {
      /* shimmer: a soft band ping-pongs across the word, twice per lap */
      let q = ph - SHIM_OFF;
      q -= Math.floor(q);
      const u = q < 0.5 ? q / 0.5 : (1 - q) / 0.5;
      const x0 = textX;
      const w = TXT_W * k;
      const bc = x0 + w * (-0.2375 + 1.475 * u);
      const bw = w * 0.22;
      const g = c.createLinearGradient(bc - bw, 0, bc + bw, 0);
      g.addColorStop(0, rgba(theme.on, 0.72));
      g.addColorStop(0.3, rgba(theme.on, 0.86));
      g.addColorStop(0.5, rgba(theme.on, 1));
      g.addColorStop(0.7, rgba(theme.on, 0.86));
      g.addColorStop(1, rgba(theme.on, 0.72));
      c.fillStyle = g;
      c.strokeStyle = g;
      c.font = theme.font.replace("100px", fontPx + "px");
      c.textBaseline = "alphabetic";
      let x = textX;
      for (let i = 0; i < glyphs.length; i++) {
        c.fillText(glyphs[i].ch, x, TXT_BASE * k);
        c.lineWidth = 0.6 * k;
        c.strokeText(glyphs[i].ch, x, TXT_BASE * k);
        x += glyphs[i].w + tracking;
      }
    }

    function render(t: number) {
      if (!S) return;
      let ph = (t / DUR) % 1;
      if (ph < 0) ph += 1;
      const head = ph * PERIM;
      const c = ctx!;
      c.setTransform(1, 0, 0, 1, 0, 0);
      c.globalCompositeOperation = "source-over";
      c.globalAlpha = 1;
      c.filter = "none";
      c.clearRect(0, 0, cv!.width, cv!.height);
      if (background) {
        c.fillStyle = background;
        c.fillRect(0, 0, cv!.width, cv!.height);
      }

      rrPath(c, CX * k, CY * k, TW * k, TH * k, TR * k);
      c.lineWidth = TRACK_W * k;
      c.strokeStyle = rgba(theme.ink, 0.07);
      c.stroke();

      paintComet(gx, head, theme.primary, [0, 0, 0], GLOW_W);
      paintComet(cox, head, theme.primary, theme.ink, CORE_W);
      if (canFilter) {
        c.filter = "blur(" + 28 * k + "px)";
        c.globalAlpha = 0.62;
        c.drawImage(glc, 0, 0);
        c.filter = "blur(" + 8 * k + "px)";
        c.globalAlpha = 0.45;
        c.drawImage(glc, 0, 0);
        c.filter = "blur(" + 1.8 * k + "px)";
        c.globalAlpha = 1;
        c.drawImage(co, 0, 0);
        c.filter = "none";
      } else {
        c.shadowColor = rgba(theme.primary, 0.9);
        c.shadowBlur = 26 * k;
        c.globalAlpha = 0.7;
        c.drawImage(glc, 0, 0);
        c.shadowBlur = 8 * k;
        c.globalAlpha = 0.8;
        c.drawImage(glc, 0, 0);
        c.shadowBlur = 0;
        c.globalAlpha = 1;
        c.drawImage(co, 0, 0);
      }
      c.globalAlpha = 1;
      c.globalCompositeOperation = "source-over";

      plate(c);
      braille(c, ph);
      drawLabel(c, ph);
    }

    let now = 0;
    let last: number | null = null;
    let raf = 0;
    let visible = true;

    function resize() {
      S = stage!.clientWidth || 1;
      dpr = Math.min(window.devicePixelRatio || 1, 2);
      cv!.width = glc.width = co.width = Math.round(S * dpr);
      cv!.height = glc.height = co.height = Math.round(S * dpr);
      k = ((S * dpr) / REF) * SCL;
      fitText();
      render(now);
    }

    function frame(ts: number) {
      if (last != null) now = (now + (ts - last) / 1000) % DUR;
      last = ts;
      render(now);
      raf = requestAnimationFrame(frame);
    }
    function start() {
      cancelAnimationFrame(raf);
      last = null;
      if (prefersReducedMotion || !visible || document.hidden) return;
      raf = requestAnimationFrame(frame);
    }

    const themeObserver = new MutationObserver(() => {
      theme = readTheme();
      fitText();
      render(now);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    const ro = new ResizeObserver(resize);
    ro.observe(stage);
    const io = new IntersectionObserver(([e]) => {
      visible = e?.isIntersecting ?? true;
      start();
    });
    io.observe(stage);
    const onVis = () => start();
    document.addEventListener("visibilitychange", onVis);
    let cancelled = false;
    document.fonts?.ready.then(() => {
      if (cancelled) return;
      fitText();
      render(now);
    });
    resize();
    start();
    return () => {
      cancelled = true;
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVis);
    };
  }, [label, background, plateKey, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      role="img"
      aria-label={label}
      className={cn(
        "absolute inset-0 flex items-center justify-center overflow-hidden [container-type:size]",
        className,
      )}
      style={{ background, filter }}
    >
      <div
        ref={stageRef}
        className="relative"
        style={{
          background,
          width: "min(100cqw, 100cqh)",
          height: "min(100cqw, 100cqh)",
        }}
      >
        <canvas ref={canvasRef} className="absolute inset-0 block h-full w-full" />
      </div>
    </div>
  );
}
```

---

# Pulse Dust

> A grain field on the page's own paper where slow travelling waves swell the dots, with rare accent grains in the theme primary.

Install: `npx @modus-ui/cli add pulse-dust`

A grain field on the page's own paper where slow travelling waves swell the dots, with rare accent grains in the theme primary. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add pulse-dust
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pulse-dust.tsx`.
3. Paste the code.

## Usage

```tsx
import { PulseDust } from "@/components/ui/pulse-dust";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <PulseDust />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type               | Default                            | Description                                      |
| :---------------- | :----------------- | :--------------------------------- | :----------------------------------------------- |
| `speed`           | `number`           | `0.8`                              | Animation speed multiplier.                      |
| `size`            | `number`           | `1.15`                             | Grain radius multiplier.                         |
| `length`          | `number`           | `0.75`                             | Grid density; higher values tighten the spacing. |
| `opacity`         | `number`           | `1`                                | Canvas opacity.                                  |
| `hue`             | `number`           | `0`                                | Hue rotation in degrees.                         |
| `saturation`      | `number`           | `1`                                | Saturation multiplier.                           |
| `brightness`      | `number`           | `1`                                | Brightness multiplier.                           |
| `dotColor`        | `string`           | theme foreground                   | Colour of the regular grains.                    |
| `highlightColors` | `[string, string]` | theme primary and muted foreground | Colours of the rare accent grains.               |
| `backgroundColor` | `string`           | theme background                   | Background colour.                               |

## Source

`components/ui/pulse-dust.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Signal Particles (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface PulseDustProps {
  speed?: number;
  size?: number;
  length?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the regular grains. Defaults to the theme foreground. */
  dotColor?: string;
  /** Colours of the rare accent grains. Default to the theme primary and muted foreground. */
  highlightColors?: [string, string];
  /** Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];
const css = (c: Rgb, alpha = 1) => `rgb(${c.map((v) => Math.round(v * 255)).join(" ")} / ${alpha})`;

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

export function PulseDust({
  speed = 0.8,
  size = 1.15,
  length = 0.75,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  dotColor,
  highlightColors,
  backgroundColor,
  className,
}: PulseDustProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const colors = useRef({ dot: "", accents: ["", ""] });
  const options = useRef({ speed, size, length });
  options.current = { speed, size, length };

  useEffect(() => {
    if (!theme) return;
    const accent = highlightColors?.map(toRgb) ?? [
      theme.primary,
      mix(theme.primary, theme["muted-foreground"], 0.55),
    ];
    colors.current = {
      dot: (dotColor ? toRgb(dotColor) : theme.foreground)
        .map((v) => Math.round(v * 255))
        .join(" "),
      accents: accent.map((c) => css(c)),
    };
  }, [theme, dotColor, highlightColors]);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx || !theme) return;

    let width = 0;
    let height = 0;
    let time = 0;
    let frame = 0;
    let visible = true;

    const draw = () => {
      const o = options.current;
      const { dot, accents } = colors.current;
      const spacing = Math.max(6, Math.round(16 / Math.max(0.35, clamp(o.length, 0.35, 2.5))));
      const grain = 2.4 * clamp(o.size, 0.05, 200);

      ctx.clearRect(0, 0, width, height);
      const cols = Math.floor(width / spacing);
      const rows = Math.floor(height / spacing);
      const offsetX = (width - cols * spacing) / 2;
      const offsetY = (height - rows * spacing) / 2;

      for (let i = 0; i <= cols; i++) {
        for (let j = 0; j <= rows; j++) {
          const nx = i * 0.1;
          const ny = j * 0.1;
          const wave1 = Math.sin(nx + time * 0.5) * Math.cos(ny - time * 0.3);
          const wave2 = Math.sin(nx * 0.5 - ny * 0.5 + time * 0.8);
          const value = wave1 + wave2;
          if (value <= 0.1) continue;
          // Square grains that swell with the wave instead of fixed round dots.
          const s = grain * clamp((value - 0.1) * 0.7, 0.25, 1);
          const x = offsetX + i * spacing - s / 2;
          const y = offsetY + j * spacing - s / 2;
          const pick = Math.sin(i * 12.34) * Math.cos(j * 56.78);
          if (pick > 0.94) ctx.fillStyle = accents[0];
          else if (pick < -0.94) ctx.fillStyle = accents[1];
          else ctx.fillStyle = `rgb(${dot} / ${Math.min(0.7, (value - 0.1) * 0.8)})`;
          ctx.fillRect(x, y, s, s);
        }
      }
    };

    const tick = () => {
      draw();
      time += 0.02 * clamp(options.current.speed, 0, 3);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !document.hidden && !frame)
        frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      width = canvas.width = host.offsetWidth;
      height = canvas.height = host.offsetHeight;
      draw();
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
    };
  }, [prefersReducedMotion, theme]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Signal Tiles

> Rounded tiles that swell in waves rolling across the frame from one corner, crested in the theme accent.

Install: `npx @modus-ui/cli add signal-tiles`

A field of rounded tiles that swell and shrink as waves roll in from the lower-left corner. Wave shoulders are drawn in `--muted-foreground`, crests in `--primary`, on the theme `--background`, so it reads as ink on paper in light mode and follows palette changes live. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add signal-tiles
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/signal-tiles.tsx`.
3. Paste the code.

## Usage

```tsx
import { SignalTiles } from "@/components/ui/signal-tiles";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SignalTiles />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                       |
| :---------------- | :------- | :------------------- | :-------------------------------- |
| `speed`           | `number` | `1`                  | Animation speed multiplier.       |
| `size`            | `number` | `28`                 | Tile size in pixels.              |
| `gap`             | `number` | `6`                  | Gap between tiles in pixels.      |
| `opacity`         | `number` | `1`                  | Canvas opacity.                   |
| `hue`             | `number` | `0`                  | Hue rotation in degrees.          |
| `saturation`      | `number` | `1`                  | Saturation multiplier.            |
| `brightness`      | `number` | `1`                  | Brightness multiplier.            |
| `color`           | `string` | theme tokens         | Single CSS colour for every tile. |
| `backgroundColor` | `string` | theme `--background` | Background colour.                |

## Source

`components/ui/signal-tiles.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Override Grid (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface SignalTilesProps {
  speed?: number;
  size?: number;
  gap?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  color?: string;
  backgroundColor?: string;
  className?: string;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

/** A bare-HSL theme token (`"24 9% 10%"`) read from the document root. */
const readToken = (name: string) =>
  getComputedStyle(document.documentElement).getPropertyValue(name).trim();

export function SignalTiles({
  speed = 1,
  size = 28,
  gap = 6,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  color,
  backgroundColor,
  className,
}: SignalTilesProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({ speed, size, gap, color });
  options.current = { speed, size, gap, color };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    let width = 0;
    let height = 0;
    let time = 0;
    let frame = 0;
    let visible = true;
    let ink = "";
    let accent = "";
    const readTheme = () => {
      ink = readToken("--muted-foreground");
      accent = readToken("--primary");
    };

    const draw = () => {
      const o = options.current;
      const blockSize = Math.max(8, Math.round(clamp(o.size, 0.05, 200)));
      const blockGap = Math.max(0, Math.round(clamp(o.gap, 0, 64)));

      ctx.clearRect(0, 0, width, height);
      const pitch = blockSize + blockGap;
      const cols = Math.ceil(width / pitch);
      const rows = Math.ceil(height / pitch);
      // The wave rolls in from the lower-left corner rather than the centre.
      const originX = -cols * 0.1;
      const originY = rows * 1.1;

      for (let i = 0; i < cols; i++) {
        for (let j = 0; j < rows; j++) {
          const dist = Math.hypot(i - originX, j - originY);
          const wave = Math.sin(time - dist * 0.4);
          if (wave > 0) {
            // Crests take the accent; the shoulders of each wave stay in muted ink.
            const crest = wave > 0.82;
            const alpha = crest ? 0.55 + wave * 0.35 : wave * 0.28;
            ctx.fillStyle = o.color ?? `hsl(${crest ? accent : ink} / ${alpha})`;
            if (o.color) ctx.globalAlpha = alpha;
            const scale = wave * 0.65 + 0.35;
            const blockScaled = blockSize * scale;
            const offset = (pitch - blockScaled) / 2;
            ctx.beginPath();
            ctx.roundRect(
              i * pitch + offset,
              j * pitch + offset,
              blockScaled,
              blockScaled,
              blockScaled * 0.28,
            );
            ctx.fill();
            ctx.globalAlpha = 1;
          }
        }
      }
    };

    const tick = () => {
      time += 0.04 * clamp(options.current.speed, 0, 3);
      draw();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !document.hidden && !frame)
        frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      width = canvas.width = host.offsetWidth;
      height = canvas.height = host.offsetHeight;
      if (prefersReducedMotion) time = 1;
      draw();
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    const themeObserver = new MutationObserver(() => {
      readTheme();
      draw();
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style", "data-theme", "data-palette"],
    });
    readTheme();
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      themeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
    };
  }, [prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Hollow Bloom

> A curved dot matrix that blooms outward from a hollow centre and drifts with the pointer, tinted from the theme primary.

Install: `npx @modus-ui/cli add hollow-bloom`

A curved dot matrix that blooms outward from a hollow centre and drifts with the pointer, tinted from the theme primary. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add hollow-bloom
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/hollow-bloom.tsx`.
3. Paste the code.

## Usage

```tsx
import { HollowBloom } from "@/components/ui/hollow-bloom";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <HollowBloom />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default          | Description                   |
| :---------------- | :------- | :--------------- | :---------------------------- |
| `speed`           | `number` | `0.8`            | Animation speed multiplier.   |
| `hue`             | `number` | `0`              | Hue rotation in degrees.      |
| `saturation`      | `number` | `1`              | Saturation multiplier.        |
| `brightness`      | `number` | `1`              | Brightness multiplier.        |
| `color`           | `string` | theme primary    | Colour of the blooming marks. |
| `backgroundColor` | `string` | theme background | Background colour.            |

## Source

`components/ui/hollow-bloom.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Void Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface HollowBloomProps {
  speed?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the blooming marks. Defaults to the theme primary. */
  color?: string;
  /** Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];

const VERTEX_SHADER = `
attribute vec2 position;
void main() {
  gl_Position = vec4(position, 0.0, 1.0);
}
`;

const FRAGMENT_SHADER = `
precision highp float;
uniform vec2 iResolution;
uniform float iTime;
uniform vec2 uMouse;
uniform vec3 uTint;
uniform vec3 uInk;
uniform vec3 uPaper;

vec2 barrel(vec2 uv, float amt) {
  vec2 cc = uv - 0.5;
  float r = dot(cc, cc);
  return uv + cc * r * amt;
}

float rand(vec2 co) {
  return fract(sin(dot(co, vec2(12.9898,78.233))) * 43758.5453);
}

void main() {
  vec2 uv = gl_FragCoord.xy / iResolution.xy;

  // Parallax drift based on uMouse
  vec2 mouseOffset = (uMouse - 0.5) * 0.05;
  uv += mouseOffset;

  // Barrel distortion curvature
  uv = barrel(uv, 0.2);

  // Outside the lens is plain paper.
  if(uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {
    gl_FragColor = vec4(uPaper, 1.0);
    return;
  }

  // Coarser grid of diamond marks
  vec2 gridCount = vec2(64.0, 64.0 * (iResolution.y / iResolution.x));
  vec2 gridUv = fract(uv * gridCount) - 0.5;
  vec2 id = floor(uv * gridCount);

  vec2 cc = (id + 0.5) / gridCount - 0.5;
  cc.y *= iResolution.y / iResolution.x;
  float dist = length(cc);

  // Rings bloom inward, from the rim toward a hollow centre
  float pulse = sin(iTime * 1.2 + dist * 14.0) * 0.5 + 0.5;
  float hollow = smoothstep(0.04, 0.16, dist);

  float size = 0.42 * pulse * hollow;
  float d = abs(gridUv.x) + abs(gridUv.y);
  float mark = smoothstep(size, size - 0.06, d);

  float flicker = rand(vec2(floor(iTime * 4.0), id.y)) > 0.985 ? 0.35 : 1.0;
  float fade = smoothstep(0.75, 0.15, dist);

  // Inner rings ink in the accent; the outer ones settle into the foreground.
  vec3 ink = mix(uTint, uInk, smoothstep(0.15, 0.55, dist));
  vec3 col = mix(uPaper, ink, clamp(mark * flicker * fade, 0.0, 1.0));

  gl_FragColor = vec4(col, 1.0);
}
`;

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type)!;
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  return shader;
}

export function HollowBloom({
  speed = 0.8,
  hue = 0,
  saturation = 1,
  brightness = 1,
  color,
  backgroundColor,
  className,
}: HollowBloomProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const options = useRef({ speed });
  options.current = { speed };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const gl = canvas?.getContext("webgl", { alpha: true, antialias: false });
    if (!host || !canvas || !gl || !theme) return;

    const vertexShader = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fragmentShader = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const program = gl.createProgram()!;
    gl.attachShader(program, vertexShader);
    gl.attachShader(program, fragmentShader);
    gl.linkProgram(program);
    gl.useProgram(program);

    const buffer = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
    gl.bufferData(
      gl.ARRAY_BUFFER,
      new Float32Array([-1.0, -1.0, 1.0, -1.0, -1.0, 1.0, -1.0, 1.0, 1.0, -1.0, 1.0, 1.0]),
      gl.STATIC_DRAW,
    );
    const positionLocation = gl.getAttribLocation(program, "position");
    gl.enableVertexAttribArray(positionLocation);
    gl.vertexAttribPointer(positionLocation, 2, gl.FLOAT, false, 0, 0);

    const iResLoc = gl.getUniformLocation(program, "iResolution");
    const iTimeLoc = gl.getUniformLocation(program, "iTime");
    const uMouseLoc = gl.getUniformLocation(program, "uMouse");
    gl.uniform3fv(gl.getUniformLocation(program, "uTint"), color ? toRgb(color) : theme.primary);
    gl.uniform3fv(gl.getUniformLocation(program, "uInk"), theme.foreground);
    gl.uniform3fv(
      gl.getUniformLocation(program, "uPaper"),
      backgroundColor ? toRgb(backgroundColor) : theme.background,
    );

    // Interactive pointer drift tracking
    let mouseX = 0.5;
    let mouseY = 0.5;
    let elapsed = 0;
    let last = performance.now();
    let frame = 0;
    let visible = true;

    const draw = () => {
      gl.uniform2f(iResLoc, canvas.width, canvas.height);
      gl.uniform1f(iTimeLoc, elapsed);
      gl.uniform2f(uMouseLoc, mouseX, mouseY);
      gl.drawArrays(gl.TRIANGLES, 0, 6);
    };
    const tick = (now: number) => {
      elapsed += ((now - last) / 1000) * clamp(options.current.speed, 0, 3);
      last = now;
      draw();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || !visible || document.hidden || frame) return;
      last = performance.now();
      frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      canvas.width = canvas.clientWidth;
      canvas.height = canvas.clientHeight;
      gl.viewport(0, 0, canvas.width, canvas.height);
      draw();
    };
    const onPointerMove = (event: PointerEvent) => {
      const bounds = host.getBoundingClientRect();
      mouseX = (event.clientX - bounds.left) / Math.max(1, bounds.width);
      mouseY = 1.0 - (event.clientY - bounds.top) / Math.max(1, bounds.height);
      if (prefersReducedMotion) draw();
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    window.addEventListener("pointermove", onPointerMove, { passive: true });
    resizeObserver.observe(host);
    intersection.observe(host);
    if (prefersReducedMotion) elapsed = 1.2;
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      window.removeEventListener("pointermove", onPointerMove);
      gl.deleteBuffer(buffer);
      gl.deleteShader(vertexShader);
      gl.deleteShader(fragmentShader);
      gl.deleteProgram(program);
    };
  }, [prefersReducedMotion, theme, color, backgroundColor]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 isolate overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    >
      <canvas ref={canvasRef} aria-hidden="true" className="absolute inset-0 block h-full w-full" />
    </div>
  );
}
```

---

# Grain Swell

> A flowing field resolved through a dot screen, inked in your theme on the page ground.

Install: `npx @modus-ui/cli add grain-swell`

A flowing field resolved through a dot matrix, inked from theme tokens: `ripple` draws a soft two-tone dot screen, `swell` a Three.js point field rising from ground to crest. Light mode sets ink dots on paper, dark mode lifts them off the dark ground. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add grain-swell
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/grain-swell.tsx`.
4. Paste the code.

## Usage

```tsx
import { GrainSwell } from "@/components/ui/grain-swell";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <GrainSwell />
    </div>
  );
}
```

## Props

| Prop              | Type                    | Default                  | Description                                                                   |
| :---------------- | :---------------------- | :----------------------- | :---------------------------------------------------------------------------- |
| `variant`         | `"ripple"` \| `"swell"` | `"ripple"`               | Which dot renderer to show.                                                   |
| `speed`           | `number`                | `1`                      | Animation speed multiplier.                                                   |
| `size`            | `number`                | `1`                      | Point size multiplier (swell).                                                |
| `length`          | `number`                | `1`                      | Wave frequency multiplier (swell).                                            |
| `density`         | `number`                | `1`                      | Point density (swell).                                                        |
| `opacity`         | `number`                | `1`                      | Canvas opacity (swell).                                                       |
| `hue`             | `number`                | `0`                      | Hue rotation in degrees.                                                      |
| `saturation`      | `number`                | `1`                      | Saturation multiplier.                                                        |
| `brightness`      | `number`                | `1`                      | Brightness multiplier.                                                        |
| `colors`          | `string[]`              | Theme inks per `variant` | Ink colours: ground, body and crest for `swell`; top and bottom for `ripple`. |
| `backgroundColor` | `string`                | `hsl(var(--background))` | Colour behind the dots, any CSS colour.                                       |

## Source

`components/ui/grain-swell.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Halftone Flow and Amber Halftone (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export type GrainSwellVariant = "ripple" | "swell";

export interface GrainSwellProps {
  variant?: GrainSwellVariant;
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Ink colours: three (ground, body, crest) for `swell`, two (top, bottom) for `ripple`. Default to theme tokens. */
  colors?: string[];
  /** Colour behind the dots; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** Theme-derived inks for each variant, rebuilt when the theme changes. */
function themeInks(variant: GrainSwellVariant) {
  const theme = readTheme();
  const [ph, ps, pl] = theme.primary;
  const body = hsl([
    ph,
    Math.max(ps, 40),
    theme.dark ? Math.max(pl, 55) : Math.min(Math.max(pl, 30), 44),
  ]);
  const crest = theme.dark ? hsl([ph + 25, 45, 88]) : hsl(theme.foreground);
  const background = hsl(theme.background);
  return {
    background,
    colors: variant === "swell" ? [background, body, crest] : [body, hsl(theme.muted)],
  };
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

const FLOW_VERTEX_SHADER = `
attribute vec4 aVertexPosition;
void main() {
  gl_Position = aVertexPosition;
}
`;

// Fragment shader for the swell variant
const FLOW_FRAGMENT_SHADER = `
precision highp float;
uniform vec2 u_resolution;
uniform float u_time;
uniform vec3 u_dark;
uniform vec3 u_red;
uniform vec3 u_bright;

mat2 rot(float a) {
  float s = sin(a), c = cos(a);
  return mat2(c, -s, s, c);
}

void main() {
  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
  vec2 p = uv * 2.0 - 1.0;
  p.x *= u_resolution.x / u_resolution.y;

  vec2 flow_uv = p;
  float time = u_time * 0.4;

  for(float i = 1.0; i < 4.0; i++) {
    flow_uv *= rot(time * 0.1);
    flow_uv.x += sin(flow_uv.y * 2.0 * i + time) * 0.5;
    flow_uv.y += cos(flow_uv.x * 1.5 * i - time * 0.8) * 0.5;
  }

  float intensity = sin(flow_uv.x * 2.0 + flow_uv.y * 3.0) * 0.5 + 0.5;

  vec3 fluid_color = mix(u_dark, u_red, smoothstep(0.2, 0.6, intensity));
  fluid_color = mix(fluid_color, u_bright, smoothstep(0.7, 1.0, intensity));

  float gridSize = 9.0;
  vec2 grid_uv = gl_FragCoord.xy / gridSize;
  vec2 cell_uv = fract(grid_uv) - 0.5;

  float dist = length(cell_uv);
  float radius = intensity * 0.45;
  float dot_mask = smoothstep(radius, radius - 0.1, dist);

  vec3 final_color = mix(u_dark, fluid_color, dot_mask);
  final_color = mix(final_color, fluid_color, 0.12);

  gl_FragColor = vec4(final_color, 1.0);
}
`;

function glslFloat(value: number, digits = 3) {
  const fixed = Number(value).toFixed(digits);
  return fixed.includes(".") ? fixed : `${fixed}.0`;
}

/** Any CSS colour THREE can parse, as raw 0–1 channels for a shader uniform. */
function toVec3(color: string): [number, number, number] {
  const c = new THREE.Color().setStyle(color, THREE.LinearSRGBColorSpace);
  return [c.r, c.g, c.b];
}

type Scene = { setSize: () => void; draw: (time: number) => void; dispose: () => void };

function createFlowScene(
  canvas: HTMLCanvasElement,
  host: HTMLElement,
  colors: () => string[],
): Scene | null {
  const gl = canvas.getContext("webgl");
  if (!gl) return null;
  const compile = (type: number, source: string) => {
    const shader = gl.createShader(type)!;
    gl.shaderSource(shader, source);
    gl.compileShader(shader);
    return shader;
  };
  const vertexShader = compile(gl.VERTEX_SHADER, FLOW_VERTEX_SHADER);
  const fragmentShader = compile(gl.FRAGMENT_SHADER, FLOW_FRAGMENT_SHADER);
  const program = gl.createProgram()!;
  gl.attachShader(program, vertexShader);
  gl.attachShader(program, fragmentShader);
  gl.linkProgram(program);
  gl.useProgram(program);

  const positionBuffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer);
  gl.bufferData(
    gl.ARRAY_BUFFER,
    new Float32Array([-1.0, 1.0, 1.0, 1.0, -1.0, -1.0, 1.0, -1.0]),
    gl.STATIC_DRAW,
  );
  const positionLocation = gl.getAttribLocation(program, "aVertexPosition");
  gl.enableVertexAttribArray(positionLocation);
  gl.vertexAttribPointer(positionLocation, 2, gl.FLOAT, false, 0, 0);

  const resolutionLocation = gl.getUniformLocation(program, "u_resolution");
  const timeLocation = gl.getUniformLocation(program, "u_time");
  const darkLocation = gl.getUniformLocation(program, "u_dark");
  const redLocation = gl.getUniformLocation(program, "u_red");
  const brightLocation = gl.getUniformLocation(program, "u_bright");

  return {
    setSize() {
      canvas.width = host.offsetWidth;
      canvas.height = host.offsetHeight;
      gl.viewport(0, 0, canvas.width, canvas.height);
    },
    draw(time) {
      const [dark, red, bright] = colors();
      gl.uniform2f(resolutionLocation, canvas.width, canvas.height);
      gl.uniform1f(timeLocation, time);
      gl.uniform3fv(darkLocation, toVec3(dark));
      gl.uniform3fv(redLocation, toVec3(red));
      gl.uniform3fv(brightLocation, toVec3(bright));
      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
    },
    dispose() {
      gl.deleteBuffer(positionBuffer);
      gl.deleteShader(vertexShader);
      gl.deleteShader(fragmentShader);
      gl.deleteProgram(program);
    },
  };
}

function createRippleScene(
  canvas: HTMLCanvasElement,
  host: HTMLElement,
  knobs: { size: number; length: number; density: number },
  colors: () => string[],
  background: () => string,
): Scene {
  const renderer = new THREE.WebGLRenderer({ canvas, alpha: true, antialias: true });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
  const scene = new THREE.Scene();
  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
  camera.position.z = 1;

  // Density tightens spacing rather than growing the grid past the frustum.
  const spacing = Number((0.085 / Math.max(0.25, knobs.density)).toFixed(4));
  const gridSize = Math.max(12, Math.ceil(2.8 / spacing));
  const pointSize = Number((9 * knobs.size).toFixed(2));
  const wave = Number((6 * knobs.length).toFixed(2));

  const geometry = new THREE.BufferGeometry();
  const positions: number[] = [];
  const scales: number[] = [];
  for (let x = -gridSize; x <= gridSize; x++) {
    for (let y = -gridSize; y <= gridSize; y++) {
      positions.push(x * spacing, y * spacing, 0);
      scales.push(1);
    }
  }
  geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
  geometry.setAttribute("scale", new THREE.Float32BufferAttribute(scales, 1));

  const color1 = new THREE.Color();
  const color2 = new THREE.Color();
  const material = new THREE.ShaderMaterial({
    uniforms: {
      time: { value: 0 },
      color1: { value: color1 },
      color2: { value: color2 },
    },
    vertexShader: `
      attribute float scale;
      varying vec2 vUv;
      varying float vScale;
      uniform float time;

      void main() {
        vUv = position.xy;
        float dist = length(position.xy - vec2(-0.7, -0.45));
        float animatedScale = scale * (sin(dist * ${glslFloat(wave, 2)} - time * 2.5) * 0.5 + 0.5);
        vScale = animatedScale;

        gl_PointSize = animatedScale * ${glslFloat(pointSize, 2)};
        gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
      }
    `,
    fragmentShader: `
      uniform vec3 color1;
      uniform vec3 color2;
      varying vec2 vUv;
      varying float vScale;

      void main() {
        vec2 coord = gl_PointCoord - vec2(0.5);
        if(length(coord) > 0.5) discard;

        vec3 finalColor = mix(color2, color1, (vUv.y + 1.0) * 0.5);
        gl_FragColor = vec4(finalColor, vScale * 0.9);
      }
    `,
    transparent: true,
  });
  scene.add(new THREE.Points(geometry, material));

  return {
    setSize() {
      const width = Math.max(1, host.offsetWidth);
      const height = Math.max(1, host.offsetHeight);
      renderer.setSize(width, height, false);
      const aspect = width / height;
      camera.left = -aspect;
      camera.right = aspect;
      camera.bottom = -1;
      camera.top = 1;
      camera.updateProjectionMatrix();
    },
    draw(time) {
      const [first, second] = colors();
      // r128 had no colour management: write the hex values straight into the shader.
      color1.setStyle(first, THREE.LinearSRGBColorSpace);
      color2.setStyle(second, THREE.LinearSRGBColorSpace);
      renderer.setClearColor(background(), 1);
      material.uniforms.time.value = time;
      renderer.render(scene, camera);
    },
    dispose() {
      geometry.dispose();
      material.dispose();
      renderer.dispose();
    },
  };
}

export function GrainSwell({
  variant = "ripple",
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  colors,
  backgroundColor,
  className,
}: GrainSwellProps) {
  const prefersReducedMotion = useReducedMotion();
  const themeVersion = useThemeVersion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [inks, setInks] = useState<ReturnType<typeof themeInks> | null>(null);
  useEffect(() => setInks(themeInks(variant)), [variant, themeVersion]);
  const background = backgroundColor ?? inks?.background ?? "hsl(var(--background))";
  const options = useRef({ speed, colors: colors ?? inks?.colors ?? [], background });
  options.current = { speed, colors: colors ?? inks?.colors ?? [], background };
  const safeSize = clamp(size, 0.05, 200);
  const safeLength = clamp(length, 0.35, 2.5);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas || !inks) return;

    const getColors = () => options.current.colors;
    const scene =
      variant === "ripple"
        ? createRippleScene(
            canvas,
            host,
            { size: safeSize, length: safeLength, density: safeDensity },
            getColors,
            () => options.current.background,
          )
        : createFlowScene(canvas, host, getColors);
    if (!scene) return;

    let elapsed = prefersReducedMotion ? 2 : 0;
    let last = performance.now();
    let frame = 0;
    let visible = true;

    const tick = (now: number) => {
      elapsed += ((now - last) / 1000) * clamp(options.current.speed, 0, 3);
      last = now;
      scene.draw(elapsed);
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || !visible || document.hidden || frame) return;
      last = performance.now();
      frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      scene.setSize();
      scene.draw(elapsed);
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    resizeObserver.observe(host);
    intersection.observe(host);
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      scene.dispose();
    };
  }, [prefersReducedMotion, variant, safeSize, safeLength, safeDensity, inks]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background, filter }}
    >
      {/* A fresh canvas per variant: a canvas keeps the first context type it is given. */}
      <canvas
        key={variant}
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: variant === "ripple" ? clamp(opacity, 0.05, 1) : undefined }}
      />
    </div>
  );
}
```

---

# Ridge Strata

> Layered ink-wash ridges drifting in parallax, rimmed in the theme's primary.

Install: `npx @modus-ui/cli add ridge-strata`

Five parallax ridges in an ink-wash ramp from the theme background to its foreground, each rimmed with a hairline of primary, with faint primary stars and an occasional streak above. The ridges drift and follow the pointer. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ridge-strata
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ridge-strata.tsx`.
3. Paste the code.

## Usage

```tsx
import { RidgeStrata } from "@/components/ui/ridge-strata";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <RidgeStrata />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default     | Description                                                         |
| :---------------- | :------- | :---------- | :------------------------------------------------------------------ |
| `speed`           | `number` | `1`         | Animation speed multiplier.                                         |
| `hue`             | `number` | `0`         | Hue rotation in degrees.                                            |
| `saturation`      | `number` | `1`         | Saturation multiplier.                                              |
| `brightness`      | `number` | `1`         | Brightness multiplier.                                              |
| `backgroundColor` | `string` | `undefined` | CSS background behind the canvas. Defaults to the theme background. |

## Source

`components/ui/ridge-strata.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Cloud Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface RidgeStrataProps {
  speed?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** CSS background behind the canvas. Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

const VERTEX_SHADER = `
attribute vec2 a_pos;
void main(){ gl_Position = vec4(a_pos, 0.0, 1.0); }
`;

const FRAGMENT_SHADER = `
precision highp float;
uniform vec2 u_res;
uniform float u_time;
uniform vec2 u_mouse;
uniform vec3 u_bg;
uniform vec3 u_ink;
uniform vec3 u_accent;

float hash(float n){ return fract(sin(n)*43758.5453123); }
float hash2(vec2 p){ return fract(sin(dot(p, vec2(127.1,311.7)))*43758.5453); }

float noise(float x){
    float i = floor(x);
    float f = fract(x);
    f = f*f*(3.0-2.0*f);
    return mix(hash(i), hash(i+1.0), f);
}

float fbm(float x, float octaves){
    float val = 0.0;
    float amp = 0.5;
    float freq = 1.0;
    for(int i = 0; i < 6; i++){
        if(float(i) >= octaves) break;
        val += amp * noise(x * freq);
        freq *= 2.17;
        amp *= 0.48;
    }
    return val;
}

float meteor(vec2 uv, float t){
    float cycle = mod(t * 0.15, 1.0);
    float seed = floor(t * 0.15);
    float h = hash(seed * 7.31);
    float h2 = hash(seed * 13.17);
    if(h > 0.30) return 0.0;
    vec2 start = vec2(0.2 + h2 * 0.6, 0.7 + h * 0.25);
    vec2 dir = normalize(vec2(1.0, -0.6 - h * 0.3));
    float progress = smoothstep(0.0, 0.7, cycle);
    vec2 pos = start + dir * progress * 0.5;
    vec2 toP = uv - pos;
    float along = dot(toP, dir);
    float perp = length(toP - dir * along);
    float trail = smoothstep(0.0, -0.12, along) * smoothstep(-0.18, -0.04, along);
    float core = smoothstep(0.003, 0.0, perp) * trail;
    float glow = smoothstep(0.012, 0.0, perp) * trail * 0.3;
    float fade = smoothstep(0.0, 0.1, cycle) * smoothstep(0.8, 0.55, cycle);
    return (core + glow) * fade;
}

float stars(vec2 uv, float density){
    vec2 cell = floor(uv * density);
    vec2 sub = fract(uv * density);
    float h = hash2(cell);
    float brightness = step(0.975, h);
    float size = 0.025 + h * 0.045;
    float d = length(sub - vec2(hash2(cell + 100.0), hash2(cell + 200.0)));
    float star = brightness * smoothstep(size, 0.0, d);
    star *= 0.5 + 0.5 * sin(u_time * (1.0 + h * 3.0) + h * 6.28);
    return star;
}

void main(){
    vec2 uv = gl_FragCoord.xy / u_res;
    float aspect = u_res.x / u_res.y;
    vec2 mouse = u_mouse * 2.0 - 1.0;

    // Paper (or night) sky with a faint accent wash low on the horizon.
    vec3 col = u_bg;
    float horizonY = 0.42;
    float wash = exp(-pow((uv.y - horizonY) * 3.2, 2.0)) * exp(-pow((uv.x - 0.72) * 1.4, 2.0));
    col = mix(col, u_accent, wash * 0.22);

    float starField = stars(uv * vec2(aspect, 1.0), 60.0)
                    + stars(uv * vec2(aspect, 1.0) + 500.0, 100.0) * 0.7;
    float starMask = 1.0;
    float xC, yS, prof, mTop, mtn, rim;

    // Ridge 0: ink deepens toward the front.
    xC = uv.x * aspect * 1.6 - u_time * 0.006 + mouse.x * 0.010;
    yS = mouse.y * 0.003;
    prof = fbm(xC, 5.0) * 0.10 + fbm(xC * 0.3 + 17.0, 3.0) * 0.07;
    mTop = 0.46 + prof + yS;
    mtn = smoothstep(mTop + 0.003, mTop - 0.001, uv.y);
    rim = smoothstep(0.006, 0.0, abs(uv.y - mTop));
    col = mix(col, mix(u_bg, u_ink, 0.10), mtn);
    col = mix(col, u_accent, rim * 0.55);
    starMask *= (1.0 - mtn);

    // Ridge 1: ink deepens toward the front.
    xC = uv.x * aspect * 2.0 - u_time * 0.012 + mouse.x * 0.020;
    yS = mouse.y * 0.006;
    prof = fbm(xC, 5.0) * 0.13 + fbm(xC * 0.3 + 34.0, 3.0) * 0.091;
    mTop = 0.38 + prof + yS;
    mtn = smoothstep(mTop + 0.003, mTop - 0.001, uv.y);
    rim = smoothstep(0.006, 0.0, abs(uv.y - mTop));
    col = mix(col, mix(u_bg, u_ink, 0.22), mtn);
    col = mix(col, u_accent, rim * 0.55);
    starMask *= (1.0 - mtn);

    // Ridge 2: ink deepens toward the front.
    xC = uv.x * aspect * 2.6 - u_time * 0.020 + mouse.x * 0.034;
    yS = mouse.y * 0.010;
    prof = fbm(xC, 5.0) * 0.16 + fbm(xC * 0.3 + 51.0, 3.0) * 0.112;
    mTop = 0.30 + prof + yS;
    mtn = smoothstep(mTop + 0.003, mTop - 0.001, uv.y);
    rim = smoothstep(0.006, 0.0, abs(uv.y - mTop));
    col = mix(col, mix(u_bg, u_ink, 0.36), mtn);
    col = mix(col, u_accent, rim * 0.55);
    starMask *= (1.0 - mtn);

    // Ridge 3: ink deepens toward the front.
    xC = uv.x * aspect * 3.2 - u_time * 0.030 + mouse.x * 0.050;
    yS = mouse.y * 0.015;
    prof = fbm(xC, 5.0) * 0.14 + fbm(xC * 0.3 + 68.0, 3.0) * 0.098;
    mTop = 0.21 + prof + yS;
    mtn = smoothstep(mTop + 0.003, mTop - 0.001, uv.y);
    rim = smoothstep(0.006, 0.0, abs(uv.y - mTop));
    col = mix(col, mix(u_bg, u_ink, 0.52), mtn);
    col = mix(col, u_accent, rim * 0.55);
    starMask *= (1.0 - mtn);

    // Ridge 4: ink deepens toward the front.
    xC = uv.x * aspect * 4.0 - u_time * 0.044 + mouse.x * 0.070;
    yS = mouse.y * 0.021;
    prof = fbm(xC, 5.0) * 0.11 + fbm(xC * 0.3 + 85.0, 3.0) * 0.077;
    mTop = 0.11 + prof + yS;
    mtn = smoothstep(mTop + 0.003, mTop - 0.001, uv.y);
    rim = smoothstep(0.006, 0.0, abs(uv.y - mTop));
    col = mix(col, mix(u_bg, u_ink, 0.70), mtn);
    col = mix(col, u_accent, rim * 0.55);
    starMask *= (1.0 - mtn);

    col = mix(col, u_accent, clamp(starField * starMask, 0.0, 1.0) * 0.7);
    float met = meteor(uv * vec2(aspect, 1.0), u_time);
    col = mix(col, u_accent, clamp(met * starMask, 0.0, 1.0));

    float vig = clamp(0.28 * pow(length((uv - 0.5) * vec2(1.1, 1.6)), 2.0), 0.0, 1.0);
    col = mix(col, u_ink, vig * 0.12);

    gl_FragColor = vec4(col, 1.0);
}
`;

const TOKENS = [
  "primary",
  "foreground",
  "background",
  "muted-foreground",
  "border",
  "card",
] as const;
type Tokens = Record<(typeof TOKENS)[number], string>;

/** Bare HSL channels of the Modus theme tokens, re-read when the theme or palette changes. */
function useThemeTokens(): Tokens | null {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const next = Object.fromEntries(
        TOKENS.map((name) => [name, style.getPropertyValue(`--${name}`).trim()]),
      ) as Tokens;
      setTokens((prev) => (prev && TOKENS.every((k) => prev[k] === next[k]) ? prev : next));
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

/** Bare HSL channels ("h s% l%") to 0–1 RGB. */
function channelsToRgb(channels: string): [number, number, number] {
  const [h, s, l] = channels.split(/\s+/).map((part) => parseFloat(part));
  const sat = (s || 0) / 100;
  const lig = (l || 0) / 100;
  const k = (n: number) => (n + (h || 0) / 30) % 12;
  const a = sat * Math.min(lig, 1 - lig);
  const f = (n: number) => lig - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
  return [f(0), f(8), f(4)];
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

function compile(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type)!;
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  return shader;
}

export function RidgeStrata({
  speed = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
  className,
}: RidgeStrataProps) {
  const tokens = useThemeTokens();
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = speed;

  useEffect(() => {
    if (!tokens) return;
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const gl = canvas?.getContext("webgl", {
      antialias: true,
      alpha: false,
      preserveDrawingBuffer: true,
    });
    if (!host || !canvas || !gl) return;

    const vs = compile(gl, gl.VERTEX_SHADER, VERTEX_SHADER);
    const fs = compile(gl, gl.FRAGMENT_SHADER, FRAGMENT_SHADER);
    const prog = gl.createProgram()!;
    gl.attachShader(prog, vs);
    gl.attachShader(prog, fs);
    gl.linkProgram(prog);
    gl.useProgram(prog);

    const buf = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), gl.STATIC_DRAW);
    const aPos = gl.getAttribLocation(prog, "a_pos");
    gl.enableVertexAttribArray(aPos);
    gl.vertexAttribPointer(aPos, 2, gl.FLOAT, false, 0, 0);

    const uRes = gl.getUniformLocation(prog, "u_res");
    const uTime = gl.getUniformLocation(prog, "u_time");
    const uMouse = gl.getUniformLocation(prog, "u_mouse");
    gl.uniform3f(gl.getUniformLocation(prog, "u_bg"), ...channelsToRgb(tokens.background));
    gl.uniform3f(gl.getUniformLocation(prog, "u_ink"), ...channelsToRgb(tokens.foreground));
    gl.uniform3f(gl.getUniformLocation(prog, "u_accent"), ...channelsToRgb(tokens.primary));

    let mx = 0.5;
    let my = 0.5;
    let smx = 0.5;
    let smy = 0.5;
    let elapsed = 0;
    let last = performance.now();
    let frame = 0;
    let visible = true;

    const draw = () => {
      gl.uniform2f(uRes, canvas.width, canvas.height);
      gl.uniform1f(uTime, elapsed);
      gl.uniform2f(uMouse, smx, smy);
      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
    };
    const tick = (now: number) => {
      elapsed += ((now - last) / 1000) * clamp(speedRef.current, 0, 3);
      last = now;
      smx += (mx - smx) * 0.04;
      smy += (my - smy) * 0.04;
      draw();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (prefersReducedMotion || !visible || document.hidden || frame) return;
      last = performance.now();
      frame = requestAnimationFrame(tick);
    };
    const resize = () => {
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = host.offsetWidth * dpr;
      canvas.height = host.offsetHeight * dpr;
      gl.viewport(0, 0, canvas.width, canvas.height);
      draw();
    };
    const onPointerMove = (event: PointerEvent) => {
      const bounds = host.getBoundingClientRect();
      mx = (event.clientX - bounds.left) / Math.max(1, bounds.width);
      my = 1.0 - (event.clientY - bounds.top) / Math.max(1, bounds.height);
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    if (!prefersReducedMotion)
      window.addEventListener("pointermove", onPointerMove, { passive: true });
    resizeObserver.observe(host);
    intersection.observe(host);
    if (prefersReducedMotion) elapsed = 4;
    resize();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      window.removeEventListener("pointermove", onPointerMove);
      gl.deleteBuffer(buf);
      gl.deleteShader(vs);
      gl.deleteShader(fs);
      gl.deleteProgram(prog);
    };
  }, [prefersReducedMotion, tokens]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    >
      <canvas ref={canvasRef} aria-hidden="true" className="absolute inset-0 block h-full w-full" />
    </div>
  );
}
```

---

# Drift Lines

> Thousands of fine strokes drifting along a simplex-noise current, drawn in your theme's inks.

Install: `npx @modus-ui/cli add drift-lines`

A canvas of particles tracing a 3D simplex-noise current, each leaving a fading stroke and parting gently around the pointer. The strokes are five inks on the theme's primary hue laid over the theme background, so it reads as pen work on paper in light mode and as light trails in dark mode, following the palette picker. It fills its positioned parent, pauses when off screen and renders a settled frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add drift-lines
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/drift-lines.tsx`.
3. Paste the code.

## Usage

```tsx
import { DriftLines } from "@/components/ui/drift-lines";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <DriftLines />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type       | Default          | Description                                              |
| :---------------- | :--------- | :--------------- | :------------------------------------------------------- |
| `speed`           | `number`   | `1`              | Animation speed multiplier.                              |
| `size`            | `number`   | `1`              | Stroke width multiplier.                                 |
| `length`          | `number`   | `1`              | Noise scale; higher values give longer, smoother curves. |
| `density`         | `number`   | `1`              | Particle count multiplier (2500 at 1).                   |
| `opacity`         | `number`   | `1`              | Canvas opacity.                                          |
| `hue`             | `number`   | `0`              | Hue rotation in degrees.                                 |
| `saturation`      | `number`   | `1`              | Saturation multiplier.                                   |
| `brightness`      | `number`   | `1`              | Brightness multiplier.                                   |
| `colors`          | `string[]` | theme inks       | Palette mapped across the noise field.                   |
| `backgroundColor` | `string`   | theme background | Background and trail fade colour.                        |

## Source

`components/ui/drift-lines.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Flow Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface DriftLinesProps {
  speed?: number;
  size?: number;
  length?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Line colours; defaults to five inks on the theme's primary hue. */
  colors?: string[];
  /** Colour behind the lines; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

type RGB = { r: number; g: number; b: number };

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** Any CSS colour to RGB, by letting a 1px canvas parse it. */
function toRgb(color: string): RGB {
  const ctx = document.createElement("canvas").getContext("2d");
  if (!ctx) return { r: 0, g: 0, b: 0 };
  ctx.fillStyle = color;
  ctx.fillRect(0, 0, 1, 1);
  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
  return { r, g, b };
}

/** Five inks on the primary hue: deep to light on a dark ground, light to deep on paper. */
function themeInks(): string[] {
  const { dark, primary } = readTheme();
  const [h, s] = primary;
  const sat = Math.max(s, dark ? 14 : 38);
  const steps = dark ? [40, 54, 68, 80, 92] : [16, 26, 36, 46, 56];
  return steps.map((l, i) => hsl([h - 30 + i * 10, sat + i * 4, l]));
}

// Simplex noise (compact implementation), based on Stefan Gustavson's simplex noise.
const F3 = 1 / 3;
const G3 = 1 / 6;
const GRAD3 = [
  [1, 1, 0],
  [-1, 1, 0],
  [1, -1, 0],
  [-1, -1, 0],
  [1, 0, 1],
  [-1, 0, 1],
  [1, 0, -1],
  [-1, 0, -1],
  [0, 1, 1],
  [0, -1, 1],
  [0, 1, -1],
  [0, -1, -1],
];

function createNoise3D(initialSeed: number) {
  const perm = new Uint8Array(512);
  const permMod12 = new Uint8Array(512);
  const p = new Uint8Array(256);
  let seed = initialSeed;
  for (let i = 0; i < 256; i++) p[i] = i;
  for (let i = 255; i > 0; i--) {
    seed = (seed * 16807 + 0) % 2147483647;
    const j = seed % (i + 1);
    const tmp = p[i];
    p[i] = p[j];
    p[j] = tmp;
  }
  for (let i = 0; i < 512; i++) {
    perm[i] = p[i & 255];
    permMod12[i] = perm[i] % 12;
  }

  return (xin: number, yin: number, zin: number) => {
    let n0, n1, n2, n3;
    const s = (xin + yin + zin) * F3;
    const i = Math.floor(xin + s),
      j = Math.floor(yin + s),
      k = Math.floor(zin + s);
    const t = (i + j + k) * G3;
    const x0 = xin - (i - t),
      y0 = yin - (j - t),
      z0 = zin - (k - t);
    let i1, j1, k1, i2, j2, k2;
    if (x0 >= y0) {
      if (y0 >= z0) [i1, j1, k1, i2, j2, k2] = [1, 0, 0, 1, 1, 0];
      else if (x0 >= z0) [i1, j1, k1, i2, j2, k2] = [1, 0, 0, 1, 0, 1];
      else [i1, j1, k1, i2, j2, k2] = [0, 0, 1, 1, 0, 1];
    } else {
      if (y0 < z0) [i1, j1, k1, i2, j2, k2] = [0, 0, 1, 0, 1, 1];
      else if (x0 < z0) [i1, j1, k1, i2, j2, k2] = [0, 1, 0, 0, 1, 1];
      else [i1, j1, k1, i2, j2, k2] = [0, 1, 0, 1, 1, 0];
    }
    const x1 = x0 - i1 + G3,
      y1 = y0 - j1 + G3,
      z1 = z0 - k1 + G3;
    const x2 = x0 - i2 + 2 * G3,
      y2 = y0 - j2 + 2 * G3,
      z2 = z0 - k2 + 2 * G3;
    const x3 = x0 - 1 + 3 * G3,
      y3 = y0 - 1 + 3 * G3,
      z3 = z0 - 1 + 3 * G3;
    const ii = i & 255,
      jj = j & 255,
      kk = k & 255;
    let t0 = 0.6 - x0 * x0 - y0 * y0 - z0 * z0;
    if (t0 < 0) n0 = 0;
    else {
      t0 *= t0;
      const g = GRAD3[permMod12[ii + perm[jj + perm[kk]]]];
      n0 = t0 * t0 * (g[0] * x0 + g[1] * y0 + g[2] * z0);
    }
    let t1 = 0.6 - x1 * x1 - y1 * y1 - z1 * z1;
    if (t1 < 0) n1 = 0;
    else {
      t1 *= t1;
      const g = GRAD3[permMod12[ii + i1 + perm[jj + j1 + perm[kk + k1]]]];
      n1 = t1 * t1 * (g[0] * x1 + g[1] * y1 + g[2] * z1);
    }
    let t2 = 0.6 - x2 * x2 - y2 * y2 - z2 * z2;
    if (t2 < 0) n2 = 0;
    else {
      t2 *= t2;
      const g = GRAD3[permMod12[ii + i2 + perm[jj + j2 + perm[kk + k2]]]];
      n2 = t2 * t2 * (g[0] * x2 + g[1] * y2 + g[2] * z2);
    }
    let t3 = 0.6 - x3 * x3 - y3 * y3 - z3 * z3;
    if (t3 < 0) n3 = 0;
    else {
      t3 *= t3;
      const g = GRAD3[permMod12[ii + 1 + perm[jj + 1 + perm[kk + 1]]]];
      n3 = t3 * t3 * (g[0] * x3 + g[1] * y3 + g[2] * z3);
    }
    return 32 * (n0 + n1 + n2 + n3);
  };
}

export function DriftLines({
  speed = 1,
  size = 1,
  length = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  colors,
  backgroundColor,
  className,
}: DriftLinesProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const theme = useThemeVersion();
  const options = useRef({ speed, size, length, colors, backgroundColor });
  options.current = { speed, size, length, colors, backgroundColor };
  const particleCount = Math.max(300, Math.round(2500 * clamp(density, 0.25, 2.5)));

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const context = canvas?.getContext("2d");
    if (!host || !canvas || !context) return;
    const ctx: CanvasRenderingContext2D = context;

    const noise3D = createNoise3D(42);
    const SPEED = 1.2;
    const MOUSE_RADIUS = 150;
    const MOUSE_FORCE = 2.5;
    let W = 0;
    let H = 0;
    let time = 0;
    let frame = 0;
    let visible = true;
    const mouse = { x: -9999, y: -9999, active: false };
    let particles: { x: number; y: number; speed: number; alpha: number; size: number }[] = [];

    // Resolved once per change of colours or theme, not per particle.
    let colorKey = "";
    let palette: RGB[] = [];
    let bg: RGB = { r: 0, g: 0, b: 0 };
    const resolveColors = () => {
      const { colors: custom, backgroundColor: ground } = options.current;
      const key = JSON.stringify([custom, ground]);
      if (key === colorKey) return;
      colorKey = key;
      palette = (custom?.length ? custom : themeInks()).map(toRgb);
      bg = toRgb(ground ?? hsl(readTheme().background));
    };
    resolveColors();

    const fillBackground = () => {
      ctx.fillStyle = `rgb(${bg.r}, ${bg.g}, ${bg.b})`;
      ctx.fillRect(0, 0, W, H);
    };

    const resize = () => {
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      W = host.offsetWidth;
      H = host.offsetHeight;
      canvas.width = W * dpr;
      canvas.height = H * dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      // Fill with background on resize to avoid flash
      fillBackground();
      if (prefersReducedMotion) for (let i = 0; i < 120; i++) step();
    };
    resize();

    particles = Array.from({ length: particleCount }, () => ({
      x: Math.random() * W,
      y: Math.random() * H,
      speed: 0.4 + Math.random() * 1.0,
      alpha: 0.15 + Math.random() * 0.55,
      size: 0.5 + Math.random() * 1.5,
    }));

    function getColor(noiseVal: number) {
      // Map noise [-1,1] to palette index
      const t = (noiseVal + 1) * 0.5;
      const idx = t * (palette.length - 1);
      const i = Math.floor(idx);
      const f = idx - i;
      const a = palette[Math.min(i, palette.length - 1)];
      const b = palette[Math.min(i + 1, palette.length - 1)];
      return { r: a.r + (b.r - a.r) * f, g: a.g + (b.g - a.g) * f, b: a.b + (b.b - a.b) * f };
    }

    function step() {
      const o = options.current;
      const speedScale = clamp(o.speed, 0, 3);
      const noiseScale = Number((0.0025 / clamp(o.length, 0.35, 2.5)).toFixed(6));
      const lineScale = Number(clamp(o.size, 0.05, 200).toFixed(3));
      resolveColors();

      // Fade the previous frame toward the ground — creates trailing effect
      ctx.fillStyle = `rgba(${bg.r}, ${bg.g}, ${bg.b}, 0.03)`;
      ctx.fillRect(0, 0, W, H);
      time += 0.0008 * speedScale;

      for (const p of particles) {
        const nx = p.x * noiseScale;
        const ny = p.y * noiseScale;
        const angle = noise3D(nx, ny, time) * Math.PI * 2;
        const colorNoise = noise3D(nx * 1.5 + 100, ny * 1.5 + 100, time * 0.5);
        let vx = Math.cos(angle) * p.speed * SPEED * speedScale;
        let vy = Math.sin(angle) * p.speed * SPEED * speedScale;

        // Mouse interaction — gentle push away
        if (mouse.active) {
          const dx = p.x - mouse.x;
          const dy = p.y - mouse.y;
          const dist = Math.sqrt(dx * dx + dy * dy);
          if (dist < MOUSE_RADIUS && dist > 0) {
            const force = (1 - dist / MOUSE_RADIUS) * MOUSE_FORCE;
            vx += (dx / dist) * force;
            vy += (dy / dist) * force;
          }
        }

        const px = p.x;
        const py = p.y;
        p.x += vx;
        p.y += vy;

        const color = getColor(colorNoise);
        ctx.beginPath();
        ctx.moveTo(px, py);
        ctx.lineTo(p.x, p.y);
        ctx.strokeStyle = `rgba(${Math.round(color.r)},${Math.round(color.g)},${Math.round(color.b)},${p.alpha})`;
        ctx.lineWidth = p.size * lineScale;
        ctx.stroke();

        // Respawn if offscreen
        if (p.x < -20 || p.x > W + 20 || p.y < -20 || p.y > H + 20) {
          p.x = Math.random() * W;
          p.y = Math.random() * H;
        }
      }
    }

    const tick = () => {
      step();
      frame = visible && !document.hidden ? requestAnimationFrame(tick) : 0;
    };
    const start = () => {
      if (!prefersReducedMotion && visible && !document.hidden && !frame)
        frame = requestAnimationFrame(tick);
    };

    // Listen on window so content layered above the field still steers it.
    const onPointerMove = (event: PointerEvent) => {
      const bounds = host.getBoundingClientRect();
      mouse.x = event.clientX - bounds.left;
      mouse.y = event.clientY - bounds.top;
      mouse.active =
        mouse.x >= 0 && mouse.y >= 0 && mouse.x <= bounds.width && mouse.y <= bounds.height;
    };
    const onPointerLeave = () => {
      mouse.active = false;
    };

    const resizeObserver = new ResizeObserver(resize);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (visible) start();
      else if (frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      }
    });
    const onVisibility = () => !document.hidden && start();
    document.addEventListener("visibilitychange", onVisibility);
    window.addEventListener("pointermove", onPointerMove, { passive: true });
    document.documentElement.addEventListener("pointerleave", onPointerLeave);
    resizeObserver.observe(host);
    intersection.observe(host);
    if (prefersReducedMotion) for (let i = 0; i < 120; i++) step();
    start();

    return () => {
      if (frame) cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      intersection.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      window.removeEventListener("pointermove", onPointerMove);
      document.documentElement.removeEventListener("pointerleave", onPointerLeave);
    };
  }, [prefersReducedMotion, particleCount, theme]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="absolute inset-0 block h-full w-full"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Loom Field

> A Three.js Verlet cloth printed with Modus type in the theme ink, plus three dramatic cloths — iridescent silk, a flown folio flag and a washi noren.

Install: `npx @modus-ui/cli add loom-field`

A Verlet-simulated sheet of fabric with its wordmark printed or woven into a procedural textile, so every letter deforms with the folds. Four variants share the same sheet: the default `linen`, printed in `--primary` and `--foreground` on `--card` with the theme heading face and redrawn whenever the theme or palette changes, an iridescent silk with bloom, a folio flag flown from a mast and a three-panel washi noren in front of a glowing shoji. It fills its positioned parent, pauses when off screen or when the tab is hidden, and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add loom-field
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/loom-field.tsx`.
4. Paste the code.

## Usage

```tsx
import { LoomField } from "@/components/ui/loom-field";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <LoomField variant="iridescent" />
    </div>
  );
}
```

## Props

| Prop              | Type                                              | Default                                                     | Description                                      |
| :---------------- | :------------------------------------------------ | :---------------------------------------------------------- | :----------------------------------------------- |
| `variant`         | `"linen" \| "iridescent" \| "atelier" \| "washi"` | `"linen"`                                                   | Which cloth to render.                           |
| `hue`             | `number`                                          | `0`                                                         | Hue rotation in degrees, clamped to -180 to 180. |
| `saturation`      | `number`                                          | `1`                                                         | Saturation multiplier, clamped to 0 to 2.        |
| `brightness`      | `number`                                          | `1`                                                         | Brightness multiplier, clamped to 0.35 to 1.65.  |
| `backgroundColor` | `string`                                          | the theme background for `linen`, a dark backdrop otherwise | Colour behind the canvas.                        |

## Source

`components/ui/loom-field.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's WovenCloth (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export type LoomFieldVariant = "linen" | "iridescent" | "atelier" | "washi";

interface LoomFieldProps {
  variant?: LoomFieldVariant;
  hue?: number;
  saturation?: number;
  brightness?: number;
  backgroundColor?: string;
  className?: string;
}

/** The theme heading face, resolved for canvas text. */
function headingFont() {
  return (
    getComputedStyle(document.documentElement).getPropertyValue("--font-heading").trim() ||
    "Georgia, serif"
  );
}
const MONO_FONT = "ui-monospace, SFMono-Regular, Menlo, monospace";

/** Reads the theme tokens the linen variant is printed and lit with. */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const token = (name: string) => `hsl(${style.getPropertyValue(`--${name}`).trim()})`;
  return {
    paper: token("card"),
    muted: token("muted"),
    ink: token("primary"),
    text: token("foreground"),
    heading: headingFont(),
    // three.js parses the comma form of hsl()
    inkLight: `hsl(${style.getPropertyValue("--primary").trim().split(/\s+/).join(", ")})`,
  };
}
type Theme = ReturnType<typeof readTheme>;

const BACKGROUNDS: Record<LoomFieldVariant, string> = {
  linen: "hsl(var(--background))",
  iridescent: "#05060d",
  atelier: "#12100d",
  washi: "#0d0a07",
};

const VIGNETTES: Record<LoomFieldVariant, string> = {
  linen: "radial-gradient(90% 80% at 50% 46%, transparent 55%, hsl(var(--background) / .9) 100%)",
  iridescent: "radial-gradient(78% 70% at 50% 44%, transparent 46%, rgba(3,4,10,.78) 100%)",
  atelier: "radial-gradient(84% 76% at 46% 42%, transparent 50%, rgba(14,12,10,.72) 100%)",
  washi: "radial-gradient(80% 74% at 50% 44%, transparent 46%, rgba(10,7,5,.80) 100%)",
};

type Runtime = {
  /** Steps of the simulation run before the first frame. */
  warm: number;
  /** Steps run before the still frame when motion is reduced. */
  still: number;
  step: (t: number) => void;
  commit: () => void;
  draw: (t: number) => void;
  fit: (w: number, h: number) => void;
  dispose: () => void;
};

type Disposable = { dispose: () => void };

const DT = 0.016;

function surface(w: number, h: number) {
  const canvas = document.createElement("canvas");
  canvas.width = w;
  canvas.height = h;
  const ctx = canvas.getContext("2d", { willReadFrequently: true }) as CanvasRenderingContext2D;
  return { canvas, ctx };
}

/* --------------------------------------------------------------- verlet --
   The shared Verlet sheet every cloth hangs from: integrate, satisfy the
   structural links a few times, then hold the pinned edge. */
type SheetOptions = {
  GX: number;
  GY: number;
  GRAV: number;
  DAMP: number;
  iterations: number;
  pin: (ix: number, iy: number) => boolean;
  wind: (ix: number, iy: number, t: number) => [number, number, number];
  linked?: (ix: number, iy: number) => boolean;
  restD?: number;
  hold: (cur: Float32Array, prev: Float32Array, rest: Float32Array, t: number) => void;
};

function createSheet(geo: THREE.PlaneGeometry, BW: number, BH: number, o: SheetOptions) {
  const { GX, GY, GRAV, DAMP } = o;
  const pos = geo.attributes.position as THREE.BufferAttribute;
  const N = (GX + 1) * (GY + 1);
  const cur = new Float32Array(N * 3);
  const prev = new Float32Array(N * 3);
  const rest = new Float32Array(N * 3);
  const pinned = new Uint8Array(N);
  const idx = (ix: number, iy: number) => ix + iy * (GX + 1);

  for (let i = 0; i < N; i++) {
    const ax = pos.getX(i);
    const ay = pos.getY(i);
    cur[i * 3] = prev[i * 3] = rest[i * 3] = ax;
    cur[i * 3 + 1] = prev[i * 3 + 1] = rest[i * 3 + 1] = ay;
    cur[i * 3 + 2] = prev[i * 3 + 2] = rest[i * 3 + 2] = 0;
  }
  for (let iy = 0; iy <= GY; iy++)
    for (let ix = 0; ix <= GX; ix++) if (o.pin(ix, iy)) pinned[idx(ix, iy)] = 1;

  const restH = BW / GX;
  const restV = BH / GY;
  const linked = o.linked ?? (() => true);

  function solve(a: number, b: number, rl: number) {
    const ax = cur[a * 3];
    const ay = cur[a * 3 + 1];
    const az = cur[a * 3 + 2];
    let dx = cur[b * 3] - ax;
    let dy = cur[b * 3 + 1] - ay;
    let dz = cur[b * 3 + 2] - az;
    const d = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1e-6;
    const diff = ((d - rl) / d) * 0.5;
    dx *= diff;
    dy *= diff;
    dz *= diff;
    const pa = pinned[a];
    const pb = pinned[b];
    if (!pa && !pb) {
      cur[a * 3] += dx;
      cur[a * 3 + 1] += dy;
      cur[a * 3 + 2] += dz;
      cur[b * 3] -= dx;
      cur[b * 3 + 1] -= dy;
      cur[b * 3 + 2] -= dz;
    } else if (pa && !pb) {
      cur[b * 3] -= dx * 2;
      cur[b * 3 + 1] -= dy * 2;
      cur[b * 3 + 2] -= dz * 2;
    } else if (!pa && pb) {
      cur[a * 3] += dx * 2;
      cur[a * 3 + 1] += dy * 2;
      cur[a * 3 + 2] += dz * 2;
    }
  }

  function step(t: number) {
    for (let iy = 0; iy <= GY; iy++) {
      for (let ix = 0; ix <= GX; ix++) {
        const i = idx(ix, iy);
        if (pinned[i]) continue;
        const f = o.wind(ix, iy, t);
        for (let k = 0; k < 3; k++) {
          const j = i * 3 + k;
          const a = k === 0 ? f[0] : k === 1 ? f[1] + GRAV : f[2];
          const v = (cur[j] - prev[j]) * DAMP;
          prev[j] = cur[j];
          cur[j] = cur[j] + v + a * DT * DT;
        }
      }
    }
    for (let it = 0; it < o.iterations; it++) {
      for (let iy = 0; iy <= GY; iy++)
        for (let ix = 0; ix < GX; ix++)
          if (linked(ix, iy)) solve(idx(ix, iy), idx(ix + 1, iy), restH);
      for (let iy = 0; iy < GY; iy++)
        for (let ix = 0; ix <= GX; ix++) solve(idx(ix, iy), idx(ix, iy + 1), restV);
      if (o.restD !== undefined) {
        for (let iy = 0; iy < GY; iy++) {
          for (let ix = 0; ix < GX; ix++) {
            if (!linked(ix, iy) || !linked(ix, iy + 1)) continue;
            solve(idx(ix, iy), idx(ix + 1, iy + 1), o.restD);
            solve(idx(ix + 1, iy), idx(ix, iy + 1), o.restD);
          }
        }
      }
    }
    o.hold(cur, prev, rest, t);
  }

  function commit() {
    for (let i = 0; i < N; i++) pos.setXYZ(i, cur[i * 3], cur[i * 3 + 1], cur[i * 3 + 2]);
    pos.needsUpdate = true;
    geo.computeVertexNormals();
  }

  return { step, commit };
}

function holdTopRow(GX: number) {
  return (cur: Float32Array, prev: Float32Array, rest: Float32Array) => {
    for (let i = 0; i <= GX; i++) {
      for (let k = 0; k < 3; k++) {
        cur[i * 3 + k] = rest[i * 3 + k];
        prev[i * 3 + k] = rest[i * 3 + k];
      }
    }
  };
}

function disposeScene(scene: THREE.Scene) {
  scene.traverse((obj) => {
    const mesh = obj as THREE.Mesh;
    if (mesh.geometry) mesh.geometry.dispose();
    const mats = mesh.material
      ? Array.isArray(mesh.material)
        ? mesh.material
        : [mesh.material]
      : [];
    mats.forEach((m) => m.dispose());
  });
}

function blurHeight(height: Float32Array, TW: number, TH: number, passes: number) {
  const tmp = new Float32Array(TW * TH);
  for (let n = 0; n < passes; n++) {
    for (let y = 0; y < TH; y++) {
      const row = y * TW;
      for (let x = 0; x < TW; x++) {
        const a = height[row + (x > 0 ? x - 1 : x)];
        const b = height[row + x];
        const c = height[row + (x < TW - 1 ? x + 1 : x)];
        tmp[row + x] = (a + b + b + c) * 0.25;
      }
    }
    for (let x = 0; x < TW; x++) {
      for (let y = 0; y < TH; y++) {
        const a = tmp[(y > 0 ? y - 1 : y) * TW + x];
        const b = tmp[y * TW + x];
        const c = tmp[(y < TH - 1 ? y + 1 : y) * TW + x];
        height[y * TW + x] = (a + b + b + c) * 0.25;
      }
    }
  }
}

function makeNormalTexture(height: Float32Array, TW: number, TH: number, strength: number) {
  const s = surface(TW, TH);
  const img = s.ctx.createImageData(TW, TH);
  const d = img.data;
  for (let y = 0; y < TH; y++) {
    const yp = y > 0 ? y - 1 : y;
    const yn = y < TH - 1 ? y + 1 : y;
    for (let x = 0; x < TW; x++) {
      const xp = x > 0 ? x - 1 : x;
      const xn = x < TW - 1 ? x + 1 : x;
      const dx = (height[y * TW + xp] - height[y * TW + xn]) * strength;
      const dy = (height[yp * TW + x] - height[yn * TW + x]) * strength;
      const len = Math.sqrt(dx * dx + dy * dy + 1);
      const o = (y * TW + x) * 4;
      d[o] = ((dx / len) * 0.5 + 0.5) * 255;
      d[o + 1] = ((dy / len) * 0.5 + 0.5) * 255;
      d[o + 2] = ((1 / len) * 0.5 + 0.5) * 255;
      d[o + 3] = 255;
    }
  }
  s.ctx.putImageData(img, 0, 0);
  return new THREE.CanvasTexture(s.canvas);
}

function makeStudioEnvironment(
  renderer: THREE.WebGLRenderer,
  stops: [string, string, string],
  boxes: [number, number, number, number, string, number][],
) {
  const W = 1024;
  const H = 512;
  const s = surface(W, H);
  const x = s.ctx;
  const g = x.createLinearGradient(0, 0, 0, H);
  g.addColorStop(0, stops[0]);
  g.addColorStop(stops === IRIDESCENT_ENV ? 0.5 : 0.46, stops[1]);
  g.addColorStop(1, stops[2]);
  x.fillStyle = g;
  x.fillRect(0, 0, W, H);
  boxes.forEach(([fx, fy, w, h, color, alpha]) => {
    const cx = W * fx;
    const cy = H * fy;
    const grad = x.createRadialGradient(cx, cy, 0, cx, cy, Math.max(w, h));
    grad.addColorStop(0, color);
    grad.addColorStop(1, "rgba(0,0,0,0)");
    x.globalAlpha = alpha;
    x.fillStyle = grad;
    x.save();
    x.translate(cx, cy);
    x.scale(w / Math.max(w, h), h / Math.max(w, h));
    x.beginPath();
    x.arc(0, 0, Math.max(w, h), 0, Math.PI * 2);
    x.fill();
    x.restore();
    x.globalAlpha = 1;
  });
  const tex = new THREE.CanvasTexture(s.canvas);
  tex.mapping = THREE.EquirectangularReflectionMapping;
  tex.colorSpace = THREE.SRGBColorSpace;
  const pmrem = new THREE.PMREMGenerator(renderer);
  pmrem.compileEquirectangularShader();
  const env = pmrem.fromEquirectangular(tex).texture;
  pmrem.dispose();
  tex.dispose();
  return env;
}

const IRIDESCENT_ENV: [string, string, string] = ["#0a0c1c", "#05060e", "#02030a"];
const ATELIER_ENV: [string, string, string] = ["#2a2620", "#1a1713", "#0d0b09"];

/* ------------------------------------------------------------ woven cloth */
function buildLinen(canvas: HTMLCanvasElement, theme: Theme): Runtime {
  const textures: Disposable[] = [];

  function makeClothTexture() {
    const W = 1280;
    const H = 800;
    const c = document.createElement("canvas");
    c.width = W;
    c.height = H;
    const x = c.getContext("2d") as CanvasRenderingContext2D;

    const g = x.createLinearGradient(0, 0, 0, H);
    g.addColorStop(0, theme.paper);
    g.addColorStop(1, theme.muted);
    x.fillStyle = g;
    x.fillRect(0, 0, W, H);

    x.strokeStyle = theme.ink;
    x.lineWidth = 2;
    x.strokeRect(46, 46, W - 92, H - 92);
    x.lineWidth = 1;
    x.strokeStyle = theme.text;
    x.strokeRect(66, 66, W - 132, H - 132);

    x.fillStyle = theme.ink;
    x.font = "italic 78px " + theme.heading;
    x.textAlign = "center";
    x.textBaseline = "middle";
    x.fillText("M", W / 2, 190);

    x.font = "normal 20px " + MONO_FONT;
    x.fillStyle = theme.text;
    x.fillText("· MODUS ·", W / 2, 246);

    x.fillStyle = theme.ink;
    x.font = "128px " + theme.heading;
    x.fillText("LOOM", W / 2, 400);
    x.fillText("FIELD", W / 2, 520);

    x.fillStyle = theme.text;
    x.font = "500 26px " + MONO_FONT;
    x.fillText("T Y P E   O N   T H R E A D", W / 2, 626);

    x.globalAlpha = 1;
    for (let yy = 0; yy < H; yy += 3) {
      x.strokeStyle = "rgba(60,30,20,0.05)";
      x.lineWidth = 1;
      x.beginPath();
      x.moveTo(0, yy + 0.5);
      x.lineTo(W, yy + 0.5);
      x.stroke();
    }
    for (let xx = 0; xx < W; xx += 3) {
      x.strokeStyle = "rgba(255,250,235,0.06)";
      x.lineWidth = 1;
      x.beginPath();
      x.moveTo(xx + 0.5, 0);
      x.lineTo(xx + 0.5, H);
      x.stroke();
    }

    const id = x.getImageData(0, 0, W, H);
    const d = id.data;
    for (let i = 0; i < d.length; i += 4) {
      const n = (Math.random() * 2 - 1) * 10;
      d[i] += n;
      d[i + 1] += n;
      d[i + 2] += n;
    }
    x.putImageData(id, 0, 0);

    const tex = new THREE.CanvasTexture(c);
    tex.anisotropy = 4;
    tex.colorSpace = THREE.SRGBColorSpace;
    textures.push(tex);
    return tex;
  }

  const scene = new THREE.Scene();
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
  let camera = new THREE.PerspectiveCamera(42, 1, 0.1, 100);

  const BW = 4.4;
  const BH = 2.75;
  const GX = 40;
  const GY = 26;
  const geo = new THREE.PlaneGeometry(BW, BH, GX, GY);
  const mat = new THREE.MeshPhongMaterial({
    map: makeClothTexture(),
    side: THREE.DoubleSide,
    shininess: 6,
    specular: 0x222222,
    color: 0xffffff,
  });
  scene.add(new THREE.Mesh(geo, mat));

  scene.add(new THREE.AmbientLight(0xffffff, 0.7));
  const key = new THREE.DirectionalLight(0xffffff, 1.05);
  key.position.set(-3, 3.5, 3.2);
  scene.add(key);
  const rim = new THREE.DirectionalLight(new THREE.Color(theme.inkLight), 0.35);
  rim.position.set(3, -1.5, 2.0);
  scene.add(rim);

  const sheet = createSheet(geo, BW, BH, {
    GX,
    GY,
    GRAV: -3.1,
    DAMP: 0.985,
    iterations: 3,
    pin: (_ix, iy) => iy === 0,
    wind: (ix, iy, t) => {
      const cx = ix / GX;
      const cy = iy / GY;
      const travel = t * 1.7 - cy * 4.2;
      const gust = 0.6 + 0.42 * Math.sin(t * 0.6) + 0.18 * Math.sin(t * 1.9 + 1.3);
      const amp = 4.3 * cy;
      const fz =
        (Math.sin(travel + cx * 3.3) + 0.5 * Math.sin(travel * 1.7 + cx * 6.0)) * amp * gust;
      const fx = Math.sin(t * 0.9 + cy * 2.2) * 0.6 * cy;
      const fy = -0.4 * cy;
      return [fx, fy, fz];
    },
    hold: holdTopRow(GX),
  });

  return {
    warm: 40,
    still: 220,
    step: sheet.step,
    commit: sheet.commit,
    draw: () => renderer.render(scene, camera),
    fit: (w, h) => {
      renderer.setSize(w, h, false);
      const aspect = w / h;
      camera = new THREE.PerspectiveCamera(42, aspect, 0.1, 100);
      const vFit = BH / 2 / Math.tan((42 * Math.PI) / 360);
      const hFit = BW / 2 / Math.tan((42 * Math.PI) / 360) / aspect;
      camera.position.set(0, 0.05, Math.max(vFit, hFit) * 1.16 + 0.4);
      camera.lookAt(0, 0, 0);
    },
    dispose: () => {
      disposeScene(scene);
      textures.forEach((t) => t.dispose());
      renderer.dispose();
    },
  };
}

/* ------------------------------------------------------- iridescent silk */
function buildIridescent(canvas: HTMLCanvasElement): Runtime {
  const TW = 1600;
  const TH = 1000;

  function makeWordmarkMask() {
    const s = surface(TW, TH);
    const x = s.ctx;
    x.fillStyle = "#000";
    x.fillRect(0, 0, TW, TH);
    x.fillStyle = "#fff";
    x.textAlign = "center";
    x.textBaseline = "middle";
    x.font = "bold 96px " + headingFont();
    x.fillText("M", TW / 2, 208);
    x.font = "700 30px " + MONO_FONT;
    x.fillText("· M O D U S ·", TW / 2, 278);
    x.font = "bold 150px " + headingFont();
    x.fillText("LOOM", TW / 2, 452);
    x.fillText("FIELD", TW / 2, 600);
    x.font = "700 38px " + MONO_FONT;
    x.fillText("S I L K   P R O O F", TW / 2, 718);
    x.strokeStyle = "#fff";
    x.lineWidth = 7;
    x.strokeRect(64, 64, TW - 128, TH - 128);
    x.lineWidth = 3;
    x.strokeRect(92, 92, TW - 184, TH - 184);
    return x.getImageData(0, 0, TW, TH).data;
  }

  function weaveHeight(x: number, y: number) {
    const p = 8;
    const cx = Math.floor(x / p);
    const cy = Math.floor(y / p);
    const u = (x % p) / p;
    const v = (y % p) / p;
    const binding = (cx * 2 + cy) % 5 === 0;
    const profile = (t: number) => Math.sin(t * Math.PI);
    let h = binding ? profile(v) * 0.9 : profile(u);
    h += Math.sin(cx * 12.9898) * Math.sin(cx * 4.1414 + 2.3) * 0.16;
    h += Math.sin(cy * 7.233 + 1.7) * 0.06;
    return h;
  }

  function valueNoise(seed: number) {
    const G = 64;
    const grid = new Float32Array(G * G);
    let s = seed;
    const rnd = () => (s = (s * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff;
    for (let i = 0; i < G * G; i++) grid[i] = rnd();
    const smooth = (t: number) => t * t * (3 - 2 * t);
    return (u: number, v: number) => {
      const fx = u * G;
      const fy = v * G;
      const ix = Math.floor(fx);
      const iy = Math.floor(fy);
      const tx = smooth(fx - ix);
      const ty = smooth(fy - iy);
      const at = (a: number, b: number) => grid[(((b % G) + G) % G) * G + (((a % G) + G) % G)];
      const a = at(ix, iy);
      const b = at(ix + 1, iy);
      const c = at(ix, iy + 1);
      const d = at(ix + 1, iy + 1);
      return a + (b - a) * tx + (c + (d - c) * tx - (a + (b - a) * tx)) * ty;
    };
  }

  const mask = makeWordmarkMask();
  const height = new Float32Array(TW * TH);
  for (let y = 0; y < TH; y++) {
    for (let x = 0; x < TW; x++) {
      const i = y * TW + x;
      const m = mask[i * 4] / 255;
      height[i] = weaveHeight(x, y) * (1 - m * 0.3) + m * 1.15;
    }
  }

  function makeAlbedoTexture() {
    const s = surface(TW, TH);
    const x = s.ctx;
    const g = x.createLinearGradient(0, 0, TW * 0.35, TH);
    g.addColorStop(0, "#161033");
    g.addColorStop(0.45, "#0d1030");
    g.addColorStop(1, "#100b26");
    x.fillStyle = g;
    x.fillRect(0, 0, TW, TH);
    const img = x.getImageData(0, 0, TW, TH);
    const d = img.data;
    for (let i = 0; i < TW * TH; i++) {
      const m = mask[i * 4] / 255;
      const shade = 0.88 + height[i] * 0.1;
      const o = i * 4;
      d[o] = Math.min(255, d[o] * shade + m * 96);
      d[o + 1] = Math.min(255, d[o + 1] * shade + m * 78);
      d[o + 2] = Math.min(255, d[o + 2] * shade + m * 118);
    }
    x.putImageData(img, 0, 0);
    const tex = new THREE.CanvasTexture(s.canvas);
    tex.colorSpace = THREE.SRGBColorSpace;
    return tex;
  }

  function makeRoughnessTexture() {
    const s = surface(TW, TH);
    const x = s.ctx;
    const img = x.createImageData(TW, TH);
    const d = img.data;
    const grain = valueNoise(9271);
    for (let y = 0; y < TH; y++) {
      for (let xx = 0; xx < TW; xx++) {
        const i = y * TW + xx;
        const m = mask[i * 4] / 255;
        const n = grain((xx / TW) * 5, (y / TH) * 5);
        let r = 0.3 - height[i] * 0.07 + n * 0.09 - m * 0.16;
        r = Math.max(0.04, Math.min(0.8, r));
        const o = i * 4;
        d[o] = d[o + 1] = d[o + 2] = r * 255;
        d[o + 3] = 255;
      }
    }
    x.putImageData(img, 0, 0);
    return new THREE.CanvasTexture(s.canvas);
  }

  function makeThicknessTexture() {
    const W = 512;
    const H = 320;
    const s = surface(W, H);
    const x = s.ctx;
    const img = x.createImageData(W, H);
    const d = img.data;
    const a = valueNoise(4471);
    const b = valueNoise(88231);
    for (let y = 0; y < H; y++) {
      for (let xx = 0; xx < W; xx++) {
        const u = xx / W;
        const v = y / H;
        const n = a(u * 3.4, v * 2.4) * 0.58 + b(u * 8.5, v * 5.6) * 0.42;
        const o = (y * W + xx) * 4;
        const sweep = 0.5 + 0.42 * Math.sin(u * Math.PI * 2 - v * 1.15);
        const t = Math.max(0, Math.min(1, sweep + (n - 0.5) * 0.26));
        d[o] = d[o + 1] = d[o + 2] = t * 255;
        d[o + 3] = 255;
      }
    }
    x.putImageData(img, 0, 0);
    return new THREE.CanvasTexture(s.canvas);
  }

  function makeBackdropTexture() {
    const W = 512;
    const H = 320;
    const s = surface(W, H);
    const x = s.ctx;
    x.fillStyle = "#04050c";
    x.fillRect(0, 0, W, H);
    const g = x.createRadialGradient(W * 0.5, H * 0.42, 0, W * 0.5, H * 0.42, W * 0.62);
    g.addColorStop(0, "rgba(58,42,120,0.85)");
    g.addColorStop(0.45, "rgba(22,20,58,0.55)");
    g.addColorStop(1, "rgba(3,4,11,0)");
    x.fillStyle = g;
    x.fillRect(0, 0, W, H);
    const tex = new THREE.CanvasTexture(s.canvas);
    tex.colorSpace = THREE.SRGBColorSpace;
    return tex;
  }

  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
  renderer.toneMapping = THREE.ACESFilmicToneMapping;
  renderer.toneMappingExposure = 1.48;

  const maxAniso = renderer.capabilities.getMaxAnisotropy();
  const scene = new THREE.Scene();
  const backdrop = makeBackdropTexture();
  scene.background = backdrop;
  const env = makeStudioEnvironment(renderer, IRIDESCENT_ENV, [
    [0.24, 0.2, 300, 120, "#fff3e2", 1],
    [0.74, 0.34, 230, 190, "#7fd8ff", 0.95],
    [0.52, 0.86, 340, 130, "#ff5fa8", 0.55],
    [0.02, 0.55, 160, 220, "#9d7bff", 0.5],
  ]);
  scene.environment = env;

  const BW = 4.7;
  const BH = 2.8;
  const GX = 56;
  const GY = 40;
  const geo = new THREE.PlaneGeometry(BW, BH, GX, GY);

  const albedo = makeAlbedoTexture();
  blurHeight(height, TW, TH, 2);
  const normalMap = makeNormalTexture(height, TW, TH, 2.4);
  const roughnessMap = makeRoughnessTexture();
  const thicknessMap = makeThicknessTexture();
  thicknessMap.wrapS = THREE.RepeatWrapping;
  [albedo, normalMap, roughnessMap, thicknessMap].forEach((t) => {
    t.anisotropy = maxAniso;
  });

  const mat = new THREE.MeshPhysicalMaterial({
    map: albedo,
    normalMap,
    normalScale: new THREE.Vector2(0.24, 0.24),
    roughnessMap,
    roughness: 1.0,
    metalness: 0.45,
    side: THREE.DoubleSide,
    envMapIntensity: 2.6,
    iridescence: 1.0,
    iridescenceIOR: 2.2,
    iridescenceThicknessRange: [300, 820],
    iridescenceThicknessMap: thicknessMap,
    sheen: 0.3,
    sheenColor: new THREE.Color("#a9d9ff"),
    sheenRoughness: 0.32,
  });
  scene.add(new THREE.Mesh(geo, mat));

  scene.add(new THREE.AmbientLight(0x3b3676, 0.55));
  const key = new THREE.DirectionalLight(0xffeede, 2.1);
  key.position.set(-3.1, 3.2, 3.4);
  scene.add(key);
  const rimCool = new THREE.DirectionalLight(0x3fbcff, 2.9);
  rimCool.position.set(3.6, 0.6, 2.2);
  scene.add(rimCool);
  const rimWarm = new THREE.DirectionalLight(0xff3d8e, 2.4);
  rimWarm.position.set(0.4, -2.6, 1.6);
  scene.add(rimWarm);
  const fill = new THREE.DirectionalLight(0x9d7bff, 1.6);
  fill.position.set(-3.2, -1.0, 2.6);
  scene.add(fill);

  const railZ = (ix: number, t: number) => {
    const cx = ix / GX;
    return (
      Math.sin(cx * Math.PI * 3.0 + t * 0.22) * 0.15 +
      Math.sin(cx * Math.PI * 5.0 - t * 0.15) * 0.05
    );
  };

  const sheet = createSheet(geo, BW, BH, {
    GX,
    GY,
    GRAV: -2.15,
    DAMP: 0.989,
    iterations: 4,
    pin: (_ix, iy) => iy === 0,
    wind: (ix, iy, t) => {
      const cx = ix / GX;
      const cy = iy / GY;
      const travel = t * 1.15 - cy * 3.4;
      const gust = 0.52 + 0.34 * Math.sin(t * 0.44) + 0.16 * Math.sin(t * 1.31 + 1.1);
      const amp = 2.15 * cy;
      const fz =
        (Math.sin(travel + cx * 2.6) + 0.46 * Math.sin(travel * 1.55 + cx * 5.1)) * amp * gust;
      const fx = Math.sin(t * 0.6 + cy * 1.9) * 0.9 * cy * (cx - 0.5);
      return [fx, -0.3 * cy, fz];
    },
    hold: (cur, prev, rest, t) => {
      for (let ix = 0; ix <= GX; ix++) {
        const i = ix;
        const z = railZ(ix, t);
        cur[i * 3] = prev[i * 3] = rest[i * 3];
        cur[i * 3 + 1] = prev[i * 3 + 1] = rest[i * 3 + 1];
        cur[i * 3 + 2] = prev[i * 3 + 2] = z;
      }
    },
  });

  // Bloom: half-float scene target, quarter-res bright pass, two blurs, composite.
  const rtScene = new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType, samples: 4 });
  const rtA = new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType });
  const rtB = new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType });
  [rtScene, rtA, rtB].forEach((rt) => {
    rt.texture.minFilter = THREE.LinearFilter;
    rt.texture.magFilter = THREE.LinearFilter;
    rt.texture.generateMipmaps = false;
  });

  const quadCam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
  const quadScene = new THREE.Scene();
  const quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2));
  quadScene.add(quad);

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

  const brightMat = new THREE.ShaderMaterial({
    uniforms: { tDiffuse: { value: null }, threshold: { value: 0.72 } },
    vertexShader: VERT,
    fragmentShader: [
      "uniform sampler2D tDiffuse; uniform float threshold; varying vec2 vUv;",
      "void main(){",
      "  vec3 c = texture2D(tDiffuse, vUv).rgb;",
      "  float l = dot(c, vec3(0.2126, 0.7152, 0.0722));",
      "  float k = max(l - threshold, 0.0) / max(l, 1e-4);",
      "  gl_FragColor = vec4(c * k, 1.0);",
      "}",
    ].join("\n"),
  });

  const blurMat = new THREE.ShaderMaterial({
    uniforms: { tDiffuse: { value: null }, direction: { value: new THREE.Vector2(1, 0) } },
    vertexShader: VERT,
    fragmentShader: [
      "uniform sampler2D tDiffuse; uniform vec2 direction; varying vec2 vUv;",
      "void main(){",
      "  vec3 sum = texture2D(tDiffuse, vUv).rgb * 0.2270270270;",
      "  sum += texture2D(tDiffuse, vUv + direction * 1.3846153846).rgb * 0.3162162162;",
      "  sum += texture2D(tDiffuse, vUv - direction * 1.3846153846).rgb * 0.3162162162;",
      "  sum += texture2D(tDiffuse, vUv + direction * 3.2307692308).rgb * 0.0702702703;",
      "  sum += texture2D(tDiffuse, vUv - direction * 3.2307692308).rgb * 0.0702702703;",
      "  gl_FragColor = vec4(sum, 1.0);",
      "}",
    ].join("\n"),
  });

  const compositeMat = new THREE.ShaderMaterial({
    uniforms: { tDiffuse: { value: null }, tBloom: { value: null }, strength: { value: 0.62 } },
    vertexShader: VERT,
    fragmentShader: [
      "uniform sampler2D tDiffuse; uniform sampler2D tBloom; uniform float strength; varying vec2 vUv;",
      "void main(){",
      "  vec3 base = texture2D(tDiffuse, vUv).rgb;",
      "  vec3 glow = texture2D(tBloom, vUv).rgb;",
      "  gl_FragColor = vec4(base + glow * strength, 1.0);",
      "  #include <tonemapping_fragment>",
      "  #include <colorspace_fragment>",
      "}",
    ].join("\n"),
  });

  function blit(material: THREE.ShaderMaterial, target: THREE.WebGLRenderTarget | null) {
    quad.material = material;
    renderer.setRenderTarget(target);
    renderer.render(quadScene, quadCam);
  }

  let camera = new THREE.PerspectiveCamera(40, 1, 0.1, 100);

  return {
    warm: 150,
    still: 150,
    step: sheet.step,
    commit: sheet.commit,
    draw: (t) => {
      thicknessMap.offset.x = (t * 0.028) % 1;
      const base = camera.position.z;
      camera.position.x = Math.sin(t * 0.13) * 0.3;
      camera.position.y = 0.02 + Math.sin(t * 0.17 + 1.4) * 0.12;
      camera.position.z = base;
      camera.lookAt(0, -0.04, 0);

      renderer.setRenderTarget(rtScene);
      renderer.clear();
      renderer.render(scene, camera);

      brightMat.uniforms.tDiffuse.value = rtScene.texture;
      blit(brightMat, rtA);
      blurMat.uniforms.tDiffuse.value = rtA.texture;
      blurMat.uniforms.direction.value.set(1 / rtA.width, 0);
      blit(blurMat, rtB);
      blurMat.uniforms.tDiffuse.value = rtB.texture;
      blurMat.uniforms.direction.value.set(0, 1 / rtA.height);
      blit(blurMat, rtA);

      compositeMat.uniforms.tDiffuse.value = rtScene.texture;
      compositeMat.uniforms.tBloom.value = rtA.texture;
      renderer.setRenderTarget(null);
      blit(compositeMat, null);
    },
    fit: (cw, ch) => {
      renderer.setSize(cw, ch, false);
      const dpr = renderer.getPixelRatio();
      const pw = Math.max(2, Math.floor(cw * dpr));
      const ph = Math.max(2, Math.floor(ch * dpr));
      rtScene.setSize(pw, ph);
      rtA.setSize(Math.max(2, pw >> 2), Math.max(2, ph >> 2));
      rtB.setSize(Math.max(2, pw >> 2), Math.max(2, ph >> 2));
      const aspect = cw / ch;
      camera = new THREE.PerspectiveCamera(40, aspect, 0.1, 100);
      const vFit = BH / 2 / Math.tan((40 * Math.PI) / 360);
      const hFit = BW / 2 / Math.tan((40 * Math.PI) / 360) / aspect;
      camera.position.set(0, 0.02, Math.max(vFit, hFit) * 0.98 + 0.24);
      camera.lookAt(0, -0.04, 0);
    },
    dispose: () => {
      disposeScene(scene);
      quad.geometry.dispose();
      [brightMat, blurMat, compositeMat].forEach((m) => m.dispose());
      [rtScene, rtA, rtB].forEach((rt) => rt.dispose());
      [albedo, normalMap, roughnessMap, thicknessMap, backdrop, env].forEach((t) => t.dispose());
      renderer.dispose();
    },
  };
}

/* ---------------------------------------------------------- atelier flag */
function buildAtelier(canvas: HTMLCanvasElement): Runtime {
  const TW = 1600;
  const TH = 1030;
  const HOIST = 122;
  const FLY_HEM = 48;
  const EDGE_HEM = 36;
  const SEAM_Y = [TH / 3, (TH * 2) / 3];
  const SEAM_H = 24;

  const alpha = (ctx: CanvasRenderingContext2D) => ctx.getImageData(0, 0, TW, TH).data;

  function makeStructureMask() {
    const s = surface(TW, TH);
    const x = s.ctx;
    x.fillStyle = "#000";
    x.fillRect(0, 0, TW, TH);
    x.fillStyle = "#fff";
    x.fillRect(0, 0, HOIST, TH);
    x.fillRect(TW - FLY_HEM, 0, FLY_HEM, TH);
    x.fillRect(0, 0, TW, EDGE_HEM);
    x.fillRect(0, TH - EDGE_HEM, TW, EDGE_HEM);
    SEAM_Y.forEach((y) => x.fillRect(HOIST, y - SEAM_H / 2, TW - HOIST - FLY_HEM, SEAM_H));
    return alpha(x);
  }

  function makeStitchMask() {
    const s = surface(TW, TH);
    const x = s.ctx;
    x.fillStyle = "#000";
    x.fillRect(0, 0, TW, TH);
    x.strokeStyle = "#fff";
    x.lineWidth = 4;
    x.setLineDash([15, 11]);
    x.lineCap = "butt";
    const run = (x0: number, y0: number, x1: number, y1: number) => {
      x.beginPath();
      x.moveTo(x0, y0);
      x.lineTo(x1, y1);
      x.stroke();
    };
    run(16, 0, 16, TH);
    run(HOIST - 16, 0, HOIST - 16, TH);
    run(TW - FLY_HEM + 16, 0, TW - FLY_HEM + 16, TH);
    run(HOIST, EDGE_HEM - 13, TW - FLY_HEM, EDGE_HEM - 13);
    run(HOIST, TH - EDGE_HEM + 13, TW - FLY_HEM, TH - EDGE_HEM + 13);
    SEAM_Y.forEach((y) => {
      run(HOIST, y - SEAM_H / 2 + 5, TW - FLY_HEM, y - SEAM_H / 2 + 5);
      run(HOIST, y + SEAM_H / 2 - 5, TW - FLY_HEM, y + SEAM_H / 2 - 5);
    });
    x.setLineDash([11, 9]);
    x.lineWidth = 3.5;
    x.strokeRect(TW - 470, TH - 214, 300, 104);
    x.setLineDash([]);
    return alpha(x);
  }

  function makeInkMask() {
    const s = surface(TW, TH);
    const x = s.ctx;
    x.fillStyle = "#000";
    x.fillRect(0, 0, TW, TH);
    x.fillStyle = "#fff";
    x.textAlign = "center";
    x.textBaseline = "middle";
    const cx = HOIST + (TW - HOIST - FLY_HEM) / 2;
    x.font = "700 30px " + MONO_FONT;
    x.fillText("F O L I O   ·   N O .   0 7", cx, TH * 0.235);
    x.font = "bold 152px " + headingFont();
    x.fillText("LOOM", cx, TH * 0.395);
    x.fillText("FIELD", cx, TH * 0.555);
    x.fillRect(cx - 250, TH * 0.645, 500, 4);
    x.font = "600 28px " + MONO_FONT;
    x.fillText("SET IN THREAD  ·  PRINTED ON LINEN  ·  MODUS UI", cx, TH * 0.705);
    x.font = "bold 40px " + headingFont();
    x.fillText("M", TW - 320, TH - 184);
    x.font = "600 19px " + MONO_FONT;
    x.fillText("MODUS · LOOM FIELD", TW - 320, TH - 144);
    return alpha(x);
  }

  const structure = makeStructureMask();
  const stitch = makeStitchMask();
  const ink = makeInkMask();

  function weaveHeight(x: number, y: number) {
    const p = 7;
    const cx = Math.floor(x / p);
    const cy = Math.floor(y / p);
    const u = (x % p) / p;
    const v = (y % p) / p;
    const warpUp = (cx + cy) % 2 === 0;
    const h = warpUp ? Math.sin(u * Math.PI) : Math.sin(v * Math.PI);
    return h + Math.sin(cx * 12.9898) * Math.sin(cy * 4.1414 + 1.9) * 0.22;
  }

  const height = new Float32Array(TW * TH);
  for (let y = 0; y < TH; y++) {
    for (let x = 0; x < TW; x++) {
      const i = y * TW + x;
      const st = structure[i * 4] / 255;
      const th = stitch[i * 4] / 255;
      height[i] = weaveHeight(x, y) + st * 1.5 + th * 3.4 + (ink[i * 4] / 255) * 0.22;
    }
  }

  function makeAlbedoTexture() {
    const s = surface(TW, TH);
    const x = s.ctx;
    const lots = ["#ded2b8", "#d8ccb1", "#e2d6bd"];
    for (let k = 0; k < 3; k++) {
      x.fillStyle = lots[k];
      x.fillRect(0, (TH / 3) * k, TW, TH / 3 + 1);
    }
    const img = x.getImageData(0, 0, TW, TH);
    const d = img.data;
    const INK = [33, 48, 77];
    const TAPE = [26, 37, 72];
    const THREAD = [242, 234, 218];
    for (let i = 0; i < TW * TH; i++) {
      const px = i % TW;
      const st = structure[i * 4] / 255;
      const th = stitch[i * 4] / 255;
      const ik = ink[i * 4] / 255;
      const o = i * 4;
      const shade = 0.86 + height[i] * 0.14;
      let r = d[o] * shade;
      let g = d[o + 1] * shade;
      let b = d[o + 2] * shade;
      if (px < HOIST) {
        r += (TAPE[0] - r) * 0.94;
        g += (TAPE[1] - g) * 0.94;
        b += (TAPE[2] - b) * 0.94;
      } else if (st > 0) {
        r *= 1 - st * 0.17;
        g *= 1 - st * 0.17;
        b *= 1 - st * 0.15;
      }
      if (ik > 0 && px >= HOIST) {
        r += (INK[0] - r) * ik;
        g += (INK[1] - g) * ik;
        b += (INK[2] - b) * ik;
      }
      if (th > 0) {
        r += (THREAD[0] - r) * th * 0.92;
        g += (THREAD[1] - g) * th * 0.92;
        b += (THREAD[2] - b) * th * 0.92;
      }
      d[o] = r;
      d[o + 1] = g;
      d[o + 2] = b;
    }
    x.putImageData(img, 0, 0);
    const tex = new THREE.CanvasTexture(s.canvas);
    tex.colorSpace = THREE.SRGBColorSpace;
    return tex;
  }

  function makeRoughnessTexture() {
    const s = surface(TW, TH);
    const x = s.ctx;
    const img = x.createImageData(TW, TH);
    const d = img.data;
    for (let i = 0; i < TW * TH; i++) {
      const th = stitch[i * 4] / 255;
      const ik = ink[i * 4] / 255;
      let r = 0.86 - height[i] * 0.05 - th * 0.42 - ik * 0.12;
      r = Math.max(0.18, Math.min(0.98, r));
      const o = i * 4;
      d[o] = d[o + 1] = d[o + 2] = r * 255;
      d[o + 3] = 255;
    }
    x.putImageData(img, 0, 0);
    return new THREE.CanvasTexture(s.canvas);
  }

  function makeBackdropTexture() {
    const W = 512;
    const H = 320;
    const s = surface(W, H);
    const x = s.ctx;
    x.fillStyle = "#100e0b";
    x.fillRect(0, 0, W, H);
    const g = x.createRadialGradient(W * 0.44, H * 0.36, 0, W * 0.44, H * 0.36, W * 0.6);
    g.addColorStop(0, "rgba(96,84,66,0.95)");
    g.addColorStop(0.5, "rgba(44,38,30,0.6)");
    g.addColorStop(1, "rgba(13,11,9,0)");
    x.fillStyle = g;
    x.fillRect(0, 0, W, H);
    const tex = new THREE.CanvasTexture(s.canvas);
    tex.colorSpace = THREE.SRGBColorSpace;
    return tex;
  }

  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
  renderer.toneMapping = THREE.ACESFilmicToneMapping;
  renderer.toneMappingExposure = 1.16;

  const maxAniso = renderer.capabilities.getMaxAnisotropy();
  const scene = new THREE.Scene();
  const backdrop = makeBackdropTexture();
  scene.background = backdrop;
  const env = makeStudioEnvironment(renderer, ATELIER_ENV, [
    [0.3, 0.14, 340, 130, "#fffaf0", 1],
    [0.78, 0.4, 220, 200, "#c8d8ea", 0.55],
    [0.06, 0.62, 200, 240, "#e8d3ac", 0.5],
  ]);
  scene.environment = env;

  const BW = 5.0;
  const BH = 2.9;
  const GX = 52;
  const GY = 34;
  const geo = new THREE.PlaneGeometry(BW, BH, GX, GY);

  const albedo = makeAlbedoTexture();
  blurHeight(height, TW, TH, 1);
  const normalMap = makeNormalTexture(height, TW, TH, 2.6);
  const roughnessMap = makeRoughnessTexture();
  [albedo, normalMap, roughnessMap].forEach((t) => {
    t.anisotropy = maxAniso;
  });

  const mat = new THREE.MeshPhysicalMaterial({
    map: albedo,
    normalMap,
    normalScale: new THREE.Vector2(0.55, 0.55),
    roughnessMap,
    roughness: 1.0,
    metalness: 0.0,
    side: THREE.DoubleSide,
    envMapIntensity: 1.15,
    sheen: 0.6,
    sheenColor: new THREE.Color("#f3e6cd"),
    sheenRoughness: 0.62,
  });

  const rig = new THREE.Group();
  rig.add(new THREE.Mesh(geo, mat));
  scene.add(rig);

  const brass = new THREE.MeshStandardMaterial({
    color: 0xb98f47,
    metalness: 1.0,
    roughness: 0.32,
  });
  const steel = new THREE.MeshStandardMaterial({
    color: 0x8d8f95,
    metalness: 1.0,
    roughness: 0.28,
  });

  const HOIST_X = -BW / 2;
  const grommets = [0.09, 0.5, 0.91].map((v) => {
    const g = new THREE.Mesh(new THREE.TorusGeometry(0.055, 0.021, 12, 28), brass);
    g.position.set(HOIST_X + 0.05, BH / 2 - v * BH, 0);
    rig.add(g);
    return g;
  });

  const mast = new THREE.Mesh(new THREE.CylinderGeometry(0.035, 0.042, BH * 1.5, 18), steel);
  mast.position.set(HOIST_X - 0.16, -BH * 0.12, -0.04);
  rig.add(mast);
  const finial = new THREE.Mesh(new THREE.SphereGeometry(0.072, 20, 14), brass);
  finial.position.set(HOIST_X - 0.16, -BH * 0.12 + BH * 0.75 + 0.05, -0.04);
  rig.add(finial);

  grommets.forEach((g) => {
    const clip = new THREE.Mesh(new THREE.TorusGeometry(0.048, 0.011, 10, 22), steel);
    clip.position.set(HOIST_X - 0.11, g.position.y, -0.02);
    clip.rotation.y = Math.PI / 2.4;
    rig.add(clip);
  });

  scene.add(new THREE.HemisphereLight(0xcadcf2, 0x4a3d2c, 0.75));
  const key = new THREE.DirectionalLight(0xfff4e0, 2.5);
  key.position.set(2.6, 3.4, 3.0);
  scene.add(key);
  const bounce = new THREE.DirectionalLight(0xe6cfa4, 0.85);
  bounce.position.set(-3.4, -1.6, 2.0);
  scene.add(bounce);
  const back = new THREE.DirectionalLight(0xfff0d8, 1.5);
  back.position.set(-1.6, 1.4, -3.2);
  scene.add(back);

  const sheet = createSheet(geo, BW, BH, {
    GX,
    GY,
    GRAV: -0.22,
    DAMP: 0.986,
    iterations: 4,
    pin: (ix) => ix === 0,
    wind: (ix, iy, t) => {
      const cx = ix / GX;
      const cy = iy / GY;
      const reach = cx * (0.35 + 0.65 * cx);
      const gust = 0.78 + 0.26 * Math.sin(t * 0.53) + 0.14 * Math.sin(t * 1.47 + 0.9);
      const travel = t * 4.2 - cx * 6.6;
      const fz = (Math.sin(travel) + 0.38 * Math.sin(travel * 1.9 + cy * 2.6)) * 3.4 * reach * gust;
      const fy = Math.sin(travel * 0.8 + 1.2) * 0.85 * reach;
      const fx = 2.6 * reach * gust;
      return [fx, fy, fz];
    },
    hold: (cur, prev, rest) => {
      for (let iy = 0; iy <= GY; iy++) {
        const i = iy * (GX + 1);
        for (let k = 0; k < 3; k++) {
          cur[i * 3 + k] = rest[i * 3 + k];
          prev[i * 3 + k] = rest[i * 3 + k];
        }
      }
    },
  });

  let camera = new THREE.PerspectiveCamera(40, 1, 0.1, 100);

  return {
    warm: 160,
    still: 160,
    step: sheet.step,
    commit: sheet.commit,
    draw: (t) => {
      rig.rotation.y = -0.16 + Math.sin(t * 0.11) * 0.045;
      rig.rotation.z = Math.sin(t * 0.08 + 0.7) * 0.012;
      camera.position.y = 0.06 + Math.sin(t * 0.15) * 0.06;
      camera.lookAt(0.1, 0.0, 0);
      renderer.render(scene, camera);
    },
    fit: (w, h) => {
      renderer.setSize(w, h, false);
      const aspect = w / h;
      camera = new THREE.PerspectiveCamera(40, aspect, 0.1, 100);
      const vFit = (BH * 1.12) / 2 / Math.tan((40 * Math.PI) / 360);
      const hFit = (BW + 1.0) / 2 / Math.tan((40 * Math.PI) / 360) / aspect;
      camera.position.set(0.1, 0.06, Math.max(vFit, hFit) * 1.13 + 0.3);
      camera.lookAt(0.1, 0.0, 0);
    },
    dispose: () => {
      disposeScene(scene);
      [albedo, normalMap, roughnessMap, backdrop, env].forEach((t) => t.dispose());
      renderer.dispose();
    },
  };
}

/* ----------------------------------------------------------- washi noren */
function buildWashi(canvas: HTMLCanvasElement): Runtime {
  const TW = 1500;
  const TH = 980;
  const PANELS = 3;
  const BAND = 0.15;
  const SLIT_U = [1 / 3, 2 / 3];

  function rng(seed: number) {
    let s = seed >>> 0;
    return () => {
      s ^= s << 13;
      s >>>= 0;
      s ^= s >> 17;
      s ^= s << 5;
      s >>>= 0;
      return s / 4294967296;
    };
  }

  const deckleRand = rng(20260826);
  const deckleLow = new Float32Array(TW);
  {
    const control: number[] = [];
    for (let i = 0; i <= 24; i++) control.push(deckleRand());
    for (let x = 0; x < TW; x++) {
      const f = (x / TW) * 24;
      const i = Math.floor(f);
      const t = f - i;
      const smooth = t * t * (3 - 2 * t);
      const a = control[i];
      const b = control[Math.min(24, i + 1)];
      const base = a + (b - a) * smooth;
      const fine = Math.sin(x * 0.19) * 0.16 + Math.sin(x * 0.061 + 1.7) * 0.24;
      deckleLow[x] = TH - 14 - (base * 26 + fine * 12);
    }
  }

  function makeAlphaMask() {
    const s = surface(TW, TH);
    const x = s.ctx;
    x.fillStyle = "#fff";
    x.fillRect(0, 0, TW, TH);
    x.fillStyle = "#000";
    const slitW = 22;
    const bandPx = TH * BAND;
    SLIT_U.forEach((u) => x.fillRect(u * TW - slitW / 2, bandPx, slitW, TH - bandPx));
    x.beginPath();
    x.moveTo(0, TH);
    for (let px = 0; px < TW; px++) x.lineTo(px, deckleLow[px]);
    x.lineTo(TW, TH);
    x.closePath();
    x.fill();
    const side = rng(771);
    for (let e = 0; e < 2; e++) {
      x.beginPath();
      x.moveTo(e ? TW : 0, 0);
      for (let py = 0; py <= TH; py += 6) {
        const w = 6 + side() * 9;
        x.lineTo(e ? TW - w : w, py);
      }
      x.lineTo(e ? TW : 0, TH);
      x.closePath();
      x.fill();
    }
    return s;
  }

  function drawWeaveCrest(x: CanvasRenderingContext2D, cx: number, cy: number, R: number) {
    const cells = 6;
    const step = (R * 1.86) / cells;
    const origin = -R * 0.93;
    x.save();
    x.beginPath();
    x.arc(cx, cy, R * 0.86, 0, Math.PI * 2);
    x.clip();
    x.fillStyle = "#f3ece0";
    for (let a = 0; a < cells; a++) {
      for (let b = 0; b < cells; b++) {
        if ((a + b) % 2) continue;
        x.fillRect(cx + origin + a * step, cy + origin + b * step, step + 0.5, step + 0.5);
      }
    }
    x.restore();
    x.strokeStyle = "#f3ece0";
    x.lineWidth = R * 0.1;
    x.beginPath();
    x.arc(cx, cy, R * 0.96, 0, Math.PI * 2);
    x.stroke();
  }

  function verticalWord(
    x: CanvasRenderingContext2D,
    word: string,
    cx: number,
    top: number,
    size: number,
    step: number,
  ) {
    x.font = "bold " + size + "px " + headingFont();
    x.textAlign = "center";
    x.textBaseline = "middle";
    for (let i = 0; i < word.length; i++) x.fillText(word[i], cx, top + i * step);
  }

  function makeClothCanvas() {
    const s = surface(TW, TH);
    const x = s.ctx;
    const g = x.createLinearGradient(0, 0, 0, TH);
    g.addColorStop(0, "#284a6c");
    g.addColorStop(0.42, "#203d5e");
    g.addColorStop(1, "#17304e");
    x.fillStyle = g;
    x.fillRect(0, 0, TW, TH);

    const cloud = rng(4471);
    for (let i = 0; i < 26; i++) {
      const cx = cloud() * TW;
      const cy = cloud() * TH;
      const r = 120 + cloud() * 320;
      const light = cloud() > 0.5;
      const rg = x.createRadialGradient(cx, cy, 0, cx, cy, r);
      rg.addColorStop(0, light ? "rgba(96,132,168,0.13)" : "rgba(9,22,40,0.16)");
      rg.addColorStop(1, "rgba(0,0,0,0)");
      x.fillStyle = rg;
      x.fillRect(cx - r, cy - r, r * 2, r * 2);
    }

    x.strokeStyle = "rgba(180,205,228,0.045)";
    x.lineWidth = 1;
    for (let px = 0; px < TW; px += 4) {
      x.beginPath();
      x.moveTo(px + 0.5, 0);
      x.lineTo(px + 0.5, TH);
      x.stroke();
    }
    x.strokeStyle = "rgba(196,218,238,0.10)";
    x.lineWidth = 2;
    for (let py = 26; py < TH; py += 38) {
      x.beginPath();
      x.moveTo(0, py + 0.5);
      x.lineTo(TW, py + 0.5);
      x.stroke();
    }

    const fib = rng(90210);
    for (let i = 0; i < 2200; i++) {
      const fx = fib() * TW;
      const fy = fib() * TH;
      const len = 30 + fib() * 150;
      const ang = (fib() - 0.5) * 0.9 + (fib() > 0.82 ? Math.PI / 2 : 0);
      const bow = (fib() - 0.5) * 26;
      const pale = fib();
      x.strokeStyle =
        pale > 0.3
          ? "rgba(214,232,247," + (0.022 + fib() * 0.048) + ")"
          : "rgba(10,20,36," + (0.04 + fib() * 0.07) + ")";
      x.lineWidth = 0.7 + fib() * 1.9;
      x.beginPath();
      x.moveTo(fx, fy);
      x.quadraticCurveTo(
        fx + Math.cos(ang) * len * 0.5 + bow,
        fy + Math.sin(ang) * len * 0.5 - bow,
        fx + Math.cos(ang) * len,
        fy + Math.sin(ang) * len,
      );
      x.stroke();
    }

    const panelW = TW / PANELS;
    x.strokeStyle = "rgba(243,236,224,0.72)";
    for (let k = 0; k < PANELS; k++) {
      const x0 = k * panelW + 34;
      const w = panelW - 68;
      x.lineWidth = 5;
      x.strokeRect(x0, TH * BAND + 34, w, TH - TH * BAND - 118);
      x.lineWidth = 2;
      x.strokeRect(x0 + 13, TH * BAND + 47, w - 26, TH - TH * BAND - 144);
    }

    x.fillStyle = "rgba(8,18,34,0.30)";
    x.fillRect(0, 0, TW, TH * BAND);
    const sh = x.createLinearGradient(0, TH * BAND, 0, TH * BAND + 54);
    sh.addColorStop(0, "rgba(6,14,28,0.42)");
    sh.addColorStop(1, "rgba(6,14,28,0)");
    x.fillStyle = sh;
    x.fillRect(0, TH * BAND, TW, 54);
    x.strokeStyle = "rgba(243,236,224,0.5)";
    x.lineWidth = 2.5;
    x.beginPath();
    x.moveTo(0, TH * BAND);
    x.lineTo(TW, TH * BAND);
    x.stroke();

    x.fillStyle = "#f3ece0";
    verticalWord(x, "LOOM", panelW * 0.5, TH * 0.34, 96, 116);
    drawWeaveCrest(x, panelW * 1.5, TH * 0.53, 158);
    verticalWord(x, "FIELD", panelW * 2.5, TH * 0.34, 96, 116);

    const S = 96;
    const sx = panelW * 1.5 - S / 2;
    const sy = TH * 0.828;
    x.fillStyle = "#a8342a";
    x.fillRect(sx, sy, S, S);
    x.strokeStyle = "#f3ece0";
    x.lineWidth = 4;
    x.strokeRect(sx + 11, sy + 11, S - 22, S - 22);
    x.fillStyle = "#f3ece0";
    for (let k = 0; k < 3; k++) x.fillRect(sx + 23 + k * 18, sy + 23, 8, S - 46);
    x.fillRect(sx + 23, sy + 38, S - 46, 8);
    x.fillRect(sx + 23, sy + 60, S - 46, 8);
    return s;
  }

  function makeWoodTexture() {
    const W = 512;
    const H = 96;
    const s = surface(W, H);
    const x = s.ctx;
    const g = x.createLinearGradient(0, 0, 0, H);
    g.addColorStop(0, "#a1764a");
    g.addColorStop(0.45, "#7d5533");
    g.addColorStop(1, "#563820");
    x.fillStyle = g;
    x.fillRect(0, 0, W, H);
    const grain = rng(3312);
    for (let i = 0; i < 160; i++) {
      const y = grain() * H;
      x.strokeStyle = "rgba(28,17,8," + (0.05 + grain() * 0.16) + ")";
      x.lineWidth = 0.6 + grain() * 1.8;
      x.beginPath();
      x.moveTo(0, y);
      for (let px = 0; px <= W; px += 32) x.lineTo(px, y + Math.sin(px * 0.02 + i) * 2.4);
      x.stroke();
    }
    const tex = new THREE.CanvasTexture(s.canvas);
    tex.colorSpace = THREE.SRGBColorSpace;
    tex.wrapS = THREE.RepeatWrapping;
    tex.repeat.set(3, 1);
    return tex;
  }

  function makeShojiTexture() {
    const W = 768;
    const H = 512;
    const s = surface(W, H);
    const x = s.ctx;
    x.fillStyle = "#1a1109";
    x.fillRect(0, 0, W, H);
    const glow = x.createRadialGradient(W * 0.5, H * 0.44, 0, W * 0.5, H * 0.44, W * 0.52);
    glow.addColorStop(0, "#ffdda4");
    glow.addColorStop(0.4, "#a97c42");
    glow.addColorStop(0.76, "#341d0c");
    glow.addColorStop(1, "#150d06");
    x.fillStyle = glow;
    x.fillRect(0, 0, W, H);
    if ("filter" in x) x.filter = "blur(7px)";
    x.strokeStyle = "rgba(46,28,13,0.20)";
    x.lineWidth = 3;
    for (let px = 54; px < W; px += 128) {
      x.beginPath();
      x.moveTo(px, 0);
      x.lineTo(px, H);
      x.stroke();
    }
    for (let py = 46; py < H; py += 118) {
      x.beginPath();
      x.moveTo(0, py);
      x.lineTo(W, py);
      x.stroke();
    }
    if ("filter" in x) x.filter = "none";
    const tex = new THREE.CanvasTexture(s.canvas);
    tex.colorSpace = THREE.SRGBColorSpace;
    return tex;
  }

  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
  renderer.toneMapping = THREE.ACESFilmicToneMapping;
  renderer.toneMappingExposure = 1.22;

  const maxAniso = renderer.capabilities.getMaxAnisotropy();
  const scene = new THREE.Scene();
  scene.background = new THREE.Color(0x0c0906);

  const shojiTex = makeShojiTexture();
  const shoji = new THREE.Mesh(
    new THREE.PlaneGeometry(13, 8.4),
    new THREE.MeshBasicMaterial({ map: shojiTex }),
  );
  shoji.position.set(0, 0, -2.4);
  scene.add(shoji);

  const BW = 4.4;
  const BH = 2.9;
  const GX = 60;
  const GY = 40;
  const geo = new THREE.PlaneGeometry(BW, BH, GX, GY);

  const albedo = new THREE.CanvasTexture(makeClothCanvas().canvas);
  albedo.colorSpace = THREE.SRGBColorSpace;
  const alphaMap = new THREE.CanvasTexture(makeAlphaMask().canvas);
  [albedo, alphaMap].forEach((t) => {
    t.anisotropy = maxAniso;
  });

  const mat = new THREE.MeshPhysicalMaterial({
    map: albedo,
    alphaMap,
    alphaTest: 0.5,
    transparent: false,
    side: THREE.DoubleSide,
    roughness: 0.92,
    metalness: 0.0,
    transmission: 0.82,
    thickness: 0.1,
    ior: 1.36,
    attenuationColor: new THREE.Color("#9dc0dd"),
    attenuationDistance: 3.0,
    sheen: 0.9,
    sheenColor: new THREE.Color("#d8e6f2"),
    sheenRoughness: 0.85,
  });
  scene.add(new THREE.Mesh(geo, mat));

  const woodTex = makeWoodTexture();
  const wood = new THREE.MeshStandardMaterial({ map: woodTex, roughness: 0.66, metalness: 0.0 });
  const rod = new THREE.Mesh(new THREE.CylinderGeometry(0.062, 0.062, BW + 0.9, 20), wood);
  rod.rotation.z = Math.PI / 2;
  rod.position.set(0, BH / 2 + 0.045, 0.02);
  scene.add(rod);
  [-1, 1].forEach((side) => {
    const cap = new THREE.Mesh(new THREE.SphereGeometry(0.082, 18, 12), wood);
    cap.position.set((side * (BW + 0.9)) / 2, BH / 2 + 0.045, 0.02);
    scene.add(cap);
    const cord = new THREE.Mesh(
      new THREE.CylinderGeometry(0.011, 0.011, 3.4, 8),
      new THREE.MeshStandardMaterial({ color: 0x2a2018, roughness: 0.9 }),
    );
    cord.position.set((side * (BW + 0.72)) / 2, BH / 2 + 1.75, 0.02);
    scene.add(cord);
  });

  scene.add(new THREE.AmbientLight(0x4a3a28, 0.8));
  const lantern = new THREE.DirectionalLight(0xffd9a0, 3.6);
  lantern.position.set(-0.4, 0.9, -3.2);
  scene.add(lantern);
  const key = new THREE.DirectionalLight(0xffe9cc, 2.1);
  key.position.set(-2.6, 2.4, 2.6);
  scene.add(key);
  const fill = new THREE.DirectionalLight(0x94b6d8, 0.5);
  fill.position.set(3.0, -1.0, 2.0);
  scene.add(fill);

  const BAND_ROWS = Math.round(GY * BAND);
  const SLIT_IX = SLIT_U.map((u) => Math.round(u * GX));
  const panelOf = (ix: number) => (ix < SLIT_IX[0] ? 0 : ix < SLIT_IX[1] ? 1 : 2);
  const restH = BW / GX;
  const restV = BH / GY;

  const sheet = createSheet(geo, BW, BH, {
    GX,
    GY,
    GRAV: -1.65,
    DAMP: 0.986,
    iterations: 3,
    pin: (_ix, iy) => iy === 0,
    linked: (ix, iy) => !(iy > BAND_ROWS && SLIT_IX.indexOf(ix + 1) !== -1),
    restD: Math.sqrt(restH * restH + restV * restV),
    wind: (ix, iy, t) => {
      const cx = ix / GX;
      const cy = iy / GY;
      const ph = panelOf(ix) * 2.1;
      const gust = 0.4 + 0.28 * Math.sin(t * 0.37 + ph * 0.6) + 0.15 * Math.sin(t * 0.93 + ph);
      const travel = t * 1.2 - cy * 2.2 + ph;
      const amp = 1.5 * cy;
      const fz = (Math.sin(travel) + 0.35 * Math.sin(travel * 1.8 + cx * 3.4)) * amp * gust;
      const fx = Math.sin(t * 0.44 + ph) * 0.2 * cy;
      return [fx, -0.18 * cy, fz];
    },
    hold: holdTopRow(GX),
  });

  let camera = new THREE.PerspectiveCamera(38, 1, 0.1, 100);

  return {
    warm: 180,
    still: 180,
    step: sheet.step,
    commit: sheet.commit,
    draw: (t) => {
      camera.position.x = Math.sin(t * 0.1) * 0.2;
      camera.position.y = 0.06 + Math.sin(t * 0.14 + 1.1) * 0.07;
      camera.lookAt(0, -0.02, 0);
      renderer.render(scene, camera);
    },
    fit: (w, h) => {
      renderer.setSize(w, h, false);
      const aspect = w / h;
      camera = new THREE.PerspectiveCamera(38, aspect, 0.1, 100);
      const vFit = (BH * 1.12) / 2 / Math.tan((38 * Math.PI) / 360);
      const hFit = (BW + 1.2) / 2 / Math.tan((38 * Math.PI) / 360) / aspect;
      camera.position.set(0, 0.06, Math.max(vFit, hFit) * 1.02 + 0.3);
      camera.lookAt(0, -0.02, 0);
    },
    dispose: () => {
      disposeScene(scene);
      [shojiTex, albedo, alphaMap, woodTex].forEach((t) => t.dispose());
      renderer.dispose();
    },
  };
}

const BUILDERS: Record<LoomFieldVariant, (canvas: HTMLCanvasElement, theme: Theme) => Runtime> = {
  linen: buildLinen,
  iridescent: buildIridescent,
  atelier: buildAtelier,
  washi: buildWashi,
};

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

export function LoomField({
  variant = "linen",
  hue = 0,
  saturation = 1,
  brightness = 1,
  backgroundColor,
  className,
}: LoomFieldProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [themeKey, setThemeKey] = useState(0);

  useEffect(() => {
    // the linen is printed on a canvas texture, so rebuild it when the theme or palette changes
    const observer = new MutationObserver(() => setThemeKey((k) => k + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette"],
    });
    return () => observer.disconnect();
  }, []);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;

    const runtime = BUILDERS[variant](canvas, readTheme());
    let t = 0;
    let raf = 0;
    let running = false;
    let visible = true;

    const resize = () => {
      const w = Math.max(1, host.clientWidth);
      const h = Math.max(1, host.clientHeight);
      runtime.fit(w, h);
      if (prefersReducedMotion || !running) runtime.draw(t);
    };

    const loop = () => {
      if (!running) return;
      t += DT;
      runtime.step(t);
      runtime.commit();
      runtime.draw(t);
      raf = requestAnimationFrame(loop);
    };
    const start = () => {
      if (running || prefersReducedMotion || !visible || document.hidden) return;
      running = true;
      raf = requestAnimationFrame(loop);
    };
    const stop = () => {
      running = false;
      cancelAnimationFrame(raf);
    };

    const warm = prefersReducedMotion ? runtime.still : runtime.warm;
    for (let s = 0; s < warm; s++) runtime.step(s * DT);
    t = warm * DT;
    runtime.commit();
    resize();

    const ro = new ResizeObserver(resize);
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(host);
    const onVisibility = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVisibility);
    start();

    return () => {
      stop();
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      runtime.dispose();
    };
  }, [variant, prefersReducedMotion, themeKey]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? BACKGROUNDS[variant], filter }}
    >
      <canvas
        key={`${variant}-${themeKey}`}
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full"
      />
      <div
        className="pointer-events-none absolute inset-0"
        style={{ background: VIGNETTES[variant] }}
      />
    </div>
  );
}
```

---

# Word Swarm

> A gooey swarm of cells drifts over serif type and turns each word it touches to ink and italic.

Install: `npx @modus-ui/cli add word-swarm`

A liquid, SVG-filtered swarm of cells wanders over a line of serif type, drawn toward the words and your pointer. Each word it touches darkens from muted ink to full foreground and leans into italic. Colours follow the active Modus theme and palette, and the type uses the heading font. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add word-swarm
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/word-swarm.tsx`.
3. Paste the code.

## Usage

```tsx
import { WordSwarm } from "@/components/ui/word-swarm";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <WordSwarm />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                              |
| :---------------- | :------- | :------------------------- | :--------------------------------------- |
| `text`            | `string` | `"Words gather meaning"`   | Text to display (max 72 characters).     |
| `size`            | `number` | `1`                        | Text size multiplier (clamped 0.55–1.6). |
| `opacity`         | `number` | `1`                        | Overall opacity (clamped 0.1–1).         |
| `backgroundColor` | `string` | Theme `--background`       | Background colour, any CSS colour.       |
| `textColor`       | `string` | Theme `--muted-foreground` | Colour of untouched words.               |
| `activeTextColor` | `string` | Theme `--foreground`       | Colour of words the swarm touches.       |
| `particleColor`   | `string` | Theme `--primary`          | Fill of the swarm's cells.               |
| `connectionColor` | `string` | Theme `--primary`, faint   | Stroke of the links between cells.       |

## Source

`components/ui/word-swarm.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Semantic Bloom (MIT, © 2026 Meng To).

import { useEffect, useId, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface WordSwarmProps {
  text?: string;
  size?: number;
  opacity?: number;
  backgroundColor?: string;
  textColor?: string;
  activeTextColor?: string;
  particleColor?: string;
  connectionColor?: string;
  className?: string;
}

const NOISE =
  "url(\"data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)' opacity='0.08'/%3E%3C/svg%3E\")";

const config = {
  particleCount: 50,
  baseRadius: 15,
  viscosity: 0.08,
  wanderStrength: 0.5,
  connectionDist: 150,
  repelDist: 50,
  textAttractionRadius: 200,
};

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

interface WordCoord {
  x: number;
  y: number;
  element: HTMLSpanElement;
  active: boolean;
}

export function WordSwarm({
  text = "Words gather meaning",
  size = 1,
  opacity = 1,
  backgroundColor,
  textColor,
  activeTextColor,
  particleColor,
  connectionColor,
  className,
}: WordSwarmProps) {
  const prefersReducedMotion = useReducedMotion();
  const filterId = `liquid-filter-${useId().replace(/:/g, "")}`;
  const rootRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const editorRef = useRef<HTMLDivElement>(null);

  const surface = backgroundColor ?? "hsl(var(--background))";
  const resting = textColor ?? "hsl(var(--muted-foreground) / 0.55)";
  const active = activeTextColor ?? "hsl(var(--foreground))";
  const particleCss = particleColor ?? "hsl(var(--primary) / 0.85)";
  const connectionCss = connectionColor ?? "hsl(var(--primary) / 0.22)";
  const content = (text.trim() ? text : "Words gather meaning").slice(0, 72);
  const sizeFactor = clamp(size, 0.55, 1.6);

  useEffect(() => {
    const root = rootRef.current;
    const canvas = canvasRef.current;
    const editor = editorRef.current;
    if (!root || !canvas || !editor) return;
    const ctx = canvas.getContext("2d");
    if (!ctx) return;

    let width = 0;
    let height = 0;
    const mouse = { x: -1000, y: -1000 };
    let wordCoordinates: WordCoord[] = [];
    // canvas cannot read CSS variables, so resolve the token colours through a probe element
    let particle = "";
    let connection = "";
    const probe = document.createElement("span");
    probe.style.display = "none";
    root.appendChild(probe);
    const resolve = (c: string) => {
      probe.style.color = c;
      return getComputedStyle(probe).color;
    };
    const readTheme = () => {
      particle = resolve(particleCss);
      connection = resolve(connectionCss);
    };
    readTheme();
    const mo = new MutationObserver(readTheme);
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "style"],
    });

    // split the text into word spans once
    editor.textContent = "";
    content.split(/(\s+)/).forEach((word) => {
      const span = document.createElement("span");
      span.textContent = word;
      if (word.trim().length > 0) {
        span.style.display = "inline-block";
        span.style.position = "relative";
        span.style.zIndex = "2";
        span.style.color = resting;
        span.style.transition = "color 1s ease";
        span.dataset.word = "true";
      }
      editor.appendChild(span);
    });

    const setActive = (el: HTMLSpanElement, on: boolean) => {
      el.style.color = on ? active : resting;
      el.style.fontStyle = on ? "italic" : "normal";
    };

    const layoutText = () => {
      const fontSize =
        width <= 640
          ? clamp(width * 0.14 * sizeFactor, 40, 96)
          : clamp(width * 0.085 * sizeFactor, 52, 132);
      editor.style.fontSize = `${fontSize}px`;
      editor.parentElement!.style.padding =
        width <= 640 ? "1.5rem" : `${clamp(width * 0.08, 32, 128)}px`;
    };

    const updateWordCoords = () => {
      const rootRect = root.getBoundingClientRect();
      wordCoordinates = [];
      editor.querySelectorAll<HTMLSpanElement>("[data-word]").forEach((span) => {
        const rect = span.getBoundingClientRect();
        setActive(span, false);
        wordCoordinates.push({
          x: rect.left - rootRect.left + rect.width / 2,
          y: rect.top - rootRect.top + rect.height / 2,
          element: span,
          active: false,
        });
      });
    };

    const resize = () => {
      width = root.clientWidth;
      height = root.clientHeight;
      canvas.width = width;
      canvas.height = height;
      layoutText();
      updateWordCoords();
    };

    class Particle {
      x: number;
      y: number;
      vx: number;
      vy: number;
      radius: number;
      angle: number;
      constructor(x: number, y: number) {
        this.x = x;
        this.y = y;
        this.vx = (Math.random() - 0.5) * 2;
        this.vy = (Math.random() - 0.5) * 2;
        this.radius = config.baseRadius * (0.8 + Math.random() * 0.5);
        this.angle = Math.random() * Math.PI * 2;
      }

      update() {
        this.angle += (Math.random() - 0.5) * 0.2;
        this.vx += Math.cos(this.angle) * config.wanderStrength;
        this.vy += Math.sin(this.angle) * config.wanderStrength;

        this.vx *= 0.95;
        this.vy *= 0.95;

        const dx = mouse.x - this.x;
        const dy = mouse.y - this.y;
        const dist = Math.sqrt(dx * dx + dy * dy);
        if (dist < 400) {
          this.vx += dx * 0.002;
          this.vy += dy * 0.002;
        }

        let closestDist = Infinity;
        let closestWord: WordCoord | null = null;
        for (const word of wordCoordinates) {
          const wdx = word.x - this.x;
          const wdy = word.y - this.y;
          const wDist = Math.sqrt(wdx * wdx + wdy * wdy);
          if (wDist < closestDist) {
            closestDist = wDist;
            closestWord = word;
          }
        }

        if (closestWord && closestDist < config.textAttractionRadius) {
          this.vx += (closestWord.x - this.x) * 0.01;
          this.vy += (closestWord.y - this.y) * 0.01;

          if (closestDist < 30) {
            if (!closestWord.active) {
              setActive(closestWord.element, true);
              closestWord.active = true;
            }
          } else if (closestDist > 60) {
            if (closestWord.active) {
              setActive(closestWord.element, false);
              closestWord.active = false;
            }
          }
        }

        this.x += this.vx;
        this.y += this.vy;

        if (this.x < 0) this.x = width;
        if (this.x > width) this.x = 0;
        if (this.y < 0) this.y = height;
        if (this.y > height) this.y = 0;
      }

      draw() {
        ctx!.beginPath();
        ctx!.arc(this.x, this.y, this.radius, 0, Math.PI * 2);
        ctx!.fillStyle = particle;
        ctx!.fill();
      }
    }

    resize();
    const particles: Particle[] = [];
    for (let i = 0; i < config.particleCount; i++) {
      particles.push(
        new Particle(
          width / 2 + (Math.random() - 0.5) * 100,
          height / 2 + (Math.random() - 0.5) * 100,
        ),
      );
    }

    const render = () => {
      ctx.clearRect(0, 0, width, height);
      ctx.strokeStyle = connection;
      ctx.lineWidth = 2;
      for (let i = 0; i < particles.length; i++) {
        const p1 = particles[i];
        p1.update();
        p1.draw();
        for (let j = i + 1; j < particles.length; j++) {
          const p2 = particles[j];
          const dx = p1.x - p2.x;
          const dy = p1.y - p2.y;
          if (Math.sqrt(dx * dx + dy * dy) < config.connectionDist) {
            ctx.beginPath();
            ctx.moveTo(p1.x, p1.y);
            ctx.lineTo(p2.x, p2.y);
            ctx.stroke();
          }
        }
      }
    };

    let raf = 0;
    let onScreen = true;
    const frame = () => {
      render();
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) raf = requestAnimationFrame(frame);
      else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    const onMove = (e: PointerEvent) => {
      const r = root.getBoundingClientRect();
      mouse.x = e.clientX - r.left;
      mouse.y = e.clientY - r.top;
    };
    window.addEventListener("pointermove", onMove);
    const ro = new ResizeObserver(() => {
      resize();
      if (prefersReducedMotion) render();
    });
    ro.observe(root);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(root);
    document.addEventListener("visibilitychange", update);
    const settle = window.setTimeout(updateWordCoords, 100);
    render();
    update();

    return () => {
      cancelAnimationFrame(raf);
      mo.disconnect();
      probe.remove();
      window.clearTimeout(settle);
      window.removeEventListener("pointermove", onMove);
      document.removeEventListener("visibilitychange", update);
      ro.disconnect();
      io.disconnect();
    };
  }, [content, sizeFactor, resting, active, particleCss, connectionCss, prefersReducedMotion]);

  return (
    <div
      ref={rootRef}
      className={cn("absolute inset-0 cursor-none overflow-hidden font-serif", className)}
      style={{
        background: surface,
      }}
    >
      <div className="absolute inset-0" style={{ opacity: clamp(opacity, 0.1, 1) }}>
        <svg className="absolute h-0 w-0" aria-hidden>
          <defs>
            <filter id={filterId}>
              <feGaussianBlur in="SourceGraphic" stdDeviation="12" result="blur" />
              <feColorMatrix
                in="blur"
                mode="matrix"
                values="1 0 0 0 0  0 1 0 0 0  0 0 1 0 0  0 0 0 19 -9"
                result="goo"
              />
              <feTurbulence
                type="fractalNoise"
                baseFrequency="0.01"
                numOctaves={3}
                result="noise"
              />
              <feDisplacementMap
                in="goo"
                in2="noise"
                scale="20"
                xChannelSelector="R"
                yChannelSelector="G"
              />
              <feComposite in="SourceGraphic" operator="atop" />
            </filter>
          </defs>
        </svg>

        <div
          className="pointer-events-none absolute inset-0 z-[3] opacity-60 mix-blend-multiply dark:mix-blend-screen"
          style={{ backgroundImage: NOISE }}
        />
        <canvas
          ref={canvasRef}
          className="pointer-events-none absolute inset-0 z-[1] h-full w-full opacity-90"
          style={{
            filter: `url(#${filterId}) contrast(150%) brightness(100%)`,
          }}
        />

        <div className="relative z-[2] box-border flex h-full w-full items-center justify-center">
          <div
            ref={editorRef}
            aria-label={content}
            className="relative flex w-full items-center justify-center overflow-visible whitespace-pre-wrap text-center font-normal leading-[0.95] tracking-[-0.02em]"
            style={{ color: resting }}
          />
        </div>
      </div>
    </div>
  );
}
```

---

# Orb Lettering

> A canvas sphere whose land is set in italic serif type along the latitudes, inked in your theme.

Install: `npx @modus-ui/cli add orb-lettering`

Land set in italic serif type along the latitude lines over a halftone sea, inked from the muted tone up to the palette's primary on the page ground. Drag to spin and tilt, scroll to zoom and click to drop a pin. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add orb-lettering
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/orb-lettering.tsx`.
3. Paste the code.

## Usage

```tsx
import { OrbLettering } from "@/components/ui/orb-lettering";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <OrbLettering />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                                          | Description                                 |
| :---------------- | :------- | :----------------------------------------------- | :------------------------------------------ |
| `text`            | `string` | `"alettertravelsroundthesphereandcomesbackhome"` | Phrase written across the land.             |
| `scale`           | `number` | `1`                                              | Scales the drawing (clamped 0.65–1.5).      |
| `opacity`         | `number` | `1`                                              | Overall opacity (clamped 0.1–1).            |
| `hue`             | `number` | `0`                                              | Hue rotation in degrees (clamped -180–180). |
| `saturation`      | `number` | `1`                                              | Saturation multiplier (clamped 0–2).        |
| `brightness`      | `number` | `1`                                              | Brightness multiplier (clamped 0.4–1.8).    |
| `inkColor`        | `string` | Theme ramp (`--muted-foreground` → `--primary`)  | Colour of the type, any CSS colour.         |
| `backgroundColor` | `string` | `hsl(var(--background))`                         | Ground colour, any CSS colour.              |

## Source

`components/ui/orb-lettering.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Globe Study (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface OrbLetteringProps {
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  text?: string;
  /** Ink colour (any CSS colour). Defaults to a ramp from --muted-foreground to --primary. */
  inkColor?: string;
  /** Ground colour (any CSS colour). Defaults to hsl(var(--background)). */
  backgroundColor?: string;
  className?: string;
}

let FACE = "serif";
/* resolves any CSS colour (including hsl(var(--token))) to an "r,g,b" triplet */
function toRgb(el: HTMLElement, color: string) {
  const probe = document.createElement("span");
  probe.style.color = color;
  probe.style.display = "none";
  el.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return m.slice(0, 3).map((v) => Math.round(Number(v)));
}
/* on black the eye needs far less ink, so every alpha runs through SOFT first */
const SOFT = 0.88;
/* Snapping every angle to one of 64 steps keeps the glyph raster cache warm. */
const QA = (Math.PI * 2) / 64;
function qang(a: number) {
  return Math.round(a / QA) * QA;
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

interface Surface {
  w: number;
  h: number;
  dpr: number;
  /* panels are not square, so scale off the short side */
  u: number;
}

interface StudyEnv {
  cv: HTMLCanvasElement;
  ctx: CanvasRenderingContext2D;
  s: Surface;
  ink: (a: number) => string;
  local: (e: PointerEvent) => { x: number; y: number };
  signal: AbortSignal;
}

const LAND_B64 =
  "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPcBAOD/HwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACA//+P//f/LwgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4/v/4/////wcAAAAEAPABAAAAfAAAAAAAAAAAAAAAAAAAAADg9w/4/////wEAAP4AAAAAAAAA+AAAAAAAAAAAAAAAAAAAAIAG+Of//////wAAAHwGAAAAAAAAAAMAAAAAAAAAAAAAAACABwAc/4P//////wAAADAAAAAAQAAAAD4AAAAAAAAAAAAAAAAAfMbDcQAA/v///wAAAAAAAADABwAA//8HAMAPAAAAAAAAAABgAAAAAAAA/P///wAAAAAAAABwAADg//8AAAAAAAAAAAAAAADwG457dwcA8P//HwAAAAAAAAAYAAD///9/eAAAAAAAAAAAAAD4/g0H/w8A8P//PwAAAAAAAAAOgOv/////fwD/AAAAAAA/AAAA/B84/v8A8P//LwAAAAD4AAAA4PP//////////wAAAOD///H/+D/3cPgDoP//DwAAAID/BwAAx/v/////////P4AA/P///////////////////////w8AAOcBAAgAAAAAAAAAAAAAgP///////////////////////wcAACYAAAQAAAAAAAAAAAAAgf///////////////////////wMM8AAAAAAAAAAAAAAAAAAAIID/////////e+wPwH8AgA8AAP/5z/////////////////8/ANH///////9/AIALgD8AAAAAwH/+//////////////////9/APj///////8fADwAAD8AAAAA8D/+//////////////////sPAPC/+f////8fAPwAADgAAAAA8D/+////////////////D/wBAMCfAP////8PAPwYAAAAAAAA8H/4//////////////9/DgcAAAAcAOD///8/APw/AAAAAAAQAB7w//////////////8BgAMAAAACAMD/////Afh/AAAAAAA4gBz+/////////////38A4AMAAMAAAMD/////B/z/AAAAAABwwAb+/////////////x8A8AEAAAAAAAD/////P///AwAAAADmgOH//////////////z8A4AAAAAAAAAD+////P/7/BwAAAAD28P////////////////8D4AAAAAAAAAD8////f/7/BwAAAADz+f////////////////8HIAAAAAAAAAD6////////BAAAAABw/v////////////////8EAAAAAAAAAADo//////8jHgAAAACA//////////////////8MAAAAAAAAAADQ//////8OPgAAAADw//////////////////8AAAAAAAAAAADg//////+PIAAAAADA////v////////////38EAAAAAAAAAADg////////AAAAAACA//v/zD/8/////////z8AAAAAAAAAAADg//////8bAAAAAACA//N/gD///////////x8GAAAAAAAAAADw//////8AAAAAAAD+B8c/AD/+/////////wcPAAAAAAAAAADg//////8AAAAAAAD+gx4/DH74/////////wABAAAAAAAAAADg/////x8AAAAAAAD+gbCn///8////////fQABAAAAAAAAAADg/////w8AAAAAAAD/gCDn///4//////9/MgADAAAAAAAAAADA/////w8AAAAAAAD+AADm/3/4//////8/cIABAAAAAAAAAADA/////wcAAAAAAAA44AHC///5////////4+ABAAAAAAAAAACA/////wcAAAAAAACI/wEA4P//////////4OgAAAAAAAAAAAAA/////wMAAAAAAAD4/wAA4P//////////ADYAAAAAAAAAAAAA/P///wEAAAAAAAD+/wEA8P//////////AQcAAAAAAAAAAAAA+P//fwAAAAAAAAD//w8P8P//////////AQEAAAAAAAAAAAAAyP//fwAAAAAAAAD//3//////////////AQAAAAAAAAAAAAAA0P+PYQAAAAAAAAD//////z//////////AwAAAAAAAAAAAAAAoP8HwAAAAAAAAMD/////83/+////////AQAAAAAAAAAAAAAAIP8DwAAAAAAAAOD/////5//I////////AAAAAAAAAAAAAAAAQP4DgAAAAAAAAPD/////z/+A////////AAAAAAAAAAAAAAAAAPwDAAIAAAAAAPD/////z/8ZwP////9/AQAAAAAAAAAAAAAAAPgDQAAAAAAAAPj/////j/9/gP////8fAQAAAAAAAAAAAAAAAPADEAMAAAAAAPz/////v///AP9//P8DAAAAAAAAAAAAAAAAAPADAwwAAAAAAPj/////P/9/APw//B8AAAAAAAAAAAAIAAAAAPCHA8AAAAAAAPj/////P/4/APwP+J8BAAAAAAAAAAAAAAAAAMD/A0YEAAAAAPj/////f/4fAPwH+B8AAwAAAAAAAAAAAAAAAAD/AQAAAAAAAPj/////f/wHAPgD8D8AAwAAAAAAAAAAAAAAAADgHwAAAAAAAPj///////wDAPgAwH8AAQAAAAAAAAAAAAAAAADAHwAAAAAAAPz//////30AAPAAwH8AAAAAAAAAAAAAAAAAAAAAHAAAAAAAAPj//////wsAAPAAgH4AAQAAAAAAAAAAAAAAAAAAGEAAAAAAAPj//////wMBAPAAgHwAAAAAAAAAAAAAAAAAAAAAGPAhAAAAAPD///////cBAOAAgDiABAAAAAAAAAAAAAAAAAAAIPl/AAAAAOD///////8AAGABABBAFAAAAAAAAAAAAAAAAAAAgP7/AQAAAMD///////8AAAABgAAAHAAAAAAAAAAAAAAAAAAAAPz/AQAAAID///////8AAAABAAEgCAAAAAAAAAAAAAAAAAAAAPz/HwAAAAD/8P///38AAAAAAANgAAAAAAAAAAAAAAAAAAAAAPz/fwAAAAAAoP///z8AAAAAYAd4AAAAAAAAAAAAAAAAAAAAAPz/fwAAAAAAAP///x8AAAAAwAY8AAAAAAAAAAAAAAAAAAAAAP7//wAAAAAAAP///w8AAAAAgAc+AAAAAAAAAAAAAAAAAAAAAP///wAAAAAAAP///wcAAAAAgIM/TwAAAAAAAAAAAAAAAAAAAP///wEAAAAAgP///wMAAAAAAIc/QAQAAAAAAAAAAAAAAAAAgP///w8AAAAAgP///wEAAAAAAA6fAUQAAAAAAAAAAAAAAAAAAP////8AAAAAAP///wAAAAAAAB6ewuwDAgAAAAAAAAAAAAAAgP////8DAAAAAP7//wAAAAAAABwAAvAPAgAAAAAAAAAAAAAAgP////8PAAAAAPz/fwAAAAAAABAAAMCfAQAAAAAAAAAAAAAAAP////8PAAAAAPz//wAAAAAAAOADAIA/MAAAAAAAAAAAAAAAAP7///8PAAAAAPz/fwAAAAAAAAAPAMBngAAAAAAAAAAAAAAAAP7///8PAAAAAPz//wAAAAAAAAAACABAAAAAAAAAAAAAAAAAAPz///8HAAAAAPj//wAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAPz///8DAAAAAPj//wAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAPj///8BAAAAAPz//4AAAAAAAAAAAB8GAAAAAAAAAAAAAAAAAPj///8BAAAAAPz//8EAAAAAAAAAIB8OAAAAAAAAAAAAAAAAAPD///8BAAAAAP7//+AAAAAAAAAA+B8OACAAAAAAAAAAAAAAAMD///8BAAAAAP7/f/gAAAAAAAAA/H8eAAAAAAAAAAAAAAAAAID///8AAAAAAP7/H/gAAAAAAAAA/P8fAABAAAAAAAAAAAAAAAD///8AAAAAAPz/D3AAAAAAAAAA/v8/AAAAAAAAAAAAAAAAAAD///8AAAAAAPj/D3gAAAAAAADA//9/AAgAAAAAAAAAAAAAAAD//38AAAAAAPj/DzgAAAAAAADw////AAAAAAAAAAAAAAAAAAD//x8AAAAAAPD/DzgAAAAAAAD4////AQAAAAAAAAAAAAAAAAD//wMAAAAAAPD/DzgAAAAAAAD4////AwAAAAAAAAAAAAAAAID//wEAAAAAAPD/AwAAAAAAAAD4////AwAAAAAAAAAAAAAAAID//wEAAAAAAPD/AwAAAAAAAAD4////BwAAAAAAAAAAAAAAAID//wEAAAAAAOD/AwAAAAAAAAD4////BwAAAAAAAAAAAAAAAID//wAAAAAAAOD/AQAAAAAAAADw////BwAAAAAAAAAAAAAAAID//wAAAAAAAMD/AAAAAAAAAADw////AwAAAAAAAAAAAAAAAID/fwAAAAAAAIB/AAAAAAAAAADgf/z/AwAAAAAAAAAAAAAAAID/PwAAAAAAAIA/AAAAAAAAAADgB/D/AQAAAAAAAAAAAAAAAMD/HQAAAAAAAIABAAAAAAAAAADwAND/AQAAAAAAAAAAAAAAAMD/AwAAAAAAAAAAAAAAAAAAAAAAAID/AAAIAAAAAAAAAAAAAMD/BwAAAAAAAAAAAAAAAAAAAAAAAAD/AAAQAAAAAAAAAAAAAOD/AwAAAAAAAAAAAAAAAAAAAAAAAAA+AABwAAAAAAAAAAAAAOA/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAOA/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAOAPAAAAAAAAAAAAAAAAAAAAAAAAAABwAAAGAAAAAAAAAAAAAMAPAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAADAAAAAAAAAAAAAPAPAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMABAAAAAAAAAAAAAPADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAOABAAAAAAAAAAAAAPAHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPAHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPADAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAAAAAAAAAPABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPCBAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMAHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAcAAAAAAAAAAAAAAA+AABAAJ8//j8PAAAAAAAAAAAAAAAAAAAMAAAAAAAAAAAAAPD/fwD///////8/AAAAAAAAAAAAAAAAAIA+AAAAAAAAAAAAPP///8D/////////HwAAAAAAAAAAAAAAAIA9AAAAAAAA8Pz/////P/j//////////wMAAAAAAAAAAMAAAPB9AAAAAID/////////P/7///////////8BAAAAAAAAAOABAwB/AAAAAPD///////////////////////8AAAAAAFACPoD///9/AAAAAPD//////////////////////x8AAAAA+P////////8HAAAAAP///////////////////////wcAAAAA/v///////wMAAAAA/v///////////////////////wcAAAD8/////////w8AAA7w/////////////////////////w8AAMAB/////////wMAgB84/////////////////////////wEAAAAA/P///////3/w4AcA/////////////////////////wAAAADg//////////8/gM///////////////////////////wMAAADg/////////////f///////////////////////////z8A7wMA/v////////////////////////////////////////8/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";

const MW = 288;
const MH = 144;
let landBits: Uint8Array | null = null;
function isLand(lon: number, lat: number) {
  if (!landBits) {
    const bin = atob(LAND_B64);
    landBits = new Uint8Array(bin.length);
    for (let i = 0; i < bin.length; i++) landBits[i] = bin.charCodeAt(i);
  }
  const gx = Math.floor(((lon + 180) / 360) * MW);
  const gy = Math.floor(((90 - lat) / 180) * MH);
  if (gx < 0 || gx >= MW || gy < 0 || gy >= MH) return false;
  const b = gy * MW + gx;
  return ((landBits[b >> 3] >> (b & 7)) & 1) === 1;
}

interface GlobeNode {
  lat: number;
  lon: number;
  land: boolean;
  c: string;
}

function createGlobe({ cv, ctx, s, ink, local, signal }: StudyEnv, PHRASE: string) {
  const nodes: GlobeNode[] = [];
  /* the halftone grid is fine enough to draw a coastline; every other land cell
     also carries a letter, which is as dense as type can get and stay readable */
  const LAT_STEP = 3.05;
  let k = 0;
  let run = 0;
  let sea3 = 0;
  for (let lat = -86; lat <= 86; lat += LAT_STEP) {
    const rl = Math.cos((lat * Math.PI) / 180);
    const n = Math.max(1, Math.round(98 * rl));
    for (let i = 0; i < n; i++) {
      const lon = -180 + (360 * i) / n;
      const l = isLand(lon, lat);
      if (!l && sea3++ % 2) continue; // half the ocean carries the whole sphere
      let letter = "";
      if (l && run++ % 2 === 0) letter = PHRASE.charAt(k++ % PHRASE.length);
      nodes.push({
        lat: (lat * Math.PI) / 180,
        lon: (lon * Math.PI) / 180,
        land: l,
        c: letter,
      });
    }
  }

  let spin = 2.1;
  let vel = 0.16;
  let hover = false;
  let drag: { x: number; y: number; moved: boolean } | null = null;
  let tilt = -0.36;
  let vtilt = 0;
  const land8: (number | string)[][] = [];
  let zoom = 1;
  let zoomT = 1;
  const pins: { lat: number; lon: number; t: number }[] = [];
  let look: { x: number; y: number } | null = null;
  const sea: number[] = [];
  const soil: number[] = [];

  /* screen point -> the lat/lon it is sitting on, or null if it missed the globe */
  const view = { cx: 0, cy: 0, R: 1, cs: 1, sn: 0, ct: 1, st: 0 };
  function unproject(px: number, py: number) {
    const x1 = (px - view.cx) / view.R;
    const y2 = (view.cy - py) / view.R;
    const q = 1 - x1 * x1 - y2 * y2;
    if (q <= 0.002) return null;
    const z2 = Math.sqrt(q);
    const y0 = y2 * view.ct + z2 * view.st;
    const z1 = -y2 * view.st + z2 * view.ct;
    const x0 = x1 * view.cs + z1 * view.sn;
    const z0 = -x1 * view.sn + z1 * view.cs;
    return {
      lat: Math.asin(Math.max(-1, Math.min(1, y0))),
      lon: Math.atan2(z0, x0),
    };
  }

  const opts = { signal };
  cv.addEventListener("pointerenter", () => (hover = true), opts);
  cv.addEventListener("pointerleave", () => (hover = false), opts);
  cv.addEventListener(
    "pointerdown",
    (e) => {
      drag = { ...local(e), moved: false };
      cv.setPointerCapture(e.pointerId);
    },
    opts,
  );
  cv.addEventListener(
    "pointermove",
    (e) => {
      const p = local(e);
      look = p;
      if (!drag) return;
      vel = ((p.x - drag.x) / s.u) * 9;
      vtilt = (-(p.y - drag.y) / s.u) * 6;
      tilt = Math.max(-1.15, Math.min(1.15, tilt + vtilt * 0.016));
      drag = { ...p, moved: true };
    },
    opts,
  );
  cv.addEventListener(
    "pointerup",
    () => {
      if (drag && !drag.moved) {
        // a click that never became a drag drops a pin
        const g = unproject(drag.x, drag.y);
        if (g) {
          pins.push({ lat: g.lat, lon: g.lon, t: performance.now() });
          if (pins.length > 7) pins.shift();
        }
      }
      drag = null;
    },
    opts,
  );
  cv.addEventListener("pointercancel", () => (drag = null), opts);
  cv.addEventListener(
    "wheel",
    (e) => {
      e.preventDefault();
      zoomT = Math.max(0.85, Math.min(2.6, zoomT * Math.exp(-e.deltaY * 0.0016)));
    },
    { signal, passive: false },
  );

  function draw(now: number, dt: number) {
    ctx.clearRect(0, 0, s.w, s.h);

    zoom += (zoomT - zoom) * Math.min(1, dt / 180);
    if (!drag) {
      const idle = hover ? 0.045 : 0.16; // slow down under the hand so it can be aimed
      vel += (idle - vel) * Math.min(1, dt / 900); // coast back to the idle drift
      vtilt *= Math.pow(0.9, dt / 16);
      tilt += (vtilt * dt) / 1000;
      tilt += (-0.36 - tilt) * Math.min(1, dt / 4000);
    }
    spin += (vel * dt) / 1000;

    const cx = s.w / 2;
    const cy = s.h / 2 + s.u * 0.035;
    const R = s.u * 0.318 * zoom;
    const fs = s.u * 0.0275 * Math.pow(zoom, 0.72);
    const cs = Math.cos(spin);
    const sn = Math.sin(spin);
    const ct = Math.cos(tilt);
    const st = Math.sin(tilt);
    view.cx = cx;
    view.cy = cy;
    view.R = R;
    view.cs = cs;
    view.sn = sn;
    view.ct = ct;
    view.st = st;

    /* a soft pool of light under the cursor, so the type near it reads */
    let lx = -1e9;
    let ly = -1e9;
    const lr = s.u * 0.2;
    const lr2 = lr * lr;
    if (look && !drag) {
      lx = look.x;
      ly = look.y;
    }

    ctx.textAlign = "center";
    ctx.textBaseline = "middle";

    /* dots first, in depth passes — setting ctx.font per glyph is what kills the frame */
    sea.length = 0;
    soil.length = 0;
    for (let i = 0; i < nodes.length; i++) {
      const nd = nodes[i];
      const cl = Math.cos(nd.lat);
      const x0 = cl * Math.cos(nd.lon);
      const y0 = Math.sin(nd.lat);
      const z0 = cl * Math.sin(nd.lon);
      const x1 = x0 * cs - z0 * sn;
      const z1 = x0 * sn + z0 * cs;
      const y2 = y0 * ct - z1 * st;
      const z2 = y0 * st + z1 * ct;
      if (z2 <= 0.02) continue; // solid earth: far side is hidden

      const px = cx + x1 * R;
      const py = cy - y2 * R; // canvas y grows downward
      const dx = px - lx;
      const dy = py - ly;
      const glow = dx * dx + dy * dy < lr2 ? 1 - Math.sqrt(dx * dx + dy * dy) / lr : 0;
      if (!nd.land) {
        sea.push(px, py, Math.min(0.999, z2 + glow * 0.55));
        continue;
      }
      if (!nd.c) {
        soil.push(px, py, Math.min(0.999, z2 + glow * 0.55));
        continue;
      }

      /* tangent to this parallel, so the type runs east */
      const tx0 = -Math.sin(nd.lon);
      const tz0 = Math.cos(nd.lon);
      const tx1 = tx0 * cs - tz0 * sn;
      const tz1 = tx0 * sn + tz0 * cs;
      const ang = qang(Math.atan2(tz1 * st, tx1));
      const b = Math.min(7, Math.max(0, (Math.min(0.999, z2 + glow * 0.6) * 7.99) | 0));
      (land8[b] || (land8[b] = [])).push(px, py, ang, nd.c, 0);
    }

    /* sea and land as a halftone, six depth passes each, batched into one path per pass */
    const dmin = Math.max(0.7, s.u * 0.0029);
    const dots = (list: number[], base: number, gain: number, grow: number) => {
      for (let lvl = 0; lvl < 6; lvl++) {
        const z = (lvl + 0.5) / 6;
        const dsz = dmin * grow * (0.55 + 0.75 * z);
        ctx.fillStyle = ink(base + gain * z);
        ctx.beginPath();
        for (let q = 0; q < list.length; q += 3) {
          const lv = list[q + 2] >= 1 ? 5 : (list[q + 2] * 6) | 0;
          if (lv !== lvl) continue;
          ctx.rect(list[q] - dsz / 2, list[q + 1] - dsz / 2, dsz, dsz);
        }
        ctx.fill();
      }
    };
    dots(sea, 0.1, 0.22, 1.0);
    dots(soil, 0.34, 0.46, 1.7);

    /* land: eight size buckets, so ctx.font is touched eight times instead of a thousand */
    for (let bi = 0; bi < 8; bi++) {
      const arr = land8[bi];
      if (!arr || !arr.length) continue;
      const zb = (bi + 0.5) / 8;
      ctx.font = "italic 500 " + (fs * (0.42 + 0.58 * zb)).toFixed(2) + "px " + FACE;
      ctx.fillStyle = ink(0.28 + 0.72 * Math.pow(zb, 0.6));
      for (let t = 0; t < arr.length; t += 5) {
        ctx.save();
        ctx.translate(arr[t] as number, arr[t + 1] as number);
        ctx.rotate(arr[t + 2] as number);
        ctx.fillText(arr[t + 3] as string, 0, 0);
        ctx.restore();
      }
      arr.length = 0;
    }

    /* pins ride the surface they were dropped on */
    for (let pi = 0; pi < pins.length; pi++) {
      const pn = pins[pi];
      const pcl = Math.cos(pn.lat);
      const ax = pcl * Math.cos(pn.lon);
      const ay = Math.sin(pn.lat);
      const az = pcl * Math.sin(pn.lon);
      const bx1 = ax * cs - az * sn;
      const bz1 = ax * sn + az * cs;
      const by2 = ay * ct - bz1 * st;
      const bz2 = ay * st + bz1 * ct;
      if (bz2 <= 0.02) continue;
      const ppx = cx + bx1 * R;
      const ppy = cy - by2 * R;
      const age = (now - pn.t) / 1000;
      const pop = Math.min(1, age / 0.22);
      const rr2 = s.u * 0.016 * (0.4 + 0.6 * pop) * (0.55 + 0.45 * bz2);
      ctx.beginPath();
      ctx.arc(ppx, ppy, rr2, 0, Math.PI * 2);
      ctx.strokeStyle = ink(0.3 + 0.55 * bz2);
      ctx.lineWidth = Math.max(0.7, s.u * 0.0022);
      ctx.stroke();
      ctx.beginPath();
      ctx.arc(ppx, ppy, Math.max(0.7, rr2 * 0.22), 0, Math.PI * 2);
      ctx.fillStyle = ink(0.45 + 0.55 * bz2);
      ctx.fill();
      if (age < 0.9) {
        // a ring that opens once, on landing
        const w2 = 1 - age / 0.9;
        ctx.beginPath();
        ctx.arc(ppx, ppy, rr2 + (1 - w2) * s.u * 0.05, 0, Math.PI * 2);
        ctx.strokeStyle = ink(0.55 * w2 * w2);
        ctx.lineWidth = Math.max(0.6, s.u * 0.0016);
        ctx.stroke();
      }
    }
  }
  return { draw, reset: undefined as undefined | (() => void) };
}

export function OrbLettering({
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  text = "alettertravelsroundthesphereandcomesbackhome",
  inkColor,
  backgroundColor,
  className,
}: OrbLetteringProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const surface = backgroundColor ?? "hsl(var(--background))";
  /* re-resolve the theme tokens whenever the mode or palette on <html> changes */
  const [theme, setTheme] = useState(0);
  useEffect(() => {
    const mo = new MutationObserver(() => setTheme((t) => t + 1));
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const cv = canvasRef.current;
    if (!cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const ac = new AbortController();
    const s: Surface = { w: 0, h: 0, dpr: 1, u: 0 };

    const resize = () => {
      const width = cv.clientWidth;
      const height = cv.clientHeight;
      if (!width || !height) return false;
      const dpr = Math.min(1.5, window.devicePixelRatio || 1);
      const w = Math.round(width * dpr);
      const h = Math.round(height * dpr);
      if (w === cv.width && h === cv.height && s.w === width) return false;
      cv.width = w;
      cv.height = h;
      s.w = width;
      s.h = height;
      s.u = Math.min(width, height);
      s.dpr = dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      return true;
    };

    FACE = getComputedStyle(cv).fontFamily || "serif";
    /* faint marks lean to the muted tone, dense ones to the palette's primary */
    const lo = toRgb(cv, inkColor ?? "hsl(var(--muted-foreground))");
    const hi = toRgb(cv, inkColor ?? "hsl(var(--primary))");
    const INK64: string[] = [];
    for (let q0 = 0; q0 < 64; q0++) {
      const t = q0 / 63;
      const c = lo.map((v, i) => Math.round(v + (hi[i] - v) * Math.min(1, t * 1.4)));
      INK64.push("rgba(" + c.join(",") + "," + (t * SOFT).toFixed(4) + ")");
    }
    const ink = (a: number) => INK64[a <= 0 ? 0 : a >= 1 ? 63 : (a * 63) | 0];
    const local = (e: PointerEvent) => {
      const r = cv.getBoundingClientRect();
      const k = cv.clientWidth / (r.width || 1);
      return { x: (e.clientX - r.left) * k, y: (e.clientY - r.top) * k };
    };

    resize();
    const study = createGlobe(
      {
        cv,
        ctx,
        s,
        ink,
        local,
        signal: ac.signal,
      },
      text,
    );

    const paint = (now: number, dt: number) => {
      if (!s.w) return;
      ctx.setTransform(s.dpr, 0, 0, s.dpr, 0, 0);
      study.draw(now, dt);
    };

    let raf = 0;
    let onScreen = true;
    let prev = performance.now();
    const frame = (now: number) => {
      const dt = Math.min(64, now - prev);
      prev = now;
      paint(now, dt);
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) {
        prev = performance.now();
        raf = requestAnimationFrame(frame);
      } else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    const onResize = () => {
      resize();
      study.reset?.();
      paint(performance.now(), 16);
    };
    const ro = new ResizeObserver(onResize);
    ro.observe(cv);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(cv);
    document.addEventListener("visibilitychange", update, {
      signal: ac.signal,
    });
    onResize();
    update();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      ac.abort();
    };
  }, [inkColor, theme, prefersReducedMotion, text]);

  const boundedHue = clamp(hue, -180, 180);
  const boundedSaturation = clamp(saturation, 0, 2);
  const boundedBrightness = clamp(brightness, 0.4, 1.8);
  const boundedScale = clamp(scale, 0.65, 1.5);
  const filter =
    boundedHue === 0 && boundedSaturation === 1 && boundedBrightness === 1
      ? undefined
      : `hue-rotate(${boundedHue}deg) saturate(${boundedSaturation}) brightness(${boundedBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: surface,
        opacity: clamp(opacity, 0.1, 1),
        filter,
      }}
    >
      <div
        className="absolute inset-0 flex items-center justify-center [container-type:size]"
        style={{
          transform: boundedScale === 1 ? undefined : `scale(${boundedScale})`,
        }}
      >
        <div
          className="relative h-[min(100cqw,100cqh)] w-[min(100cqw,100cqh)] cursor-crosshair touch-none"
          style={{
            background:
              "radial-gradient(ellipse 60% 58% at 50% 48%, hsl(var(--primary) / 0.07), transparent 70%)",
          }}
        >
          <canvas
            ref={canvasRef}
            aria-label="Orb Lettering: drag to spin, scroll to zoom, click to drop a pin"
            className="absolute inset-0 block h-full w-full font-serif"
          />
        </div>
      </div>
    </div>
  );
}
```

---

# Contour Stream

> A sentence in italic serif running around the contour of an SVG mark, drawn on canvas.

Install: `npx @modus-ui/cli add contour-stream`

A mark's contour sampled as one path, with an italic serif sentence running its full length in your theme's ink. It defaults to a rounded square. Hover to speed it up, click to shove the letters outward. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add contour-stream
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/contour-stream.tsx`.
3. Paste the code.

## Usage

```tsx
import { ContourStream } from "@/components/ui/contour-stream";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ContourStream />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                                                                     | Description                                     |
| :---------------- | :------- | :-------------------------------------------------------------------------- | :---------------------------------------------- |
| `path`            | `string` | `"M6 2h12a4 4 0 0 1 4 4v12a4 4 0 0 1-4 4H6a4 4 0 0 1-4-4V6a4 4 0 0 1 4-4Z"` | SVG path data (24×24 viewBox) the type follows. |
| `text`            | `string` | `"modusfollowsthecontourandwritesitbackonemoretime"`                        | Phrase running along the outline.               |
| `scale`           | `number` | `1`                                                                         | Scales the drawing (clamped 0.65–1.5).          |
| `opacity`         | `number` | `1`                                                                         | Overall opacity (clamped 0.1–1).                |
| `hue`             | `number` | `0`                                                                         | Hue rotation in degrees (clamped -180–180).     |
| `saturation`      | `number` | `1`                                                                         | Saturation multiplier (clamped 0–2).            |
| `brightness`      | `number` | `1`                                                                         | Brightness multiplier (clamped 0.4–1.8).        |
| `inkColor`        | `string` | Theme ramp (`--muted-foreground` → `--primary`)                             | Colour of the type, any CSS colour.             |
| `backgroundColor` | `string` | `hsl(var(--background))`                                                    | Ground colour, any CSS colour.                  |

## Source

`components/ui/contour-stream.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Outline Typeflow (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface ContourStreamProps {
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  path?: string;
  text?: string;
  /** Ink colour (any CSS colour). Defaults to a ramp from --muted-foreground to --primary. */
  inkColor?: string;
  /** Ground colour (any CSS colour). Defaults to hsl(var(--background)). */
  backgroundColor?: string;
  className?: string;
}

let FACE = "serif";
/* resolves any CSS colour (including hsl(var(--token))) to an "r,g,b" triplet */
function toRgb(el: HTMLElement, color: string) {
  const probe = document.createElement("span");
  probe.style.color = color;
  probe.style.display = "none";
  el.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return m.slice(0, 3).map((v) => Math.round(Number(v)));
}
/* on black the eye needs far less ink, so every alpha runs through SOFT first */
const SOFT = 0.88;
/* Snapping every angle to one of 64 steps keeps the glyph raster cache warm. */
const QA = (Math.PI * 2) / 64;
function qang(a: number) {
  return Math.round(a / QA) * QA;
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

interface Surface {
  w: number;
  h: number;
  dpr: number;
  /* panels are not square, so scale off the short side */
  u: number;
}

interface StudyEnv {
  cv: HTMLCanvasElement;
  ctx: CanvasRenderingContext2D;
  s: Surface;
  ink: (a: number) => string;
  local: (e: PointerEvent) => { x: number; y: number };
  signal: AbortSignal;
}

/* the default mark (24x24 viewBox): a ring */
const DEFAULT_PATH = "M6 2h12a4 4 0 0 1 4 4v12a4 4 0 0 1-4 4H6a4 4 0 0 1-4-4V6a4 4 0 0 1 4-4Z";

const SVGNS = "http://www.w3.org/2000/svg";

interface PathLine {
  pts: { x: number; y: number }[];
  acc: number[];
  len: number;
}

/* dense samples of a path, split wherever the pen jumps between subpaths */
function polylines(d: string, step: number): PathLine[] {
  const scratch = document.createElementNS(SVGNS, "svg");
  scratch.setAttribute("viewBox", "0 0 24 24");
  scratch.style.cssText = "position:absolute;width:0;height:0;overflow:hidden;pointer-events:none";
  document.body.appendChild(scratch);
  const el = document.createElementNS(SVGNS, "path");
  el.setAttribute("d", d);
  scratch.appendChild(el);
  const L = el.getTotalLength();
  const n = Math.max(64, Math.ceil(L / step));
  const lines: { x: number; y: number }[][] = [];
  let cur: { x: number; y: number }[] = [];
  let prev: DOMPoint | null = null;
  for (let i = 0; i <= n; i++) {
    const p = el.getPointAtLength((L * i) / n);
    if (prev) {
      const jump = Math.hypot(p.x - prev.x, p.y - prev.y);
      if (jump > step * 6) {
        if (cur.length > 3) lines.push(cur);
        cur = [];
      }
    }
    cur.push({ x: p.x, y: p.y });
    prev = p;
  }
  if (cur.length > 3) lines.push(cur);
  document.body.removeChild(scratch);

  /* arc-length parameterise each run */
  return lines
    .map((pts) => {
      const acc = [0];
      for (let i = 1; i < pts.length; i++)
        acc.push(acc[i - 1] + Math.hypot(pts[i].x - pts[i - 1].x, pts[i].y - pts[i - 1].y));
      return { pts, acc, len: acc[acc.length - 1] };
    })
    .filter((l) => l.len > step * 8);
}

const _pt = { x: 0, y: 0, a: 0 };
function atLength(line: PathLine, t: number) {
  const len = line.len;
  t = t - Math.floor(t / len) * len; // wrap
  const a = line.acc;
  let lo = 0;
  let hi = a.length - 1;
  while (lo < hi - 1) {
    const m = (lo + hi) >> 1;
    if (a[m] <= t) lo = m;
    else hi = m;
  }
  const seg = a[hi] - a[lo] || 1;
  const f = (t - a[lo]) / seg;
  const p0 = line.pts[lo];
  const p1 = line.pts[hi];
  _pt.x = p0.x + (p1.x - p0.x) * f;
  _pt.y = p0.y + (p1.y - p0.y) * f;
  _pt.a = Math.atan2(p1.y - p0.y, p1.x - p0.x);
  return _pt;
}

function createTypeflow(
  { cv, ctx, s, ink, local, signal }: StudyEnv,
  path: string,
  PHRASE: string,
) {
  const lines = polylines(path, 0.05);
  let flow = 0;
  let speed = 1;
  let hover = false;
  let look: { x: number; y: number } | null = null;
  const burst: { t: number }[] = []; // letters kicked loose by a click

  const opts = { signal };
  cv.addEventListener("pointerenter", () => (hover = true), opts);
  cv.addEventListener(
    "pointerleave",
    () => {
      hover = false;
      look = null;
    },
    opts,
  );
  cv.addEventListener("pointermove", (e) => (look = local(e)), opts);
  cv.addEventListener(
    "pointerdown",
    () => {
      burst.push({ t: performance.now() });
      if (burst.length > 3) burst.shift();
    },
    opts,
  );

  function draw(now: number, dt: number) {
    ctx.clearRect(0, 0, s.w, s.h);

    speed += ((hover ? 3.1 : 1) - speed) * Math.min(1, dt / 280);
    flow += ((speed * dt) / 1000) * 1.9;

    const span = s.u * 0.62; // the 24-unit mark, in card px
    const k = span / 24;
    const cx = s.w / 2 - 12 * k;
    const cy = s.h / 2 + s.u * 0.02 - 12 * k;
    const fs = s.u * 0.025;
    const step = (fs * 0.76) / k; // spacing measured in path units

    /* the most recent click sends a shove outward that settles back */
    let kick = 0;
    if (burst.length) {
      const kickAge = (now - burst[burst.length - 1].t) / 1000;
      kick = Math.max(0, 1 - kickAge / 1.1);
      kick = kick * kick;
    }

    ctx.textAlign = "center";
    ctx.textBaseline = "middle";
    ctx.font = "italic 500 " + fs.toFixed(2) + "px " + FACE;
    const base = 0.92 - kick * 0.35;
    ctx.fillStyle = ink(base);
    let lit = -1; /* quantised, so fillStyle is touched rarely */
    const lx = look ? look.x : -1e9;
    const ly = look ? look.y : -1e9;
    const LR = s.u * 0.22;
    const LR2 = LR * LR;

    let idx = 0;
    for (let li = 0; li < lines.length; li++) {
      const line = lines[li];
      const n = Math.max(3, Math.round(line.len / step));
      const sp = line.len / n;
      for (let i = 0; i < n; i++) {
        const q = atLength(line, i * sp + flow);
        let px = cx + q.x * k;
        let py = cy + q.y * k;

        if (kick > 0) {
          const dx = px - (cx + 12 * k);
          const dy = py - (cy + 12 * k);
          const d = Math.hypot(dx, dy) || 1;
          const wob = Math.sin(i * 1.7 + li * 2.3);
          px += (dx / d) * kick * s.u * 0.11 * (0.6 + 0.5 * wob);
          py += (dy / d) * kick * s.u * 0.11 * (0.6 + 0.5 * wob);
        }

        let gd = 0;
        if (look) {
          const ddx = px - lx;
          const ddy = py - ly;
          const dd = ddx * ddx + ddy * ddy;
          if (dd < LR2) gd = 1 - Math.sqrt(dd) / LR;
        }
        const lv = (gd * 5) | 0;
        if (lv !== lit) {
          lit = lv;
          ctx.fillStyle = ink(base + (1 - base) * ((lv + (lv ? 0.5 : 0)) / 5));
        }
        ctx.save();
        ctx.translate(px, py);
        ctx.rotate(qang(q.a));
        ctx.fillText(PHRASE.charAt(idx++ % PHRASE.length), 0, 0);
        ctx.restore();
      }
    }
  }
  return { draw, reset: undefined as undefined | (() => void) };
}

export function ContourStream({
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  path = DEFAULT_PATH,
  text = "modusfollowsthecontourandwritesitbackonemoretime",
  inkColor,
  backgroundColor,
  className,
}: ContourStreamProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const surface = backgroundColor ?? "hsl(var(--background))";
  /* re-resolve the theme tokens whenever the mode or palette on <html> changes */
  const [theme, setTheme] = useState(0);
  useEffect(() => {
    const mo = new MutationObserver(() => setTheme((t) => t + 1));
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const cv = canvasRef.current;
    if (!cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const ac = new AbortController();
    const s: Surface = { w: 0, h: 0, dpr: 1, u: 0 };

    const resize = () => {
      const width = cv.clientWidth;
      const height = cv.clientHeight;
      if (!width || !height) return false;
      const dpr = 2;
      const w = Math.round(width * dpr);
      const h = Math.round(height * dpr);
      if (w === cv.width && h === cv.height && s.w === width) return false;
      cv.width = w;
      cv.height = h;
      s.w = width;
      s.h = height;
      s.u = Math.min(width, height);
      s.dpr = dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      return true;
    };

    FACE = getComputedStyle(cv).fontFamily || "serif";
    /* faint marks lean to the muted tone, dense ones to the palette's primary */
    const lo = toRgb(cv, inkColor ?? "hsl(var(--muted-foreground))");
    const hi = toRgb(cv, inkColor ?? "hsl(var(--primary))");
    const INK64: string[] = [];
    for (let q0 = 0; q0 < 64; q0++) {
      const t = q0 / 63;
      const c = lo.map((v, i) => Math.round(v + (hi[i] - v) * Math.min(1, t * 1.4)));
      INK64.push("rgba(" + c.join(",") + "," + (t * SOFT).toFixed(4) + ")");
    }
    const ink = (a: number) => INK64[a <= 0 ? 0 : a >= 1 ? 63 : (a * 63) | 0];
    const local = (e: PointerEvent) => {
      const r = cv.getBoundingClientRect();
      const k = cv.clientWidth / (r.width || 1);
      return { x: (e.clientX - r.left) * k, y: (e.clientY - r.top) * k };
    };

    resize();
    const study = createTypeflow(
      {
        cv,
        ctx,
        s,
        ink,
        local,
        signal: ac.signal,
      },
      path,
      text,
    );

    const paint = (now: number, dt: number) => {
      if (!s.w) return;
      ctx.setTransform(s.dpr, 0, 0, s.dpr, 0, 0);
      study.draw(now, dt);
    };

    let raf = 0;
    let onScreen = true;
    let prev = performance.now();
    const frame = (now: number) => {
      const dt = Math.min(64, now - prev);
      prev = now;
      paint(now, dt);
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) {
        prev = performance.now();
        raf = requestAnimationFrame(frame);
      } else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    const onResize = () => {
      resize();
      study.reset?.();
      paint(performance.now(), 16);
    };
    const ro = new ResizeObserver(onResize);
    ro.observe(cv);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(cv);
    document.addEventListener("visibilitychange", update, {
      signal: ac.signal,
    });
    onResize();
    update();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      ac.abort();
    };
  }, [inkColor, theme, prefersReducedMotion, path, text]);

  const boundedHue = clamp(hue, -180, 180);
  const boundedSaturation = clamp(saturation, 0, 2);
  const boundedBrightness = clamp(brightness, 0.4, 1.8);
  const boundedScale = clamp(scale, 0.65, 1.5);
  const filter =
    boundedHue === 0 && boundedSaturation === 1 && boundedBrightness === 1
      ? undefined
      : `hue-rotate(${boundedHue}deg) saturate(${boundedSaturation}) brightness(${boundedBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: surface,
        opacity: clamp(opacity, 0.1, 1),
        filter,
      }}
    >
      <div
        className="absolute inset-0 flex items-center justify-center [container-type:size]"
        style={{
          transform: boundedScale === 1 ? undefined : `scale(${boundedScale})`,
        }}
      >
        <div
          className="relative h-[min(100cqw,100cqh)] w-[min(100cqw,100cqh)] cursor-crosshair touch-none"
          style={{
            background:
              "radial-gradient(ellipse 60% 58% at 50% 48%, hsl(var(--primary) / 0.07), transparent 70%)",
          }}
        >
          <canvas
            ref={canvasRef}
            aria-label="Contour Stream: hover to speed the type, click to shove it outward"
            className="absolute inset-0 block h-full w-full font-serif"
          />
        </div>
      </div>
    </div>
  );
}
```

---

# Shifting Swarm

> A swarm of serif glyphs filling one SVG mark that turns into another on click.

Install: `npx @modus-ui/cli add shifting-swarm`

Two marks sharing a swarm of italic serif glyphs in your theme's ink, paired by angle so the change reads as a turn. It rests on the ring and turns into the spark. Click to switch, hover to push the glyphs aside. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add shifting-swarm
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/shifting-swarm.tsx`.
3. Paste the code.

## Usage

```tsx
import { ShiftingSwarm } from "@/components/ui/shifting-swarm";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ShiftingSwarm />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                                                                                      | Description                                        |
| :---------------- | :------- | :------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| `fromPath`        | `string` | `"M12 2a10 10 0 1 1 0 20a10 10 0 1 1 0-20Zm0 5a5 5 0 1 0 0 10a5 5 0 1 0 0-10Z"`              | SVG path data (24×24 viewBox) of the resting mark. |
| `toPath`          | `string` | `"M12 0C12.9 7 17 11.1 24 12C17 12.9 12.9 17 12 24C11.1 17 7 12.9 0 12C7 11.1 11.1 7 12 0Z"` | SVG path data (24×24 viewBox) it morphs into.      |
| `scale`           | `number` | `1`                                                                                          | Scales the drawing (clamped 0.65–1.5).             |
| `opacity`         | `number` | `1`                                                                                          | Overall opacity (clamped 0.1–1).                   |
| `hue`             | `number` | `0`                                                                                          | Hue rotation in degrees (clamped -180–180).        |
| `saturation`      | `number` | `1`                                                                                          | Saturation multiplier (clamped 0–2).               |
| `brightness`      | `number` | `1`                                                                                          | Brightness multiplier (clamped 0.4–1.8).           |
| `inkColor`        | `string` | Theme ramp (`--muted-foreground` → `--primary`)                                              | Colour of the type, any CSS colour.                |
| `backgroundColor` | `string` | `hsl(var(--background))`                                                                     | Ground colour, any CSS colour.                     |

## Source

`components/ui/shifting-swarm.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Morphing Glyph Cloud (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface ShiftingSwarmProps {
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  fromPath?: string;
  toPath?: string;
  /** Ink colour (any CSS colour). Defaults to a ramp from --muted-foreground to --primary. */
  inkColor?: string;
  /** Ground colour (any CSS colour). Defaults to hsl(var(--background)). */
  backgroundColor?: string;
  className?: string;
}

let FACE = "serif";
/* resolves any CSS colour (including hsl(var(--token))) to an "r,g,b" triplet */
function toRgb(el: HTMLElement, color: string) {
  const probe = document.createElement("span");
  probe.style.color = color;
  probe.style.display = "none";
  el.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return m.slice(0, 3).map((v) => Math.round(Number(v)));
}
/* on black the eye needs far less ink, so every alpha runs through SOFT first */
const SOFT = 0.88;
/* Snapping every angle to one of 64 steps keeps the glyph raster cache warm. */
const QA = (Math.PI * 2) / 64;
function qang(a: number) {
  return Math.round(a / QA) * QA;
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

interface Surface {
  w: number;
  h: number;
  dpr: number;
  /* panels are not square, so scale off the short side */
  u: number;
}

interface StudyEnv {
  cv: HTMLCanvasElement;
  ctx: CanvasRenderingContext2D;
  s: Surface;
  ink: (a: number) => string;
  local: (e: PointerEvent) => { x: number; y: number };
  signal: AbortSignal;
}

/* the two default marks (24x24 viewBox) */
const DEFAULT_FROM_PATH =
  "M12 2a10 10 0 1 1 0 20a10 10 0 1 1 0-20Zm0 5a5 5 0 1 0 0 10a5 5 0 1 0 0-10Z";
const DEFAULT_TO_PATH =
  "M12 0C12.9 7 17 11.1 24 12C17 12.9 12.9 17 12 24C11.1 17 7 12.9 0 12C7 11.1 11.1 7 12 0Z";

function rng(seed: number) {
  let s = seed >>> 0;
  return () => {
    s ^= s << 13;
    s >>>= 0;
    s ^= s >> 17;
    s ^= s << 5;
    s >>>= 0;
    return s / 4294967296;
  };
}

/* points scattered evenly inside a filled path, centred and normalised to its own
   bounding box so a short wide mark and a tall one both fill the same frame */
function fitPoints(d: string, spacing: number, rand: () => number, rule: CanvasFillRule) {
  const S = 320;
  const c = document.createElement("canvas");
  c.width = c.height = S;
  const x = c.getContext("2d", { willReadFrequently: true });
  const out: { x: number; y: number }[] = [];
  if (!x) return out;
  x.setTransform(S / 24, 0, 0, S / 24, 0, 0);
  x.fillStyle = "black";
  x.fill(new Path2D(d), rule || "evenodd");
  const data = x.getImageData(0, 0, S, S).data;
  const inside: number[] = [];
  for (let i = 0; i < S * S; i++) if (data[i * 4 + 3] > 128) inside.push(i);
  if (!inside.length) return out;
  const hit = new Uint8Array(S * S);
  let x0 = 1e9;
  let x1 = -1e9;
  let y0 = 1e9;
  let y1 = -1e9;
  for (let m = 0; m < inside.length; m++) {
    const gx = inside[m] % S;
    const gy = (inside[m] / S) | 0;
    hit[inside[m]] = 1;
    if (gx < x0) x0 = gx;
    if (gx > x1) x1 = gx;
    if (gy < y0) y0 = gy;
    if (gy > y1) y1 = gy;
  }
  const span = Math.max(x1 - x0, y1 - y0) || 1;
  const mx = (x0 + x1) / 2;
  const my = (y0 + y1) / 2;

  /* jittered grid at the glyph's own advance, so letters sit shoulder to shoulder
     without stacking into an unreadable smear */
  const cell = Math.max(1.6, spacing * span);
  for (let gy2 = y0; gy2 < y1; gy2 += cell) {
    for (let gx2 = x0; gx2 < x1; gx2 += cell) {
      const jx = gx2 + rand() * cell;
      const jy = gy2 + rand() * cell;
      const ix = jx | 0;
      const iy = jy | 0;
      if (ix < 0 || ix >= S || iy < 0 || iy >= S || !hit[iy * S + ix]) continue;
      out.push({ x: (jx - mx) / span, y: (jy - my) / span });
    }
  }
  return out;
}

const SPAN = 0.6; // fractions of the card
const FS = 0.018;
const GAP = (FS * 0.6 * 1.06) / SPAN; // one glyph advance, in shape units
const CHARS =
  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789<>/\\{}[]()=+-*#$%&@?!";

function createMark(
  { cv, ctx, s, ink, local, signal }: StudyEnv,
  fromPath: string,
  toPath: string,
) {
  const rand = rng(9152026);
  const A = fitPoints(fromPath, GAP, rand, "evenodd"); // the resting mark
  const B = fitPoints(toPath, GAP, rand, "evenodd");
  const glyphs: { c: string; ph: number; sp: number; wob: number }[] = [];
  for (let i = 0; i < Math.max(A.length, B.length); i++) {
    glyphs.push({
      c: CHARS.charAt((rand() * CHARS.length) | 0),
      ph: rand() * Math.PI * 2,
      sp: 0.55 + rand() * 0.9,
      wob: 0.4 + rand() * 0.8,
    });
  }
  /* keep the two clouds paired by angle so the morph reads as a rotation, not a shuffle */
  function order(set: { x: number; y: number }[]) {
    return set
      .map((p, i) => ({ i, a: Math.atan2(p.y, p.x), r: Math.hypot(p.x, p.y) }))
      .sort((u, v) => u.a - v.a || u.r - v.r)
      .map((o) => o.i);
  }
  const oa = order(A);
  const ob = order(B);
  const M = Math.min(A.length, B.length);
  const pair: [{ x: number; y: number }, { x: number; y: number }][] = [];
  for (let j = 0; j < M; j++)
    pair.push([A[oa[((j * A.length) / M) | 0]], B[ob[((j * B.length) / M) | 0]]]);

  let m = 0;
  let target = 0;
  let hover: { x: number; y: number } | null = null;
  let live = true;

  const opts = { signal };
  cv.addEventListener(
    "pointerdown",
    () => {
      target = 1 - target;
      live = true;
    },
    opts,
  );
  cv.addEventListener(
    "pointermove",
    (e) => {
      hover = local(e);
      live = true;
    },
    opts,
  );
  cv.addEventListener(
    "pointerleave",
    () => {
      hover = null;
      live = true;
    },
    opts,
  );

  function draw(now: number, dt: number) {
    const moving = hover || Math.abs(target - m) > 1e-4;
    if (!moving && !live) return; // settled: the last frame stays on screen
    live = !!moving;
    ctx.clearRect(0, 0, s.w, s.h);

    m += (target - m) * Math.min(1, dt / 460);
    const e = m < 0.5 ? 4 * m * m * m : 1 - Math.pow(-2 * m + 2, 3) / 2; // easeInOutCubic

    const span = s.u * SPAN;
    const cx = s.w / 2;
    const cy = s.h / 2 + s.u * 0.02;
    const fs = s.u * FS;
    const t = now / 1000;
    const travel = 4 * e * (1 - e); // biggest scatter mid-flight

    ctx.textAlign = "center";
    ctx.textBaseline = "middle";
    ctx.font = "italic 500 " + fs.toFixed(2) + "px " + FACE;
    ctx.fillStyle = ink(0.88);
    let dirty = false;

    for (let i = 0; i < pair.length; i++) {
      const g = glyphs[i];
      const p = pair[i];
      const ux = p[0].x + (p[1].x - p[0].x) * e;
      const uy = p[0].y + (p[1].y - p[0].y) * e;
      let px = cx + ux * span;
      let py = cy + uy * span;

      /* a slow breath at rest, an arc while morphing */
      px += Math.sin(t * g.sp + g.ph) * s.u * 0.0035 * g.wob;
      py += Math.cos(t * g.sp * 0.9 + g.ph) * s.u * 0.0035 * g.wob;
      py -= travel * Math.sin(g.ph) * s.u * 0.05;

      let a = 0.88;
      if (hover) {
        const dx = px - hover.x;
        const dy = py - hover.y;
        const d2 = dx * dx + dy * dy;
        const rr = s.u * 0.1;
        if (d2 < rr * rr) {
          const d = Math.sqrt(d2) || 1;
          const push = 1 - d / rr;
          px += (dx / d) * push * push * s.u * 0.055;
          py += (dy / d) * push * push * s.u * 0.055;
          a = 0.88 - 0.35 * push;
        }
      }
      if (a !== 0.88) {
        ctx.fillStyle = ink(a);
        dirty = true;
      } else if (dirty) {
        ctx.fillStyle = ink(0.88);
        dirty = false;
      }
      ctx.fillText(g.c, px, py);
    }
  }
  return {
    draw,
    reset: () => {
      live = true;
    },
  };
}

export function ShiftingSwarm({
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  fromPath = DEFAULT_FROM_PATH,
  toPath = DEFAULT_TO_PATH,
  inkColor,
  backgroundColor,
  className,
}: ShiftingSwarmProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const surface = backgroundColor ?? "hsl(var(--background))";
  /* re-resolve the theme tokens whenever the mode or palette on <html> changes */
  const [theme, setTheme] = useState(0);
  useEffect(() => {
    const mo = new MutationObserver(() => setTheme((t) => t + 1));
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const cv = canvasRef.current;
    if (!cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const ac = new AbortController();
    const s: Surface = { w: 0, h: 0, dpr: 1, u: 0 };

    const resize = () => {
      const width = cv.clientWidth;
      const height = cv.clientHeight;
      if (!width || !height) return false;
      const dpr = 2;
      const w = Math.round(width * dpr);
      const h = Math.round(height * dpr);
      if (w === cv.width && h === cv.height && s.w === width) return false;
      cv.width = w;
      cv.height = h;
      s.w = width;
      s.h = height;
      s.u = Math.min(width, height);
      s.dpr = dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      return true;
    };

    FACE = getComputedStyle(cv).fontFamily || "serif";
    /* faint marks lean to the muted tone, dense ones to the palette's primary */
    const lo = toRgb(cv, inkColor ?? "hsl(var(--muted-foreground))");
    const hi = toRgb(cv, inkColor ?? "hsl(var(--primary))");
    const INK64: string[] = [];
    for (let q0 = 0; q0 < 64; q0++) {
      const t = q0 / 63;
      const c = lo.map((v, i) => Math.round(v + (hi[i] - v) * Math.min(1, t * 1.4)));
      INK64.push("rgba(" + c.join(",") + "," + (t * SOFT).toFixed(4) + ")");
    }
    const ink = (a: number) => INK64[a <= 0 ? 0 : a >= 1 ? 63 : (a * 63) | 0];
    const local = (e: PointerEvent) => {
      const r = cv.getBoundingClientRect();
      const k = cv.clientWidth / (r.width || 1);
      return { x: (e.clientX - r.left) * k, y: (e.clientY - r.top) * k };
    };

    resize();
    const study = createMark(
      {
        cv,
        ctx,
        s,
        ink,
        local,
        signal: ac.signal,
      },
      fromPath,
      toPath,
    );

    const paint = (now: number, dt: number) => {
      if (!s.w) return;
      ctx.setTransform(s.dpr, 0, 0, s.dpr, 0, 0);
      study.draw(now, dt);
    };

    let raf = 0;
    let onScreen = true;
    let prev = performance.now();
    const frame = (now: number) => {
      const dt = Math.min(64, now - prev);
      prev = now;
      paint(now, dt);
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) {
        prev = performance.now();
        raf = requestAnimationFrame(frame);
      } else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    const onResize = () => {
      resize();
      study.reset?.();
      paint(performance.now(), 16);
    };
    const ro = new ResizeObserver(onResize);
    ro.observe(cv);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(cv);
    document.addEventListener("visibilitychange", update, {
      signal: ac.signal,
    });
    onResize();
    update();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      ac.abort();
    };
  }, [inkColor, theme, prefersReducedMotion, fromPath, toPath]);

  const boundedHue = clamp(hue, -180, 180);
  const boundedSaturation = clamp(saturation, 0, 2);
  const boundedBrightness = clamp(brightness, 0.4, 1.8);
  const boundedScale = clamp(scale, 0.65, 1.5);
  const filter =
    boundedHue === 0 && boundedSaturation === 1 && boundedBrightness === 1
      ? undefined
      : `hue-rotate(${boundedHue}deg) saturate(${boundedSaturation}) brightness(${boundedBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: surface,
        opacity: clamp(opacity, 0.1, 1),
        filter,
      }}
    >
      <div
        className="absolute inset-0 flex items-center justify-center [container-type:size]"
        style={{
          transform: boundedScale === 1 ? undefined : `scale(${boundedScale})`,
        }}
      >
        <div
          className="relative h-[min(100cqw,100cqh)] w-[min(100cqw,100cqh)] cursor-crosshair touch-none"
          style={{
            background:
              "radial-gradient(ellipse 60% 58% at 50% 48%, hsl(var(--primary) / 0.07), transparent 70%)",
          }}
        >
          <canvas
            ref={canvasRef}
            aria-label="Shifting Swarm: click to move the swarm between the two marks"
            className="absolute inset-0 block h-full w-full font-serif"
          />
        </div>
      </div>
    </div>
  );
}
```

---

# Drape Type

> A verlet drape woven from italic serif letters in your theme's ink. Grab it and pull.

Install: `npx @modus-ui/cli add drape-type`

A sheet of italic serif letters hanging from five pegs on the page, faint strokes in the muted tone and dense folds in the palette's primary. Letters stretch and rotate with the weave; grab the sheet and pull. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add drape-type
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/drape-type.tsx`.
3. Paste the code.

## Usage

```tsx
import { DrapeType } from "@/components/ui/drape-type";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <DrapeType />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                                                     | Description                                 |
| :---------------- | :------- | :---------------------------------------------------------- | :------------------------------------------ |
| `text`            | `string` | `"modusholdsthefoldandletsthedraftcarryeverylinetotheedge"` | Phrase woven into the sheet.                |
| `scale`           | `number` | `1`                                                         | Scales the drawing (clamped 0.65–1.5).      |
| `opacity`         | `number` | `1`                                                         | Overall opacity (clamped 0.1–1).            |
| `hue`             | `number` | `0`                                                         | Hue rotation in degrees (clamped -180–180). |
| `saturation`      | `number` | `1`                                                         | Saturation multiplier (clamped 0–2).        |
| `brightness`      | `number` | `1`                                                         | Brightness multiplier (clamped 0.4–1.8).    |
| `inkColor`        | `string` | Theme ramp (`--muted-foreground` → `--primary`)             | Colour of the type, any CSS colour.         |
| `backgroundColor` | `string` | `hsl(var(--background))`                                    | Ground colour, any CSS colour.              |

## Source

`components/ui/drape-type.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Cloth Study (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface DrapeTypeProps {
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  text?: string;
  /** Ink colour (any CSS colour). Defaults to a ramp from --muted-foreground to --primary. */
  inkColor?: string;
  /** Ground colour (any CSS colour). Defaults to hsl(var(--background)). */
  backgroundColor?: string;
  className?: string;
}

let FACE = "serif";
/* resolves any CSS colour (including hsl(var(--token))) to an "r,g,b" triplet */
function toRgb(el: HTMLElement, color: string) {
  const probe = document.createElement("span");
  probe.style.color = color;
  probe.style.display = "none";
  el.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return m.slice(0, 3).map((v) => Math.round(Number(v)));
}
/* on black the eye needs far less ink, so every alpha runs through SOFT first */
const SOFT = 0.88;
/* Snapping every angle to one of 64 steps keeps the glyph raster cache warm. */
const QA = (Math.PI * 2) / 64;
function qang(a: number) {
  return Math.round(a / QA) * QA;
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

interface Surface {
  w: number;
  h: number;
  dpr: number;
  /* panels are not square, so scale off the short side */
  u: number;
}

interface StudyEnv {
  cv: HTMLCanvasElement;
  ctx: CanvasRenderingContext2D;
  s: Surface;
  ink: (a: number) => string;
  local: (e: PointerEvent) => { x: number; y: number };
  signal: AbortSignal;
}

const GX = 19;
const GY = 21;

interface ClothPoint {
  x: number;
  y: number;
  px: number;
  py: number;
  pin: { x: number; y: number } | null;
  free: number;
  gx?: number;
  gy?: number;
}

function createCloth({ cv, ctx, s, ink, local, signal }: StudyEnv, PHRASE: string) {
  let pts: ClothPoint[] = [];
  let rest = 0;
  let built = 0;
  let pointer: { x: number; y: number } | null = null;
  let wind = 0;
  let held: ClothPoint | null = null;

  function build() {
    const w = s.w;
    if (!w) return;
    rest = (s.u * 0.58) / (GX - 1);
    const x0 = w / 2 - (rest * (GX - 1)) / 2;
    const y0 = s.h * 0.185;
    pts = [];
    for (let j = 0; j < GY; j++)
      for (let i = 0; i < GX; i++) {
        const x = x0 + i * rest;
        const y = y0 + j * rest;
        pts.push({
          x,
          y,
          px: x,
          py: y,
          pin: j === 0 && (i % 5 === 0 || i === GX - 1) ? { x, y } : null,
          free: 0,
        });
      }
    built = w;
  }
  const P = (i: number, j: number) => pts[j * GX + i];

  const opts = { signal };
  cv.addEventListener(
    "pointermove",
    (e) => {
      pointer = local(e);
      if (held) {
        held.gx = pointer.x;
        held.gy = pointer.y;
      }
    },
    opts,
  );
  cv.addEventListener("pointerleave", () => (pointer = null), opts);
  cv.addEventListener(
    "pointerdown",
    (e) => {
      const p = local(e);
      let best: ClothPoint | null = null;
      let bd = 1e9;
      for (let k = 0; k < pts.length; k++) {
        const q = pts[k];
        if (q.pin) continue;
        const d = (q.x - p.x) * (q.x - p.x) + (q.y - p.y) * (q.y - p.y);
        if (d < bd) {
          bd = d;
          best = q;
        }
      }
      if (best && bd < s.u * 0.24 * (s.u * 0.24)) {
        held = best;
        held.gx = p.x;
        held.gy = p.y;
        cv.setPointerCapture(e.pointerId);
      }
    },
    opts,
  );
  const drop = () => (held = null);
  cv.addEventListener("pointerup", drop, opts);
  cv.addEventListener("pointercancel", drop, opts);

  /* fixed-step verlet: a variable dt makes the constraint pass under-relax and the
     sheet collapses instead of hanging */
  let acc2 = 0;
  const H = 1 / 120;
  function step(dtms: number) {
    acc2 += Math.min(50, dtms) / 1000;
    let guard = 0;
    while (acc2 >= H && guard++ < 2) {
      acc2 -= H;
      substep(H);
    }
  }
  function substep(h: number) {
    const g = s.w * 1.6;
    const now = performance.now();
    wind += h;
    const hh = h * h;
    const damp = 0.992;
    for (let k = 0; k < pts.length; k++) {
      const p = pts[k];
      if (held && p === held) {
        p.px = p.x;
        p.py = p.y;
        p.x += (held.gx! - p.x) * 0.45; // the hand leads, the cloth follows
        p.y += (held.gy! - p.y) * 0.45;
        continue;
      }
      if (p.pin && p.free < now) {
        p.x = p.pin.x;
        p.y = p.pin.y;
        p.px = p.x;
        p.py = p.y;
        continue;
      }
      const vx = (p.x - p.px) * damp;
      const vy = (p.y - p.py) * damp;
      p.px = p.x;
      p.py = p.y;
      const breeze =
        (Math.sin(wind * 1.9 + p.y * 0.035) * 0.55 + Math.sin(wind * 0.7) * 0.45) * s.u * 0.55;
      p.x += vx + breeze * hh;
      p.y += vy + g * hh;
      if (pointer && !held) {
        // a passing hand only brushes it
        const dx = p.x - pointer.x;
        const dy = p.y - pointer.y;
        const d = Math.hypot(dx, dy);
        const rr = s.u * 0.13;
        if (d < rr && d > 0.001) {
          const push = (1 - d / rr) * (1 - d / rr) * s.u * 0.008;
          p.x += (dx / d) * push;
          p.y += (dy / d) * push;
        }
      }
    }
    const iters = held ? 12 : 6; // a hand on it needs the constraint to travel
    for (let it = 0; it < iters; it++) {
      for (let j = 0; j < GY; j++)
        for (let i = 0; i < GX; i++) {
          if (i < GX - 1) solve(P(i, j), P(i + 1, j), rest);
          if (j < GY - 1) solve(P(i, j), P(i, j + 1), rest);
        }
      for (let m = 0; m < pts.length; m++) {
        const q = pts[m];
        if (held && q === held) {
          q.x = held.gx!;
          q.y = held.gy!;
          continue;
        }
        if (q.pin && q.free < now) {
          q.x = q.pin.x;
          q.y = q.pin.y;
        }
      }
    }
    /* a final hard clamp: cloth stretches a little and then simply refuses,
       otherwise a long pull draws it out into strings */
    const lim = rest * 1.14;
    for (let j2 = 0; j2 < GY; j2++)
      for (let i2 = 0; i2 < GX; i2++) {
        if (i2 < GX - 1) clampLink(P(i2, j2), P(i2 + 1, j2), lim);
        if (j2 < GY - 1) clampLink(P(i2, j2), P(i2, j2 + 1), lim);
      }
  }
  function clampLink(a: ClothPoint, b: ClothPoint, lim: number) {
    const dx = b.x - a.x;
    const dy = b.y - a.y;
    const d = Math.hypot(dx, dy);
    if (d <= lim || d < 1e-4) return;
    const f = ((d - lim) / d) * 0.5;
    const ox = dx * f;
    const oy = dy * f;
    if (a !== held && !(a.pin && a.free < performance.now())) {
      a.x += ox;
      a.y += oy;
    }
    if (b !== held && !(b.pin && b.free < performance.now())) {
      b.x -= ox;
      b.y -= oy;
    }
  }
  function solve(a: ClothPoint, b: ClothPoint, len: number) {
    const dx = b.x - a.x;
    const dy = b.y - a.y;
    const d = Math.hypot(dx, dy) || 1e-4;
    const diff = ((d - len) / d) * 0.5;
    const ox = dx * diff;
    const oy = dy * diff;
    a.x += ox;
    a.y += oy;
    b.x -= ox;
    b.y -= oy;
  }

  function draw(now: number, dt: number) {
    if (built !== s.w) build();
    ctx.clearRect(0, 0, s.w, s.h);
    step(dt);

    const fs = rest * 0.86;
    ctx.textAlign = "center";
    ctx.textBaseline = "middle";
    ctx.font = "italic 500 " + fs.toFixed(2) + "px " + FACE;
    let idx = 0;
    for (let j = 0; j < GY - 1; j++) {
      for (let i = 0; i < GX - 1; i++) {
        const a = P(i, j);
        const b = P(i + 1, j);
        const c = P(i, j + 1);
        const d2 = P(i + 1, j + 1);
        const mx = (a.x + b.x + c.x + d2.x) / 4;
        const my = (a.y + b.y + c.y + d2.y) / 4;
        const ex = (b.x - a.x + d2.x - c.x) / 2;
        const ey = (b.y - a.y + d2.y - c.y) / 2;
        const fx = (c.x - a.x + d2.x - b.x) / 2;
        const fy = (c.y - a.y + d2.y - b.y) / 2;
        const sx = Math.hypot(ex, ey) / rest;
        const sy = Math.hypot(fx, fy) / rest;
        const area = Math.abs(ex * fy - ey * fx) / (rest * rest); // stands in for facing
        const ang = Math.atan2(ey, ex);
        const a2 = 0.2 + 0.75 * Math.min(1, area);
        ctx.save();
        ctx.translate(mx, my);
        ctx.rotate(qang(ang));
        ctx.scale(Math.max(0.15, Math.min(1.7, sx)), Math.max(0.15, Math.min(1.7, sy)));
        ctx.fillStyle = ink(a2);
        ctx.fillText(PHRASE.charAt(idx++ % PHRASE.length), 0, 0);
        ctx.restore();
      }
    }

    /* the pegs it hangs from */
    for (let i2 = 0; i2 < GX; i2++) {
      const q = P(i2, 0);
      if (!q.pin) continue;
      const pinned = q.free < now;
      ctx.beginPath();
      ctx.arc(q.pin.x, q.pin.y, s.w * (pinned ? 0.006 : 0.004), 0, Math.PI * 2);
      ctx.fillStyle = ink(pinned ? 0.62 : 0.22);
      ctx.fill();
    }
  }
  return { draw, reset: build };
}

export function DrapeType({
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  text = "modusholdsthefoldandletsthedraftcarryeverylinetotheedge",
  inkColor,
  backgroundColor,
  className,
}: DrapeTypeProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const surface = backgroundColor ?? "hsl(var(--background))";
  /* re-resolve the theme tokens whenever the mode or palette on <html> changes */
  const [theme, setTheme] = useState(0);
  useEffect(() => {
    const mo = new MutationObserver(() => setTheme((t) => t + 1));
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const cv = canvasRef.current;
    if (!cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const ac = new AbortController();
    const s: Surface = { w: 0, h: 0, dpr: 1, u: 0 };

    const resize = () => {
      const width = cv.clientWidth;
      const height = cv.clientHeight;
      if (!width || !height) return false;
      const dpr = Math.min(1.5, window.devicePixelRatio || 1);
      const w = Math.round(width * dpr);
      const h = Math.round(height * dpr);
      if (w === cv.width && h === cv.height && s.w === width) return false;
      cv.width = w;
      cv.height = h;
      s.w = width;
      s.h = height;
      s.u = Math.min(width, height);
      s.dpr = dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      return true;
    };

    FACE = getComputedStyle(cv).fontFamily || "serif";
    /* faint marks lean to the muted tone, dense ones to the palette's primary */
    const lo = toRgb(cv, inkColor ?? "hsl(var(--muted-foreground))");
    const hi = toRgb(cv, inkColor ?? "hsl(var(--primary))");
    const INK64: string[] = [];
    for (let q0 = 0; q0 < 64; q0++) {
      const t = q0 / 63;
      const c = lo.map((v, i) => Math.round(v + (hi[i] - v) * Math.min(1, t * 1.4)));
      INK64.push("rgba(" + c.join(",") + "," + (t * SOFT).toFixed(4) + ")");
    }
    const ink = (a: number) => INK64[a <= 0 ? 0 : a >= 1 ? 63 : (a * 63) | 0];
    const local = (e: PointerEvent) => {
      const r = cv.getBoundingClientRect();
      const k = cv.clientWidth / (r.width || 1);
      return { x: (e.clientX - r.left) * k, y: (e.clientY - r.top) * k };
    };

    resize();
    const study = createCloth(
      {
        cv,
        ctx,
        s,
        ink,
        local,
        signal: ac.signal,
      },
      text,
    );

    const paint = (now: number, dt: number) => {
      if (!s.w) return;
      ctx.setTransform(s.dpr, 0, 0, s.dpr, 0, 0);
      study.draw(now, dt);
    };

    let raf = 0;
    let onScreen = true;
    let prev = performance.now();
    const frame = (now: number) => {
      const dt = Math.min(64, now - prev);
      prev = now;
      paint(now, dt);
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) {
        prev = performance.now();
        raf = requestAnimationFrame(frame);
      } else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    const onResize = () => {
      resize();
      study.reset?.();
      paint(performance.now(), 16);
    };
    const ro = new ResizeObserver(onResize);
    ro.observe(cv);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(cv);
    document.addEventListener("visibilitychange", update, {
      signal: ac.signal,
    });
    onResize();
    update();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      ac.abort();
    };
  }, [inkColor, theme, prefersReducedMotion, text]);

  const boundedHue = clamp(hue, -180, 180);
  const boundedSaturation = clamp(saturation, 0, 2);
  const boundedBrightness = clamp(brightness, 0.4, 1.8);
  const boundedScale = clamp(scale, 0.65, 1.5);
  const filter =
    boundedHue === 0 && boundedSaturation === 1 && boundedBrightness === 1
      ? undefined
      : `hue-rotate(${boundedHue}deg) saturate(${boundedSaturation}) brightness(${boundedBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: surface,
        opacity: clamp(opacity, 0.1, 1),
        filter,
      }}
    >
      <div
        className="absolute inset-0 flex items-center justify-center [container-type:size]"
        style={{
          transform: boundedScale === 1 ? undefined : `scale(${boundedScale})`,
        }}
      >
        <div
          className="relative h-[min(100cqw,100cqh)] w-[min(100cqw,100cqh)] cursor-crosshair touch-none"
          style={{
            background:
              "radial-gradient(ellipse 60% 58% at 50% 48%, hsl(var(--primary) / 0.07), transparent 70%)",
          }}
        >
          <canvas
            ref={canvasRef}
            aria-label="Drape Type: grab the sheet of letters and pull"
            className="absolute inset-0 block h-full w-full font-serif"
          />
        </div>
      </div>
    </div>
  );
}
```

---

# Glyph Surge

> A quiet field of mono glyphs where every click sends a surge of weight and colour through the type.

Install: `npx @modus-ui/cli add glyph-surge`

A 19×19 field of mono glyphs set in faint theme ink. It opens with one surge from the centre, and each click fires another that travels outward, swelling the letters it passes and lifting them into the primary colour. Colours and type follow the active Modus theme and palette. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add glyph-surge
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/glyph-surge.tsx`.
3. Paste the code.

## Usage

```tsx
import { GlyphSurge } from "@/components/ui/glyph-surge";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <GlyphSurge />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                 |
| :---------------- | :------- | :------------------- | :------------------------------------------ |
| `scale`           | `number` | `1`                  | Scales the drawing (clamped 0.65–1.5).      |
| `opacity`         | `number` | `1`                  | Overall opacity (clamped 0.1–1).            |
| `hue`             | `number` | `0`                  | Hue rotation in degrees (clamped -180–180). |
| `saturation`      | `number` | `1`                  | Saturation multiplier (clamped 0–2).        |
| `brightness`      | `number` | `1`                  | Brightness multiplier (clamped 0.4–1.8).    |
| `inkColor`        | `string` | Theme `--foreground` | Resting colour of the type, any CSS colour. |
| `backgroundColor` | `string` | Theme `--background` | Background colour, any CSS colour.          |

## Source

`components/ui/glyph-surge.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Ripple Study (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface GlyphSurgeProps {
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  inkColor?: string;
  backgroundColor?: string;
  className?: string;
}

const CHARS =
  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789=?#§¶△◊×÷%@&*/<>+-$¥£~^|:;.,()[]{}";
const N = 19;
const LIFE = 1250; // ms

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

/** Reads a theme token (bare HSL channels) or passes a CSS colour through, as "r,g,b". */
function toRgb(el: HTMLElement, color: string) {
  el.style.color = color;
  const m = getComputedStyle(el).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  return m.slice(0, 3).join(",");
}

function rng(seed: number) {
  let s = seed >>> 0;
  return () => {
    s ^= s << 13;
    s >>>= 0;
    s ^= s >> 17;
    s ^= s << 5;
    s >>>= 0;
    return s / 4294967296;
  };
}

export function GlyphSurge({
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  inkColor,
  backgroundColor,
  className,
}: GlyphSurgeProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const surface = backgroundColor ?? "hsl(var(--background))";

  useEffect(() => {
    const cv = canvasRef.current;
    if (!cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const ac = new AbortController();
    const s = { w: 0, h: 0, dpr: 1 };
    const ink = { base: "0,0,0", peak: "0,0,0", font: "monospace" };
    const probe = document.createElement("span");
    probe.style.display = "none";
    cv.parentElement!.appendChild(probe);
    const readTheme = () => {
      ink.base = toRgb(probe, inkColor ?? "hsl(var(--foreground))");
      ink.peak = toRgb(probe, "hsl(var(--primary))");
      ink.font = getComputedStyle(cv).fontFamily;
    };
    readTheme();
    const mo = new MutationObserver(() => {
      readTheme();
      draw(performance.now());
    });
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "style"],
    });

    const resize = () => {
      const r = { width: cv.clientWidth, height: cv.clientHeight };
      if (!r.width || !r.height) return false;
      const dpr = Math.min(2, window.devicePixelRatio || 1);
      const w = Math.round(r.width * dpr);
      const h = Math.round(r.height * dpr);
      if (w === cv.width && h === cv.height && s.w === r.width) return false;
      cv.width = w;
      cv.height = h;
      s.w = r.width;
      s.h = r.height;
      s.dpr = dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      return true;
    };

    const plate: string[] = [];
    const r0 = rng(20260809);
    for (let i = 0; i < N * N; i++) plate.push(CHARS.charAt(Math.floor(r0() * CHARS.length)));

    const rings: { x: number; y: number; t: number }[] = [];

    const draw = (now: number) => {
      ctx.clearRect(0, 0, s.w, s.h);

      const size = Math.min(s.w, s.h);
      const cell = size * 0.042;
      const fs = cell * 0.9;
      const x0 = s.w / 2 - (cell * (N - 1)) / 2;
      const y0 = s.h / 2 - (cell * (N - 1)) / 2;

      while (rings.length && now - rings[0].t > LIFE) rings.shift();

      const speed = size * 1.2; // px / s
      const band = cell * 2.45;

      ctx.textAlign = "center";
      ctx.textBaseline = "middle";
      ctx.font = fs.toFixed(2) + "px " + ink.font;
      ctx.lineJoin = "round";

      for (let gy = 0; gy < N; gy++) {
        const py = y0 + gy * cell;
        for (let gx = 0; gx < N; gx++) {
          const px = x0 + gx * cell;
          let v = 0;
          for (let k = 0; k < rings.length; k++) {
            const R = rings[k];
            const age = (now - R.t) / 1000;
            if (age < 0) continue;
            const rad = speed * age;
            const dx = px - R.x;
            const dy = py - R.y;
            const d = Math.sqrt(dx * dx + dy * dy);
            let q = (d - rad) / band;
            if (q > 2.4 || q < -3.8) continue;
            if (q < 0) q *= 0.62; // the wave drags a tail behind its front
            const env = Math.max(0, 1 - age / (LIFE / 1000));
            v += Math.exp(-q * q) * Math.pow(env, 1.15);
          }
          if (v > 1) v = 1;

          const ch = plate[gy * N + gx];
          // quiet plate; the passing wave lifts glyphs into the primary ink and swells them
          ctx.fillStyle = "rgba(" + ink.base + "," + (0.28 + v * 0.3).toFixed(3) + ")";
          ctx.fillText(ch, px, py);
          if (v > 0.03) {
            const col = "rgba(" + ink.peak + "," + v.toFixed(3) + ")";
            ctx.fillStyle = col;
            ctx.strokeStyle = col;
            ctx.lineWidth = fs * v * 0.12;
            ctx.fillText(ch, px, py);
            ctx.strokeText(ch, px, py);
          }
        }
      }
    };

    let raf = 0;
    let onScreen = true;
    const frame = (now: number) => {
      draw(now);
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) raf = requestAnimationFrame(frame);
      else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    cv.addEventListener(
      "pointerdown",
      (e) => {
        const r = cv.getBoundingClientRect();
        const k = cv.clientWidth / (r.width || 1);
        rings.push({
          x: (e.clientX - r.left) * k,
          y: (e.clientY - r.top) * k,
          t: performance.now(),
        });
        if (rings.length > 8) rings.shift();
      },
      { signal: ac.signal },
    );

    const onResize = () => {
      if (resize()) rings.length = 0;
      draw(performance.now());
    };
    const ro = new ResizeObserver(onResize);
    ro.observe(cv);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(cv);
    document.addEventListener("visibilitychange", update, {
      signal: ac.signal,
    });
    onResize();
    // open with one surge from the centre so the field introduces itself
    if (!prefersReducedMotion) rings.push({ x: s.w / 2, y: s.h / 2, t: performance.now() + 300 });
    update();

    return () => {
      cancelAnimationFrame(raf);
      mo.disconnect();
      probe.remove();
      ro.disconnect();
      io.disconnect();
      ac.abort();
    };
  }, [inkColor, prefersReducedMotion]);

  const boundedHue = clamp(hue, -180, 180);
  const boundedSaturation = clamp(saturation, 0, 2);
  const boundedBrightness = clamp(brightness, 0.4, 1.8);
  const boundedScale = clamp(scale, 0.65, 1.5);
  const filter =
    boundedHue === 0 && boundedSaturation === 1 && boundedBrightness === 1
      ? undefined
      : `hue-rotate(${boundedHue}deg) saturate(${boundedSaturation}) brightness(${boundedBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{
        background: surface,
        opacity: clamp(opacity, 0.1, 1),
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-label="Glyph field: click to send a surge through the type"
        className="absolute inset-0 block h-full w-full cursor-crosshair touch-none font-mono"
        style={{
          transform: boundedScale === 1 ? undefined : `scale(${boundedScale})`,
        }}
      />
    </div>
  );
}
```

---

# Sphere Sketch

> Italic serif letters wrapped around a turning globe; click to shake some loose.

Install: `npx @modus-ui/cli add sphere-sketch`

1,900 italic serif letters and printer's marks wrapped around a turning globe, inked in the theme foreground with the side facing you picked out in the primary colour. Hover to spin faster, click to shake letters off; they tumble away in the primary colour and regrow. Colours and the typeface come from the theme, so it follows light and dark mode and the palette picker. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add sphere-sketch
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/sphere-sketch.tsx`.
3. Paste the code.

## Usage

```tsx
import { SphereSketch } from "@/components/ui/sphere-sketch";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SphereSketch />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default | Description                                                    |
| :---------------- | :------- | :------ | :------------------------------------------------------------- |
| `scale`           | `number` | `1`     | Scales the drawing (clamped 0.65–1.5).                         |
| `opacity`         | `number` | `1`     | Overall opacity (clamped 0.1–1).                               |
| `hue`             | `number` | `0`     | Hue rotation in degrees (clamped -180–180).                    |
| `saturation`      | `number` | `1`     | Saturation multiplier (clamped 0–2).                           |
| `brightness`      | `number` | `1`     | Brightness multiplier (clamped 0.4–1.8).                       |
| `inkColor`        | `string` | None    | Any CSS colour for the type; defaults to the theme foreground. |
| `backgroundColor` | `string` | None    | Background colour; defaults to the theme background.           |
| `className`       | `string` | None    | Extra classes for the wrapper.                                 |

## Source

`components/ui/sphere-sketch.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Ball Study (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface SphereSketchProps {
  scale?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  inkColor?: string;
  backgroundColor?: string;
  className?: string;
}

const CHARS = "abcdefghijklmnopqrstuvwxyzæœßfi&¶§†‡*?!;:,.()[]αβγδεζηθλμξπσφψω";
const N = 1900;
const TILT = 0.17;
const ct = Math.cos(TILT);
const st = Math.sin(TILT);
// radius / glyph size / drop, as fractions of the card
const RR = 0.3065;
const FS = 0.0265;
const CYOFF = 0.046;

interface Part {
  x: number;
  y: number;
  vx: number;
  vy: number;
  rot: number;
  vr: number;
  size: number;
  c: string;
  t: number;
  life: number;
}

function clamp(value: number, min: number, max: number) {
  return Math.min(max, Math.max(min, value));
}

/** Reads a bare-HSL theme token (e.g. `--foreground`) as a canvas colour. */
function token(name: string) {
  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  return v ? `hsl(${v})` : "currentColor";
}

function rng(seed: number) {
  let s = seed >>> 0;
  return () => {
    s ^= s << 13;
    s >>>= 0;
    s ^= s >> 17;
    s ^= s << 5;
    s >>>= 0;
    return s / 4294967296;
  };
}

export function SphereSketch({
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  inkColor,
  backgroundColor,
  className,
}: SphereSketchProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const cv = canvasRef.current;
    if (!cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const ac = new AbortController();
    const s = { w: 0, h: 0, dpr: 1 };
    let ink = "";
    let accent = "";
    let face = "";
    const readTheme = () => {
      ink = inkColor ?? token("--foreground");
      accent = token("--primary");
      face = getComputedStyle(cv).fontFamily || "serif";
    };
    readTheme();

    const resize = () => {
      const r = { width: cv.clientWidth, height: cv.clientHeight };
      if (!r.width || !r.height) return false;
      const dpr = Math.min(2, window.devicePixelRatio || 1);
      const w = Math.round(r.width * dpr);
      const h = Math.round(r.height * dpr);
      if (w === cv.width && h === cv.height && s.w === r.width) return false;
      cv.width = w;
      cv.height = h;
      s.w = r.width;
      s.h = r.height;
      s.dpr = dpr;
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      return true;
    };

    const pts: { x: number; y: number; z: number; c: string; back: number }[] = [];
    const r0 = rng(77712345);
    for (let i = 0; i < N; i++) {
      // uniform random on the sphere — a lattice would show its spiral arms
      const y = 1 - 2 * r0();
      const rad = Math.sqrt(Math.max(0, 1 - y * y));
      const th = r0() * Math.PI * 2;
      pts.push({
        x: Math.cos(th) * rad,
        y,
        z: Math.sin(th) * rad,
        c: CHARS.charAt(Math.floor(r0() * CHARS.length)),
        back: 0, // timestamp at which it regrows
      });
    }

    let spin = 0;
    let vel = 0.17;
    let hover = false;
    const parts: Part[] = [];
    const proj = new Float32Array(N * 4); // x, y, scale, depth

    const draw = (now: number, dt: number) => {
      ctx.clearRect(0, 0, s.w, s.h);

      const target = hover ? 0.62 : 0.17;
      vel += (target - vel) * Math.min(1, dt / 300);
      spin += (vel * dt) / 1000;

      const size = Math.min(s.w, s.h);
      const cx = s.w / 2;
      const cy = s.h / 2 + size * CYOFF;
      const R = size * RR;
      const fs = size * FS;
      const cs = Math.cos(spin);
      const sn = Math.sin(spin);

      const order: number[] = [];
      for (let i = 0; i < N; i++) {
        const p = pts[i];
        const x1 = p.x * cs - p.z * sn;
        const z1 = p.x * sn + p.z * cs;
        const y2 = p.y * ct - z1 * st;
        const z2 = p.y * st + z1 * ct;
        const d = (z2 + 1) * 0.5; // 0 = far side, 1 = nearest point
        const sc = 0.1 + 0.9 * Math.pow(d, 1.8);
        proj[i * 4] = cx + x1 * R;
        proj[i * 4 + 1] = cy + y2 * R;
        proj[i * 4 + 2] = sc;
        proj[i * 4 + 3] = d;
        if (p.back > now) continue;
        order.push(i);
      }
      order.sort((a, b) => proj[a * 4 + 3] - proj[b * 4 + 3]);

      ctx.textAlign = "center";
      ctx.textBaseline = "middle";

      let lastFont = "";
      for (let k = 0; k < order.length; k++) {
        const j = order[k];
        const z2b = proj[j * 4 + 3];
        const scb = proj[j * 4 + 2];
        let a = 0.55 + 0.45 * Math.pow(z2b, 1.1);
        const grow = pts[j].back ? Math.min(1, (now - pts[j].back) / 420) : 1;
        if (grow < 1) a *= grow;
        // depth-sorted, so quantising the size keeps ctx.font churn low
        const f = "italic " + Math.round(fs * scb * 4.4) / 4 + "px " + face;
        if (f !== lastFont) {
          ctx.font = f;
          lastFont = f;
        }
        ctx.globalAlpha = a;
        ctx.fillStyle = z2b > 0.9 ? accent : ink;
        ctx.fillText(pts[j].c, proj[j * 4], proj[j * 4 + 1]);
      }

      // knocked-loose letters
      const g = size * 0.8;
      for (let m = parts.length - 1; m >= 0; m--) {
        const q = parts[m];
        const age = now - q.t;
        if (age > q.life || q.y > s.h + 40) {
          parts.splice(m, 1);
          continue;
        }
        q.vy += (g * dt) / 1000;
        q.x += (q.vx * dt) / 1000;
        q.y += (q.vy * dt) / 1000;
        q.rot += (q.vr * dt) / 1000;
        const af = Math.max(0, 1 - age / q.life);
        ctx.save();
        ctx.translate(q.x, q.y);
        ctx.rotate(q.rot);
        ctx.font = "italic " + q.size.toFixed(2) + "px " + face;
        ctx.globalAlpha = 0.95 * Math.pow(af, 0.5);
        ctx.fillStyle = accent;
        ctx.fillText(q.c, 0, 0);
        ctx.restore();
      }
      ctx.globalAlpha = 1;
    };

    let raf = 0;
    let onScreen = true;
    let prev = performance.now();
    const frame = (now: number) => {
      const dt = Math.min(64, now - prev);
      prev = now;
      draw(now, dt);
      raf = requestAnimationFrame(frame);
    };
    const update = () => {
      const run = onScreen && !document.hidden && !prefersReducedMotion;
      if (run && !raf) {
        prev = performance.now();
        raf = requestAnimationFrame(frame);
      } else if (!run && raf) {
        cancelAnimationFrame(raf);
        raf = 0;
      }
    };

    const opts = { signal: ac.signal };
    cv.addEventListener("pointerenter", () => (hover = true), opts);
    cv.addEventListener("pointerleave", () => (hover = false), opts);
    cv.addEventListener(
      "pointerdown",
      (e) => {
        const r = cv.getBoundingClientRect();
        const kk = cv.clientWidth / (r.width || 1);
        const p = { x: (e.clientX - r.left) * kk, y: (e.clientY - r.top) * kk };
        const size = Math.min(s.w, s.h);
        const fs = size * FS;
        const now = performance.now();
        const hitR = size * 0.055;
        const hit = hitR * hitR;
        for (let i = 0; i < N; i++) {
          if (pts[i].back > now) continue;
          if (proj[i * 4 + 3] < 0.72) continue; // only the letters actually facing you
          const dx = proj[i * 4] - p.x;
          const dy = proj[i * 4 + 1] - p.y;
          if (dx * dx + dy * dy > hit) continue;
          const d = Math.sqrt(dx * dx + dy * dy) || 1;
          pts[i].back = now + 1500 + Math.random() * 260;
          parts.push({
            x: proj[i * 4],
            y: proj[i * 4 + 1],
            vx:
              (dx / d) * size * (0.1 + Math.random() * 0.16) + (Math.random() - 0.5) * size * 0.05,
            vy: (dy / d) * size * 0.08 - size * (0.04 + Math.random() * 0.1),
            rot: 0,
            vr: (Math.random() - 0.5) * 5.5,
            size: fs * (0.85 + 0.15 * proj[i * 4 + 2]), // reads as a whole letter once it is off the ball
            c: pts[i].c,
            t: now,
            life: 2100,
          });
        }
        if (parts.length > 420) parts.splice(0, parts.length - 420);
      },
      opts,
    );

    const onResize = () => {
      if (resize()) parts.length = 0;
      draw(performance.now(), 16);
    };
    const ro = new ResizeObserver(onResize);
    ro.observe(cv);
    const io = new IntersectionObserver(([entry]) => {
      onScreen = entry?.isIntersecting ?? true;
      update();
    });
    io.observe(cv);
    document.addEventListener("visibilitychange", update, {
      signal: ac.signal,
    });
    const themeObserver = new MutationObserver(() => {
      readTheme();
      draw(performance.now(), 16);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette"],
    });
    onResize();
    update();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      themeObserver.disconnect();
      ac.abort();
    };
  }, [inkColor, prefersReducedMotion]);

  const boundedHue = clamp(hue, -180, 180);
  const boundedSaturation = clamp(saturation, 0, 2);
  const boundedBrightness = clamp(brightness, 0.4, 1.8);
  const boundedScale = clamp(scale, 0.65, 1.5);
  const filter =
    boundedHue === 0 && boundedSaturation === 1 && boundedBrightness === 1
      ? undefined
      : `hue-rotate(${boundedHue}deg) saturate(${boundedSaturation}) brightness(${boundedBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden bg-background", className)}
      style={{
        background: backgroundColor,
        opacity: clamp(opacity, 0.1, 1),
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        aria-label="Letter sphere: hover to spin faster, click to knock letters loose"
        className="absolute inset-0 block h-full w-full cursor-crosshair touch-none font-serif"
        style={{
          transform: boundedScale === 1 ? undefined : `scale(${boundedScale})`,
        }}
      />
    </div>
  );
}
```

---

# Emblem Globe

> A tiny dot-matrix globe that draws 23 marks in the theme ink, for a status pill or an avatar slot.

Install: `npx @modus-ui/cli add emblem-globe`

A small canvas globe that renders a mark as z-sorted, softly lit dots and keeps it gently moving, ideal next to a "Composing…" status label. The dots are recoloured in `--primary` (or any `color`) on a transparent surface, so it follows light, dark and every palette. Pick one of 23 marks and two sizes. It pauses when off screen or the tab is hidden and draws a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add emblem-globe
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/emblem-globe.tsx`.
3. Paste the code.

## Usage

```tsx
import { EmblemGlobe } from "@/components/ui/emblem-globe";

export default function Example() {
  return (
    <div className="h-14 w-14">
      <EmblemGlobe brand="ux" />
    </div>
  );
}
```

Available brands: `claude`, `openai`, `codex`, `cursor`, `gemini`, `figma`, `framer`, `react`, `swift`, `designcode`, `aura`, `dreamcut`, `ui`, `ux`, `css`, `ios`, `neuform`, `github`, `x`, `instagram`, `threads`, `linkedin`, `email`.

## Props

| Prop              | Type                                                                                                                                                                                                                                                                                                              | Default                 | Description                                          |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | :--------------------------------------------------- |
| `brand`           | `"claude"` \| `"openai"` \| `"codex"` \| `"cursor"` \| `"gemini"` \| `"figma"` \| `"framer"` \| `"react"` \| `"swift"` \| `"designcode"` \| `"aura"` \| `"dreamcut"` \| `"ui"` \| `"ux"` \| `"css"` \| `"ios"` \| `"neuform"` \| `"github"` \| `"x"` \| `"instagram"` \| `"threads"` \| `"linkedin"` \| `"email"` | `"ui"`                  | Which mark to animate.                               |
| `size`            | `"small" \| "medium"`                                                                                                                                                                                                                                                                                             | `"medium"`              | `small` renders a 20px globe, `medium` a 56px globe. |
| `color`           | `string`                                                                                                                                                                                                                                                                                                          | `"hsl(var(--primary))"` | Dot colour; theme tokens are resolved.               |
| `speed`           | `number`                                                                                                                                                                                                                                                                                                          | `1`                     | Animation speed multiplier, clamped to 0.1–3.        |
| `paused`          | `boolean`                                                                                                                                                                                                                                                                                                         | `false`                 | Freezes the animation on its current frame.          |
| `backgroundColor` | `string`                                                                                                                                                                                                                                                                                                          | `"transparent"`         | Surface colour behind the globe.                     |

## Source

`components/ui/emblem-globe.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Brand Orbs (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

/* ------------------------------------------------------------------
   Orb engine — ported literally from ThreeUI's brand-orbs-v2.html.
   Every brand is drawn as z-sorted dots on a 2D canvas; logo marks are
   inline SVG path data sampled into dot lattices.
------------------------------------------------------------------- */
const TAU = Math.PI * 2;
const clamp01 = (v: any) => (v < 0 ? 0 : v > 1 ? 1 : v);
const smooth = (v: any) => {
  v = clamp01(v);
  return v * v * (3 - 2 * v);
};
const lerp = (a?: any, b?: any, m?: any) => a + (b - a) * m;

/* deterministic hash noise (ported from the reference orb engine) */
const hash = (x?: any, y?: any) => {
  const n = Math.sin(x * 12.9898 + y * 78.233) * 43758.5453;
  return n - Math.floor(n);
};
const vnoise = (x?: any, y?: any) => {
  const xi = Math.floor(x),
    yi = Math.floor(y);
  let fx = x - xi,
    fy = y - yi;
  fx = fx * fx * (3 - 2 * fx);
  fy = fy * fy * (3 - 2 * fy);
  const a = hash(xi, yi),
    b = hash(xi + 1, yi),
    c = hash(xi, yi + 1),
    d = hash(xi + 1, yi + 1);
  return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
};

/* fibonacci sphere point i of n → [x,y,z] on unit sphere */
const fib = (i?: any, n?: any) => {
  const ga = Math.PI * (3 - Math.sqrt(5));
  const y = 1 - (2 * (i + 0.5)) / n;
  const r = Math.sqrt(Math.max(0, 1 - y * y));
  const th = i * ga;
  return [r * Math.cos(th), y, r * Math.sin(th)];
};

/* yaw+tilt rotation and orthographic projection: returns (x,y,z)→[px,py,zdepth] */
const proj = (yaw?: any, tilt?: any, cx?: any, cy?: any, s?: any) => {
  const st = Math.sin(tilt),
    ct = Math.cos(tilt);
  const sy = Math.sin(yaw),
    cyw = Math.cos(yaw);
  return (x?: any, y?: any, z?: any) => {
    const px = x * cyw + z * sy,
      pz = -x * sy + z * cyw;
    const py = y * ct - pz * st,
      z2 = y * st + pz * ct;
    return [cx + px * s, cy - py * s, z2];
  };
};

/* dot radius scale for a given canvas size (reference: (size/300)^.6) */
const rscale = (S: any) => Math.pow(S / 300, 0.6);

/* painter: z-sorted brand-tinted dots.
   dot: {x,y,z,r,v (brightness 0..1),a,c (optional [r,g,b] accent)} */
function paint(ctx?: any, dots?: any, accent?: any, sat?: any, rMin?: any) {
  dots.sort((a?: any, b?: any) => a.z - b.z);
  for (const d of dots) {
    const al = d.a ?? 1;
    if (al < 0.02) continue;
    const v = clamp01(d.v);
    const g = v * 255;
    const acc = d.c || accent;
    const st = d.c ? 0.95 : sat;
    let r = g,
      gg = g,
      b = g;
    if (acc && st) {
      const lift = Math.min(1, v * 1.12);
      r = g * (1 - st) + acc[0] * lift * st;
      gg = g * (1 - st) + acc[1] * lift * st;
      b = g * (1 - st) + acc[2] * lift * st;
    }
    if (v > 0.85) {
      const w = ((v - 0.85) / 0.15) * 0.45;
      r += (255 - r) * w;
      gg += (255 - gg) * w;
      b += (255 - b) * w;
    }
    ctx.fillStyle = `rgba(${r | 0},${gg | 0},${b | 0},${al})`;
    ctx.beginPath();
    ctx.arc(d.x, d.y, Math.max(rMin, d.r), 0, TAU);
    ctx.fill();
  }
}

/* ============ CLAUDE — spark burst ============ */
function drawClaude(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.84;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const yaw = 0.32 * Math.sin(t * 0.5),
    tilt = 0.3 + 0.17 * Math.sin(t * 0.33);
  const p = proj(yaw, tilt, cx, cy, R);
  const spin = t * 0.17;
  const rays = o.mini ? 8 : 11;
  const perRay = o.mini ? 4 : 6;
  const dots: any = [];
  /* ghost silhouette ring */
  const gh = o.mini ? 10 : 22;
  for (let i = 0; i < gh; i++) {
    const a = (i / gh) * TAU + t * 0.05;
    const [x, y, z] = p(Math.cos(a), Math.sin(a), 0);
    dots.push({ x, y, z, r: 0.8 * rs, v: 0.22, a: 0.1 + 0.1 * ((z + 1) / 2) });
  }
  for (let k = 0; k < rays; k++) {
    const baseA = (k / rays) * TAU + (hash(k, 3.1) - 0.5) * 0.3 + spin;
    const baseL = 0.62 + 0.38 * hash(k, 7.7);
    const pulse = 0.5 + 0.5 * Math.sin(t * 1.7 - k * 1.13);
    const L = baseL * (0.8 + 0.28 * pulse * pulse);
    for (let j = 0; j < perRay; j++) {
      const f = (j + 0.8) / perRay;
      const rr = 0.14 + f * (L - 0.14);
      const [x, y, z] = p(Math.cos(baseA) * rr, Math.sin(baseA) * rr, 0);
      const dep = (z + 1) / 2;
      dots.push({
        x,
        y,
        z,
        r: (0.75 + 1.35 * (1 - f * 0.45) + 0.5 * dep) * rs,
        v: 0.38 + 0.38 * f + 0.22 * pulse * f,
        a: 0.55 + 0.45 * f,
      });
    }
  }
  /* core */
  const [x0, y0, z0] = p(0, 0, 0);
  dots.push({ x: x0, y: y0, z: z0 + 0.01, r: 1.5 * rs, v: 0.92 });
  paint(ctx, dots, o.accent, 0.85, 0.3);
}

/* ============ SPHERE (study) — blossom knot ============ */
function drawSphere(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.8;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(t * 0.26, 0.35 + 0.08 * Math.sin(t * 0.4), cx, cy, R);
  const rings = 6,
    phi = 1.13; /* ring plane tilt from vertical axis */
  const ghostN = o.mini ? 10 : 32;
  const runners = o.mini ? 1 : 2;
  const dots: any = [];
  for (let i = 0; i < rings; i++) {
    const a = (i / rings) * TAU;
    /* ring normal, arranged with 6-fold symmetry */
    const nx = Math.sin(phi) * Math.cos(a),
      ny = Math.cos(phi),
      nz = Math.sin(phi) * Math.sin(a);
    /* orthonormal basis in ring plane */
    let ux = -nz,
      uy = 0,
      uz = nx;
    const ul = Math.hypot(ux, uz) || 1;
    ux /= ul;
    uz /= ul;
    const vx = ny * uz - nz * uy,
      vy = nz * ux - nx * uz,
      vz = nx * uy - ny * ux;
    const rad = 0.74;
    for (let j = 0; j < ghostN; j++) {
      const th = (j / ghostN) * TAU;
      const gx = (ux * Math.cos(th) + vx * Math.sin(th)) * rad;
      const gy = (uy * Math.cos(th) + vy * Math.sin(th)) * rad;
      const gz = (uz * Math.cos(th) + vz * Math.sin(th)) * rad;
      const [x, y, z] = p(gx, gy, gz);
      const dep = (z + 1) / 2;
      dots.push({ x, y, z, r: (0.65 + 1 * dep) * rs, v: 0.4 + 0.45 * dep, a: 0.4 + 0.6 * dep });
    }
    for (let m = 0; m < runners; m++) {
      const th = t * (i % 2 ? -0.9 : 0.9) + i * 1.05 + (m / runners) * TAU;
      const gx = (ux * Math.cos(th) + vx * Math.sin(th)) * rad;
      const gy = (uy * Math.cos(th) + vy * Math.sin(th)) * rad;
      const gz = (uz * Math.cos(th) + vz * Math.sin(th)) * rad;
      const [x, y, z] = p(gx, gy, gz);
      const dep = (z + 1) / 2;
      dots.push({ x, y, z, r: (1.2 + 1.5 * dep) * rs, v: 0.78 + 0.22 * dep });
    }
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ CURSOR — the pointer ============ */
const mkArrow = (pts?: any, ox?: any, oy?: any, sc?: any) =>
  pts.map(([x, y]: any) => [(x - ox) * sc, (y - oy) * sc]);
/* the arrow inside the Cursor logo, traced from its own path (viewBox 24), tip first.
   two long edges (18.55 / 18.90) and two short ones (10.80 / 10.93) — the logo's own proportions */
const ARROW_CLEAN = mkArrow(
  [
    [21.207, 6.338],
    [12.11, 22.9],
    [11.95, 12.1],
    [2.657, 6.338],
  ],
  12,
  12,
  0.08426,
);
/* the cube silhouette that frames it — same transform, so the two nest exactly as they do in the logo */
const CURSOR_HEX = mkArrow(
  [
    [12, 0.131],
    [22.528, 6.19],
    [22.528, 17.81],
    [12, 23.866],
    [1.471, 17.81],
    [1.471, 6.19],
  ],
  12,
  12,
  0.08426,
);
/* study: the classic pointer, tail leg and all */
const ARROW_LEG = mkArrow(
  [
    [0, 0],
    [0, 17],
    [4, 13],
    [7, 19.5],
    [10, 18],
    [7, 12],
    [12, 12],
  ],
  5.7,
  11.6,
  0.086,
);
function perimeter(pts?: any) {
  const n = pts.length,
    seg: any = [];
  let L = 0;
  for (let i = 0; i < n; i++) {
    const a = pts[i],
      b = pts[(i + 1) % n];
    const l = Math.hypot(b[0] - a[0], b[1] - a[1]);
    seg.push(l);
    L += l;
  }
  return (u: any) => {
    let d = (((u % 1) + 1) % 1) * L,
      i = 0;
    while (d > seg[i] && i < n - 1) {
      d -= seg[i];
      i++;
    }
    const a = pts[i],
      b = pts[(i + 1) % n],
      f = seg[i] ? d / seg[i] : 0;
    return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
  };
}
const cleanPath = perimeter(ARROW_CLEAN),
  legPath = perimeter(ARROW_LEG),
  hexPath = perimeter(CURSOR_HEX);
function inPoly(pts?: any, x?: any, y?: any) {
  let hit = false;
  for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
    const [xi, yi] = pts[i],
      [xj, yj] = pts[j];
    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) hit = !hit;
  }
  return hit;
}
function drawArrowOrb(
  ctx?: any,
  S?: any,
  t?: any,
  o?: any,
  rot?: any,
  pts?: any,
  path?: any,
  opt?: any,
) {
  const { span, fill, wob, frame, framePath } = opt;
  const cs = Math.cos(rot),
    sn = Math.sin(rot);
  const rp = (x?: any, y?: any) => [x * cs - y * sn, x * sn + y * cs];
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.84;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const w = wob ?? 1; /* keep the official mark close to the flat logo silhouette */
  const p = proj(0.26 * w * Math.sin(t * 0.5), (0.3 + 0.12 * Math.sin(t * 0.35)) * w, cx, cy, R);
  /* click cycle */
  const beat = 2.4,
    c = (((t / beat) % 1) + 1) % 1;
  const press = c < 0.14 ? Math.sin((c / 0.14) * Math.PI) : 0;
  const scale = 1 - 0.09 * press;
  /* one dot every fixed step of edge length, so every line is an even queue */
  let per = 0;
  for (let i = 0; i < pts.length; i++) {
    const a = pts[i],
      b = pts[(i + 1) % pts.length];
    per += Math.hypot(b[0] - a[0], b[1] - a[1]);
  }
  const N = Math.max(8, Math.round(per / (o.mini ? 0.4 : 0.152)));
  const dots: any = [];
  const tip = rp(pts[0][0], pts[0][1]);
  for (let i = 0; i < N; i++) {
    const [ax0, ay0] = path((i + 0.5) / N);
    const [ax, ay] = rp(ax0, ay0);
    const [x, y, z] = p(ax * scale, -ay * scale, 0);
    const dep = (z + 1) / 2;
    const tipNear = Math.max(0, 1 - Math.hypot(ax - tip[0], ay - tip[1]) / span);
    dots.push({
      x,
      y,
      z,
      r: (0.85 + 1.05 * dep + 0.7 * tipNear) * rs,
      v: 0.58 + 0.26 * tipNear + 0.14 * dep + 0.12 * press,
    });
  }
  /* interior lattice so the mark reads as a solid pointer, not an outline */
  if (fill && !o.mini) {
    let x0 = 1e9,
      x1 = -1e9,
      y0 = 1e9,
      y1 = -1e9;
    for (const [px, py] of pts) {
      x0 = Math.min(x0, px);
      x1 = Math.max(x1, px);
      y0 = Math.min(y0, py);
      y1 = Math.max(y1, py);
    }
    const gap = 0.17;
    for (let gy = y0 + gap * 0.5; gy < y1; gy += gap) {
      for (let gx = x0 + gap * 0.5; gx < x1; gx += gap) {
        if (!inPoly(pts, gx, gy)) continue;
        const [ax, ay] = rp(gx, gy);
        const [x, y, z] = p(ax * scale, -ay * scale, 0.03);
        const dep = (z + 1) / 2;
        const tipNear = Math.max(0, 1 - Math.hypot(ax - tip[0], ay - tip[1]) / span);
        dots.push({
          x,
          y,
          z,
          r: (0.72 + 0.8 * dep) * rs,
          v: 0.43 + 0.16 * dep + 0.18 * tipNear,
          a: 0.85,
        });
      }
    }
  }
  /* the cube outline, its own even queue of dots, sat behind the arrow */
  if (frame) {
    let fper = 0;
    for (let i = 0; i < frame.length; i++) {
      const a = frame[i],
        b = frame[(i + 1) % frame.length];
      fper += Math.hypot(b[0] - a[0], b[1] - a[1]);
    }
    const FN = Math.max(6, Math.round(fper / (o.mini ? 0.44 : 0.152)));
    for (let i = 0; i < FN; i++) {
      const [fx0, fy0] = framePath((i + 0.5) / FN);
      const [fx, fy] = rp(fx0, fy0);
      const [x, y, z] = p(fx * scale, -fy * scale, -0.05);
      const dep = (z + 1) / 2;
      dots.push({ x, y, z, r: (0.78 + 0.68 * dep) * rs, v: 0.46 + 0.16 * dep, a: 0.8 });
    }
  }
  /* click ripple expanding from the tip */
  const rip = c < 0.5 ? c / 0.5 : 0;
  if (rip > 0 && !o.mini) {
    const rr = 0.22 + 0.72 * rip,
      Nr = 14;
    for (let i = 0; i < Nr; i++) {
      const a = (i / Nr) * TAU;
      const [x, y, z] = p(tip[0] + Math.cos(a) * rr, -(tip[1] + Math.sin(a) * rr), -0.05);
      dots.push({ x, y, z, r: 0.7 * rs, v: 0.62, a: (1 - rip) * 0.5 });
    }
  }
  paint(ctx, dots, null, 0, 0.3);
}
/* official: pointing right and a little up, like the logo */
function drawCursor(ctx?: any, S?: any, t?: any, o?: any) {
  drawArrowOrb(ctx, S, t, o, 0, ARROW_CLEAN, cleanPath, {
    span: 1.5,
    fill: true,
    wob: 0.5,
    frame: CURSOR_HEX,
    framePath: hexPath,
  });
}
/* study: the original up-left pointer */
function drawPointer(ctx?: any, S?: any, t?: any, o?: any) {
  drawArrowOrb(ctx, S, t, o, 0, ARROW_LEG, legPath, { span: 1.05 });
}

/* ============ CUBE (study) — face sweep ============ */
const CUBE_V: any = [];
for (let i = 0; i < 8; i++) CUBE_V.push([i & 1 ? 1 : -1, i & 2 ? 1 : -1, i & 4 ? 1 : -1]);
const CUBE_E = [
  [0, 1],
  [2, 3],
  [4, 5],
  [6, 7],
  [0, 2],
  [1, 3],
  [4, 6],
  [5, 7],
  [0, 4],
  [1, 5],
  [2, 6],
  [3, 7],
];
const CUBE_F = [
  [0, 1, 3, 2],
  [4, 5, 7, 6],
  [0, 1, 5, 4],
  [2, 3, 7, 6],
  [0, 2, 6, 4],
  [1, 3, 7, 5],
];
const CUBE_PATH = [0, 1, 3, 2, 6, 7, 5, 4]; /* gray-code loop over vertices */
function drawCube(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.8;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.63 + t * 0.38, 0.6155 + 0.06 * Math.sin(t * 0.5), cx, cy, R);
  const h = 0.62;
  const perEdge = o.mini ? 4 : 8;
  /* face sweep: one face pulses at a time */
  const cyc = t * 0.55;
  const face = Math.floor(cyc % 6);
  const pulse = Math.sin(clamp01(cyc % 1) * Math.PI);
  const inFace = CUBE_F[face];
  const dots: any = [];
  for (const [a, b] of CUBE_E) {
    const hot = inFace.includes(a) && inFace.includes(b) ? pulse : 0;
    const A = CUBE_V[a],
      B = CUBE_V[b];
    for (let j = 0; j < perEdge; j++) {
      const f = (j + 0.5) / perEdge;
      const [x, y, z] = p(
        lerp(A[0], B[0], f) * h,
        lerp(A[1], B[1], f) * h,
        lerp(A[2], B[2], f) * h,
      );
      const dep = (z + 1) / 2;
      dots.push({
        x,
        y,
        z,
        r: (0.8 + 1.5 * dep + 0.5 * hot) * rs,
        v: 0.42 + 0.44 * dep + 0.28 * hot,
        a: 0.55 + 0.45 * dep,
      });
    }
  }
  /* corner anchors */
  for (const V of CUBE_V) {
    const [x, y, z] = p(V[0] * h, V[1] * h, V[2] * h);
    const dep = (z + 1) / 2;
    dots.push({ x, y, z, r: (1.2 + 1.5 * dep) * rs, v: 0.52 + 0.4 * dep });
  }
  /* the runner "cursor" walking the edges */
  const walk = t * 0.8;
  const seg = Math.floor(walk % 8),
    fseg = walk % 1;
  const A = CUBE_V[CUBE_PATH[seg]],
    B = CUBE_V[CUBE_PATH[(seg + 1) % 8]];
  for (let k = 0; k < 4; k++) {
    const f = clamp01(fseg - k * 0.09);
    const [x, y, z] = p(lerp(A[0], B[0], f) * h, lerp(A[1], B[1], f) * h, lerp(A[2], B[2], f) * h);
    dots.push({ x, y, z: z + 0.02, r: (1.7 - k * 0.3) * rs, v: 0.96 - k * 0.17, a: 1 - k * 0.2 });
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ GEMINI — astroid twinkle ============ */
function drawGemini(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.84;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const yaw = 0.3 * Math.sin(t * 0.45),
    tilt = 0.32 + 0.14 * Math.sin(t * 0.28);
  const p = proj(yaw, tilt, cx, cy, R);
  const rotW = 0.14 * Math.sin(t * 0.9); /* twinkle wobble */
  const scale = 0.88 + 0.12 * Math.sin(t * 1.8); /* twinkle breath */
  const N = o.mini ? 22 : 58;
  const dots: any = [];
  const cBlue = [64, 148, 255],
    cPurple = [176, 118, 240],
    cPink = [225, 118, 178];
  const grad = (py: any) => {
    /* vertical gradient: top blue → mid purple → bottom pink (screen up = +py) */
    const gpos = clamp01((1 - py) / 2);
    return gpos < 0.5
      ? [
          lerp(cBlue[0], cPurple[0], gpos * 2),
          lerp(cBlue[1], cPurple[1], gpos * 2),
          lerp(cBlue[2], cPurple[2], gpos * 2),
        ]
      : [
          lerp(cPurple[0], cPink[0], gpos * 2 - 1),
          lerp(cPurple[1], cPink[1], gpos * 2 - 1),
          lerp(cPurple[2], cPink[2], gpos * 2 - 1),
        ];
  };
  for (let i = 0; i < N; i++) {
    const th = (i / N) * TAU + rotW;
    const c3 = Math.cos(th),
      s3 = Math.sin(th);
    const px = c3 * c3 * c3 * scale,
      py = s3 * s3 * s3 * scale;
    const [x, y, z] = p(px, py, 0);
    const dep = (z + 1) / 2;
    const tip = Math.pow(Math.abs(px) + Math.abs(py), 1.6); /* brighter near the 4 points */
    dots.push({
      x,
      y,
      z,
      r: (0.7 + 1.1 * dep + 0.9 * tip) * rs,
      v: 0.48 + 0.32 * tip + 0.2 * dep,
      c: grad(py),
    });
  }
  /* inner echo star for body */
  const Ni = o.mini ? 0 : N >> 1;
  for (let i = 0; i < Ni; i++) {
    const th = (i / Ni) * TAU - rotW * 0.6;
    const c3 = Math.cos(th),
      s3 = Math.sin(th);
    const px = c3 * c3 * c3 * scale * 0.48,
      py = s3 * s3 * s3 * scale * 0.48;
    const [x, y, z] = p(px, py, 0.04);
    dots.push({ x, y, z, r: 0.85 * rs, v: 0.52, a: 0.8, c: grad(py * 2) });
  }
  /* orbiting satellite sparkles */
  if (!o.mini)
    for (let k = 0; k < 3; k++) {
      const a = t * (k % 2 ? -0.5 : 0.65) + k * 2.1;
      const rr = 0.95 + 0.1 * Math.sin(t * 1.3 + k * 2);
      const [x, y, z] = p(Math.cos(a) * rr, Math.sin(a) * rr, 0.25 * Math.sin(t * 0.7 + k * 3));
      const tw = 0.5 + 0.5 * Math.sin(t * 3 + k * 2.4);
      dots.push({
        x,
        y,
        z,
        r: (0.6 + 0.9 * tw) * rs,
        v: 0.85,
        a: 0.25 + 0.6 * tw,
        c: k === 0 ? cBlue : k === 1 ? cPurple : cPink,
      });
    }
  /* core glimmer */
  const [x0, y0, z0] = p(0, 0, 0);
  dots.push({
    x: x0,
    y: y0,
    z: z0 + 0.01,
    r: (1.1 + 0.5 * Math.sin(t * 2.2)) * rs,
    v: 0.9,
    c: cPurple,
  });
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ FIGMA — swatch morph ============ */
const FIGMA_COLS = [
  [242, 78, 30] /* L-top  */,
  [255, 114, 98] /* R-top  */,
  [162, 89, 255] /* L-mid  */,
  [26, 188, 254] /* R-mid  */,
  [10, 207, 131] /* L-bot  */,
];
const FIGMA_POS = [
  [-0.21, -0.42],
  [0.21, -0.42],
  [-0.21, 0],
  [0.21, 0],
  [-0.21, 0.42],
];
function drawFigma(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.8;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const per = o.mini ? 6 : 13; /* dots per swatch */
  const N = per * 5;
  /* cycle: sphere → logo → sphere */
  const T = 7,
    u = (((t * 0.9) % T) + T) % T;
  let m: any; /* 0 = sphere, 1 = logo */
  if (u < 2.8) m = 0;
  else if (u < 3.7) m = smooth((u - 2.8) / 0.9);
  else if (u < 5.6) m = 1;
  else if (u < 6.5) m = 1 - smooth((u - 5.6) / 0.9);
  else m = 0;
  const p = proj(t * 0.5, 0.32 + 0.1 * Math.sin(t * 0.35), cx, cy, R);
  const dots: any = [];
  for (let i = 0; i < N; i++) {
    const grp = i % 5;
    const idx = (i / 5) | 0;
    /* sphere home */
    const f = fib(i, N);
    const [sx, sy, sz] = p(f[0], f[1], f[2]);
    /* logo home: tight sunflower disc per swatch, face-on */
    const ring = 0.155 * Math.sqrt((idx + 0.5) / per);
    const ang = idx * 2.399963 + grp * 1.2;
    const bob = 0.008 * Math.sin(t * 1.6 + grp * 1.3);
    const lx = cx + (FIGMA_POS[grp][0] + Math.cos(ang) * ring) * R * 1.05;
    const ly = cy + (FIGMA_POS[grp][1] + bob + Math.sin(ang) * ring) * R * 1.05;
    const x = lerp(sx, lx, m),
      y = lerp(sy, ly, m),
      z = lerp(sz, grp * 0.05 - 0.1, m);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.8 + 1.4 * lerp(dep, 0.85, m)) * rs,
      v: lerp(0.45 + 0.48 * dep, 0.85, m),
      c: FIGMA_COLS[grp],
    });
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ REACT — the atom ============ */
function drawReact(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.92;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.1 * Math.sin(t * 0.4), 0.12 * Math.sin(t * 0.33), cx, cy, R);
  const spin = t * 0.26,
    rx = 0.94,
    ry = 0.345;
  const per = o.mini ? 20 : 56;
  const dots: any = [];
  for (let k = 0; k < 3; k++) {
    const a0 = spin + (k * Math.PI) / 3;
    const ca = Math.cos(a0),
      sa = Math.sin(a0);
    const ring = (th: any) => {
      const ex = Math.cos(th) * rx,
        ey = Math.sin(th) * ry;
      return [ex * ca - ey * sa, ex * sa + ey * ca];
    };
    for (let i = 0; i < per; i++) {
      const th = (i / per) * TAU;
      const [gx, gy] = ring(th);
      const [x, y, z] = p(gx, gy, 0);
      /* a highlight travels each orbit so the flat mark still breathes */
      const ph = (((th / TAU - t * 0.19 - k * 0.33) % 1) + 1) % 1;
      const crest = Math.exp(-Math.pow(ph - 0.5, 2) / 0.022);
      dots.push({
        x,
        y,
        z: z + crest * 0.01,
        r: (0.95 + 0.6 * crest) * rs,
        v: 0.66 + 0.3 * crest,
        a: 0.85 + 0.15 * crest,
      });
    }
    const eth = t * (k % 2 ? -1.15 : 1.3) + k * 2.1;
    const [ex2, ey2] = ring(eth);
    const [x2, y2, z2] = p(ex2, ey2, 0.04);
    dots.push({ x: x2, y: y2, z: z2 + 0.02, r: 1.9 * rs, v: 0.95 });
  }
  /* nucleus */
  const nN = o.mini ? 3 : 7;
  for (let i = 0; i < nN; i++) {
    const a = (i / nN) * TAU,
      rr = i ? 0.085 : 0;
    const [x, y, z] = p(Math.cos(a) * rr, Math.sin(a) * rr, 0.05);
    dots.push({ x, y, z: z + 0.03, r: 1.5 * rs, v: 0.9 });
  }
  paint(ctx, dots, o.accent, 0.88, 0.3);
}

/* ============ SWIFT — the bird ============ */
const OPENAI_PATH =
  "M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z";
const SWIFT_PATH =
  "M13.543 3.41c4.114 2.47 6.545 7.162 5.549 11.131-.024.093-.05.181-.076.272l.002.001c2.062 2.538 1.5 5.258 1.236 4.745-1.072-2.086-3.066-1.568-4.088-1.043a6.803 6.803 0 0 1-.281.158l-.02.012-.002.002c-2.115 1.123-4.957 1.205-7.812-.022a12.568 12.568 0 0 1-5.64-4.838c.649.48 1.35.902 2.097 1.252 3.019 1.414 6.051 1.311 8.197-.002C9.651 12.73 7.101 9.67 5.146 7.191a10.628 10.628 0 0 1-1.005-1.384c2.34 2.142 6.038 4.83 7.365 5.576C8.69 8.408 6.208 4.743 6.324 4.86c4.436 4.47 8.528 6.996 8.528 6.996.154.085.27.154.36.213.085-.215.16-.437.224-.668.708-2.588-.09-5.548-1.893-7.992z";
const maskCache: any = new Map();
/* sample a real logo path into a dot lattice, normalised on its own bounding box */
function pathDots(key?: any, d?: any, N?: any, vb?: any, strokeW?: any, inv?: any, rc?: any) {
  const ck = key + "-" + N + "-" + (inv || "") + (rc ? "-rc" : "");
  if (maskCache.has(ck)) return maskCache.get(ck);
  const px = 200,
    c = document.createElement("canvas");
  c.width = c.height = px;
  const g = c.getContext("2d") as CanvasRenderingContext2D;
  g.setTransform(px / (vb || 24), 0, 0, px / (vb || 24), 0, 0);
  if (strokeW) {
    g.strokeStyle = "white";
    g.lineWidth = strokeW;
    g.lineJoin = "round";
    g.lineCap = "round";
    g.stroke(new Path2D(d));
  } else {
    g.fillStyle = "white";
    g.fill(new Path2D(d));
  }
  const img = g.getImageData(0, 0, px, px).data;
  let x0 = px,
    x1 = -1,
    y0 = px,
    y1 = -1;
  for (let j = 0; j < px; j++)
    for (let i = 0; i < px; i++)
      if (img[(j * px + i) * 4 + 3] > 128) {
        if (i < x0) x0 = i;
        if (i > x1) x1 = i;
        if (j < y0) y0 = j;
        if (j > y1) y1 = j;
      }
  const mx = (x0 + x1) / 2,
    my = (y0 + y1) / 2,
    m = Math.max(x1 - x0, y1 - y0);
  const pts: any = [];
  for (let j = 0; j < N; j++)
    for (let i = 0; i < N; i++) {
      const sx = mx + ((((i + 0.5) / N) * 2 - 1) * m) / 2,
        sy = my + ((((j + 0.5) / N) * 2 - 1) * m) / 2;
      const ix = Math.round(sx),
        iy = Math.round(sy);
      if (ix < 0 || iy < 0 || ix >= px || iy >= px) continue;
      const on = img[(iy * px + ix) * 4 + 3] > 128;
      const nx = (sx - mx) / (m / 2),
        ny = (sy - my) / (m / 2);
      if (inv) {
        /* the mark is the hole: keep empty pixels that sit inside the outer silhouette */
        if (on) continue;
        if (inv === "circle" && Math.hypot(nx, ny) > 0.96) continue;
        if (
          inv === "box" &&
          Math.pow(Math.abs(nx), 4) + Math.pow(Math.abs(ny), 4) > Math.pow(0.9, 4)
        )
          continue;
      } else if (!on) continue;
      pts.push([nx, ny]);
    }
  /* a mark carried as a hole is normalised against the outer silhouette, so it can sit
     off-centre in the frame; recentre it on its own bounds */
  if (rc && pts.length) {
    let ax0 = 1e9,
      ax1 = -1e9,
      ay0 = 1e9,
      ay1 = -1e9;
    for (const [qx, qy] of pts) {
      if (qx < ax0) ax0 = qx;
      if (qx > ax1) ax1 = qx;
      if (qy < ay0) ay0 = qy;
      if (qy > ay1) ay1 = qy;
    }
    const ox = (ax0 + ax1) / 2,
      oy = (ay0 + ay1) / 2;
    for (const q of pts) {
      q[0] -= ox;
      q[1] -= oy;
    }
  }
  maskCache.set(ck, pts);
  return pts;
}

/* ---------- marks sampled straight from each brand's own logo path ---------- */
const MARK_PATHS: any = {
  github:
    "M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12",
  x: "M14.234 10.162 22.977 0h-2.072l-7.591 8.824L7.251 0H.258l9.168 13.343L.258 24H2.33l8.016-9.318L16.749 24h6.993zm-2.837 3.299-.929-1.329L3.076 1.56h3.182l5.965 8.532.929 1.329 7.754 11.09h-3.182z",
  instagram:
    "M7.0301.084c-1.2768.0602-2.1487.264-2.911.5634-.7888.3075-1.4575.72-2.1228 1.3877-.6652.6677-1.075 1.3368-1.3802 2.127-.2954.7638-.4956 1.6365-.552 2.914-.0564 1.2775-.0689 1.6882-.0626 4.947.0062 3.2586.0206 3.6671.0825 4.9473.061 1.2765.264 2.1482.5635 2.9107.308.7889.72 1.4573 1.388 2.1228.6679.6655 1.3365 1.0743 2.1285 1.38.7632.295 1.6361.4961 2.9134.552 1.2773.056 1.6884.069 4.9462.0627 3.2578-.0062 3.668-.0207 4.9478-.0814 1.28-.0607 2.147-.2652 2.9098-.5633.7889-.3086 1.4578-.72 2.1228-1.3881.665-.6682 1.0745-1.3378 1.3795-2.1284.2957-.7632.4966-1.636.552-2.9124.056-1.2809.0692-1.6898.063-4.948-.0063-3.2583-.021-3.6668-.0817-4.9465-.0607-1.2797-.264-2.1487-.5633-2.9117-.3084-.7889-.72-1.4568-1.3876-2.1228C21.2982 1.33 20.628.9208 19.8378.6165 19.074.321 18.2017.1197 16.9244.0645 15.6471.0093 15.236-.005 11.977.0014 8.718.0076 8.31.0215 7.0301.0839m.1402 21.6932c-1.17-.0509-1.8053-.2453-2.2287-.408-.5606-.216-.96-.4771-1.3819-.895-.422-.4178-.6811-.8186-.9-1.378-.1644-.4234-.3624-1.058-.4171-2.228-.0595-1.2645-.072-1.6442-.079-4.848-.007-3.2037.0053-3.583.0607-4.848.05-1.169.2456-1.805.408-2.2282.216-.5613.4762-.96.895-1.3816.4188-.4217.8184-.6814 1.3783-.9003.423-.1651 1.0575-.3614 2.227-.4171 1.2655-.06 1.6447-.072 4.848-.079 3.2033-.007 3.5835.005 4.8495.0608 1.169.0508 1.8053.2445 2.228.408.5608.216.96.4754 1.3816.895.4217.4194.6816.8176.9005 1.3787.1653.4217.3617 1.056.4169 2.2263.0602 1.2655.0739 1.645.0796 4.848.0058 3.203-.0055 3.5834-.061 4.848-.051 1.17-.245 1.8055-.408 2.2294-.216.5604-.4763.96-.8954 1.3814-.419.4215-.8181.6811-1.3783.9-.4224.1649-1.0577.3617-2.2262.4174-1.2656.0595-1.6448.072-4.8493.079-3.2045.007-3.5825-.006-4.848-.0608M16.953 5.5864A1.44 1.44 0 1 0 18.39 4.144a1.44 1.44 0 0 0-1.437 1.4424M5.8385 12.012c.0067 3.4032 2.7706 6.1557 6.173 6.1493 3.4026-.0065 6.157-2.7701 6.1506-6.1733-.0065-3.4032-2.771-6.1565-6.174-6.1498-3.403.0067-6.156 2.771-6.1496 6.1738M8 12.0077a4 4 0 1 1 4.008 3.9921A3.9996 3.9996 0 0 1 8 12.0077",
  threads:
    "M12.186 24h-.007c-3.581-.024-6.334-1.205-8.184-3.509C2.35 18.44 1.5 15.586 1.472 12.01v-.017c.03-3.579.879-6.43 2.525-8.482C5.845 1.205 8.6.024 12.18 0h.014c2.746.02 5.043.725 6.826 2.098 1.677 1.29 2.858 3.13 3.509 5.467l-2.04.569c-1.104-3.96-3.898-5.984-8.304-6.015-2.91.022-5.11.936-6.54 2.717C4.307 6.504 3.616 8.914 3.589 12c.027 3.086.718 5.496 2.057 7.164 1.43 1.783 3.631 2.698 6.54 2.717 2.623-.02 4.358-.631 5.8-2.045 1.647-1.613 1.618-3.593 1.09-4.798-.31-.71-.873-1.3-1.634-1.75-.192 1.352-.622 2.446-1.284 3.272-.886 1.102-2.14 1.704-3.73 1.79-1.202.065-2.361-.218-3.259-.801-1.063-.689-1.685-1.74-1.752-2.964-.065-1.19.408-2.285 1.33-3.082.88-.76 2.119-1.207 3.583-1.291a13.853 13.853 0 0 1 3.02.142c-.126-.742-.375-1.332-.75-1.757-.513-.586-1.308-.883-2.359-.89h-.029c-.844 0-1.992.232-2.721 1.32L7.734 7.847c.98-1.454 2.568-2.256 4.478-2.256h.044c3.194.02 5.097 1.975 5.287 5.388.108.046.216.094.321.142 1.49.7 2.58 1.761 3.154 3.07.797 1.82.871 4.79-1.548 7.158-1.85 1.81-4.094 2.628-7.277 2.65Zm1.003-11.69c-.242 0-.487.007-.739.021-1.836.103-2.98.946-2.916 2.143.067 1.256 1.452 1.839 2.784 1.767 1.224-.065 2.818-.543 3.086-3.71a10.5 10.5 0 0 0-2.215-.221z",
  linkedin:
    "M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z",
  css: "M0 0v20.16A3.84 3.84 0 0 0 3.84 24h16.32A3.84 3.84 0 0 0 24 20.16V3.84A3.84 3.84 0 0 0 20.16 0Zm14.256 13.08c1.56 0 2.28 1.08 2.304 2.64h-1.608c.024-.288-.048-.6-.144-.84-.096-.192-.288-.264-.552-.264-.456 0-.696.264-.696.84-.024.576.288.888.768 1.08.72.288 1.608.744 1.92 1.296q.432.648.432 1.656c0 1.608-.912 2.592-2.496 2.592-1.656 0-2.4-1.032-2.424-2.688h1.68c0 .792.264 1.176.792 1.176.264 0 .456-.072.552-.24.192-.312.24-1.176-.048-1.512-.312-.408-.912-.6-1.32-.816q-.828-.396-1.224-.936c-.24-.36-.36-.888-.36-1.536 0-1.44.936-2.472 2.424-2.448m5.4 0c1.584 0 2.304 1.08 2.328 2.64h-1.608c0-.288-.048-.6-.168-.84-.096-.192-.264-.264-.528-.264-.48 0-.72.264-.72.84s.288.888.792 1.08c.696.288 1.608.744 1.92 1.296.264.432.408.984.408 1.656.024 1.608-.888 2.592-2.472 2.592-1.68 0-2.424-1.056-2.448-2.688h1.68c0 .744.264 1.176.792 1.176.264 0 .456-.072.552-.24.216-.312.264-1.176-.048-1.512-.288-.408-.888-.6-1.32-.816-.552-.264-.96-.576-1.2-.936s-.36-.888-.36-1.536c-.024-1.44.912-2.472 2.4-2.448m-11.031.018c.711-.006 1.419.198 1.839.63.432.432.672 1.128.648 1.992H9.336c.024-.456-.096-.792-.432-.96-.312-.144-.768-.048-.888.24-.12.264-.192.576-.168.864v3.504c0 .744.264 1.128.768 1.128a.65.65 0 0 0 .552-.264c.168-.24.192-.552.168-.84h1.776c.096 1.632-.984 2.712-2.568 2.688-1.536 0-2.496-.864-2.472-2.472v-4.032c0-.816.24-1.44.696-1.848.432-.408 1.146-.624 1.857-.63",
  ios: "M1.1 6.05C.486 6.05 0 6.53 0 7.13A1.08 1.08 0 0 0 1.1 8.21C1.72 8.21 2.21 7.73 2.21 7.13C2.21 6.53 1.72 6.05 1.1 6.05M8.71 6.07C5.35 6.07 3.25 8.36 3.25 12C3.25 15.67 5.35 17.95 8.71 17.95C12.05 17.95 14.16 15.67 14.16 12C14.16 8.36 12.05 6.07 8.71 6.07M19.55 6.07C17.05 6.07 15.27 7.45 15.27 9.5C15.27 11.13 16.28 12.15 18.4 12.64L19.89 13C21.34 13.33 21.93 13.81 21.93 14.64C21.93 15.6 20.96 16.28 19.58 16.28C18.17 16.28 17.11 15.59 17 14.53H15C15.08 16.65 16.82 17.95 19.46 17.95C22.25 17.95 24 16.58 24 14.4C24 12.69 23 11.72 20.68 11.19L19.35 10.89C17.94 10.55 17.36 10.1 17.36 9.34C17.36 8.38 18.24 7.74 19.54 7.74C20.85 7.74 21.75 8.39 21.85 9.46H23.81C23.76 7.44 22.09 6.07 19.55 6.07M8.71 7.82C10.75 7.82 12.06 9.45 12.06 12C12.06 14.57 10.75 16.2 8.71 16.2C6.65 16.2 5.35 14.57 5.35 12C5.35 9.45 6.65 7.82 8.71 7.82M.111 9.31V17.76H2.1V9.31H.11Z",
  neuform:
    "M111.571 49.9795L84 64.7156L112.332 77.9309 M107.889 87.5876L77.9727 78.5118L88.6616 107.89 M78.6897 111.575L63.9536 84.0035L50.7383 112.335 M41.0796 107.89L50.1554 77.9739L20.7773 88.6627 M17.0924 78.6912L44.6636 63.9551L16.332 50.7398 M20.7812 41.0833L50.697 50.1591L40.0081 20.781 M49.9766 17.0959L64.7127 44.6672L77.928 16.3356 M87.5875 20.7808L78.5117 50.6965L107.89 40.0077",
  designcode:
    "M14 12H24C29.5228 12 34 16.4772 34 22C34 27.5228 29.5228 32 24 32H14V12Z M30.3581 14.3347C28.6503 12.9333 26.6553 12.0237 24.2764 12L14.2469 22L24.2764 32C26.6552 31.9762 28.6503 31.041 30.3581 29.6397C30.3166 29.5982 27.6374 27.0121 26.6669 26.0446C25.6965 25.0772 23.2779 22.7255 22.5501 22C22.5501 22 30.3166 14.3762 30.3581 14.3347Z",
};
/* one driver for every sampled mark; each brand is just a config */
function drawMark(ctx?: any, S?: any, t?: any, o?: any, cfg?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * (cfg.fit ?? 0.88);
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.15 * Math.sin(t * 0.4), 0.13 * Math.sin(t * 0.31), cx, cy, R);
  const pts = pathDots(
    cfg.key,
    MARK_PATHS[cfg.key],
    o.mini ? (cfg.nMini ?? 12) : (cfg.n ?? 26),
    cfg.vb,
    cfg.stroke,
    cfg.invert,
    cfg.recenter,
  );
  const wave = ((((t * (cfg.speed ?? 0.4)) % 1) + 1) % 1) * 2.4 - 1.2;
  const dots: any = [];
  for (const [gx, gy] of pts) {
    let crest: any;
    if (cfg.motion === "scan") crest = Math.exp(-Math.pow(gy - wave, 2) / 0.05);
    else if (cfg.motion === "sweep") {
      const ph = (((Math.atan2(gy, gx) / TAU + 0.5 - t * 0.3) % 1) + 1) % 1;
      crest = Math.exp(-Math.pow(ph - 0.5, 2) / 0.014);
    } else crest = Math.exp(-Math.pow((gx - gy) * 0.5 - wave, 2) / 0.05);
    const [x, y, z] = p(gx, -gy, 0);
    const dep = (z + 1) / 2;
    const d: any = {
      x,
      y,
      z,
      r: (0.78 + 0.72 * dep + 0.45 * crest) * rs,
      v: (cfg.v ?? 0.58) + 0.15 * dep + 0.3 * crest,
    };
    if (cfg.grad) {
      const m = clamp01((gy + 1) / 2);
      d.c = [
        lerp(cfg.grad[0][0], cfg.grad[1][0], m),
        lerp(cfg.grad[0][1], cfg.grad[1][1], m),
        lerp(cfg.grad[0][2], cfg.grad[1][2], m),
      ];
    }
    dots.push(d);
  }
  paint(ctx, dots, cfg.accent ?? null, cfg.accent ? 0.9 : 0, 0.3);
}
const mk = (cfg: any) => (ctx?: any, S?: any, t?: any, o?: any) => drawMark(ctx, S, t, o, cfg);

/* walk a real path at uniform arc length, so its lines come out as even dot runs */
const walkCache: any = new Map();
function pathWalk(key?: any, d?: any, spacing?: any, ox?: any, oy?: any, sc?: any) {
  const ck = "w" + key + "-" + spacing;
  if (walkCache.has(ck)) return walkCache.get(ck);
  const NS = "http://www.w3.org/2000/svg";
  const svg = document.createElementNS(NS, "svg");
  svg.setAttribute("width", "0");
  svg.setAttribute("height", "0");
  svg.style.cssText = "position:absolute;left:-9999px;top:0";
  document.body.appendChild(svg);
  const pts: any = [];
  for (const sub of d.split(/(?=M)/)) {
    /* every subpath gets its own even queue */
    if (!sub.trim()) continue;
    const el = document.createElementNS(NS, "path");
    el.setAttribute("d", sub);
    svg.appendChild(el);
    const L = el.getTotalLength();
    if (!L) continue;
    const n = Math.max(2, Math.round(L / spacing));
    for (let i = 0; i < n; i++) {
      const q = el.getPointAtLength(((i + 0.5) / n) * L);
      pts.push([(q.x - ox) * sc, (q.y - oy) * sc]);
    }
  }
  svg.remove();
  walkCache.set(ck, pts);
  return pts;
}

/* ============ DESIGNCODE — monogram in a dot field ============ */
/* geometry is static, so build it once per size: the disc, minus a clearance
   around the monogram, plus the monogram itself. Normalised on the logo's own
   disc (centre 22,22 r 22 of its 44 viewBox) so the proportions are the logo's. */
const dcCache: any = new Map();
function dcGeom(mini?: any) {
  const ck = mini ? "m" : "s";
  if (dcCache.has(ck)) return dcCache.get(ck);
  /* the monogram, walked evenly along its own outlines (logo's disc: centre 22,22 r 22 of 44) */
  const mark = pathWalk("designcode", MARK_PATHS.designcode, mini ? 3.1 : 1.5, 22, 22, 1 / 22);
  /* the disc of dots behind it, kept clear of the lines */
  const fg = mini ? 0.26 : 0.12,
    cl = mini ? 0.17 : 0.105,
    cl2 = cl * cl;
  const field: any = [];
  for (let gy = -1; gy <= 1; gy += fg) {
    for (let gx = -1; gx <= 1; gx += fg) {
      if (Math.hypot(gx, gy) > 0.97) continue;
      let near = false;
      for (const [mx2, my2] of mark) {
        const dx = gx - mx2,
          dy = gy - my2;
        if (dx * dx + dy * dy < cl2) {
          near = true;
          break;
        }
      }
      if (!near) field.push([gx, gy]);
    }
  }
  const geom: any = { mark, field };
  dcCache.set(ck, geom);
  return geom;
}
function drawDesignCode(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.82;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.12 * Math.sin(t * 0.38), 0.12 * Math.sin(t * 0.29), cx, cy, R);
  const { mark, field } = dcGeom(o.mini);
  const wave = ((((t * 0.3) % 1) + 1) % 1) * 2.3 - 1.15;
  const dots: any = [];
  for (const [gx, gy] of field) {
    const [x, y, z] = p(gx, -gy, 0);
    const dep = (z + 1) / 2;
    dots.push({ x, y, z, r: (0.7 + 0.58 * dep) * rs, v: 0.3 + 0.1 * dep, a: 0.82 });
  }
  for (const [gx, gy] of mark) {
    const crest = Math.exp(-Math.pow(gy - wave, 2) / 0.06);
    const [x, y, z] = p(gx, -gy, 0.05);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.9 + 0.75 * dep + 0.3 * crest) * rs,
      v: 0.78 + 0.1 * dep + 0.18 * crest,
    });
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ AURA — the logo's own dot field ============ */
/* [x, y, radius] for each circle in the Aura mark, normalised on its bounding box */
const AURA_DOTS = [
  [-0.173, -0.959, 0.065],
  [-0.015, -0.963, 0.061],
  [0.138, -0.971, 0.052],
  [-0.264, -0.803, 0.059],
  [-0.103, -0.804, 0.058],
  [0.056, -0.807, 0.055],
  [0.207, -0.817, 0.044],
  [-0.336, -0.636, 0.064],
  [-0.172, -0.634, 0.067],
  [-0.012, -0.636, 0.064],
  [0.131, -0.655, 0.045],
  [0.284, -0.664, 0.036],
  [-0.417, -0.47, 0.068],
  [-0.291, -0.507, 0.032],
  [-0.143, -0.52, 0.018],
  [0.049, -0.49, 0.048],
  [0.201, -0.5, 0.038],
  [0.357, -0.506, 0.033],
  [-0.499, -0.313, 0.064],
  [-0.375, -0.351, 0.025],
  [-0.217, -0.355, 0.021],
  [0.131, -0.331, 0.045],
  [0.285, -0.339, 0.037],
  [0.439, -0.346, 0.03],
  [-0.589, -0.157, 0.058],
  [-0.456, -0.185, 0.03],
  [-0.298, -0.19, 0.025],
  [0.207, -0.17, 0.045],
  [0.361, -0.178, 0.036],
  [0.513, -0.187, 0.027],
  [-0.669, 0.002, 0.055],
  [-0.534, -0.024, 0.029],
  [0.291, -0.009, 0.043],
  [0.45, -0.012, 0.041],
  [0.598, -0.026, 0.026],
  [-0.755, 0.163, 0.054],
  [-0.611, 0.146, 0.036],
  [-0.457, 0.137, 0.028],
  [0.36, 0.145, 0.035],
  [0.523, 0.146, 0.036],
  [0.675, 0.136, 0.026],
  [-0.836, 0.322, 0.05],
  [-0.681, 0.315, 0.043],
  [-0.524, 0.31, 0.039],
  [-0.355, 0.316, 0.045],
  [-0.196, 0.314, 0.043],
  [-0.038, 0.31, 0.038],
  [0.117, 0.303, 0.032],
  [0.265, 0.289, 0.018],
  [0.442, 0.304, 0.032],
  [0.601, 0.301, 0.03],
  [0.759, 0.297, 0.025],
  [-0.924, 0.48, 0.047],
  [-0.765, 0.477, 0.044],
  [-0.588, 0.492, 0.058],
  [-0.43, 0.488, 0.055],
  [-0.3, 0.456, 0.023],
  [-0.118, 0.476, 0.043],
  [0.035, 0.468, 0.035],
  [0.197, 0.467, 0.034],
  [0.353, 0.462, 0.028],
  [0.516, 0.463, 0.029],
  [0.677, 0.462, 0.029],
  [0.832, 0.455, 0.022],
  [-1.0, 0.643, 0.048],
  [-0.839, 0.642, 0.047],
  [-0.675, 0.645, 0.05],
  [-0.527, 0.631, 0.035],
  [0.123, 0.632, 0.037],
  [0.277, 0.625, 0.029],
  [0.437, 0.623, 0.028],
  [0.599, 0.623, 0.028],
  [0.757, 0.619, 0.024],
  [0.918, 0.618, 0.023],
  [-0.92, 0.808, 0.051],
  [-0.762, 0.804, 0.047],
  [0.357, 0.79, 0.033],
  [0.517, 0.787, 0.03],
  [0.676, 0.785, 0.028],
  [0.835, 0.782, 0.024],
  [1.0, 0.785, 0.028],
  [-0.995, 0.971, 0.053],
  [-0.835, 0.97, 0.051],
  [0.604, 0.951, 0.033],
  [0.761, 0.947, 0.028],
  [0.926, 0.95, 0.031],
];
function drawAura(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.63;
  const rs = rscale(S) * (o.mini ? 1.7 : 1);
  const p = proj(0.14 * Math.sin(t * 0.36), 0.12 * Math.sin(t * 0.28), cx, cy, R);
  /* an aura travels outward through the field */
  const ring = ((((t * 0.32) % 1) + 1) % 1) * 2.2 - 0.2;
  const dots: any = [];
  const step = o.mini ? 2 : 1;
  for (let i = 0; i < AURA_DOTS.length; i += step) {
    const [gx, gy, gr] = AURA_DOTS[i];
    const d0 = Math.hypot(gx, gy);
    const glow = Math.exp(-Math.pow(d0 - ring, 2) / 0.045);
    const [x, y, z] = p(gx, -gy, 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: Math.max(0.4, gr * R * 0.92) + (0.25 * dep + 0.5 * glow) * rs,
      v: 0.5 + 0.12 * dep + 0.36 * glow,
    });
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ FLOWER (study) — tapered petal bloom ============ */
function drawFlower(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.92;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.12 * Math.sin(t * 0.34), 0.12 * Math.sin(t * 0.27), cx, cy, R);
  const petals = 6,
    spin = t * 0.15;
  const open = 0.9 + 0.1 * Math.sin(t * 0.8); /* the bloom breathes */
  const a = 0.42,
    b = 0.335; /* petal half-length / half-width */
  const mid = 0.53 * open; /* petal centre, measured from the middle */
  const gap = o.mini ? 0.17 : 0.076;
  const dots: any = [];
  for (let k = 0; k < petals; k++) {
    const th = spin + (k / petals) * TAU;
    const ca = Math.cos(th),
      sa = Math.sin(th);
    const lean = 0.5 + 0.5 * Math.sin(t * 0.9 + k * 1.05);
    for (let u = -a; u <= a; u += gap) {
      /* teardrop: pinched toward the centre, full at the outer end */
      const bw = b * (0.5 + (0.5 * (u + a)) / (2 * a));
      for (let v = -bw; v <= bw; v += gap) {
        const q = Math.pow(Math.abs(u / a), 2.8) + Math.pow(Math.abs(v / bw), 2.4);
        if (q > 1) continue;
        const rad = mid + u;
        const gx = rad * ca - v * sa,
          gy = rad * sa + v * ca;
        const [x, y, z] = p(gx, -gy, 0.05 * (1 - q));
        const dep = (z + 1) / 2;
        const rim = clamp01(q);
        dots.push({
          x,
          y,
          z,
          r: (0.68 + 0.6 * dep + 0.3 * rim) * rs,
          v: 0.48 + 0.13 * dep + 0.26 * rim + 0.1 * lean,
          a: 0.7 + 0.24 * rim,
        });
      }
    }
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ DREAMCUT — the blossom ============ */
function drawDreamCut(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.88;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.11 * Math.sin(t * 0.33), 0.11 * Math.sin(t * 0.26), cx, cy, R);
  const petals = 6,
    spin = t * 0.14;
  const breathe = 1 + 0.04 * Math.sin(t * 0.9);
  /* six round lobes, spaced so they overlap into a scalloped blossom */
  const d = 0.46 * breathe,
    rp = 0.41 * breathe,
    hole = 0.11;
  const pc: any = [];
  for (let k = 0; k < petals; k++) {
    const th = spin + (k / petals) * TAU;
    pc.push([Math.cos(th) * d, Math.sin(th) * d]);
  }
  const gap = o.mini ? 0.2 : 0.1;
  const glow = ((((t * 0.3) % 1) + 1) % 1) * TAU; /* a highlight travels round the bloom */
  const dots: any = [];
  const lit = (gx?: any, gy?: any) => 0.5 + 0.5 * Math.cos(Math.atan2(gy, gx) - glow);
  /* dim fill: the union of the six lobes */
  for (let gy = -1; gy <= 1; gy += gap) {
    for (let gx = -1; gx <= 1; gx += gap) {
      if (Math.hypot(gx, gy) < hole) continue; /* the dark centre */
      let bd = 9;
      for (let k = 0; k < petals; k++) {
        const dd = Math.hypot(gx - pc[k][0], gy - pc[k][1]);
        if (dd < bd) bd = dd;
      }
      if (bd > rp) continue;
      const [x, y, z] = p(gx, -gy, 0.03);
      const dep = (z + 1) / 2;
      const l = lit(gx, gy);
      dots.push({
        x,
        y,
        z,
        r: (0.58 + 0.45 * dep) * rs,
        v: 0.27 + 0.09 * dep + 0.15 * l * l,
        a: 0.66,
      });
    }
  }
  /* each petal's own edge, so the six lobes read as petals and not one blob */
  const per = o.mini ? 10 : 26;
  for (let k = 0; k < petals; k++) {
    for (let i = 0; i < per; i++) {
      const a = (i / per) * TAU;
      const gx = pc[k][0] + Math.cos(a) * rp,
        gy = pc[k][1] + Math.sin(a) * rp;
      if (Math.hypot(gx, gy) < hole) continue;
      const [x, y, z] = p(gx, -gy, 0.06);
      const dep = (z + 1) / 2;
      const l = lit(gx, gy);
      dots.push({ x, y, z, r: (0.88 + 0.78 * dep) * rs, v: 0.66 + 0.12 * dep + 0.26 * l * l });
    }
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ EMAIL — the envelope, flap lifting ============ */
function drawEmail(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.8;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.14 * Math.sin(t * 0.4), 0.14 * Math.sin(t * 0.3), cx, cy, R);
  /* gy runs downward here, so -h is the top edge */
  const w = 0.88,
    h = 0.6,
    r = 0.24;
  /* opens, holds, shuts again */
  const cyc = (((t * 0.3) % 1) + 1) % 1;
  const lift = smooth(Math.sin(clamp01(cyc * 1.5) * Math.PI));
  /* the letter only shows once the flap has actually lifted */
  const show = clamp01((lift - 0.2) / 0.3);
  const step = o.mini ? 0.28 : 0.128; /* spaced like the cube's edges */
  const dots: any = [];
  /* one dot, cube-weighted: bigger and brighter as it comes forward */
  const dot = (gx?: any, gy?: any, z0?: any, v?: any, mul?: any) => {
    const [x, y, z] = p(gx, -gy, z0 || 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.82 + 1.5 * dep) * rs,
      v: v + 0.44 * dep,
      a: (0.62 + 0.38 * dep) * (mul ?? 1),
    });
  };
  const node = (gx?: any, gy?: any, z0?: any, mul?: any) => {
    /* the cube's brighter corner anchors */
    const [x, y, z] = p(gx, -gy, z0 || 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (1.22 + 1.5 * dep) * rs,
      v: 0.62 + 0.4 * dep,
      a: (0.68 + 0.32 * dep) * (mul ?? 1),
    });
  };
  const line = (ax?: any, ay?: any, bx?: any, by?: any, v?: any, z0?: any, mul?: any) => {
    const L = Math.hypot(bx - ax, by - ay),
      n = Math.max(2, Math.round(L / step));
    for (let i = 0; i <= n; i++) {
      const f = i / n;
      dot(ax + (bx - ax) * f, ay + (by - ay) * f, z0, v, mul);
    }
  };
  /* rounded envelope body, walked at even spacing */
  const body: any = [];
  const arc = (ax?: any, ay?: any, a0?: any, a1?: any) => {
    for (let i = 0; i <= 5; i++) {
      const a = a0 + ((a1 - a0) * i) / 5;
      body.push([ax + Math.cos(a) * r, ay + Math.sin(a) * r]);
    }
  };
  body.push([-w + r, -h], [w - r, -h]);
  arc(w - r, -h + r, -Math.PI / 2, 0);
  body.push([w, h - r]);
  arc(w - r, h - r, 0, Math.PI / 2);
  body.push([-w + r, h]);
  arc(-w + r, h - r, Math.PI / 2, Math.PI);
  body.push([-w, -h + r]);
  arc(-w + r, -h + r, Math.PI, Math.PI * 1.5);
  let per = 0;
  for (let i = 0; i < body.length; i++) {
    const a = body[i],
      b = body[(i + 1) % body.length];
    per += Math.hypot(b[0] - a[0], b[1] - a[1]);
  }
  const bodyPath = perimeter(body);
  const N = Math.max(8, Math.round(per / step));
  for (let i = 0; i < N; i++) {
    const [gx, gy] = bodyPath((i + 0.5) / N);
    dot(gx, gy, 0, 0.5);
  }
  /* anchors where the four corners turn */
  const kx = w - r * 0.3,
    ky = h - r * 0.3;
  node(-kx, -ky);
  node(kx, -ky);
  node(kx, ky);
  node(-kx, ky);
  /* the letter: hidden while shut, rising into view as the flap opens */
  if (show > 0.02) {
    const lw = w * 0.6,
      lh = h * 0.62,
      lr = 0.1,
      lz = -0.06;
    const ly = 0; /* sits centred; the flap does the revealing */
    line(-lw + lr, ly - lh, lw - lr, ly - lh, 0.56, lz, show);
    line(-lw + lr, ly + lh, lw - lr, ly + lh, 0.56, lz, show);
    line(-lw, ly - lh + lr, -lw, ly + lh - lr, 0.56, lz, show);
    line(lw, ly - lh + lr, lw, ly + lh - lr, 0.56, lz, show);
    if (!o.mini) {
      /* a couple of written lines */
      line(-lw * 0.55, ly - lh * 0.3, lw * 0.55, ly - lh * 0.3, 0.5, lz, show);
      line(-lw * 0.55, ly + lh * 0.12, lw * 0.28, ly + lh * 0.12, 0.5, lz, show);
    }
    node(-lw, ly - lh, lz, show);
    node(lw, ly - lh, lz, show);
  }
  /* the flap: creased along the top edge, dipping in when shut, swinging up when open */
  const apex = lerp(0.34 * h, -1.5 * h, lift);
  const fx = w - r * 0.4,
    fy = -h + r * 0.1;
  line(-fx, fy, 0, apex, 0.6, 0.07);
  line(fx, fy, 0, apex, 0.6, 0.07);
  node(0, apex, 0.08);
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ OPENAI — the rosette, blooming ============ */
function drawOpenAI(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.9;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.12 * Math.sin(t * 0.38), 0.12 * Math.sin(t * 0.29), cx, cy, R);
  const pts = pathDots("openai", OPENAI_PATH, o.mini ? 14 : 34);
  /* furls shut and opens again; the outer petals swirl further than the middle */
  const cyc = (((t * 0.28) % 1) + 1) % 1;
  const open = smooth(Math.sin(cyc * Math.PI));
  const scl = 0.5 + 0.5 * open;
  const dots: any = [];
  for (const [gx0, gy0] of pts) {
    const r0 = Math.hypot(gx0, gy0),
      th = Math.atan2(gy0, gx0);
    const a = th + (1 - open) * 1.5 * r0 + t * 0.1;
    const rr = r0 * scl;
    const [x, y, z] = p(Math.cos(a) * rr, -Math.sin(a) * rr, 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.78 + 0.7 * dep + 0.4 * r0 * open) * rs,
      v: 0.5 + 0.16 * dep + 0.28 * r0 * open,
    });
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ NEUFORM — eight chevrons ============ */
function drawNeuform(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.88;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.13 * Math.sin(t * 0.36), 0.12 * Math.sin(t * 0.28), cx, cy, R);
  /* the mark is drawn in strokes, so walk it evenly rather than sampling a fill */
  const pts = pathWalk("neuform", MARK_PATHS.neuform, o.mini ? 6.5 : 2.9, 64, 64, 1 / 64);
  const spin = t * 0.12,
    cs = Math.cos(spin),
    sn = Math.sin(spin);
  /* light pushes outward through the eight arms */
  const wave = ((((t * 0.34) % 1) + 1) % 1) * 1.55 - 0.1;
  const dots: any = [];
  for (const [gx0, gy0] of pts) {
    const gx = gx0 * cs - gy0 * sn,
      gy = gx0 * sn + gy0 * cs;
    const rr = Math.hypot(gx, gy);
    const crest = Math.exp(-Math.pow(rr - wave, 2) / 0.035);
    const [x, y, z] = p(gx, -gy, 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.8 + 0.7 * dep + 0.55 * crest) * rs,
      v: 0.48 + 0.14 * dep + 0.34 * crest,
    });
  }
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ UI — the panel ============ */
function drawUI(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.84;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.15 * Math.sin(t * 0.34), 0.14 * Math.sin(t * 0.27), cx, cy, R);
  const step = o.mini ? 0.3 : 0.13;
  const dots: any = [];
  const dot = (gx?: any, gy?: any, v?: any, mul?: any) => {
    const [x, y, z] = p(gx, -gy, 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.8 + 1.45 * dep) * rs,
      v: v + 0.42 * dep,
      a: (0.6 + 0.4 * dep) * (mul ?? 1),
    });
  };
  const line = (ax?: any, ay?: any, bx?: any, by?: any, v?: any, mul?: any) => {
    const L = Math.hypot(bx - ax, by - ay),
      n = Math.max(2, Math.round(L / step));
    for (let i = 0; i <= n; i++) {
      const f = i / n;
      dot(ax + (bx - ax) * f, ay + (by - ay) * f, v, mul);
    }
  };
  const w = 0.84,
    h = 0.64,
    r = 0.16,
    bar = -h + 0.3,
    side = -w + 0.42;
  /* the window frame */
  line(-w + r, -h, w - r, -h, 0.5);
  line(-w + r, h, w - r, h, 0.5);
  line(-w, -h + r, -w, h - r, 0.5);
  line(w, -h + r, w, h - r, 0.5);
  for (const [ax, ay, a0] of [
    [w - r, -h + r, -Math.PI / 2],
    [w - r, h - r, 0],
    [-w + r, h - r, Math.PI / 2],
    [-w + r, -h + r, Math.PI],
  ])
    for (let i = 0; i <= 4; i++) {
      const a = a0 + (i / 4) * (Math.PI / 2);
      dot(ax + Math.cos(a) * r, ay + Math.sin(a) * r, 0.5);
    }
  line(-w, bar, w, bar, 0.46); /* title bar */
  line(side, bar, side, h, 0.42); /* sidebar */
  if (!o.mini) {
    dot(-w + 0.17, -h + 0.15, 0.8);
    dot(-w + 0.3, -h + 0.15, 0.8);
  }
  /* content rows light up in turn, like a panel filling in */
  const rows = o.mini ? 2 : 3;
  for (let i = 0; i < rows; i++) {
    const yy = bar + 0.22 + i * 0.24;
    const pulse = 0.5 + 0.5 * Math.sin(t * 1.5 - i * 1.1);
    line(side + 0.16, yy, w - 0.16 - (i === rows - 1 ? 0.28 : 0), yy, 0.36 + 0.3 * pulse);
  }
  /* and a nav item on the sidebar */
  if (!o.mini)
    for (let i = 0; i < 2; i++) {
      const yy = bar + 0.28 + i * 0.3;
      line(
        -w + 0.14,
        yy,
        side - 0.12,
        yy,
        0.34 + 0.22 * (0.5 + 0.5 * Math.sin(t * 1.5 - i * 1.1 - 0.6)),
      );
    }
  paint(ctx, dots, o.accent, 0.86, 0.3);
}

/* ============ UX — the journey ============ */
const uxCurve = (u: any) => [
  -0.82 + 1.64 * u,
  0.4 * Math.cos(u * Math.PI) - 0.17 * Math.sin(u * TAU),
];
function drawUX(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.86;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.15 * Math.sin(t * 0.33), 0.14 * Math.sin(t * 0.26), cx, cy, R);
  const dots: any = [];
  const dot = (gx?: any, gy?: any, v?: any, size?: any, mul?: any) => {
    const [x, y, z] = p(gx, -gy, 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: ((size ?? 0.8) + 1.4 * dep) * rs,
      v: v + 0.4 * dep,
      a: (0.6 + 0.4 * dep) * (mul ?? 1),
    });
  };
  /* the path itself, evenly spaced */
  const N = o.mini ? 13 : 34;
  for (let i = 0; i <= N; i++) {
    const u = i / N,
      q = uxCurve(u);
    /* a traveller runs the route */
    const head = (((t * 0.32) % 1) + 1) % 1;
    const d = Math.abs(u - head);
    const crest = Math.exp((-d * d) / 0.006);
    dot(q[0], q[1], 0.38 + 0.38 * crest, 0.78 + 0.5 * crest);
  }
  /* waypoints along the way */
  for (const u of o.mini ? [0.5] : [0.06, 0.5, 0.94]) {
    const q = uxCurve(u);
    const ring = o.mini ? 5 : 9,
      rr = 0.13;
    for (let i = 0; i < ring; i++) {
      const a = (i / ring) * TAU;
      dot(q[0] + Math.cos(a) * rr, q[1] + Math.sin(a) * rr, 0.58, 0.78);
    }
  }
  /* an arrowhead where the route ends */
  if (!o.mini) {
    const e = uxCurve(1),
      b = uxCurve(0.93);
    const ang = Math.atan2(e[1] - b[1], e[0] - b[0]);
    for (const s2 of [-1, 1])
      for (let i = 1; i <= 3; i++) {
        const a = ang + Math.PI + s2 * 0.62,
          f = (i / 3) * 0.2;
        dot(e[0] + Math.cos(a) * f, e[1] + Math.sin(a) * f, 0.66);
      }
  }
  paint(ctx, dots, o.accent, 0.86, 0.3);
}

/* ============ CODEX — prompt blob ============ */
const CODEX_CHEV = [
  [-0.3, -0.34],
  [0.07, 0],
  [-0.3, 0.34],
]; /* the '>' , y down */
const CODEX_BAR = [
  [0.11, 0.3],
  [0.43, 0.3],
]; /* the '_' */
function segDist(px?: any, py?: any, ax?: any, ay?: any, bx?: any, by?: any) {
  const dx = bx - ax,
    dy = by - ay,
    L2 = dx * dx + dy * dy;
  let u = L2 ? ((px - ax) * dx + (py - ay) * dy) / L2 : 0;
  u = u < 0 ? 0 : u > 1 ? 1 : u;
  return Math.hypot(px - (ax + dx * u), py - (ay + dy * u));
}
function drawCodex(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.92;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(0.13 * Math.sin(t * 0.42), 0.13 * Math.sin(t * 0.31), cx, cy, R);
  const lobes = 6,
    spin = t * 0.2;
  const amp = 0.1 + 0.03 * Math.sin(t * 1.15);
  const rad = (th: any) => 0.76 * (1 + amp * Math.cos(lobes * (th - spin)));
  /* the underscore blinks like a terminal caret */
  const ph = (((t / 1.15) % 1) + 1) % 1;
  const blink = ph < 0.58 ? 1 : ph < 0.68 ? 1 - (ph - 0.58) / 0.1 : ph < 0.9 ? 0 : (ph - 0.9) / 0.1;
  const light = [186, 186, 252],
    deep = [104, 96, 246];
  const dots: any = [];
  const gap = o.mini ? 0.28 : 0.112;
  const clr = o.mini ? 0.1 : 0.108;
  const chevD = (x?: any, y?: any) =>
    Math.min(
      segDist(x, y, CODEX_CHEV[0][0], CODEX_CHEV[0][1], CODEX_CHEV[1][0], CODEX_CHEV[1][1]),
      segDist(x, y, CODEX_CHEV[1][0], CODEX_CHEV[1][1], CODEX_CHEV[2][0], CODEX_CHEV[2][1]),
    );
  const barD = (x?: any, y?: any) =>
    segDist(x, y, CODEX_BAR[0][0], CODEX_BAR[0][1], CODEX_BAR[1][0], CODEX_BAR[1][1]);
  for (let gy = -1; gy <= 1; gy += gap) {
    for (let gx = -1; gx <= 1; gx += gap) {
      const d = Math.hypot(gx, gy);
      if (!d || d > rad(Math.atan2(gy, gx))) continue;
      if (chevD(gx, gy) < clr || barD(gx, gy) < clr * 0.92)
        continue; /* leave room for the glyphs */
      const [x, y, z] = p(gx, -gy, 0);
      const dep = (z + 1) / 2,
        m = clamp01((gy + 0.85) / 1.7);
      dots.push({
        x,
        y,
        z,
        r: (0.9 + 1.05 * dep) * rs,
        a: 0.95,
        v: 0.8 - 0.12 * m,
        c: [lerp(light[0], deep[0], m), lerp(light[1], deep[1], m), lerp(light[2], deep[2], m)],
      });
    }
  }
  /* the prompt itself, in white */
  const step = o.mini ? 0.13 : 0.052;
  const glyph = (ax?: any, ay?: any, bx?: any, by?: any, alpha?: any) => {
    const L = Math.hypot(bx - ax, by - ay),
      n = Math.max(2, Math.round(L / step));
    for (let i = 0; i <= n; i++) {
      const f = i / n,
        gx = ax + (bx - ax) * f,
        gy = ay + (by - ay) * f;
      const [x, y, z] = p(gx, -gy, 0.06);
      dots.push({
        x,
        y,
        z,
        r: (1.15 + 1.1 * ((z + 1) / 2)) * rs,
        v: 0.97,
        a: alpha,
        c: [255, 255, 255],
      });
    }
  };
  glyph(CODEX_CHEV[0][0], CODEX_CHEV[0][1], CODEX_CHEV[1][0], CODEX_CHEV[1][1], 1);
  glyph(CODEX_CHEV[1][0], CODEX_CHEV[1][1], CODEX_CHEV[2][0], CODEX_CHEV[2][1], 1);
  if (blink > 0.02)
    glyph(CODEX_BAR[0][0], CODEX_BAR[0][1], CODEX_BAR[1][0], CODEX_BAR[1][1], blink);
  paint(ctx, dots, null, 0, 0.3);
}

/* ============ SWIFT — the bird ============ */
function drawSwift(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.88;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  /* a slow bank, as if riding an updraft */
  const p = proj(0.2 * Math.sin(t * 0.43), 0.18 * Math.sin(t * 0.31) - 0.04, cx, cy, R);
  const pts = pathDots("swift", SWIFT_PATH, o.mini ? 11 : 27);
  const bob = 0.035 * Math.sin(t * 0.95);
  const wave = ((((t * 0.4) % 1) + 1) % 1) * 2.4 - 1.2;
  const dots: any = [];
  for (const [gx, gy] of pts) {
    /* crest sweeps tail-to-beak along the bird's diagonal */
    const u = (gx - gy) * 0.5;
    const crest = Math.exp(-Math.pow(u - wave, 2) / 0.05);
    const [x, y, z] = p(gx, -gy + bob, 0);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.75 + 0.8 * dep + 0.45 * crest) * rs,
      v: 0.6 + 0.16 * dep + 0.26 * crest,
    });
  }
  paint(ctx, dots, o.accent, 0.92, 0.3);
}

/* ============ FRAMER — letter morph ============ */
const FRAMER_PTS = (() => {
  /* dot fill of the logo's three sections; each one carries its own diagonal (viewBox 24) */
  const pts: any = [],
    g = 1.72;
  for (let y = 0.9; y <= 7.4; y += g)
    /* top: left edge runs down to (12,8) */
    for (let x = 4 + y; x <= 19.4; x += g) pts.push([x, y, 0]);
  for (let y = 8.9; y <= 15.4; y += g)
    /* middle: right edge runs out to (20,16) */
    for (let x = 4.9; x <= 12 + (y - 8); x += g) pts.push([x, y, 1]);
  for (let y = 16.9; y <= 23.4; y += g)
    /* bottom: left edge runs down to (12,24) */
    for (let x = 4 + (y - 16); x <= 11.9; x += g) pts.push([x, y, 2]);
  return pts;
})();
function drawFramer(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.8;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const list = o.mini ? FRAMER_PTS.filter((_?: any, i?: any) => i % 2 === 0) : FRAMER_PTS;
  const N = list.length;
  /* cycle: sphere -> letter -> sphere (phase-shifted against the Figma orb) */
  const T = 7,
    u = (((t * 0.9 + 3.5) % T) + T) % T;
  let m: any;
  if (u < 2.8) m = 0;
  else if (u < 3.7) m = smooth((u - 2.8) / 0.9);
  else if (u < 5.6) m = 1;
  else if (u < 6.5) m = 1 - smooth((u - 5.6) / 0.9);
  else m = 0;
  const p = proj(t * 0.5, 0.32 + 0.1 * Math.sin(t * 0.35), cx, cy, R);
  const dots: any = [];
  for (let i = 0; i < N; i++) {
    const [lx0, ly0, sec] = list[i];
    const f = fib(i, N);
    const [sx, sy, sz] = p(f[0], f[1], f[2]);
    const sway = 0.012 * Math.sin(t * 1.4 + sec * 2.1) * (sec === 1 ? -1 : 1);
    const lx = cx + (((lx0 - 12) / 12) * 0.95 + sway) * R * 1.02;
    const ly = cy + ((ly0 - 12) / 12) * 0.95 * R * 1.02;
    const x = lerp(sx, lx, m),
      y = lerp(sy, ly, m),
      z = lerp(sz, sec * 0.05 - 0.08, m);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.8 + 1.35 * lerp(dep, 0.85, m)) * rs,
      v: lerp(0.42 + 0.48 * dep, 0.87, m),
    });
  }
  paint(ctx, dots, o.accent, 0.9, 0.3);
}

/* ============ BLUE ORB (study) — band shift ============ */
function drawBands(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.8;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  const p = proj(t * 0.08, 0.35, cx, cy, R);
  const perRing = o.mini ? 14 : 22;
  const bands = [-0.58, 0, 0.58];
  const sub = o.mini ? [0] : [-0.09, 0, 0.09];
  /* eased 90-degree snap every few beats, alternating direction per band */
  const beat = 2.4,
    w = t / beat,
    step = Math.floor(w),
    f = w - step;
  const snapped = step + smooth(clamp01(f * 2.2));
  const snapPulse = Math.sin(clamp01(f * 2.2) * Math.PI);
  const dots: any = [];
  for (let b = 0; b < 3; b++) {
    const dir = b % 2 ? -1 : 1;
    const phase = dir * ((snapped * Math.PI) / 2 + t * 0.18) + b * 0.8;
    const hot = (step % 3 === b ? 1 : 0.25) * snapPulse;
    for (const so of sub) {
      const yy = bands[b] + so;
      const rad = Math.sqrt(Math.max(0, 1 - yy * yy)) * 0.96;
      for (let j = 0; j < perRing; j++) {
        const th = (j / perRing) * TAU + phase;
        const [x, y, z] = p(Math.cos(th) * rad, yy, Math.sin(th) * rad);
        const dep = (z + 1) / 2;
        dots.push({
          x,
          y,
          z,
          r: (0.7 + 1.5 * dep + 0.45 * hot) * rs,
          v: 0.4 + 0.48 * dep + 0.16 * hot,
          a: 0.45 + 0.55 * dep,
        });
      }
    }
  }
  paint(ctx, dots, o.accent, 0.9, 0.3);
}

/* ============ BOOK COVERS (study) — a closed book with a mark stamped on it ============ */
/* the mark is laid onto the cover plane, so it takes the book's perspective */
function drawBookCover(ctx?: any, S?: any, t?: any, o?: any, cfg?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.9;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  /* a gentle three-quarter that drifts, so the cover turns through the light */
  const yaw = 0.55 + 0.13 * Math.sin(t * 0.28);
  const p = proj(yaw, 0.34 + 0.06 * Math.sin(t * 0.41), cx, cy, R);
  const w = 0.54,
    h = 0.72,
    d = 0.15; /* half width / height / half thickness */
  const gapE = o.mini ? 0.33 : 0.155; /* the cube's dot step */
  const dots: any = [];
  const dot = (gx?: any, gy?: any, gz?: any, v?: any, mul?: any, col?: any) => {
    const [x, y, z] = p(gx, gy, gz);
    const dep = (z + 1) / 2;
    const q: any = {
      x,
      y,
      z,
      r: (0.8 + 1.5 * dep) * rs,
      v: v + 0.44 * dep,
      a: (0.58 + 0.42 * dep) * (mul ?? 1),
    };
    if (col) q.c = col;
    dots.push(q);
  };
  const node = (gx?: any, gy?: any, gz?: any, mul?: any) => {
    const [x, y, z] = p(gx, gy, gz);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (1.2 + 1.5 * dep) * rs,
      v: 0.52 + 0.4 * dep,
      a: (0.62 + 0.38 * dep) * (mul ?? 1),
    });
  };
  const edge = (a?: any, b?: any, v?: any, mul?: any) => {
    const L = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
    const k = Math.max(2, Math.round(L / gapE));
    for (let i = 0; i < k; i++) {
      const f = (i + 0.5) / k;
      dot(a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f, a[2] + (b[2] - a[2]) * f, v, mul);
    }
  };
  /* the closed slab */
  const V: any = [];
  for (const sx of [-w, w])
    for (const sy of [-h, h]) for (const sz of [-d, d]) V.push([sx, sy, sz]);
  const ix = (a?: any, b?: any, c?: any) => (a ? 4 : 0) + (b ? 2 : 0) + (c ? 1 : 0);
  const E: any = [];
  for (const a of [0, 1]) for (const b of [0, 1]) E.push([ix(a, b, 0), ix(a, b, 1)]);
  for (const a of [0, 1]) for (const c of [0, 1]) E.push([ix(a, 0, c), ix(a, 1, c)]);
  for (const b of [0, 1]) for (const c of [0, 1]) E.push([ix(0, b, c), ix(1, b, c)]);
  for (const [i, j] of E) edge(V[i], V[j], 0.45);
  for (const q of V) node(q[0], q[1], q[2]);
  /* page edges along the fore-edge, away from the spine */
  if (!o.mini)
    for (const pz of [-d * 0.5, 0, d * 0.5]) edge([w, -h * 0.9, pz], [w, h * 0.9, pz], 0.34);
  /* the mark, stamped on the front cover */
  const front = d + 0.02,
    sp = w * 0.78;
  /* as the book turns, a highlight rakes across the cover */
  for (const [u, v, weight, col] of cfg.marks(t, o)) {
    const rake = 0.55 + 0.45 * Math.cos(u * 2.1 - yaw * 3.4);
    dot(
      u * sp,
      -v * sp,
      front,
      (cfg.base ?? 0.5) * weight + 0.26 * weight * rake,
      1,
      col || cfg.col,
    );
  }
  paint(ctx, dots, null, 0, 0.3);
}
/* Claude's spark burst, flattened onto the cover */
const claudeCoverMarks = (t?: any, o?: any) => {
  const out: any = [],
    rays = o.mini ? 8 : 11,
    per = o.mini ? 3 : 5;
  for (let k = 0; k < rays; k++) {
    const a = (k / rays) * TAU + t * 0.1 + (hash(k, 3.1) - 0.5) * 0.28;
    const pulse = 0.5 + 0.5 * Math.sin(t * 1.7 - k * 1.13);
    const L = (0.6 + 0.38 * hash(k, 7.7)) * (0.82 + 0.24 * pulse * pulse);
    for (let j = 0; j < per; j++) {
      const f = (j + 0.8) / per;
      out.push([Math.cos(a) * L * f, Math.sin(a) * L * f, 0.62 + 0.3 * f + 0.2 * pulse]);
    }
  }
  out.push([0, 0, 1.25]);
  return out;
};
/* OpenAI's rosette, stamped still like a foil block */
const openaiCoverMarks = (t?: any, o?: any) => {
  const pts = pathDots("openai", OPENAI_PATH, o.mini ? 10 : 17);
  const breathe = 1 + 0.02 * Math.sin(t * 0.8);
  return pts.map(([gx, gy]: any) => [gx * 0.78 * breathe, gy * 0.78 * breathe, 0.9]);
};

/* ---- 2-D mark geometry for the book covers: still stamps, built once and cached ---- */
const coverCache: any = new Map();
const cov = (key?: any, build?: any) => {
  if (!coverCache.has(key)) coverCache.set(key, build());
  return coverCache.get(key);
};
/* lay dots along a segment */
const covSeg = (
  out?: any,
  ax?: any,
  ay?: any,
  bx?: any,
  by?: any,
  step?: any,
  w?: any,
  col?: any,
) => {
  const L = Math.hypot(bx - ax, by - ay),
    n = Math.max(2, Math.round(L / step));
  for (let i = 0; i <= n; i++) {
    const f = i / n;
    out.push([ax + (bx - ax) * f, ay + (by - ay) * f, w, col]);
  }
};
/* sample a real logo path straight onto the cover */
const covPath = (
  key?: any,
  d?: any,
  N?: any,
  sc?: any,
  vb?: any,
  stroke?: any,
  inv?: any,
  rc?: any,
) => pathDots("cov" + key, d, N, vb, stroke, inv, rc).map(([x, y]: any) => [x * sc, y * sc, 0.92]);

const COVER_MARKS: any = {
  openai: () => cov("openai", () => covPath("openai", OPENAI_PATH, 17, 0.78)),
  swift: () => cov("swift", () => covPath("swift", SWIFT_PATH, 16, 0.8)),
  github: () =>
    cov("github", () => covPath("github", MARK_PATHS.github, 18, 0.8, 24, 0, "circle", 1)),
  linkedin: () =>
    cov("linkedin", () => covPath("linkedin", MARK_PATHS.linkedin, 18, 0.76, 24, 0, "box", 1)),
  x: () => cov("x", () => covPath("x", MARK_PATHS.x, 16, 0.72)),
  instagram: () => cov("instagram", () => covPath("instagram", MARK_PATHS.instagram, 17, 0.78)),
  threads: () => cov("threads", () => covPath("threads", MARK_PATHS.threads, 17, 0.78)),
  designcode: () =>
    cov("designcode", () =>
      pathWalk("dcCover", MARK_PATHS.designcode, 1.9, 22, 22, 1 / 22).map(([x, y]: any) => [
        x * 1.55,
        y * 1.55,
        0.95,
      ]),
    ),
  framer: () =>
    cov("framer", () =>
      FRAMER_PTS.map(([x, y]: any) => [((x - 12) / 12) * 0.78, ((y - 12) / 12) * 0.78, 0.92]),
    ),
  aura: () =>
    cov("aura", () => AURA_DOTS.map(([x, y, r]: any) => [x * 0.82, y * 0.82, 0.6 + 5 * r])),
  css: () => cov("css", () => covPath("css", MARK_PATHS.css, 19, 0.8, 24, 0, "box", 1)),
  ios: () => cov("ios", () => covPath("ios", MARK_PATHS.ios, 20, 0.86)),
  neuform: () =>
    cov("neuform", () =>
      pathWalk("nfCover", MARK_PATHS.neuform, 3.1, 64, 64, 1 / 64).map(([x, y]: any) => [
        x * 0.84,
        y * 0.84,
        0.95,
      ]),
    ),
  ui: () =>
    cov("ui", () => {
      const o: any = [],
        w = 0.74,
        h = 0.56,
        bar = -h + 0.26,
        side = -w + 0.36;
      covSeg(o, -w, -h, w, -h, 0.1, 0.92);
      covSeg(o, w, -h, w, h, 0.1, 0.92);
      covSeg(o, w, h, -w, h, 0.1, 0.92);
      covSeg(o, -w, h, -w, -h, 0.1, 0.92);
      covSeg(o, -w, bar, w, bar, 0.1, 0.9);
      covSeg(o, side, bar, side, h, 0.1, 0.86);
      for (let i = 0; i < 3; i++)
        covSeg(o, side + 0.14, bar + 0.2 + i * 0.2, w - 0.14, bar + 0.2 + i * 0.2, 0.1, 0.8);
      return o;
    }),
  ux: () =>
    cov("ux", () => {
      const o: any = [];
      for (let i = 0; i <= 30; i++) {
        const q = uxCurve(i / 30);
        o.push([q[0] * 0.82, q[1] * 0.82, 0.9]);
      }
      for (const u of [0.06, 0.5, 0.94]) {
        const q = uxCurve(u);
        for (let i = 0; i < 9; i++) {
          const a = (i / 9) * TAU;
          o.push([(q[0] + Math.cos(a) * 0.13) * 0.82, (q[1] + Math.sin(a) * 0.13) * 0.82, 1]);
        }
      }
      return o;
    }),
  codex: () =>
    cov("codex", () => {
      const o: any = [];
      covSeg(o, -0.4, -0.44, 0.1, 0, 0.075, 0.95); /* the '>' */
      covSeg(o, 0.1, 0, -0.4, 0.44, 0.075, 0.95);
      covSeg(o, 0.17, 0.4, 0.62, 0.4, 0.075, 0.95); /* the '_' */
      return o;
    }),
  cursor: () =>
    cov("cursor", () => {
      const o: any = [],
        P = ARROW_CLEAN;
      for (let i = 0; i < P.length; i++) {
        const a = P[i],
          b = P[(i + 1) % P.length];
        covSeg(o, a[0] * 0.58, a[1] * 0.58, b[0] * 0.58, b[1] * 0.58, 0.07, 0.95);
      }
      return o;
    }),
  gemini: () =>
    cov("gemini", () => {
      const o: any = [],
        N = 44;
      for (let i = 0; i < N; i++) {
        const th = (i / N) * TAU,
          c = Math.cos(th),
          sn = Math.sin(th);
        o.push([c * c * c * 0.82, sn * sn * sn * 0.82, 0.95]);
      }
      return o;
    }),
  figma: () =>
    cov("figma", () => {
      const o: any = [];
      FIGMA_POS.forEach(([px, py]: any, g?: any) => {
        for (let i = 0; i < 15; i++) {
          const ring = 0.175 * Math.sqrt((i + 0.5) / 15),
            a = i * 2.399963 + g * 1.2;
          o.push([
            px * 1.62 + Math.cos(a) * ring,
            py * 1.62 + Math.sin(a) * ring,
            0.98,
            FIGMA_COLS[g],
          ]);
        }
      });
      return o;
    }),
  react: () =>
    cov("react", () => {
      const o: any = [],
        rx = 0.84,
        ry = 0.3,
        per = 26;
      for (let k = 0; k < 3; k++) {
        const a0 = (k * Math.PI) / 3,
          ca = Math.cos(a0),
          sa = Math.sin(a0);
        for (let i = 0; i < per; i++) {
          const th = (i / per) * TAU,
            ex = Math.cos(th) * rx,
            ey = Math.sin(th) * ry;
          o.push([ex * ca - ey * sa, ex * sa + ey * ca, 0.9]);
        }
      }
      o.push([0, 0, 1.15]);
      return o;
    }),
  dreamcut: () =>
    cov("dreamcut", () => {
      const o: any = [],
        petals = 6,
        d = 0.44,
        rp = 0.39,
        hole = 0.1;
      const pc: any = [];
      for (let k = 0; k < petals; k++) {
        const th = (k / petals) * TAU;
        pc.push([Math.cos(th) * d, Math.sin(th) * d]);
      }
      for (let gy = -0.9; gy <= 0.9; gy += 0.135) {
        /* dim fill */
        for (let gx = -0.9; gx <= 0.9; gx += 0.135) {
          if (Math.hypot(gx, gy) < hole) continue;
          let bd = 9;
          for (const q of pc) {
            const dd = Math.hypot(gx - q[0], gy - q[1]);
            if (dd < bd) bd = dd;
          }
          if (bd > rp) continue;
          o.push([gx, gy, 0.58]);
        }
      }
      for (const q of pc) {
        /* each petal's own edge */
        for (let i = 0; i < 24; i++) {
          const a = (i / 24) * TAU;
          const px = q[0] + Math.cos(a) * rp,
            py = q[1] + Math.sin(a) * rp;
          if (Math.hypot(px, py) < hole) continue;
          o.push([px, py, 1]);
        }
      }
      return o;
    }),
  email: () =>
    cov("email", () => {
      const o: any = [],
        w = 0.74,
        h = 0.5;
      covSeg(o, -w, -h, w, -h, 0.085, 0.92);
      covSeg(o, w, -h, w, h, 0.085, 0.92);
      covSeg(o, w, h, -w, h, 0.085, 0.92);
      covSeg(o, -w, h, -w, -h, 0.085, 0.92);
      covSeg(o, -w, -h, 0, h * 0.34, 0.085, 0.95); /* the flap */
      covSeg(o, w, -h, 0, h * 0.34, 0.085, 0.95);
      return o;
    }),
};
const COVER_COL: any = {
  css: [156, 116, 224],
  ios: [214, 214, 224],
  ui: [130, 200, 240],
  ux: [240, 190, 120],
  claude: [222, 132, 100],
  codex: [176, 176, 250],
  gemini: [186, 132, 246],
  framer: [80, 140, 255],
  react: [120, 224, 250],
  swift: [242, 118, 88],
  designcode: [180, 224, 238],
  instagram: [228, 118, 156],
  linkedin: [80, 148, 226],
};
/* one book per mark */
const bookOf = (key: any) => (c?: any, S?: any, t?: any, o?: any) =>
  drawBookCover(c, S, t, o, {
    marks:
      key === "claude"
        ? claudeCoverMarks
        : key === "openai"
          ? openaiCoverMarks
          : (tt?: any, oo?: any) => COVER_MARKS[key](tt, oo),
    col: COVER_COL[key],
    base: 0.5,
  });

/* ============ BOOK (study) — open book, cube-style wireframe ============ */
function drawBook(ctx?: any, S?: any, t?: any, o?: any) {
  const cx = S / 2,
    cy = S / 2,
    R = (S / 2) * 0.84;
  const rs = rscale(S) * (o.mini ? 1.8 : 1);
  /* a three-quarter view like the cube's, drifting */
  const p = proj(0.4 + 0.14 * Math.sin(t * 0.28), 0.66 + 0.05 * Math.sin(t * 0.44), cx, cy, R);
  const h = 0.58,
    Lp = 0.92; /* page half-height / page width, sized so edges carry the cube's dot count */
  /* the cube spaces 8 dots along a 1.24 edge; match that step so every line here is even */
  const gapE = o.mini ? 0.33 : 0.155;
  const dots: any = [];
  const dot = (gx?: any, gy?: any, gz?: any, v?: any, mul?: any) => {
    const [x, y, z] = p(gx, gy, gz);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (0.8 + 1.5 * dep) * rs,
      v: v + 0.44 * dep,
      a: (0.55 + 0.45 * dep) * (mul ?? 1),
    });
  };
  const node = (gx?: any, gy?: any, gz?: any, mul?: any) => {
    /* the cube's brighter corner anchors */
    const [x, y, z] = p(gx, gy, gz);
    const dep = (z + 1) / 2;
    dots.push({
      x,
      y,
      z,
      r: (1.2 + 1.5 * dep) * rs,
      v: 0.52 + 0.4 * dep,
      a: (0.6 + 0.4 * dep) * (mul ?? 1),
    });
  };
  const edge = (a?: any, b?: any, v?: any, mul?: any) => {
    const L = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]);
    const k = Math.max(
      2,
      Math.round(L / gapE),
    ); /* count follows length, so spacing stays constant */
    for (let i = 0; i < k; i++) {
      const f = (i + 0.5) / k;
      dot(a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f, a[2] + (b[2] - a[2]) * f, v, mul);
    }
  };
  /* the two halves breathe between flat-open and tented */
  const lift = 0.17 + 0.19 * (0.5 + 0.5 * Math.sin(t * 0.5));
  /* one half, standing off the spine at angle th (measured in the x-z plane) */
  const leaf = (th?: any, v?: any, mul?: any) => {
    const ex = Math.cos(th) * Lp,
      ez = Math.sin(th) * Lp;
    edge([0, -h, 0], [ex, -h, ez], v, mul);
    edge([ex, -h, ez], [ex, h, ez], v, mul);
    edge([ex, h, ez], [0, h, 0], v, mul);
    node(ex, -h, ez, mul);
    node(ex, h, ez, mul);
  };
  leaf(lift, 0.42); /* right half */
  leaf(Math.PI - lift, 0.42); /* left half */
  /* the spine, and its anchors */
  edge([0, -h, 0], [0, h, 0], 0.6);
  node(0, -h, 0);
  node(0, h, 0);
  /* page edges stacked on each half */
  if (!o.mini)
    for (const f of [0.4, 0.64, 0.86]) {
      for (const th of [lift, Math.PI - lift]) {
        const ex = Math.cos(th) * Lp * f,
          ez = Math.sin(th) * Lp * f;
        edge([ex, -h * 0.93, ez], [ex, h * 0.93, ez], 0.32);
      }
    }
  /* now and then a page sweeps over from one side to the other */
  const cyc = (((t * 0.24) % 1) + 1) % 1;
  if (cyc < 0.5) {
    const tau = smooth(cyc / 0.5);
    const th = lerp(lift, Math.PI - lift, tau);
    const fade = Math.sin(tau * Math.PI) * 0.55 + 0.45;
    leaf(th, 0.66, fade);
  }
  paint(ctx, dots, null, 0, 0.3);
}

const MODES: any = {
  claude: { draw: drawClaude, accent: [217, 119, 87], speed: 1, staticT: 1.4 },
  openai: { draw: drawOpenAI, accent: null, speed: 1, staticT: 0.8 },
  cursor: { draw: drawCursor, accent: null, speed: 1, staticT: 1 },
  gemini: { draw: drawGemini, accent: null, speed: 1, staticT: 0.9 },
  figma: { draw: drawFigma, accent: null, speed: 1, staticT: 5 },
  framer: { draw: drawFramer, accent: [51, 119, 255], speed: 1, staticT: 1.1 },
  codex: { draw: drawCodex, accent: null, speed: 1, staticT: 0.4 },
  react: { draw: drawReact, accent: [97, 218, 251], speed: 1, staticT: 1.2 },
  sphere: { draw: drawSphere, accent: null, speed: 1, staticT: 0.8 },
  css: {
    draw: mk({
      key: "css",
      n: 30,
      nMini: 13,
      motion: "scan",
      speed: 0.34,
      invert: "box",
      accent: [150, 110, 220],
      v: 0.66,
      fit: 1.02,
    }),
    accent: null,
    speed: 1,
    staticT: 1.2,
  },
  ios: {
    draw: mk({ key: "ios", n: 30, nMini: 13, motion: "diag", fit: 0.78, v: 0.64 }),
    accent: null,
    speed: 1,
    staticT: 1.1,
  },
  neuform: { draw: drawNeuform, accent: null, speed: 1, staticT: 1.5 },
  ui: { draw: drawUI, accent: [130, 200, 240], speed: 1, staticT: 1.2 },
  ux: { draw: drawUX, accent: [240, 190, 120], speed: 1, staticT: 1.6 },
  designcode: { draw: drawDesignCode, accent: null, speed: 1, staticT: 1.3 },
  aura: { draw: drawAura, accent: null, speed: 1, staticT: 1.5 },
  dreamcut: { draw: drawDreamCut, accent: null, speed: 1, staticT: 1.2 },
  swift: { draw: drawSwift, accent: [240, 81, 56], speed: 1, staticT: 0.9 },
  github: {
    draw: mk({
      key: "github",
      n: 30,
      nMini: 13,
      motion: "diag",
      invert: "circle",
      recenter: true,
      v: 0.62,
    }),
    accent: null,
    speed: 1,
    staticT: 1.1,
  },
  x: {
    draw: mk({ key: "x", n: 30, nMini: 12, motion: "sweep", fit: 0.7, v: 0.64 }),
    accent: null,
    speed: 1,
    staticT: 1.1,
  },
  instagram: {
    draw: mk({
      key: "instagram",
      n: 28,
      nMini: 13,
      motion: "sweep",
      fit: 0.74,
      grad: [
        [151, 78, 200],
        [250, 140, 70],
      ],
      v: 0.68,
    }),
    accent: null,
    speed: 1,
    staticT: 1.4,
  },
  threads: {
    draw: mk({ key: "threads", n: 30, nMini: 13, motion: "sweep", fit: 0.74, v: 0.64 }),
    accent: null,
    speed: 1,
    staticT: 1.2,
  },
  linkedin: {
    draw: mk({
      key: "linkedin",
      n: 30,
      nMini: 13,
      motion: "scan",
      speed: 0.38,
      invert: "box",
      accent: [40, 130, 220],
      v: 0.66,
    }),
    accent: null,
    speed: 1,
    staticT: 1.2,
  },
  email: { draw: drawEmail, accent: null, speed: 1, staticT: 1.2 },
  flower: { draw: drawFlower, accent: null, speed: 1, staticT: 1.2 },
  book: { draw: drawBook, accent: null, speed: 1, staticT: 0.52 },
  claudebook: { draw: bookOf("claude"), accent: null, speed: 1, staticT: 1.3 },
  openaibook: { draw: bookOf("openai"), accent: null, speed: 1, staticT: 1.3 },
  codexbook: { draw: bookOf("codex"), accent: null, speed: 1, staticT: 1.3 },
  cursorbook: { draw: bookOf("cursor"), accent: null, speed: 1, staticT: 1.3 },
  geminibook: { draw: bookOf("gemini"), accent: null, speed: 1, staticT: 1.3 },
  figmabook: { draw: bookOf("figma"), accent: null, speed: 1, staticT: 1.3 },
  framerbook: { draw: bookOf("framer"), accent: null, speed: 1, staticT: 1.3 },
  reactbook: { draw: bookOf("react"), accent: null, speed: 1, staticT: 1.3 },
  swiftbook: { draw: bookOf("swift"), accent: null, speed: 1, staticT: 1.3 },
  designcodebook: { draw: bookOf("designcode"), accent: null, speed: 1, staticT: 1.3 },
  aurabook: { draw: bookOf("aura"), accent: null, speed: 1, staticT: 1.3 },
  dreamcutbook: { draw: bookOf("dreamcut"), accent: null, speed: 1, staticT: 1.3 },
  githubbook: { draw: bookOf("github"), accent: null, speed: 1, staticT: 1.3 },
  xbook: { draw: bookOf("x"), accent: null, speed: 1, staticT: 1.3 },
  instagrambook: { draw: bookOf("instagram"), accent: null, speed: 1, staticT: 1.3 },
  threadsbook: { draw: bookOf("threads"), accent: null, speed: 1, staticT: 1.3 },
  linkedinbook: { draw: bookOf("linkedin"), accent: null, speed: 1, staticT: 1.3 },
  emailbook: { draw: bookOf("email"), accent: null, speed: 1, staticT: 1.3 },
  uibook: { draw: bookOf("ui"), accent: null, speed: 1, staticT: 1.3 },
  uxbook: { draw: bookOf("ux"), accent: null, speed: 1, staticT: 1.3 },
  cssbook: { draw: bookOf("css"), accent: null, speed: 1, staticT: 1.3 },
  iosbook: { draw: bookOf("ios"), accent: null, speed: 1, staticT: 1.3 },
  neuformbook: { draw: bookOf("neuform"), accent: null, speed: 1, staticT: 1.3 },
  cube: { draw: drawCube, accent: null, speed: 1, staticT: 2.6 },
  orb: { draw: drawBands, accent: [64, 122, 255], speed: 1, staticT: 0.5 },
  pointer: { draw: drawPointer, accent: null, speed: 1, staticT: 1 },
};

export const EMBLEM_GLOBE_BRANDS = [
  "claude",
  "openai",
  "codex",
  "cursor",
  "gemini",
  "figma",
  "framer",
  "react",
  "swift",
  "designcode",
  "aura",
  "dreamcut",
  "ui",
  "ux",
  "css",
  "ios",
  "neuform",
  "github",
  "x",
  "instagram",
  "threads",
  "linkedin",
  "email",
] as const;

export type EmblemGlobeBrand = (typeof EMBLEM_GLOBE_BRANDS)[number];

const SIZE_PIXELS = { small: 20, medium: 56 } as const;

export interface EmblemGlobeProps {
  /** Which brand mark to animate. */
  brand?: EmblemGlobeBrand;
  /** "small" renders a 20px orb, "medium" a 56px orb. */
  size?: "small" | "medium";
  /** Dot colour; `var(--token)` references are resolved from the theme. */
  color?: string;
  /** Animation speed multiplier, clamped to 0.1–3. */
  speed?: number;
  /** Freeze the animation on its current frame. */
  paused?: boolean;
  /** Surface colour behind the globe. */
  backgroundColor?: string;
  className?: string;
}

export function EmblemGlobe({
  brand = "ui",
  size = "medium",
  color = "hsl(var(--primary))",
  speed = 1,
  paused = false,
  backgroundColor = "transparent",
  className,
}: EmblemGlobeProps) {
  const prefersReducedMotion = useReducedMotion();
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const controls = useRef({ speed, paused });
  controls.current.speed = Math.min(3, Math.max(0.1, speed));
  controls.current.paused = paused;

  const S = SIZE_PIXELS[size] ?? 56;

  useEffect(() => {
    const canvas = canvasRef.current;
    const def = MODES[brand] ?? MODES.claude;
    if (!canvas) return;
    const dpr = Math.min(2, window.devicePixelRatio || 1);
    canvas.width = Math.round(S * dpr);
    canvas.height = Math.round(S * dpr);
    const ctx = canvas.getContext("2d");
    if (!ctx) return;
    const o = { mini: S < 32, accent: def.accent };
    // the marks are drawn as lit dots, then recoloured in the theme ink keeping their alpha
    let ink = "";
    const readInk = () => {
      const style = getComputedStyle(document.documentElement);
      ink = color.replace(/var\((--[\w-]+)\)/g, (_, name: string) =>
        style.getPropertyValue(name).trim(),
      );
    };
    readInk();
    const frame = (t: number) => {
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      ctx.globalCompositeOperation = "source-over";
      ctx.clearRect(0, 0, S, S);
      def.draw(ctx, S, t * def.speed * (o.mini ? 1.25 : 1), o);
      ctx.globalCompositeOperation = "source-in";
      ctx.fillStyle = ink;
      ctx.fillRect(0, 0, S, S);
      ctx.globalCompositeOperation = "source-over";
    };
    const themeObserver = new MutationObserver(() => {
      readInk();
      frame(clock / 1e3);
    });
    let clock = performance.now();

    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    if (prefersReducedMotion) {
      clock = def.staticT * 1e3;
      frame(def.staticT);
      return () => themeObserver.disconnect();
    }

    let last = performance.now();
    let visible = true;
    let raf = 0;
    const tick = () => {
      const now = performance.now();
      if (!controls.current.paused) clock += (now - last) * controls.current.speed;
      last = now;
      if (visible && document.visibilityState !== "hidden") frame(clock / 1e3);
      raf = requestAnimationFrame(tick);
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
    });
    io.observe(canvas);
    frame(clock / 1e3);
    raf = requestAnimationFrame(tick);
    return () => {
      cancelAnimationFrame(raf);
      io.disconnect();
      themeObserver.disconnect();
    };
  }, [brand, S, color, prefersReducedMotion]);

  return (
    <div
      className={cn("grid h-full w-full place-items-center", className)}
      style={{ background: backgroundColor }}
    >
      <canvas
        ref={canvasRef}
        aria-hidden="true"
        className="block"
        style={{ width: S, height: S }}
      />
    </div>
  );
}
```

---

# Vitals Board

> An isometric ink-line readout in your theme colours, with floating node cubes, layered planes or a flowing mesh.

Install: `npx @modus-ui/cli add vitals-board`

A square canvas drawn in isometric projection on the page paper: a cluster of floating wireframe cubes, five stacked scan planes, or a breathing height-field mesh. Strong lines take the theme primary and faint ones the foreground, so it follows light, dark and every palette. It pauses when off screen and draws a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add vitals-board
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/vitals-board.tsx`.
3. Paste the code.

## Usage

```tsx
import { VitalsBoard } from "@/components/ui/vitals-board";

export default function Example() {
  return (
    <div className="flex min-h-[400px] items-center justify-center">
      <VitalsBoard variant="flow" />
    </div>
  );
}
```

## Props

| Prop              | Type                            | Default   | Description                                                          |
| :---------------- | :------------------------------ | :-------- | :------------------------------------------------------------------- |
| `variant`         | `"layers" \| "nodes" \| "flow"` | `"nodes"` | Which diagnostic figure to draw.                                     |
| `speed`           | `number`                        | `1`       | Animation speed multiplier (0 to 3).                                 |
| `size`            | `number`                        | `1`       | Scale of the panel.                                                  |
| `opacity`         | `number`                        | `1`       | Opacity of the panel.                                                |
| `hue`             | `number`                        | `0`       | Hue rotation in degrees.                                             |
| `saturation`      | `number`                        | `1`       | Saturation multiplier.                                               |
| `brightness`      | `number`                        | `1`       | Brightness multiplier.                                               |
| `color`           | `string`                        | none      | Hex stroke override; defaults to the theme primary and foreground.   |
| `backgroundColor` | `string`                        | none      | Fill used to occlude hidden lines; defaults to the theme background. |

## Source

`components/ui/vitals-board.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Diagnostics Panel (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type VitalsBoardVariant = "layers" | "nodes" | "flow";

interface VitalsBoardProps {
  variant?: VitalsBoardVariant;
  speed?: number;
  size?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  color?: string;
  backgroundColor?: string;
  className?: string;
}

type Ctx = CanvasRenderingContext2D;
type Ink = (alpha: number) => string;

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

function hexToRgb(hex: string) {
  const value = hex.replace("#", "");
  const full =
    value.length === 3
      ? value
          .split("")
          .map((c) => c + c)
          .join("")
      : value;
  const n = parseInt(full, 16);
  return `${(n >> 16) & 255},${(n >> 8) & 255},${n & 255}`;
}

/** Reads the theme's bare HSL channels and re-reads them when the theme or palette changes. */
function useThemeChannels() {
  const [tokens, setTokens] = useState({ ink: "0 0% 10%", accent: "0 0% 10%", paper: "0 0% 100%" });
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const get = (name: string) => style.getPropertyValue(`--${name}`).trim();
      const next = { ink: get("foreground"), accent: get("primary"), paper: get("background") };
      setTokens((prev) =>
        prev.ink === next.ink && prev.accent === next.accent && prev.paper === next.paper
          ? prev
          : next,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

const projectIso = (x: number, y: number, z: number) => {
  const angle = Math.PI / 6;
  return { x: (x - z) * Math.cos(angle), y: y + (x + z) * Math.sin(angle) };
};

function drawLayers(ctx: Ctx, t: number, ink: Ink, paper: string) {
  const size = 42;
  const layers = 5;
  const gap = 20;
  ctx.lineWidth = 1;
  for (let i = layers - 1; i >= 0; i--) {
    const yOff = i * gap - (layers * gap) / 2 + Math.sin(t + i * 0.4) * 4;
    const p1 = projectIso(-size, yOff, -size);
    const p2 = projectIso(size, yOff, -size);
    const p3 = projectIso(size, yOff, size);
    const p4 = projectIso(-size, yOff, size);

    ctx.beginPath();
    ctx.moveTo(p1.x, p1.y);
    ctx.lineTo(p2.x, p2.y);
    ctx.lineTo(p3.x, p3.y);
    ctx.lineTo(p4.x, p4.y);
    ctx.closePath();

    ctx.fillStyle = paper;
    ctx.fill();
    ctx.strokeStyle = i === 0 ? ink(0.8) : ink(0.15);
    ctx.stroke();

    if (i === 0) {
      ctx.save();
      const center = projectIso(0, yOff, 0);
      ctx.translate(center.x, center.y);
      ctx.scale(1, 0.5);
      const sqSize = size * 0.55;
      ctx.beginPath();
      ctx.rect(-sqSize, -sqSize, sqSize * 2, sqSize * 2);
      ctx.strokeStyle = ink(0.4);
      ctx.stroke();
      ctx.clip();
      for (let j = -sqSize; j < sqSize; j += 4) {
        ctx.beginPath();
        ctx.moveTo(-sqSize, j);
        ctx.lineTo(sqSize, j);
        ctx.strokeStyle = ink(0.2);
        ctx.stroke();
      }
      ctx.restore();
    }

    if (i < layers - 1) {
      const nextY = (i + 1) * gap - (layers * gap) / 2 + Math.sin(t + (i + 1) * 0.4) * 4;
      const p1Next = projectIso(-size, nextY, -size);
      const p3Next = projectIso(size, nextY, size);
      ctx.beginPath();
      ctx.setLineDash([2, 2]);
      ctx.moveTo(p1.x, p1.y);
      ctx.lineTo(p1Next.x, p1Next.y);
      ctx.moveTo(p3.x, p3.y);
      ctx.lineTo(p3Next.x, p3Next.y);
      ctx.strokeStyle = ink(0.1);
      ctx.stroke();
      ctx.setLineDash([]);
    }
  }
}

function drawCube(ctx: Ctx, x: number, y: number, z: number, s: number, colorStr: string) {
  const pts = [
    projectIso(x - s, y - s, z - s),
    projectIso(x + s, y - s, z - s),
    projectIso(x + s, y - s, z + s),
    projectIso(x - s, y - s, z + s),
    projectIso(x - s, y + s, z - s),
    projectIso(x + s, y + s, z - s),
    projectIso(x + s, y + s, z + s),
    projectIso(x - s, y + s, z + s),
  ];
  ctx.strokeStyle = colorStr;
  ctx.lineWidth = 1;
  ctx.beginPath();
  ctx.moveTo(pts[0].x, pts[0].y);
  ctx.lineTo(pts[1].x, pts[1].y);
  ctx.lineTo(pts[2].x, pts[2].y);
  ctx.lineTo(pts[3].x, pts[3].y);
  ctx.closePath();
  ctx.moveTo(pts[4].x, pts[4].y);
  ctx.lineTo(pts[5].x, pts[5].y);
  ctx.lineTo(pts[6].x, pts[6].y);
  ctx.lineTo(pts[7].x, pts[7].y);
  ctx.closePath();
  ctx.moveTo(pts[0].x, pts[0].y);
  ctx.lineTo(pts[4].x, pts[4].y);
  ctx.moveTo(pts[1].x, pts[1].y);
  ctx.lineTo(pts[5].x, pts[5].y);
  ctx.moveTo(pts[2].x, pts[2].y);
  ctx.lineTo(pts[6].x, pts[6].y);
  ctx.moveTo(pts[3].x, pts[3].y);
  ctx.lineTo(pts[7].x, pts[7].y);
  ctx.stroke();
}

function drawNodes(ctx: Ctx, t: number, ink: Ink) {
  const s = 22;
  const float = Math.sin(t) * 4;
  drawCube(ctx, -35, -float, -35, s, ink(0.15));
  drawCube(ctx, 35, float, -35, s, ink(0.15));
  drawCube(ctx, -35, float, 35, s, ink(0.15));
  drawCube(ctx, 35, -float, 35, s, ink(0.15));
  drawCube(ctx, 0, Math.cos(t) * 6 - 15, 0, s * 0.9, ink(0.6));
}

function drawFlow(ctx: Ctx, t: number, ink: Ink, paper: string) {
  const size = 65;
  const segments = 22;
  const step = (size * 2) / segments;
  ctx.lineWidth = 1;
  const getH = (x: number, z: number) => {
    const dist = Math.sqrt(x * x + z * z);
    const peak = Math.max(0, 45 - dist * 1.1);
    const wave = Math.sin(x * 0.2 + t * 1.5) * Math.cos(z * 0.2 + t * 1.5) * 5;
    return -peak - wave + 15;
  };

  for (let z = -size; z < size; z += step) {
    for (let x = -size; x < size; x += step) {
      const y1 = getH(x, z);
      const y2 = getH(x + step, z);
      const y3 = getH(x + step, z + step);
      const y4 = getH(x, z + step);
      const p1 = projectIso(x, y1, z);
      const p2 = projectIso(x + step, y2, z);
      const p3 = projectIso(x + step, y3, z + step);
      const p4 = projectIso(x, y4, z + step);

      ctx.beginPath();
      ctx.moveTo(p1.x, p1.y);
      ctx.lineTo(p2.x, p2.y);
      ctx.lineTo(p3.x, p3.y);
      ctx.lineTo(p4.x, p4.y);
      ctx.closePath();
      ctx.fillStyle = paper;
      ctx.fill();

      const heightRatio = Math.max(0, -y1 / 30);
      const alpha = 0.05 + heightRatio * 0.4;
      ctx.strokeStyle = heightRatio > 0.6 ? ink(alpha + 0.3) : ink(alpha + 0.05);
      ctx.stroke();
    }
  }
}

export function VitalsBoard({
  variant = "nodes",
  speed = 1,
  size = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  color,
  backgroundColor,
  className,
}: VitalsBoardProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const theme = useThemeChannels();
  const paper = backgroundColor ?? `hsl(${theme.paper})`;
  const live = useRef({ speed });
  live.current = { speed: clamp(speed, 0, 3) };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d", { alpha: true });
    if (!host || !canvas || !ctx) return;

    const rgb = color ? hexToRgb(color) : null;
    // Strong marks take the primary, faint ones the foreground, so the figure keeps depth on any palette.
    const ink: Ink = (alpha) =>
      rgb ? `rgba(${rgb},${alpha})` : `hsl(${alpha >= 0.5 ? theme.accent : theme.ink} / ${alpha})`;
    let w = 1;
    let h = 1;
    let time = 0;
    let raf = 0;
    let visible = true;

    const render = () => {
      ctx.clearRect(0, 0, w, h);
      ctx.save();
      ctx.translate(w / 2, h / 2 + 5);
      if (variant === "nodes") drawNodes(ctx, time, ink);
      else if (variant === "flow") drawFlow(ctx, time, ink, paper);
      else drawLayers(ctx, time, ink, paper);
      ctx.restore();
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      w = rect.width;
      h = rect.height;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(w * dpr));
      canvas.height = Math.max(1, Math.floor(h * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      render();
    };

    const loop = () => {
      time += 0.015 * live.current.speed;
      render();
      raf = requestAnimationFrame(loop);
    };

    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (!prefersReducedMotion && visible && !document.hidden) raf = requestAnimationFrame(loop);
    };

    const ro = new ResizeObserver(resize);
    ro.observe(host);
    resize();

    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
    };
  }, [variant, color, theme, paper, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("relative aspect-square w-[360px] max-w-full overflow-hidden", className)}
      style={{
        opacity: clamp(opacity, 0.05, 1),
        transform: size === 1 ? undefined : `scale(${clamp(size, 0.05, 200)})`,
        filter,
      }}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 h-full w-full"
        style={{ touchAction: "none" }}
      />
    </div>
  );
}
```

---

# Tactile Switch

> One switch in four treatments drawn from the Modus tokens: a flat sprung switch, a pressed-paper tactile slider, Three.js glass and a shader-lit capsule.

Install: `npx @modus-ui/cli add tactile-switch`

A switch that fills its stage, in four styles: a flat switch with a sprung knob in `--primary` (the default), a tactile slider whose track, knob and mono label come from the theme tokens, a refractive Three.js glass capsule, and a single-shader plasma trough. Every variant follows light and dark appearance automatically, works with keyboard and screen readers, and the WebGL variants react to the pointer. The WebGL variants pause off screen, and with reduced motion every variant snaps instead of animating.

## Installation

### CLI

```bash
npx @modus-ui/cli add tactile-switch
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/tactile-switch.tsx`.
4. Paste the code.

## Usage

```tsx
import { TactileSwitch } from "@/components/ui/tactile-switch";

export default function Example() {
  return (
    <div className="flex h-[400px] w-full">
      <TactileSwitch variant="glass" onChange={(on) => console.log(on)} />
    </div>
  );
}
```

## Props

| Prop         | Type                                           | Default        | Description                                                   |
| :----------- | :--------------------------------------------- | :------------- | :------------------------------------------------------------ |
| `variant`    | `"classic" \| "modern" \| "glass" \| "shader"` | `"modern"`     | Which treatment to render.                                    |
| `mode`       | `"auto" \| "dark" \| "light"`                  | `"auto"`       | Appearance; `"auto"` follows the page theme, then the system. |
| `defaultOn`  | `boolean`                                      | `true`         | Initial state.                                                |
| `label`      | `string`                                       | `"Draft mode"` | Accessible name, also shown on the knob or in the caption.    |
| `speed`      | `number`                                       | `1`            | Animation speed of the shader variant (0 to 3).               |
| `size`       | `number`                                       | `1`            | Scale of the switch (0.35 to 2.5).                            |
| `opacity`    | `number`                                       | `1`            | Opacity of the whole stage.                                   |
| `hue`        | `number`                                       | `0`            | Hue rotation in degrees.                                      |
| `saturation` | `number`                                       | `1`            | Saturation multiplier.                                        |
| `brightness` | `number`                                       | `1`            | Brightness multiplier.                                        |
| `onChange`   | `(on: boolean) => void`                        | none           | Called with the new state after each toggle.                  |

## Source

`components/ui/tactile-switch.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Skeuomorphic Toggle (MIT, © 2026 Meng To).

import {
  useCallback,
  useEffect,
  useRef,
  useState,
  type CSSProperties,
  type MutableRefObject,
  type PointerEvent,
  type RefObject,
} from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

type ToggleMode = "dark" | "light";
type ToggleModePreference = ToggleMode | "auto";
type TactileSwitchVariant = "classic" | "modern" | "glass" | "shader";

interface TactileSwitchProps {
  variant?: TactileSwitchVariant;
  mode?: ToggleModePreference;
  defaultOn?: boolean;
  label?: string;
  speed?: number;
  size?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  onChange?: (on: boolean) => void;
  className?: string;
}

interface VariantProps {
  mode: ToggleMode;
  on: boolean;
  flip: () => void;
  label: string;
  speed: number;
  size: number;
  still: boolean;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

const BODY_FONT = "var(--font-body), ui-sans-serif, system-ui, sans-serif";
const MONO_FONT = "ui-monospace, SFMono-Regular, Menlo, monospace";

/* ---------------------------------------------------------------------------
   Appearance: the site's data-theme / data-scheme / class wins, then the OS.
--------------------------------------------------------------------------- */

function readAutomaticToggleMode(): ToggleMode {
  if (typeof document === "undefined" || typeof window === "undefined") return "dark";
  const root = document.documentElement;
  const declared = root.dataset.theme ?? root.dataset.scheme;
  if (declared === "light" || declared === "dark") return declared;
  if (root.classList.contains("light")) return "light";
  if (root.classList.contains("dark")) return "dark";
  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
}

function useToggleMode(preference: ToggleModePreference): ToggleMode {
  const enabled = preference === "auto";
  const [automatic, setAutomatic] = useState<ToggleMode>("dark");

  useEffect(() => {
    if (!enabled) return undefined;
    const media = window.matchMedia("(prefers-color-scheme: dark)");
    const update = () => setAutomatic(readAutomaticToggleMode());
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-scheme", "data-theme"],
    });
    media.addEventListener("change", update);
    update();
    return () => {
      observer.disconnect();
      media.removeEventListener("change", update);
    };
  }, [enabled]);

  if (preference === "light" || preference === "dark") return preference;
  return automatic;
}

/* ---------------------------------------------------------------------------
   Frame driver shared by the WebGL variants: runs while on screen and the tab
   is visible; with reduced motion it only draws a settled frame on demand.
--------------------------------------------------------------------------- */

interface FrameScene {
  frame: (now: number, still: boolean) => void;
}

function useFrameLoop(
  hostRef: RefObject<HTMLDivElement | null>,
  sceneRef: MutableRefObject<FrameScene | null>,
  still: boolean,
) {
  const kickRef = useRef<() => void>(() => {});

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return undefined;
    let raf = 0;
    let visible = true;

    const tick = (now: number) => {
      raf = 0;
      const scene = sceneRef.current;
      if (!scene) return;
      scene.frame(now, still);
      if (!still && visible && !document.hidden) raf = requestAnimationFrame(tick);
    };
    const kick = () => {
      if (!raf) raf = requestAnimationFrame(tick);
    };
    const sync = () => {
      if (visible && !document.hidden) kick();
    };
    kickRef.current = kick;

    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    kick();

    return () => {
      cancelAnimationFrame(raf);
      io.disconnect();
      document.removeEventListener("visibilitychange", sync);
      kickRef.current = () => {};
    };
  }, [hostRef, sceneRef, still]);

  return kickRef;
}

/* ---------------------------------------------------------------------------
   Classic: the original tactile export.
--------------------------------------------------------------------------- */

/* Both modes read the Modus tokens, which already flip with the theme; only the depth differs. */
const CLASSIC_BASE = {
  stage: "hsl(var(--background))",
  onBg: "repeating-linear-gradient(90deg, transparent, transparent 2px, hsl(var(--foreground) / 0.03) 2px, hsl(var(--foreground) / 0.03) 4px), linear-gradient(180deg, hsl(var(--primary) / 0.16) 0%, hsl(var(--primary) / 0.42) 100%)",
  offBg:
    "repeating-linear-gradient(90deg, transparent, transparent 2px, hsl(var(--foreground) / 0.03) 2px, hsl(var(--foreground) / 0.03) 4px), linear-gradient(180deg, hsl(var(--muted)) 0%, hsl(var(--border)) 100%)",
  onBorder: "hsl(var(--primary))",
  offBorder: "hsl(var(--border))",
  thumbBg: "linear-gradient(180deg, hsl(var(--card)) 0%, hsl(var(--muted)) 100%)",
  thumbBorder: "hsl(var(--border))",
};

const CLASSIC = {
  light: {
    ...CLASSIC_BASE,
    onShadow:
      "inset 0 4px 8px rgba(0,0,0,0.1), inset 0 -2px 4px rgba(255,255,255,0.6), 0 0 0 6px hsl(var(--card)), 0 0 25px 5px hsl(var(--primary) / 0.28)",
    offShadow:
      "inset 0 4px 8px rgba(0,0,0,0.12), inset 0 -2px 4px rgba(255,255,255,0.5), 0 0 0 6px hsl(var(--card)), 0 0 18px 2px hsl(var(--foreground) / 0.1)",
  },
  dark: {
    ...CLASSIC_BASE,
    onShadow:
      "inset 0 5px 10px rgba(0,0,0,0.52), inset 0 -2px 4px hsl(var(--primary) / 0.2), 0 0 0 6px hsl(var(--card)), 0 0 26px 5px hsl(var(--primary) / 0.3)",
    offShadow:
      "inset 0 5px 10px rgba(0,0,0,0.56), inset 0 -2px 4px hsl(var(--foreground) / 0.1), 0 0 0 6px hsl(var(--card)), 0 0 18px 2px hsl(var(--foreground) / 0.08)",
  },
} as const;

const CLASSIC_ON_THUMB_SHADOW =
  "0 10px 20px -4px hsl(var(--primary) / 0.3), 0 4px 6px -2px rgba(0,0,0,0.06), inset 0 2px 3px hsl(var(--card)), inset 0 -2px 4px hsl(var(--primary) / 0.18)";
const CLASSIC_OFF_THUMB_SHADOW =
  "0 8px 16px -4px rgba(0,0,0,0.18), 0 3px 5px -2px rgba(0,0,0,0.05), inset 0 2px 3px hsl(var(--card)), inset 0 -2px 4px hsl(var(--foreground) / 0.12)";

function ClassicToggle({ mode, on, flip, label, size, still }: VariantProps) {
  const palette = CLASSIC[mode];
  const ease = still ? "none" : undefined;
  return (
    <div
      className="flex h-full w-full items-center justify-center"
      style={{ background: palette.stage, fontFamily: BODY_FONT }}
    >
      <div
        role="switch"
        aria-checked={on}
        aria-label={label}
        tabIndex={0}
        onClick={flip}
        onKeyDown={(event) => {
          if (event.key === "Enter" || event.key === " ") {
            event.preventDefault();
            flip();
          }
        }}
        className="relative z-10 box-border h-16 w-48 cursor-pointer select-none rounded-full p-1.5"
        style={{
          background: on ? palette.onBg : palette.offBg,
          boxShadow: on ? palette.onShadow : palette.offShadow,
          border: `1px solid ${on ? palette.onBorder : palette.offBorder}`,
          transform: size === 1 ? undefined : `scale(${clamp(size, 0.35, 2.5)})`,
          transition:
            ease ?? "background 0.35s ease, box-shadow 0.35s ease, border-color 0.35s ease",
        }}
      >
        <div
          className="absolute left-1.5 top-1.5 box-border flex h-[calc(100%-0.75rem)] w-[116px] items-center justify-center rounded-full"
          style={{
            background: palette.thumbBg,
            boxShadow: on ? CLASSIC_ON_THUMB_SHADOW : CLASSIC_OFF_THUMB_SHADOW,
            border: `1px solid ${palette.thumbBorder}`,
            /* clientWidth 190 - thumb clientWidth 114 - 12 = 64px travel, as the original measures it. */
            transform: `translateX(${on ? 64 : 0}px)`,
            transition:
              ease ?? "transform 0.35s cubic-bezier(0.22, 1, 0.36, 1), box-shadow 0.35s ease",
          }}
        >
          <span
            className="font-mono text-[11px] uppercase tracking-[0.2em]"
            style={{
              opacity: on ? 1 : 0.72,
              color: on ? "hsl(var(--foreground))" : "hsl(var(--muted-foreground))",
              transition: ease ?? "color 0.35s ease, opacity 0.35s ease",
            }}
          >
            {label}
          </span>
        </div>
      </div>
    </div>
  );
}

/* ---------------------------------------------------------------------------
   Modern: flat switch with a sprung, squashing knob.
--------------------------------------------------------------------------- */

const MODERN_BASE = {
  track: "hsl(var(--muted))",
  trackOn: "hsl(var(--primary))",
  edge: "hsl(var(--border))",
  edgeOn: "hsl(var(--primary) / 0.4)",
  thumb: "hsl(var(--card))",
  mark: "hsl(var(--primary))",
  caption: "hsl(var(--muted-foreground))",
  captionOn: "hsl(var(--foreground))",
  focus: "hsl(var(--ring) / 0.35)",
  stage: "hsl(var(--background))",
  stageTop: "hsl(var(--background))",
  stageBottom: "hsl(var(--muted) / 0.6)",
  halo: "hsl(var(--primary) / 0.12)",
};

const MODERN = {
  light: {
    ...MODERN_BASE,
    thumbShadow: "0 1px 1px rgba(0, 0, 0, 0.1), 0 6px 14px -4px rgba(0, 0, 0, 0.28)",
  },
  dark: {
    ...MODERN_BASE,
    thumbShadow: "0 1px 1px rgba(0, 0, 0, 0.5), 0 8px 18px -6px rgba(0, 0, 0, 0.7)",
  },
} as const;

const SPRING_EASE = "cubic-bezier(0.32, 0.72, 0, 1)";

function ModernToggle({ mode, on, flip, label, size, still }: VariantProps) {
  const palette = MODERN[mode];
  const switchRef = useRef<HTMLButtonElement>(null);
  const thumbRef = useRef<HTMLSpanElement>(null);
  const motion = useRef({ value: on ? 1 : 0, velocity: 0 });
  const [focused, setFocused] = useState(false);

  /* A light spring: the knob leans into the travel, trails a little squash
     and settles with one small overshoot (damping ratio ~0.67). */
  useEffect(() => {
    const control = switchRef.current;
    const thumb = thumbRef.current;
    if (!control || !thumb) return undefined;
    const target = on ? 1 : 0;
    const state = motion.current;
    let handle = 0;
    let last = performance.now();

    const apply = (progress: number, speed: number) => {
      const travel = Math.max(0, control.clientWidth - thumb.offsetLeft * 2 - thumb.offsetWidth);
      const lean = Math.min(1, Math.abs(speed) / 6);
      const scaleX = 1 + lean * 0.16;
      const scaleY = 1 - lean * 0.1;
      thumb.style.transformOrigin = speed >= 0 ? "right center" : "left center";
      thumb.style.transform = `translate3d(${(progress * travel).toFixed(2)}px, 0, 0) scale(${scaleX.toFixed(4)}, ${scaleY.toFixed(4)})`;
    };

    const settle = () => {
      state.value = target;
      state.velocity = 0;
      apply(target, 0);
    };

    if (still) {
      settle();
      const observer = new ResizeObserver(settle);
      observer.observe(control);
      return () => observer.disconnect();
    }

    const step = (now: number) => {
      const delta = Math.min(0.032, (now - last) / 1000);
      last = now;
      const stiffness = 210;
      const damping = 19.5;
      state.velocity += ((target - state.value) * stiffness - state.velocity * damping) * delta;
      state.value += state.velocity * delta;
      apply(state.value, state.velocity);
      if (Math.abs(target - state.value) < 0.0006 && Math.abs(state.velocity) < 0.006) {
        settle();
        return;
      }
      handle = requestAnimationFrame(step);
    };

    handle = requestAnimationFrame(step);
    const observer = new ResizeObserver(() => apply(state.value, 0));
    observer.observe(control);
    return () => {
      cancelAnimationFrame(handle);
      observer.disconnect();
    };
  }, [on, still]);

  const t = (value: string) => (still ? "none" : value);
  const markBase: CSSProperties = {
    position: "absolute",
    inset: 0,
    width: "100%",
    height: "100%",
    fill: "none",
    stroke: "currentColor",
    strokeWidth: 2.6,
    strokeLinecap: "round",
    strokeLinejoin: "round",
    transition: t(`opacity 0.28s ease, transform 0.34s ${SPRING_EASE}`),
  };

  return (
    <div
      className="relative box-border grid h-full w-full place-items-center overflow-hidden"
      style={{
        isolation: "isolate",
        containerType: "size",
        background: `linear-gradient(180deg, ${palette.stageTop} 0%, ${palette.stage} 62%, ${palette.stageBottom} 100%)`,
        colorScheme: mode,
        fontFamily: MONO_FONT,
      }}
    >
      <div
        aria-hidden="true"
        className="pointer-events-none absolute rounded-full"
        style={{
          width: "min(72cqw, 620px)",
          height: "min(72cqh, 380px)",
          background: `radial-gradient(closest-side, ${palette.halo}, transparent 72%)`,
          opacity: on ? 1 : 0,
          transform: on ? "scale(1)" : "scale(0.86)",
          transition: t(`opacity 0.5s ease, transform 0.6s ${SPRING_EASE}`),
        }}
      />
      <div
        className="relative grid justify-items-center"
        style={{ gap: "clamp(12px, 2.4cqh, 24px)", transform: `scale(${clamp(size, 0.35, 2.5)})` }}
      >
        <button
          ref={switchRef}
          type="button"
          role="switch"
          aria-checked={on}
          aria-label={label}
          onClick={flip}
          onFocus={(event) => setFocused(event.currentTarget.matches(":focus-visible"))}
          onBlur={() => setFocused(false)}
          className="relative block cursor-pointer appearance-none rounded-full border-0 bg-transparent p-0 outline-none"
          style={{
            width: "clamp(104px, min(18cqw, 33cqh), 330px)",
            aspectRatio: "44 / 25",
            containerType: "inline-size",
            WebkitTapHighlightColor: "transparent",
          }}
        >
          <span
            aria-hidden="true"
            className="absolute inset-0 rounded-full"
            style={{
              background: on ? palette.trackOn : palette.track,
              boxShadow: `inset 0 0 0 1px ${on ? palette.edgeOn : palette.edge}${focused ? `, 0 0 0 4px ${palette.focus}` : ""}`,
              transition: t(`background 0.46s ${SPRING_EASE}, box-shadow 0.46s ease`),
            }}
          />
          <span
            ref={thumbRef}
            aria-hidden="true"
            className="absolute grid place-items-center rounded-full"
            style={{
              top: "4.6cqw",
              left: "4.6cqw",
              width: "47.6cqw",
              height: "47.6cqw",
              background: palette.thumb,
              boxShadow: palette.thumbShadow,
              willChange: "transform",
            }}
          >
            <span className="relative h-[36%] w-[36%]" style={{ color: palette.mark }}>
              <svg
                viewBox="0 0 24 24"
                aria-hidden="true"
                style={{
                  ...markBase,
                  opacity: on ? 1 : 0,
                  transform: on ? "scale(1) rotate(0deg)" : "scale(0.6) rotate(-18deg)",
                }}
              >
                <path d="M5 12.8 9.6 17.4 19 8" />
              </svg>
              <svg
                viewBox="0 0 24 24"
                aria-hidden="true"
                style={{
                  ...markBase,
                  opacity: on ? 0 : 0.34,
                  transform: on ? "scale(0.6)" : "scale(1)",
                }}
              >
                <path d="M6.5 12h11" />
              </svg>
            </span>
          </span>
        </button>
        <p
          className="m-0 flex items-baseline uppercase"
          style={{
            gap: "0.55em",
            fontSize: "clamp(11px, 0.85cqw, 16px)",
            letterSpacing: "0.2em",
            color: on ? palette.captionOn : palette.caption,
            transition: t("color 0.4s ease"),
          }}
        >
          <span>{label}</span>
          <b className="font-medium" style={{ fontVariantNumeric: "tabular-nums" }}>
            {on ? "On" : "Off"}
          </b>
        </p>
      </div>
    </div>
  );
}

/* ---------------------------------------------------------------------------
   Glass: Three.js transmission capsule with a lit filament and a lens knob.
--------------------------------------------------------------------------- */

type GlassPalette = {
  backdrop: number;
  backdropFloor: number;
  shadow: number;
  glass: number;
  attenuationOff: number;
  attenuationOn: number;
  knob: number;
  knobTransmission: number;
  knobEnv: number;
  shellEmissive: number;
  filamentOn: number;
  filamentOff: number;
  key: number;
  keyIntensity: number;
  ambient: number;
  envSkyTop: number;
  envSkyBottom: number;
  envFloor: number;
  envSoftbox: number;
  envIntensity: number;
};

const GLASS_PALETTES: Record<ToggleMode, GlassPalette> = {
  light: {
    backdrop: 0xe9ecf1,
    backdropFloor: 0xdfe3ea,
    shadow: 0.3,
    glass: 0xf4f8ff,
    attenuationOff: 0xdfe8f5,
    attenuationOn: 0x2f6bff,
    knob: 0xfdfeff,
    knobTransmission: 0.78,
    knobEnv: 1.3,
    shellEmissive: 0.02,
    filamentOn: 0x2f6bff,
    filamentOff: 0xc4ccd8,
    key: 0xffffff,
    keyIntensity: 0.18,
    ambient: 0.015,
    envSkyTop: 0xffffff,
    envSkyBottom: 0x9aa4b4,
    envFloor: 0x2a3040,
    envSoftbox: 0xffffff,
    envIntensity: 1.0,
  },
  dark: {
    backdrop: 0x0a0b0f,
    backdropFloor: 0x06070a,
    shadow: 0.55,
    glass: 0xe8eefb,
    attenuationOff: 0x7f93b8,
    attenuationOn: 0x2f6bff,
    knob: 0xf2f6ff,
    knobTransmission: 0.58,
    knobEnv: 2.3,
    shellEmissive: 0.62,
    filamentOn: 0x3b7bff,
    filamentOff: 0x161a24,
    key: 0xd8e4ff,
    keyIntensity: 0.12,
    ambient: 0.006,
    envSkyTop: 0xdde6f5,
    envSkyBottom: 0x1a2030,
    envFloor: 0x04050a,
    envSoftbox: 0xffffff,
    envIntensity: 0.9,
  },
};

const GLASS_STAGE: Record<ToggleMode, string> = { light: "#eef1f6", dark: "#08090d" };

const TRACK_RADIUS = 0.6;
const TRACK_LENGTH = 1.2;
const THUMB_RADIUS = TRACK_RADIUS - 0.225;
const TRAVEL = (TRACK_LENGTH / 2) * 0.8;
const CONTROL_WIDTH = TRACK_LENGTH + TRACK_RADIUS * 2;
const VIEW_HEIGHT = (TRACK_RADIUS * 2) / 0.13;
const WIDTH_SHARE = 0.18;
/* The original ran three r149 legacy lights; physical lights need a PI factor. */
const LEGACY_LIGHT = Math.PI;

/* Hex colours enter three's linear working space through ColorManagement. */
const linear = (hex: number) => new THREE.Color(hex);

type Softbox = {
  u: number;
  v: number;
  halfWidth: number;
  halfHeight: number;
  intensity: number;
  feather: number;
  warm: number;
};

/* An HDR studio: the softboxes run far above the sky so the tone mapper blows
   them into hard specular streaks that make the surface read as glass. */
const SOFTBOXES: readonly Softbox[] = [
  { u: 0.3, v: 0.2, halfWidth: 0.155, halfHeight: 0.135, intensity: 19, feather: 0.86, warm: 0.04 },
  { u: 0.52, v: 0.115, halfWidth: 0.17, halfHeight: 0.04, intensity: 15, feather: 0.9, warm: 0 },
  {
    u: 0.86,
    v: 0.31,
    halfWidth: 0.085,
    halfHeight: 0.09,
    intensity: 10,
    feather: 0.92,
    warm: -0.06,
  },
  { u: 0.25, v: 0.5, halfWidth: 0.1, halfHeight: 0.2, intensity: 6.5, feather: 0.8, warm: 0 },
  {
    u: 0.95,
    v: 0.21,
    halfWidth: 0.028,
    halfHeight: 0.032,
    intensity: 70,
    feather: 0.45,
    warm: 0.02,
  },
  { u: 0.5, v: 0.82, halfWidth: 0.5, halfHeight: 0.22, intensity: 0.5, feather: 1, warm: 0.02 },
];

function smoothFalloff(distance: number, extent: number, feather: number) {
  const inner = extent * (1 - feather);
  if (distance <= inner) return 1;
  if (distance >= extent) return 0;
  const t = (distance - inner) / (extent - inner);
  return 1 - t * t * (3 - 2 * t);
}

function buildEnvironmentTexture(palette: GlassPalette) {
  const width = 512;
  const height = 256;
  const data = new Float32Array(width * height * 4);
  const skyTop = linear(palette.envSkyTop);
  const skyBottom = linear(palette.envSkyBottom);
  const floor = linear(palette.envFloor);
  const box = linear(palette.envSoftbox);

  for (let y = 0; y < height; y += 1) {
    const v = 1 - y / (height - 1);
    const ground = smoothFalloff(Math.max(0, 0.62 - v), 0.34, 1);
    const skyMix = Math.min(1, v / 0.56);
    const skyR = skyTop.r + (skyBottom.r - skyTop.r) * skyMix;
    const skyG = skyTop.g + (skyBottom.g - skyTop.g) * skyMix;
    const skyB = skyTop.b + (skyBottom.b - skyTop.b) * skyMix;
    const fade = 1 - Math.max(0, v - 0.62) * 1.1;
    const baseR = skyR + (floor.r * fade - skyR) * ground;
    const baseG = skyG + (floor.g * fade - skyG) * ground;
    const baseB = skyB + (floor.b * fade - skyB) * ground;

    for (let x = 0; x < width; x += 1) {
      const u = x / (width - 1);
      let r = baseR;
      let g = baseG;
      let b = baseB;
      for (const light of SOFTBOXES) {
        let du = Math.abs(u - light.u);
        if (du > 0.5) du = 1 - du;
        const dv = Math.abs(v - light.v);
        const radial = Math.sqrt(
          (du / light.halfWidth) * (du / light.halfWidth) +
            (dv / light.halfHeight) * (dv / light.halfHeight),
        );
        if (radial >= 1) continue;
        const strength = smoothFalloff(radial, 1, light.feather) * light.intensity;
        r += box.r * strength * (1 + light.warm);
        g += box.g * strength;
        b += box.b * strength * (1 - light.warm);
      }
      const index = (y * width + x) * 4;
      data[index] = r;
      data[index + 1] = g;
      data[index + 2] = b;
      data[index + 3] = 1;
    }
  }

  const texture = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.FloatType);
  texture.mapping = THREE.EquirectangularReflectionMapping;
  texture.minFilter = THREE.LinearFilter;
  texture.magFilter = THREE.LinearFilter;
  texture.generateMipmaps = false;
  texture.needsUpdate = true;
  return texture;
}

function buildMicroTextures() {
  const size = 512;
  const canvas = document.createElement("canvas");
  canvas.width = size;
  canvas.height = size;
  const ctx = canvas.getContext("2d");
  if (!ctx) return null;

  const image = ctx.createImageData(size, size);
  const height = new Float32Array(size * size);
  let seed = 0x9e3779b9;
  const random = () => {
    seed ^= seed << 13;
    seed ^= seed >>> 17;
    seed ^= seed << 5;
    return ((seed >>> 0) % 100000) / 100000;
  };

  const coarse = new Float32Array(64 * 64);
  for (let i = 0; i < coarse.length; i += 1) coarse[i] = random();
  const at64 = (ax: number, ay: number) => coarse[(ay & 63) * 64 + (ax & 63)];
  for (let y = 0; y < size; y += 1) {
    for (let x = 0; x < size; x += 1) {
      const u = (x / size) * 64;
      const v = (y / size) * 64;
      const x0 = Math.floor(u);
      const y0 = Math.floor(v);
      const fx = u - x0;
      const fy = v - y0;
      const sx = fx * fx * (3 - 2 * fx);
      const sy = fy * fy * (3 - 2 * fy);
      const a = at64(x0, y0);
      const b = at64(x0 + 1, y0);
      const c = at64(x0, y0 + 1);
      const d = at64(x0 + 1, y0 + 1);
      const value = (a * (1 - sx) + b * sx) * (1 - sy) + (c * (1 - sx) + d * sx) * sy;
      const grain = Math.sin(x * 12.9898 + y * 78.233) * 43758.5453;
      height[y * size + x] = value * 0.86 + (grain - Math.floor(grain)) * 0.14;
    }
  }

  for (let i = 0; i < height.length; i += 1) {
    const value = 168 + height[i] * 78;
    image.data[i * 4] = value;
    image.data[i * 4 + 1] = value;
    image.data[i * 4 + 2] = value;
    image.data[i * 4 + 3] = 255;
  }
  ctx.putImageData(image, 0, 0);
  const roughness = new THREE.CanvasTexture(canvas);
  roughness.wrapS = THREE.RepeatWrapping;
  roughness.wrapT = THREE.RepeatWrapping;

  const normalCanvas = document.createElement("canvas");
  normalCanvas.width = size;
  normalCanvas.height = size;
  const normalCtx = normalCanvas.getContext("2d");
  if (!normalCtx) return { roughness, normal: null };
  const normalImage = normalCtx.createImageData(size, size);
  const at = (x: number, y: number) => height[((y + size) % size) * size + ((x + size) % size)];
  for (let y = 0; y < size; y += 1) {
    for (let x = 0; x < size; x += 1) {
      const dx = at(x + 1, y) - at(x - 1, y);
      const dy = at(x, y + 1) - at(x, y - 1);
      const index = (y * size + x) * 4;
      normalImage.data[index] = 128 + dx * 110;
      normalImage.data[index + 1] = 128 - dy * 110;
      normalImage.data[index + 2] = 255;
      normalImage.data[index + 3] = 255;
    }
  }
  normalCtx.putImageData(normalImage, 0, 0);
  const normal = new THREE.CanvasTexture(normalCanvas);
  normal.wrapS = THREE.RepeatWrapping;
  normal.wrapT = THREE.RepeatWrapping;
  return { roughness, normal };
}

const BACKDROP_VERTEX = /* glsl */ `
varying vec2 vUv;
void main() {
  vUv = uv;
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}
`;

const BACKDROP_FRAGMENT = /* glsl */ `
precision highp float;
varying vec2 vUv;
uniform float uAspect;
uniform float uShadow;
uniform vec3 uBackdrop;
uniform vec3 uFloor;

void main() {
  vec2 p = vec2((vUv.x - 0.5) * uAspect, vUv.y - 0.5);
  vec3 color = mix(uFloor, uBackdrop, smoothstep(-0.42, 0.16, p.y));

  vec2 core = (p - vec2(0.0, -0.052)) / vec2(0.148, 0.038);
  vec2 spread = (p - vec2(0.0, -0.062)) / vec2(0.28, 0.1);
  float occlusion = exp(-dot(core, core) * 0.9) * 0.72 + exp(-dot(spread, spread) * 0.8) * 0.42;
  color *= 1.0 - clamp(occlusion, 0.0, 1.0) * uShadow;

  float dither = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
  color += (dither - 0.5) * 0.0035;

  gl_FragColor = vec4(color, 1.0);
}
`;

interface ToggleScene extends FrameScene {
  setMode: (mode: ToggleMode) => void;
  setSpeed: (speed: number) => void;
  setSize: (size: number) => void;
  setOn: (on: boolean) => void;
  setPointer: (x: number, y: number) => void;
  resize: (width: number, height: number) => void;
  measureSwitch: () => { width: number; height: number };
  dispose: () => void;
}

function createGlassScene(
  canvas: HTMLCanvasElement,
  mode: ToggleMode,
  speed: number,
  on: boolean,
): ToggleScene {
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
  renderer.outputColorSpace = THREE.SRGBColorSpace;
  renderer.toneMapping = THREE.ACESFilmicToneMapping;
  renderer.toneMappingExposure = 1;

  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(26, 1, 0.1, 40);
  camera.position.set(0, 0.22, 9.4);
  camera.lookAt(0, 0, 0);

  const pmrem = new THREE.PMREMGenerator(renderer);
  pmrem.compileEquirectangularShader();

  const backdropUniforms = {
    uAspect: { value: 1 },
    uShadow: { value: GLASS_PALETTES[mode].shadow },
    uBackdrop: { value: linear(GLASS_PALETTES[mode].backdrop) },
    uFloor: { value: linear(GLASS_PALETTES[mode].backdropFloor) },
  };

  const backdrop = new THREE.Mesh(
    new THREE.PlaneGeometry(1, 1),
    new THREE.ShaderMaterial({
      uniforms: backdropUniforms,
      vertexShader: BACKDROP_VERTEX,
      fragmentShader: BACKDROP_FRAGMENT,
      depthWrite: false,
    }),
  );
  backdrop.position.z = -3.2;
  backdrop.renderOrder = -1;
  scene.add(backdrop);

  const micro = buildMicroTextures();
  const maxAnisotropy = renderer.capabilities.getMaxAnisotropy();
  if (micro?.roughness) {
    micro.roughness.anisotropy = maxAnisotropy;
    micro.roughness.repeat.set(3, 2);
  }
  if (micro?.normal) {
    micro.normal.anisotropy = maxAnisotropy;
    micro.normal.repeat.set(3, 2);
  }

  const rig = new THREE.Group();
  rig.rotation.set(-0.05, 0.13, 0);
  scene.add(rig);

  const glassMaterial = new THREE.MeshPhysicalMaterial({
    color: linear(GLASS_PALETTES[mode].glass),
    metalness: 0,
    roughness: 0.115,
    transmission: 1,
    ior: 1.62,
    clearcoat: 1,
    clearcoatRoughness: 0.008,
    attenuationColor: linear(GLASS_PALETTES[mode].attenuationOff),
    attenuationDistance: 6,
    envMapIntensity: GLASS_PALETTES[mode].envIntensity,
    specularIntensity: 1,
    roughnessMap: micro?.roughness ?? null,
    clearcoatNormalMap: micro?.normal ?? null,
    clearcoatNormalScale: new THREE.Vector2(0.13, 0.13),
    thickness: 1.25,
    iridescence: 0.2,
    iridescenceIOR: 1.3,
    iridescenceThicknessRange: [120, 420],
    emissive: linear(GLASS_PALETTES[mode].filamentOn),
    emissiveIntensity: 0,
  });

  const track = new THREE.Mesh(
    new THREE.CapsuleGeometry(TRACK_RADIUS, TRACK_LENGTH, 64, 192),
    glassMaterial,
  );
  track.rotation.z = Math.PI / 2;
  track.scale.set(1, 1, 0.82);
  rig.add(track);

  const filamentMaterial = new THREE.MeshStandardMaterial({
    color: linear(GLASS_PALETTES[mode].filamentOff),
    emissive: linear(GLASS_PALETTES[mode].filamentOn),
    emissiveIntensity: on ? 1 : 0,
    roughness: 0.34,
    metalness: 0,
  });
  const filament = new THREE.Mesh(
    new THREE.CapsuleGeometry(0.105, TRACK_LENGTH + 0.16, 16, 64),
    filamentMaterial,
  );
  filament.rotation.z = Math.PI / 2;
  filament.position.set(0, -0.31, -0.04);
  rig.add(filament);

  const knobMaterial = new THREE.MeshPhysicalMaterial({
    color: linear(GLASS_PALETTES[mode].knob),
    metalness: 0,
    roughness: 0.125,
    transmission: GLASS_PALETTES[mode].knobTransmission,
    ior: 1.47,
    clearcoat: 1,
    clearcoatRoughness: 0.01,
    attenuationColor: linear(GLASS_PALETTES[mode].attenuationOff),
    attenuationDistance: 3,
    envMapIntensity: GLASS_PALETTES[mode].envIntensity * GLASS_PALETTES[mode].knobEnv,
    roughnessMap: micro?.roughness ?? null,
    clearcoatNormalMap: micro?.normal ?? null,
    clearcoatNormalScale: new THREE.Vector2(0.1, 0.1),
    thickness: 0.62,
    iridescence: 0.12,
    iridescenceIOR: 1.25,
    iridescenceThicknessRange: [100, 380],
  });

  const knob = new THREE.Mesh(new THREE.SphereGeometry(THUMB_RADIUS, 160, 96), knobMaterial);
  knob.position.z = TRACK_RADIUS * 0.82;
  rig.add(knob);

  const ambient = new THREE.AmbientLight(0xffffff, GLASS_PALETTES[mode].ambient * LEGACY_LIGHT);
  scene.add(ambient);

  const key = new THREE.DirectionalLight(
    linear(GLASS_PALETTES[mode].key),
    GLASS_PALETTES[mode].keyIntensity * LEGACY_LIGHT,
  );
  key.position.set(2.2, 3.4, 4);
  scene.add(key);

  let environmentTarget: THREE.WebGLRenderTarget | null = null;
  function applyEnvironment(next: ToggleMode) {
    const source = buildEnvironmentTexture(GLASS_PALETTES[next]);
    const nextTarget = pmrem.fromEquirectangular(source);
    source.dispose();
    environmentTarget?.dispose();
    environmentTarget = nextTarget;
    scene.environment = nextTarget.texture;
  }
  applyEnvironment(mode);

  let currentMode = mode;
  let currentSpeed = speed;
  let target = on ? 1 : 0;
  let progress = target;
  let velocity = 0;
  let onGlow = target;
  const attenuationOffColor = linear(GLASS_PALETTES[mode].attenuationOff);
  const attenuationOnColor = linear(GLASS_PALETTES[mode].attenuationOn);
  const filamentOffColor = linear(GLASS_PALETTES[mode].filamentOff);
  const filamentOnColor = linear(GLASS_PALETTES[mode].filamentOn);
  const pointer = new THREE.Vector2(0, 0);
  const smoothedPointer = new THREE.Vector2(0, 0);
  let width = 1;
  let height = 1;
  let baseDistance = camera.position.z;
  let sizeScale = 1;
  let last = performance.now();

  function applyPalette(next: ToggleMode) {
    const palette = GLASS_PALETTES[next];
    backdropUniforms.uBackdrop.value = linear(palette.backdrop);
    backdropUniforms.uFloor.value = linear(palette.backdropFloor);
    backdropUniforms.uShadow.value = palette.shadow;
    glassMaterial.color = linear(palette.glass);
    glassMaterial.envMapIntensity = palette.envIntensity;
    knobMaterial.color = linear(palette.knob);
    knobMaterial.attenuationColor = linear(palette.attenuationOff);
    knobMaterial.transmission = palette.knobTransmission;
    knobMaterial.envMapIntensity = palette.envIntensity * palette.knobEnv;
    attenuationOffColor.copy(linear(palette.attenuationOff));
    attenuationOnColor.copy(linear(palette.attenuationOn));
    filamentOffColor.copy(linear(palette.filamentOff));
    filamentOnColor.copy(linear(palette.filamentOn));
    filamentMaterial.emissive = linear(palette.filamentOn);
    glassMaterial.emissive = linear(palette.filamentOn);
    ambient.intensity = palette.ambient * LEGACY_LIGHT;
    key.color = linear(palette.key);
    key.intensity = palette.keyIntensity * LEGACY_LIGHT;
    applyEnvironment(next);
  }

  function resize(nextWidth: number, nextHeight: number) {
    width = Math.max(1, Math.round(nextWidth));
    height = Math.max(1, Math.round(nextHeight));
    renderer.setSize(width, height, false);
    camera.aspect = width / height;
    /* Frame the control by moving the camera rather than scaling the meshes:
       glass thickness is in world units. */
    const halfFov = (camera.fov * Math.PI) / 360;
    const visibleHeight =
      Math.max(VIEW_HEIGHT, CONTROL_WIDTH / (WIDTH_SHARE * camera.aspect)) / sizeScale;
    baseDistance = visibleHeight / (2 * Math.tan(halfFov));
    camera.position.z = baseDistance;
    camera.updateProjectionMatrix();
    const backdropHeight = 2 * (baseDistance - backdrop.position.z) * Math.tan(halfFov);
    backdrop.scale.set(backdropHeight * camera.aspect * 1.08, backdropHeight * 1.08, 1);
    backdropUniforms.uAspect.value = camera.aspect;
  }

  function measureSwitch() {
    const halfWidth = TRACK_LENGTH / 2 + TRACK_RADIUS;
    const left = new THREE.Vector3(-halfWidth, 0, 0).project(camera);
    const right = new THREE.Vector3(halfWidth, 0, 0).project(camera);
    const top = new THREE.Vector3(0, TRACK_RADIUS, 0).project(camera);
    const bottom = new THREE.Vector3(0, -TRACK_RADIUS, 0).project(camera);
    return {
      width: Math.abs(right.x - left.x) * 0.5 * width,
      height: Math.abs(top.y - bottom.y) * 0.5 * height,
    };
  }

  function frame(now: number, still: boolean) {
    const delta = Math.min(0.05, (now - last) / 1000);
    last = now;
    if (still) {
      progress = target;
      velocity = 0;
      onGlow = target;
      smoothedPointer.copy(pointer);
    } else {
      /* Critically damped travel: a heavy glass object should not wobble. */
      const stiffness = 150;
      const damping = 2 * Math.sqrt(stiffness);
      velocity += (target - progress) * stiffness * delta - velocity * damping * delta;
      progress += velocity * delta;
      onGlow += (target - onGlow) * Math.min(1, delta * 6);
      smoothedPointer.lerp(pointer, Math.min(1, delta * 3.2));
    }
    void currentSpeed;

    knob.position.x = (progress * 2 - 1) * TRAVEL;
    knob.rotation.z = -progress * Math.PI * 0.9;
    knob.rotation.y = smoothedPointer.x * 0.3;

    filamentMaterial.emissiveIntensity = onGlow * (currentMode === "dark" ? 3.2 : 1.4);
    filamentMaterial.color.copy(filamentOffColor).lerp(filamentOnColor, onGlow * 0.85);
    glassMaterial.attenuationColor.copy(attenuationOffColor).lerp(attenuationOnColor, onGlow);
    glassMaterial.attenuationDistance = 6 - onGlow * 4.8;
    glassMaterial.emissiveIntensity = onGlow * GLASS_PALETTES[currentMode].shellEmissive;

    camera.position.set(smoothedPointer.x * 0.5, 0.22 + smoothedPointer.y * 0.32, baseDistance);
    camera.lookAt(0, 0, 0);
    renderer.render(scene, camera);
  }

  return {
    frame,
    setMode(next) {
      if (next === currentMode) return;
      currentMode = next;
      applyPalette(next);
    },
    setSpeed(next) {
      currentSpeed = next;
    },
    setSize(next) {
      sizeScale = next;
      resize(width, height);
    },
    setOn(next) {
      target = next ? 1 : 0;
    },
    setPointer(x, y) {
      pointer.set(x, y);
    },
    resize,
    measureSwitch,
    dispose() {
      environmentTarget?.dispose();
      pmrem.dispose();
      micro?.roughness?.dispose();
      micro?.normal?.dispose();
      scene.traverse((object) => {
        if (!(object instanceof THREE.Mesh)) return;
        object.geometry.dispose();
        const material = object.material;
        if (Array.isArray(material)) material.forEach((entry) => entry.dispose());
        else material.dispose();
      });
      renderer.dispose();
    },
  };
}

/* ---------------------------------------------------------------------------
   Shader: one fragment shader draws the whole control.
--------------------------------------------------------------------------- */

const SHADER_STAGE: Record<ToggleMode, string> = { light: "#f4f6fa", dark: "#06070b" };

const SHADER_VERTEX = `
attribute vec2 aPosition;
void main() {
  gl_Position = vec4(aPosition, 0.0, 1.0);
}
`;

const SHADER_FRAGMENT_BODY = `
precision highp float;

uniform vec2 uRes;
uniform float uUnit;
uniform float uTime;
uniform float uOn;
uniform float uProgress;
uniform float uMode;
uniform vec2 uPointer;

const float R = 1.0;
const float L = 1.35;
const float TH = 0.78;
const float PI = 3.14159265359;

float hash11(float n) {
  return fract(sin(n * 127.1) * 43758.5453123);
}

vec2 hash21(float n) {
  return fract(sin(vec2(n * 127.1, n * 311.7)) * 43758.5453123);
}

float hash22(vec2 co) {
  return fract(sin(dot(mod(co, 512.0), vec2(12.9898, 78.233))) * 43758.5453123);
}

float valueNoise(vec2 p) {
  vec2 i = floor(p);
  vec2 f = fract(p);
  vec2 u = f * f * (3.0 - 2.0 * f);
  float a = hash11(i.x + i.y * 57.0);
  float b = hash11(i.x + 1.0 + i.y * 57.0);
  float c = hash11(i.x + (i.y + 1.0) * 57.0);
  float d = hash11(i.x + 1.0 + (i.y + 1.0) * 57.0);
  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
}

float fbm(vec2 p) {
  float value = 0.0;
  float amplitude = 0.5;
  for (int i = 0; i < 5; i++) {
    value += amplitude * valueNoise(p);
    p = p * 2.03 + 11.3;
    amplitude *= 0.5;
  }
  return value;
}

float ridged(vec2 p) {
  float value = 0.0;
  float amplitude = 0.5;
  for (int i = 0; i < 4; i++) {
    float n = 1.0 - abs(valueNoise(p) * 2.0 - 1.0);
    value += amplitude * n * n;
    p = p * 2.11 + 7.7;
    amplitude *= 0.5;
  }
  return value;
}

vec2 warp(vec2 p, float t) {
  vec2 q = vec2(fbm(p + vec2(0.0, t * 0.12)), fbm(p + vec2(5.2, 1.3) - t * 0.09));
  vec2 r = vec2(fbm(p + 3.4 * q + vec2(1.7, 9.2)), fbm(p + 3.4 * q + vec2(8.3, 2.8)));
  return p + 0.42 * r;
}

float sdCapsule(vec2 p, float halfLength, float radius) {
  p.x -= clamp(p.x, -halfLength, halfLength);
  return length(p) - radius;
}

float fw(float d) {
#ifdef HAS_DERIVATIVES
  return max(fwidth(d), 1e-5);
#else
  return 1.6 / uUnit;
#endif
}

float fill(float d) {
  float w = fw(d) * 0.72;
  return smoothstep(w, -w, d);
}

float stroke(float d, float halfWidth) {
  float w = fw(d) * 0.8;
  return smoothstep(halfWidth + w, halfWidth - w, abs(d));
}

float capsuleHalo(vec2 p, float spread) {
  return exp(-max(0.0, sdCapsule(p, L, R)) * spread);
}

void main() {
  vec2 frag = gl_FragCoord.xy - 0.5 * uRes;
  vec2 p = frag / uUnit;
  vec2 screen = frag / max(uRes.x, uRes.y);

  float dark = uMode;
  float energy = mix(0.16, 1.0, uOn);

  vec3 accent = mix(vec3(0.09, 0.32, 0.95), vec3(0.24, 0.55, 1.0), dark);
  vec3 accentWarm = mix(vec3(0.55, 0.18, 0.86), vec3(0.62, 0.32, 1.0), dark);
  vec3 accentCool = mix(vec3(0.06, 0.62, 0.92), vec3(0.36, 0.86, 1.0), dark);
  vec3 sparkColor = mix(vec3(0.15, 0.62, 0.98), vec3(0.55, 0.86, 1.0), dark);
  vec3 dormant = mix(vec3(0.66, 0.69, 0.75), vec3(0.16, 0.19, 0.25), dark);

  vec3 skyTop = mix(vec3(0.965, 0.972, 0.984), vec3(0.055, 0.062, 0.086), dark);
  vec3 skyBottom = mix(vec3(0.886, 0.906, 0.941), vec3(0.016, 0.019, 0.031), dark);
  vec3 color = mix(skyBottom, skyTop, smoothstep(-0.55, 0.55, screen.y));

  vec2 lattice = fract(p * 1.8) - 0.5;
  float dots = smoothstep(0.09, 0.02, length(lattice));
  color += dots * mix(-0.05, 0.05, dark) * mix(vec3(0.32, 0.4, 0.62), accent, dark);

  float haloR = capsuleHalo(p * 0.985, 1.35);
  float haloG = capsuleHalo(p, 1.5);
  float haloB = capsuleHalo(p * 1.015, 1.65);
  vec3 halo = vec3(haloR, haloG, haloB) * mix(accent, accentWarm, 0.35);
  color += halo * energy * mix(0.045, 0.3, dark);

  float d = sdCapsule(p, L, R);
  float inside = fill(d);

  vec2 flowP = vec2(p.x * 0.72 - uTime * 0.3, p.y * 1.25);
  vec2 w = warp(flowP, uTime);
  float plasma = fbm(w * 1.5);
  float threads = ridged(vec2(w.x * 2.2, w.y * 3.4 + uTime * 0.16));

  float brushed = 0.5 + 0.5 * sin(p.y * 74.0 + fbm(w * 3.0) * 9.0);
  brushed *= 0.5 + 0.5 * valueNoise(vec2(p.x * 26.0, p.y * 4.0));

  float caustic = pow(abs(sin(w.x * 3.6 - uTime * 1.5 + threads * 2.4)), 9.0);

  vec2 cell = fract(p * vec2(22.0, 19.0)) - 0.5;
  float micro = stroke(length(cell) - 0.2, 0.035);

  float streak = pow(max(0.0, sin(p.x * 2.1 - uTime * 2.6 + plasma * 3.4)), 7.0);

  vec3 interior = mix(dormant, mix(accent, accentWarm, plasma * 0.42), uOn);
  interior *= mix(0.24, 0.86, plasma) * energy;
  interior += mix(accentCool, vec3(1.0), 0.25) * threads * threads * uOn * 0.15;
  interior += mix(accent, vec3(1.0), 0.35) * caustic * uOn * 0.2;
  interior += accentCool * micro * mix(0.018, 0.05, dark) * energy;
  interior *= 0.82 + 0.18 * brushed;
  interior += mix(accent, vec3(1.0), 0.35) * streak * uOn * 0.34;

  vec3 restColor = dormant * mix(0.6, 0.2, dark) * (0.72 + 0.4 * plasma);
  restColor += accentCool * micro * mix(0.02, 0.045, dark);
  restColor *= 0.88 + 0.12 * brushed;
  interior = mix(restColor, interior, uOn);

  float trough = smoothstep(-R, R * 0.35, p.y);
  interior *= mix(0.42, 1.2, trough);

  color = mix(color, interior, inside);

  color *= 1.0 - stroke(d - 0.028, 0.026) * mix(0.16, 0.3, dark);
  vec3 rimColor = mix(accent, vec3(1.0), mix(0.5, 0.28, dark));
  color += rimColor * stroke(d, 0.013) * mix(0.34, 0.66, dark) * energy;
  float bevel = stroke(d + 0.062, 0.02) * smoothstep(-0.35, 0.85, p.y / R);
  color += mix(accentCool, vec3(1.0), 0.5) * bevel * mix(0.2, 0.34, dark) * energy;
  color += rimColor * exp(-abs(d) * 18.0) * mix(0.06, 0.13, dark) * energy * inside;

  vec3 sparks = vec3(0.0);
  for (int i = 0; i < 64; i++) {
    float fi = float(i);
    vec2 h = hash21(fi + 3.7);
    float phase = hash11(fi * 7.13 + 1.7);
    float weight = hash11(fi * 3.31 + 5.9);
    float life = fract(uTime * (0.2 + h.x * 0.42) * mix(0.35, 1.0, uOn) + phase);
    float x = mix(-L - R * 0.55, L + R * 0.55, life);
    float y = (h.y - 0.5) * 1.52 * (0.32 + 0.68 * sin(life * PI)) + sin(life * 6.4 + fi) * 0.06;
    vec2 sp = p - vec2(x, y);
    sp.x *= 0.45;
    float fade = sin(life * PI);
    float grain = 1500.0 + 5200.0 * weight;
    float core = exp(-dot(sp, sp) * grain * 3.0);
    float tail = exp(-dot(sp, sp) * grain);
    float brightness = 0.35 + 0.65 * weight;
    sparks += mix(sparkColor, vec3(1.0), 0.6 * fade) * (tail * 0.55 + core) * fade * brightness;
  }
  color += sparks * mix(0.3, 1.15, uOn) * mix(0.85, 1.15, dark) * inside;

  float thumbX = mix(-L, L, uProgress);
  vec2 tp = p - vec2(thumbX, 0.0);
  float td = length(tp) - TH;
  float thumbIn = fill(td);
  vec2 disc = tp / TH;
  float discLength = min(1.0, length(disc));
  vec3 normal = normalize(vec3(disc, sqrt(max(1e-4, 1.0 - discLength * discLength))));

  vec2 shellUv = vec2(atan(normal.y, normal.x) * 1.6, normal.z * 2.4);
  float relief = valueNoise(shellUv * 15.0) * 0.6 + valueNoise(shellUv * 41.0) * 0.4;
  vec3 bumped = normalize(normal + vec3((relief - 0.5) * 0.035, (relief - 0.5) * 0.035, 0.0));

  vec3 light = normalize(vec3(-0.42 + uPointer.x * 0.35, 0.58 + uPointer.y * 0.35, 0.8));
  vec3 fillDir = normalize(vec3(0.62, -0.28, 0.55));
  vec3 rimDir = normalize(vec3(0.34, 0.5, -0.72));
  float diffuse = max(0.0, dot(bumped, light));
  float specular = pow(max(0.0, dot(reflect(-light, bumped), vec3(0.0, 0.0, 1.0))), 120.0);
  vec3 stretched = normalize(vec3(bumped.x * 0.28, bumped.y, bumped.z));
  float sheen = pow(max(0.0, dot(reflect(-light, stretched), vec3(0.0, 0.0, 1.0))), 16.0);
  float fillTerm = max(0.0, dot(bumped, fillDir));
  float rimTerm = pow(max(0.0, dot(bumped, rimDir)), 2.2) * pow(1.0 - max(0.0, normal.z), 1.6);
  float fresnel = pow(1.0 - max(0.0, normal.z), 2.6);

  vec3 thumbBase = mix(vec3(0.96, 0.97, 0.99), vec3(0.78, 0.82, 0.9), dark);
  vec3 thumbColor = thumbBase * (0.17 + 0.86 * diffuse * diffuse);
  thumbColor += thumbBase * mix(accentCool, vec3(1.0), 0.35) * fillTerm * 0.3;
  thumbColor += mix(accentCool, vec3(1.0), 0.5) * rimTerm * mix(0.3, 0.55, dark);
  thumbColor *= 0.975 + 0.05 * relief;
  thumbColor += mix(accent, accentWarm, 0.4) * fresnel * mix(0.34, 0.6, dark) * energy;
  thumbColor += vec3(1.0) * specular * 1.6;
  thumbColor += mix(vec3(1.0), accentCool, 0.35) * sheen * 0.13;
  thumbColor += mix(accent, accentWarm, 0.6) * uOn * 0.1;
  thumbColor += accentCool * smoothstep(0.2, -0.9, disc.y) * uOn * mix(0.1, 0.16, dark);
  thumbColor = thumbColor / (1.0 + thumbColor * 0.22);

  float contact = exp(-dot(tp * vec2(0.8, 1.6), tp * vec2(0.8, 1.6)) * 1.9);
  color *= 1.0 - contact * 0.42 * inside;

  color = mix(color, thumbColor, thumbIn);
  color += mix(vec3(1.0), accentCool, 0.4) * stroke(td, 0.01) * mix(0.15, 0.26, dark);
  color += mix(accent, accentWarm, 0.35) * exp(-max(0.0, td) * 7.0) * uOn * 0.22 * inside;

  color *= mix(0.86, 1.0, smoothstep(1.0, 0.2, length(screen * vec2(1.0, 1.25))));
  float grain = hash22(gl_FragCoord.xy + vec2(mod(uTime * 61.0, 512.0), mod(uTime * 37.0, 512.0)));
  color += (grain - 0.5) * mix(0.014, 0.03, dark);

  gl_FragColor = vec4(max(color, 0.0), 1.0);
}
`;

const SHADER_TRACK_HALF_LENGTH = 1.35;
const SHADER_TRACK_RADIUS = 1;
const HEIGHT_SHARE = 0.13;

function compileShader(gl: WebGLRenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Shader could not be created.");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    const log = gl.getShaderInfoLog(shader);
    gl.deleteShader(shader);
    throw new Error(`Shader failed to compile: ${log ?? "unknown error"}`);
  }
  return shader;
}

function createShaderScene(
  canvas: HTMLCanvasElement,
  mode: ToggleMode,
  speed: number,
  size: number,
  on: boolean,
): ToggleScene {
  const context = canvas.getContext("webgl", { antialias: true, alpha: false });
  if (!context) throw new Error("WebGL is unavailable.");
  const gl = context;
  const hasDerivatives = Boolean(gl.getExtension("OES_standard_derivatives"));

  const program = gl.createProgram();
  if (!program) throw new Error("Program could not be created.");
  const prefix = hasDerivatives
    ? "#extension GL_OES_standard_derivatives : enable\n#define HAS_DERIVATIVES\n"
    : "";
  const vertex = compileShader(gl, gl.VERTEX_SHADER, SHADER_VERTEX);
  const fragment = compileShader(gl, gl.FRAGMENT_SHADER, prefix + SHADER_FRAGMENT_BODY);
  gl.attachShader(program, vertex);
  gl.attachShader(program, fragment);
  gl.linkProgram(program);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
    throw new Error(`Program failed to link: ${gl.getProgramInfoLog(program) ?? "unknown error"}`);
  }
  gl.deleteShader(vertex);
  gl.deleteShader(fragment);
  gl.useProgram(program);

  const buffer = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
  const position = gl.getAttribLocation(program, "aPosition");
  gl.enableVertexAttribArray(position);
  gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);

  const uniforms = {
    res: gl.getUniformLocation(program, "uRes"),
    unit: gl.getUniformLocation(program, "uUnit"),
    time: gl.getUniformLocation(program, "uTime"),
    on: gl.getUniformLocation(program, "uOn"),
    progress: gl.getUniformLocation(program, "uProgress"),
    mode: gl.getUniformLocation(program, "uMode"),
    pointer: gl.getUniformLocation(program, "uPointer"),
  };

  const pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
  let width = 1;
  let height = 1;
  let unit = 1;
  let sizeScale = size;
  let currentMode = mode;
  let currentSpeed = speed;
  let target = on ? 1 : 0;
  let progress = target;
  let velocity = 0;
  let glow = target;
  let pointerX = 0;
  let pointerY = 0;
  let smoothX = 0;
  let smoothY = 0;
  let elapsed = 0;
  let last = performance.now();

  function layout() {
    unit =
      Math.min(
        (height * HEIGHT_SHARE) / (SHADER_TRACK_RADIUS * 2),
        (width * WIDTH_SHARE) / ((SHADER_TRACK_HALF_LENGTH + SHADER_TRACK_RADIUS) * 2),
      ) * sizeScale;
  }

  function resize(nextWidth: number, nextHeight: number) {
    width = Math.max(1, Math.round(nextWidth));
    height = Math.max(1, Math.round(nextHeight));
    canvas.width = Math.round(width * pixelRatio);
    canvas.height = Math.round(height * pixelRatio);
    canvas.style.width = `${width}px`;
    canvas.style.height = `${height}px`;
    gl.viewport(0, 0, canvas.width, canvas.height);
    layout();
  }

  function frame(now: number, still: boolean) {
    const delta = Math.min(0.05, (now - last) / 1000);
    last = now;
    if (still) {
      progress = target;
      velocity = 0;
      glow = target;
      smoothX = pointerX;
      smoothY = pointerY;
    } else {
      elapsed += delta * currentSpeed;
      const stiffness = 165;
      const damping = 2 * Math.sqrt(stiffness);
      velocity += (target - progress) * stiffness * delta - velocity * damping * delta;
      progress += velocity * delta;
      glow += (target - glow) * Math.min(1, delta * 5.5);
      smoothX += (pointerX - smoothX) * Math.min(1, delta * 3.4);
      smoothY += (pointerY - smoothY) * Math.min(1, delta * 3.4);
    }

    gl.uniform2f(uniforms.res, canvas.width, canvas.height);
    gl.uniform1f(uniforms.unit, unit * pixelRatio);
    gl.uniform1f(uniforms.time, elapsed);
    gl.uniform1f(uniforms.on, glow);
    gl.uniform1f(uniforms.progress, progress);
    gl.uniform1f(uniforms.mode, currentMode === "dark" ? 1 : 0);
    gl.uniform2f(uniforms.pointer, smoothX, smoothY);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
  }

  return {
    frame,
    setMode(next) {
      currentMode = next;
    },
    setSpeed(next) {
      currentSpeed = next;
    },
    setSize(next) {
      sizeScale = next;
      layout();
    },
    setOn(next) {
      target = next ? 1 : 0;
    },
    setPointer(x, y) {
      pointerX = x;
      pointerY = y;
    },
    resize,
    measureSwitch() {
      return {
        width: unit * (SHADER_TRACK_HALF_LENGTH + SHADER_TRACK_RADIUS) * 2,
        height: unit * SHADER_TRACK_RADIUS * 2,
      };
    },
    dispose() {
      gl.deleteBuffer(buffer);
      gl.deleteProgram(program);
    },
  };
}

/* ---------------------------------------------------------------------------
   Shared stage for the two WebGL variants.
--------------------------------------------------------------------------- */

const STAGE_TEXT = {
  light: {
    caption: "rgba(17, 22, 34, 0.5)",
    captionOn: "rgba(17, 22, 34, 0.78)",
    focus: "rgba(58, 120, 255, 0.45)",
  },
  dark: {
    caption: "rgba(233, 238, 250, 0.46)",
    captionOn: "rgba(233, 238, 250, 0.82)",
    focus: "rgba(122, 168, 255, 0.5)",
  },
} as const;

function CanvasToggle({
  kind,
  mode,
  on,
  flip,
  label,
  speed,
  size,
  still,
}: VariantProps & { kind: "glass" | "shader" }) {
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const switchRef = useRef<HTMLButtonElement>(null);
  const sceneRef = useRef<ToggleScene | null>(null);
  const [supported, setSupported] = useState(true);
  const [focused, setFocused] = useState(false);
  const text = STAGE_TEXT[mode];
  const kickRef = useFrameLoop(hostRef, sceneRef as MutableRefObject<FrameScene | null>, still);
  const initial = useRef({ mode, speed, size, on });

  const syncSwitchFootprint = useCallback(() => {
    const control = switchRef.current;
    const footprint = sceneRef.current?.measureSwitch();
    if (!control || !footprint) return;
    control.style.width = `${Math.round(footprint.width)}px`;
    control.style.height = `${Math.round(footprint.height)}px`;
  }, []);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return undefined;
    const start = initial.current;
    let scene: ToggleScene;
    try {
      scene =
        kind === "glass"
          ? createGlassScene(canvas, start.mode, clamp(start.speed, 0, 3), start.on)
          : createShaderScene(
              canvas,
              start.mode,
              clamp(start.speed, 0, 3),
              clamp(start.size, 0.35, 2.5),
              start.on,
            );
    } catch {
      setSupported(false);
      return undefined;
    }
    if (kind === "glass") scene.setSize(clamp(start.size, 0.35, 2.5));
    sceneRef.current = scene;

    const observer = new ResizeObserver((entries) => {
      const box = entries[0]?.contentRect;
      if (!box) return;
      scene.resize(box.width, box.height);
      syncSwitchFootprint();
      kickRef.current();
    });
    observer.observe(host);
    scene.resize(host.clientWidth, host.clientHeight);
    syncSwitchFootprint();
    kickRef.current();

    return () => {
      observer.disconnect();
      scene.dispose();
      sceneRef.current = null;
    };
  }, [kind, kickRef, syncSwitchFootprint]);

  useEffect(() => {
    sceneRef.current?.setMode(mode);
    kickRef.current();
  }, [mode, kickRef]);

  useEffect(() => {
    sceneRef.current?.setSpeed(clamp(speed, 0, 3));
  }, [speed]);

  useEffect(() => {
    sceneRef.current?.setSize(clamp(size, 0.35, 2.5));
    syncSwitchFootprint();
    kickRef.current();
  }, [size, syncSwitchFootprint, kickRef]);

  useEffect(() => {
    sceneRef.current?.setOn(on);
    kickRef.current();
  }, [on, kickRef]);

  const handlePointerMove = (event: PointerEvent<HTMLDivElement>) => {
    const host = hostRef.current;
    if (!host) return;
    const rect = host.getBoundingClientRect();
    const x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
    const y = ((event.clientY - rect.top) / rect.height) * 2 - 1;
    sceneRef.current?.setPointer(clamp(x, -1, 1), clamp(-y, -1, 1));
    kickRef.current();
  };

  return (
    <div
      ref={hostRef}
      className="relative box-border block h-full w-full cursor-pointer overflow-hidden"
      style={{
        isolation: "isolate",
        containerType: "size",
        background: kind === "glass" ? GLASS_STAGE[mode] : SHADER_STAGE[mode],
        colorScheme: mode,
        fontFamily: MONO_FONT,
        WebkitTapHighlightColor: "transparent",
      }}
      onPointerMove={handlePointerMove}
      onPointerLeave={() => {
        sceneRef.current?.setPointer(0, 0);
        kickRef.current();
      }}
      onClick={flip}
    >
      <canvas ref={canvasRef} className="absolute inset-0 block h-full w-full" />
      <button
        ref={switchRef}
        type="button"
        role="switch"
        aria-checked={on}
        aria-label={label}
        className="absolute left-1/2 top-1/2 h-[112px] w-[200px] -translate-x-1/2 -translate-y-1/2 cursor-pointer appearance-none rounded-full border-0 bg-transparent p-0 outline-none"
        style={{ boxShadow: focused ? `0 0 0 4px ${text.focus}` : undefined }}
        onFocus={(event) => setFocused(event.currentTarget.matches(":focus-visible"))}
        onBlur={() => setFocused(false)}
        onClick={(event) => {
          /* The whole stage is clickable, so keep the button from toggling twice. */
          event.stopPropagation();
          flip();
        }}
      />
      <p
        className="pointer-events-none absolute left-1/2 m-0 flex -translate-x-1/2 items-baseline uppercase"
        style={{
          top: "calc(50% + max(52px, 11cqh))",
          gap: "0.55em",
          fontSize: "clamp(11px, 1.9cqw, 14px)",
          letterSpacing: "0.08em",
          color: on ? text.captionOn : text.caption,
          transition: still ? "none" : "color 0.45s ease",
        }}
      >
        <span>{label}</span>
        <b className="font-medium">{on ? "On" : "Off"}</b>
      </p>
      {supported ? null : (
        <p
          className="absolute inset-0 m-0 grid place-items-center p-6 text-center text-[13px] leading-normal"
          style={{ color: text.caption }}
        >
          This variant needs WebGL, which this browser did not provide.
        </p>
      )}
    </div>
  );
}

/* ---------------------------------------------------------------------------
   Public component.
--------------------------------------------------------------------------- */

export function TactileSwitch({
  variant = "modern",
  mode = "auto",
  defaultOn = true,
  label = "Draft mode",
  speed = 1,
  size = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  onChange,
  className,
}: TactileSwitchProps) {
  const prefersReducedMotion = useReducedMotion();
  const resolvedMode = useToggleMode(mode);
  const [on, setOn] = useState(defaultOn);
  const onChangeRef = useRef(onChange);
  onChangeRef.current = onChange;

  const flip = useCallback(() => {
    setOn((current) => !current);
  }, []);

  const firstRender = useRef(true);
  useEffect(() => {
    if (firstRender.current) {
      firstRender.current = false;
      return;
    }
    onChangeRef.current?.(on);
  }, [on]);

  const shared: VariantProps = {
    mode: resolvedMode,
    on,
    flip,
    label,
    speed,
    size,
    still: Boolean(prefersReducedMotion),
  };

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      className={cn("relative h-full w-full overflow-hidden", className)}
      style={{ opacity: clamp(opacity, 0.05, 1), filter }}
    >
      {variant === "modern" ? (
        <ModernToggle {...shared} />
      ) : variant === "glass" ? (
        <CanvasToggle key="glass" kind="glass" {...shared} />
      ) : variant === "shader" ? (
        <CanvasToggle key="shader" kind="shader" {...shared} />
      ) : (
        <ClassicToggle {...shared} />
      )}
    </div>
  );
}
```

---

# Draft Form

> A turning wireframe solid inked on a drafting guide, in your theme's colours.

Install: `npx @modus-ui/cli add draft-form`

A canvas wireframe that turns in 3D over a dashed crosshair and registration circle, like a figure on a drafting sheet. Edges are drawn in the foreground ink with depth fading and the vertices are dotted in the primary colour, so it follows light and dark mode and the palette picker. Choose a nested icosahedron, a stellated cube or two interlocking cylinders. It pauses when off screen and draws a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add draft-form
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/draft-form.tsx`.
3. Paste the code.

## Usage

```tsx
import { DraftForm } from "@/components/ui/draft-form";

export default function Example() {
  return (
    <div className="flex min-h-[400px] items-center justify-center bg-background">
      <DraftForm variant="cube" />
    </div>
  );
}
```

## Props

| Prop         | Type                                | Default    | Description                                                         |
| :----------- | :---------------------------------- | :--------- | :------------------------------------------------------------------ |
| `variant`    | `"cube" \| "cylinders" \| "sphere"` | `"sphere"` | Which form to draw.                                                 |
| `speed`      | `number`                            | `1`        | Rotation speed multiplier (0 to 3).                                 |
| `size`       | `number`                            | `1`        | Line width multiplier.                                              |
| `length`     | `number`                            | `1`        | Scale of the form itself (0.35 to 2.5).                             |
| `opacity`    | `number`                            | `1`        | Opacity of the canvas.                                              |
| `hue`        | `number`                            | `0`        | Hue rotation in degrees.                                            |
| `saturation` | `number`                            | `1`        | Saturation multiplier.                                              |
| `brightness` | `number`                            | `1`        | Brightness multiplier.                                              |
| `color`      | `string`                            | none       | Any CSS colour for edges and vertices; defaults to the theme's ink. |
| `className`  | `string`                            | none       | Extra classes for the wrapper.                                      |

## Source

`components/ui/draft-form.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Wireframe Forms (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

type DraftFormVariant = "cube" | "cylinders" | "sphere";

interface DraftFormProps {
  variant?: DraftFormVariant;
  speed?: number;
  size?: number;
  length?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  color?: string;
  className?: string;
}

type Point = { x: number; y: number; z: number };

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

/** Reads a bare-HSL theme token (e.g. `--foreground`) as a canvas colour. */
function token(name: string) {
  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  return v ? `hsl(${v})` : "currentColor";
}

function buildShape(shapeType: DraftFormVariant, length: number) {
  const points: Point[] = [];
  const edges: [number, number][] = [];
  if (shapeType === "cube") {
    const s = Math.round(80 * length);
    points.push(
      { x: s, y: s, z: s },
      { x: -s, y: -s, z: s },
      { x: -s, y: s, z: -s },
      { x: s, y: -s, z: -s },
    );
    points.push(
      { x: -s, y: -s, z: -s },
      { x: s, y: s, z: -s },
      { x: s, y: -s, z: s },
      { x: -s, y: s, z: s },
    );
    edges.push([0, 1], [0, 2], [0, 3], [1, 2], [1, 3], [2, 3]);
    edges.push([4, 5], [4, 6], [4, 7], [5, 6], [5, 7], [6, 7]);
  } else if (shapeType === "cylinders") {
    const r = Math.round(70 * length);
    const segments = 24;
    for (let i = 0; i < segments; i++) {
      const theta = (i / segments) * Math.PI * 2;
      points.push({ x: Math.cos(theta) * r, y: Math.sin(theta) * r, z: -30 });
      points.push({ x: Math.cos(theta) * r, y: Math.sin(theta) * r, z: 30 });
      const next = (i + 1) % segments;
      edges.push([i * 2, next * 2], [i * 2 + 1, next * 2 + 1], [i * 2, i * 2 + 1]);
    }
    const offset = points.length;
    for (let i = 0; i < segments; i++) {
      const theta = (i / segments) * Math.PI * 2;
      points.push({ x: Math.cos(theta) * r, y: -30, z: Math.sin(theta) * r });
      points.push({ x: Math.cos(theta) * r, y: 30, z: Math.sin(theta) * r });
      const next = (i + 1) % segments;
      edges.push(
        [offset + i * 2, offset + next * 2],
        [offset + i * 2 + 1, offset + next * 2 + 1],
        [offset + i * 2, offset + i * 2 + 1],
      );
    }
  } else {
    const t = (1.0 + Math.sqrt(5.0)) / 2.0;
    const s = Math.round(50 * length);
    const p = [
      [-1, t, 0],
      [1, t, 0],
      [-1, -t, 0],
      [1, -t, 0],
      [0, -1, t],
      [0, 1, t],
      [0, -1, -t],
      [0, 1, -t],
      [t, 0, -1],
      [t, 0, 1],
      [-t, 0, -1],
      [-t, 0, 1],
    ];
    p.forEach((v) => points.push({ x: v[0] * s, y: v[1] * s, z: v[2] * s }));
    for (let i = 0; i < points.length; i++) {
      for (let j = i + 1; j < points.length; j++) {
        const d = Math.hypot(
          points[i].x - points[j].x,
          points[i].y - points[j].y,
          points[i].z - points[j].z,
        );
        if (d < s * 2.1) edges.push([i, j]);
      }
    }
    p.forEach((v) => points.push({ x: v[0] * s * 0.5, y: v[1] * s * 0.5, z: v[2] * s * 0.5 }));
    const off = 12;
    for (let i = 0; i < 12; i++) {
      for (let j = i + 1; j < 12; j++) {
        const d = Math.hypot(
          points[off + i].x - points[off + j].x,
          points[off + i].y - points[off + j].y,
          points[off + i].z - points[off + j].z,
        );
        if (d < s * 1.1) edges.push([off + i, off + j]);
      }
      edges.push([i, off + i]);
    }
  }
  return { points, edges };
}

export function DraftForm({
  variant = "sphere",
  speed = 1,
  size = 1,
  length = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  color,
  className,
}: DraftFormProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const live = useRef({ speed });
  live.current = { speed: clamp(speed, 0, 3) };

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;

    let ink = "";
    let accent = "";
    let grid = "";
    const readColors = () => {
      ink = color ?? token("--foreground");
      accent = color ?? token("--primary");
      grid = token("--border");
    };
    readColors();
    const lineAlpha = 0.55;
    const lineWidth = Number((0.8 * clamp(size, 0.05, 200)).toFixed(2));
    const { points, edges } = buildShape(variant, clamp(length, 0.35, 2.5));
    let width = 1;
    let height = 1;
    let cx = 0;
    let cy = 0;
    let angleX = 0;
    let angleY = 0;
    let raf = 0;
    let visible = true;

    const project = (p: Point) => {
      const x = p.x * Math.cos(angleY) - p.z * Math.sin(angleY);
      let z = p.z * Math.cos(angleY) + p.x * Math.sin(angleY);
      const y = p.y * Math.cos(angleX) - z * Math.sin(angleX);
      z = z * Math.cos(angleX) + p.y * Math.sin(angleX);
      const fov = 400;
      const scale = fov / (fov + z);
      return { x: x * scale + cx, y: y * scale + cy, z };
    };

    const render = () => {
      ctx.clearRect(0, 0, width, height);
      // Drafting guides: a crosshair and a registration circle behind the form.
      ctx.globalAlpha = 1;
      ctx.strokeStyle = grid;
      ctx.lineWidth = 1;
      ctx.setLineDash([3, 5]);
      ctx.beginPath();
      ctx.moveTo(cx, 12);
      ctx.lineTo(cx, height - 12);
      ctx.moveTo(12, cy);
      ctx.lineTo(width - 12, cy);
      ctx.stroke();
      ctx.setLineDash([]);
      ctx.beginPath();
      ctx.arc(cx, cy, Math.min(width, height) * 0.42, 0, Math.PI * 2);
      ctx.stroke();
      ctx.lineWidth = lineWidth;
      ctx.strokeStyle = ink;
      const projected = points.map(project);
      edges.forEach((e) => {
        const p1 = projected[e[0]];
        const p2 = projected[e[1]];
        const depth = (p1.z + p2.z) / 2;
        const alpha = Math.max(0.1, 1 - depth / 200);
        ctx.beginPath();
        ctx.moveTo(p1.x, p1.y);
        ctx.lineTo(p2.x, p2.y);
        ctx.globalAlpha = alpha * lineAlpha;
        ctx.stroke();
      });
      projected.forEach((p) => {
        const alpha = Math.max(0.1, 1 - p.z / 200);
        if (alpha > 0.5) {
          ctx.globalAlpha = alpha;
          ctx.fillStyle = accent;
          ctx.beginPath();
          ctx.arc(p.x, p.y, 2, 0, Math.PI * 2);
          ctx.fill();
        }
      });
    };

    const resize = () => {
      const rect = host.getBoundingClientRect();
      width = rect.width;
      height = rect.height;
      cx = width / 2;
      cy = height / 2;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(width * dpr));
      canvas.height = Math.max(1, Math.floor(height * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      render();
    };

    const loop = () => {
      angleY += 0.005 * live.current.speed;
      angleX += 0.002 * live.current.speed;
      render();
      raf = requestAnimationFrame(loop);
    };

    const sync = () => {
      cancelAnimationFrame(raf);
      raf = 0;
      if (!prefersReducedMotion && visible && !document.hidden) raf = requestAnimationFrame(loop);
    };

    const themeObserver = new MutationObserver(() => {
      readColors();
      render();
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette"],
    });

    const ro = new ResizeObserver(resize);
    ro.observe(host);
    resize();

    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      sync();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", sync);
    sync();

    return () => {
      cancelAnimationFrame(raf);
      ro.disconnect();
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", sync);
    };
  }, [variant, color, size, length, prefersReducedMotion]);

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      ref={hostRef}
      className={cn("relative aspect-square w-[480px] max-w-[72vw]", className)}
      style={{ opacity: clamp(opacity, 0.05, 1), filter }}
    >
      <canvas ref={canvasRef} className="absolute inset-0 h-full w-full" />
    </div>
  );
}
```

---

# Pace Dial

> A printed instrument dial with a self-test needle sweep, in speedometer, tachometer, boost and power variants.

Install: `npx @modus-ui/cli add pace-dial`

A flat, printed instrument dial set on a card: hairline ticks, italic serif numerals, a mono label and unit, a large serif readout and a slim needle and progress arc in the theme primary, with the red line drawn in the primary as well. Every colour comes from theme tokens, so it follows light and dark mode and the palette picker. When it scrolls into view it runs an instrument self-test (full-scale sweep, fall back, settle on the live reading) and repeats every eight seconds. It renders the settled reading without motion when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add pace-dial
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pace-dial.tsx`.
3. Paste the code.

## Usage

```tsx
import { PaceDial } from "@/components/ui/pace-dial";

export default function Example() {
  return (
    <div className="flex items-center justify-center p-8">
      <PaceDial variant="boost" className="max-w-[340px]" />
    </div>
  );
}
```

## Props

| Prop         | Type                                                  | Default         | Description                                   |
| :----------- | :---------------------------------------------------- | :-------------- | :-------------------------------------------- |
| `variant`    | `"tachometer" \| "speedometer" \| "boost" \| "power"` | `"speedometer"` | Which instrument to render.                   |
| `hue`        | `number`                                              | `0`             | Hue rotation applied to the dial, in degrees. |
| `saturation` | `number`                                              | `1`             | Saturation multiplier applied to the dial.    |
| `brightness` | `number`                                              | `1`             | Brightness multiplier applied to the dial.    |

## Source

`components/ui/pace-dial.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Performance Gauges (MIT, © 2026 Meng To).

import * as React from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export type PaceDialVariant = "tachometer" | "speedometer" | "boost" | "power";

export interface PaceDialProps {
  variant?: PaceDialVariant;
  hue?: number;
  saturation?: number;
  brightness?: number;
  className?: string;
}

type Zone = { from: number; to: number; color: string };
type Scale = {
  start: number;
  sweep: number;
  min: number;
  max: number;
  majorStep: number;
  minorPerMajor: number;
};
type Spec = Scale & {
  label: string;
  unit: string;
  numeral: (v: number) => string;
  hot: (v: number) => boolean;
  zones: Zone[];
  progressFrom?: number;
  idle: number;
  value: number;
  peak?: number;
  soc?: number;
  readout: (v: number) => string;
  footer: string;
  sub?: Scale & { value: number };
};

const INK = "hsl(var(--foreground))";
const MUTED = "hsl(var(--muted-foreground))";
const ACCENT = "hsl(var(--primary))";
const tone = (token: string, alpha: number) => `hsl(var(${token}) / ${alpha})`;

const SPECS: Record<PaceDialVariant, Spec> = {
  speedometer: {
    label: "Pace",
    unit: "km/h",
    start: -135,
    sweep: 270,
    min: 0,
    max: 160,
    majorStep: 20,
    minorPerMajor: 4,
    numeral: (v) => String(v),
    hot: (v) => v >= 140,
    zones: [
      { from: 0, to: 140, color: tone("--foreground", 0.12) },
      { from: 140, to: 160, color: ACCENT },
    ],
    progressFrom: 0,
    idle: 0,
    value: 118,
    peak: 143,
    readout: (v) => String(Math.round(v)),
    footer: "Odo 03159.5",
  },
  tachometer: {
    label: "Revs",
    unit: "r/min ×1000",
    start: -135,
    sweep: 270,
    min: 0,
    max: 7,
    majorStep: 1,
    minorPerMajor: 5,
    numeral: (v) => String(v),
    hot: (v) => v >= 5.5,
    zones: [
      { from: 0, to: 5.5, color: tone("--foreground", 0.12) },
      { from: 5.5, to: 7, color: ACCENT },
    ],
    idle: 0,
    value: 5.2,
    readout: (v) => v.toFixed(1),
    footer: "Temp °C",
    sub: { start: -110, sweep: 220, min: 40, max: 130, majorStep: 30, minorPerMajor: 3, value: 92 },
  },
  boost: {
    label: "Boost",
    unit: "bar",
    start: -135,
    sweep: 270,
    min: -1,
    max: 1.5,
    majorStep: 0.5,
    minorPerMajor: 5,
    numeral: (v) => v.toFixed(1),
    hot: (v) => v >= 1.2,
    zones: [
      { from: -1, to: 0, color: tone("--muted-foreground", 0.25) },
      { from: 0, to: 1.2, color: tone("--primary", 0.35) },
      { from: 1.2, to: 1.5, color: ACCENT },
    ],
    idle: -0.85,
    value: 0.92,
    readout: (v) => (v >= 0 ? "+" : "−") + Math.abs(v).toFixed(2),
    footer: "Wastegate 1.20",
  },
  power: {
    label: "Output",
    unit: "kW",
    start: -135,
    sweep: 270,
    min: -30,
    max: 120,
    majorStep: 30,
    minorPerMajor: 3,
    numeral: (v) => (v === -30 ? "CHG" : String(v)),
    hot: (v) => v < 0,
    zones: [
      { from: -30, to: 0, color: tone("--primary", 0.55) },
      { from: 0, to: 120, color: tone("--foreground", 0.12) },
    ],
    progressFrom: 0,
    idle: -22,
    value: 78,
    soc: 72,
    readout: (v) => String(Math.round(v)),
    footer: "Charge 72%",
  },
};

const angleFor = (s: Scale, value: number) =>
  s.start + ((value - s.min) / (s.max - s.min)) * s.sweep;

const arcGradient = (s: Scale, segments: Zone[]) =>
  segments
    .map((segment) => {
      const from = angleFor(s, segment.from);
      const span = ((segment.to - segment.from) / (s.max - s.min)) * s.sweep;
      return `conic-gradient(from ${from}deg, ${segment.color} 0deg, ${segment.color} ${span}deg, transparent ${span}deg)`;
    })
    .join(", ");

const BAND_MASK =
  "radial-gradient(closest-side, transparent 90%, black 90.5%, black 93%, transparent 93.5%)";
const PROGRESS_MASK =
  "radial-gradient(closest-side, transparent 76%, black 76.5%, black 78%, transparent 78.5%)";
const maskStyle = (mask: string): React.CSSProperties => ({
  WebkitMaskImage: mask,
  maskImage: mask,
});

const CSS = `
.pd-root{container-type:inline-size;position:relative;aspect-ratio:1/1;color:${INK};transition:opacity .8s cubic-bezier(.2,.8,.2,1),transform .8s cubic-bezier(.2,.8,.2,1),filter .8s}
.pd-root *,.pd-root *::before,.pd-root *::after{box-sizing:border-box}
.pd-face{position:absolute;inset:4cqw;border-radius:50%;background:radial-gradient(closest-side,hsl(var(--card)) 0%,hsl(var(--card)) 70%,color-mix(in hsl,hsl(var(--card)),hsl(var(--foreground)) 4%) 100%);border:1px solid hsl(var(--border));box-shadow:0 0 0 1.6cqw hsl(var(--background)),0 0 0 calc(1.6cqw + 1px) hsl(var(--border)),0 30px 60px -30px hsl(var(--foreground) / .35)}
.pd-layer{position:absolute;inset:0;pointer-events:none;border-radius:50%}
.pd-spoke{position:absolute;inset:0}
.pd-tick{position:absolute;left:50%;transform:translateX(-50%)}
.pd-tick.minor{top:5.6%;width:.35%;height:2.4%}
.pd-tick.major{top:5%;width:.7%;height:5.2%}
.pd-numeral{position:absolute;left:50%;top:13.5%;line-height:1;white-space:nowrap;font-variant-numeric:tabular-nums;font-style:italic}
.pd-needle{position:absolute;inset:0;transform:rotate(var(--angle,0deg));transition:transform var(--needle-duration,1200ms) var(--needle-ease,cubic-bezier(.2,.9,.25,1));will-change:transform}
.pd-flutter{position:absolute;inset:0}
.pd-blade{position:absolute;left:50%;top:9%;bottom:50%;width:.9%;transform:translateX(-50%);border-radius:999px 999px 0 0}
.pd-tail{position:absolute;left:50%;top:50%;width:.9%;height:12%;transform:translateX(-50%)}
.pd-hub{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);border-radius:50%;aspect-ratio:1}
.pd-stack{position:absolute;left:50%;transform:translateX(-50%);display:flex;flex-direction:column;align-items:center;white-space:nowrap}
.pd-cap{font-size:2.4cqw;letter-spacing:.32em;text-indent:.32em;line-height:1;text-transform:uppercase}
.pd-readout{font-size:13cqw;line-height:.9;font-variant-numeric:tabular-nums;letter-spacing:-.02em}
@keyframes pd-flutter{0%,100%{transform:rotate(-.4deg)}50%{transform:rotate(.4deg)}}
.pd-flutter[data-live]{animation:pd-flutter 2.6s ease-in-out infinite}
@keyframes pd-pulse{0%,100%{opacity:.3}50%{opacity:1}}
.pd-pulse{animation:pd-pulse 1.4s ease-in-out infinite}
.pd-still .pd-needle,.pd-still .pd-soc{transition:none!important}
.pd-still .pd-flutter,.pd-still .pd-pulse{animation:none!important}
`;

export function PaceDial({
  variant = "speedometer",
  hue = 0,
  saturation = 1,
  brightness = 1,
  className,
}: PaceDialProps) {
  const prefersReducedMotion = useReducedMotion();
  const spec = SPECS[variant] ?? SPECS.speedometer;
  const rootRef = React.useRef<HTMLDivElement>(null);

  const [revealed, setRevealed] = React.useState(false);
  const [reading, setReading] = React.useState({ value: spec.idle, duration: 1200 });
  const [readout, setReadout] = React.useState(spec.readout(spec.idle));
  const [peak, setPeak] = React.useState<number | null>(null);
  const [subValue, setSubValue] = React.useState(spec.sub?.min ?? 0);
  const [soc, setSoc] = React.useState(0);
  const [live, setLive] = React.useState(false);

  // reveal once in view, then start the instrument 500ms later
  React.useEffect(() => {
    const el = rootRef.current;
    if (!el) return;
    const io = new IntersectionObserver(
      (entries) => {
        if (entries.some((e) => e.isIntersecting)) {
          setRevealed(true);
          io.disconnect();
        }
      },
      { threshold: 0.1 },
    );
    io.observe(el);
    return () => io.disconnect();
  }, []);

  React.useEffect(() => {
    setReading({ value: spec.idle, duration: 0 });
    setReadout(spec.readout(spec.idle));
    setPeak(null);
    setSubValue(spec.sub?.min ?? 0);
    setSoc(0);
    setLive(false);
    if (!revealed) return;

    const timers: ReturnType<typeof setTimeout>[] = [];
    let raf = 0;
    let interval: ReturnType<typeof setInterval> | undefined;

    const countTo = (from: number, to: number, duration: number) => {
      cancelAnimationFrame(raf);
      if (prefersReducedMotion || duration === 0) {
        setReadout(spec.readout(to));
        return;
      }
      const started = performance.now();
      const step = (now: number) => {
        const progress = Math.min(1, (now - started) / duration);
        const eased = 1 - Math.pow(1 - progress, 3);
        setReadout(spec.readout(from + (to - from) * eased));
        if (progress < 1) raf = requestAnimationFrame(step);
      };
      raf = requestAnimationFrame(step);
    };
    const sweepTo = (value: number, duration: number) => setReading({ value, duration });

    const run = () => {
      if (spec.soc != null) setSoc(spec.soc);
      if (spec.sub) setSubValue(spec.sub.value);

      if (prefersReducedMotion) {
        sweepTo(spec.value, 0);
        countTo(spec.value, spec.value, 0);
        if (spec.peak != null) setPeak(spec.peak);
        return;
      }

      const cycle = () => {
        setLive(false);
        // instrument self-test: full-scale sweep, fall back to rest, settle on the live reading
        sweepTo(spec.max, 1100);
        countTo(spec.idle, spec.max, 1100);
        setPeak(spec.max);
        timers.push(
          setTimeout(() => {
            sweepTo(spec.idle, 900);
            countTo(spec.max, spec.idle, 900);
            setPeak(spec.idle);
          }, 1350),
          setTimeout(() => {
            sweepTo(spec.value, 1200);
            countTo(spec.idle, spec.value, 1200);
            setPeak(spec.peak ?? null);
          }, 2500),
          setTimeout(() => setLive(true), 3900),
        );
      };
      cycle();
      interval = setInterval(cycle, 8000);
    };

    timers.push(setTimeout(run, 500));
    return () => {
      timers.forEach(clearTimeout);
      if (interval) clearInterval(interval);
      cancelAnimationFrame(raf);
    };
  }, [revealed, spec, prefersReducedMotion]);

  const ticks = (s: Scale, hot: (v: number) => boolean, small = false) => {
    const step = s.majorStep / s.minorPerMajor;
    const count = Math.round((s.max - s.min) / step);
    return Array.from({ length: count + 1 }, (_, index) => {
      const value = s.min + index * step;
      const isMajor = index % s.minorPerMajor === 0;
      return (
        <div
          key={index}
          className="pd-spoke"
          style={{ transform: `rotate(${angleFor(s, value)}deg)` }}
        >
          <i
            className={cn("pd-tick", isMajor ? "major" : "minor")}
            style={{
              background: hot(value) ? ACCENT : isMajor ? INK : MUTED,
              opacity: isMajor ? 0.9 : 0.55,
              ...(small && {
                top: "10%",
                height: isMajor ? "12%" : "6%",
                width: isMajor ? "3%" : "1.6%",
              }),
            }}
          />
        </div>
      );
    });
  };

  const numerals = Array.from(
    { length: Math.round((spec.max - spec.min) / spec.majorStep) + 1 },
    (_, index) => {
      const value = Math.round((spec.min + index * spec.majorStep) * 1000) / 1000;
      const angle = angleFor(spec, value);
      return (
        <div key={index} className="pd-spoke" style={{ transform: `rotate(${angle}deg)` }}>
          <span
            className="pd-numeral font-serif"
            style={{
              fontSize: spec.numeral(value).length > 2 ? "4.4cqw" : "5.4cqw",
              color: spec.hot(value) ? ACCENT : INK,
              transform: `translateX(-50%) rotate(${-angle}deg)`,
            }}
          >
            {spec.numeral(value)}
          </span>
        </div>
      );
    },
  );

  const from = spec.progressFrom ?? spec.min;
  const progress =
    revealed && reading.value > from
      ? arcGradient(spec, [{ from, to: reading.value, color: ACCENT }])
      : undefined;
  const hotNow = spec.hot(reading.value) && revealed;

  let detail: React.ReactNode = null;
  if (spec.sub) {
    const sub = spec.sub;
    detail = (
      <div
        style={{
          position: "absolute",
          left: "50%",
          top: "80%",
          transform: "translate(-50%,-50%)",
          width: "13%",
          aspectRatio: "1",
          borderRadius: 9999,
          border: `1px solid ${tone("--border", 1)}`,
          background: tone("--background", 1),
        }}
      >
        <div className="pd-layer">{ticks(sub, (v) => v >= 115, true)}</div>
        <div
          className="pd-needle"
          style={
            {
              "--needle-duration": "1700ms",
              "--angle": `${angleFor(sub, subValue)}deg`,
            } as React.CSSProperties
          }
        >
          <i className="pd-blade" style={{ top: "16%", width: "3%", background: ACCENT }} />
        </div>
        <div className="pd-hub" style={{ width: "14%", background: INK }} />
      </div>
    );
  } else if (spec.soc != null) {
    detail = (
      <div className="pd-stack" style={{ top: "75%" }}>
        <div
          style={{
            width: "22cqw",
            height: "1.2cqw",
            borderRadius: 9999,
            background: tone("--foreground", 0.1),
            overflow: "hidden",
          }}
        >
          <div
            className="pd-soc"
            style={{
              height: "100%",
              background: ACCENT,
              transition: "width 1400ms cubic-bezier(0,0,.2,1)",
              width: `${soc}%`,
            }}
          />
        </div>
      </div>
    );
  }

  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${hue}deg) saturate(${saturation}) brightness(${brightness})`;

  return (
    <div
      ref={rootRef}
      className={cn("pd-root w-full font-sans", prefersReducedMotion && "pd-still", className)}
      style={{
        opacity: revealed ? 1 : 0,
        transform: revealed ? "translateY(0)" : "translateY(20px)",
        filter: revealed ? filter : ["blur(4px)", filter].filter(Boolean).join(" "),
        transition: prefersReducedMotion ? "none" : undefined,
      }}
    >
      <style dangerouslySetInnerHTML={{ __html: CSS }} />
      <div className="pd-face">
        <div
          className="pd-layer"
          style={{ ...maskStyle(BAND_MASK), background: arcGradient(spec, spec.zones) }}
        />
        <div className="pd-layer" style={{ ...maskStyle(PROGRESS_MASK), background: progress }} />
        <div className="pd-layer">{ticks(spec, spec.hot)}</div>
        <div className="pd-layer">{numerals}</div>
        {spec.peak != null && (
          <div
            className="pd-spoke"
            style={{
              transition: "transform 900ms cubic-bezier(.2,.9,.25,1)",
              transform: peak != null ? `rotate(${angleFor(spec, peak)}deg)` : undefined,
            }}
          >
            <i
              style={{
                position: "absolute",
                left: "50%",
                top: "1.8%",
                transform: "translateX(-50%)",
                borderLeft: "1.2cqw solid transparent",
                borderRight: "1.2cqw solid transparent",
                borderTop: `1.8cqw solid ${ACCENT}`,
              }}
            />
          </div>
        )}
        <div className="pd-stack font-mono" style={{ top: "29%" }}>
          <span className="pd-cap" style={{ color: MUTED }}>
            {spec.label}
          </span>
        </div>
        <div className="pd-stack" style={{ top: spec.sub ? "57%" : "54%" }}>
          <span className="pd-readout font-serif" style={{ color: INK }}>
            {readout}
          </span>
          <span className="pd-cap font-mono" style={{ color: ACCENT, marginTop: "1.6cqw" }}>
            {spec.unit}
          </span>
        </div>
        {detail}
        <div className="pd-stack font-mono" style={{ top: "86%" }}>
          <span
            className="pd-cap"
            style={{ color: MUTED, display: "flex", alignItems: "center", gap: "1.2cqw" }}
          >
            {variant === "boost" && hotNow && (
              <i
                className="pd-pulse"
                style={{
                  width: "1.4cqw",
                  height: "1.4cqw",
                  borderRadius: 9999,
                  background: ACCENT,
                }}
              />
            )}
            {spec.footer}
          </span>
        </div>
        <div
          className="pd-needle"
          style={
            {
              "--needle-ease": "cubic-bezier(.16,1.28,.4,1)",
              "--needle-duration": `${reading.duration}ms`,
              "--angle": `${angleFor(spec, reading.value)}deg`,
            } as React.CSSProperties
          }
        >
          <div className="pd-flutter" data-live={live ? "" : undefined}>
            <i className="pd-blade" style={{ background: ACCENT }} />
            <i className="pd-tail" style={{ background: INK }} />
          </div>
        </div>
        <div
          className="pd-hub"
          style={{ width: "5%", background: tone("--card", 1), border: `0.8cqw solid ${INK}` }}
        />
      </div>
    </div>
  );
}
```

---

# Conjure Button

> A seated paper button whose serif letters shimmer in a wave and swap to an active label on focus.

Install: `npx @modus-ui/cli add conjure-button`

A card button seated in a muted well. Its serif letters shimmer in a wave, the spark icon flickers, and on focus the letters bloom and blur into the active label, with a glow rising from the theme's primary colour. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add conjure-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/conjure-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { ConjureButton } from "@/components/ui/conjure-button";

export default function Example() {
  return <ConjureButton onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop          | Type                                   | Default       | Description                |
| :------------ | :------------------------------------- | :------------ | :------------------------- |
| `label`       | `string`                               | `"Compose"`   | Resting label.             |
| `activeLabel` | `string`                               | `"Composing"` | Label shown while focused. |
| `onClick`     | `MouseEventHandler<HTMLButtonElement>` | `undefined`   | Click handler.             |

## Source

`components/ui/conjure-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Generate Button (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface ConjureButtonProps {
  label?: string;
  activeLabel?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

const STYLES = `
.mcj-wrap { position: relative; display: inline-block; isolation: isolate; }
.mcj {
  --r: 14px; --pad: 5px; --t: .4s; --glow: hsl(var(--primary));
  position: relative; display: flex; align-items: center; gap: .6rem; padding: .7rem 1.3rem; user-select: none;
  border: 1px solid hsl(var(--border)); border-radius: var(--r); cursor: pointer; outline: none;
  color: hsl(var(--foreground)); background: hsl(var(--card));
  box-shadow: inset 0 1px 1px hsl(var(--background) / .6), inset 0 6px 10px hsl(var(--background) / .35),
    0 -2px 4px hsl(var(--foreground) / .04), 0 12px 24px -12px hsl(var(--foreground) / .35);
  transition: box-shadow var(--t), border-color var(--t), background-color var(--t);
}
.mcj::before {
  content: ""; position: absolute; inset: calc(var(--pad) * -1); z-index: -1; pointer-events: none;
  border-radius: calc(var(--r) + var(--pad)); background: hsl(var(--muted));
  box-shadow: inset 1px 1px 1px hsl(var(--background) / .7), inset -1px -1px 2px hsl(var(--foreground) / .08);
  transition: box-shadow var(--t);
}
.mcj::after {
  content: ""; position: absolute; inset: 0; border-radius: inherit; pointer-events: none; opacity: 0;
  background: linear-gradient(0deg, hsl(var(--primary) / .55), hsl(var(--primary) / .15) 45%, transparent);
  transition: opacity var(--t);
}
.mcj-letter { position: relative; display: inline-block; color: hsl(var(--muted-foreground)); animation: mcj-letter 2.4s ease-in-out infinite; }
@keyframes mcj-letter { 50% { color: hsl(var(--foreground)); text-shadow: 0 0 6px hsl(var(--primary) / .45); } }
.mcj-svg { position: relative; z-index: 1; width: 20px; height: 20px; fill: hsl(var(--primary)); animation: mcj-flicker 2s linear .5s infinite; transition: transform var(--t); }
@keyframes mcj-flicker { 50% { opacity: .35; } }
.mcj-txt { position: relative; z-index: 1; display: flex; align-items: center; min-width: 6.6em; height: 1.5em; }
.mcj-t1, .mcj-t2 { position: absolute; white-space: nowrap; }
.mcj-t2 { opacity: 0; }
.mcj:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 7px; }
.mcj:focus .mcj-t1 { animation: mcj-out .3s ease-in-out 1s forwards; }
.mcj:focus .mcj-t2 { animation: mcj-out .3s ease-in-out 1s reverse forwards; }
@keyframes mcj-out { 0% { opacity: 1; } 100% { opacity: 0; } }
.mcj:focus .mcj-letter { animation: mcj-focus 1s ease-in-out forwards, mcj-letter 1.2s ease-in-out infinite; }
@keyframes mcj-focus { 0%, 100% { filter: blur(0); } 50% { transform: scale(1.8); filter: blur(8px) drop-shadow(-30px 10px 10px hsl(var(--primary))); } }
.mcj:hover { border-color: hsl(var(--primary) / .5); }
.mcj:hover::after, .mcj:focus::after { opacity: .5; }
.mcj:hover .mcj-svg { animation: none; transform: rotate(-14deg) scale(1.1); filter: drop-shadow(0 0 4px hsl(var(--primary) / .6)); }
.mcj:active { border-color: hsl(var(--primary)); }
.mcj:active::after { opacity: 1; }
.mcj:active .mcj-letter { animation: none; color: hsl(var(--foreground)); }
.mcj[data-reduced], .mcj[data-reduced] *, .mcj[data-reduced]::before, .mcj[data-reduced]::after { animation: none !important; transition: none !important; }
`;

function Letters({ text }: { text: string }) {
  return (
    <>
      {Array.from(text).map((ch, i) => (
        <span key={i} className="mcj-letter" style={{ animationDelay: `${i * 0.08}s` }}>
          {ch === " " ? " " : ch}
        </span>
      ))}
    </>
  );
}

export function ConjureButton({
  label = "Compose",
  activeLabel = "Composing",
  onClick,
  className,
}: ConjureButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <div className={cn("mcj-wrap", className)}>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <button
        type="button"
        aria-label={label}
        title={label}
        onClick={onClick}
        data-reduced={prefersReducedMotion ? "" : undefined}
        className="mcj font-serif text-xl"
      >
        <svg className="mcj-svg" viewBox="0 0 24 24" aria-hidden="true">
          <path d="M12 2.5l1.6 5.2a3 3 0 0 0 2 2l5.2 1.6-5.2 1.6a3 3 0 0 0-2 2L12 20.1l-1.6-5.2a3 3 0 0 0-2-2L3.2 11.3l5.2-1.6a3 3 0 0 0 2-2L12 2.5Z" />
          <circle cx="19.5" cy="4.5" r="1.5" />
        </svg>
        <span className="mcj-txt">
          <span className="mcj-t1">
            <Letters text={label} />
          </span>
          <span className="mcj-t2">
            <Letters text={activeLabel} />
          </span>
        </span>
      </button>
    </div>
  );
}
```

---

# Halo Trace

> A mono pill whose hairline is traced by a slow beam of the theme's primary colour.

Install: `npx @modus-ui/cli add halo-trace`

A card-coloured pill with an uppercase mono label and a status dot. A beam of the theme's primary colour continuously traces its hairline border; on hover the beam brightens, the dot and label ink in, the pill lifts and the arrow nudges outward. It follows the active theme and palette in light and dark mode. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add halo-trace
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/halo-trace.tsx`.
4. Paste the code.

## Usage

```tsx
import { HaloTrace } from "@/components/ui/halo-trace";

export default function Example() {
  return <HaloTrace />;
}
```

## Props

| Prop        | Type                                   | Default                 | Description                         |
| :---------- | :------------------------------------- | :---------------------- | :---------------------------------- |
| `label`     | `string`                               | `"Send for review"`     | Button text.                        |
| `beamColor` | `string`                               | `"hsl(var(--primary))"` | Colour of the spinning border beam. |
| `speed`     | `number`                               | `4`                     | Seconds per beam rotation.          |
| `onClick`   | `MouseEventHandler<HTMLButtonElement>` | `undefined`             | Click handler.                      |

## Source

`components/ui/halo-trace.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Spinning Border Button (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface HaloTraceProps {
  label?: string;
  beamColor?: string;
  speed?: number;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

export function HaloTrace({
  label = "Send for review",
  beamColor = "hsl(var(--primary))",
  speed = 4,
  onClick,
  className,
}: HaloTraceProps) {
  const prefersReducedMotion = useReducedMotion();
  const t = prefersReducedMotion ? "" : "transition-all duration-300";
  return (
    <button
      type="button"
      onClick={onClick}
      className={cn(
        "group relative inline-flex items-center justify-center overflow-hidden rounded-full p-[1.5px] hover:shadow-[0_12px_30px_-12px_hsl(var(--primary)/0.5)]",
        "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[3px] focus-visible:outline-[hsl(var(--primary))]",
        !prefersReducedMotion && "transition-all duration-300 hover:-translate-y-0.5",
        className,
      )}
    >
      <span className="absolute inset-0 rounded-full bg-[hsl(var(--border))]" />
      <span
        className={cn(
          "absolute inset-[-100%] opacity-60 group-hover:opacity-100",
          t,
          !prefersReducedMotion && "animate-spin",
        )}
        style={{
          animationDuration: `${speed}s`,
          background: `conic-gradient(from 0deg at 50% 50%, transparent 0%, transparent 62%, ${beamColor} 100%)`,
        }}
      />
      <span
        className={cn(
          "relative flex h-full w-full items-center justify-center gap-2.5 rounded-full bg-[hsl(var(--card))] px-6 py-3 font-mono text-[11px] font-medium uppercase tracking-[0.2em] text-[hsl(var(--muted-foreground))] group-hover:text-foreground",
          t,
        )}
      >
        <span
          aria-hidden="true"
          className={cn(
            "h-1.5 w-1.5 rounded-full bg-[hsl(var(--primary)/0.35)] group-hover:bg-[hsl(var(--primary))]",
            t,
          )}
        />
        <span className="relative z-10">{label}</span>
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="13"
          height="13"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          strokeWidth="2"
          strokeLinecap="round"
          strokeLinejoin="round"
          className={cn("relative z-10 group-hover:translate-x-0.5", t)}
          aria-hidden="true"
        >
          <path d="M7 17 17 7" />
          <path d="M8 7h9v9" />
        </svg>
      </span>
    </button>
  );
}
```

---

# Glaze Button

> A glazed button in the theme's primary colour with a serif label and a sheen that sweeps across on hover.

Install: `npx @modus-ui/cli add glaze-button`

A glazed button poured in the theme's primary colour: lighter at the top-left, deeper at the base, with an inset highlight and a coloured drop shadow. The label is set in the serif heading face beside a mono return glyph, and a diagonal sheen sweeps across on hover. Transitions are off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add glaze-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/glaze-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { GlazeButton } from "@/components/ui/glaze-button";

export default function Example() {
  return <GlazeButton />;
}
```

## Props

| Prop      | Type                                   | Default            | Description    |
| :-------- | :------------------------------------- | :----------------- | :------------- |
| `label`   | `string`                               | `"Send the brief"` | Button text.   |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`        | Click handler. |

## Source

`components/ui/glaze-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Gradient CTA (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface GlazeButtonProps {
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

export function GlazeButton({ label = "Send the brief", onClick, className }: GlazeButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <button
      type="button"
      onClick={onClick}
      className={cn(
        "group relative overflow-hidden rounded-[10px] px-7 py-3.5 font-serif text-lg text-primary-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-2 focus-visible:ring-offset-background",
        !prefersReducedMotion &&
          "transition-[transform,box-shadow] duration-300 active:translate-y-px",
        className,
      )}
      style={{
        backgroundImage:
          "linear-gradient(160deg, color-mix(in srgb, hsl(var(--primary)) 72%, white) 0%, hsl(var(--primary)) 55%, color-mix(in srgb, hsl(var(--primary)) 78%, black) 100%)",
        boxShadow:
          "0 14px 30px -14px hsl(var(--primary) / 0.85), inset 0 1px 0 rgb(255 255 255 / 0.35), inset 0 -3px 6px rgb(0 0 0 / 0.22)",
      }}
    >
      <span
        aria-hidden
        className={cn(
          "absolute inset-y-0 -left-1/2 w-1/3 -skew-x-12 bg-[linear-gradient(90deg,transparent,rgb(255_255_255/0.35),transparent)] group-hover:left-[120%]",
          !prefersReducedMotion && "transition-[left] duration-700 ease-out",
        )}
      />
      <span className="relative flex items-center gap-3">
        {label}
        <span className="font-mono text-[10px] uppercase tracking-[0.2em] opacity-70">↵</span>
      </span>
    </button>
  );
}
```

---

# Sheen CTA

> A paper pill with a serif italic label and a sweep of primary light on hover.

Install: `npx @modus-ui/cli add sheen-cta`

A paper-card pill with a serif italic label and a primary dot. On hover it lifts and a soft band of primary light sweeps across it. Colours come from the active theme and palette. Transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add sheen-cta
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/sheen-cta.tsx`.
4. Paste the code.

## Usage

```tsx
import { SheenCta } from "@/components/ui/sheen-cta";

export default function Example() {
  return (
    <div className="h-[300px] w-full">
      <SheenCta onClick={() => console.log("clicked")} />
    </div>
  );
}
```

## Props

| Prop      | Type                                   | Default            | Description         |
| :-------- | :------------------------------------- | :----------------- | :------------------ |
| `label`   | `string`                               | `"Join the folio"` | Button text.        |
| `type`    | `"button" \| "submit" \| "reset"`      | `"button"`         | Native button type. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`        | Click handler.      |

## Source

`components/ui/sheen-cta.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Trochil Signal (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface SheenCtaProps {
  /** Button text. */
  label?: string;
  type?: "button" | "submit" | "reset";
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

/** A paper pill with a serif italic label; a band of light sweeps across it on hover. */
export function SheenCta({
  label = "Join the folio",
  type = "button",
  onClick,
  className,
}: SheenCtaProps) {
  const still = useReducedMotion();
  return (
    <div className={cn("relative grid h-full min-h-[240px] w-full place-items-center", className)}>
      <button
        type={type}
        onClick={onClick}
        className={cn(
          "group relative inline-flex h-14 items-center gap-3 overflow-hidden rounded-full border border-border bg-[hsl(var(--card))] px-8 font-serif text-lg italic text-foreground",
          "shadow-[0_1px_0_hsl(var(--background))_inset,0_12px_28px_-14px_hsl(var(--foreground)/0.35)] transition-[transform,box-shadow,border-color] duration-300",
          "hover:-translate-y-0.5 hover:border-[hsl(var(--primary)/0.6)] hover:shadow-[0_1px_0_hsl(var(--background))_inset,0_18px_36px_-14px_hsl(var(--primary)/0.45)]",
          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[hsl(var(--ring))]",
          "before:absolute before:inset-0 before:-translate-x-[120%] before:bg-[linear-gradient(105deg,transparent_20%,hsl(var(--primary)/0.22)_50%,transparent_80%)] before:transition-transform before:duration-700 hover:before:translate-x-[120%]",
          still && "transition-none before:transition-none hover:translate-y-0",
        )}
      >
        <span className="relative h-1.5 w-1.5 rounded-full bg-[hsl(var(--primary))]" aria-hidden />
        <span className="relative">{label}</span>
      </button>
    </div>
  );
}
```

---

# Kiln Button

> A glowing pill button fired from the theme's primary and destructive colours, with a coal-chip chevron.

Install: `npx @modus-ui/cli add kiln-button`

A pill whose gradient is mixed from the theme's primary and destructive tokens, so it smoulders in any palette, with a soft kiln glow behind it. It lifts and brightens on hover and presses in on click; the chevron sits in a round coal chip. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add kiln-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/kiln-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { KilnButton } from "@/components/ui/kiln-button";

export default function Example() {
  return <KilnButton onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default        | Description         |
| :-------- | :------------------------------------- | :------------- | :------------------ |
| `label`   | `string`                               | `"Fire it up"` | Button text.        |
| `type`    | `"button" \| "submit" \| "reset"`      | `"button"`     | Native button type. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`    | Click handler.      |

## Source

`components/ui/kiln-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Attune Thermal (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

const STYLES = `
.m-kiln {
  --m-kiln-hot: color-mix(in oklab, hsl(var(--primary)) 55%, hsl(var(--destructive)));
  position: relative; display: inline-flex; align-items: center; gap: 14px; height: 54px; padding: 0 10px 0 24px;
  border: 0; border-radius: 999px; cursor: pointer; white-space: nowrap; color: hsl(var(--primary-foreground));
  background: linear-gradient(180deg, color-mix(in oklab, var(--m-kiln-hot) 80%, hsl(var(--primary-foreground))) 0%, var(--m-kiln-hot) 45%, hsl(var(--primary)) 100%);
  box-shadow: inset 0 1px hsl(var(--primary-foreground) / .3), 0 0 0 1px hsl(var(--primary) / .4), 0 14px 32px -10px var(--m-kiln-hot);
  transition: transform .2s ease, box-shadow .2s ease, filter .2s ease;
}
.m-kiln::before {
  content: ""; position: absolute; inset: -18px -30px; z-index: -1; border-radius: inherit; pointer-events: none;
  background: radial-gradient(closest-side, color-mix(in srgb, var(--m-kiln-hot) 35%, transparent), transparent);
}
.m-kiln-coal { display: grid; width: 34px; height: 34px; place-items: center; border-radius: 999px; background: hsl(var(--primary-foreground) / .16); }
.m-kiln svg { width: 9px; height: 13px; fill: none; stroke: currentColor; stroke-width: 1.8; transition: transform .2s ease; }
.m-kiln:hover { transform: translateY(-2px); filter: brightness(1.08); box-shadow: inset 0 1px hsl(var(--primary-foreground) / .4), 0 0 0 1px hsl(var(--primary) / .4), 0 20px 40px -10px var(--m-kiln-hot); }
.m-kiln:hover svg { transform: translateX(2px); }
.m-kiln:active { transform: translateY(1px); }
.m-kiln:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 5px; }
.m-kiln[data-reduced], .m-kiln[data-reduced] svg { transition-duration: .01ms !important; }
`;

export interface KilnButtonProps {
  label?: string;
  type?: "button" | "submit" | "reset";
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

export function KilnButton({
  label = "Fire it up",
  type = "button",
  onClick,
  className,
}: KilnButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <button
        className={cn("m-kiln font-mono text-xs uppercase tracking-[0.2em]", className)}
        data-reduced={prefersReducedMotion ? "" : undefined}
        type={type}
        onClick={onClick}
      >
        <span>{label}</span>
        <span className="m-kiln-coal">
          <svg viewBox="0 0 12 12" aria-hidden="true">
            <path d="M3 1.5 8 6 3 10.5" />
          </svg>
        </span>
      </button>
    </>
  );
}
```

---

# Hairline CTA

> A mono, uppercase hairline button whose primary ink floods up from the baseline on hover.

Install: `npx @modus-ui/cli add hairline-cta`

A mono, uppercase hairline button with an index number and a diagonal arrow. On hover the theme's primary colour floods up from the baseline and the arrow lifts. It follows the active theme and palette, and fills its parent so it can be centred in any container. Transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add hairline-cta
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/hairline-cta.tsx`.
4. Paste the code.

## Usage

```tsx
import { HairlineCta } from "@/components/ui/hairline-cta";

export default function Example() {
  return (
    <div className="h-[300px] w-full">
      <HairlineCta onClick={() => console.log("clicked")} />
    </div>
  );
}
```

## Props

| Prop      | Type                                   | Default            | Description         |
| :-------- | :------------------------------------- | :----------------- | :------------------ |
| `label`   | `string`                               | `"Read the index"` | Button text.        |
| `type`    | `"button" \| "submit" \| "reset"`      | `"button"`         | Native button type. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`        | Click handler.      |

## Source

`components/ui/hairline-cta.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Tideform Outline (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface HairlineCtaProps {
  /** Button text. */
  label?: string;
  type?: "button" | "submit" | "reset";
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

/** A mono, uppercase hairline button whose ink floods up from the baseline on hover. */
export function HairlineCta({
  label = "Read the index",
  type = "button",
  onClick,
  className,
}: HairlineCtaProps) {
  const still = useReducedMotion();
  return (
    <div className={cn("relative grid h-full min-h-[240px] w-full place-items-center", className)}>
      <button
        type={type}
        onClick={onClick}
        className={cn(
          "group relative isolate inline-flex items-center gap-5 overflow-hidden border border-[hsl(var(--foreground)/0.35)] px-6 py-4 font-mono text-[11px] font-medium uppercase tracking-[0.22em] text-foreground",
          "transition-colors duration-300 hover:border-[hsl(var(--primary))] hover:text-[hsl(var(--primary-foreground))]",
          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[hsl(var(--ring))]",
          "before:absolute before:inset-0 before:-z-10 before:origin-bottom before:scale-y-0 before:bg-[hsl(var(--primary))] before:transition-transform before:duration-300 before:ease-[cubic-bezier(.2,.8,.2,1)] hover:before:scale-y-100",
          still && "transition-none before:transition-none",
        )}
      >
        <span className="text-[hsl(var(--muted-foreground))] transition-colors group-hover:text-[hsl(var(--primary-foreground)/0.7)]">
          01
        </span>
        <span>{label}</span>
        <svg
          viewBox="0 0 12 12"
          aria-hidden="true"
          className={cn(
            "h-3 w-3 fill-none stroke-current stroke-[1.4] transition-transform duration-300 group-hover:-translate-y-0.5 group-hover:translate-x-0.5",
            still && "transition-none",
          )}
        >
          <path d="M2 10 10 2M4 2h6v6" />
        </svg>
      </button>
    </div>
  );
}
```

---

# Halo Invite

> A card-coloured invite pill with a monogram badge and a halo of light circling its edge.

Install: `npx @modus-ui/cli add halo-invite`

An invite link in a card-coloured pill: a serif monogram badge (or a portrait), a serif label and an arrow chip that fills with ink on hover, while a halo of the theme's primary colour circles the edge. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add halo-invite
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/halo-invite.tsx`.
4. Paste the code.

## Usage

```tsx
import { HaloInvite } from "@/components/ui/halo-invite";

export default function Example() {
  return <HaloInvite href="/contact" />;
}
```

## Props

| Prop        | Type                                   | Default                | Description                                                       |
| :---------- | :------------------------------------- | :--------------------- | :---------------------------------------------------------------- |
| `label`     | `string`                               | `"Book a studio call"` | Link text.                                                        |
| `href`      | `string`                               | `"#"`                  | Link target.                                                      |
| `avatarSrc` | `string`                               | `undefined`            | Portrait for the leading badge; a monogram is drawn when omitted. |
| `avatarAlt` | `string`                               | `""`                   | Alt text for the portrait.                                        |
| `monogram`  | `string`                               | `"M"`                  | Letter for the monogram badge.                                    |
| `speed`     | `number`                               | `5`                    | Seconds per revolution of the halo.                               |
| `onClick`   | `MouseEventHandler<HTMLAnchorElement>` | `undefined`            | Click handler.                                                    |

## Source

`components/ui/halo-invite.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Glassmorphism CTA (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface HaloInviteProps {
  label?: string;
  href?: string;
  /** Portrait shown in the leading badge; a serif monogram is drawn when omitted. */
  avatarSrc?: string;
  avatarAlt?: string;
  /** Letter for the monogram badge when there is no portrait. */
  monogram?: string;
  /** Seconds per revolution of the halo. */
  speed?: number;
  onClick?: MouseEventHandler<HTMLAnchorElement>;
  className?: string;
}

const KEYFRAMES = `@keyframes m-halo-spin{to{transform:translate(-50%,-50%) rotate(360deg)}}`;

export function HaloInvite({
  label = "Book a studio call",
  href = "#",
  avatarSrc,
  avatarAlt = "",
  monogram = "M",
  speed = 5,
  onClick,
  className,
}: HaloInviteProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <a
      href={href}
      onClick={onClick}
      className={cn(
        "group relative isolate inline-flex overflow-hidden rounded-full p-px shadow-[0_14px_40px_-16px_hsl(var(--primary)/0.55)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-ring",
        !prefersReducedMotion && "transition-transform duration-300 hover:-translate-y-0.5",
        className,
      )}
    >
      <style dangerouslySetInnerHTML={{ __html: KEYFRAMES }} />
      <span aria-hidden className="absolute inset-0 bg-border" />
      <span
        aria-hidden
        className="absolute left-1/2 top-1/2 aspect-square w-[160%]"
        style={{
          transform: "translate(-50%,-50%)",
          background:
            "conic-gradient(from 0deg, transparent 0 62%, hsl(var(--primary) / 0.15) 72%, hsl(var(--primary)) 86%, transparent 90%)",
          animation: prefersReducedMotion ? undefined : `m-halo-spin ${speed}s linear infinite`,
        }}
      />
      <span className="relative z-10 flex items-center gap-3 rounded-full bg-card/95 py-2 pl-2 pr-2 text-card-foreground backdrop-blur">
        {avatarSrc ? (
          // eslint-disable-next-line @next/next/no-img-element
          <img
            src={avatarSrc}
            alt={avatarAlt}
            className="h-9 w-9 rounded-full object-cover ring-1 ring-border"
          />
        ) : (
          <span
            aria-hidden
            className="grid h-9 w-9 place-items-center rounded-full bg-primary font-serif text-lg italic text-primary-foreground"
          >
            {monogram}
          </span>
        )}
        <span className="whitespace-nowrap font-serif text-lg">{label}</span>
        <span className="ml-1 grid h-9 w-9 place-items-center rounded-full border border-border bg-muted text-foreground transition-colors group-hover:bg-primary group-hover:text-primary-foreground">
          <svg
            viewBox="0 0 24 24"
            fill="none"
            stroke="currentColor"
            strokeWidth="1.6"
            strokeLinecap="round"
            strokeLinejoin="round"
            className="h-4 w-4"
            aria-hidden="true"
          >
            <path d="M7 17 17 7M9 7h8v8" />
          </svg>
        </span>
      </span>
    </a>
  );
}
```

---

# Terrace Dusk

> Fifteen breathing terraces stepping down from left to right, cut from your theme's tones.

Install: `npx @modus-ui/cli add terrace-dusk`

A full-bleed Three.js shader of fifteen grained bars that step down from left to right and breathe on a slow pulse. The bars are a lightness ramp on the theme's primary hue and the ground above them is the theme background, so it reads as ink terraces on paper in light mode and as dusk in dark mode, following the palette picker. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add terrace-dusk
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/terrace-dusk.tsx`.
4. Paste the code.

## Usage

```tsx
import { TerraceDusk } from "@/components/ui/terrace-dusk";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <TerraceDusk />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                            |
| :---------------- | :------- | :------------------------- | :------------------------------------- |
| `hue`             | `number` | `0`                        | Hue rotation in degrees (-180 to 180). |
| `saturation`      | `number` | `1`                        | Saturation multiplier (0 to 2).        |
| `brightness`      | `number` | `1`                        | Brightness multiplier (0.35 to 1.65).  |
| `baseColor`       | `string` | theme primary, deep        | Colour of the bars at the bottom.      |
| `startColor`      | `string` | theme primary, light       | Gradient colour on the left side.      |
| `endColor`        | `string` | theme primary              | Gradient colour on the right side.     |
| `horizonColor`    | `string` | theme background           | Colour above the stepped horizon.      |
| `backgroundColor` | `string` | `"hsl(var(--background))"` | Colour behind the canvas.              |

## Source

`components/ui/terrace-dusk.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Expanse Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

interface TerraceDuskProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the bars at the bottom. */
  baseColor?: string;
  /** Gradient colour on the left side; defaults to a theme tone. */
  startColor?: string;
  /** Gradient colour on the right side; defaults to a theme tone. */
  endColor?: string;
  /** Colour above the stepped horizon. */
  horizonColor?: string;
  /** Colour behind the canvas; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

const vertexShader = /* glsl */ `
  void main() {
    gl_Position = vec4(position, 1.0);
  }
`;

const fragmentShader = /* glsl */ `
  uniform vec2 u_resolution;
  uniform float u_time;
  uniform vec3 u_base;
  uniform vec3 u_start;
  uniform vec3 u_end;
  uniform vec3 u_horizon;

  float random(vec2 st) {
    return fract(sin(dot(st.xy, vec2(12.9898,78.233))) * 43758.5453123);
  }

  void main() {
    vec2 st = gl_FragCoord.xy / u_resolution.xy;
    float numBars = 15.0;
    float barIndex = floor(st.x * numBars);
    float t = 1.0 - barIndex / (numBars - 1.0);

    // Breathing pulse animation
    float anim = sin(u_time * 0.5 + t * 3.0) * 0.025;

    // Curve for horizon line
    float targetHeight = 0.12 + pow(t, 1.6) * 0.62 + anim;

    vec3 colorBase = u_base;
    vec3 colorMid = mix(u_start, u_end, st.x);
    vec3 color = mix(colorBase, colorMid, smoothstep(0.1, 0.7, st.y));

    // Stepped horizon cutoff
    if (st.y > targetHeight) {
      gl_FragColor = vec4(u_horizon, 1.0);
      return;
    }

    // High-frequency film grain
    float noise = random(st * (u_time * 0.1)) * 0.08;
    gl_FragColor = vec4(color + noise, 1.0);
  }
`;

export function TerraceDusk({
  hue = 0,
  saturation = 1,
  brightness = 1,
  baseColor,
  startColor,
  endColor,
  horizonColor,
  backgroundColor = "hsl(var(--background))",
  className,
}: TerraceDuskProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const theme = useThemeVersion();

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return;

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: false });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    host.appendChild(renderer.domElement);

    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
    const scene = new THREE.Scene();
    const geometry = new THREE.PlaneGeometry(2, 2);
    // The shader writes raw values; colours are passed in the same space.
    const raw = (color: string) => new THREE.Color(color).convertLinearToSRGB();
    // Terraces are a lightness ramp on the primary hue, cut out of the theme ground.
    const { dark, primary, background } = readTheme();
    const [h, s] = primary;
    const sat = Math.max(s, 34);
    const uniforms = {
      u_time: { value: 0 },
      u_resolution: { value: new THREE.Vector2() },
      u_base: { value: raw(baseColor ?? hsl([h, sat, dark ? 10 : 18])) },
      u_start: { value: raw(startColor ?? hsl([h - 26, sat + 10, dark ? 62 : 42])) },
      u_end: { value: raw(endColor ?? hsl([h, sat, dark ? 36 : 34])) },
      u_horizon: { value: raw(horizonColor ?? hsl(background)) },
    };
    const material = new THREE.ShaderMaterial({
      uniforms,
      vertexShader,
      fragmentShader,
      transparent: true,
    });
    scene.add(new THREE.Mesh(geometry, material));

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      renderer.setSize(width, height, false);
      // CSS pixels, exactly as the original.
      uniforms.u_resolution.value.set(width, height);
    };
    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);

    let frame = 0;
    let visible = true;
    const render = (time: number) => {
      uniforms.u_time.value = time * 0.001;
      renderer.render(scene, camera);
    };
    const loop = (time: number) => {
      render(time);
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) render(1000);
      else if (visible && !document.hidden) frame = requestAnimationFrame(loop);
    };
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, baseColor, startColor, endColor, horizonColor, theme]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor, filter }}
    />
  );
}
```

---

# Circuit Heart

> An isometric Three.js platform with a pulsing core and orbiting nodes, lit from your theme.

Install: `npx @modus-ui/cli add circuit-heart`

An orthographic, isometric Three.js scene: a platform on a theme surface with a glowing core in the palette's primary whose pulse lights the cubes orbiting around it, set on the page ground. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add circuit-heart
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/circuit-heart.tsx`.
4. Paste the code.

## Usage

```tsx
import { CircuitHeart } from "@/components/ui/circuit-heart";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <CircuitHeart />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                        | Description                                            |
| :---------------- | :------- | :----------------------------- | :----------------------------------------------------- |
| `hue`             | `number` | `0`                            | Hue rotation in degrees (-180 to 180).                 |
| `saturation`      | `number` | `1`                            | Saturation multiplier (0 to 2).                        |
| `brightness`      | `number` | `1`                            | Brightness multiplier (0.35 to 1.65).                  |
| `accentColor`     | `string` | `hsl(var(--primary))`          | Glow colour of the core, accent nodes and point light. |
| `platformColor`   | `string` | `hsl(var(--card))`             | Colour of the base disc.                               |
| `nodeColor`       | `string` | `hsl(var(--muted-foreground))` | Colour of the non-accent orbiting nodes.               |
| `backgroundColor` | `string` | `hsl(var(--background))`       | Colour behind the effect.                              |

## Source

`components/ui/circuit-heart.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Logic Core (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface CircuitHeartProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Glow colour of the core, accent nodes and point light; defaults to the theme primary. */
  accentColor?: string;
  /** Colour of the base disc; defaults to the theme card. */
  platformColor?: string;
  /** Colour of the non-accent orbiting nodes; defaults to the theme muted ink. */
  nodeColor?: string;
  /** Colour behind the effect; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// The original ran on three r136 without colour management: hex values are used as-is.
const raw = (value: string | number) => new THREE.Color(value).convertLinearToSRGB();

export function CircuitHeart({
  hue = 0,
  saturation = 1,
  brightness = 1,
  accentColor,
  platformColor,
  nodeColor,
  backgroundColor,
  className,
}: CircuitHeartProps) {
  const prefersReducedMotion = useReducedMotion();
  const themeVersion = useThemeVersion();
  const hostRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const container = hostRef.current;
    if (!container) return;

    const theme = readTheme();
    const [ph, ps, pl] = theme.primary;
    const accent =
      accentColor ??
      hsl([ph, Math.max(ps, 45), theme.dark ? Math.max(pl, 58) : Math.min(Math.max(pl, 38), 48)]);
    const platformTone =
      platformColor ??
      hsl([
        theme.background[0],
        theme.background[1],
        theme.dark ? theme.background[2] + 7 : theme.background[2] - 6,
      ]);
    const nodeTone = nodeColor ?? hsl(theme.muted);
    const edgeTone = hsl(theme.foreground);

    const scene = new THREE.Scene();
    const d = 12; // Camera frustum size
    const aspect = Math.max(1, container.clientWidth) / Math.max(1, container.clientHeight);
    const camera = new THREE.OrthographicCamera(-d * aspect, d * aspect, d, -d, 1, 1000);
    camera.position.set(-22, 11, 18); // Low three-quarter view
    camera.lookAt(0, 0, 0);

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    container.appendChild(renderer.domElement);

    const group = new THREE.Group();
    scene.add(group);

    const disposables: { dispose: () => void }[] = [];
    const track = <T extends { dispose: () => void }>(item: T) => {
      disposables.push(item);
      return item;
    };

    const basePlatformMat = track(
      new THREE.MeshStandardMaterial({ color: raw(platformTone), roughness: 0.9, metalness: 0.1 }),
    );
    const coreEmissiveMat = track(
      new THREE.MeshStandardMaterial({
        color: raw(accent),
        emissive: raw(accent),
        emissiveIntensity: 0.5,
        roughness: 0.2,
      }),
    );
    const wireframeMat = track(
      new THREE.LineBasicMaterial({ color: raw(edgeTone), transparent: true, opacity: 0.35 }),
    );

    const platformGeo = track(new THREE.CylinderGeometry(9, 9, 0.4, 64));
    const platform = new THREE.Mesh(platformGeo, basePlatformMat);
    platform.position.y = -2;
    group.add(platform);
    platform.add(
      new THREE.LineSegments(track(new THREE.EdgesGeometry(platformGeo, 30)), wireframeMat),
    );

    const coreGeo = track(new THREE.CylinderGeometry(1.1, 1.1, 4.5, 6));
    const core = new THREE.Mesh(coreGeo, coreEmissiveMat);
    core.position.y = 0.25;
    group.add(core);

    type NodeData = {
      angle: number;
      radius: number;
      speed: number;
      yBase: number;
      yOffset: number;
    };
    const nodes: { mesh: THREE.Mesh; data: NodeData }[] = [];
    const nodeCount = 16;
    const nodeEdgeMat = track(
      new THREE.LineBasicMaterial({ color: raw(edgeTone), transparent: true, opacity: 0.45 }),
    );
    for (let i = 0; i < nodeCount; i++) {
      const isAccent = Math.random() > 0.7;
      const nodeMat = isAccent
        ? coreEmissiveMat
        : track(new THREE.MeshStandardMaterial({ color: raw(nodeTone), roughness: 0.8 }));
      const size = 0.4 + Math.random() * 0.4;
      const nodeGeo = track(new THREE.OctahedronGeometry(size * 0.75));
      const node = new THREE.Mesh(nodeGeo, nodeMat);

      const angle = (i / nodeCount) * Math.PI * 2;
      const radius = 4 + Math.random() * 4;
      node.position.set(Math.cos(angle) * radius, -1 + Math.random() * 4, Math.sin(angle) * radius);
      node.add(new THREE.LineSegments(track(new THREE.EdgesGeometry(nodeGeo)), nodeEdgeMat));

      nodes.push({
        mesh: node,
        data: {
          angle,
          radius,
          speed: 0.005 + Math.random() * 0.015,
          yBase: node.position.y,
          yOffset: Math.random() * Math.PI * 2,
        },
      });
      group.add(node);
    }

    // Legacy (pre-r155) light intensities scaled by PI to keep the original look.
    scene.add(new THREE.AmbientLight(raw(hsl([0, 0, 100])), 0.45 * Math.PI));
    const dirLight = new THREE.DirectionalLight(raw(hsl([0, 0, 100])), 0.6 * Math.PI);
    dirLight.position.set(10, 20, 5);
    scene.add(dirLight);
    const pointLight = new THREE.PointLight(raw(accent), 1.5 * Math.PI, 25, 0);
    pointLight.position.set(0, 1, 0);
    scene.add(pointLight);

    let time = 0;
    const step = () => {
      time += 0.016;
      group.rotation.y = Math.sin(time * 0.1) * 0.15;
      group.position.y = Math.sin(time * 0.5) * 0.2;

      const pulse = (Math.sin(time * 2.5) + 1) * 0.5;
      coreEmissiveMat.emissiveIntensity = 0.4 + pulse * 0.6;
      pointLight.intensity = (1.0 + pulse * 1.5) * Math.PI;

      nodes.forEach(({ mesh, data }) => {
        data.angle += data.speed;
        mesh.position.x = Math.cos(data.angle) * data.radius;
        mesh.position.z = Math.sin(data.angle) * data.radius;
        mesh.position.y = data.yBase + Math.sin(time * 1.5 + data.yOffset) * 0.5;
        mesh.rotation.x += 0.01;
        mesh.rotation.y += 0.02;
      });
      renderer.render(scene, camera);
    };

    const resize = () => {
      const width = Math.max(1, container.clientWidth);
      const height = Math.max(1, container.clientHeight);
      const newAspect = width / height;
      camera.left = -d * newAspect;
      camera.right = d * newAspect;
      camera.top = d;
      camera.bottom = -d;
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);
      if (prefersReducedMotion) renderer.render(scene, camera);
    };
    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(container);

    let frame = 0;
    let visible = true;
    const loop = () => {
      step();
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) step();
      else if (visible && !document.hidden) frame = requestAnimationFrame(loop);
    };
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(container);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      disposables.forEach((item) => item.dispose());
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, accentColor, platformColor, nodeColor, themeVersion]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    />
  );
}
```

---

# Lens Drift

> Soft noise-driven bands of theme colour drifting behind a trail of glass lenses that follow the pointer.

Install: `npx @modus-ui/cli add lens-drift`

A Three.js scene of soft simplex-noise bands seen through a trail of glass lenses: one large lens low on the left and smaller ones rising to the right, each with a fresnel rim. The ground, lens tint and bands come from the active theme, so it is a pale study on paper in light mode and a dim one in dark mode, and follows the palette. The camera eases toward the pointer. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add lens-drift
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/lens-drift.tsx`.
4. Paste the code.

## Usage

```tsx
import { LensDrift } from "@/components/ui/lens-drift";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <LensDrift />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                              |
| :---------------- | :------- | :------------------- | :------------------------------------------------------- |
| `hue`             | `number` | `0`                  | Hue rotation in degrees (-180 to 180).                   |
| `saturation`      | `number` | `1`                  | Saturation multiplier (0 to 2).                          |
| `brightness`      | `number` | `1`                  | Brightness multiplier (0.35 to 1.65).                    |
| `primaryColor`    | `string` | `--primary`          | First beam colour (theme token by default).              |
| `secondaryColor`  | `string` | `--muted-foreground` | Second beam colour (theme token by default).             |
| `backgroundColor` | `string` | `--background`       | Ground colour behind the beams (theme token by default). |

## Source

`components/ui/lens-drift.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Dimensional Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

export interface LensDriftProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** First beam colour. Defaults to the theme's `--primary`. */
  primaryColor?: string;
  /** Second beam colour. Defaults to the theme's `--muted-foreground`. */
  secondaryColor?: string;
  /** Ground colour behind the beams. Defaults to the theme's `--background`. */
  backgroundColor?: string;
  className?: string;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// The original shaders write raw colour values (three r128, no colour management).
const raw = (value: string) => new THREE.Color(value).convertLinearToSRGB();

const snoiseLogic = /* glsl */ `
  vec3 permute(vec3 x) { return mod(((x*34.0)+1.0)*x, 289.0); }
  float snoise(vec2 v){
    const vec4 C = vec4(0.211324865405187, 0.366025403784439, -0.577350269189626, 0.024390243902439);
    vec2 i  = floor(v + dot(v, C.yy) );
    vec2 x0 = v -   i + dot(i, C.xx);
    vec2 i1;
    i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
    vec4 x12 = x0.xyxy + C.xxzz;
    x12.xy -= i1;
    i = mod(i, 289.0);
    vec3 p = permute( permute( i.y + vec3(0.0, i1.y, 1.0 )) + i.x + vec3(0.0, i1.x, 1.0 ));
    vec3 m = max(0.5 - vec3(dot(x0,x0), dot(x12.xy,x12.xy), dot(x12.zw,x12.zw)), 0.0);
    m = m*m ; m = m*m ;
    vec3 x = 2.0 * fract(p * C.www) - 1.0;
    vec3 h = abs(x) - 0.5;
    vec3 ox = floor(x + 0.5);
    vec3 a0 = x - ox;
    m *= 1.79284291400159 - 0.85373472095314 * ( a0*a0 + h*h );
    vec3 g;
    g.x  = a0.x  * x0.x  + h.x  * x0.y;
    g.yz = a0.yz * x12.xz + h.yz * x12.yw;
    return 130.0 * dot(m, g);
  }
`;

const bgFragment = /* glsl */ `
  uniform float u_time;
  uniform vec2 u_resolution;
  uniform vec3 u_color1;
  uniform vec3 u_color2;
  uniform vec3 u_base;
  uniform vec3 u_lens;
  ${snoiseLogic}
  void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution.xy;
    uv.x *= u_resolution.x / u_resolution.y;

    vec3 baseColor = u_base;
    vec2 st = uv * 0.5;
    st += vec2(snoise(st + u_time * 0.04), snoise(st - u_time * 0.04)) * 0.4;

    float beam = smoothstep(0.2, 0.9, snoise(vec2(st.x + st.y * 2.0 - u_time * 0.1, u_time * 0.03)));
    vec3 glow = mix(u_color1, u_color2, snoise(uv * 2.0 + u_time * 0.15) * 0.5 + 0.5);

    float dist = distance(gl_FragCoord.xy / u_resolution.xy, vec2(0.5));
    float vignette = smoothstep(1.5, 0.1, dist);

    vec3 edgeColor = u_base;
    vec3 colorGlow = mix(baseColor, glow, beam * 0.45);

    gl_FragColor = vec4(mix(edgeColor, colorGlow, vignette), 1.0);
  }
`;

const glassVertex = /* glsl */ `
  varying vec3 vNormal;
  void main() {
    vNormal = normalize(normalMatrix * normal);
    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
  }
`;

const glassFragment = /* glsl */ `
  uniform float u_time;
  uniform vec2 u_resolution;
  uniform vec3 u_color1;
  uniform vec3 u_color2;
  uniform vec3 u_base;
  uniform vec3 u_lens;
  varying vec3 vNormal;
  ${snoiseLogic}
  void main() {
    vec2 uv = gl_FragCoord.xy / u_resolution.xy;
    uv += vNormal.xy * 0.2;
    uv.x *= u_resolution.x / u_resolution.y;

    vec3 baseColor = u_lens;
    vec2 st = uv * 0.6;
    st += vec2(snoise(st + u_time * 0.06), snoise(st - u_time * 0.06)) * 0.35;

    float beam = smoothstep(0.1, 0.9, snoise(vec2(st.x + st.y * 1.8 - u_time * 0.12, u_time * 0.02)));
    vec3 glow = mix(u_color1, u_color2, snoise(uv * 1.8 + u_time * 0.12) * 0.5 + 0.5);

    float fresnel = dot(vec3(0.0, 0.0, 1.0), vNormal);
    fresnel = clamp(1.0 - fresnel, 0.0, 1.0);
    fresnel = pow(fresnel, 2.5);

    vec3 finalColor = mix(baseColor, glow, clamp((beam * 0.5) + (fresnel * 0.8), 0.0, 1.0));
    gl_FragColor = vec4(finalColor, 0.95);
  }
`;

// A single large lens low on the left, with a loose trail of smaller ones rising to the right.
const SPHERES = [
  { scale: 3.4, x: -5.2, y: -2.2, z: 0, speed: 0.002 },
  { scale: 1.5, x: 1.2, y: 0.6, z: 1.5, speed: 0.004 },
  { scale: 0.95, x: 5.0, y: 2.6, z: 2.5, speed: 0.005 },
  { scale: 0.55, x: 7.6, y: 4.4, z: 3.5, speed: 0.008 },
];

export function LensDrift({
  hue = 0,
  saturation = 1,
  brightness = 1,
  primaryColor,
  secondaryColor,
  backgroundColor,
  className,
}: LensDriftProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const tokens = useTokens();
  const color1 = primaryColor ?? tokens?.primary;
  const color2 = secondaryColor ?? tokens?.muted;
  const ground = backgroundColor ?? tokens?.background;
  const lens = tokens?.card;

  useEffect(() => {
    const host = hostRef.current;
    if (!host || !color1 || !color2 || !ground || !lens) return;

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: false });
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    host.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100);
    camera.position.z = 12;

    const uniforms = {
      u_time: { value: 0 },
      u_resolution: { value: new THREE.Vector2() },
      u_color1: { value: raw(color1) },
      u_color2: { value: raw(color2) },
      u_base: { value: raw(ground) },
      u_lens: { value: raw(lens) },
    };

    const bgGeometry = new THREE.PlaneGeometry(2, 2);
    const bgMaterial = new THREE.ShaderMaterial({
      vertexShader: `void main() { gl_Position = vec4(position, 1.0); }`,
      fragmentShader: bgFragment,
      uniforms,
      depthWrite: false,
      depthTest: false,
    });
    const bgMesh = new THREE.Mesh(bgGeometry, bgMaterial);
    bgMesh.position.z = -15;
    scene.add(bgMesh);

    const glassMaterial = new THREE.ShaderMaterial({
      vertexShader: glassVertex,
      fragmentShader: glassFragment,
      uniforms,
      transparent: true,
    });
    const sphereGeo = new THREE.SphereGeometry(1, 64, 64);
    const spheres = SPHERES.map((data) => {
      const mesh = new THREE.Mesh(sphereGeo, glassMaterial);
      mesh.scale.set(data.scale, data.scale, data.scale);
      mesh.position.set(data.x, data.y, data.z);
      scene.add(mesh);
      return { mesh, baseY: data.y, speed: data.speed, offset: Math.random() * Math.PI * 2 };
    });

    // Mouse offset from the host centre, like the original's offset from the window centre.
    let mouseX = 0;
    let mouseY = 0;
    const onPointerMove = (event: PointerEvent) => {
      const rect = host.getBoundingClientRect();
      mouseX = event.clientX - (rect.left + rect.width / 2);
      mouseY = event.clientY - (rect.top + rect.height / 2);
    };
    window.addEventListener("pointermove", onPointerMove);

    const render = (time: number) => {
      uniforms.u_time.value = time;
      camera.position.x += (mouseX * 0.005 - camera.position.x) * 0.05;
      camera.position.y += (-mouseY * 0.005 - camera.position.y) * 0.05;
      camera.lookAt(scene.position);
      spheres.forEach((s) => {
        s.mesh.position.y = s.baseY + Math.sin(time * s.speed * 120 + s.offset) * 0.5;
        s.mesh.rotation.x = time * s.speed * 18;
        s.mesh.rotation.y = time * s.speed * 24;
      });
      renderer.render(scene, camera);
    };

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      renderer.setSize(width, height, false);
      camera.aspect = width / height;
      camera.updateProjectionMatrix();
      const dist = camera.position.z - bgMesh.position.z;
      const vFov = (camera.fov * Math.PI) / 180;
      const planeHeight = 2 * Math.tan(vFov / 2) * dist;
      bgMesh.scale.set((planeHeight * camera.aspect) / 2, planeHeight / 2, 1);
      // CSS pixels, exactly as the original (gl_FragCoord spans more on high-DPR screens).
      uniforms.u_resolution.value.set(width, height);
      if (prefersReducedMotion) render(elapsed);
    };

    let elapsed = 0;
    let last = performance.now();
    let frame = 0;
    let visible = true;
    const loop = (now: number) => {
      elapsed += (now - last) / 1000;
      last = now;
      render(elapsed);
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) render(elapsed);
      else if (visible && !document.hidden) {
        last = performance.now();
        frame = requestAnimationFrame(loop);
      }
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      window.removeEventListener("pointermove", onPointerMove);
      bgGeometry.dispose();
      bgMaterial.dispose();
      sphereGeo.dispose();
      glassMaterial.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, color1, color2, ground, lens]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    />
  );
}
```

---

# Thread Swell

> A curtain of Three.js threads that swell in rolling waves, inked in the active theme colours.

Install: `npx @modus-ui/cli add thread-swell`

Forty-six Three.js threads hang like a curtain seen from below, swelling in two layered waves and fading from the primary colour to the muted ink colour. On a dark theme the threads glow additively; on paper they are drawn as ink, and both follow the active palette. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add thread-swell
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/thread-swell.tsx`.
4. Paste the code.

## Usage

```tsx
import { ThreadSwell } from "@/components/ui/thread-swell";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ThreadSwell />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default              | Description                                          |
| :---------------- | :------- | :------------------- | :--------------------------------------------------- |
| `hue`             | `number` | `0`                  | Hue rotation in degrees (-180 to 180).               |
| `saturation`      | `number` | `1`                  | Saturation multiplier (0 to 2).                      |
| `brightness`      | `number` | `1`                  | Brightness multiplier (0.35 to 1.65).                |
| `startColor`      | `string` | `--primary`          | Colour of the first thread (theme token by default). |
| `endColor`        | `string` | `--muted-foreground` | Colour of the last thread (theme token by default).  |
| `backgroundColor` | `string` | `--background`       | Colour behind the threads (theme token by default).  |

## Source

`components/ui/thread-swell.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Data Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

type Tokens = {
  primary: string;
  foreground: string;
  muted: string;
  background: string;
  card: string;
  border: string;
  dark: boolean;
};

/** Reads the Modus theme tokens (bare HSL channels) as comma `hsl()` strings canvas and three.js both parse. */
function readTokens(): Tokens {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const hsl = (name: string) =>
    `hsl(${cs
      .getPropertyValue(name)
      .trim()
      .split(/[\s,]+/)
      .filter(Boolean)
      .join(", ")})`;
  return {
    primary: hsl("--primary"),
    foreground: hsl("--foreground"),
    muted: hsl("--muted-foreground"),
    background: hsl("--background"),
    card: hsl("--card"),
    border: hsl("--border"),
    dark: root.classList.contains("dark") || root.dataset.theme === "dark",
  };
}

/** The current theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTokens() {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const update = () => setTokens(readTokens());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

export interface ThreadSwellProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the first thread. Defaults to the theme's `--primary`. */
  startColor?: string;
  /** Colour of the last thread. Defaults to the theme's `--muted-foreground`. */
  endColor?: string;
  /** Colour behind the threads. Defaults to the theme's `--background`. */
  backgroundColor?: string;
  className?: string;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// The original ran on three r128 without colour management: hex values are used as-is.
const raw = (value: string) => new THREE.Color(value).convertLinearToSRGB();

export function ThreadSwell({
  hue = 0,
  saturation = 1,
  brightness = 1,
  startColor,
  endColor,
  backgroundColor,
  className,
}: ThreadSwellProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const tokens = useTokens();
  const from = startColor ?? tokens?.primary;
  const to = endColor ?? tokens?.muted;
  // Additive light only reads on a dark ground; on paper the threads are drawn as ink.
  const additive = tokens?.dark ?? true;

  useEffect(() => {
    const container = hostRef.current;
    if (!container || !from || !to) return;

    const scene = new THREE.Scene();
    const camera = new THREE.PerspectiveCamera(55, 1, 0.1, 100);
    camera.position.set(0, -6, 8);
    camera.lookAt(0, 0, 0);

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    container.appendChild(renderer.domElement);

    const group = new THREE.Group();
    scene.add(group);

    const numLines = 46;
    const pointsPerLine = 100;
    const colorStart = raw(from);
    const colorEnd = raw(to);
    const lines: THREE.Line<THREE.BufferGeometry, THREE.LineBasicMaterial>[] = [];

    for (let i = 0; i < numLines; i++) {
      const points: THREE.Vector3[] = [];
      const xPos = (i - numLines / 2) * 0.3;
      for (let j = 0; j < pointsPerLine; j++) {
        const yPos = (j - pointsPerLine / 2) * 0.2;
        points.push(new THREE.Vector3(xPos, yPos, 0));
      }
      const geometry = new THREE.BufferGeometry().setFromPoints(points);
      const color = new THREE.Color().lerpColors(colorStart, colorEnd, i / numLines);
      const material = new THREE.LineBasicMaterial({
        color,
        transparent: true,
        opacity: (additive ? 0.2 : 0.3) + Math.random() * 0.4,
        blending: additive ? THREE.AdditiveBlending : THREE.NormalBlending,
      });
      const line = new THREE.Line(geometry, material);
      group.add(line);
      lines.push(line);
    }

    // Tilt to create a flowing plane
    group.rotation.x = Math.PI / 2.6;
    group.rotation.z = Math.PI / 9;

    const render = (seconds: number) => {
      const time = seconds * 0.4; // Slower, more relaxed pace
      lines.forEach((line) => {
        const attribute = line.geometry.attributes.position as THREE.BufferAttribute;
        const positions = attribute.array as Float32Array;
        for (let j = 0; j < pointsPerLine; j++) {
          const idx = j * 3;
          const x = positions[idx];
          const y = positions[idx + 1];
          // Smooth, rolling, gentle waves reminiscent of water or silk
          const wave1 = Math.sin(y * 1.2 + time + x * 0.8) * 0.8;
          const wave2 = Math.cos(x * 1.5 - time * 0.8 + y * 0.5) * 0.6;
          positions[idx + 2] = wave1 + wave2;
        }
        attribute.needsUpdate = true;
      });
      renderer.render(scene, camera);
    };

    let elapsed = 0;
    let last = performance.now();
    let frame = 0;
    let visible = true;

    const resize = () => {
      const width = Math.max(1, container.clientWidth);
      const height = Math.max(1, container.clientHeight);
      camera.aspect = width / height;
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);
      if (prefersReducedMotion) render(elapsed);
    };

    const loop = (now: number) => {
      elapsed += (now - last) / 1000;
      last = now;
      render(elapsed);
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) render(elapsed);
      else if (visible && !document.hidden) {
        last = performance.now();
        frame = requestAnimationFrame(loop);
      }
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(container);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(container);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      lines.forEach((line) => {
        line.geometry.dispose();
        line.material.dispose();
      });
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, from, to, additive]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    />
  );
}
```

---

# Relief Mesh

> A slowly turning mesh globe of pulsing nodes joined by fine links, inked in theme tokens and fading into the page background.

Install: `npx @modus-ui/cli add relief-mesh`

A slowly turning mesh globe of pulsing nodes joined by fine links, inked in theme tokens and fading into the page background. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add relief-mesh
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/relief-mesh.tsx`.
3. Paste the code.

## Usage

```tsx
import { ReliefMesh } from "@/components/ui/relief-mesh";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <ReliefMesh />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default          | Description                                  |
| :---------------- | :------- | :--------------- | :------------------------------------------- |
| `hue`             | `number` | `0`              | Hue rotation in degrees (-180 to 180).       |
| `saturation`      | `number` | `1`              | Saturation multiplier (0 to 2).              |
| `brightness`      | `number` | `1`              | Brightness multiplier (0.35 to 1.65).        |
| `nodeColor`       | `string` | theme primary    | Colour of the pulsing nodes.                 |
| `lineColor`       | `string` | theme foreground | Colour of the links between nodes.           |
| `fogColor`        | `string` | theme background | Colour the far side of the globe fades into. |
| `backgroundColor` | `string` | theme background | Colour behind the effect.                    |

## Source

`components/ui/relief-mesh.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Topology Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

interface ReliefMeshProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the pulsing nodes. Defaults to the theme primary. */
  nodeColor?: string;
  /** Colour of the links between nodes. Defaults to the theme foreground. */
  lineColor?: string;
  /** Colour the far side of the globe fades into. Defaults to the theme background. */
  fogColor?: string;
  /** Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

type Rgb = [number, number, number];
const TOKENS = [
  "background",
  "foreground",
  "primary",
  "muted-foreground",
  "border",
  "card",
] as const;
type Theme = Record<(typeof TOKENS)[number], Rgb>;

/** Any CSS colour as 0–1 sRGB channels, resolved by the browser. */
function toRgb(color: string): Rgb {
  const probe = document.createElement("i");
  probe.style.display = "none";
  probe.style.color = color;
  document.body.appendChild(probe);
  const [r = 0, g = 0, b = 0] = (getComputedStyle(probe).color.match(/[\d.]+/g) ?? []).map(Number);
  probe.remove();
  return [r / 255, g / 255, b / 255];
}

/** The Modus theme tokens, re-read whenever the mode or palette on <html> changes. */
function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      setTheme(
        Object.fromEntries(
          TOKENS.map((t) => [t, toRgb(`hsl(${style.getPropertyValue(`--${t}`).trim()})`)]),
        ) as Theme,
      );
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

const mix = (a: Rgb, b: Rgb, t: number): Rgb => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];

// Colours reach the screen untouched (linear output), so sRGB channels go in as-is.
const color3 = (c: Rgb) => new THREE.Color(c[0], c[1], c[2]);

export function ReliefMesh({
  hue = 0,
  saturation = 1,
  brightness = 1,
  nodeColor,
  lineColor,
  fogColor,
  backgroundColor,
  className,
}: ReliefMeshProps) {
  const prefersReducedMotion = useReducedMotion();
  const theme = useTheme();
  const hostRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const host = hostRef.current;
    if (!host || !theme) return;

    const fog = fogColor ? toRgb(fogColor) : theme.background;
    const link = lineColor ? toRgb(lineColor) : theme.foreground;
    const scene = new THREE.Scene();
    scene.fog = new THREE.Fog(color3(fog), 300, 950);

    const camera = new THREE.PerspectiveCamera(60, 1, 1, 2000);
    camera.position.z = 650;

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    host.appendChild(renderer.domElement);

    const group = new THREE.Group();
    scene.add(group);

    const numNodes = 120;
    // Faceted nodes instead of smooth spheres.
    const nodeGeo = new THREE.OctahedronGeometry(1, 0);
    const primary = nodeColor ? toRgb(nodeColor) : theme.primary;
    const nodeTints = [color3(primary), color3(mix(primary, link, 0.5))];
    type NodeData = { baseSize: number; pulseSpeed: number; pulseOffset: number };
    const nodes: {
      mesh: THREE.Mesh<THREE.OctahedronGeometry, THREE.MeshBasicMaterial>;
      data: NodeData;
    }[] = [];

    for (let i = 0; i < numNodes; i++) {
      const phi = Math.acos(-1 + (2 * i) / numNodes);
      const theta = Math.sqrt(numNodes * Math.PI) * phi;
      const x = Math.cos(theta) * Math.sin(phi);
      const y = Math.sin(theta) * Math.sin(phi);
      const z = Math.cos(phi);

      const mesh = new THREE.Mesh(
        nodeGeo,
        new THREE.MeshBasicMaterial({
          color: nodeTints[i % 3 === 0 ? 1 : 0],
          transparent: true,
          opacity: 0.9,
        }),
      );
      mesh.position.set(x, y, z);
      group.add(mesh);
      nodes.push({
        mesh,
        data: {
          baseSize: Math.random() * 1.5 + 1.0,
          pulseSpeed: Math.random() * 0.02 + 0.015,
          pulseOffset: Math.random() * Math.PI * 2,
        },
      });
    }

    const linePos: number[] = [];
    const lineColors: number[] = [];
    const threshold = 0.45;
    for (let i = 0; i < numNodes; i++) {
      for (let j = i + 1; j < numNodes; j++) {
        const a = nodes[i].mesh.position;
        const b = nodes[j].mesh.position;
        const dist = a.distanceTo(b);
        if (dist < threshold) {
          linePos.push(a.x, a.y, a.z, b.x, b.y, b.z);
          // Normal blending: weak links fade into the fog colour instead of adding light.
          const [cr, cg, cb] = mix(fog, link, (1 - dist / threshold) * 0.9);
          lineColors.push(cr, cg, cb, cr, cg, cb);
        }
      }
    }

    const lineGeo = new THREE.BufferGeometry();
    lineGeo.setAttribute("position", new THREE.Float32BufferAttribute(linePos, 3));
    lineGeo.setAttribute("color", new THREE.Float32BufferAttribute(lineColors, 3));
    const lineMat = new THREE.LineBasicMaterial({
      vertexColors: true,
      transparent: true,
      depthWrite: false,
      opacity: 0.8,
    });
    group.add(new THREE.LineSegments(lineGeo, lineMat));

    let time = 0;
    const step = () => {
      group.rotation.y = time * 0.0018;
      group.rotation.x = -0.35;
      group.rotation.z = time * 0.0006;
      nodes.forEach(({ mesh, data }) => {
        const pulse = (Math.sin(time * data.pulseSpeed + data.pulseOffset) + 1) / 2;
        const targetRadius = data.baseSize + pulse * 1.8;
        const scale = targetRadius / group.scale.x;
        mesh.scale.set(scale, scale, scale);
        mesh.material.opacity = 0.4 + pulse * 0.6;
      });
      renderer.render(scene, camera);
    };

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      camera.aspect = width / height;
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);

      // A globe rising from the lower left edge, cropped by the frame.
      const R = width > 768 ? 430 : 230;
      group.scale.set(R, R, R);
      const centerX = width > 768 ? -width * 0.22 : 0;
      const centerY = width > 768 ? -height * 0.3 : -height * 0.25;
      group.position.set(centerX, centerY, 0);
      if (prefersReducedMotion) step();
    };

    let frame = 0;
    let visible = true;
    const loop = () => {
      time += 1;
      step();
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) step();
      else if (visible && !document.hidden) frame = requestAnimationFrame(loop);
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      nodes.forEach(({ mesh }) => mesh.material.dispose());
      nodeGeo.dispose();
      lineGeo.dispose();
      lineMat.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, theme, nodeColor, lineColor, fogColor]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    />
  );
}
```

---

# Dust Veil

> A drifting fbm veil of dust in your theme's tones that leans toward the pointer.

Install: `npx @modus-ui/cli add dust-veil`

A full-bleed fragment shader of warped fbm noise forming a veil of dust with a drifting band of light, coloured from the palette's primary and fading into the page ground. It breathes slowly and drifts toward the pointer. It fills its positioned parent, re-reads the theme when the mode or palette changes, pauses when off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add dust-veil
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/dust-veil.tsx`.
4. Paste the code.

## Usage

```tsx
import { DustVeil } from "@/components/ui/dust-veil";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <DustVeil />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                     | Description                            |
| :---------------- | :------- | :-------------------------- | :------------------------------------- |
| `hue`             | `number` | `0`                         | Hue rotation in degrees (-180 to 180). |
| `saturation`      | `number` | `1`                         | Saturation multiplier (0 to 2).        |
| `brightness`      | `number` | `1`                         | Brightness multiplier (0.35 to 1.65).  |
| `deepColor`       | `string` | Faint `--foreground` wash   | Colour of the outer veil.              |
| `coreColor`       | `string` | `hsl(var(--primary))`       | Colour of the dense core.              |
| `glowColor`       | `string` | Warmer shift of `--primary` | Colour of the drifting band of light.  |
| `backgroundColor` | `string` | `hsl(var(--background))`    | Colour behind the effect.              |

## Source

`components/ui/dust-veil.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Nebula (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface DustVeilProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the outer veil; defaults to a faint foreground wash. */
  deepColor?: string;
  /** Colour of the dense core; defaults to the theme primary. */
  coreColor?: string;
  /** Colour of the drifting band of light; defaults to a warmer shift of the primary. */
  glowColor?: string;
  /** Colour behind the effect; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
    border: read("--border"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// The original shader writes raw colour values (three r128, no colour management).
const raw = (value: string) => new THREE.Color(value).convertLinearToSRGB();

const fragmentShader = /* glsl */ `
  precision highp float;
  uniform float u_time;
  uniform vec2 u_resolution;
  uniform vec2 u_mouse;
  uniform vec3 u_deep;
  uniform vec3 u_purple;
  uniform vec3 u_violet;
  uniform vec3 u_bg;
  uniform float u_dark;

  vec3 mod289(vec3 x){return x - floor(x*(1.0/289.0))*289.0;}
  vec2 mod289(vec2 x){return x - floor(x*(1.0/289.0))*289.0;}
  vec3 permute(vec3 x){return mod289(((x*34.0)+1.0)*x);}
  float snoise(vec2 v){
    const vec4 C = vec4(0.211324865405187,0.366025403784439,-0.577350269189626,0.024390243902439);
    vec2 i = floor(v + dot(v, C.yy));
    vec2 x0 = v - i + dot(i, C.xx);
    vec2 i1 = (x0.x > x0.y) ? vec2(1.0,0.0) : vec2(0.0,1.0);
    vec4 x12 = x0.xyxy + C.xxzz;
    x12.xy -= i1;
    i = mod289(i);
    vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
    vec3 m = max(0.5 - vec3(dot(x0,x0), dot(x12.xy,x12.xy), dot(x12.zw,x12.zw)), 0.0);
    m = m*m; m = m*m;
    vec3 x = 2.0 * fract(p * C.www) - 1.0;
    vec3 h = abs(x) - 0.5;
    vec3 ox = floor(x + 0.5);
    vec3 a0 = x - ox;
    m *= 1.79284291400159 - 0.85373472095314 * (a0*a0 + h*h);
    vec3 g;
    g.x = a0.x * x0.x + h.x * x0.y;
    g.yz = a0.yz * x12.xz + h.yz * x12.yw;
    return 130.0 * dot(m, g);
  }
  float fbm(vec2 p){
    float v = 0.0; float a = 0.55;
    for(int i=0;i<4;i++){ v += a*snoise(p); p *= 2.05; a *= 0.5; }
    return v;
  }

  void main(){
    vec2 uv = gl_FragCoord.xy / u_resolution.xy;
    vec2 p = uv;
    p.x *= u_resolution.x / u_resolution.y;

    float t = u_time * 0.05;
    vec2 drift = (u_mouse - 0.5) * 0.12;

    // warp coordinates for fluid motion
    vec2 st = p * 0.85 + drift;
    st += vec2(fbm(st + t), fbm(st - t)) * 0.35;

    vec3 col = u_bg;
    float aspect = u_resolution.x / u_resolution.y;

    // main mass, weighted to the lower left
    vec2 c1 = vec2(aspect * 0.3, 0.2) + drift;
    float d1 = length(p - c1);
    float n1 = fbm(st * 1.4 + t * 2.0);
    float mass = smoothstep(1.25, 0.05, d1 + n1 * 0.32);

    // a horizontal band of light drifting across the frame
    float band = smoothstep(0.32, 0.0, abs(uv.y - 0.38 - n1 * 0.16)) * smoothstep(1.3, 0.1, abs(p.x - aspect * 0.4));

    // secondary glow, top right
    vec2 c2 = vec2(aspect * 0.95, 0.95);
    float d2 = length(p - c2);
    float mass2 = smoothstep(0.8, 0.0, d2 + fbm(st*1.1 - t)*0.25);

    col = mix(col, u_deep, clamp(mass*0.9 + mass2*0.7, 0.0, 1.0));
    col = mix(col, u_purple, clamp(mass*mass*0.9 + mass2*0.45, 0.0, 1.0));
    col = mix(col, u_violet, clamp(band * mass * 0.85, 0.0, 1.0));

    // breathing pulse, towards the ground colour
    col = mix(u_bg, col, 0.9 + 0.1 * sin(u_time * 0.4));

    // fine grain so the veil reads like printed dust
    float grain = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
    col += (grain - 0.5) * 0.035;

    // fade back to the ground at the edges
    float vig = smoothstep(1.5, 0.3, length(uv - vec2(0.4, 0.4)));
    col = mix(u_bg, col, mix(0.35, 1.0, vig));

    gl_FragColor = vec4(col, 1.0);
  }
`;

export function DustVeil({
  hue = 0,
  saturation = 1,
  brightness = 1,
  deepColor,
  coreColor,
  glowColor,
  backgroundColor,
  className,
}: DustVeilProps) {
  const prefersReducedMotion = useReducedMotion();
  const themeVersion = useThemeVersion();
  const hostRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return;

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: false });
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    host.appendChild(renderer.domElement);

    const theme = readTheme();
    const [ph, ps, pl] = theme.primary;
    const fallbackDeep = hsl([theme.foreground[0], theme.foreground[1], theme.dark ? 22 : 82]);
    const fallbackCore = hsl([
      ph,
      Math.max(ps, 28),
      theme.dark ? Math.max(pl, 48) : Math.min(pl, 38),
    ]);
    const fallbackGlow = hsl([ph + 28, Math.max(ps, 55), theme.dark ? 68 : 52]);
    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
    const uniforms = {
      u_time: { value: 0 },
      u_resolution: { value: new THREE.Vector2() },
      u_mouse: { value: new THREE.Vector2(0.5, 0.5) },
      u_deep: { value: raw(deepColor ?? fallbackDeep) },
      u_purple: { value: raw(coreColor ?? fallbackCore) },
      u_violet: { value: raw(glowColor ?? fallbackGlow) },
      u_bg: { value: raw(backgroundColor ?? hsl(theme.background)) },
      u_dark: { value: theme.dark ? 1 : 0 },
    };
    const geometry = new THREE.PlaneGeometry(2, 2);
    const material = new THREE.ShaderMaterial({
      uniforms,
      vertexShader: "void main(){ gl_Position = vec4(position, 1.0); }",
      fragmentShader,
    });
    scene.add(new THREE.Mesh(geometry, material));

    // Pointer position normalised to the host, like the original's window.
    const mouseTarget = { x: 0.5, y: 0.5 };
    const onPointerMove = (event: PointerEvent) => {
      const rect = host.getBoundingClientRect();
      mouseTarget.x = (event.clientX - rect.left) / Math.max(1, rect.width);
      mouseTarget.y = 1.0 - (event.clientY - rect.top) / Math.max(1, rect.height);
    };
    window.addEventListener("pointermove", onPointerMove);

    let elapsed = 0;
    const render = () => {
      uniforms.u_time.value = elapsed;
      uniforms.u_mouse.value.x += (mouseTarget.x - uniforms.u_mouse.value.x) * 0.03;
      uniforms.u_mouse.value.y += (mouseTarget.y - uniforms.u_mouse.value.y) * 0.03;
      renderer.render(scene, camera);
    };

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      renderer.setSize(width, height, false);
      // CSS pixels, exactly as the original.
      uniforms.u_resolution.value.set(width, height);
      if (prefersReducedMotion) render();
    };

    let last = performance.now();
    let frame = 0;
    let visible = true;
    const loop = (now: number) => {
      elapsed += (now - last) / 1000;
      last = now;
      render();
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) render();
      else if (visible && !document.hidden) {
        last = performance.now();
        frame = requestAnimationFrame(loop);
      }
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      window.removeEventListener("pointermove", onPointerMove);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, deepColor, coreColor, glowColor, backgroundColor, themeVersion]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
    />
  );
}
```

---

# Ribbon Light

> Diagonal ribbons of ink-toned light drifting over the page, tinted from your theme.

Install: `npx @modus-ui/cli add ribbon-light`

A full-bleed Three.js simplex-noise shader of soft diagonal ribbons that drift and fold across the frame. The two ribbon inks come from the theme's primary hue and are mixed onto the theme background, so it reads as ink on paper in light mode and as light in dark mode. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ribbon-light
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ribbon-light.tsx`.
4. Paste the code.

## Usage

```tsx
import { RibbonLight } from "@/components/ui/ribbon-light";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <RibbonLight />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                            |
| :---------------- | :------- | :------------------------- | :------------------------------------- |
| `hue`             | `number` | `0`                        | Hue rotation in degrees (-180 to 180). |
| `saturation`      | `number` | `1`                        | Saturation multiplier (0 to 2).        |
| `brightness`      | `number` | `1`                        | Brightness multiplier (0.35 to 1.65).  |
| `primaryColor`    | `string` | theme primary              | First colour of the ribbons.           |
| `secondaryColor`  | `string` | theme primary, shifted     | Second colour of the ribbons.          |
| `backgroundColor` | `string` | `"hsl(var(--background))"` | Colour behind the ribbons.             |

## Source

`components/ui/ribbon-light.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Fluid Field (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

interface RibbonLightProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** First colour of the flowing light beams. */
  primaryColor?: string;
  /** Second colour of the flowing light beams. */
  secondaryColor?: string;
  /** Colour behind the ribbons; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// The original shader writes raw colour values (three r128, no colour management).
const raw = (value: string) => new THREE.Color(value).convertLinearToSRGB();

const fragmentShader = /* glsl */ `
  uniform float u_time;
  uniform vec2 u_resolution;
  uniform vec3 u_color1;
  uniform vec3 u_color2;
  uniform vec3 u_base;

  // Compact 2D Simplex Noise
  vec3 mod289(vec3 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
  vec2 mod289(vec2 x) { return x - floor(x * (1.0 / 289.0)) * 289.0; }
  vec3 permute(vec3 x) { return mod289(((x*34.0)+1.0)*x); }
  
  float snoise(vec2 v) {
      const vec4 C = vec4(0.211324865405187, 0.366025403784439, -0.577350269189626, 0.024390243902439);
      vec2 i  = floor(v + dot(v, C.yy));
      vec2 x0 = v -   i + dot(i, C.xx);
      vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
      vec4 x12 = x0.xyxy + C.xxzz;
      x12.xy -= i1;
      i = mod289(i);
      vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
      vec3 m = max(0.5 - vec3(dot(x0,x0), dot(x12.xy,x12.xy), dot(x12.zw,x12.zw)), 0.0);
      m = m*m;
      m = m*m;
      vec3 x = 2.0 * fract(p * C.www) - 1.0;
      vec3 h = abs(x) - 0.5;
      vec3 ox = floor(x + 0.5);
      vec3 a0 = x - ox;
      m *= 1.79284291400159 - 0.85373472095314 * (a0*a0 + h*h);
      vec3 g;
      g.x  = a0.x  * x0.x  + h.x  * x0.y;
      g.yz = a0.yz * x12.xz + h.yz * x12.yw;
      return 130.0 * dot(m, g);
  }

  void main() {
      vec2 uv = gl_FragCoord.xy / u_resolution.xy;
      uv.x *= u_resolution.x / u_resolution.y;

      vec2 st = uv * 0.7;
      st += vec2(snoise(st + u_time * 0.05), snoise(st - u_time * 0.05)) * 0.3;

      float beam = smoothstep(0.1, 0.8, snoise(vec2(st.x * 1.8 - st.y - u_time * 0.12, u_time * 0.02)));
      vec3 glow = mix(u_color1, u_color2, snoise(uv * 1.5 + u_time * 0.1) * 0.5 + 0.5);

      gl_FragColor = vec4(mix(u_base, glow, clamp(beam * 0.85, 0.0, 1.0)), 1.0);
  }
        
`;

export function RibbonLight({
  hue = 0,
  saturation = 1,
  brightness = 1,
  primaryColor,
  secondaryColor,
  backgroundColor = "hsl(var(--background))",
  className,
}: RibbonLightProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const theme = useThemeVersion();

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return;

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: false });
    renderer.outputColorSpace = THREE.LinearSRGBColorSpace;
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    host.appendChild(renderer.domElement);

    // Ribbons are two inks on the primary hue laid over the theme ground.
    const { dark, primary, background } = readTheme();
    const [h, s] = primary;
    const sat = Math.max(s, 40);
    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
    const uniforms = {
      u_time: { value: 0 },
      u_resolution: { value: new THREE.Vector2() },
      u_color1: { value: raw(primaryColor ?? hsl([h, sat, dark ? 56 : 34])) },
      u_color2: { value: raw(secondaryColor ?? hsl([h - 30, sat, dark ? 70 : 50])) },
      u_base: { value: raw(hsl(background)) },
    };
    const geometry = new THREE.PlaneGeometry(2, 2);
    const material = new THREE.ShaderMaterial({
      uniforms,
      vertexShader: "void main(){ gl_Position = vec4(position, 1.0); }",
      fragmentShader,
    });
    scene.add(new THREE.Mesh(geometry, material));

    let elapsed = 0;
    const render = () => {
      uniforms.u_time.value = elapsed;
      renderer.render(scene, camera);
    };

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      renderer.setSize(width, height, false);
      // CSS pixels, exactly as the original.
      uniforms.u_resolution.value.set(width, height);
      if (prefersReducedMotion) render();
    };

    let last = performance.now();
    let frame = 0;
    let visible = true;
    const loop = (now: number) => {
      elapsed += (now - last) / 1000;
      last = now;
      render();
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) render();
      else if (visible && !document.hidden) {
        last = performance.now();
        frame = requestAnimationFrame(loop);
      }
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, primaryColor, secondaryColor, theme]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor, filter }}
    />
  );
}
```

---

# Ash Spiral

> A drifting spiral of 12,000 sparks drawn in your theme's ink, set off-centre.

Install: `npx @modus-ui/cli add ash-spiral`

A Three.js point spiral of 12,000 sparks winding into an off-centre core. Spark colours are derived from the theme's primary hue: on a dark background they glow with additive light, on paper they settle as soft ink, and they follow the palette picker. Rendered at half resolution, it fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ash-spiral
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ash-spiral.tsx`.
4. Paste the code.

## Usage

```tsx
import { AshSpiral } from "@/components/ui/ash-spiral";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <AshSpiral />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                            |
| :---------------- | :------- | :------------------------- | :------------------------------------- |
| `hue`             | `number` | `0`                        | Hue rotation in degrees (-180 to 180). |
| `saturation`      | `number` | `1`                        | Saturation multiplier (0 to 2).        |
| `brightness`      | `number` | `1`                        | Brightness multiplier (0.35 to 1.65).  |
| `emberColor`      | `string` | theme primary, shifted     | Colour of the outer, cooling sparks.   |
| `heatColor`       | `string` | theme primary              | Colour of the hot, inner sparks.       |
| `coreColor`       | `string` | theme highlight            | Colour of the bright spiral core.      |
| `backgroundColor` | `string` | `"hsl(var(--background))"` | Colour behind the spiral.              |

## Source

`components/ui/ash-spiral.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Ember Storm (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

interface AshSpiralProps {
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the outer, cooling sparks. */
  emberColor?: string;
  /** Colour of the hot, inner sparks. */
  heatColor?: string;
  /** Colour of the bright spiral core. */
  coreColor?: string;
  /** Colour behind the spiral; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

// The shaders write raw colour values: CSS colours are used as-is.
const raw = (value: string) => new THREE.Color(value).convertLinearToSRGB();

const COUNT = 12000;
const RES = 0.5;

const vertexShader = /* glsl */ `
  attribute float aSeed;
  attribute float aAng;
  attribute float aRad;
  uniform float uTime;
  uniform float uScale;
  uniform float uAspect;
  varying float vHeat;
  varying float vFlick;
  varying float vCore;
  float hash(float n){ return fract(sin(n*12.9898)*43758.5453); }
  void main(){
      float life = hash(aSeed*7.31);
      float u = fract(uTime*(0.045 + life*0.06) + aSeed);
      float rmax = 0.58 + aRad*0.48;
      float r = max(rmax*(1.0 - u*0.82), 0.018);
      float omega = (0.55 + life*0.55) / (r*0.9 + 0.12);
      float spiral = (rmax - r)*5.2;
      float theta = aAng + uTime*omega*0.34 + spiral;
      float t1 = sin(theta*3.0 + aSeed*10.0 + uTime*0.8);
      float t2 = sin(r*9.0 - uTime*1.1 + aSeed*4.0);
      r += t1*0.022 + t2*0.016;
      float cx = -0.24, cy = -0.02;
      float x = cx + (cos(theta)*r)/uAspect;
      float y = cy + sin(theta)*r;
      y += u*0.11 + sin(uTime*5.0 + aSeed*30.0)*0.006;
      x += sin(uTime*3.3 + aSeed*22.0)*0.004/uAspect;

      vCore  = 1.0 - smoothstep(0.0, 0.17, r);
      vHeat  = clamp(pow(1.0-u, 1.3) * (0.5 + 0.5*(1.0-r)), 0.0, 1.0);
      vFlick = 0.55 + 0.45*sin(uTime*9.0 + aSeed*40.0);
      float sz = (0.7 + hash(aSeed*12.3)*2.7) * (0.45 + vHeat*1.55 + vCore*1.4);
      gl_Position = vec4(x, y, 0.0, 1.0);
      gl_PointSize = sz * uScale;
  }
                
`;

const fragmentShader = /* glsl */ `
  precision mediump float;
  varying float vHeat;
  varying float vFlick;
  varying float vCore;
  uniform vec3 uCrimson;
  uniform vec3 uAmber;
  uniform vec3 uWhite;
  uniform float uInk;
  void main(){
      vec2 p = gl_PointCoord*2.0 - 1.0;
      float d = dot(p,p);
      if(d>1.0) discard;
      float core = (1.0-d); core *= core;
      vec3 crimson = uCrimson;
      vec3 amber   = uAmber;
      vec3 white   = uWhite;
      vec3 c = mix(crimson, amber, vHeat);
      c = mix(c, white, vCore*0.85);
      float a = core*(0.28 + 0.85*vHeat)*vFlick + core*vCore*0.55;
      gl_FragColor = vec4(c*mix(1.0 + vHeat*0.5 + vCore*0.7, 1.0, uInk), a*mix(1.0, 1.6, uInk));
  }
                
`;

export function AshSpiral({
  hue = 0,
  saturation = 1,
  brightness = 1,
  emberColor,
  heatColor,
  coreColor,
  backgroundColor = "hsl(var(--background))",
  className,
}: AshSpiralProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const theme = useThemeVersion();

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return;

    // Sparks are inks on the primary hue: light on the dark ground, dark on paper.
    const { dark, primary } = readTheme();
    const [h, s] = primary;
    const sat = Math.max(s, dark ? 26 : 42);
    const outer = emberColor ?? hsl([h - 14, sat, dark ? 52 : 40]);
    const inner = heatColor ?? hsl([h, sat + 18, dark ? 74 : 24]);
    const core = coreColor ?? hsl([h, dark ? 40 : sat, dark ? 92 : 14]);

    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      alpha: true,
      powerPreference: "high-performance",
    });
    // Rendered at half resolution and stretched, exactly as the original.
    renderer.setPixelRatio(1);
    renderer.setClearColor(0x000000, 0);
    renderer.domElement.style.cssText = `position:absolute;inset:0;width:100%;height:100%;display:block;mix-blend-mode:${dark ? "screen" : "multiply"}`;
    host.appendChild(renderer.domElement);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);

    const seeds = new Float32Array(COUNT);
    const angs = new Float32Array(COUNT);
    const rads = new Float32Array(COUNT);
    for (let i = 0; i < COUNT; i++) {
      seeds[i] = Math.random();
      angs[i] = Math.random() * Math.PI * 2.0;
      rads[i] = Math.sqrt(Math.random());
    }
    const geo = new THREE.BufferGeometry();
    geo.setAttribute("position", new THREE.BufferAttribute(new Float32Array(COUNT * 3), 3));
    geo.setAttribute("aSeed", new THREE.BufferAttribute(seeds, 1));
    geo.setAttribute("aAng", new THREE.BufferAttribute(angs, 1));
    geo.setAttribute("aRad", new THREE.BufferAttribute(rads, 1));

    const uniforms = {
      uTime: { value: 0 },
      uScale: { value: 1 },
      uAspect: { value: 1.6 },
      uCrimson: { value: raw(outer) },
      uAmber: { value: raw(inner) },
      uWhite: { value: raw(core) },
      uInk: { value: dark ? 0 : 1 },
    };
    const mat = new THREE.ShaderMaterial({
      uniforms,
      transparent: true,
      depthTest: false,
      depthWrite: false,
      blending: dark ? THREE.AdditiveBlending : THREE.NormalBlending,
      vertexShader,
      fragmentShader,
    });
    const points = new THREE.Points(geo, mat);
    points.frustumCulled = false;
    scene.add(points);

    const render = () => renderer.render(scene, camera);

    const resize = () => {
      const w = Math.max(1, host.clientWidth);
      const h = Math.max(1, host.clientHeight);
      renderer.setSize(Math.round(w * RES), Math.round(h * RES), false);
      uniforms.uAspect.value = Math.max(0.6, w / h);
      uniforms.uScale.value = Math.max(0.6, (h * RES) / 900);
      if (prefersReducedMotion) render();
    };

    let frame = 0;
    let visible = true;
    let last = performance.now();
    const loop = (now: number) => {
      const dt = Math.min(0.05, (now - last) / 1000);
      last = now;
      uniforms.uTime.value += dt;
      render();
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) {
        uniforms.uTime.value = 9.1;
        render();
      } else if (visible && !document.hidden) {
        last = performance.now();
        frame = requestAnimationFrame(loop);
      }
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      geo.dispose();
      mat.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [prefersReducedMotion, emberColor, heatColor, coreColor, theme]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor, filter }}
    />
  );
}
```

---

# Dot Whirl

> A leaning funnel of 9,500 dots wound by two spiral guides, drawn in your theme's ink.

Install: `npx @modus-ui/cli add dot-whirl`

A Three.js funnel of 9,500 orbiting dots, wound by two spiral guides and a haze of ambient dust, leaning across the frame and turning toward the pointer. Dots and guides take the theme's ink and muted tones over the theme background: additive light in dark mode, plain ink on paper in light mode, following the palette picker. It fills its positioned parent, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add dot-whirl
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/dot-whirl.tsx`.
4. Paste the code.

## Usage

```tsx
import { DotWhirl } from "@/components/ui/dot-whirl";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <DotWhirl />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default          | Description                                           |
| :---------------- | :------- | :--------------- | :---------------------------------------------------- |
| `speed`           | `number` | `1`              | Animation speed multiplier (0 to 3).                  |
| `size`            | `number` | `1`              | Point size multiplier.                                |
| `density`         | `number` | `1`              | Particle count multiplier (0.25 to 2.5).              |
| `opacity`         | `number` | `1`              | Opacity of the effect (0.05 to 1).                    |
| `hue`             | `number` | `0`              | Hue rotation in degrees (-180 to 180).                |
| `saturation`      | `number` | `1`              | Saturation multiplier (0 to 2).                       |
| `brightness`      | `number` | `1`              | Brightness multiplier (0.35 to 1.65).                 |
| `primaryColor`    | `string` | theme ink        | Colour of the whirl dots and the bright spiral guide. |
| `secondaryColor`  | `string` | theme muted tone | Colour of the dim spiral guide and ambient dust.      |
| `backgroundColor` | `string` | theme background | Colour behind the whirl.                              |

## Source

`components/ui/dot-whirl.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Flux Vortex (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { animate, useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
import { RenderPass } from "three/examples/jsm/postprocessing/RenderPass.js";
import { UnrealBloomPass } from "three/examples/jsm/postprocessing/UnrealBloomPass.js";
import { cn } from "@/lib/utils";

interface DotWhirlProps {
  speed?: number;
  size?: number;
  density?: number;
  opacity?: number;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Colour of the whirl dots and the bright spiral guide. */
  primaryColor?: string;
  /** Colour of the dim spiral guide and ambient dust. */
  secondaryColor?: string;
  /** Colour behind the whirl; defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

type Hsl = [number, number, number];

/** Theme tokens are bare HSL channels ("24 8% 20%"). */
function readTheme() {
  const style = getComputedStyle(document.documentElement);
  const read = (name: string): Hsl => {
    const [h = 0, s = 0, l = 0] = style
      .getPropertyValue(name)
      .trim()
      .split(/[\s,/%]+/)
      .map(Number);
    return [h, s, l];
  };
  const background = read("--background");
  return {
    dark: background[2] < 50,
    background,
    foreground: read("--foreground"),
    primary: read("--primary"),
    muted: read("--muted-foreground"),
  };
}

/** Comma-separated hsl(), which both canvas and THREE.Color parse. */
const hsl = ([h, s, l]: Hsl, alpha = 1) =>
  `hsla(${Math.round(h)}, ${Math.round(Math.min(100, Math.max(0, s)))}%, ${Math.round(Math.min(100, Math.max(0, l)))}%, ${alpha})`;

/** Bumps on light/dark or palette changes so canvas colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
const scaleCount = (base: number, density: number, minimum = 1) =>
  Math.max(minimum, Math.round(base * density));

export function DotWhirl({
  speed = 1,
  size = 1,
  density = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  primaryColor,
  secondaryColor,
  backgroundColor,
  className,
}: DotWhirlProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const theme = useThemeVersion();
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const safeSize = clamp(size, 0.05, 200);
  const safeDensity = clamp(density, 0.25, 2.5);

  useEffect(() => {
    const host = hostRef.current;
    if (!host) return;

    // Dots are the theme's ink: additive light on a dark ground, plain ink on paper.
    const { dark, primary, foreground, muted, background } = readTheme();
    const [h, s] = primary;
    const sat = Math.max(s, 30);
    const ink = primaryColor ?? hsl([h, sat, dark ? Math.max(foreground[2], 80) : 22]);
    const dust = secondaryColor ?? hsl([h - 20, sat + 10, dark ? 46 : muted[2] + 12]);
    const ground = backgroundColor ?? hsl(background);
    const blending = dark ? THREE.AdditiveBlending : THREE.NormalBlending;

    const scene = new THREE.Scene();
    scene.background = new THREE.Color(ground);
    scene.fog = new THREE.FogExp2(ground, 0.04);

    const camera = new THREE.PerspectiveCamera(75, 1, 0.1, 100);
    camera.position.z = 7;

    const renderer = new THREE.WebGLRenderer({
      antialias: false,
      powerPreference: "high-performance",
      alpha: false,
    });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
    renderer.toneMapping = THREE.ACESFilmicToneMapping;
    renderer.toneMappingExposure = 1.0;
    renderer.domElement.style.cssText =
      "position:absolute;inset:0;width:100%;height:100%;display:block";
    host.appendChild(renderer.domElement);

    // The whirl leans across the frame instead of standing upright.
    const tilt = new THREE.Group();
    tilt.rotation.z = -0.5;
    tilt.position.x = 1.2;
    scene.add(tilt);
    const mainGroup = new THREE.Group();
    tilt.add(mainGroup);

    // --- 1. Vortex Particle Field ---
    const vortexCount = scaleCount(9500, safeDensity, 1200);
    const vortexPositions = new Float32Array(vortexCount * 3);
    const vortexRadius = new Float32Array(vortexCount);
    const vortexAngle = new Float32Array(vortexCount);
    const vortexHeight = new Float32Array(vortexCount);
    const vortexSpeed = new Float32Array(vortexCount);

    for (let i = 0; i < vortexCount; i++) {
      const i3 = i * 3;
      const y = (Math.random() - 0.5) * 7.5;
      const funnel = 0.4 + Math.abs(y) * 0.2;
      const r = (0.1 + Math.pow(Math.random(), 1.5) * 2.5) * funnel;
      const a = Math.random() * Math.PI * 2;
      vortexHeight[i] = y;
      vortexRadius[i] = r;
      vortexAngle[i] = a;
      vortexSpeed[i] = 0.5 + Math.random() * 0.8;
      vortexPositions[i3] = Math.cos(a) * r;
      vortexPositions[i3 + 1] = y;
      vortexPositions[i3 + 2] = Math.sin(a) * r;
    }

    const vortexGeometry = new THREE.BufferGeometry();
    vortexGeometry.setAttribute("position", new THREE.BufferAttribute(vortexPositions, 3));
    const vortexMaterial = new THREE.PointsMaterial({
      size: Number((0.006 * safeSize).toFixed(4)),
      color: ink,
      transparent: true,
      opacity: 0.6,
      blending,
      depthWrite: false,
    });
    mainGroup.add(new THREE.Points(vortexGeometry, vortexMaterial));

    // --- 2. Spiral Guides ---
    const createSpiralLine = (turnOffset: number, color: string) => {
      const spiralPoints: THREE.Vector3[] = [];
      const pointCount = 400;
      for (let i = 0; i < pointCount; i++) {
        const t = i / (pointCount - 1);
        const angle = t * Math.PI * 14 + turnOffset;
        const radius = 0.2 + t * 2.8;
        const y = (0.5 - t) * 6.0;
        spiralPoints.push(new THREE.Vector3(Math.cos(angle) * radius, y, Math.sin(angle) * radius));
      }
      return new THREE.Line(
        new THREE.BufferGeometry().setFromPoints(spiralPoints),
        new THREE.LineBasicMaterial({
          color,
          transparent: true,
          opacity: 0.15,
          blending,
        }),
      );
    };
    const spiralLineA = createSpiralLine(0, dust);
    const spiralLineB = createSpiralLine(Math.PI, ink);
    mainGroup.add(spiralLineA, spiralLineB);

    // --- 3. Ambient Particles ---
    const particlesCount = scaleCount(300, safeDensity, 40);
    const posArray = new Float32Array(particlesCount * 3);
    for (let i = 0; i < particlesCount * 3; i++) posArray[i] = (Math.random() - 0.5) * 12;
    const particlesGeometry = new THREE.BufferGeometry();
    particlesGeometry.setAttribute("position", new THREE.BufferAttribute(posArray, 3));
    const particlesMaterial = new THREE.PointsMaterial({
      size: Number((0.008 * safeSize).toFixed(4)),
      color: dust,
      transparent: true,
      opacity: 0.4,
      blending,
    });
    const particlesMesh = new THREE.Points(particlesGeometry, particlesMaterial);
    scene.add(particlesMesh);

    // --- Post Processing ---
    const bloomPass = new UnrealBloomPass(new THREE.Vector2(1, 1), 1.0, 0.4, 0.85);
    bloomPass.strength = 0.6;
    bloomPass.radius = 0.3;
    bloomPass.threshold = 0.2;
    // Bloom lifts light marks on a dark ground; on paper it would wash the page out.
    bloomPass.enabled = dark;
    const composer = new EffectComposer(renderer);
    composer.addPass(new RenderPass(scene, camera));
    composer.addPass(bloomPass);

    // --- Pointer, mapped to the host centre like the original's window centre ---
    let mouseX = 0;
    let mouseY = 0;
    const onPointerMove = (event: PointerEvent) => {
      const rect = host.getBoundingClientRect();
      mouseX = event.clientX - (rect.left + rect.width / 2);
      mouseY = event.clientY - (rect.top + rect.height / 2);
    };
    window.addEventListener("pointermove", onPointerMove);

    let elapsedTime = 0;
    const render = () => {
      const targetX = mouseX * 0.001;
      const targetY = mouseY * 0.0008;
      mainGroup.rotation.y += 0.002;
      mainGroup.rotation.y += 0.03 * (targetX - mainGroup.rotation.y);
      mainGroup.rotation.x += 0.03 * (targetY - mainGroup.rotation.x);

      const positions = vortexGeometry.attributes.position.array as Float32Array;
      for (let i = 0; i < vortexCount; i++) {
        const i3 = i * 3;
        const spin = elapsedTime * vortexSpeed[i] * 0.5 + vortexHeight[i] * 0.5;
        const angle = vortexAngle[i] + spin;
        const pulse = Math.sin(elapsedTime * 1.2 + i * 0.01) * 0.05;
        const radius = vortexRadius[i] + pulse;
        positions[i3] = Math.cos(angle) * radius;
        positions[i3 + 1] = vortexHeight[i] + Math.sin(elapsedTime + i * 0.02) * 0.03;
        positions[i3 + 2] = Math.sin(angle) * radius;
      }
      vortexGeometry.attributes.position.needsUpdate = true;

      spiralLineA.rotation.y = elapsedTime * 0.15;
      spiralLineB.rotation.y = -elapsedTime * 0.12;
      particlesMesh.rotation.y = elapsedTime * 0.03;
      particlesMesh.rotation.x = -mouseY * 0.0001;

      composer.render();
    };

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      camera.aspect = width / height;
      camera.updateProjectionMatrix();
      renderer.setSize(width, height, false);
      composer.setSize(width, height);
      if (prefersReducedMotion) render();
    };

    // Intro: the vortex grows in from 0.6 (power3.out, 2s, after the loader fades).
    const intro = prefersReducedMotion
      ? undefined
      : animate(0.6, 1, {
          duration: 2,
          delay: 0.5,
          ease: [0.215, 0.61, 0.355, 1],
          onUpdate: (value) => mainGroup.scale.setScalar(value),
        });
    if (!prefersReducedMotion) mainGroup.scale.setScalar(0.6);

    let last = performance.now();
    let frame = 0;
    let visible = true;
    const loop = (now: number) => {
      elapsedTime += ((now - last) / 1000) * speedRef.current;
      last = now;
      render();
      frame = requestAnimationFrame(loop);
    };
    const start = () => {
      cancelAnimationFrame(frame);
      if (prefersReducedMotion) render();
      else if (visible && !document.hidden) {
        last = performance.now();
        frame = requestAnimationFrame(loop);
      }
    };

    resize();
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersection = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      start();
    });
    intersection.observe(host);
    document.addEventListener("visibilitychange", start);
    start();

    return () => {
      cancelAnimationFrame(frame);
      intro?.stop();
      intersection.disconnect();
      resizeObserver.disconnect();
      document.removeEventListener("visibilitychange", start);
      window.removeEventListener("pointermove", onPointerMove);
      vortexGeometry.dispose();
      vortexMaterial.dispose();
      [spiralLineA, spiralLineB].forEach((line) => {
        line.geometry.dispose();
        line.material.dispose();
      });
      particlesGeometry.dispose();
      particlesMaterial.dispose();
      bloomPass.dispose();
      composer.dispose();
      renderer.dispose();
      renderer.domElement.remove();
    };
  }, [
    prefersReducedMotion,
    safeSize,
    safeDensity,
    primaryColor,
    secondaryColor,
    backgroundColor,
    theme,
  ]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor ?? "hsl(var(--background))", filter }}
      aria-hidden="true"
    >
      <div
        ref={hostRef}
        className="absolute inset-0"
        style={{ opacity: clamp(opacity, 0.05, 1) }}
      />
    </div>
  );
}
```

---

# Orbit Chip Button

> A solid primary pill led by a paper chip whose arrow turns forward on hover.

Install: `npx @modus-ui/cli add orbit-chip-button`

A solid primary pill led by a paper chip. On hover the chip's diagonal arrow turns to point forward and the pill lifts. Colours come from the active theme and palette. Transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add orbit-chip-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/orbit-chip-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { OrbitChipButton } from "@/components/ui/orbit-chip-button";

export default function Example() {
  return (
    <div className="h-[300px] w-full">
      <OrbitChipButton onClick={() => console.log("clicked")} />
    </div>
  );
}
```

## Props

| Prop      | Type                                   | Default           | Description    |
| :-------- | :------------------------------------- | :---------------- | :------------- |
| `label`   | `string`                               | `"Start a draft"` | Button text.   |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`       | Click handler. |

## Source

`components/ui/orbit-chip-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Understory Arrow Pill (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface OrbitChipButtonProps {
  /** Button text. */
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

/** A solid primary pill led by a paper chip whose arrow turns from diagonal to forward on hover. */
export function OrbitChipButton({
  label = "Start a draft",
  onClick,
  className,
}: OrbitChipButtonProps) {
  const still = useReducedMotion();
  return (
    <div className={cn("relative grid h-full min-h-[240px] w-full place-items-center", className)}>
      <button
        type="button"
        onClick={onClick}
        className={cn(
          "group inline-flex h-14 items-center gap-4 rounded-full bg-[hsl(var(--primary))] py-0 pl-2 pr-7 font-sans text-base font-medium text-[hsl(var(--primary-foreground))]",
          "shadow-[0_14px_30px_-12px_hsl(var(--primary)/0.55)] transition-[transform,box-shadow] duration-300 hover:-translate-y-0.5 hover:shadow-[0_20px_38px_-12px_hsl(var(--primary)/0.6)]",
          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[hsl(var(--ring))]",
          still && "transition-none hover:translate-y-0",
        )}
      >
        <span className="grid h-10 w-10 place-items-center rounded-full bg-[hsl(var(--background))] text-foreground">
          <svg
            viewBox="0 0 12 12"
            aria-hidden="true"
            className={cn(
              "h-3 w-3 -rotate-45 fill-none stroke-current stroke-2 transition-transform duration-300 group-hover:rotate-0",
              still && "transition-none",
            )}
          >
            <path d="M1.5 6h9M7 2.5 10.5 6 7 9.5" />
          </svg>
        </span>
        <span>{label}</span>
      </button>
    </div>
  );
}
```

---

# Stamp Key

> A theme-inked key that presses into its base and lights its index tick on hover.

Install: `npx @modus-ui/cli add stamp-key`

A key set on a darker plinth: on hover the face presses down into the base and its index tick lights up, and on press it bottoms out. The primary key is inked in the theme's primary colour; the secondary key is a paper card with a hairline. Labels are uppercase mono, and both keys follow the active palette in light and dark mode.

## Installation

### CLI

```bash
npx @modus-ui/cli add stamp-key
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/stamp-key.tsx`.
3. Paste the code.

## Usage

```tsx
import { StampKey } from "@/components/ui/stamp-key";

export default function Example() {
  return (
    <div className="h-[400px] w-full">
      <StampKey variant="secondary" />
    </div>
  );
}
```

## Props

| Prop      | Type                                   | Default                                           | Description                                    |
| :-------- | :------------------------------------- | :------------------------------------------------ | :--------------------------------------------- |
| `variant` | `"primary" \| "secondary"`             | `"primary"`                                       | Ink-filled primary key or paper secondary key. |
| `label`   | `string`                               | "Commit" (primary) or "Save as draft" (secondary) | Button text.                                   |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | —                                                 | Click handler for the button.                  |

## Source

`components/ui/stamp-key.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Meridian Keycap (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface StampKeyProps {
  /** Ink-filled primary key or paper secondary key. */
  variant?: "primary" | "secondary";
  /** Button text. Defaults to "Commit" (primary) or "Save as draft" (secondary). */
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

export function StampKey({ variant = "primary", label, onClick, className }: StampKeyProps) {
  const prefersReducedMotion = useReducedMotion();
  const primary = variant !== "secondary";
  const motion = prefersReducedMotion ? "transition-none" : "transition-all duration-150 ease-out";
  return (
    <div
      className={cn(
        "relative isolate grid h-full min-h-[240px] w-full place-items-center overflow-hidden",
        className,
      )}
    >
      <button
        type="button"
        onClick={onClick}
        className={cn(
          "group relative inline-flex h-16 shrink-0 cursor-pointer items-end rounded-[6px] border-0 p-0 font-mono text-[12px] font-medium uppercase tracking-[0.2em]",
          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[hsl(var(--primary))]",
          primary
            ? "bg-[color-mix(in_oklab,hsl(var(--primary))_70%,hsl(var(--foreground)))]"
            : "bg-[hsl(var(--border))]",
        )}
      >
        <span
          className={cn(
            "relative mb-[6px] flex h-[58px] items-center gap-3 rounded-[6px] px-7 ring-1 ring-inset",
            motion,
            "-translate-y-0 group-hover:translate-y-[4px] group-active:translate-y-[6px]",
            primary
              ? "bg-[hsl(var(--primary))] text-[hsl(var(--primary-foreground))] ring-[hsl(var(--primary-foreground)/0.15)]"
              : "bg-[hsl(var(--card))] text-foreground ring-[hsl(var(--border))]",
          )}
        >
          <span
            aria-hidden
            className={cn(
              "h-3 w-px",
              motion,
              primary
                ? "bg-[hsl(var(--primary-foreground)/0.35)] group-hover:bg-[hsl(var(--primary-foreground))]"
                : "bg-[hsl(var(--muted-foreground)/0.4)] group-hover:bg-[hsl(var(--primary))]",
            )}
          />
          {label ?? (primary ? "Commit" : "Save as draft")}
        </span>
      </button>
    </div>
  );
}
```

---

# Ink Endcap Button

> An italic serif pill with a round ink endcap, as a hairline outline or a solid fill.

Install: `npx @modus-ui/cli add ink-endcap-button`

An italic serif pill finished with a round endcap holding an arrow. The default `outline` variant is a hairline ring with a primary endcap; `solid` fills the pill with the primary colour and inverts the endcap. It lifts slightly on hover and holds still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-endcap-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ink-endcap-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { InkEndcapButton } from "@/components/ui/ink-endcap-button";

export default function Example() {
  return <InkEndcapButton label="Open the archive" />;
}
```

## Props

| Prop      | Type                                   | Default              | Description                                                               |
| :-------- | :------------------------------------- | :------------------- | :------------------------------------------------------------------------ |
| `label`   | `string`                               | `"Open the archive"` | Button text.                                                              |
| `variant` | `"solid" \| "outline"`                 | `"outline"`          | `solid` is ink on paper; `outline` is a hairline ring with an ink endcap. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | —                    | Click handler for the button.                                             |

## Source

`components/ui/ink-endcap-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Halvorsen Arrow Pill (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface InkEndcapButtonProps {
  /** Button text. */
  label?: string;
  /** `solid` is ink on paper; `outline` is a hairline ring with an ink endcap. */
  variant?: "solid" | "outline";
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

export function InkEndcapButton({
  label = "Open the archive",
  variant = "outline",
  onClick,
  className,
}: InkEndcapButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  const solid = variant === "solid";
  return (
    <button
      type="button"
      onClick={onClick}
      className={cn(
        "group inline-flex h-14 items-center gap-5 rounded-full pl-8 pr-2 font-serif text-xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-4 focus-visible:ring-offset-background",
        solid
          ? "bg-[hsl(var(--primary))] text-primary-foreground shadow-[0_14px_30px_-12px_hsl(var(--primary)/0.6)]"
          : "border border-[hsl(var(--foreground)/0.25)] bg-transparent text-foreground hover:border-[hsl(var(--primary))]",
        !prefersReducedMotion &&
          "transition-[transform,border-color] duration-300 hover:-translate-y-0.5",
        className,
      )}
    >
      <span className="italic">{label}</span>
      <span
        aria-hidden
        className={cn(
          "relative grid h-10 w-10 place-items-center overflow-hidden rounded-full",
          solid
            ? "bg-[hsl(var(--background))] text-foreground"
            : "bg-[hsl(var(--primary))] text-primary-foreground",
        )}
      >
        <svg
          viewBox="0 0 12 12"
          className={cn(
            "h-3 w-3 fill-none stroke-current [stroke-width:1.75]",
            !prefersReducedMotion &&
              "transition-transform duration-300 group-hover:translate-x-0.5",
          )}
        >
          <path d="M1.5 6h8M6 2.5 9.5 6 6 9.5" />
        </svg>
      </span>
    </button>
  );
}
```

---

# Prism Key

> A frosted key-shaped button with a palette-tinted prism edge and an ink arrow chip.

Install: `npx @modus-ui/cli add prism-key`

A frosted button whose masked gradient rim catches the theme's primary colour like light through a prism. The default arrow variant carries a solid ink chip whose arrow tilts upward on hover; the plain variant is text only. Labels are set in uppercase mono, and every colour comes from the active theme. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add prism-key
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/prism-key.tsx`.
4. Paste the code.

## Usage

```tsx
import { PrismKey } from "@/components/ui/prism-key";

export default function Example() {
  return <PrismKey onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default                                            | Description                           |
| :-------- | :------------------------------------- | :------------------------------------------------- | :------------------------------------ |
| `variant` | `"arrow" \| "plain"`                   | `"arrow"`                                          | Key with an arrow chip, or text only. |
| `label`   | `string`                               | "Open the kit" (arrow) or "Request access" (plain) | Button text.                          |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`                                        | Click handler.                        |

## Source

`components/ui/prism-key.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Aster Glass (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface PrismKeyProps {
  /** Glass key with an arrow chip, or a plain text key. */
  variant?: "arrow" | "plain";
  /** Button text. Defaults to "Open the kit" (arrow) or "Request access" (plain). */
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

const RIM = `
  content: ""; position: absolute; inset: 0; border-radius: inherit; padding: 1px; pointer-events: none;
  mask: linear-gradient(black 0 0) content-box, linear-gradient(black 0 0); mask-composite: exclude;
  -webkit-mask: linear-gradient(black 0 0) content-box, linear-gradient(black 0 0); -webkit-mask-composite: xor;`;

const STYLES = `
.m-prism-key {
  position: relative; display: inline-flex; align-items: center; justify-content: center; height: 52px;
  border: 0; border-radius: 14px; isolation: isolate; cursor: pointer; white-space: nowrap;
  color: hsl(var(--foreground)); background: hsl(var(--foreground) / .045);
  box-shadow: 0 18px 40px -24px hsl(var(--primary) / .55), inset 0 1px 0 hsl(var(--background) / .6);
  backdrop-filter: blur(16px) saturate(1.3); -webkit-backdrop-filter: blur(16px) saturate(1.3);
  transition: transform .5s cubic-bezier(.22,1,.36,1), background .4s ease, box-shadow .5s cubic-bezier(.22,1,.36,1);
}
.m-prism-key::before {${RIM}
  z-index: -1;
  background: linear-gradient(148deg, hsl(var(--primary) / .7), hsl(var(--foreground) / .12) 36%, hsl(var(--foreground) / .04) 60%, hsl(var(--primary) / .45));
  transition: filter .45s cubic-bezier(.22,1,.36,1);
}
.m-prism-key::after {
  content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; pointer-events: none;
  background: linear-gradient(180deg, hsl(var(--background) / .55), transparent 52%);
}
.m-prism-key:hover { transform: translateY(-2px); background: hsl(var(--primary) / .1); box-shadow: 0 14px 30px -14px hsl(var(--primary) / .6), inset 0 1px 0 hsl(var(--background) / .6); }
.m-prism-key:hover::before { filter: saturate(1.4) brightness(1.15); }
.m-prism-key:active { transform: translateY(0); }
.m-prism-key:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 5px; }
.m-prism-key-chip {
  position: relative; display: grid; width: 36px; height: 36px; place-items: center; border-radius: 10px;
  background: hsl(var(--primary)); color: hsl(var(--primary-foreground));
  box-shadow: inset 0 1px 0 hsl(var(--primary-foreground) / .35);
}
.m-prism-key svg { width: 15px; height: 15px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; transition: transform .5s cubic-bezier(.22,1,.36,1); }
.m-prism-key:hover svg { transform: translateX(2px) rotate(-45deg); }
.m-prism-key[data-reduced], .m-prism-key[data-reduced]::before, .m-prism-key[data-reduced] svg { transition-duration: .01ms !important; }
`;

export function PrismKey({ variant = "arrow", label, onClick, className }: PrismKeyProps) {
  const prefersReducedMotion = useReducedMotion();
  const arrow = variant === "arrow";
  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <button
        type="button"
        onClick={onClick}
        data-reduced={prefersReducedMotion ? "" : undefined}
        className={cn(
          "m-prism-key font-mono text-xs uppercase tracking-[0.18em]",
          arrow ? "gap-4 pl-6 pr-2" : "px-8",
          className,
        )}
      >
        <span>{label ?? (arrow ? "Open the kit" : "Request access")}</span>
        {arrow && (
          <span className="m-prism-key-chip">
            <svg viewBox="0 0 12 12" aria-hidden="true">
              <path d="M2 6h8M6.6 2.6 10 6 6.6 9.4" />
            </svg>
          </span>
        )}
      </button>
    </>
  );
}
```

---

# Round Glyph

> Three round icon buttons in the theme's colours: a raised plus key, a frosted play disc and a stitched mail ring.

Install: `npx @modus-ui/cli add round-glyph`

Round icon buttons in three treatments. The default plus is a raised ink key with a pressed lip whose cross turns on hover; play is a frosted disc with a sheen orbiting inside that fills with the primary colour on hover; mail is a dashed ring that stitches a second ring around itself on hover. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add round-glyph
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/round-glyph.tsx`.
4. Paste the code.

## Usage

```tsx
import { RoundGlyph } from "@/components/ui/round-glyph";

export default function Example() {
  return <RoundGlyph variant="mail" />;
}
```

## Props

| Prop        | Type                                   | Default                                 | Description             |
| :---------- | :------------------------------------- | :-------------------------------------- | :---------------------- |
| `variant`   | `"plus" \| "play" \| "mail"`           | `"plus"`                                | Which button to render. |
| `ariaLabel` | `string`                               | "Add", "Play" or "Send mail" by variant | Accessible label.       |
| `disabled`  | `boolean`                              | `false`                                 | Disables the button.    |
| `type`      | `"button" \| "submit" \| "reset"`      | `"button"`                              | Native button type.     |
| `onClick`   | `MouseEventHandler<HTMLButtonElement>` | `undefined`                             | Click handler.          |

## Source

`components/ui/round-glyph.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Circle Buttons (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface RoundGlyphProps {
  /** Raised plus key, frosted play disc with an orbiting sheen, or stitched mail ring. */
  variant?: "plus" | "play" | "mail";
  /** Accessible label. Defaults to "Add", "Play" or "Send mail". */
  ariaLabel?: string;
  disabled?: boolean;
  type?: "button" | "submit" | "reset";
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

const LABELS = { play: "Play", plus: "Add", mail: "Send mail" } as const;

const STYLES = `
.mrg { position: relative; display: grid; width: 68px; aspect-ratio: 1; place-items: center; padding: 0; border: 0; border-radius: 50%;
  background: transparent; color: hsl(var(--foreground)); cursor: pointer; transition: transform .2s ease-in-out; -webkit-tap-highlight-color: transparent; }
.mrg:disabled { cursor: not-allowed; opacity: .45; }
.mrg:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 7px; }
.mrg > span { position: absolute; inset: 0; border-radius: inherit; pointer-events: none; }
.mrg-icon { z-index: 5; display: grid; place-items: center; }
.mrg-icon svg { width: 32%; height: 32%; overflow: visible; }

/* plus: a raised ink key with a pressed lip */
.mrg[data-v="plus"] { color: hsl(var(--primary-foreground)); }
.mrg[data-v="plus"] .mrg-face {
  background: radial-gradient(80% 80% at 35% 25%, color-mix(in oklab, hsl(var(--primary)) 70%, hsl(var(--primary-foreground))), hsl(var(--primary)));
  box-shadow: 0 0 0 1px hsl(var(--primary) / .4), 0 5px 0 color-mix(in oklab, hsl(var(--primary)) 65%, black), 0 14px 22px -8px hsl(var(--primary) / .7);
  transition: box-shadow .15s;
}
.mrg[data-v="plus"] .mrg-aura { inset: -10px; background: hsl(var(--primary) / .18); filter: blur(10px); opacity: .5; transition: opacity .4s; }
.mrg[data-v="plus"] svg { fill: none; stroke: currentColor; stroke-linecap: round; stroke-width: 1.8; transition: transform .3s ease; }
.mrg[data-v="plus"]:not(:disabled):hover .mrg-aura { opacity: 1; }
.mrg[data-v="plus"]:not(:disabled):hover svg { transform: rotate(90deg); }
.mrg[data-v="plus"]:not(:disabled):active { transform: translateY(3px); }
.mrg[data-v="plus"]:not(:disabled):active .mrg-face { box-shadow: 0 0 0 1px hsl(var(--primary) / .4), 0 2px 0 color-mix(in oklab, hsl(var(--primary)) 65%, black); }

/* play: frosted disc with a sheen orbiting inside */
.mrg[data-v="play"] { overflow: hidden; }
.mrg[data-v="play"] .mrg-face { background: hsl(var(--card) / .8); border: 1px solid hsl(var(--border)); box-shadow: inset 2px 4px 14px hsl(var(--foreground) / .06);
  backdrop-filter: blur(30px); -webkit-backdrop-filter: blur(30px); }
.mrg[data-v="play"] .mrg-aura { z-index: 3; inset: auto; top: 50%; left: 50%; width: 160px; height: 160px; border-radius: 50%;
  background: conic-gradient(from 180deg, transparent 200deg, hsl(var(--primary) / .35) 360deg); filter: blur(12px);
  transform: translate(-50%, -50%); animation: mrg-orbit 3.8s linear infinite; transition: opacity .5s; }
.mrg[data-v="play"] svg { margin-left: 4%; fill: currentColor; }
.mrg[data-v="play"]:not(:disabled):hover .mrg-face { background: hsl(var(--primary)); }
.mrg[data-v="play"]:not(:disabled):hover { color: hsl(var(--primary-foreground)); }
.mrg[data-v="play"]:not(:disabled):hover .mrg-aura { opacity: 0; }
.mrg[data-v="play"]:not(:disabled):active { transform: scale(.96); }
@keyframes mrg-orbit {
  0% { transform: translate(-50%, -50%) rotate(0); } 25% { transform: translate(calc(-50% - 24px), -50%) rotate(90deg); }
  50% { transform: translate(-50%, -50%) rotate(180deg); } 75% { transform: translate(calc(-50% + 24px), -50%) rotate(270deg); }
  100% { transform: translate(-50%, -50%) rotate(360deg); }
}

/* mail: a dashed ring that stitches closed on hover */
.mrg[data-v="mail"] { color: hsl(var(--muted-foreground)); }
.mrg[data-v="mail"] .mrg-face { border: 1px dashed hsl(var(--border)); background: hsl(var(--card)); transition: background-color .2s, border-color .2s; }
.mrg[data-v="mail"] .mrg-aura { inset: -8px; border: 1.5px dashed hsl(var(--primary)); opacity: 0; transform: rotate(-90deg) scale(.85);
  transition: opacity .3s, transform .6s cubic-bezier(.22,1,.36,1); }
.mrg[data-v="mail"] svg { fill: none; stroke: currentColor; stroke-linecap: round; stroke-linejoin: round; stroke-width: 1.5; }
.mrg[data-v="mail"]:not(:disabled):hover { color: hsl(var(--primary-foreground)); transform: scale(1.05); }
.mrg[data-v="mail"]:not(:disabled):hover .mrg-face { background: hsl(var(--primary)); border-color: hsl(var(--primary)); }
.mrg[data-v="mail"]:not(:disabled):hover .mrg-aura { opacity: 1; transform: rotate(0) scale(1); }
.mrg[data-v="mail"]:not(:disabled):active { transform: scale(.97); }

.mrg[data-reduced], .mrg[data-reduced] *, .mrg[data-reduced] svg { animation: none !important; transition-duration: .01ms !important; }
`;

function Glyph({ variant }: { variant: "play" | "plus" | "mail" }) {
  if (variant === "play")
    return (
      <svg viewBox="0 0 32 32" aria-hidden="true">
        <path d="M11.75 8.7c0-1.28 1.4-2.08 2.5-1.43l12 7.3a1.66 1.66 0 0 1 0 2.86l-12 7.3a1.66 1.66 0 0 1-2.5-1.43V8.7Z" />
      </svg>
    );
  if (variant === "plus")
    return (
      <svg viewBox="0 0 32 32" aria-hidden="true">
        <path d="M16 7v18M7 16h18" />
      </svg>
    );
  return (
    <svg viewBox="0 0 32 32" aria-hidden="true">
      <rect x="5.25" y="7.5" width="21.5" height="17" rx="3.25" />
      <path d="m7.25 10 7.35 5.72a2.26 2.26 0 0 0 2.8 0L24.75 10" />
    </svg>
  );
}

export function RoundGlyph({
  variant = "plus",
  ariaLabel,
  disabled = false,
  type = "button",
  onClick,
  className,
}: RoundGlyphProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <button
        className={cn("mrg", className)}
        data-v={variant}
        data-reduced={prefersReducedMotion ? "" : undefined}
        type={type}
        aria-label={ariaLabel ?? LABELS[variant]}
        disabled={disabled}
        onClick={onClick}
      >
        <span className="mrg-aura" aria-hidden="true" />
        <span className="mrg-face" aria-hidden="true" />
        <span className="mrg-icon">
          <Glyph variant={variant} />
        </span>
      </button>
    </>
  );
}
```

---

# Prism Flow Button

> A WebGL2 button whose face pours into prismatic ribbons on hover, set on a soft theme-coloured pool.

Install: `npx @modus-ui/cli add prism-flow-button`

A dispersion shader paints laminar prismatic ribbons inside the pill on hover, a travelling chromatic rim runs round the outline, the cursor drags the ribbons and each press throws a faceted ripple. The plate is a deep shade of the theme's primary colour resting on a soft pool of the page background. Comes as a labelled pill, an icon circle or a larger play circle. Pauses when off screen; with reduced motion the surface holds still.

## Installation

### CLI

```bash
npx @modus-ui/cli add prism-flow-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/prism-flow-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { PrismFlowButton } from "@/components/ui/prism-flow-button";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <PrismFlowButton text="Get the build" />
    </div>
  );
}
```

## Props

| Prop          | Type                           | Default                                     | Description                                             |
| :------------ | :----------------------------- | :------------------------------------------ | :------------------------------------------------------ |
| `variant`     | `"pill" \| "circle" \| "play"` | `"pill"`                                    | Labelled pill, icon-only circle, or larger play circle. |
| `rendering`   | `"colored" \| "monotone"`      | `"colored"`                                 | Play variant only: full colour or greyscale.            |
| `diameter`    | `number`                       | `88`                                        | Play variant only: diameter in px (72 to 160).          |
| `strokeWidth` | `number`                       | `3`                                         | Play variant only: rim stroke width in px (1 to 8).     |
| `text`        | `string`                       | "Get the build", "Add" or "Play" by variant | Pill label, or the accessible name.                     |
| `embedded`    | `boolean`                      | `false`                                     | Use a flat card ground instead of the soft theme pool.  |
| `onClick`     | `() => void`                   | —                                           | Click handler.                                          |

## Source

`components/ui/prism-flow-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Liquid Metal Button (MIT, © 2026 Meng To).

import { useEffect, useRef, type CSSProperties } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface PrismFlowButtonProps {
  /** Labelled pill, icon-only circle, or larger play circle. */
  variant?: "pill" | "circle" | "play";
  /** Play variant only: full colour or greyscale metal. */
  rendering?: "colored" | "monotone";
  /** Play variant only: button diameter in px (72 to 160). */
  diameter?: number;
  /** Play variant only: rim stroke width in px (1 to 8). */
  strokeWidth?: number;
  /** Label (pill) or accessible name. Defaults to "Get the build", "Add" or "Play". */
  text?: string;
  /** Flat card ground instead of the soft theme pool. */
  embedded?: boolean;
  onClick?: () => void;
  className?: string;
}

/* =====================================================================
   Prism flow — a dispersion shader.

   A scalar field V is painted through a soft plateau: dark below it, blown
   white inside, dark above.  The plateau is evaluated once per spectral
   wavelength at a slightly different height in V, so the plateau's lower
   edge fringes warm and its upper edge fringes cool.
   ===================================================================== */

const VERT = `#version 300 es
in vec2 position; void main(){ gl_Position = vec4(position,0.,1.); }`;

const HEAD = `#version 300 es
precision highp float;
out vec4 o;

uniform vec2  uC;        // pill centre, device px
uniform vec2  uHalf;     // pill half-extent, device px
uniform float uT;        // seconds
uniform float uHover;    // 0..1
uniform float uPress;    // 0..1, eased
uniform vec4  uRip[3];   // xy centre (button heights, +y down), z start, w live
uniform vec4  uRipK;     // speed, ring width, decay, amplitude
uniform vec4  uRipK2;    // facet depth, facet count, crest sharpness, emission
uniform vec4  uPtr;      // xy trailing cursor, z strength, w normalised speed
uniform vec4  uPtrK;     // radius, base amplitude, speed amplitude, rim lift

#define PI 3.14159265

float sdPill(vec2 p, vec2 b, float r){
  vec2 q = abs(p) - b + r;
  return min(max(q.x,q.y),0.) + length(max(q,0.)) - r;
}

/* Expanding ring from each press, in button-height units.  Three slots so a
   quick double-tap overlaps instead of cutting the first one off.

   Two things keep it from reading as a water ripple: the wavefront is
   faceted rather than circular — its radius is modulated by angle, and the
   facets rotate as it travels — and the crest profile is a cusp rather than
   a gaussian, so it lands as a crease in sheet metal instead of a soft swell. */
float ripple(vec2 p, float t){
  float sum = 0.;
  for(int i = 0; i < 3; i++){
    if(uRip[i].w < 0.5) continue;
    float age = t - uRip[i].z;
    if(age < 0. || age > 4.) continue;
    vec2  rp = p - uRip[i].xy;
    float facet = 1. + uRipK2.x * cos(uRipK2.y * atan(rp.y, rp.x) + age * 2.1 + float(i) * 2.4);
    float x = (length(rp) - age * uRipK.x * facet) / uRipK.y;
    sum += exp(-pow(abs(x) + 1e-4, uRipK2.z)) * exp(-age * uRipK.z);
  }
  return sum;
}

/* A soft well under the cursor.  It lags behind the real pointer and swells
   with speed, so moving across the button drags the metal rather than sliding
   a static blob over it. */
float pointerW(vec2 p){
  if(uPtr.z < 0.001) return 0.;
  float d = length(p - uPtr.xy) / uPtrK.x;
  return exp(-d*d) * uPtr.z;
}
/* Displacing the sample point, not the field value, is what makes this read as
   liquid: the bands bulge and stretch around the cursor like a lens instead of
   just getting brighter under it. */
vec2 pointerWarp(vec2 p){
  float w = pointerW(p);
  if(w <= 0.) return vec2(0.);
  return normalize(p - uPtr.xy + vec2(1e-5)) * w * (uPtrK.y + uPtrK.z * uPtr.w);
}
`;

/* ---- the travelling rim, in its own pass so the blur below never touches it */
const FRAG_RIM =
  HEAD +
  `
uniform float uBw;       // stroke half-width, device px
uniform float uE[8];     // base, hot, chroma-across, chroma-along, speed,
                         // topBias, press lift, ripple lift

/* Arc-length position around the pill, 0..1, starting at the right-hand
   extreme and running counter-clockwise.  Straight runs and caps are measured
   in real length so a highlight travels at a constant speed all the way
   round instead of stalling on the caps. */
float perim(vec2 d, float a, float r){
  float P = 4.*a + 2.*PI*r;
  float s;
  if(d.x >= a){                                   // right cap
    float th = atan(d.y, d.x - a); if(th < 0.) th += 2.*PI;
    s = (th <= PI*0.5) ? r*th : P - r*(2.*PI - th);
  } else if(d.x <= -a){                           // left cap
    float th = atan(d.y, d.x + a); if(th < 0.) th += 2.*PI;
    s = r*PI*0.5 + 2.*a + r*(th - PI*0.5);
  } else if(d.y >= 0.){                           // top run
    s = r*PI*0.5 + (a - d.x);
  } else {                                        // bottom run
    s = r*PI*1.5 + 2.*a + (d.x + a);
  }
  return s / P;
}
// periodic bump, so a highlight wraps cleanly at s = 0
float pb(float u, float w){ u = fract(u); float x = min(u, 1.-u); return exp(-(x*x)/(w*w)); }

// travelling brightness around the rim — three lobes at different speeds and
// widths, which never quite re-align, so the light keeps re-pooling
float rimHot(float s, float t){
  float v = uE[0];
  v += 0.62 * pb(s - t*uE[4],             0.075);
  v += 0.44 * pb(s + t*uE[4]*0.63 + 0.41, 0.135);
  v += 0.30 * pb(s - t*uE[4]*0.34 + 0.73, 0.200);
  return v;
}
// soft band riding the pill edge, offset per channel to fringe across the stroke
float rimBand(float sd, float off){ return 1. - smoothstep(0., uBw*1.05, abs(sd + uBw*0.55 + off)); }

void main(){
  vec2  d  = gl_FragCoord.xy - uC;
  float sd = sdPill(d, uHalf, uHalf.y);
  if(sd > uBw*2.5 || sd < -uBw*3.5){ o = vec4(0.); return; }

  /* Each channel is offset both *across* the stroke and *along* it, so the rim
     fringes red-outside / cyan-inside and its hue also drifts as a highlight
     slides past — the two together are what read as metal rather than as a
     moving white dot. */
  float a = max(uHalf.x - uHalf.y, 0.);
  float s = perim(d, a, uHalf.y);
  float top = mix(1., 0.5 + 0.5 * (d.y / uHalf.y), uE[5]);

  // pressing lifts the whole outline, and each ripple flares it again as the
  // ring sweeps past — so the rim reports the press twice, once as a step and
  // once as a wave running round the edge
  // …and the stretch of outline nearest the cursor picks up a little too
  vec2  p   = vec2(d.x, -d.y) / (uHalf.y * 2.);
  float lift = 1. + uPress * uE[6] + ripple(p, uT) * uE[7]
             + pointerW(p) * uPtrK.w;

  o = vec4(vec3(
    rimBand(sd,  uE[2]) * rimHot(s + uE[3], uT),
    rimBand(sd,  0.   ) * rimHot(s,         uT),
    rimBand(sd, -uE[2]) * rimHot(s - uE[3], uT)
  ) * uE[1] * top * lift, 1.);
}`;

const FRAG_SCENE =
  HEAD +
  `
uniform float uP[21];    // tunables

float h21(vec2 p){
  vec3 p3 = fract(vec3(p.xyx) * 0.1031);
  p3 += dot(p3, p3.yzx + 33.33);
  return fract((p3.x + p3.y) * p3.z);
}
float vn(vec2 p){
  vec2 i = floor(p), f = fract(p);
  f = f*f*(3.-2.*f);
  float a = h21(i), b = h21(i+vec2(1,0)), c = h21(i+vec2(0,1)), d = h21(i+vec2(1,1));
  return mix(mix(a,b,f.x), mix(c,d,f.x), f.y) * 2. - 1.;
}
// normalised to roughly -1..1; low gain keeps the first octave dominant, which
// is what keeps the ribbons big and smooth instead of turbulent
float fbm(vec2 p, float g){
  float s = 0., a = 1., n = 0.;
  for(int i=0;i<4;i++){ s += a*vn(p); n += a; p = p*2.03 + 11.7; a *= g; }
  return s / n;
}
float fbm(vec2 p){ return fbm(p, 0.5); }

/* p is in button-height units, +y down, origin at the pill centre.

   The bands in the reference are a *family of parallel curves*: one swooping
   valley repeated up the button, dense where the light is pinched and pulled
   wide open where it is not.  So the field is built that way explicitly —

       V = (y - valley(x)) * density(x)

   — rather than hoping 2-D noise happens to produce it.  Level sets of V are
   all vertical translates of the same valley curve, which is what makes the
   ribbons laminar and near-parallel; a density that varies along x is what makes
   them crowd into razor fringes at one end and open into a broad wash at the
   other.  A soft plateau over V then paints them, sampled once per
   wavelength at slightly offset heights, so every edge opens into a prism of
   width dispersion / |grad V|.                                             */

// smooth 1-D wiggle that drifts slowly with time
float wig(float x, float t, float seed){
  return vn(vec2(x,          t*0.150 + seed)) * 0.60
       + vn(vec2(x*2.07 + 4., t*0.105 + seed)) * 0.27
       + vn(vec2(x*4.30 - 7., t*0.080 + seed)) * 0.13;
}

float valleyAt(vec2 p, float t){ return wig(p.x*uP[0], t, 0.0) * uP[1]; }
float densAt  (vec2 p, float t){ return uP[2] * exp(uP[3] * wig(p.x*uP[4] + 9.0, t, 2.7)); }

float surface(vec2 p, float t){
  float V = (p.y - valleyAt(p,t)) * densAt(p,t);
  V += uP[5] * fbm(p*vec2(0.8, 1.7)*uP[6] + vec2(t*0.05, -t*0.03), uP[17]);
  return V - uP[7];
}
// One plateau per unit of V — so the density is literally bands per button height.
// A plateau rather than a step is what puts warm on the low edge and cool on
// the high edge of every ribbon.
float tone(float v){
  float u = fract(v);
  float e = uP[9], W = uP[10] * 0.5;
  return smoothstep(0.5-W-e, 0.5-W, u) * (1. - smoothstep(0.5+W, 0.5+W+e, u));
}
vec3 spec(float t){ return clamp(vec3(1.5) - abs(4.*t - vec3(3.,2.,1.)), 0., 1.); }

void main(){
  vec2  d  = gl_FragCoord.xy - uC;
  float sd = sdPill(d, uHalf, uHalf.y);
  float pill = 1. - smoothstep(-1., 1., sd);
  float S = uHalf.y * 2.;                 // button height, device px
  float t = uT;

  // rgb is premultiplied by the mask and alpha carries it, so the blur that
  // follows can normalise and keep a clean edge instead of a dark vignette
  if(uHover <= 0.0015 || pill <= 0.0015){ o = vec4(0., 0., 0., pill); return; }

  vec2  p = vec2(d.x, -d.y) / S;          // gl_FragCoord is y-up
  vec2  q = p + pointerWarp(p);           // the cursor drags the sheet

  // self-refraction: bend the lookup along the field's own slope, which piles
  // iso-lines up into folds instead of leaving them evenly spaced
  float h0 = surface(q, t);
  vec2  gp = vec2(dFdx(h0), -dFdy(h0)) * S;          // grad in p-units
  float V  = surface(q - gp * uP[8] / max(uP[2], .001), t);

  // gradient-aligned filaments: fast variation across the iso-lines, slow
  // along them, so the fine detail reads as drawn-out fibres of light
  vec2  gd = normalize(gp + vec2(1e-5));
  V += uP[13] * fbm(vec2(dot(q,gd)*uP[14], dot(q, vec2(-gd.y,gd.x))*uP[14]*0.04) + vec2(0., t*0.06));

  // press ripple: displacing the field rather than adding light means the
  // bands themselves bow outwards as the ring passes, which is what sells it
  // as a disturbance *in* the metal instead of a decal over it
  float rip  = ripple(p, t);
  float well = pointerW(p);
  V += rip * uRipK.w;

  // Real dispersion is not linear in wavelength — the blue end bends far more
  // than the red (Cauchy).  Skewing the sample offsets the same way is what
  // gives the reference its broad cool wash against a tight warm edge.
  const int N = 21;
  float mid = 1. - pow(0.5, uP[12]);
  vec3 col = vec3(0.), wsum = vec3(0.);
  for(int i=0;i<N;i++){
    float k = float(i)/float(N-1);
    vec3  w = spec(k);
    col  += w * tone(V + ((1. - pow(1. - k, uP[12])) - mid) * uP[11]);
    wsum += w;
  }
  col /= wsum;
  col = pow(col, vec3(uP[15]));

  // light envelope — the ribbons only exist where the sheet is lit, and the
  // dark upper region is bounded by the same valley curve the bands follow
  float lit = smoothstep(uP[18], uP[19], q.y - valleyAt(q, t));
  lit *= mix(1., lit, 0.55);                     // deepen the unlit crescent
  col *= uP[16] * lit;

  // the crest runs hotter, and carries a little light of its own so it stays
  // legible through the softening blur and across the unlit part of the pill
  col = col * (1. + rip * 1.15 + well * 0.60);

  o = vec4(col * pill * uHover, pill);
}`;

/* Downsample; optionally adding a second source (used to fold the rim into
   the bloom input).  Alpha rides along so the metal's coverage mask survives
   the blur chain. */
const FRAG_DOWN = `#version 300 es
precision highp float;
out vec4 o;
uniform sampler2D uTex, uTex2;
uniform vec2 uDstTexel;   // 1 / destination size  (maps dest fragCoord -> uv)
uniform vec2 uSrcTexel;   // 1 / source size       (tap spacing)
uniform float uAdd;       // 1 to include uTex2
void main(){
  vec2 uv = gl_FragCoord.xy * uDstTexel;
  // Taps sit a quarter of a *destination* texel out, so for a 2x reduction
  // they land exactly on the four source texel centres.  Spacing them by a
  // whole source texel instead — as this did originally — skips every other
  // pixel, and any fine detail in the field folds down into low-frequency
  // moiré that no amount of subsequent blurring can remove.
  vec2 e = uDstTexel * 0.25;
  vec4 s = texture(uTex, uv + vec2(-e.x,-e.y)) + texture(uTex, uv + vec2( e.x,-e.y))
         + texture(uTex, uv + vec2(-e.x, e.y)) + texture(uTex, uv + vec2( e.x, e.y));
  s *= 0.25;
  if(uAdd > 0.5){
    vec4 r = texture(uTex2, uv + vec2(-e.x,-e.y)) + texture(uTex2, uv + vec2( e.x,-e.y))
           + texture(uTex2, uv + vec2(-e.x, e.y)) + texture(uTex2, uv + vec2( e.x, e.y));
    s.rgb += r.rgb * 0.25;
  }
  o = s;
}`;

const FRAG_BLUR = `#version 300 es
precision highp float;
out vec4 o;
uniform sampler2D uTex; uniform vec2 uTexel; uniform vec2 uDir; uniform float uR;
void main(){
  vec2 uv = gl_FragCoord.xy * uTexel;
  vec2 st = uTexel * uDir * uR;
  vec4 s = texture(uTex, uv) * 0.1964;
  s += (texture(uTex, uv + st*1.4118) + texture(uTex, uv - st*1.4118)) * 0.2969;
  s += (texture(uTex, uv + st*3.2941) + texture(uTex, uv - st*3.2941)) * 0.0944;
  s += (texture(uTex, uv + st*5.1765) + texture(uTex, uv - st*5.1765)) * 0.0104;
  o = s;
}`;

const FRAG_COMP =
  HEAD +
  `
uniform sampler2D uSoft, uRim, uGlow;
uniform vec2  uRes;
uniform float uGlowGain, uGlowIn, uOccl, uDim, uPunch;

void main(){
  vec2 uv = gl_FragCoord.xy / uRes;
  vec3 glow = texture(uGlow, uv).rgb;

  vec2  d    = gl_FragCoord.xy - uC;
  float sd   = sdPill(d, uHalf, uHalf.y);
  float pill = 1. - smoothstep(-1., 1., sd);

  // normalised blur: dividing by the blurred coverage keeps the softened metal
  // full strength right up to the edge instead of fading into the mask
  vec4 m = texture(uSoft, uv);

  // Scrim, applied *after* the blur: knock the metal back through the middle
  // where the label sits, leaving the top and bottom at full brightness.  Doing
  // this before the blur would smear the protection away at high blur values.
  float veil = 1. - smoothstep(0.46, 0.88, abs(d.y) / uHalf.y);

  // Blurring flattens the tonal range into a wash; putting the contrast back
  // with a power curve — after the blur, so it costs no smoothness — is what
  // makes it read as poured metal rather than a soft glow.  Highlights keep
  // their level while the mid-tones drop away.
  vec3 metal = pow(max(m.rgb / max(m.a, 1e-3), 0.), vec3(uPunch));

  vec3 core = metal * pill * mix(1., uDim, veil) + texture(uRim, uv).rgb;

  // The ripple's own light is added here, after the blur, so the crease stays
  // a hard line.  Its displacement of the field still rides inside the
  // softened metal — the sheet bows, and the crest glints along the fold.
  float rip = ripple(vec2(d.x, -d.y) / (uHalf.y * 2.), uT);
  core += vec3(rip * rip) * uRipK2.w * pill * mix(1., 0.42, veil);

  // The button occludes its own bloom over the patch where its shadow falls,
  // so the drop shadow keeps its contrast even when the face is blown out.
  float sdSh = sdPill(d + vec2(0., uHalf.y * 0.62), uHalf * 0.94, uHalf.y * 0.94);
  float occl = uOccl * exp(-max(sdSh, 0.) / (uHalf.y * 0.75));

  // Bloom spills mostly outward; a little of it is allowed back inside so the
  // hot rim bleeds onto the face, as it does on the reference component.
  vec3 rgb = core + glow * uGlowGain * mix(1., uGlowIn, pill) * (1. - occl * (1. - pill));

  // premultiplied — the page's ambient pool and the button's drop shadow are
  // CSS underneath, and this layer adds light on top of them
  float a = clamp(max(rgb.r, max(rgb.g, rgb.b)), 0., 1.);
  o = vec4(min(rgb, vec3(1.)), a);
}`;

// the metal field — uP[0..20]
const P = {
  valFreq: 0.5,
  valAmp: 0.55,
  dens: 2.4,
  densVar: 2.2,
  densFreq: 0.32,
  wobAmp: 0.12,
  wobFreq: 1.6,
  lift: 0.05,
  refract: 0.18,
  edge: 0.04,
  width: 0.46,
  disp: 0.3,
  skew: 1.5,
  fineAmp: 0.0,
  fineFreq: 9.0,
  gamma: 1.0,
  gain: 1.9,
  octGain: 0.32,
  litLo: -0.26,
  litHi: 0.1,
  dim: 0.44,
};
// the animated rim — uE[0..7]
const E = {
  base: 0.2,
  hot: 0.82,
  chromA: 0.42,
  chromS: 0.03,
  speed: 0.07,
  top: 0.35,
  press: 0.85,
  ripple: 1.6,
};
// composite / JS-side only
const C = { glow: 1.95, glowR: 1.3, glowIn: 0.3, occl: 0.62, soften: 0.24, punch: 1.5 };
// disturbances — all distances in button heights, times in seconds
const R = {
  speed: 1.85,
  width: 0.2,
  decay: 1.35,
  amp: 1.35,
  facet: 0.18,
  lobes: 6.0,
  sharp: 1.15,
  emit: 0.45,
  ptrRad: 0.55,
  ptrAmp: 0.32,
  ptrFast: 0.4,
  ptrRim: 0.8,
  ptrLag: 0.0016,
  ptrVref: 4.5,
};
const P_ARR = new Float32Array(Object.values(P));
const E_ARR = new Float32Array(Object.values(E));

const PLATE_SHADOW = {
  rest: {
    background: "color-mix(in srgb, hsl(var(--primary)) 22%, black)",
    boxShadow:
      "0 calc(var(--h) * 0.10) calc(var(--h) * 0.22) hsl(var(--foreground) / .28), 0 calc(var(--h) * 0.30) calc(var(--h) * 0.66) hsl(var(--foreground) / .18), 0 calc(var(--h) * 0.62) calc(var(--h) * 1.30) hsl(var(--foreground) / .1)",
  },
  hot: {
    background: "color-mix(in srgb, hsl(var(--primary)) 16%, black)",
    boxShadow:
      "0 calc(var(--h) * 0.12) calc(var(--h) * 0.26) hsl(var(--primary) / .4), 0 calc(var(--h) * 0.40) calc(var(--h) * 0.86) hsl(var(--foreground) / .28), 0 calc(var(--h) * 0.86) calc(var(--h) * 1.80) hsl(var(--primary) / .16)",
  },
  press: {
    background: "color-mix(in srgb, hsl(var(--primary)) 12%, black)",
    boxShadow:
      "0 calc(var(--h) * 0.05) calc(var(--h) * 0.13) hsl(var(--foreground) / .3), 0 calc(var(--h) * 0.16) calc(var(--h) * 0.40) hsl(var(--foreground) / .2), 0 calc(var(--h) * 0.34) calc(var(--h) * 0.80) hsl(var(--foreground) / .1)",
  },
};

const STYLES = `
.m-lmb-btn:focus-visible{outline:calc(4 * var(--u)) solid hsl(var(--primary));outline-offset:calc(10 * var(--u))}
.m-lmb-play .m-lmb-btn:focus-visible{outline:2px solid hsl(var(--primary));outline-offset:4px}
`;

type Target = { tex: WebGLTexture; fbo: WebGLFramebuffer; w: number; h: number };
type Prog = { p: WebGLProgram; u: Record<string, WebGLUniformLocation | null> };

function clampNum(value: number, min: number, max: number, fallback: number) {
  return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
}

export function PrismFlowButton({
  variant = "pill",
  rendering = "colored",
  diameter = 88,
  strokeWidth = 3,
  text,
  embedded = false,
  onClick,
  className,
}: PrismFlowButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const stageRef = useRef<HTMLDivElement>(null);
  const plateRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const btnRef = useRef<HTMLButtonElement>(null);
  const calmRef = useRef(false);
  calmRef.current = !!prefersReducedMotion;
  const strokeRef = useRef(3);

  const safeVariant = variant === "circle" || variant === "play" ? variant : "pill";
  const isPlay = safeVariant === "play";
  const safeText = String(
    text ?? (safeVariant === "pill" ? "Get the build" : safeVariant === "circle" ? "Add" : "Play"),
  ).slice(0, 24);
  const playDiameter = clampNum(diameter, 72, 160, 88);
  strokeRef.current = clampNum(strokeWidth, 1, 8, 3);

  const stageStyle: Record<string, string> = isPlay
    ? { "--h": `${playDiameter}px`, "--bw": "var(--h)" }
    : safeVariant === "circle"
      ? { "--h": "clamp(56px, 10vmin, 72px)", "--bw": "var(--h)" }
      : {
          "--h": "52px",
          "--bw": `calc(${Math.min(3000, Math.max(1407, 820 + safeText.length * 94))} * var(--u))`,
        };

  useEffect(() => {
    const cv = canvasRef.current;
    const stage = stageRef.current;
    const btn = btnRef.current;
    const plate = plateRef.current;
    const root = rootRef.current;
    if (!cv || !stage || !btn || !plate || !root) return;
    const gl = cv.getContext("webgl2", {
      alpha: true,
      antialias: false,
      premultipliedAlpha: true,
      powerPreference: "high-performance",
    });
    if (!gl) return;

    function sh(type: number, src: string) {
      const s = gl!.createShader(type)!;
      gl!.shaderSource(s, src);
      gl!.compileShader(s);
      if (!gl!.getShaderParameter(s, gl!.COMPILE_STATUS))
        throw new Error(gl!.getShaderInfoLog(s) + "\n" + src);
      return s;
    }
    const shaders: WebGLShader[] = [];
    function prog(fs: string): Prog {
      const p = gl!.createProgram()!;
      const vs = sh(gl!.VERTEX_SHADER, VERT);
      const f = sh(gl!.FRAGMENT_SHADER, fs);
      shaders.push(vs, f);
      gl!.attachShader(p, vs);
      gl!.attachShader(p, f);
      gl!.bindAttribLocation(p, 0, "position");
      gl!.linkProgram(p);
      if (!gl!.getProgramParameter(p, gl!.LINK_STATUS))
        throw new Error(gl!.getProgramInfoLog(p) ?? "link failed");
      const u: Prog["u"] = {};
      const n = gl!.getProgramParameter(p, gl!.ACTIVE_UNIFORMS);
      for (let i = 0; i < n; i++) {
        const info = gl!.getActiveUniform(p, i)!;
        u[info.name.replace("[0]", "")] = gl!.getUniformLocation(p, info.name);
      }
      return { p, u };
    }
    const pScene = prog(FRAG_SCENE),
      pRim = prog(FRAG_RIM),
      pDown = prog(FRAG_DOWN),
      pBlur = prog(FRAG_BLUR),
      pComp = prog(FRAG_COMP);

    const vao = gl.createVertexArray();
    gl.bindVertexArray(vao);
    const vbo = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
    gl.enableVertexAttribArray(0);
    gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);

    const hasFloat = !!gl.getExtension("EXT_color_buffer_half_float");
    const targets: Target[] = [];
    function makeTarget(): Target {
      const tex = gl!.createTexture()!;
      gl!.bindTexture(gl!.TEXTURE_2D, tex);
      gl!.texParameteri(gl!.TEXTURE_2D, gl!.TEXTURE_MIN_FILTER, gl!.LINEAR);
      gl!.texParameteri(gl!.TEXTURE_2D, gl!.TEXTURE_MAG_FILTER, gl!.LINEAR);
      gl!.texParameteri(gl!.TEXTURE_2D, gl!.TEXTURE_WRAP_S, gl!.CLAMP_TO_EDGE);
      gl!.texParameteri(gl!.TEXTURE_2D, gl!.TEXTURE_WRAP_T, gl!.CLAMP_TO_EDGE);
      const fbo = gl!.createFramebuffer()!;
      gl!.bindFramebuffer(gl!.FRAMEBUFFER, fbo);
      gl!.framebufferTexture2D(gl!.FRAMEBUFFER, gl!.COLOR_ATTACHMENT0, gl!.TEXTURE_2D, tex, 0);
      const t = { tex, fbo, w: 0, h: 0 };
      targets.push(t);
      return t;
    }
    function sizeTarget(t: Target, w: number, h: number) {
      if (t.w === w && t.h === h) return;
      t.w = w;
      t.h = h;
      gl!.bindTexture(gl!.TEXTURE_2D, t.tex);
      if (hasFloat)
        gl!.texImage2D(gl!.TEXTURE_2D, 0, gl!.RGBA16F, w, h, 0, gl!.RGBA, gl!.HALF_FLOAT, null);
      else gl!.texImage2D(gl!.TEXTURE_2D, 0, gl!.RGBA8, w, h, 0, gl!.RGBA, gl!.UNSIGNED_BYTE, null);
    }
    const T_core = makeTarget(),
      T_rim = makeTarget(),
      T_s1 = makeTarget(),
      T_s2 = makeTarget(),
      T_a = makeTarget(),
      T_b = makeTarget();

    let W = 0,
      H = 0,
      DPR = 1,
      BW = 0,
      BH = 0,
      CX = 0,
      CY = 0;
    let DOWN = 4;
    const GLOW_TEX = 129;
    let needResize = true;

    function resize() {
      const r = stage!.getBoundingClientRect();
      const br = btn!.getBoundingClientRect();
      DPR = Math.min(window.devicePixelRatio || 1, 2);
      const w = Math.max(2, Math.round(r.width * DPR));
      const h = Math.max(2, Math.round(r.height * DPR));
      if (w !== W || h !== H) {
        W = w;
        H = h;
        cv!.width = W;
        cv!.height = H;
      }
      BW = br.width * DPR;
      BH = br.height * DPR;
      CX = (br.left - r.left) * DPR + BW / 2;
      CY = H - ((br.top - r.top) * DPR + BH / 2);
      sizeTarget(T_core, W, H);
      sizeTarget(T_rim, W, H);
      const hw = Math.max(2, Math.ceil(W / 2)),
        hh = Math.max(2, Math.ceil(H / 2));
      sizeTarget(T_s1, hw, hh);
      sizeTarget(T_s2, hw, hh);
      DOWN = Math.max(1, Math.min(4, Math.round(BH / GLOW_TEX)));
      const dw = Math.max(2, Math.ceil(W / DOWN)),
        dh = Math.max(2, Math.ceil(H / DOWN));
      sizeTarget(T_a, dw, dh);
      sizeTarget(T_b, dw, dh);
      needResize = false;
    }
    const ro = new ResizeObserver(() => {
      needResize = true;
    });
    ro.observe(stage);

    function drawTo(t: Target | null) {
      gl!.bindFramebuffer(gl!.FRAMEBUFFER, t ? t.fbo : null);
      gl!.viewport(0, 0, t ? t.w : W, t ? t.h : H);
      gl!.drawArrays(gl!.TRIANGLES, 0, 3);
    }

    let hover = 0,
      hoverTarget = 0,
      clock = 0,
      last = performance.now();
    const RIP = [0, 1, 2].map(() => ({ x: 0, y: 0, t: -99, on: 0 }));
    const ripArr = new Float32Array(12);
    let ripNext = 0,
      press = 0,
      pressTarget = 0;
    const ptr = { x: 0, y: 0 },
      ptrS = { x: 0, y: 0 };
    let ptrAmt = 0,
      ptrSpeed = 0;
    const on = { over: false, press: false, focus: false };

    function addRipple(x: number, y: number) {
      const r = RIP[ripNext];
      ripNext = (ripNext + 1) % RIP.length;
      r.x = x;
      r.y = y;
      r.t = clock;
      r.on = 1;
    }
    function localPt(e: PointerEvent): [number, number] {
      const b = btn!.getBoundingClientRect(),
        s = b.height;
      return [(e.clientX - (b.left + b.width / 2)) / s, (e.clientY - (b.top + b.height / 2)) / s];
    }

    let drawn: string | null = null;
    let raf = 0;
    let running = false;

    function frame(now: number) {
      const dtRaw = (now - last) / 1000;
      last = now;
      const dt = Math.min(dtRaw, 1 / 20);
      const calm = calmRef.current;
      if (!calm) clock += dt;

      const k = hoverTarget > hover ? 1 - Math.pow(0.0012, dt) : 1 - Math.pow(0.00012, dt);
      hover += (hoverTarget - hover) * k;
      if (Math.abs(hoverTarget - hover) < 0.0008) hover = hoverTarget;

      const pk = pressTarget > press ? 1 - Math.pow(1e-9, dt) : 1 - Math.pow(0.004, dt);
      press += (pressTarget - press) * pk;
      if (Math.abs(pressTarget - press) < 0.002) press = pressTarget;

      for (let i = 0; i < RIP.length; i++) {
        const r = RIP[i];
        if (r.on && clock - r.t > 4) r.on = 0;
        ripArr[i * 4] = r.x;
        ripArr[i * 4 + 1] = r.y;
        ripArr[i * 4 + 2] = r.t;
        ripArr[i * 4 + 3] = r.on;
      }
      const ripLive = RIP.some((r) => r.on);

      const lag = 1 - Math.pow(R.ptrLag, dt);
      const dx = (ptr.x - ptrS.x) * lag,
        dy = (ptr.y - ptrS.y) * lag;
      ptrS.x += dx;
      ptrS.y += dy;
      const inst = Math.min(Math.hypot(dx, dy) / Math.max(dt, 1e-3) / R.ptrVref, 1);
      ptrSpeed += (inst - ptrSpeed) * (1 - Math.pow(inst > ptrSpeed ? 0.001 : 0.02, dt));
      const wantWell = on.over || on.press ? 1 : 0;
      ptrAmt += (wantWell - ptrAmt) * (1 - Math.pow(0.004, dt));
      if (Math.abs(wantWell - ptrAmt) < 0.002) ptrAmt = wantWell;

      if (needResize) resize();

      const sig = calm && !ripLive && ptrAmt < 0.002 ? `${hover}|${press}|${W}|${H}` : null;
      if (sig !== null && sig === drawn) {
        raf = requestAnimationFrame(frame);
        return;
      }
      drawn = sig;

      const bw = isPlay
        ? Math.max(0.5 * DPR, strokeRef.current * DPR * 0.5)
        : Math.max(1.5, 3.2 * (BH / 516));

      // 1. metal, masked to the pill
      gl!.useProgram(pScene.p);
      gl!.uniform2f(pScene.u.uC, CX, CY);
      gl!.uniform2f(pScene.u.uHalf, BW / 2, BH / 2);
      gl!.uniform1f(pScene.u.uT, clock);
      gl!.uniform1f(pScene.u.uHover, hover);
      gl!.uniform1f(pScene.u.uPress, press);
      gl!.uniform4fv(pScene.u.uRip, ripArr);
      gl!.uniform4f(pScene.u.uRipK, R.speed, R.width, R.decay, R.amp);
      gl!.uniform4f(pScene.u.uRipK2, R.facet, R.lobes, R.sharp, R.emit);
      gl!.uniform4f(pScene.u.uPtr, ptrS.x, ptrS.y, ptrAmt, ptrSpeed);
      gl!.uniform4f(pScene.u.uPtrK, R.ptrRad, R.ptrAmp, R.ptrFast, R.ptrRim);
      gl!.uniform1fv(pScene.u.uP, P_ARR);
      drawTo(T_core);

      // 2. rim, kept out of the softening blur so the outline stays razor thin
      gl!.useProgram(pRim.p);
      gl!.uniform2f(pRim.u.uC, CX, CY);
      gl!.uniform2f(pRim.u.uHalf, BW / 2, BH / 2);
      gl!.uniform1f(pRim.u.uT, clock);
      gl!.uniform1f(pRim.u.uBw, bw);
      gl!.uniform1f(pRim.u.uPress, press);
      gl!.uniform4fv(pRim.u.uRip, ripArr);
      gl!.uniform4f(pRim.u.uRipK, R.speed, R.width, R.decay, R.amp);
      gl!.uniform4f(pRim.u.uRipK2, R.facet, R.lobes, R.sharp, R.emit);
      gl!.uniform4f(pRim.u.uPtr, ptrS.x, ptrS.y, ptrAmt, ptrSpeed);
      gl!.uniform4f(pRim.u.uPtrK, R.ptrRad, R.ptrAmp, R.ptrFast, R.ptrRim);
      gl!.uniform1fv(pRim.u.uE, E_ARR);
      drawTo(T_rim);

      // 3. soften the metal — half-res box down, then a separable gaussian
      gl!.useProgram(pDown.p);
      gl!.activeTexture(gl!.TEXTURE0);
      gl!.bindTexture(gl!.TEXTURE_2D, T_core.tex);
      gl!.uniform1i(pDown.u.uTex, 0);
      gl!.uniform1f(pDown.u.uAdd, 0);
      gl!.uniform2f(pDown.u.uDstTexel, 1 / T_s1.w, 1 / T_s1.h);
      gl!.uniform2f(pDown.u.uSrcTexel, 1 / W, 1 / H);
      drawTo(T_s1);

      gl!.useProgram(pBlur.p);
      gl!.uniform1i(pBlur.u.uTex, 0);
      gl!.uniform2f(pBlur.u.uTexel, 1 / T_s1.w, 1 / T_s1.h);
      const sigTex = C.soften * (BH * 0.5) * 0.95;
      if (sigTex > 0.1) {
        const iters = Math.min(4, Math.max(1, Math.ceil(sigTex / 3.0)));
        gl!.uniform1f(pBlur.u.uR, sigTex / Math.sqrt(iters) / 1.95);
        for (let i = 0; i < iters; i++) {
          gl!.bindTexture(gl!.TEXTURE_2D, T_s1.tex);
          gl!.uniform2f(pBlur.u.uDir, 1, 0);
          drawTo(T_s2);
          gl!.bindTexture(gl!.TEXTURE_2D, T_s2.tex);
          gl!.uniform2f(pBlur.u.uDir, 0, 1);
          drawTo(T_s1);
        }
      }

      // 4. bloom, fed by the softened metal plus the crisp rim
      gl!.useProgram(pDown.p);
      gl!.activeTexture(gl!.TEXTURE0);
      gl!.bindTexture(gl!.TEXTURE_2D, T_s1.tex);
      gl!.activeTexture(gl!.TEXTURE1);
      gl!.bindTexture(gl!.TEXTURE_2D, T_rim.tex);
      gl!.uniform1i(pDown.u.uTex, 0);
      gl!.uniform1i(pDown.u.uTex2, 1);
      gl!.uniform1f(pDown.u.uAdd, 1);
      gl!.uniform2f(pDown.u.uDstTexel, 1 / T_a.w, 1 / T_a.h);
      gl!.uniform2f(pDown.u.uSrcTexel, 1 / T_s1.w, 1 / T_s1.h);
      drawTo(T_a);

      gl!.useProgram(pBlur.p);
      gl!.activeTexture(gl!.TEXTURE0);
      gl!.uniform1i(pBlur.u.uTex, 0);
      gl!.uniform2f(pBlur.u.uTexel, 1 / T_a.w, 1 / T_a.h);
      const rs = (C.glowR * (BH / DOWN)) / GLOW_TEX;
      for (const r of [1.0, 2.3, 5.2, 9.0].map((v) => v * rs)) {
        gl!.uniform1f(pBlur.u.uR, r);
        gl!.bindTexture(gl!.TEXTURE_2D, T_a.tex);
        gl!.uniform2f(pBlur.u.uDir, 1, 0);
        drawTo(T_b);
        gl!.bindTexture(gl!.TEXTURE_2D, T_b.tex);
        gl!.uniform2f(pBlur.u.uDir, 0, 1);
        drawTo(T_a);
      }

      // 5. composite
      gl!.useProgram(pComp.p);
      gl!.activeTexture(gl!.TEXTURE0);
      gl!.bindTexture(gl!.TEXTURE_2D, T_s1.tex);
      gl!.uniform1i(pComp.u.uSoft, 0);
      gl!.activeTexture(gl!.TEXTURE1);
      gl!.bindTexture(gl!.TEXTURE_2D, T_rim.tex);
      gl!.uniform1i(pComp.u.uRim, 1);
      gl!.activeTexture(gl!.TEXTURE2);
      gl!.bindTexture(gl!.TEXTURE_2D, T_a.tex);
      gl!.uniform1i(pComp.u.uGlow, 2);
      gl!.uniform2f(pComp.u.uRes, W, H);
      gl!.uniform2f(pComp.u.uC, CX, CY);
      gl!.uniform2f(pComp.u.uHalf, BW / 2, BH / 2);
      gl!.uniform1f(pComp.u.uT, clock);
      gl!.uniform4fv(pComp.u.uRip, ripArr);
      gl!.uniform4f(pComp.u.uRipK, R.speed, R.width, R.decay, R.amp);
      gl!.uniform4f(pComp.u.uRipK2, R.facet, R.lobes, R.sharp, R.emit);
      gl!.uniform1f(pComp.u.uGlowGain, C.glow);
      gl!.uniform1f(pComp.u.uGlowIn, C.glowIn);
      gl!.uniform1f(pComp.u.uOccl, C.occl);
      gl!.uniform1f(pComp.u.uDim, P.dim);
      gl!.uniform1f(pComp.u.uPunch, C.punch);
      drawTo(null);

      raf = requestAnimationFrame(frame);
    }

    /* ---------------- interaction ---------------- */
    const sync = () => {
      hoverTarget = on.over || on.press || on.focus ? 1 : 0;
      pressTarget = on.press ? 1 : 0;
      const s = on.press
        ? PLATE_SHADOW.press
        : hoverTarget > 0.5
          ? PLATE_SHADOW.hot
          : PLATE_SHADOW.rest;
      plate!.style.background = s.background;
      plate!.style.boxShadow = s.boxShadow;
      plate!.style.transitionDuration = on.press ? ".10s" : ".38s";
    };
    const onEnter = (e: PointerEvent) => {
      if (e.pointerType !== "mouse") return;
      [ptr.x, ptr.y] = localPt(e);
      ptrS.x = ptr.x;
      ptrS.y = ptr.y;
      ptrSpeed = 0;
      on.over = true;
      sync();
    };
    const onLeave = (e: PointerEvent) => {
      if (e.pointerType === "mouse") {
        on.over = false;
        sync();
      }
    };
    const onMove = (e: PointerEvent) => {
      if (!on.over && !on.press) return;
      [ptr.x, ptr.y] = localPt(e);
    };
    const onDown = (e: PointerEvent) => {
      [ptr.x, ptr.y] = localPt(e);
      on.press = true;
      sync();
      addRipple(ptr.x, ptr.y);
    };
    const onUp = () => {
      on.press = false;
      sync();
    };
    const onFocus = () => {
      on.focus = btn.matches(":focus-visible");
      sync();
    };
    const onBlur = () => {
      on.focus = false;
      sync();
    };
    const onKeyDown = (e: KeyboardEvent) => {
      if ((e.key !== "Enter" && e.key !== " ") || e.repeat) return;
      on.press = true;
      sync();
      addRipple(0, 0);
    };
    const onKeyUp = (e: KeyboardEvent) => {
      if (e.key !== "Enter" && e.key !== " ") return;
      on.press = false;
      sync();
    };
    btn.addEventListener("pointerenter", onEnter);
    btn.addEventListener("pointerleave", onLeave);
    window.addEventListener("pointermove", onMove, { passive: true });
    btn.addEventListener("pointerdown", onDown);
    window.addEventListener("pointerup", onUp);
    window.addEventListener("pointercancel", onUp);
    btn.addEventListener("focus", onFocus);
    btn.addEventListener("blur", onBlur);
    btn.addEventListener("keydown", onKeyDown);
    btn.addEventListener("keyup", onKeyUp);

    // pause off-screen and while the tab is hidden
    let visible = true;
    const update = () => {
      const want = visible && document.visibilityState !== "hidden";
      if (want && !running) {
        running = true;
        last = performance.now();
        drawn = null;
        raf = requestAnimationFrame(frame);
      } else if (!want && running) {
        running = false;
        cancelAnimationFrame(raf);
      }
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      update();
    });
    io.observe(root);
    document.addEventListener("visibilitychange", update);
    resize();
    update();

    return () => {
      running = false;
      cancelAnimationFrame(raf);
      io.disconnect();
      ro.disconnect();
      document.removeEventListener("visibilitychange", update);
      btn.removeEventListener("pointerenter", onEnter);
      btn.removeEventListener("pointerleave", onLeave);
      window.removeEventListener("pointermove", onMove);
      btn.removeEventListener("pointerdown", onDown);
      window.removeEventListener("pointerup", onUp);
      window.removeEventListener("pointercancel", onUp);
      btn.removeEventListener("focus", onFocus);
      btn.removeEventListener("blur", onBlur);
      btn.removeEventListener("keydown", onKeyDown);
      btn.removeEventListener("keyup", onKeyUp);
      for (const t of targets) {
        gl.deleteTexture(t.tex);
        gl.deleteFramebuffer(t.fbo);
      }
      for (const pr of [pScene, pRim, pDown, pBlur, pComp]) gl.deleteProgram(pr.p);
      for (const s of shaders) gl.deleteShader(s);
      gl.deleteBuffer(vbo);
      gl.deleteVertexArray(vao);
    };
  }, [safeVariant, isPlay]);

  const u = "var(--u)";
  return (
    <div
      ref={rootRef}
      className={cn(
        "relative grid h-full w-full place-items-center overflow-hidden",
        isPlay && "m-lmb-play",
        className,
      )}
      style={{
        background: embedded
          ? "hsl(var(--card))"
          : "radial-gradient(46vmax 32vmax at 50% 47%, hsl(var(--primary) / 0.1) 0%, hsl(var(--background)) 70%) hsl(var(--background))",
        fontFamily: "var(--font-body)",
        fontOpticalSizing: "auto",
        WebkitFontSmoothing: "antialiased",
      }}
    >
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <div
        ref={stageRef}
        style={
          {
            "--u": "calc(var(--h) / 516)",
            "--bh": "var(--h)",
            "--pad": "calc(900 * var(--u))",
            ...stageStyle,
            position: "relative",
            width: "calc(var(--bw) + 2 * var(--pad))",
            height: "calc(var(--bh) + 2 * var(--pad))",
            display: "grid",
            placeItems: "center",
            touchAction: "manipulation",
          } as CSSProperties
        }
      >
        <div
          ref={plateRef}
          aria-hidden="true"
          style={{
            position: "absolute",
            width: "var(--bw)",
            height: "var(--bh)",
            borderRadius: 999,
            ...PLATE_SHADOW.rest,
            transition:
              "box-shadow .38s cubic-bezier(.22,.61,.36,1), background .38s cubic-bezier(.22,.61,.36,1)",
          }}
        />
        <canvas
          ref={canvasRef}
          style={{
            position: "absolute",
            inset: 0,
            width: "100%",
            height: "100%",
            display: "block",
            filter: isPlay && rendering === "monotone" ? "grayscale(1) contrast(1.04)" : "none",
          }}
        />
        <button
          ref={btnRef}
          className="m-lmb-btn"
          type="button"
          aria-label={
            safeVariant === "pill"
              ? safeText || "Button"
              : safeText.trim() || (isPlay ? "Play" : "Add")
          }
          onClick={onClick}
          style={{
            position: "relative",
            width: "var(--bw)",
            height: "var(--bh)",
            border: 0,
            background: "none",
            padding: 0,
            borderRadius: 999,
            display: "flex",
            flexDirection: isPlay ? "column" : "row",
            alignItems: "center",
            justifyContent: "center",
            gap: safeVariant === "pill" ? `calc(88 * ${u})` : 0,
            color: "white",
            fontFamily: "inherit",
            fontWeight: 500,
            fontSize: `calc(207 * ${u})`,
            lineHeight: 1,
            letterSpacing: 0,
            cursor: "pointer",
            WebkitTapHighlightColor: "transparent",
            outline: "none",
          }}
        >
          {isPlay ? (
            <svg
              viewBox="0 0 48 48"
              aria-hidden="true"
              style={{
                width: "calc(var(--h) * .25)",
                height: "calc(var(--h) * .25)",
                display: "block",
                flex: "none",
                overflow: "visible",
                transform: "translateX(calc(var(--h) * .018))",
              }}
            >
              <path
                fill="currentColor"
                d="M15.5 10.75a2.2 2.2 0 0 1 3.32-1.9l18.04 13.25a2.35 2.35 0 0 1 0 3.8L18.82 39.15a2.2 2.2 0 0 1-3.32-1.9v-26.5Z"
              />
            </svg>
          ) : (
            <svg
              viewBox="0 0 115 115"
              aria-hidden="true"
              style={{
                width: safeVariant === "circle" ? "28%" : `calc(115 * ${u})`,
                height: safeVariant === "circle" ? "28%" : `calc(115 * ${u})`,
                display: "block",
                flex: "none",
                overflow: "visible",
              }}
            >
              <g stroke="currentColor" strokeWidth="17" strokeLinecap="round">
                <path d="M57.5 8.5 V106.5" />
                <path d="M8.5 57.5 H106.5" />
              </g>
            </svg>
          )}
          {safeVariant === "pill" ? (
            <span style={{ display: "block", transform: `translateY(calc(2 * ${u}))` }}>
              {safeText}
            </span>
          ) : null}
        </button>
      </div>
    </div>
  );
}
```

---

# Ember Tag

> A lanyard tag sketched in thousands of theme-ink embers, standing in light slanted rain above a waterline.

Install: `npx @modus-ui/cli add ember-tag`

A Canvas 2D particle scene in the theme's ink: thousands of embers in `--primary` trace the edges of a lanyard badge, curl noise plumes them into fur, slanted rain in `--muted-foreground` falls in front of and behind the card and a waterline reflects it. On paper the strokes multiply like ink; in dark mode they add up like light, and both follow the palette picker. Fills its positioned parent, pauses off screen and paints a still frame for reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ember-tag
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ember-tag.tsx`.
3. Paste the code.

## Usage

```tsx
import { EmberTag } from "@/components/ui/ember-tag";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full overflow-hidden">
      <EmberTag />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default                    | Description                                         |
| :---------------- | :------- | :------------------------- | :-------------------------------------------------- |
| `speed`           | `number` | `0.8`                      | Simulation speed multiplier (0 to 2).               |
| `particleAmount`  | `number` | `0.8`                      | Ember count multiplier (0.35 to 1.4).               |
| `rainAmount`      | `number` | `0.45`                     | Rain count multiplier (0 to 1.5).                   |
| `turbulence`      | `number` | `1.3`                      | Curl-noise turbulence multiplier (0 to 2).          |
| `spread`          | `number` | `1.25`                     | Ember trail spread multiplier (0.5 to 1.75).        |
| `backgroundColor` | `string` | `"hsl(var(--background))"` | Scene background colour; theme tokens are resolved. |
| `color`           | `string` | `"hsl(var(--primary))"`    | Ember colour; theme tokens are resolved.            |

## Source

`components/ui/ember-tag.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Spark Badge (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface EmberTagProps {
  /** Simulation speed multiplier (0 to 2). */
  speed?: number;
  /** Ember count multiplier (0.35 to 1.4). */
  particleAmount?: number;
  /** Rain count multiplier (0 to 1.5). */
  rainAmount?: number;
  /** Curl-noise turbulence multiplier (0 to 2). */
  turbulence?: number;
  /** Ember trail spread multiplier (0.5 to 1.75). */
  spread?: number;
  /** Scene background colour; `var(--token)` references are resolved from the theme. */
  backgroundColor?: string;
  /** Ember colour; `var(--token)` references are resolved from the theme. */
  color?: string;
  className?: string;
}

const TAU = Math.PI * 2;

/** Resolves `var(--token)` references against the document's theme, for use on a canvas. */
function resolveThemeColor(value: string) {
  const style = getComputedStyle(document.documentElement);
  return value.replace(/var\((--[\w-]+)\)/g, (_, name: string) =>
    style.getPropertyValue(name).trim(),
  );
}

/** True when the theme's background is dark, read from the lightness channel of `--background`. */
function themeIsDark() {
  const bg = getComputedStyle(document.documentElement).getPropertyValue("--background").trim();
  const lightness = parseFloat(bg.split(/\s+/)[2] ?? "100");
  return lightness < 50;
}

/* ------------------------------------------------------------------ *
 *  rng + noise
 * ------------------------------------------------------------------ */
function mulberry32(a: number) {
  return function () {
    a |= 0;
    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;
  };
}

const NS = 256,
  NM = NS - 1;
type Field = { cx: Float32Array; cy: Float32Array };

// tileable smooth scalar field -> its curl, precomputed once
function makeCurlField(seed: number): Field {
  const r = mulberry32(seed);
  const a = new Float32Array(NS * NS),
    b = new Float32Array(NS * NS);
  for (let i = 0; i < NS * NS; i++) a[i] = r();
  const R = 5;
  for (let p = 0; p < 3; p++) {
    for (let y = 0; y < NS; y++) {
      const o = y * NS;
      for (let x = 0; x < NS; x++) {
        let s = 0;
        for (let k = -R; k <= R; k++) s += a[o + ((x + k) & NM)];
        b[o + x] = s / (2 * R + 1);
      }
    }
    for (let x = 0; x < NS; x++) {
      for (let y = 0; y < NS; y++) {
        let s = 0;
        for (let k = -R; k <= R; k++) s += b[((y + k) & NM) * NS + x];
        a[y * NS + x] = s / (2 * R + 1);
      }
    }
  }
  let mn = Infinity,
    mx = -Infinity;
  for (let i = 0; i < NS * NS; i++) {
    if (a[i] < mn) mn = a[i];
    if (a[i] > mx) mx = a[i];
  }
  const sc = 2 / (mx - mn);
  for (let i = 0; i < NS * NS; i++) a[i] = (a[i] - mn) * sc - 1;
  const cx = new Float32Array(NS * NS),
    cy = new Float32Array(NS * NS);
  const H = 2;
  let vmax = 0;
  for (let y = 0; y < NS; y++)
    for (let x = 0; x < NS; x++) {
      const dy = a[((y + H) & NM) * NS + x] - a[((y - H + NS) & NM) * NS + x];
      const dx = a[y * NS + ((x + H) & NM)] - a[y * NS + ((x - H + NS) & NM)];
      const i = y * NS + x;
      cx[i] = dy;
      cy[i] = -dx;
      const m = Math.abs(dy) + Math.abs(dx);
      if (m > vmax) vmax = m;
    }
  const inv = 1.9 / vmax;
  for (let i = 0; i < NS * NS; i++) {
    cx[i] *= inv;
    cy[i] *= inv;
  }
  return { cx, cy };
}

function curlSample(F: Field, x: number, y: number, out: number[] | Float32Array) {
  x *= NS;
  y *= NS;
  let x0 = Math.floor(x),
    y0 = Math.floor(y);
  const fx = x - x0,
    fy = y - y0;
  x0 &= NM;
  y0 &= NM;
  const x1 = (x0 + 1) & NM,
    y1 = (y0 + 1) & NM;
  const u = fx * fx * (3 - 2 * fx),
    v = fy * fy * (3 - 2 * fy);
  const i00 = y0 * NS + x0,
    i01 = y0 * NS + x1,
    i10 = y1 * NS + x0,
    i11 = y1 * NS + x1;
  const ax = F.cx[i00] + (F.cx[i01] - F.cx[i00]) * u,
    bx = F.cx[i10] + (F.cx[i11] - F.cx[i10]) * u;
  const ay = F.cy[i00] + (F.cy[i01] - F.cy[i00]) * u,
    by = F.cy[i10] + (F.cy[i11] - F.cy[i10]) * u;
  out[0] = ax + (bx - ax) * v;
  out[1] = ay + (by - ay) * v;
}

/* ------------------------------------------------------------------ *
 *  figure — authored in art space (0..1 square), rasterised to a mask
 * ------------------------------------------------------------------ */
const MW = 768;
const AY0 = -0.55,
  AH = 1.55;
const MH = Math.round(MW * AH);

/* Per-region emission: [ink, drift]. */
const EMPH: Record<string, [number, number]> = {
  base: [1.0, 0.8],
  strap: [1.35, 1.15],
  clip: [2.3, 0.42],
  card: [1.95, 0.55],
  slot: [2.0, 0.2],
  rule: [1.05, 0.15],
  word: [1.75, 0.17],
  edition: [1.8, 0.18],
  window: [1.7, 0.16],
  meta: [1.15, 0.15],
  name: [2.1, 0.18],
  tier: [1.85, 0.17],
  qr: [1.45, 0.2],
};
const B = 78;
const W2G = (k: string) => {
  const e = EMPH[k];
  const r = Math.max(0, Math.min(255, Math.round(e[0] * B)));
  const g = Math.max(0, Math.min(255, Math.round(e[1] * B)));
  return "rgb(" + r + "," + g + ",0)";
};

type Ctx = CanvasRenderingContext2D;

function buildMasks() {
  const solid = document.createElement("canvas");
  solid.width = MW;
  solid.height = MH;
  const emph = document.createElement("canvas");
  emph.width = MW;
  emph.height = MH;
  const gm = solid.getContext("2d")!;
  const ge = emph.getContext("2d", { willReadFrequently: true })!;
  ge.fillStyle = W2G("base");
  ge.fillRect(0, 0, MW, MH);

  const S = MW;
  gm.translate(0, -AY0 * S);
  ge.translate(0, -AY0 * S);
  const key = (k: string) => {
    const c = W2G(k);
    gm.fillStyle = "white";
    gm.strokeStyle = "white";
    ge.fillStyle = c;
    ge.strokeStyle = c;
  };
  const both = (fn: (c: Ctx) => void) => {
    fn(gm);
    fn(ge);
  };

  const rr = (c: Ctx, x0: number, y0: number, x1: number, y1: number, r: number) => {
    const X0 = x0 * S,
      Y0 = y0 * S,
      X1 = x1 * S,
      Y1 = y1 * S,
      R = r * S;
    c.beginPath();
    c.moveTo(X0 + R, Y0);
    c.arcTo(X1, Y0, X1, Y1, R);
    c.arcTo(X1, Y1, X0, Y1, R);
    c.arcTo(X0, Y1, X0, Y0, R);
    c.arcTo(X0, Y0, X1, Y0, R);
    c.closePath();
  };
  const poly = (c: Ctx, a: number[][]) => {
    c.beginPath();
    c.moveTo(a[0][0] * S, a[0][1] * S);
    for (let i = 1; i < a.length; i++) c.lineTo(a[i][0] * S, a[i][1] * S);
    c.closePath();
  };
  const SC = 1.12;
  const tilt = (c: Ctx) => {
    c.save();
    c.translate(0.5 * S, 0.862 * S);
    c.scale(SC, SC);
    c.translate(-0.5 * S, -0.862 * S);
    c.translate(0.5 * S, 0.3 * S);
    c.rotate(-0.048);
    c.translate(-0.5 * S, -0.3 * S);
  };

  /* ---- lanyard: two ribbons rising out of frame to the clip ---- */
  key("strap");
  both((c) => {
    poly(c, [
      [-0.315, -0.55],
      [-0.236, -0.55],
      [0.5, 0.208],
      [0.46, 0.208],
    ]);
    c.fill();
  });
  both((c) => {
    poly(c, [
      [1.236, -0.55],
      [1.315, -0.55],
      [0.54, 0.208],
      [0.5, 0.208],
    ]);
    c.fill();
  });

  /* ---- clip and card ---- */
  key("clip");
  both((c) => {
    tilt(c);
    rr(c, 0.4536, 0.248, 0.5464, 0.306, 0.01);
    c.fill();
    c.restore();
  });
  key("card");
  both((c) => {
    tilt(c);
    rr(c, 0.312, 0.296, 0.688, 0.862, 0.024);
    c.fill();
    c.restore();
  });

  // snapshot the un-carved silhouette for rain occlusion
  const occ = document.createElement("canvas");
  occ.width = MW;
  occ.height = MH;
  occ.getContext("2d")!.drawImage(solid, 0, 0);

  gm.globalCompositeOperation = "destination-out";
  gm.lineCap = "round";
  gm.lineJoin = "round";
  ge.lineCap = "round";
  ge.lineJoin = "round";

  const cutRR = (x0: number, y0: number, x1: number, y1: number, r: number, k: string) => {
    rr(gm, x0, y0, x1, y1, r);
    gm.fill();
    ge.fillStyle = W2G(k);
    ge.strokeStyle = W2G(k);
    ge.lineWidth = 0.019 * S;
    rr(ge, x0, y0, x1, y1, r);
    ge.fill();
    ge.stroke();
  };
  const frameRR = (
    x0: number,
    y0: number,
    x1: number,
    y1: number,
    r: number,
    w: number,
    k: string,
  ) => {
    gm.lineWidth = w * S;
    rr(gm, x0, y0, x1, y1, r);
    gm.stroke();
    ge.strokeStyle = W2G(k);
    ge.lineWidth = (w + 0.017) * S;
    rr(ge, x0, y0, x1, y1, r);
    ge.stroke();
  };
  const cutLine = (x0: number, y0: number, x1: number, y1: number, w: number, k: string) => {
    gm.lineWidth = w * S;
    gm.beginPath();
    gm.moveTo(x0 * S, y0 * S);
    gm.lineTo(x1 * S, y1 * S);
    gm.stroke();
    ge.strokeStyle = W2G(k);
    ge.lineWidth = (w + 0.016) * S;
    ge.beginPath();
    ge.moveTo(x0 * S, y0 * S);
    ge.lineTo(x1 * S, y1 * S);
    ge.stroke();
  };

  tilt(gm);
  tilt(ge);

  cutRR(0.462, 0.316, 0.538, 0.334, 0.009, "slot");
  cutRR(0.342, 0.356, 0.5, 0.386, 0.005, "word");
  cutRR(0.576, 0.362, 0.658, 0.379, 0.004, "edition");
  cutLine(0.342, 0.402, 0.658, 0.402, 0.0045, "rule");
  frameRR(0.342, 0.42, 0.658, 0.6, 0.007, 0.005, "window");
  cutLine(0.342, 0.626, 0.556, 0.626, 0.004, "meta");
  cutRR(0.342, 0.648, 0.604, 0.69, 0.005, "name");
  cutLine(0.342, 0.708, 0.54, 0.708, 0.004, "meta");
  cutLine(0.342, 0.744, 0.658, 0.744, 0.0045, "rule");
  cutRR(0.342, 0.764, 0.47, 0.802, 0.019, "tier");
  cutLine(0.342, 0.822, 0.45, 0.822, 0.0038, "meta");

  /* ---- data block ---- */
  (() => {
    const x0 = 0.54,
      y0 = 0.752,
      m = 0.0197;
    frameRR(x0, y0, x0 + m * 6, y0 + m * 5, 0.004, 0.0038, "qr");
    for (const [cxm, cym] of [
      [0, 0],
      [4, 0],
      [0, 3],
    ]) {
      const fx0 = x0 + (cxm + 0.35) * m,
        fy0 = y0 + (cym + 0.35) * m;
      frameRR(fx0, fy0, fx0 + m * 1.3, fy0 + m * 1.3, 0.0018, 0.0034, "qr");
    }
    const r = mulberry32(0x51de);
    for (let gy = 0; gy < 5; gy++)
      for (let gx = 0; gx < 6; gx++) {
        if ((gx < 2 && gy < 2) || (gx > 3 && gy < 2) || (gx < 2 && gy > 2)) continue;
        if (r() > 0.46) continue;
        const mx = x0 + (gx + 0.28) * m,
          my = y0 + (gy + 0.28) * m;
        cutRR(mx, my, mx + m * 0.62, my + m * 0.62, 0.0012, "qr");
      }
  })();

  /* ---- the window carries a serif wordmark in the theme heading face ---- */
  (() => {
    const family =
      getComputedStyle(document.documentElement).getPropertyValue("--font-heading").trim() ||
      "serif";
    const h = 0.1 * S;
    ge.strokeStyle = W2G("edition");
    gm.lineWidth = 0.0068 * S;
    ge.lineWidth = 0.019 * S;
    both((c) => {
      c.font = `italic ${h}px ${family}`;
      c.textAlign = "center";
      c.textBaseline = "middle";
      c.strokeText("Modus", 0.5 * S, 0.512 * S);
    });
  })();

  gm.restore();
  ge.restore();
  gm.globalCompositeOperation = "source-over";
  return { detail: solid, occ, emph };
}

/* ------------------------------------------------------------------ *
 *  emitters: silhouette edges of the mask, with outward normals
 * ------------------------------------------------------------------ */
function buildEmitters(
  maskCanvas: HTMLCanvasElement,
  emphCanvas: HTMLCanvasElement,
  rnd: () => number,
) {
  const d = maskCanvas.getContext("2d")!.getImageData(0, 0, MW, MH).data;
  const ed = emphCanvas.getContext("2d")!.getImageData(0, 0, MW, MH).data;
  const a = new Float32Array(MW * MH),
    b = new Float32Array(MW * MH);
  for (let i = 0; i < MW * MH; i++) a[i] = d[i * 4 + 3] / 255;
  const R = 2;
  for (let p = 0; p < 2; p++) {
    for (let y = 0; y < MH; y++) {
      const o = y * MW;
      for (let x = 0; x < MW; x++) {
        let s = 0,
          n = 0;
        for (let k = -R; k <= R; k++) {
          const xx = x + k;
          if (xx < 0 || xx >= MW) continue;
          s += a[o + xx];
          n++;
        }
        b[o + x] = s / n;
      }
    }
    for (let x = 0; x < MW; x++) {
      for (let y = 0; y < MH; y++) {
        let s = 0,
          n = 0;
        for (let k = -R; k <= R; k++) {
          const yy = y + k;
          if (yy < 0 || yy >= MH) continue;
          s += b[yy * MW + x];
          n++;
        }
        a[y * MW + x] = s / n;
      }
    }
  }
  const ex: number[] = [],
    ey: number[] = [],
    enx: number[] = [],
    eny: number[] = [],
    ew: number[] = [],
    ee: number[] = [],
    edr: number[] = [];
  for (let y = 1; y < MH - 1; y++)
    for (let x = 1; x < MW - 1; x++) {
      const i = y * MW + x;
      const gx = a[i + 1] - a[i - 1],
        gy = a[i + MW] - a[i - MW];
      const m = Math.hypot(gx, gy);
      if (m < 0.035) continue;
      const w = ed[i * 4] / 78,
        dr = ed[i * 4 + 1] / 78;
      ex.push(x / MW);
      ey.push(y / MW + AY0);
      enx.push(-gx / m);
      eny.push(-gy / m);
      ew.push(m * w);
      ee.push(w);
      edr.push(dr);
    }
  const n = ew.length,
    cdf = new Float32Array(n);
  let acc = 0;
  for (let i = 0; i < n; i++) {
    acc += ew[i];
    cdf[i] = acc;
  }
  return {
    n,
    total: acc,
    cdf,
    x: Float32Array.from(ex),
    y: Float32Array.from(ey),
    nx: Float32Array.from(enx),
    ny: Float32Array.from(eny),
    e: Float32Array.from(ee),
    dr: Float32Array.from(edr),
    pick() {
      const t = rnd() * this.total;
      let lo = 0,
        hi = this.n - 1;
      while (lo < hi) {
        const mid = (lo + hi) >> 1;
        if (this.cdf[mid] < t) lo = mid + 1;
        else hi = mid;
      }
      return lo;
    },
  };
}

const mk = (n: number) => ({
  x: new Float32Array(n),
  y: new Float32Array(n),
  nx: new Float32Array(n),
  ny: new Float32Array(n),
  rx: new Float32Array(n),
  ry: new Float32Array(n),
  spd: new Float32Array(n),
  len: new Float32Array(n),
  br: new Float32Array(n),
  seed: new Float32Array(n),
  style: new Uint8Array(n),
  life: new Float32Array(n),
  max: new Float32Array(n),
  vx: new Float32Array(n),
  vy: new Float32Array(n),
  pin: new Float32Array(n),
  age: new Float32Array(n),
  k: new Uint8Array(n),
});
type Pool = ReturnType<typeof mk>;

export function EmberTag({
  speed = 0.8,
  particleAmount = 0.8,
  rainAmount = 0.45,
  turbulence = 1.3,
  spread = 1.25,
  backgroundColor = "hsl(var(--background))",
  color = "hsl(var(--primary))",
  className,
}: EmberTagProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const controls = useRef({
    speed,
    particleAmount,
    rainAmount,
    turbulence,
    spread,
    backgroundColor,
    color,
  });
  const applyRef = useRef<() => void>(() => {});

  useEffect(() => {
    const c = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
    controls.current = {
      speed: c(speed, 0, 2),
      particleAmount: c(particleAmount, 0.35, 1.4),
      rainAmount: c(rainAmount, 0, 1.5),
      turbulence: c(turbulence, 0, 2),
      spread: c(spread, 0.5, 1.75),
      backgroundColor,
      color,
    };
    applyRef.current();
  }, [speed, particleAmount, rainAmount, turbulence, spread, backgroundColor, color]);

  useEffect(() => {
    const host = hostRef.current;
    const cv = canvasRef.current;
    if (!host || !cv) return;
    const ctx = cv.getContext("2d")!;
    const theme = { bg: "", ink: "", rain: "", blend: "lighter" as GlobalCompositeOperation };
    const readTheme = () => {
      theme.bg = resolveThemeColor(controls.current.backgroundColor);
      theme.ink = resolveThemeColor(controls.current.color);
      theme.rain = resolveThemeColor("hsl(var(--muted-foreground))");
      theme.blend = themeIsDark() ? "lighter" : "multiply";
    };
    readTheme();
    const themeObserver = new MutationObserver(() => applyRef.current());
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    const rnd = mulberry32(0x5eed12);
    const F1 = makeCurlField(0x1234),
      F2 = makeCurlField(0x9abc);
    const _cv = [0, 0];
    let CT = 0;
    function curlAt(x: number, y: number, out: Float32Array) {
      curlSample(F1, x * 1.3 + CT * 0.011, y * 1.3 - CT * 0.019, _cv);
      const ox = _cv[0],
        oy = _cv[1];
      curlSample(F2, x * 3.05 - CT * 0.026, y * 3.05 + CT * 0.015, _cv);
      out[0] = ox + _cv[0] * 0.45;
      out[1] = oy + _cv[1] * 0.45;
    }

    let VW = 0,
      VH = 0,
      DPR = 1,
      ART = { x: 0, y: 0, s: 0 },
      LW = 1,
      WATER = 0;
    const WANG = (60 * Math.PI) / 180;
    const WIND = { x: Math.cos(WANG), y: Math.sin(WANG) };

    const MASKS = buildMasks();
    const EM = buildEmitters(MASKS.detail, MASKS.emph, rnd);

    const SEG = 0.0082;
    const NF0 = 17600,
      NR0 = 300,
      NW0 = 460,
      REF_S = 900;
    let NF = NF0,
      NR = NR0,
      NW = NW0;
    let BASE_NF = NF0,
      BASE_NR = NR0,
      BASE_NW = NW0;
    const CAP_F = 40000,
      CAP_R = 1400,
      CAP_W = 1600;

    function applyParticleCounts() {
      const k = controls.current;
      NF = Math.min(CAP_F, Math.max(1, Math.round(BASE_NF * k.particleAmount)));
      NR = Math.min(CAP_R, Math.max(0, Math.round(BASE_NR * k.rainAmount)));
      NW = Math.min(CAP_W, Math.max(1, Math.round(BASE_NW * k.particleAmount)));
    }

    const FUR = mk(CAP_F),
      RAIN = mk(CAP_R),
      WAT = mk(CAP_W);

    const pickStyle = () => {
      const r = rnd();
      return r < 0.46 ? 0 : r < 0.78 ? 1 : 2;
    };
    const stepsFor = (len: number, lo: number, hi: number) =>
      Math.max(lo, Math.min(hi, Math.round(len / (SEG * ART.s))));

    function pickHot() {
      let e = EM.pick();
      for (let t = 0; t < 3; t++) {
        curlSample(F1, EM.x[e] * 0.85 + CT * 0.045, EM.y[e] * 0.85 - CT * 0.03, _cv);
        const h = _cv[0] * 0.5 + 0.5;
        if (rnd() < h * h * 1.15) break;
        e = EM.pick();
      }
      return e;
    }

    function spawnFur(i: number, seeded: boolean) {
      const e = pickHot();
      const j = 0.0032 * ART.s;
      FUR.x[i] = ART.x + EM.x[e] * ART.s + (rnd() - 0.5) * j;
      FUR.y[i] = ART.y + EM.y[e] * ART.s + (rnd() - 0.5) * j;
      const em = EM.e[e],
        eb = Math.sqrt(em),
        dr = EM.dr[e];
      const pin = Math.max(0, Math.min(1, 1 - dr / 0.85));
      FUR.pin[i] = pin;
      const sp =
        rnd() < 0.58 + pin * 0.38
          ? (rnd() < 0.5 ? -1 : 1) * (1.44 + (rnd() - 0.5) * 0.42 * (1 - pin * 0.7))
          : (rnd() - 0.5) * 1.15;
      const cs = Math.cos(sp),
        sn = Math.sin(sp);
      FUR.rx[i] = EM.nx[e] * cs - EM.ny[e] * sn;
      FUR.ry[i] = EM.nx[e] * sn + EM.ny[e] * cs;
      FUR.nx[i] = FUR.rx[i];
      FUR.ny[i] = FUR.ry[i];
      FUR.spd[i] =
        ART.s * (0.01 + Math.pow(rnd(), 1.8) * 0.098) * (0.24 + dr * 0.9) * (1 - pin * 0.9);
      FUR.len[i] = ART.s * (0.0022 + Math.pow(rnd(), 2.3) * 0.011) * (1 - pin * 0.28);
      FUR.br[i] = (0.74 + rnd() * 0.94) * eb * (1 + pin * 0.3);
      FUR.max[i] = (0.17 + rnd() * 0.74) * (1 - pin * 0.55) * (0.75 + dr * 0.42);
      FUR.k[i] = stepsFor(FUR.len[i], 1, 6);
      FUR.seed[i] = rnd() * 1000;
      FUR.style[i] = pickStyle();
      FUR.life[i] = seeded ? rnd() * FUR.max[i] : FUR.max[i];
    }
    function spawnRain(i: number, seeded: boolean) {
      const sp = ART.s * (0.4 + Math.pow(rnd(), 1.2) * 0.46);
      RAIN.vx[i] = WIND.x * sp;
      RAIN.vy[i] = WIND.y * sp;
      const r = rnd();
      RAIN.len[i] = ART.s * (0.035 + Math.pow(r, 1.45) * 0.15);
      RAIN.br[i] = 0.3 + Math.pow(rnd(), 1.3) * 1.05;
      RAIN.k[i] = stepsFor(RAIN.len[i], 3, 14);
      RAIN.seed[i] = rnd() * 1000;
      RAIN.style[i] = rnd() < 0.74 ? 0 : rnd() < 0.6 ? 1 : 2;
      RAIN.pin[i] = rnd() < 0.24 ? 1 : 0;
      if (seeded) {
        RAIN.x[i] = rnd() * VW;
        RAIN.y[i] = rnd() * VH;
      } else {
        const skew = (WIND.x / WIND.y) * (VH + RAIN.len[i]);
        RAIN.x[i] = -skew + rnd() * (VW + skew);
        RAIN.y[i] = -RAIN.len[i] * WIND.y - rnd() * ART.s * 0.25;
      }
      RAIN.age[i] = 0;
    }
    function waveAt(x: number) {
      curlSample(F2, (x / ART.s) * 0.55 + CT * 0.02, 0.31, _cv);
      return _cv[0] * 0.011 * ART.s;
    }
    function spawnWater(i: number, seeded: boolean) {
      const yw = WATER;
      let x: number, y: number, br: number;
      const roll = rnd();
      if (roll < 0.34) {
        x = rnd() * VW;
        y = yw + waveAt(x) + (rnd() - 0.35) * 0.013 * ART.s;
        br = 0.58 + rnd() * 0.9;
      } else if (roll < 0.68) {
        const e = EM.pick();
        const ax = ART.x + EM.x[e] * ART.s,
          ay = ART.y + EM.y[e] * ART.s;
        x = ax + (rnd() - 0.5) * 0.05 * ART.s;
        y = yw + waveAt(x) + (yw - ay) * 0.34 + (rnd() - 0.5) * 0.014 * ART.s;
        br = 0.28 + rnd() * 0.62;
        if (y < yw + 0.004 * ART.s || y > VH) {
          x = rnd() * VW;
          y = yw + rnd() * Math.max(1, VH - yw);
        }
      } else {
        x = rnd() * VW;
        y = yw + waveAt(x) + Math.pow(rnd(), 2.2) * Math.max(1, VH - yw);
        br = 0.24 + rnd() * 0.66;
      }
      WAT.x[i] = x;
      WAT.y[i] = y;
      const dir = rnd() < 0.5 ? -1 : 1;
      WAT.nx[i] = dir;
      WAT.ny[i] = (rnd() - 0.5) * 0.1;
      WAT.len[i] = ART.s * (0.01 + Math.pow(rnd(), 2.0) * 0.135);
      WAT.br[i] = br;
      WAT.k[i] = stepsFor(WAT.len[i], 2, 14);
      WAT.seed[i] = rnd() * 1000;
      WAT.style[i] = rnd() < 0.3 ? 0 : rnd() < 0.5 ? 1 : 2;
      WAT.max[i] = 0.6 + rnd() * 1.6;
      WAT.life[i] = seeded ? rnd() * WAT.max[i] : WAT.max[i];
    }

    function layout(cw: number, ch: number) {
      DPR = Math.min(2, window.devicePixelRatio || 1);
      VW = Math.round(cw * DPR);
      VH = Math.round(ch * DPR);
      cv!.width = VW;
      cv!.height = VH;
      const s = Math.min(VW, VH);
      ART = { x: (VW - s) / 2, y: VH * 0.87 - 0.888 * s, s };
      WATER = ART.y + 0.888 * s;
      LW = Math.max(0.85, (s / 1280) * 1.05);
      const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
      const D = clamp(Math.pow(s / REF_S, 0.55), 0.6, 1.9);
      BASE_NF = Math.min(CAP_F, Math.round(NF0 * D));
      BASE_NR = Math.min(CAP_R, Math.round(NR0 * D * clamp((VW * VH) / (s * s), 0.6, 3.0)));
      BASE_NW = Math.min(CAP_W, Math.round(NW0 * D * clamp(VW / s, 0.6, 3.0)));
      applyParticleCounts();
      for (let i = 0; i < CAP_F; i++) spawnFur(i, true);
      for (let i = 0; i < CAP_R; i++) spawnRain(i, true);
      for (let i = 0; i < CAP_W; i++) spawnWater(i, true);
    }

    /* ---- draw ---- */
    const LEVELS = [0.19, 0.31, 0.47, 0.68, 0.97];
    const DASHES = [[], [3.2, 3.4], [1.15, 4.6]];
    const NB = LEVELS.length * DASHES.length;
    const paths: Path2D[] = new Array(NB);
    const cur = new Float32Array(2);

    function levelOf(a: number) {
      if (a < 0.26) return 0;
      if (a < 0.39) return 1;
      if (a < 0.57) return 2;
      if (a < 0.82) return 3;
      return 4;
    }
    function lit(seed: number, k: number) {
      const v = Math.sin((seed + k * 1.7) * 127.1) * 43758.5453;
      return v - Math.floor(v) > 0.28;
    }
    function emit(
      style: number,
      lvl: number,
      moved: boolean,
      x: number,
      y: number,
      px: number,
      py: number,
    ) {
      const p = paths[style * LEVELS.length + lvl];
      if (moved) p.moveTo(px, py);
      p.lineTo(x, y);
    }

    let turb = 1,
      spr = 1;

    function strand(P: Pool, i: number, mode: number) {
      const K = P.k[i];
      let env: number;
      if (mode === 1) {
        env = Math.min(1, P.age[i] * 9);
      } else {
        const t = 1 - P.life[i] / P.max[i];
        env = Math.min(1, t * 9) * Math.min(1, (1 - t) * 3.4);
      }
      if (env <= 0.01) return;
      const style = P.style[i],
        seed = P.seed[i];
      const base = P.br[i] * env;
      const L = P.len[i] * (mode === 0 ? spr : 1),
        h = L / K;
      let x = P.x[i],
        y = P.y[i];
      const dirx = P.nx[i],
        diry = P.ny[i];
      let prevLvl = -1,
        moved = true;
      const ix = 1 / ART.s;

      for (let k = 0; k < K; k++) {
        const s = k / K;
        curlAt((x - ART.x) * ix, (y - ART.y) * ix, cur);
        let dx: number, dy: number;
        if (mode === 0) {
          const c = (0.1 + s * 0.42) * turb * (1 - P.pin[i] * 0.85);
          dx = dirx + cur[0] * c;
          dy = diry + cur[1] * c;
        } else if (mode === 1) {
          const c = (0.05 + s * 0.17) * turb;
          dx = -WIND.x + cur[0] * c;
          dy = -WIND.y + cur[1] * c;
        } else {
          dx = dirx + cur[0] * 0.1;
          dy = diry * 0.6 + cur[1] * 0.045;
        }
        const m = Math.hypot(dx, dy) || 1;
        dx /= m;
        dy /= m;
        const nx2 = x + dx * h,
          ny2 = y + dy * h;

        const a = base * Math.pow(1 - s, mode === 1 ? 0.75 : 0.95);
        if (a > 0.15 && lit(seed, k)) {
          const lvl = levelOf(a);
          if (lvl !== prevLvl) moved = true;
          emit(style, lvl, moved, nx2, ny2, x, y);
          prevLvl = lvl;
          moved = false;
        } else {
          moved = true;
          prevLvl = -1;
        }
        x = nx2;
        y = ny2;
      }
    }

    function stepRain(d: number) {
      for (let i = 0; i < NR; i++) {
        RAIN.age[i] += d;
        RAIN.x[i] += RAIN.vx[i] * d;
        RAIN.y[i] += RAIN.vy[i] * d;
        const ty = RAIN.y[i] - RAIN.len[i] * WIND.y,
          tx = RAIN.x[i] - RAIN.len[i] * WIND.x;
        if (ty > VH || tx > VW) spawnRain(i, false);
      }
    }
    function stepFur(d: number) {
      for (let i = 0; i < NF; i++) {
        FUR.life[i] -= d;
        if (FUR.life[i] <= 0) {
          spawnFur(i, false);
          continue;
        }
        const age = 1 - FUR.life[i] / FUR.max[i];
        const pin = FUR.pin[i],
          free = 1 - pin;
        curlAt((FUR.x[i] - ART.x) / ART.s, (FUR.y[i] - ART.y) / ART.s, cur);
        const rad = (Math.pow(1 - age, 1.5) * 0.9 * free + 0.62 * pin) * 1.45;
        const c = (0.34 + age * 1.25) * turb * (1 - pin * 0.88);
        let dx = FUR.rx[i] * rad + WIND.x * 0.5 * free + cur[0] * c;
        let dy = FUR.ry[i] * rad + WIND.y * 0.5 * free + cur[1] * c;
        const m = Math.hypot(dx, dy) || 1;
        dx /= m;
        dy /= m;
        FUR.x[i] += dx * FUR.spd[i] * d;
        FUR.y[i] += dy * FUR.spd[i] * d;
        FUR.nx[i] = dx;
        FUR.ny[i] = dy;
      }
    }
    function stepWater(d: number) {
      for (let i = 0; i < NW; i++) {
        WAT.life[i] -= d;
        WAT.x[i] += WAT.nx[i] * ART.s * 0.035 * d;
        if (WAT.life[i] <= 0) spawnWater(i, false);
      }
    }
    function cycle() {
      const cyc = 0.5 - 0.5 * Math.cos((CT * TAU) / 17);
      turb = (0.62 + cyc * 0.78) * controls.current.turbulence;
      spr = (0.88 + cyc * 0.44) * controls.current.spread;
    }
    function prewarm() {
      const d = 1 / 30;
      for (let n = 0; n < 30; n++) {
        CT += d;
        stepRain(d);
        stepFur(d);
        stepWater(d);
      }
      cycle();
    }

    function flush(stroke = theme.ink) {
      ctx.globalCompositeOperation = theme.blend;
      ctx.strokeStyle = stroke;
      ctx.lineWidth = LW;
      ctx.lineCap = "butt";
      for (let s = 0; s < DASHES.length; s++) {
        ctx.setLineDash(DASHES[s].map((v) => v * LW));
        for (let l = 0; l < LEVELS.length; l++) {
          ctx.globalAlpha = LEVELS[l];
          ctx.stroke(paths[s * LEVELS.length + l]);
        }
      }
      ctx.setLineDash([]);
      ctx.globalAlpha = 1;
      ctx.globalCompositeOperation = "source-over";
    }

    function render() {
      ctx.globalCompositeOperation = "source-over";
      ctx.fillStyle = theme.bg;
      ctx.fillRect(0, 0, VW, VH);

      for (let i = 0; i < NB; i++) paths[i] = new Path2D();
      for (let i = 0; i < NR; i++) if (!RAIN.pin[i]) strand(RAIN, i, 1);
      flush(theme.rain);

      ctx.save();
      ctx.globalCompositeOperation = "destination-out";
      ctx.filter = "blur(" + (ART.s * 0.004).toFixed(2) + "px)";
      ctx.drawImage(MASKS.occ, ART.x, ART.y + AY0 * ART.s, ART.s, AH * ART.s);
      ctx.restore();
      ctx.filter = "none";
      // the canvas is opaque, so restore the ground under the punched-out figure
      ctx.globalCompositeOperation = "destination-over";
      ctx.fillStyle = theme.bg;
      ctx.fillRect(0, 0, VW, VH);
      ctx.globalCompositeOperation = "source-over";

      for (let i = 0; i < NB; i++) paths[i] = new Path2D();
      for (let i = 0; i < NF; i++) strand(FUR, i, 0);
      for (let i = 0; i < NW; i++) strand(WAT, i, 2);
      flush();

      for (let i = 0; i < NB; i++) paths[i] = new Path2D();
      for (let i = 0; i < NR; i++) if (RAIN.pin[i]) strand(RAIN, i, 1);
      flush(theme.rain);
    }

    let last = 0,
      acc = 0,
      frames = 0,
      slowRun = 0,
      raf = 0,
      running = false;

    function frame(ts: number) {
      raf = requestAnimationFrame(frame);
      if (!last) last = ts;
      let dt = (ts - last) / 1000;
      last = ts;
      if (dt > 0.1) dt = 0.1;
      const rate = controls.current.speed;
      CT += dt * rate;
      cycle();
      const d = dt * rate;
      stepRain(d);
      stepFur(d);
      stepWater(d);
      render();

      // adaptive load governor
      frames++;
      acc += dt;
      if (frames >= 40) {
        const avg = acc / frames;
        frames = 0;
        acc = 0;
        if (avg > 0.022) {
          slowRun++;
          if (slowRun >= 2) {
            NF = Math.max(1100, (NF * 0.85) | 0);
            NR = Math.max(240, (NR * 0.9) | 0);
            NW = Math.max(260, (NW * 0.9) | 0);
            slowRun = 0;
          }
        } else slowRun = 0;
      }
    }

    applyRef.current = () => {
      readTheme();
      applyParticleCounts();
      if (!running) render();
    };

    let lastW = 0,
      lastH = 0,
      resizeT = 0;
    const measure = () => {
      const r = host.getBoundingClientRect();
      return [Math.max(1, Math.round(r.width)), Math.max(1, Math.round(r.height))];
    };
    const relayout = () => {
      clearTimeout(resizeT);
      resizeT = window.setTimeout(() => {
        const [w, h] = measure();
        if (w === lastW && h === lastH) return;
        lastW = w;
        lastH = h;
        layout(w, h);
        prewarm();
        render();
      }, 120);
    };
    const ro = new ResizeObserver(relayout);
    ro.observe(host);
    [lastW, lastH] = measure();
    layout(lastW, lastH);
    prewarm();
    render();

    let visible = true;
    const update = () => {
      const want = !prefersReducedMotion && visible && document.visibilityState !== "hidden";
      if (want && !running) {
        running = true;
        last = 0;
        raf = requestAnimationFrame(frame);
      } else if (!want && running) {
        running = false;
        cancelAnimationFrame(raf);
      }
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      update();
    });
    io.observe(host);
    document.addEventListener("visibilitychange", update);
    update();

    return () => {
      running = false;
      cancelAnimationFrame(raf);
      clearTimeout(resizeT);
      ro.disconnect();
      io.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", update);
      applyRef.current = () => {};
    };
  }, [prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 overflow-hidden", className)}
      style={{ background: backgroundColor }}
      role="img"
      aria-label="Animated ember tag in rain"
    >
      <canvas ref={canvasRef} className="block h-full w-full" />
    </div>
  );
}
```

---

# Draft Folio

> An open folio in theme ink whose leaves curl as you drag them, with a primary-tinted loupe you can slide across the page.

Install: `npx @modus-ui/cli add draft-folio`

An open folio lying on the theme background, its photos washed to monochrome and its loupe, captions and paper drawn from the Modus tokens (`--foreground`, `--primary`, `--card`) so it follows light, dark and every palette. Drag a page and the leaf bends through a chain of 18 strips instead of pivoting flat, lit and shaded as it lifts. The book leans toward the cursor, zooms from the toolbar, riffles through every plate on first view, and carries a loupe you can pick up and drag across the paper. Each photo is washed onto a drawn spread, or pass your own spread artwork. It fills its positioned parent, waits until it is on screen to riffle, and skips the riffle, tilt and spring when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add draft-folio
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/draft-folio.tsx`.
3. Paste the code.

## Usage

```tsx
import { DraftFolio } from "@/components/ui/draft-folio";

export default function Example() {
  return (
    <div className="relative h-[600px] w-full overflow-hidden">
      <DraftFolio
        pages={[
          {
            src: "https://images.unsplash.com/photo-1525625293386-3f8f99389edd?w=1400",
            title: "Marina Bay Sands",
            place: "Bayfront",
          },
          {
            src: "https://images.unsplash.com/photo-1600664356348-10686526af4f?w=1400",
            title: "The Merlion",
            place: "Merlion Park",
          },
        ]}
        startPage={0}
      />
    </div>
  );
}
```

Images must allow cross-origin use (Unsplash does) so they can be drawn onto the spread. Set `spread: true` on a page whose `src` is already a 1760×1240 transparent image of an open folio with the paper between 5.1–94.9% across and 21.8–78.2% down; it is used as-is.

## Props

| Prop            | Type               | Default                                               | Description                                            |
| :-------------- | :----------------- | :---------------------------------------------------- | :----------------------------------------------------- |
| `pages`         | `DraftFolioPage[]` | Eight Unsplash photos of Singapore with titles/places | Plates: `src`, `title`, optional `place` and `spread`. |
| `startPage`     | `number`           | `2`                                                   | Plate the book lands on after the opening riffle.      |
| `intro`         | `boolean`          | `true`                                                | Riffle through the plates when first on screen.        |
| `magnification` | `number`           | `1.8`                                                 | Magnification of the glass.                            |
| `hint`          | `string`           | `"Drag a leaf to turn it · Slide the loupe to read"`  | Hint shown under the toolbar until first interaction.  |
| `paperColor`    | `string`           | `"hsl(var(--background))"`                            | Desk colour behind the book.                           |
| `inkColor`      | `string`           | `"hsl(var(--foreground))"`                            | Text, icon and handwriting colour.                     |
| `accentColor`   | `string`           | `"hsl(var(--primary))"`                               | Loupe rim and active toggle colour.                    |
| `sheetColor`    | `string`           | `"hsl(var(--card))"`                                  | Colour of the drawn folio paper.                       |

## Source

`components/ui/draft-folio.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Sketchbook (MIT, © 2026 Meng To).

import { useEffect, useMemo, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export type DraftFolioPage = {
  /** Image URL. A photo is laid onto a drawn draft-folio spread; with `spread` it is used as-is. */
  src: string;
  title: string;
  place?: string;
  /** `src` is already a 1760×1240 transparent spread of an open draft-folio. */
  spread?: boolean;
};

export type DraftFolioProps = {
  pages?: DraftFolioPage[];
  startPage?: number;
  intro?: boolean;
  magnification?: number;
  hint?: string;
  paperColor?: string;
  inkColor?: string;
  accentColor?: string;
  sheetColor?: string;
  className?: string;
};

const unsplash = (id: string) =>
  `https://images.unsplash.com/photo-${id}?auto=format&fit=crop&w=1400&q=80`;

const DEFAULT_PAGES: DraftFolioPage[] = [
  { src: unsplash("1525625293386-3f8f99389edd"), title: "Marina Bay Sands", place: "Bayfront" },
  {
    src: unsplash("1508964942454-1a56651d54ac"),
    title: "Gardens by the Bay",
    place: "Supertree Grove",
  },
  { src: unsplash("1600664356348-10686526af4f"), title: "The Merlion", place: "Merlion Park" },
  { src: unsplash("1506351421178-63b52a2d2562"), title: "Supertrees at Dusk", place: "Bay South" },
  { src: unsplash("1542114740389-9b46fb1e5be7"), title: "ArtScience Museum", place: "Marina Bay" },
  { src: unsplash("1555217851-6141535bd771"), title: "Rain Vortex", place: "Changi" },
  { src: unsplash("1496939376851-89342e90adcd"), title: "Marina Bay Skyline", place: "The Bay" },
  {
    src: unsplash("1565967511849-76a60a516170"),
    title: "The Merlion by Night",
    place: "One Fullerton",
  },
];

const SPREAD_W = 1760;
const SPREAD_H = 1240;

/** Resolves `var(--token)` references against the document's theme, for use on a canvas. */
function resolveThemeColor(value: string) {
  const style = getComputedStyle(document.documentElement);
  return value.replace(/var\((--[\w-]+)\)/g, (_, name: string) =>
    style.getPropertyValue(name).trim(),
  );
}

/** Adds an alpha channel to a resolved `hsl(...)` colour; other formats are returned as-is. */
function withAlpha(color: string, alpha: number) {
  const m = /^hsl\((.*)\)$/.exec(color);
  return m ? `hsl(${m[1]} / ${alpha})` : color;
}

/** Reads a font-family custom property (`--font-heading`, `--font-body`) for canvas text. */
function themeFont(name: string) {
  return getComputedStyle(document.documentElement).getPropertyValue(name).trim() || "serif";
}

function loadImage(src: string) {
  return new Promise<HTMLImageElement>((resolve, reject) => {
    const im = new Image();
    im.crossOrigin = "anonymous";
    im.onload = () => resolve(im);
    im.onerror = reject;
    im.src = src;
  });
}

/* Draws an open draft-folio spread with the paper in the same place as the
   original plates (x 5.1–94.9 %, y 21.8–78.2 %), the photo washed onto the
   right page and the plate's title handwritten on the left. */
async function composeSpread(page: DraftFolioPage, sheet: string, ink: string): Promise<string> {
  if (page.spread) return page.src;
  const c = document.createElement("canvas");
  c.width = SPREAD_W;
  c.height = SPREAD_H;
  const g = c.getContext("2d");
  if (!g) return page.src;
  const x0 = SPREAD_W * 0.051,
    x1 = SPREAD_W * 0.949,
    y0 = SPREAD_H * 0.218,
    y1 = SPREAD_H * 0.782;
  const mid = SPREAD_W / 2;
  const roundRect = (x: number, y: number, w: number, h: number, r: number) => {
    g.beginPath();
    g.roundRect(x, y, w, h, r);
  };
  roundRect(x0, y0, x1 - x0, y1 - y0, 34);
  g.fillStyle = resolveThemeColor(sheet);
  g.fill();
  const inkColor = resolveThemeColor(ink);
  g.save();
  roundRect(x0, y0, x1 - x0, y1 - y0, 34);
  g.clip();
  /* paper tooth */
  for (let i = 0; i < 9000; i++) {
    g.globalAlpha = Math.random() * 0.035;
    g.fillStyle = inkColor;
    g.fillRect(x0 + Math.random() * (x1 - x0), y0 + Math.random() * (y1 - y0), 2, 2);
  }
  /* the gutter and the page edges */
  const gut = g.createLinearGradient(mid - 90, 0, mid + 90, 0);
  gut.addColorStop(0, withAlpha(inkColor, 0));
  gut.addColorStop(0.47, withAlpha(inkColor, 0.16));
  gut.addColorStop(0.5, withAlpha(inkColor, 0.26));
  gut.addColorStop(0.53, withAlpha(inkColor, 0.16));
  gut.addColorStop(1, withAlpha(inkColor, 0));
  g.fillStyle = gut;
  g.fillRect(mid - 90, y0, 180, y1 - y0);
  g.strokeStyle = withAlpha(inkColor, 0.1);
  g.lineWidth = 3;
  g.strokeRect(x0 + 1.5, y0 + 1.5, x1 - x0 - 3, y1 - y0 - 3);

  /* the photo, washed onto the right page with a soft painted edge */
  try {
    const im = await loadImage(page.src);
    const px = mid + 70,
      py = y0 + 70,
      pw = x1 - 70 - px,
      ph = y1 - 90 - py;
    const s = Math.max(pw / im.naturalWidth, ph / im.naturalHeight);
    const sw = pw / s,
      sh = ph / s;
    const layer = document.createElement("canvas");
    layer.width = pw;
    layer.height = ph;
    const l = layer.getContext("2d");
    if (l) {
      l.filter = "grayscale(1) contrast(1.1) brightness(1.05)";
      l.drawImage(
        im,
        (im.naturalWidth - sw) / 2,
        (im.naturalHeight - sh) / 2,
        sw,
        sh,
        0,
        0,
        pw,
        ph,
      );
      l.filter = "none";
      l.globalCompositeOperation = "destination-in";
      const fx = l.createLinearGradient(0, 0, pw, 0);
      fx.addColorStop(0, "rgba(0,0,0,0)");
      fx.addColorStop(0.06, "#000");
      fx.addColorStop(0.94, "#000");
      fx.addColorStop(1, "rgba(0,0,0,0)");
      l.fillStyle = fx;
      l.fillRect(0, 0, pw, ph);
      const fy = l.createLinearGradient(0, 0, 0, ph);
      fy.addColorStop(0, "rgba(0,0,0,0)");
      fy.addColorStop(0.07, "#000");
      fy.addColorStop(0.93, "#000");
      fy.addColorStop(1, "rgba(0,0,0,0)");
      l.fillStyle = fy;
      l.fillRect(0, 0, pw, ph);
      g.globalCompositeOperation = "multiply";
      g.globalAlpha = 0.92;
      g.drawImage(layer, px, py);
      g.globalAlpha = 1;
      g.globalCompositeOperation = "source-over";
    }
  } catch {
    /* an unreachable image leaves a blank page */
  }

  /* the handwriting on the left page */
  g.globalAlpha = 0.82;
  g.fillStyle = inkColor;
  g.font = `italic 64px ${themeFont("--font-heading")}`;
  g.textBaseline = "alphabetic";
  g.fillText(page.title, x0 + 110, y1 - 170, mid - x0 - 200);
  if (page.place) {
    g.globalAlpha = 0.5;
    g.font = "24px ui-monospace, SFMono-Regular, Menlo, monospace";
    g.fillText(
      page.place.toUpperCase().split("").join(String.fromCharCode(8202)),
      x0 + 112,
      y1 - 118,
    );
  }
  g.restore();
  g.globalAlpha = 1;

  const blob = await new Promise<Blob | null>((r) => c.toBlob(r, "image/png"));
  return blob ? URL.createObjectURL(blob) : page.src;
}

const STYLE = `
.msb{--ink-soft:color-mix(in srgb,var(--ink) 58%,transparent);--ink-faint:color-mix(in srgb,var(--ink) 36%,transparent);--hairline:color-mix(in srgb,var(--ink) 14%,transparent);
  --display:var(--font-heading),serif;
  --font:ui-monospace,SFMono-Regular,Menlo,monospace;--track-caps:.24em;
  font-family:var(--font);font-weight:400;color:var(--ink);-webkit-font-smoothing:antialiased}
.msb *{box-sizing:border-box}
.msb button{font:inherit}
.msb .wash{position:absolute;inset:0;pointer-events:none;opacity:.85;
  background:radial-gradient(60% 50% at 12% 18%,color-mix(in srgb,var(--earth) 35%,transparent),color-mix(in srgb,var(--earth) 0%,transparent) 70%),
    radial-gradient(45% 40% at 88% 30%,color-mix(in srgb,var(--earth) 32%,transparent),color-mix(in srgb,var(--earth) 0%,transparent) 72%),
    radial-gradient(70% 55% at 50% 100%,color-mix(in srgb,var(--earth) 40%,transparent),color-mix(in srgb,var(--earth) 0%,transparent) 70%)}
.msb .wash:after{content:"";position:absolute;inset:0;
  background:linear-gradient(180deg,color-mix(in srgb,var(--paper) 25%,transparent) 0%,color-mix(in srgb,var(--paper) 72%,transparent) 58%,var(--paper) 88%)}
.msb .hero{position:relative;display:grid;justify-items:center;align-content:center;width:100%;height:100%;padding:12px 0 10px}
.msb .hero,.msb .hero *{-webkit-user-select:none;user-select:none}
.msb .hero img{-webkit-user-drag:none}
.msb .sb-wrap{display:grid;justify-items:center;gap:8px;width:100%;position:relative;z-index:2}
.msb .sb-stage{display:flex;align-items:center;justify-content:center;width:100%;position:relative;touch-action:pan-y}
.msb .sb-arrow{flex:none;display:inline-flex;align-items:center;justify-content:center;padding:6px 2px;border:0;background:transparent;
  color:var(--ink-faint);cursor:pointer;transition:color .2s;-webkit-tap-highlight-color:transparent;z-index:8}
.msb .sb-arrow:hover{color:var(--ink)}
.msb .sb-3d{position:relative;flex:1 1;min-width:0;max-width:min(900px,92%);perspective:1750px;perspective-origin:50% 46%}
.msb .sb-tilt{position:relative;transform-style:preserve-3d;transform:rotateX(var(--rx,0deg)) rotateY(var(--ry,0deg)) scale(var(--zoom,1));will-change:transform}
.msb .sb-book{position:relative;width:100%;aspect-ratio:1760/1240;transform-style:preserve-3d;z-index:1}
.msb .sb-cast{position:absolute;pointer-events:none;z-index:0}
.msb .sb-cast.ambient{left:5%;right:5%;top:27%;bottom:2%;
  background:radial-gradient(50% 50% at 50% 58%,rgb(0 0 0 / 34%) 0%,rgb(0 0 0 / 19%) 40%,rgb(0 0 0 / 0%) 74%);
  filter:blur(26px);opacity:calc(1 - var(--shade,0) * .42)}
.msb .sb-cast.contact{left:9%;right:9%;top:62%;bottom:10%;
  background:radial-gradient(50% 44% at 50% 42%,rgb(0 0 0 / 40%) 0%,rgb(0 0 0 / 17%) 48%,rgb(0 0 0 / 0%) 78%);
  filter:blur(11px);opacity:calc(1 - var(--shade,0) * .5)}
.msb .sb-cast.hair{left:12%;right:12%;top:70%;bottom:17%;
  background:radial-gradient(50% 52% at 50% 40%,rgb(0 0 0 / 34%) 0%,rgb(0 0 0 / 0%) 76%);
  filter:blur(4px);opacity:calc(1 - var(--shade,0) * .62)}
.msb .sb-full{position:absolute;inset:0}
.msb .sb-full img{width:100%;height:auto;display:block}
.msb .sb-half{position:absolute;top:0;bottom:0;width:50%;overflow-x:clip;overflow-y:visible}
.msb .sb-half.left{left:0}
.msb .sb-half.right{left:50%}
.msb .sb-half-img{width:200%;max-width:none;height:auto;display:block}
.msb .sb-half-img.right{margin-left:-100%}
.msb .gutter-shade{position:absolute;top:var(--pg,21.8%);bottom:var(--pg,21.8%);width:46%;pointer-events:none;opacity:calc(var(--shade,0) * .62);
  -webkit-mask-image:linear-gradient(180deg,transparent 0,#000 5.2%,#000 94.8%,transparent 100%);
  mask-image:linear-gradient(180deg,transparent 0,#000 5.2%,#000 94.8%,transparent 100%)}
.msb .gutter-shade.left{right:0;background:linear-gradient(270deg,rgb(0 0 0 / 30%),rgb(0 0 0 / 0%) 82%)}
.msb .gutter-shade.right{left:0;background:linear-gradient(90deg,rgb(0 0 0 / 24%),rgb(0 0 0 / 0%) 82%)}
.msb .curl{position:absolute;top:0;height:100%;width:calc(var(--bw,0px) * var(--span));transform-style:preserve-3d;z-index:6}
.msb .curl.next{left:50%;transform-origin:left center;transform:rotateY(calc(-1 * var(--tt,0deg)))}
.msb .curl.prev{right:50%;transform-origin:right center;transform:rotateY(var(--tt,0deg))}
.msb .strip{position:absolute;top:0;height:100%;width:calc(var(--bw,0px) * var(--span) / var(--n));transform-style:preserve-3d}
.msb .curl.next .strip{transform-origin:left center}
.msb .curl.prev .strip{transform-origin:right center}
.msb .curl.next>.strip{left:0}
.msb .curl.prev>.strip{right:0;left:auto}
.msb .curl.next .strip .strip{left:100%;transform:rotateY(var(--td,0deg))}
.msb .curl.prev .strip .strip{right:100%;transform:rotateY(calc(-1 * var(--td,0deg)))}
.msb .face{position:absolute;top:0;bottom:0;left:0;right:-1.1px;backface-visibility:hidden;-webkit-backface-visibility:hidden;
  background-repeat:no-repeat;background-size:var(--bw,0px) auto}
.msb .face.back{transform:rotateY(180deg)}
.msb .face .sh,.msb .face .gl{
  -webkit-mask-image:linear-gradient(180deg,transparent 0,#000 5.2%,#000 94.8%,transparent 100%);
  mask-image:linear-gradient(180deg,transparent 0,#000 5.2%,#000 94.8%,transparent 100%)}
.msb .strip.edge .face .sh,.msb .strip.edge .face .gl{
  -webkit-mask-image:linear-gradient(180deg,transparent 0,#000 9%,#000 91%,transparent 100%),var(--hf);
  mask-image:linear-gradient(180deg,transparent 0,#000 9%,#000 91%,transparent 100%),var(--hf);
  -webkit-mask-composite:source-in;mask-composite:intersect}
.msb .curl.next .strip.edge .face.front,.msb .curl.prev .strip.edge .face.back{--hf:linear-gradient(90deg,#000 0 22%,transparent 96%)}
.msb .curl.next .strip.edge .face.back,.msb .curl.prev .strip.edge .face.front{--hf:linear-gradient(270deg,#000 0 22%,transparent 96%)}
.msb .face .sh{position:absolute;left:0;right:0;top:var(--pg,21.8%);bottom:var(--pg,21.8%);pointer-events:none}
.msb .curl.next .face.front .sh,.msb .curl.prev .face.back .sh{background:linear-gradient(90deg,rgb(0 0 0 / var(--a1,0)),rgb(0 0 0 / var(--a2,0)))}
.msb .curl.next .face.back .sh,.msb .curl.prev .face.front .sh{background:linear-gradient(90deg,rgb(0 0 0 / var(--a2,0)),rgb(0 0 0 / var(--a1,0)))}
.msb .face .gl{position:absolute;left:0;right:0;top:var(--pg,21.8%);bottom:var(--pg,21.8%);pointer-events:none;background:var(--sheet);
  opacity:calc(var(--shade,0) * var(--lit,1) * var(--lit,1) * .20)}
.msb .loupe{position:absolute;left:0;top:0;width:var(--lr,270px);height:var(--lr,270px);pointer-events:none;z-index:80;opacity:0;
  transition:opacity .25s ease;will-change:transform}
.msb .loupe.on{opacity:1}
.msb .loupe.held .ring{cursor:grabbing}
.msb .loupe .ring{position:absolute;inset:0;border-radius:50%;pointer-events:auto;cursor:grab;padding:calc(var(--lr,270px) * .058);
  box-shadow:0 1px 2px rgb(0 0 0 / 30%),0 10px 18px rgb(0 0 0 / 24%),0 26px 40px rgb(0 0 0 / 20%),0 48px 66px rgb(0 0 0 / 13%)}
.msb .loupe .ring:before{content:"";position:absolute;inset:0;border-radius:50%;pointer-events:none;
  background:linear-gradient(146deg,color-mix(in srgb,var(--earth) 8%,white) 0%,color-mix(in srgb,var(--earth) 35%,white) 14%,color-mix(in srgb,var(--earth) 75%,white) 32%,color-mix(in srgb,var(--earth) 70%,black) 50%,color-mix(in srgb,var(--earth) 45%,white) 66%,color-mix(in srgb,var(--earth) 12%,white) 80%,var(--earth) 100%);
  box-shadow:inset 0 1px 1px rgba(255,255,255,.8),inset 0 -2px 3px rgb(0 0 0 / 50%);
  -webkit-mask-image:radial-gradient(circle closest-side at 50% 50%,transparent 0 88.2%,#000 89.8% 100%);
  mask-image:radial-gradient(circle closest-side at 50% 50%,transparent 0 88.2%,#000 89.8% 100%)}
.msb .loupe .grip{position:absolute;left:50%;top:50%;width:calc(var(--lr,270px) * .74);height:calc(var(--lr,270px) * .125);
  transform-origin:0 50%;transform:rotate(40deg) translate(calc(var(--lr,270px) * .33),-50%);border-radius:calc(var(--lr,270px) * .06);
  pointer-events:auto;cursor:grab;
  background:linear-gradient(180deg,rgba(255,255,255,.46) 0 13%,rgba(255,255,255,0) 44%,rgba(0,0,0,.26) 100%),
    linear-gradient(90deg,color-mix(in srgb,var(--ink) 40%,white) 0 14%,color-mix(in srgb,var(--ink) 70%,white) 14% 20%,var(--ink) 20% 62%,color-mix(in srgb,var(--ink) 80%,black) 62% 92%,rgb(0 0 0 / 50%) 92% 100%);
  box-shadow:0 8px 15px rgb(0 0 0 / 26%),0 18px 26px rgb(0 0 0 / 14%)}
.msb .lens{position:relative;display:block;width:100%;height:100%;border-radius:50%;background-repeat:no-repeat;overflow:hidden;
  box-shadow:inset 0 0 0 1px rgb(0 0 0 / 55%),inset 0 4px 12px rgb(0 0 0 / 28%),inset 0 -7px 16px color-mix(in srgb,var(--paper) 14%,transparent)}
.msb .zoomwrap{position:absolute;inset:0;overflow:hidden;pointer-events:none;z-index:2;opacity:0}
.msb .zoominner{position:absolute;inset:0;transform-origin:0 0}
.msb .lens:before,.msb .lens:after{content:"";position:absolute;inset:0;border-radius:50%;pointer-events:none}
.msb .lens:before{z-index:1;background:radial-gradient(circle at 50% 50%,rgba(0,0,0,0) 54%,rgb(0 0 0 / 10%) 76%,rgb(0 0 0 / 34%) 100%);
  box-shadow:inset 0 0 0 2px rgb(0 0 0 / 20%),inset 0 0 0 4px color-mix(in srgb,var(--earth) 15%,transparent)}
.msb .lens:after{z-index:2;background:radial-gradient(36% 26% at 29% 19%,rgba(255,255,255,.30),rgba(255,255,255,0) 76%),
  radial-gradient(24% 16% at 74% 86%,rgba(255,255,255,.12),rgba(255,255,255,0) 80%),
  linear-gradient(150deg,rgba(255,255,255,.06) 0 18%,rgba(255,255,255,0) 42%)}
.msb .sb-tools{display:flex;align-items:center;gap:6px;border:1px solid var(--hairline);border-radius:999px;padding:5px 7px;
  background:color-mix(in srgb,var(--paper) 62%,transparent);-webkit-backdrop-filter:blur(8px);backdrop-filter:blur(8px)}
.msb .tool{width:28px;height:28px;display:inline-flex;align-items:center;justify-content:center;border:0;border-radius:50%;
  background:transparent;color:var(--ink-soft);cursor:pointer;transition:background-color .18s ease,color .18s ease}
.msb .tool:hover{background:color-mix(in srgb,var(--paper) 90%,transparent);color:var(--ink)}
.msb .tool[aria-pressed="true"]{background:color-mix(in srgb,var(--earth) 16%,transparent);color:var(--earth)}
.msb .tool:disabled{opacity:.32;cursor:default;background:transparent}
.msb .tool svg{width:15px;height:15px;display:block}
.msb .tool-sep{width:1px;height:17px;background:var(--hairline);margin:0 2px}
.msb .zoom-read{font-size:11px;letter-spacing:.1em;color:var(--ink-faint);min-width:40px;text-align:center;font-variant-numeric:tabular-nums}
@media (pointer:coarse){.msb .loupe{display:none}}
.msb .sb-zone{position:absolute;top:0;bottom:0;border:0;background:transparent;cursor:grab;z-index:60;-webkit-tap-highlight-color:transparent}
.msb .sb-zone:active{cursor:grabbing}
.msb .sb-prev{left:0;width:50%}
.msb .sb-next{right:0;width:50%}
.msb .sb-captions{display:grid;justify-items:center;min-height:18px}
.msb .sb-captions>*{grid-area:1/1;margin:0}
.msb .sb-caption{font-size:13px;letter-spacing:var(--track-caps);text-transform:uppercase;color:var(--ink-soft);animation:msb-cap-in .5s ease both}
.msb .sb-caption.live{animation:none}
@keyframes msb-cap-in{0%{opacity:0}}
.msb .sb-hint{margin:0;font-size:11px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-faint);transition:opacity .4s ease}
.msb .sb-hint.gone{opacity:0}
.msb .sb-wrap.intro .sb-full img,.msb .sb-wrap.intro .sb-half-img{filter:url(#msb-mblur-1)}
.msb .sb-wrap.intro.b2 .sb-full img,.msb .sb-wrap.intro.b2 .sb-half-img{filter:url(#msb-mblur-2)}
.msb .sb-wrap.intro .sb-caption{animation:none}
@media (max-width:640px){
  .msb .hero{padding:4px 0}
  .msb .sb-wrap{gap:5px}
  .msb .sb-arrow{position:absolute;top:50%;transform:translateY(-50%);z-index:70;padding:12px 6px}
  .msb .sb-arrow.left{left:2px}
  .msb .sb-arrow.right{right:2px}
  .msb .sb-3d{max-width:100%}
  .msb .sb-hint{font-size:9.5px;letter-spacing:.1em;padding:0 16px;text-align:center}
}
`;

/* the turning leaf */
const N = 18; /* strips — enough for a smooth curve */
const SPAN = 0.449; /* gutter → outer page edge, as a fraction */
const BETA = 0.6; /* peak curl of the arc, radians */
const TILT_X = 4.5,
  TILT_Y = 7;
const ZOOM_MIN = 0.9,
  ZOOM_MAX = 1.5;

export function DraftFolio({
  pages = DEFAULT_PAGES,
  startPage = 2,
  intro = true,
  magnification = 1.8,
  hint = "Drag a leaf to turn it · Slide the loupe to read",
  paperColor = "hsl(var(--background))",
  inkColor = "hsl(var(--foreground))",
  accentColor = "hsl(var(--primary))",
  sheetColor = "hsl(var(--card))",
  className,
}: DraftFolioProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const pagesKey = useMemo(() => JSON.stringify(pages), [pages]);
  const [themeKey, setThemeKey] = useState(0);

  useEffect(() => {
    // the spreads are painted on a canvas, so repaint them when the theme or palette changes
    const observer = new MutationObserver(() => setThemeKey((k) => k + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette"],
    });
    return () => observer.disconnect();
  }, []);

  useEffect(() => {
    const root = rootRef.current;
    if (!root) return;
    const PAGES: (DraftFolioPage & { url: string })[] = (
      JSON.parse(pagesKey) as DraftFolioPage[]
    ).map((p) => ({
      ...p,
      url: "",
    }));
    const M = PAGES.length;
    if (!M) return;
    const LAND = ((startPage % M) + M) % M;
    const REDUCED = !!prefersReducedMotion;
    const MAG = magnification;
    const q = <T extends HTMLElement>(s: string) => root.querySelector(s) as T;
    const wrap = q<HTMLDivElement>(".sb-wrap");
    const stage = q<HTMLDivElement>(".sb-stage");
    const sb3d = q<HTMLDivElement>(".sb-3d");
    const book = q<HTMLDivElement>(".sb-book");
    const capBox = q<HTMLDivElement>(".sb-captions");
    const hintEl = q<HTMLParagraphElement>(".sb-hint");
    const loupe = q<HTMLDivElement>(".loupe");
    const zoomWrap = q<HTMLDivElement>(".zoomwrap");
    const zoomInner = q<HTMLDivElement>(".zoominner");
    const zRead = q<HTMLSpanElement>(".zoom-read");
    const loupeBtn = q<HTMLButtonElement>("[data-loupe]");
    const zInBtn = q<HTMLButtonElement>("[data-zin]");
    const zOutBtn = q<HTMLButtonElement>("[data-zout]");
    const leftBtn = q<HTMLButtonElement>(".sb-arrow.left");
    const rightBtn = q<HTMLButtonElement>(".sb-arrow.right");

    let disposed = false;
    let booted = false;
    let visible = false;
    const objectUrls: string[] = [];
    const timers: number[] = [];

    type Turn = { dir: "next" | "prev"; from: number; to: number; t: number };
    let idx = 0,
      turn: Turn | null = null;
    let strips: HTMLDivElement[] = [];

    const el = (t: string, c?: string) => {
      const e = document.createElement(t);
      if (c) e.className = c;
      return e;
    };
    function imgEl(i: number, side: string) {
      const im = new Image();
      im.className = "sb-half-img " + side;
      im.draggable = false;
      im.alt = "";
      im.src = PAGES[i].url;
      return im;
    }
    function halfEl(pos: string, i: number) {
      const d = el("div", "sb-half " + pos);
      d.appendChild(imgEl(i, pos));
      d.appendChild(el("div", "gutter-shade " + pos));
      return d;
    }
    /* build the strip chain once per turn; background offsets are pure
       geometry, so they never need touching again while it animates */
    function buildCurl(dir: string, from: number, to: number) {
      strips = [];
      const c = el("div", "curl " + dir);
      c.style.setProperty("--n", String(N));
      c.style.setProperty("--span", String(SPAN));
      let host: HTMLElement = c;
      for (let i = 0; i < N; i++) {
        const s = el("div", "strip") as HTMLDivElement;
        s.style.setProperty("--i", String(i));
        const gut = "calc(var(--bw) * 0.5)";
        const sw = "calc(var(--bw) * " + SPAN + " / " + N + ")";
        const A = "calc(-1 * (" + gut + " + " + i + " * " + sw + "))";
        const B = "calc(" + (i + 1) + " * " + sw + " - " + gut + ")";
        const f = el("div", "face front"),
          b = el("div", "face back");
        const dress = (e: HTMLElement, url: string, px: string) => {
          e.style.backgroundImage = "url(" + url + ")";
          e.style.backgroundPositionX = px;
        };
        dress(f, PAGES[from].url, dir === "next" ? A : B);
        dress(b, PAGES[to].url, dir === "next" ? B : A);
        f.appendChild(el("div", "sh"));
        f.appendChild(el("div", "gl"));
        b.appendChild(el("div", "sh"));
        b.appendChild(el("div", "gl"));
        s.appendChild(f);
        s.appendChild(b);
        if (i === N - 1) s.classList.add("edge");
        host.appendChild(s);
        host = s;
        strips.push(s);
      }
      return c;
    }
    function applyTurn(t: number) {
      const th = Math.PI * t;
      const beta = BETA * Math.sin(Math.PI * t);
      const D = 180 / Math.PI;
      const tt = th + beta,
        td = (2 * beta) / N;
      sb3d.style.setProperty("--tt", (tt * D).toFixed(2) + "deg");
      sb3d.style.setProperty("--td", (td * D).toFixed(3) + "deg");
      sb3d.style.setProperty("--shade", Math.sin(Math.PI * t).toFixed(3));
      fadeCaption(t);
      for (let i = 0; i < strips.length; i++) {
        const l1 = Math.abs(Math.cos(tt - i * td));
        const l2 = Math.abs(Math.cos(tt - (i + 1) * td));
        const st = strips[i].style;
        st.setProperty("--lit", l1.toFixed(3));
        st.setProperty("--a1", ((1 - l1) * 0.62).toFixed(3));
        st.setProperty("--a2", ((1 - l2) * 0.62).toFixed(3));
      }
    }
    function paint() {
      book.textContent = "";
      if (!turn) {
        const f = el("div", "sb-full");
        const im = new Image();
        im.src = PAGES[idx].url;
        im.alt = PAGES[idx].title;
        im.draggable = false;
        f.appendChild(im);
        book.appendChild(f);
        sb3d.style.setProperty("--shade", "0");
      } else {
        const next = turn.dir === "next";
        book.appendChild(halfEl("left", next ? turn.from : turn.to));
        book.appendChild(halfEl("right", next ? turn.to : turn.from));
        book.appendChild(buildCurl(turn.dir, turn.from, turn.to));
        applyTurn(turn.t);
      }
      const a = el("button", "sb-zone sb-prev"),
        b = el("button", "sb-zone sb-next");
      a.setAttribute("aria-label", "previous page");
      b.setAttribute("aria-label", "next page");
      book.appendChild(a);
      book.appendChild(b);
      layout();
      caption();
      syncZoomLayer();
      placeLoupe();
    }
    let capOut: HTMLElement | null = null,
      capIn: HTMLElement | null = null;
    function caption() {
      capBox.textContent = "";
      capOut = capIn = null;
      if (turn) {
        capOut = el("p", "sb-caption live");
        capOut.textContent = PAGES[turn.from].title;
        capBox.appendChild(capOut);
        capIn = el("p", "sb-caption live");
        capIn.textContent = PAGES[turn.to].title;
        capBox.appendChild(capIn);
        fadeCaption(turn.t);
      } else {
        const p = el("p", "sb-caption");
        p.textContent = PAGES[idx].title;
        capBox.appendChild(p);
      }
    }
    function fadeCaption(t: number) {
      if (!capOut || !capIn) return;
      /* the old title is gone before the new one arrives */
      const out = 1 - Math.max(0, Math.min(1, (t - 0.1) / 0.28));
      const inn = Math.max(0, Math.min(1, (t - 0.56) / 0.3));
      capOut.style.opacity = out.toFixed(3);
      capIn.style.opacity = inn.toFixed(3);
    }
    function layout() {
      sb3d.style.setProperty("--bw", book.clientWidth + "px");
    }

    /* spring loop */
    type Motion =
      | { kind: "spring"; v: number; target: number; done?: () => void; k: number; c: number }
      | { kind: "tween"; from: number; target: number; dur: number; e: number; done?: () => void };
    let spring: Motion | null = null;
    function animateTo(target: number, onDone: () => void, stiff?: number, damp?: number) {
      spring = { kind: "spring", v: 0, target, done: onDone, k: stiff || 150, c: damp || 22 };
      kick();
    }
    function tweenTo(target: number, dur: number, onDone: () => void) {
      spring = { kind: "tween", from: turn ? turn.t : 0, target, dur, e: 0, done: onDone };
      kick();
    }
    let raf: number | null = null,
      last = 0;
    function tick(now: number) {
      raf = null;
      const dt = Math.min(0.032, (now - last) / 1000 || 0.016);
      last = now;
      if (spring && turn) {
        const s = spring;
        if (s.kind === "tween") {
          s.e += dt;
          const k = Math.min(1, s.e / s.dur);
          turn.t = s.from + (s.target - s.from) * k;
          applyTurn(turn.t);
          if (k >= 1) {
            spring = null;
            s.done?.();
          }
        } else {
          const x = turn.t - s.target;
          s.v += (-s.k * x - s.c * s.v) * dt;
          turn.t += s.v * dt;
          if (Math.abs(turn.t - s.target) < 0.002 && Math.abs(s.v) < 0.02) {
            turn.t = s.target;
            spring = null;
            applyTurn(turn.t);
            s.done?.();
          } else applyTurn(turn.t);
        }
      }
      viewSpring();
      const lmoved = loupeEase();
      if ((spring || viewActive || lmoved) && raf === null && !disposed)
        raf = requestAnimationFrame(tick);
    }
    function kick() {
      if (raf === null && !disposed) {
        last = performance.now();
        raf = requestAnimationFrame(tick);
      }
    }

    /* tilt + zoom of the book */
    const view = { rx: 0, ry: 0, z: 1, trx: 0, try_: 0, tz: 1 };
    let viewActive = false;
    let lastZ = 1;
    function applyView() {
      sb3d.style.setProperty("--rx", view.rx.toFixed(2) + "deg");
      sb3d.style.setProperty("--ry", view.ry.toFixed(2) + "deg");
      sb3d.style.setProperty("--zoom", view.z.toFixed(3));
      if (view.z !== lastZ) {
        lastZ = view.z;
        placeLoupe();
      }
    }
    function viewSpring() {
      const e = 0.14;
      let moved = false;
      for (const [k, t] of [
        ["rx", "trx"],
        ["ry", "try_"],
        ["z", "tz"],
      ] as const) {
        const d = view[t] - view[k];
        if (Math.abs(d) > 0.0006) {
          view[k] += d * e;
          moved = true;
        } else view[k] = view[t];
      }
      if (moved) applyView();
      viewActive = moved;
      return moved;
    }
    function setView(rx: number, ry: number, z: number) {
      view.trx = Math.max(-TILT_X, Math.min(TILT_X, rx));
      view.try_ = Math.max(-TILT_Y, Math.min(TILT_Y, ry));
      view.tz = Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, z));
      viewActive = true;
      kick();
      syncZoom();
    }
    /* the book leans toward the cursor — no dragging, and never far */
    function tiltTo(cx: number, cy: number) {
      if (drag) return;
      const r = book.getBoundingClientRect();
      if (!r.width) return;
      const nx = Math.max(-1, Math.min(1, (cx - (r.left + r.width / 2)) / (r.width * 0.62)));
      const ny = Math.max(-1, Math.min(1, (cy - (r.top + r.height / 2)) / (r.height * 0.9)));
      setView(-ny * TILT_X, nx * TILT_Y, view.tz);
    }
    const onWinMove = (e: PointerEvent) => {
      if (e.pointerType === "touch" || !visible || REDUCED) return;
      tiltTo(e.clientX, e.clientY);
    };
    const onWinOut = (e: PointerEvent) => {
      if (!e.relatedTarget) setView(0, 0, view.tz);
    };
    const onBlur = () => setView(0, 0, view.tz);
    const onDbl = () => setView(view.trx, view.try_, 1);

    /* pointer work */
    let drag: {
      dir: "next" | "prev";
      x0: number;
      w: number;
      moved: number;
      vel: number;
      tPrev: number;
    } | null = null;
    const hideHint = () => hintEl.classList.add("gone");
    const onDown = (e: PointerEvent) => {
      if (e.button !== 0 || !booted) return;
      const onBook = (e.target as HTMLElement).closest(".sb-zone");
      if ((e.target as HTMLElement).closest(".sb-arrow")) return;
      e.preventDefault();
      stage.setPointerCapture(e.pointerId);
      hideHint();
      if (!onBook || introOn) return;
      const r = book.getBoundingClientRect();
      const dir = (e.clientX - r.left) / r.width > 0.5 ? "next" : "prev";
      startTurn(dir, 0);
      drag = { dir, x0: e.clientX, w: r.width, moved: 0, vel: 0, tPrev: performance.now() };
    };
    const onMove = (e: PointerEvent) => {
      if (!drag) return;
      const dx = e.clientX - drag.x0;
      drag.moved = Math.max(drag.moved, Math.abs(dx));
      const raw = (drag.dir === "next" ? -dx : dx) / (drag.w * 0.62);
      const t = Math.max(0, Math.min(1, raw));
      const now = performance.now();
      drag.vel = (t - (turn ? turn.t : 0)) / Math.max(0.001, (now - drag.tPrev) / 1000);
      drag.tPrev = now;
      if (turn) {
        turn.t = t;
        applyTurn(t);
      }
    };
    const endDrag = () => {
      if (!drag) return;
      const d = drag;
      drag = null;
      if (!turn) return;
      if (d.moved < 6) {
        commit();
        return;
      }
      const go = turn.t > 0.42 || d.vel > 1.1;
      if (go) commit();
      else cancel();
    };
    const prevent = (e: Event) => e.preventDefault();

    /* turn control */
    function startTurn(dir: "next" | "prev", t: number) {
      spring = null;
      if (turn) {
        idx = turn.to;
        turn = null;
      }
      shoveLoupe(dir);
      const from = idx;
      turn = { dir, from, to: dir === "next" ? (from + 1) % M : (from - 1 + M) % M, t: t || 0 };
      paint();
    }
    function commit() {
      if (!turn) return;
      if (REDUCED) {
        idx = turn.to;
        turn = null;
        paint();
        return;
      }
      animateTo(
        1,
        () => {
          if (turn) idx = turn.to;
          turn = null;
          paint();
        },
        170,
        26,
      );
    }
    function cancel() {
      if (!turn) return;
      animateTo(
        0,
        () => {
          turn = null;
          paint();
        },
        150,
        24,
      );
    }
    function step(dir: "next" | "prev") {
      if (!booted) return;
      if (introOn) endIntro();
      if (turn) {
        idx = turn.to;
        turn = null;
      }
      startTurn(dir, 0);
      commit();
    }
    const onLeft = () => step("prev");
    const onRight = () => step("next");
    const onKey = (e: KeyboardEvent) => {
      if (!visible) return;
      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
      if (e.metaKey || e.ctrlKey || e.altKey) return;
      const t = e.target as HTMLElement | null;
      if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.isContentEditable)) return;
      e.preventDefault();
      hideHint();
      step(e.key === "ArrowRight" ? "next" : "prev");
    };

    /* loupe + controls */
    let loupeOn = true,
      lx: number | null = null,
      ly: number | null = null,
      lgrab: { cx: number; cy: number; lx0: number; ly0: number } | null = null,
      lTarget: { x: number; y: number } | null = null;
    const loupeSize = () => Math.round(Math.max(165, Math.min(262, book.clientWidth * 0.235)));
    const bookBox = () => ({ x: 0, y: 0, w: book.clientWidth, h: book.clientHeight });
    function restLoupe() {
      const b = bookBox();
      lx = b.x + b.w * 0.88;
      ly = b.y + b.h * 0.855;
      placeLoupe();
    }
    function syncZoomLayer() {
      zoomInner.textContent = "";
      for (const c of Array.from(book.children)) {
        if (c.classList.contains("sb-zone")) continue;
        zoomInner.appendChild(c.cloneNode(true));
      }
    }
    function placeLoupe() {
      if (lx === null || ly === null) return;
      const B = bookBox(),
        bw = B.w,
        bh = B.h;
      if (!bw) return;
      const R = loupeSize() / 2,
        bez = R * 2 * 0.058;
      loupe.style.setProperty("--lr", R * 2 + "px");
      loupe.style.transform =
        "translate3d(" + (lx - R).toFixed(1) + "px," + (ly - R).toFixed(1) + "px,0)";
      if (loupeOn) loupe.classList.add("on");
      const z = view.z,
        cx = bw / 2,
        cy = bh / 2;
      const x0 = cx + (bw * 0.051 - cx) * z,
        x1 = cx + (bw * 0.949 - cx) * z;
      const y0 = cy + (bh * 0.218 - cy) * z,
        y1 = cy + (bh * 0.782 - cy) * z;
      const nx = Math.max(x0, Math.min(lx, x1));
      const ny = Math.max(y0, Math.min(ly, y1));
      const inside =
        lx > x0 && lx < x1 && ly > y0 && ly < y1
          ? Math.min(lx - x0, x1 - lx, ly - y0, y1 - ly)
          : -Math.hypot(lx - nx, ly - ny);
      const k = Math.max(0, Math.min(1, (inside + R * 0.3) / (R * 0.55)));
      zoomWrap.style.opacity = (loupeOn ? k : 0).toFixed(3);
      if (k <= 0.002) return;
      const r = (R - bez).toFixed(1);
      const mask =
        "radial-gradient(circle " +
        r +
        "px at " +
        lx.toFixed(1) +
        "px " +
        ly.toFixed(1) +
        "px,#000 calc(100% - 1px),transparent 100%)";
      zoomWrap.style.webkitMaskImage = mask;
      zoomWrap.style.maskImage = mask;
      const px = cx + (lx - cx) / z,
        py = cy + (ly - cy) / z,
        s = MAG * z;
      zoomInner.style.transform =
        "translate(" +
        (lx - px * s).toFixed(1) +
        "px," +
        (ly - py * s).toFixed(1) +
        "px) scale(" +
        s.toFixed(4) +
        ")";
    }
    /* the leaf shoves the glass aside as it sweeps past */
    function shoveLoupe(dir: string) {
      if (!loupeOn || lx === null || ly === null || lgrab) return;
      const b = bookBox();
      const nx = (b.w / 2 + (lx - b.x - b.w / 2) / view.z) / b.w,
        ny = (b.h / 2 + (ly - b.y - b.h / 2) / view.z) / b.h;
      if (nx < 0.02 || nx > 0.98 || ny < 0.17 || ny > 0.83) return;
      lTarget = { x: b.x + b.w * (dir === "next" ? 0.12 : 0.88), y: b.y + b.h * 0.855 };
      kick();
    }
    function loupeEase() {
      if (!lTarget || lx === null || ly === null) return false;
      if (lgrab) {
        lTarget = null;
        return false;
      }
      const dx = lTarget.x - lx,
        dy = lTarget.y - ly;
      if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5) {
        lx = lTarget.x;
        ly = lTarget.y;
        lTarget = null;
        placeLoupe();
        return false;
      }
      lx += dx * 0.17;
      ly += dy * 0.17;
      placeLoupe();
      return true;
    }
    const onLoupeDown = (e: PointerEvent) => {
      if (!loupeOn || e.button !== 0 || lx === null || ly === null) return;
      e.preventDefault();
      e.stopPropagation();
      lTarget = null;
      lgrab = { cx: e.clientX, cy: e.clientY, lx0: lx, ly0: ly };
      loupe.classList.add("held");
      loupe.setPointerCapture(e.pointerId);
      hideHint();
    };
    const onLoupeMove = (e: PointerEvent) => {
      if (!lgrab) return;
      const b = bookBox(),
        R = loupeSize() / 2;
      lx = Math.max(
        b.x - R * 0.7,
        Math.min(b.x + b.w + R * 0.7, lgrab.lx0 + (e.clientX - lgrab.cx)),
      );
      ly = Math.max(
        b.y - R * 0.7,
        Math.min(b.y + b.h + R * 1.0, lgrab.ly0 + (e.clientY - lgrab.cy)),
      );
      placeLoupe();
    };
    const dropLoupe = () => {
      lgrab = null;
      loupe.classList.remove("held");
    };
    const onLoupeBtn = () => {
      loupeOn = !loupeOn;
      loupeBtn.setAttribute("aria-pressed", String(loupeOn));
      loupe.classList.toggle("on", loupeOn);
      if (loupeOn && lx === null) restLoupe();
      else placeLoupe();
    };
    function syncZoom() {
      zRead.textContent = Math.round(view.tz * 100) + "%";
      zOutBtn.disabled = view.tz <= ZOOM_MIN + 0.001;
      zInBtn.disabled = view.tz >= ZOOM_MAX - 0.001;
    }
    const onZIn = () => {
      setView(view.trx, view.try_, view.tz * 1.16);
      hideHint();
    };
    const onZOut = () => {
      setView(view.trx, view.try_, view.tz / 1.16);
      hideHint();
    };

    /* the riffle */
    let riffle: { bell: number; dur: number }[] = [],
      riffleAt = 0,
      introOn = false;
    function endIntro() {
      introOn = false;
      wrap.classList.remove("intro", "b2");
    }
    function riffleStep() {
      const s = riffle[riffleAt];
      wrap.classList.toggle("b2", s.bell > 0.55);
      startTurn("next", 0);
      tweenTo(1, s.dur, () => {
        if (turn) idx = turn.to;
        turn = null;
        riffleAt++;
        if (introOn && riffleAt < riffle.length) {
          paint();
          riffleStep();
        } else {
          endIntro();
          paint();
        }
      });
    }
    let introPending = true;
    function startIntro() {
      const coarse = matchMedia("(max-width: 640px), (pointer: coarse)").matches;
      if (coarse || REDUCED || !intro || M < 2) {
        idx = LAND;
        paint();
        return;
      }
      const steps = M + LAND;
      riffle = [];
      for (let r = 0; r < steps; r++) {
        const bell = Math.sin(Math.PI * (r / (steps - 1)));
        riffle.push({ bell, dur: 0.26 - 0.19 * bell });
      }
      riffleAt = 0;
      introOn = true;
      wrap.classList.add("intro");
      riffleStep();
    }

    const ro = new ResizeObserver(() => {
      layout();
      if (booted) {
        lx = null;
        restLoupe();
      }
    });
    ro.observe(book);
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible && booted && introPending) {
        introPending = false;
        timers.push(window.setTimeout(startIntro, 220));
      }
    });
    io.observe(root);

    stage.addEventListener("pointerdown", onDown);
    stage.addEventListener("pointermove", onMove);
    stage.addEventListener("pointerup", endDrag);
    stage.addEventListener("pointercancel", endDrag);
    stage.addEventListener("dragstart", prevent);
    stage.addEventListener("selectstart", prevent);
    stage.addEventListener("dblclick", onDbl);
    leftBtn.addEventListener("click", onLeft);
    rightBtn.addEventListener("click", onRight);
    loupe.addEventListener("pointerdown", onLoupeDown);
    loupe.addEventListener("pointermove", onLoupeMove);
    loupe.addEventListener("pointerup", dropLoupe);
    loupe.addEventListener("pointercancel", dropLoupe);
    loupeBtn.addEventListener("click", onLoupeBtn);
    zInBtn.addEventListener("click", onZIn);
    zOutBtn.addEventListener("click", onZOut);
    window.addEventListener("pointermove", onWinMove, { passive: true });
    window.addEventListener("pointerout", onWinOut);
    window.addEventListener("blur", onBlur);
    window.addEventListener("keydown", onKey);

    /* boot */
    (async () => {
      const sheet = sheetColor;
      const urls = await Promise.all(PAGES.map((p) => composeSpread(p, sheet, inkColor)));
      if (disposed) {
        urls.forEach((u) => u.startsWith("blob:") && URL.revokeObjectURL(u));
        return;
      }
      urls.forEach((u, i) => {
        PAGES[i].url = u;
        if (u.startsWith("blob:")) objectUrls.push(u);
      });
      await Promise.all(
        PAGES.map((p) => {
          const im = new Image();
          im.src = p.url;
          return im.decode().catch(() => {});
        }),
      );
      if (disposed) return;
      idx = intro && !REDUCED ? 0 : LAND;
      paint();
      applyView();
      syncZoom();
      restLoupe();
      booted = true;
      if (visible && introPending) {
        introPending = false;
        timers.push(window.setTimeout(startIntro, 220));
      }
    })();

    return () => {
      disposed = true;
      if (raf !== null) cancelAnimationFrame(raf);
      timers.forEach((t) => clearTimeout(t));
      ro.disconnect();
      io.disconnect();
      stage.removeEventListener("pointerdown", onDown);
      stage.removeEventListener("pointermove", onMove);
      stage.removeEventListener("pointerup", endDrag);
      stage.removeEventListener("pointercancel", endDrag);
      stage.removeEventListener("dragstart", prevent);
      stage.removeEventListener("selectstart", prevent);
      stage.removeEventListener("dblclick", onDbl);
      leftBtn.removeEventListener("click", onLeft);
      rightBtn.removeEventListener("click", onRight);
      loupe.removeEventListener("pointerdown", onLoupeDown);
      loupe.removeEventListener("pointermove", onLoupeMove);
      loupe.removeEventListener("pointerup", dropLoupe);
      loupe.removeEventListener("pointercancel", dropLoupe);
      loupeBtn.removeEventListener("click", onLoupeBtn);
      zInBtn.removeEventListener("click", onZIn);
      zOutBtn.removeEventListener("click", onZOut);
      window.removeEventListener("pointermove", onWinMove);
      window.removeEventListener("pointerout", onWinOut);
      window.removeEventListener("blur", onBlur);
      window.removeEventListener("keydown", onKey);
      book.textContent = "";
      zoomInner.textContent = "";
      capBox.textContent = "";
      wrap.classList.remove("intro", "b2");
      loupe.classList.remove("on", "held");
      objectUrls.forEach((u) => URL.revokeObjectURL(u));
    };
  }, [
    pagesKey,
    startPage,
    intro,
    magnification,
    sheetColor,
    inkColor,
    prefersReducedMotion,
    themeKey,
  ]);

  return (
    <div
      ref={rootRef}
      className={cn("msb absolute inset-0 overflow-hidden", className)}
      style={
        {
          background: paperColor,
          "--paper": paperColor,
          "--ink": inkColor,
          "--earth": accentColor,
          "--sheet": sheetColor,
        } as React.CSSProperties
      }
    >
      <style dangerouslySetInnerHTML={{ __html: STYLE }} />
      <div className="wash" aria-hidden="true" />
      <section className="hero">
        <div className="sb-wrap">
          <svg width="0" height="0" style={{ position: "absolute" }} aria-hidden="true">
            <filter id="msb-mblur-1">
              <feGaussianBlur stdDeviation="5 0" />
            </filter>
            <filter id="msb-mblur-2">
              <feGaussianBlur stdDeviation="14 0" />
            </filter>
          </svg>
          <div className="sb-stage">
            <button className="sb-arrow left" aria-label="previous page">
              <svg viewBox="0 0 14 44" width="14" height="44" fill="none" aria-hidden="true">
                <polyline
                  points="11,3 3,22 11,41"
                  stroke="currentColor"
                  strokeWidth="1.1"
                  strokeLinecap="round"
                  strokeLinejoin="round"
                />
              </svg>
            </button>
            <div className="sb-3d">
              <div className="sb-tilt">
                <div className="sb-cast ambient" aria-hidden="true" />
                <div className="sb-cast contact" aria-hidden="true" />
                <div className="sb-cast hair" aria-hidden="true" />
                <div className="sb-book" />
              </div>
              <div className="zoomwrap" aria-hidden="true">
                <div className="zoominner" />
              </div>
              <div className="loupe">
                <span className="grip" />
                <span className="ring">
                  <span className="lens" />
                </span>
              </div>
            </div>
            <button className="sb-arrow right" aria-label="next page">
              <svg viewBox="0 0 14 44" width="14" height="44" fill="none" aria-hidden="true">
                <polyline
                  points="3,3 11,22 3,41"
                  stroke="currentColor"
                  strokeWidth="1.1"
                  strokeLinecap="round"
                  strokeLinejoin="round"
                />
              </svg>
            </button>
          </div>
          <div className="sb-captions" aria-live="polite" />
          <div className="sb-tools" role="group" aria-label="view controls">
            <button className="tool" data-zout="" aria-label="zoom out">
              <svg
                viewBox="0 0 20 20"
                fill="none"
                stroke="currentColor"
                strokeWidth="1.6"
                strokeLinecap="round"
              >
                <circle cx="8.6" cy="8.6" r="5.6" />
                <path d="M12.8 12.8 17.4 17.4M6.2 8.6h4.8" />
              </svg>
            </button>
            <span className="zoom-read">100%</span>
            <button className="tool" data-zin="" aria-label="zoom in">
              <svg
                viewBox="0 0 20 20"
                fill="none"
                stroke="currentColor"
                strokeWidth="1.6"
                strokeLinecap="round"
              >
                <circle cx="8.6" cy="8.6" r="5.6" />
                <path d="M12.8 12.8 17.4 17.4M6.2 8.6h4.8M8.6 6.2v4.8" />
              </svg>
            </button>
            <span className="tool-sep" aria-hidden="true" />
            <button className="tool" data-loupe="" aria-label="magnifier" aria-pressed="true">
              <svg
                viewBox="0 0 20 20"
                fill="none"
                stroke="currentColor"
                strokeWidth="1.6"
                strokeLinecap="round"
              >
                <circle cx="8.8" cy="8.8" r="5.8" />
                <path d="M13 13l4.4 4.4" />
                <path d="M6.4 7.2a3.2 3.2 0 0 1 2.4-1.4" opacity=".55" />
              </svg>
            </button>
          </div>
          <p className="sb-hint">{hint}</p>
        </div>
      </section>
    </div>
  );
}
```

---

# Ink Capsule

> An ink-filled capsule with a comet of light orbiting inside it and a serif label.

Install: `npx @modus-ui/cli add ink-capsule`

A capsule filled with the theme's primary ink, with a soft comet of light circling inside it. On hover the comet settles into a centred glow and a halo ring widens around the capsule. The label is set in the heading serif. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-capsule
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ink-capsule.tsx`.
4. Paste the code.

## Usage

```tsx
import { InkCapsule } from "@/components/ui/ink-capsule";

export default function Example() {
  return <InkCapsule onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default           | Description    |
| :-------- | :------------------------------------- | :---------------- | :------------- |
| `label`   | `string`                               | `"Join the list"` | Button text.   |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`       | Click handler. |

## Source

`components/ui/ink-capsule.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Dark Pill (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface InkCapsuleProps {
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

// An ink-filled capsule with a slow comet of light orbiting inside it.
const STYLES = `
.m-ink-capsule {
  position: relative; display: inline-flex; align-items: center; justify-content: center; gap: 12px;
  height: 60px; padding: 0 34px; overflow: hidden; border: 0; border-radius: 999px; cursor: pointer;
  color: hsl(var(--primary-foreground)); background: hsl(var(--primary)); isolation: isolate;
  box-shadow: 0 0 0 4px hsl(var(--primary) / .08), 0 18px 36px -18px hsl(var(--primary) / .8),
    inset 0 1px 0 hsl(var(--primary-foreground) / .2);
  transition: transform .3s ease, box-shadow .3s ease;
}
.m-ink-capsule::after {
  content: ""; position: absolute; inset: 0; z-index: 2; border-radius: inherit; pointer-events: none;
  border: 1px solid hsl(var(--primary-foreground) / .35);
  -webkit-mask-image: linear-gradient(170deg, black, transparent 55%); mask-image: linear-gradient(170deg, black, transparent 55%);
}
.m-ink-capsule-label { position: relative; z-index: 3; }
.m-ink-capsule-dot { position: relative; z-index: 3; width: 6px; height: 6px; border-radius: 999px; background: currentColor; opacity: .7; }
.m-ink-capsule-comet { position: absolute; z-index: 1; top: calc(50% - 90px); left: calc(50% - 90px); width: 180px; height: 180px; pointer-events: none; }
.m-ink-capsule-comet::before, .m-ink-capsule-comet::after { content: ""; position: absolute; inset: 0; border-radius: 50%; }
.m-ink-capsule-comet::before {
  background: conic-gradient(from 180deg, transparent 200deg, hsl(var(--primary-foreground) / .28) 360deg);
  filter: blur(14px); animation: m-ink-capsule-orbit 4.2s linear infinite; transition: opacity .5s;
}
.m-ink-capsule-comet::after {
  inset: 40px; background: hsl(var(--primary-foreground) / .22); opacity: 0; filter: blur(8px);
  transform: scale(.5); transition: opacity .5s, transform .7s;
}
.m-ink-capsule:hover { transform: translateY(-1px); box-shadow: 0 0 0 8px hsl(var(--primary) / .08), 0 22px 40px -18px hsl(var(--primary) / .9), inset 0 1px 0 hsl(var(--primary-foreground) / .2); }
.m-ink-capsule:hover .m-ink-capsule-comet::before { opacity: 0; }
.m-ink-capsule:hover .m-ink-capsule-comet::after { opacity: 1; transform: scale(1); }
.m-ink-capsule:active { transform: scale(.98); }
.m-ink-capsule:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 5px; }
@keyframes m-ink-capsule-orbit {
  0% { transform: translate(0) rotate(0); }
  25% { transform: translateX(-36px) rotate(90deg); }
  50% { transform: translate(0) rotate(180deg); }
  75% { transform: translateX(36px) rotate(270deg); }
  100% { transform: translate(0) rotate(360deg); }
}
.m-ink-capsule[data-reduced], .m-ink-capsule[data-reduced] * , .m-ink-capsule[data-reduced] *::before, .m-ink-capsule[data-reduced] *::after { animation: none !important; transition: none !important; }
.m-ink-capsule[data-reduced]:active { transform: none; }
`;

export function InkCapsule({ label = "Join the list", onClick, className }: InkCapsuleProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <button
        className={cn("m-ink-capsule font-serif text-xl", className)}
        type="button"
        data-reduced={prefersReducedMotion ? "" : undefined}
        onClick={onClick}
      >
        <span className="m-ink-capsule-dot" aria-hidden="true" />
        <span className="m-ink-capsule-label">{label}</span>
        <span className="m-ink-capsule-comet" aria-hidden="true" />
      </button>
    </>
  );
}
```

---

# Keystroke Button

> A keycap button with a key legend, a serif label and a hard bottom edge that sinks when pressed.

Install: `npx @modus-ui/cli add keystroke-button`

A keycap shaded from the card and muted tokens with a hard ink edge underneath. A mono key legend and a small primary status light sit in its top row above a serif label; a primary halo blooms on hover and the cap sinks 3px when pressed. Transitions are off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add keystroke-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/keystroke-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { KeystrokeButton } from "@/components/ui/keystroke-button";

export default function Example() {
  return <KeystrokeButton onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default            | Description                                  |
| :-------- | :------------------------------------- | :----------------- | :------------------------------------------- |
| `label`   | `string`                               | `"Commit changes"` | Button text.                                 |
| `keyHint` | `string`                               | `"⌘ S"`            | Key legend printed in the corner of the cap. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`        | Click handler.                               |

## Source

`components/ui/keystroke-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Launch Button (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface KeystrokeButtonProps {
  label?: string;
  /** Key legend printed in the corner of the cap. */
  keyHint?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

export function KeystrokeButton({
  label = "Commit changes",
  keyHint = "⌘ S",
  onClick,
  className,
}: KeystrokeButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <button
      type="button"
      onClick={onClick}
      className={cn(
        "group/key relative rounded-[12px] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-4 focus-visible:ring-offset-background",
        className,
      )}
    >
      <span
        aria-hidden
        className={cn(
          "absolute -inset-2 rounded-[16px] bg-[hsl(var(--primary)/0.25)] opacity-0 blur-lg group-hover/key:opacity-100",
          !prefersReducedMotion && "transition-opacity duration-500",
        )}
      />
      <span
        className={cn(
          "relative flex min-w-[220px] flex-col items-start gap-3 rounded-[12px] border border-[hsl(var(--border))] bg-[linear-gradient(180deg,hsl(var(--card)),hsl(var(--muted)))] px-5 pb-3.5 pt-3 text-left text-foreground shadow-[0_5px_0_hsl(var(--foreground)/0.75),0_14px_22px_-8px_hsl(var(--foreground)/0.4)] active:shadow-[0_2px_0_hsl(var(--foreground)/0.75),0_6px_10px_-6px_hsl(var(--foreground)/0.4)]",
          !prefersReducedMotion && "transition-all duration-150 active:translate-y-[3px]",
        )}
      >
        <span className="flex w-full items-center justify-between font-mono text-[10px] uppercase tracking-[0.2em] text-muted-foreground">
          <span>{keyHint}</span>
          <span className="h-1.5 w-1.5 rounded-full bg-[hsl(var(--primary))] shadow-[0_0_8px_hsl(var(--primary))]" />
        </span>
        <span className="font-serif text-xl leading-none">{label}</span>
      </span>
    </button>
  );
}
```

---

# Stitch Frame Button

> A paper button that pins four corners and stitches a dashed frame around itself on hover.

Install: `npx @modus-ui/cli add stitch-frame-button`

A card-coloured button with an italic serif label. On hover four round pins travel to the corners, a dashed frame is stitched around it one edge at a time, a dot grid fades in behind, and the button fills with the primary ink. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add stitch-frame-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/stitch-frame-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { StitchFrameButton } from "@/components/ui/stitch-frame-button";

export default function Example() {
  return <StitchFrameButton onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default             | Description    |
| :-------- | :------------------------------------- | :------------------ | :------------- |
| `label`   | `string`                               | `"Start sketching"` | Button text.   |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`         | Click handler. |

## Source

`components/ui/stitch-frame-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Dot Border Button (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface StitchFrameButtonProps {
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

// On hover four pins travel to the corners and a stitched frame is sewn around the button, one edge at a time.
const STYLES = `
.msf-wrap {
  --pin: 7px; --speed: .32s; --ink: hsl(var(--primary));
  position: relative; display: inline-flex; padding: .9rem 1.1rem; isolation: isolate; user-select: none;
}
.msf-wrap::after {
  content: ""; position: absolute; inset: 0; z-index: -1; pointer-events: none; opacity: 0;
  background-image: radial-gradient(hsl(var(--primary) / .28) 1px, transparent 1.2px); background-size: 6px 6px;
}
.msf-wrap:has(.msf-btn:hover)::after { animation: msf-fade calc(var(--speed) * 4) ease-in-out forwards; }
@keyframes msf-fade { 80% { opacity: 0; } 100% { opacity: 1; } }
.msf-btn {
  display: flex; align-items: center; gap: .6rem; padding: .7rem 1.4rem; white-space: nowrap; border: 1px solid hsl(var(--border));
  border-radius: calc(var(--radius) - 2px); background: hsl(var(--card)); color: hsl(var(--foreground)); cursor: pointer;
  transition: transform .2s ease-in-out, background-color .2s ease-in-out, color .2s ease-in-out;
}
.msf-btn:hover { background: var(--ink); color: hsl(var(--primary-foreground)); transform: scale(1.04); }
.msf-btn:active { transform: scale(.98); }
.msf-btn:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 4px; }
.msf-svg { width: 18px; height: 18px; fill: none; stroke: currentColor; stroke-width: 1.4; stroke-linecap: round; stroke-linejoin: round; transition: transform .3s ease; }
.msf-btn:hover .msf-svg { transform: rotate(-12deg); }
.msf-pin { position: absolute; width: var(--pin); aspect-ratio: 1; border-radius: 999px; background: var(--ink); opacity: 0; }
.msf-wrap:has(.msf-btn:hover) .msf-pin.t.l { top: 50%; left: 20%; animation: msf-tl var(--speed) ease-in-out forwards; }
.msf-wrap:has(.msf-btn:hover) .msf-pin.t.r { top: 50%; right: 20%; animation: msf-tr var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * .6); }
.msf-wrap:has(.msf-btn:hover) .msf-pin.b.r { bottom: 50%; right: 20%; animation: msf-br var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * 1.2); }
.msf-wrap:has(.msf-btn:hover) .msf-pin.b.l { bottom: 50%; left: 20%; animation: msf-bl var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * 1.8); }
@keyframes msf-tl { 100% { top: calc(var(--pin) * -.5); left: calc(var(--pin) * -.5); opacity: 1; } }
@keyframes msf-tr { 100% { top: calc(var(--pin) * -.5); right: calc(var(--pin) * -.5); opacity: 1; } }
@keyframes msf-br { 100% { bottom: calc(var(--pin) * -.5); right: calc(var(--pin) * -.5); opacity: 1; } }
@keyframes msf-bl { 100% { bottom: calc(var(--pin) * -.5); left: calc(var(--pin) * -.5); opacity: 1; } }
.msf-line { position: absolute; }
.msf-line.h { height: 1px; width: 100%; background-image: repeating-linear-gradient(90deg, transparent 0 3px, var(--ink) 3px 7px); }
.msf-line.v { width: 1px; height: 100%; background-image: repeating-linear-gradient(0deg, transparent 0 3px, var(--ink) 3px 7px); }
.msf-line.t { top: 0; transform-origin: left; transform: scaleX(0); }
.msf-line.b { bottom: 0; transform-origin: right; transform: scaleX(0); }
.msf-line.l { left: 0; transform-origin: bottom; transform: scaleY(0); }
.msf-line.r { right: 0; transform-origin: top; transform: scaleY(0); }
.msf-wrap:has(.msf-btn:hover) .msf-line.t { animation: msf-x var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * .8); }
.msf-wrap:has(.msf-btn:hover) .msf-line.r { animation: msf-y var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * 1.4); }
.msf-wrap:has(.msf-btn:hover) .msf-line.b { animation: msf-x var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * 2); }
.msf-wrap:has(.msf-btn:hover) .msf-line.l { animation: msf-y var(--speed) ease-in-out forwards; animation-delay: calc(var(--speed) * 2.4); }
@keyframes msf-x { 100% { transform: scaleX(1); } }
@keyframes msf-y { 100% { transform: scaleY(1); } }
.msf-wrap[data-reduced] *, .msf-wrap[data-reduced]::after { animation-duration: .01ms !important; animation-delay: 0s !important; transition: none !important; }
.msf-wrap[data-reduced] .msf-btn:hover, .msf-wrap[data-reduced] .msf-btn:active { transform: none; }
`;

export function StitchFrameButton({
  label = "Start sketching",
  onClick,
  className,
}: StitchFrameButtonProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <div className={cn("msf-wrap", className)} data-reduced={prefersReducedMotion ? "" : undefined}>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <div className="msf-line h t" />
      <div className="msf-line v r" />
      <div className="msf-line h b" />
      <div className="msf-line v l" />
      <div className="msf-pin t l" />
      <div className="msf-pin t r" />
      <div className="msf-pin b r" />
      <div className="msf-pin b l" />
      <button type="button" className="msf-btn font-serif text-xl italic" onClick={onClick}>
        <span>{label}</span>
        <svg className="msf-svg" viewBox="0 0 24 24" aria-hidden="true">
          <path d="M4 20l4-1 11-11a2.1 2.1 0 0 0-3-3L5 16l-1 4Z" />
          <path d="M14 7l3 3" />
        </svg>
      </button>
    </div>
  );
}
```

---

# Rising Motes

> A primary-ink button with motes of light drifting up through it.

Install: `npx @modus-ui/cli add rising-motes`

A button in the theme's primary colour, lit from below, with small motes drifting upward through it. The arrow rises on hover and the button presses in on click. The label is set in uppercase mono. Animations and transitions are turned off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add rising-motes
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/rising-motes.tsx`.
4. Paste the code.

## Usage

```tsx
import { RisingMotes } from "@/components/ui/rising-motes";

export default function Example() {
  return <RisingMotes onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default       | Description    |
| :-------- | :------------------------------------- | :------------ | :------------- |
| `label`   | `string`                               | `"Subscribe"` | Button text.   |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`   | Click handler. |

## Source

`components/ui/rising-motes.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Floating Dots CTA (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface RisingMotesProps {
  label?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

const MOTES: [string, number, number, number][] = [
  // left, opacity, duration (s), delay (s)
  ["8%", 0.9, 2.6, 0.3],
  ["19%", 0.6, 2.2, 1.1],
  ["31%", 0.8, 2.9, 0],
  ["42%", 0.5, 2.4, 0.7],
  ["53%", 1, 2.1, 0.2],
  ["61%", 0.6, 2.7, 1.4],
  ["72%", 0.9, 2.3, 0.5],
  ["81%", 0.7, 2.8, 0.9],
  ["90%", 0.8, 2.0, 0.1],
  ["96%", 0.5, 2.5, 1.6],
  ["14%", 0.7, 3.0, 1.9],
  ["67%", 0.6, 3.1, 2.2],
];

const STYLES = `
.mrm-btn {
  position: relative; display: inline-flex; align-items: center; justify-content: center; overflow: hidden;
  min-height: 52px; padding: 0 26px; border: 0; border-radius: calc(var(--radius) + 4px); cursor: pointer;
  color: hsl(var(--primary-foreground)); isolation: isolate;
  background: radial-gradient(70% 90% at 50% 120%, color-mix(in oklab, hsl(var(--primary)) 55%, hsl(var(--primary-foreground))) 0%, transparent 100%), hsl(var(--primary));
  box-shadow: 0 0 0 1px hsl(var(--primary) / .5), 0 16px 30px -16px hsl(var(--primary));
  transition: transform .25s ease, box-shadow .25s ease;
}
.mrm-btn::before {
  content: ""; position: absolute; inset: 1px; border-radius: inherit; pointer-events: none;
  background: linear-gradient(178deg, hsl(var(--primary-foreground) / .22), transparent 60%);
}
.mrm-btn:hover { transform: translateY(-1px); box-shadow: 0 0 0 1px hsl(var(--primary) / .5), 0 20px 38px -16px hsl(var(--primary)); }
.mrm-btn:active { transform: scale(.96); }
.mrm-btn:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 4px; }
.mrm-motes { position: absolute; inset: 0; overflow: hidden; pointer-events: none; z-index: 1; }
.mrm-mote { position: absolute; bottom: -6px; width: 3px; height: 3px; border-radius: 999px; background: hsl(var(--primary-foreground)); animation: mrm-rise infinite ease-in-out; }
@keyframes mrm-rise { 0% { transform: translateY(0) scale(1); } 85% { opacity: 0; } 100% { transform: translateY(-60px) scale(.4); opacity: 0; } }
${MOTES.map(
  ([left, opacity, duration, delay], index) =>
    `.mrm-mote:nth-child(${index + 1}) { left: ${left}; opacity: ${opacity}; animation-duration: ${duration}s; animation-delay: ${delay}s; }`,
).join("\n")}
.mrm-inner { position: relative; z-index: 2; display: inline-flex; align-items: center; gap: 10px; }
.mrm-icon { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; transition: transform .3s ease; }
.mrm-btn:hover .mrm-icon { transform: translateY(-3px); }
.mrm-btn[data-reduced], .mrm-btn[data-reduced] *, .mrm-btn[data-reduced]::before { animation: none !important; transition: none !important; }
.mrm-btn[data-reduced]:active, .mrm-btn[data-reduced]:hover .mrm-icon { transform: none; }
`;

export function RisingMotes({ label = "Subscribe", onClick, className }: RisingMotesProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <>
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <button
        type="button"
        onClick={onClick}
        className={cn("mrm-btn font-mono text-xs uppercase tracking-[0.22em]", className)}
        data-reduced={prefersReducedMotion ? "" : undefined}
      >
        <span className="mrm-motes" aria-hidden="true">
          {MOTES.map((_, index) => (
            <i key={index} className="mrm-mote" />
          ))}
        </span>
        <span className="mrm-inner">
          {label}
          <svg className="mrm-icon" viewBox="0 0 24 24" aria-hidden="true">
            <path d="M12 19V5" />
            <path d="m6 11 6-6 6 6" />
          </svg>
        </span>
      </button>
    </>
  );
}
```

---

# Roll Label

> A paper pill whose mono label rolls up and away while an inked copy with an arrow rises in on hover.

Install: `npx @modus-ui/cli add roll-label`

A card-coloured pill with a hairline border and an uppercase mono label. On hover the button lifts, the label rolls upward and blurs out while a copy in the theme's primary colour rises from below with an arrow, and a primary underline draws across. It follows the active theme and palette in light and dark mode. Hue, saturation and brightness grade the button with a CSS filter, and the motion is switched off when the user prefers reduced motion. The component centres the button in its parent and is transparent unless you pass `background`.

## Installation

### CLI

```bash
npx @modus-ui/cli add roll-label
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/roll-label.tsx`.
4. Paste the code.

## Usage

```tsx
import { RollLabel } from "@/components/ui/roll-label";

export default function Example() {
  return (
    <div className="h-[300px] w-full">
      <RollLabel onClick={() => console.log("clicked")} />
    </div>
  );
}
```

## Props

| Prop         | Type                                   | Default              | Description                                      |
| :----------- | :------------------------------------- | :------------------- | :----------------------------------------------- |
| `label`      | `string`                               | `"Open the archive"` | Button text.                                     |
| `hue`        | `number`                               | `0`                  | Hue rotation in degrees, clamped to -180 to 180. |
| `saturation` | `number`                               | `1`                  | Saturation multiplier, clamped to 0 to 2.        |
| `brightness` | `number`                               | `1`                  | Brightness multiplier, clamped to 0.35 to 1.65.  |
| `background` | `string`                               | `undefined`          | Stage background; transparent when omitted.      |
| `onClick`    | `MouseEventHandler<HTMLButtonElement>` | `undefined`          | Click handler.                                   |

## Source

`components/ui/roll-label.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Sliding Text CTA (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useEffect, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

interface RollLabelProps {
  label?: string;
  hue?: number;
  saturation?: number;
  brightness?: number;
  background?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

const clamp = (value: number, minimum: number, maximum: number) =>
  Math.min(maximum, Math.max(minimum, value));

const EASE = "ease-[cubic-bezier(0.15,0.83,0.66,1)]";

export function RollLabel({
  hue = 0,
  saturation = 1,
  brightness = 1,
  background,
  onClick,
  className,
  label = "Open the archive",
}: RollLabelProps) {
  const prefersReduced = useReducedMotion();
  // Follow the setting only after hydration, so the first render matches the server's.
  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
  useEffect(() => setPrefersReducedMotion(Boolean(prefersReduced)), [prefersReduced]);
  const filter = `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  return (
    <div
      className={cn("flex h-full w-full items-center justify-center overflow-hidden", className)}
      style={{ background, filter }}
    >
      <button
        type="button"
        onClick={onClick}
        className={cn(
          "group relative inline-flex min-w-[120px] cursor-pointer items-center justify-center overflow-hidden rounded-full border border-[hsl(var(--border))] bg-[hsl(var(--card))] px-6 py-3.5 font-mono text-[12px] font-medium uppercase tracking-[0.18em] text-foreground",
          "shadow-[0_1px_0_hsl(var(--background)),0_10px_24px_-14px_hsl(var(--foreground)/0.45)] hover:border-[hsl(var(--primary)/0.5)]",
          "focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-[3px] focus-visible:outline-[hsl(var(--primary))]",
          !prefersReducedMotion && cn("transition-all duration-700 hover:-translate-y-[2px]", EASE),
        )}
      >
        <span
          className={cn(
            "relative z-10",
            !prefersReducedMotion &&
              "transition-all duration-500 ease-out group-hover:-translate-y-7 group-hover:opacity-0 group-hover:blur-[3px]",
          )}
        >
          {label}
        </span>
        {!prefersReducedMotion && (
          <span
            aria-hidden="true"
            className="absolute inset-0 z-10 flex translate-y-7 items-center justify-center gap-2 text-[hsl(var(--primary))] opacity-0 blur-[3px] transition-all duration-300 ease-in-out group-hover:translate-y-0 group-hover:opacity-100 group-hover:blur-none"
          >
            {label}
            <span className="text-[13px] leading-none">&rarr;</span>
          </span>
        )}
        <span
          aria-hidden="true"
          className={cn(
            "absolute bottom-[7px] left-6 right-6 h-px origin-left scale-x-0 bg-[hsl(var(--primary)/0.6)] group-hover:scale-x-100",
            !prefersReducedMotion && cn("transition-transform duration-700", EASE),
          )}
        />
      </button>
    </div>
  );
}
```

---

# Comet Ring Button

> A card-toned button whose hairline rim is chased by a comet of theme colour.

Install: `npx @modus-ui/cli add comet-ring-button`

A quiet card-toned button with a mono, tracked label. A single comet of the theme's primary colour laps its hairline rim, a fine ruled texture drifts across the face, and on hover a soft glow rises from below while the arrow chip turns. Everything is drawn from the theme tokens, so it follows light, dark and every palette; motion stops when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add comet-ring-button
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/comet-ring-button.tsx`.
4. Paste the code.

## Usage

```tsx
import { CometRingButton } from "@/components/ui/comet-ring-button";

export default function Example() {
  return <CometRingButton onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default           | Description                                           |
| :-------- | :------------------------------------- | :---------------- | :---------------------------------------------------- |
| `label`   | `string`                               | `"Begin a draft"` | Button text.                                          |
| `speed`   | `number`                               | `4`               | Seconds for the comet to complete one lap of the rim. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`       | Click handler.                                        |

## Source

`components/ui/comet-ring-button.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Gradient Beam CTA (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface CometRingButtonProps {
  label?: string;
  /** Seconds for the comet to complete one lap of the rim. */
  speed?: number;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

const KEYFRAMES = `
@keyframes mcr-orbit { to { transform: rotate(360deg); } }
@keyframes mcr-grain { to { background-position: 18px 0; } }
`;

export function CometRingButton({
  label = "Begin a draft",
  speed = 4,
  onClick,
  className,
}: CometRingButtonProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <button
      type="button"
      onClick={onClick}
      className={cn(
        "group relative isolate inline-flex items-center gap-3 overflow-hidden rounded-[14px] py-4 pl-7 pr-5 font-mono text-xs uppercase tracking-[0.22em] text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-2 focus-visible:ring-offset-background",
        !prefersReducedMotion && "transition-transform duration-500 hover:-translate-y-0.5",
        className,
      )}
    >
      <style dangerouslySetInnerHTML={{ __html: KEYFRAMES }} />
      <span aria-hidden className="absolute inset-0 -z-20 overflow-hidden rounded-[14px]">
        <span className="absolute inset-0 bg-[hsl(var(--border))]" />
        <span
          className="absolute left-1/2 top-1/2 aspect-square w-[160%] -translate-x-1/2 -translate-y-1/2"
          style={{
            background:
              "conic-gradient(from 0deg, transparent 0 250deg, hsl(var(--primary) / 0.2) 300deg, hsl(var(--primary)) 352deg, hsl(var(--background)) 357deg, transparent 360deg)",
            animation: prefersReducedMotion ? "none" : `mcr-orbit ${speed}s linear infinite`,
          }}
        />
      </span>
      <span
        aria-hidden
        className="absolute inset-[1.5px] -z-10 overflow-hidden rounded-[12.5px] bg-card"
      >
        <span
          className="absolute inset-0 opacity-60"
          style={{
            backgroundImage:
              "repeating-linear-gradient(90deg, hsl(var(--foreground) / 0.07) 0 1px, transparent 1px 6px)",
            animation: prefersReducedMotion ? "none" : "mcr-grain 6s linear infinite",
          }}
        />
        <span
          className={cn(
            "absolute -bottom-6 left-1/2 h-12 w-3/4 -translate-x-1/2 rounded-full bg-[hsl(var(--primary)/0.12)] blur-xl group-hover:bg-[hsl(var(--primary)/0.3)]",
            !prefersReducedMotion && "transition-colors duration-500",
          )}
        />
      </span>
      <span className="relative">{label}</span>
      <span
        aria-hidden
        className={cn(
          "relative grid h-6 w-6 place-items-center rounded-full border border-[hsl(var(--primary)/0.5)] text-[hsl(var(--primary))]",
          !prefersReducedMotion && "transition-transform duration-300 group-hover:rotate-45",
        )}
      >
        <svg
          viewBox="0 0 24 24"
          width="12"
          height="12"
          fill="none"
          stroke="currentColor"
          strokeWidth="2"
          strokeLinecap="round"
        >
          <path d="M7 17 17 7M9 7h8v8" />
        </svg>
      </span>
    </button>
  );
}
```

---

# Satin Capsule

> A satin card-toned capsule with a graded hairline, a mono annotation and a primary arrow chip.

Install: `npx @modus-ui/cli add satin-capsule`

A satin capsule shaded from the card and muted tokens, edged by a graded hairline. The label sits beside a small mono annotation and a round arrow chip in the primary colour that nudges forward on hover, while the shadow warms toward the primary. Transitions are off when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add satin-capsule
```

### Manual

1. Install `framer-motion`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/satin-capsule.tsx`.
4. Paste the code.

## Usage

```tsx
import { SatinCapsule } from "@/components/ui/satin-capsule";

export default function Example() {
  return <SatinCapsule onClick={() => console.log("clicked")} />;
}
```

## Props

| Prop      | Type                                   | Default            | Description                                                             |
| :-------- | :------------------------------------- | :----------------- | :---------------------------------------------------------------------- |
| `label`   | `string`                               | `"Read the notes"` | Button text.                                                            |
| `meta`    | `string`                               | `"04 min"`         | Small mono annotation after the label; pass an empty string to hide it. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined`        | Click handler.                                                          |

## Source

`components/ui/satin-capsule.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Gradient Pill Button (MIT, © 2026 Meng To).

import type { MouseEventHandler } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface SatinCapsuleProps {
  label?: string;
  /** Small mono annotation after the label; pass an empty string to hide it. */
  meta?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
  className?: string;
}

// A hairline drawn by a masked ::before, graded from the theme ink.
const BORDER_STYLE = `
.msc-button::before {
  content: ""; position: absolute; inset: 0; padding: 1px; border-radius: inherit;
  -webkit-mask: linear-gradient(white 0 0) content-box, linear-gradient(white 0 0);
  -webkit-mask-composite: xor; mask-composite: exclude;
  background: linear-gradient(180deg, hsl(var(--foreground) / 0.35), hsl(var(--primary) / 0.05) 50%, hsl(var(--foreground) / 0.25));
  pointer-events: none;
}
`;

export function SatinCapsule({
  label = "Read the notes",
  meta = "04 min",
  onClick,
  className,
}: SatinCapsuleProps) {
  const prefersReducedMotion = useReducedMotion();
  return (
    <button
      type="button"
      onClick={onClick}
      className={cn(
        "msc-button group relative inline-flex items-center gap-3 rounded-full bg-[linear-gradient(180deg,hsl(var(--card)),hsl(var(--muted))_50%,hsl(var(--card)))] py-2.5 pl-6 pr-2.5 text-sm text-foreground shadow-[0_18px_34px_-16px_hsl(var(--foreground)/0.45),inset_0_1px_0_hsl(var(--background))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--primary))] focus-visible:ring-offset-2 focus-visible:ring-offset-background",
        !prefersReducedMotion &&
          "transition-shadow duration-300 hover:shadow-[0_22px_40px_-14px_hsl(var(--primary)/0.5),inset_0_1px_0_hsl(var(--background))]",
        className,
      )}
    >
      <style dangerouslySetInnerHTML={{ __html: BORDER_STYLE }} />
      <span className="font-sans tracking-tight">{label}</span>
      {meta ? (
        <span className="font-mono text-[10px] uppercase tracking-[0.18em] text-muted-foreground">
          {meta}
        </span>
      ) : null}
      <span
        aria-hidden
        className={cn(
          "grid h-7 w-7 place-items-center rounded-full bg-[hsl(var(--primary))] text-primary-foreground",
          !prefersReducedMotion && "transition-transform duration-300 group-hover:translate-x-0.5",
        )}
      >
        <svg
          viewBox="0 0 24 24"
          width="14"
          height="14"
          fill="none"
          stroke="currentColor"
          strokeWidth="1.75"
          strokeLinecap="round"
          strokeLinejoin="round"
        >
          <path d="M5 12h14" />
          <path d="m12 5 7 7-7 7" />
        </svg>
      </span>
    </button>
  );
}
```

---

# Opening Mark

> An opening title in the theme's italic serif that assembles letter by letter, then holds and loops.

Install: `npx @modus-ui/cli add opening-mark`

Each letter drifts in from a seeded offset in the theme's italic heading face, trailing soft fringes in the primary and muted tones that converge as it lands, while a square seal in `--primary` settles beside the word. The finished title holds, then replays. It reads its colours from the theme, scales to fill its parent, pauses off screen and shows the finished title when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add opening-mark
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/opening-mark.tsx`.
3. Paste the code.

## Usage

```tsx
import { OpeningMark } from "@/components/ui/opening-mark";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full">
      <OpeningMark text="Modus UI" />
    </div>
  );
}
```

## Props

| Prop              | Type      | Default                    | Description                                            |
| :---------------- | :-------- | :------------------------- | :----------------------------------------------------- |
| `text`            | `string`  | `"Modus UI"`               | Wordmark text that assembles.                          |
| `showMark`        | `boolean` | `true`                     | Show the seal mark (in `--primary`) before the text.   |
| `color`           | `string`  | `"hsl(var(--foreground))"` | Text colour, any CSS colour.                           |
| `backgroundColor` | `string`  | `"hsl(var(--background))"` | Scene background.                                      |
| `fontSize`        | `number`  | `150`                      | Font size of the wordmark on the 1280×720 composition. |
| `duration`        | `number`  | `1.7`                      | Seconds the assemble animation runs.                   |
| `holdTime`        | `number`  | `1.1`                      | Seconds the finished wordmark holds before looping.    |

## Source

`components/ui/opening-mark.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's ThreeUI Intro (MIT, © 2026 Meng To).

import { useEffect, useId, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface OpeningMarkProps {
  /** Wordmark text that assembles. */
  text?: string;
  /** Show the seal mark (in --primary) before the text. */
  showMark?: boolean;
  /** Text colour (any CSS colour). */
  color?: string;
  /** Scene background. */
  backgroundColor?: string;
  /** Font size of the wordmark on the 1280×720 composition. */
  fontSize?: number;
  /** Seconds the assemble animation runs. */
  duration?: number;
  /** Seconds the finished wordmark holds before looping. */
  holdTime?: number;
  className?: string;
}

const W = 1280;
const H = 720;
const SCENE_LENGTH = 1.72;

const clamp = (v: number, a: number, b: number) => (v < a ? a : v > b ? b : v);
const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
const seg = (t: number, a: number, b: number) => clamp((t - a) / (b - a || 1e-6), 0, 1);
const smooth = (t: number) => t * t * (3 - 2 * t);
const eOut = (t: number) => 1 - Math.pow(1 - t, 3);

function rng(s: number) {
  let a = s >>> 0;
  return () => {
    a += 0x6d2b79f5;
    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;
  };
}

export function OpeningMark({
  text = "Modus UI",
  showMark = true,
  color = "hsl(var(--foreground))",
  backgroundColor = "hsl(var(--background))",
  fontSize = 150,
  duration = 1.7,
  holdTime = 1.1,
  className,
}: OpeningMarkProps) {
  const prefersReducedMotion = useReducedMotion();
  const maskId = `iw-cut-${useId().replace(/:/g, "")}`;
  const rootRef = useRef<HTMLDivElement>(null);
  const compRef = useRef<HTMLDivElement>(null);
  const markRef = useRef<HTMLSpanElement>(null);
  const textRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const root = rootRef.current;
    const comp = compRef.current;
    const tx = textRef.current;
    if (!root || !comp || !tx) return;
    const mk = markRef.current;
    const chars = Array.from(tx.querySelectorAll<HTMLSpanElement>("[data-char]"));
    const R = rng(7719);
    const jit = chars.map(() => [R() * 2 - 1, R() * 2 - 1, R()]);

    const fit = () => {
      const { width, height } = root.getBoundingClientRect();
      comp.style.transform = `scale(${Math.min(width / W, height / H).toFixed(4)})`;
    };
    const ro = new ResizeObserver(fit);
    ro.observe(root);
    fit();

    const update = (t: number) => {
      const p = seg(t, 0, SCENE_LENGTH);
      if (mk) {
        mk.style.opacity = clamp(smooth(seg(p, 0.26, 0.5)), 0, 1).toFixed(3);
        mk.style.transform = `scale(${lerp(0.55, 1, eOut(seg(p, 0.26, 0.56))).toFixed(3)})`;
      }
      for (let i = 0; i < chars.length; i++) {
        const j = jit[i];
        const a = eOut(clamp(seg(p, 0.02, 0.5) * 1.5 - j[2] * 0.5, 0, 1));
        const c = chars[i].style;
        c.transform = `translate(${(j[0] * 62 * (1 - a)).toFixed(1)}px,${(j[1] * 34 * (1 - a)).toFixed(1)}px) scale(${lerp(1.24, 1, a).toFixed(3)})`;
        c.opacity = clamp(Math.min(1, a * 1.6), 0, 1).toFixed(3);
        const sep = (1 - a) * 11;
        c.textShadow =
          sep > 0.4
            ? `${(-sep).toFixed(1)}px 0 hsl(var(--primary) / .55),${sep.toFixed(1)}px 0 hsl(var(--muted-foreground) / .45),0 ${(sep * 0.55).toFixed(1)}px hsl(var(--border))`
            : "none";
        c.filter = sep > 0.7 ? `blur(${(sep * 0.3).toFixed(2)}px)` : "none";
      }
    };

    if (prefersReducedMotion) {
      update(duration);
      return () => ro.disconnect();
    }

    const cycle = duration + holdTime;
    let elapsed = 0;
    let last = -1;
    let raf = 0;
    let visible = true;
    const frame = (now: number) => {
      if (last >= 0) elapsed = (elapsed + (now - last) / 1000) % cycle;
      last = now;
      update(Math.min(elapsed, duration));
      raf = requestAnimationFrame(frame);
    };
    const start = () => {
      if (raf || !visible || document.hidden) return;
      last = -1;
      raf = requestAnimationFrame(frame);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(root);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);
    update(0);
    start();
    return () => {
      stop();
      io.disconnect();
      ro.disconnect();
      document.removeEventListener("visibilitychange", onVis);
    };
  }, [text, showMark, duration, holdTime, prefersReducedMotion]);

  return (
    <div
      ref={rootRef}
      role="img"
      aria-label={text}
      className={cn("relative h-full w-full overflow-hidden", className)}
      style={{ background: backgroundColor }}
    >
      <div
        ref={compRef}
        className="absolute left-1/2 top-1/2"
        style={{
          width: W,
          height: H,
          margin: `-${H / 2}px 0 0 -${W / 2}px`,
          transformOrigin: "50% 50%",
        }}
      >
        <div className="pointer-events-none absolute inset-0">
          <div
            ref={textRef}
            className="absolute inset-x-0 top-1/2 whitespace-nowrap text-center font-serif italic"
            style={{
              transform: "translateY(-50%)",
              fontWeight: 400,
              letterSpacing: "-.02em",
              lineHeight: 1,
              fontSize,
              color,
            }}
          >
            {showMark && (
              <span
                ref={markRef}
                className="inline-block text-[hsl(var(--primary))]"
                style={{ verticalAlign: "-.02em", marginRight: ".18em", opacity: 0 }}
              >
                <svg
                  viewBox="0 0 512 512"
                  aria-hidden="true"
                  className="block"
                  style={{ width: ".62em", height: ".62em" }}
                >
                  <defs>
                    <mask
                      id={maskId}
                      maskUnits="userSpaceOnUse"
                      x="0"
                      y="0"
                      width="512"
                      height="512"
                    >
                      <rect width="512" height="512" fill="black" />
                      <rect x="56" y="56" width="400" height="400" rx="72" fill="white" />
                      <rect x="200" y="200" width="112" height="112" rx="20" fill="black" />
                    </mask>
                  </defs>
                  <rect width="512" height="512" fill="currentColor" mask={`url(#${maskId})`} />
                </svg>
              </span>
            )}
            {Array.from(text).map((ch, i) => (
              <span key={i} data-char="" className="inline-block" style={{ opacity: 0 }}>
                {ch === " " ? " " : ch}
              </span>
            ))}
          </div>
        </div>
      </div>
    </div>
  );
}
```

---

# Dust Signature

> A word set in the theme's italic serif, drawn from a grid of dots and squares lit by drifting bands.

Install: `npx @modus-ui/cli add dust-signature`

A seeded grid of fine dots and squares samples a word set in the theme's italic heading face, and slanted bands drift across the letters, shading each grain from the muted tone through `--primary` to the foreground. It sits on the page ground in light and dark mode, re-reads the palette when it changes, fills its parent, pauses off screen and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add dust-signature
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/dust-signature.tsx`.
3. Paste the code.

## Usage

```tsx
import { DustSignature } from "@/components/ui/dust-signature";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full">
      <DustSignature text="Modus" />
    </div>
  );
}
```

## Props

| Prop              | Type                         | Default                                   | Description                                 |
| :---------------- | :--------------------------- | :---------------------------------------- | :------------------------------------------ |
| `text`            | `string`                     | `"Modus"`                                 | Text the particle field spells out.         |
| `colors`          | `[number, number, number][]` | Theme ramp (muted → primary → foreground) | Particle palette, blended across particles. |
| `backgroundColor` | `string`                     | `"hsl(var(--background))"`                | Scene background.                           |
| `speed`           | `number`                     | `2`                                       | Animation speed multiplier.                 |

## Source

`components/ui/dust-signature.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Particle Wordmark (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface DustSignatureProps {
  /** Text the particle field spells out. */
  text?: string;
  /** Particle palette as RGB triplets, blended across particles. Defaults to the theme's muted → primary → foreground ramp. */
  colors?: [number, number, number][];
  /** Scene background (any CSS colour). */
  backgroundColor?: string;
  /** Animation speed multiplier. */
  speed?: number;
  className?: string;
}

const FORMATS = ["dot", "dot", "square"];
const SIZE_SMALL = [1.4, 2.8];
const SIZE_BIG = [3, 4.2];
const BIG_CHANCE = 0.07;
const GAP = 5;
const SEED = 1337;
const GAMMA = 0.8;
const DUR = 8;
const TAU = Math.PI * 2;

type Particle = {
  cx: number;
  cy: number;
  nx: number;
  ny: number;
  format: string;
  size: number;
  offset: number;
  mask: number;
};

function noise(x: number, y: number, t: number) {
  const a = x + 0.7 * Math.sin(1.2 * y + t);
  const r = y + 0.7 * Math.cos(1.1 * x - t);
  return (
    (Math.sin(1.3 * a + 0.6 * t) +
      Math.cos(1.5 * r - 0.5 * t) +
      Math.sin((a + r) * 0.9 + 0.3 * t)) /
    3
  );
}

function snowfall(
  p: Particle,
  t: number,
  n: {
    fall: number;
    freq: number;
    trail: number;
    sway?: number;
    wind?: number;
    swirl?: number;
    axis?: string;
  },
) {
  const swirl = n.swirl ? n.swirl * noise(3 * p.nx, 3 * p.ny, 0.5 * t) : 0;
  const sway = (n.sway || 0) * Math.sin(0.8 * t + p.offset * TAU + 4 * p.ny) + swirl;
  const i = n.axis === "x" ? p.nx : p.ny;
  const l = n.axis === "x" ? p.ny : p.nx;
  const o = i * n.freq - t * n.fall + p.offset * n.freq + sway + (n.wind || 0) * l;
  const s = o - Math.floor(o);
  return s < n.trail ? 1 - s / n.trail : 0;
}

function squall(p: Particle, t: number) {
  const band = 0.35 + 0.65 * Math.pow(0.5 + 0.5 * Math.sin(3 * p.nx - 0.5 * t), 2);
  const flake = snowfall(p, t, { fall: 0.26, freq: 5, trail: 0.4, sway: 0.14, wind: 0.8 });
  return { a: 0.14 + 0.86 * band * Math.pow(flake, 1.8), p: 0.7 * p.offset };
}

function lcg(seed: number) {
  let e = seed >>> 0;
  return () => {
    e = (1664525 * e + 0x3c6ef35f) >>> 0;
    return e / 0xffffffff;
  };
}

/* resolves any CSS colour (including hsl(var(--token))) to an RGB triplet */
function toRgb(el: HTMLElement, color: string): [number, number, number] {
  const probe = document.createElement("span");
  probe.style.color = color;
  probe.style.display = "none";
  el.appendChild(probe);
  const m = getComputedStyle(probe).color.match(/[\d.]+/g) ?? ["0", "0", "0"];
  probe.remove();
  return [Number(m[0]), Number(m[1]), Number(m[2])];
}

export function DustSignature({
  text = "Modus",
  colors,
  backgroundColor = "hsl(var(--background))",
  speed = 2,
  className,
}: DustSignatureProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const colorKey = JSON.stringify(colors ?? null);
  /* re-resolve the theme tokens whenever the mode or palette on <html> changes */
  const [theme, setTheme] = useState(0);
  useEffect(() => {
    const mo = new MutationObserver(() => setTheme((t) => t + 1));
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    const ctx = canvas?.getContext("2d");
    if (!host || !canvas || !ctx) return;
    const PALETTE: [number, number, number][] = JSON.parse(colorKey) ?? [
      toRgb(host, "hsl(var(--muted-foreground))"),
      toRgb(host, "hsl(var(--primary))"),
      toRgb(host, "hsl(var(--foreground))"),
    ];
    const face = getComputedStyle(host).fontFamily || "serif";
    const mixPalette = (p: number) => {
      const e = Math.max(0, Math.min(1, p)) * (PALETTE.length - 1);
      const r = Math.floor(e);
      const s = e - r;
      const a = PALETTE[r];
      const b = PALETTE[Math.min(PALETTE.length - 1, r + 1)];
      return [a[0] + (b[0] - a[0]) * s, a[1] + (b[1] - a[1]) * s, a[2] + (b[2] - a[2]) * s];
    };

    let particles: Particle[] = [];
    let tNow = 0;
    let alive = true;

    const makeMask = (w: number, h: number) => {
      const off = document.createElement("canvas");
      off.width = w;
      off.height = h;
      const g = off.getContext("2d");
      if (!g) return null;
      /* the mark is set in the theme's heading face, italic, sized to fill the strip */
      let size = h * 0.92;
      g.font = `italic 400 ${size}px ${face}`;
      const fit = (w * 0.94) / Math.max(1, g.measureText(text).width);
      if (fit < 1) size *= fit;
      g.font = `italic 400 ${size}px ${face}`;
      g.fillStyle = "white";
      g.textAlign = "center";
      g.textBaseline = "middle";
      g.fillText(text, w / 2, h * 0.54);
      const data = g.getImageData(0, 0, w, h).data;
      return (x: number, y: number) => {
        const ix = Math.min(w - 1, Math.max(0, Math.round(x)));
        const iy = Math.min(h - 1, Math.max(0, Math.round(y)));
        const i = (iy * w + ix) * 4;
        const lum = (0.299 * data[i] + 0.587 * data[i + 1] + 0.114 * data[i + 2]) / 255;
        return Math.pow(lum * (data[i + 3] / 255), GAMMA);
      };
    };

    const rebuild = () => {
      const w = host.clientWidth;
      const h = host.clientHeight;
      if (!w || !h) return;
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      canvas.width = Math.max(1, Math.floor(w * dpr));
      canvas.height = Math.max(1, Math.floor(h * dpr));
      ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
      const sample = makeMask(w, h);
      const rand = lcg(SEED);
      const cols = Math.ceil(w / GAP);
      const rows = Math.ceil(h / GAP);
      const ox = (w - (cols - 1) * GAP) / 2;
      const oy = (h - (rows - 1) * GAP) / 2;
      particles = [];
      for (let y = 0; y < rows; y++) {
        for (let x = 0; x < cols; x++) {
          const format = FORMATS[Math.floor(rand() * FORMATS.length)];
          const range = rand() < BIG_CHANCE ? SIZE_BIG : SIZE_SMALL;
          const size = range[0] + rand() * (range[1] - range[0]);
          const px = ox + x * GAP;
          const py = oy + y * GAP;
          rand(); // phase
          rand(); // speed
          particles.push({
            cx: px,
            cy: py,
            nx: cols > 1 ? x / (cols - 1) : 0.5,
            ny: rows > 1 ? y / (rows - 1) : 0.5,
            format,
            size,
            offset: rand(),
            mask: sample ? sample(px, py) : 1,
          });
        }
      }
    };

    const render = (t: number) => {
      ctx.clearRect(0, 0, canvas.width, canvas.height);
      for (const p of particles) {
        const field = squall(p, t);
        const rgb = mixPalette(field.p);
        let alpha = Math.max(0, Math.min(1, field.a));
        if (p.mask < 1) alpha = p.mask * (0.3 + 0.7 * alpha);
        if (alpha <= 0.005) continue;
        ctx.fillStyle = `rgba(${rgb[0]},${rgb[1]},${rgb[2]},${alpha})`;
        const r = p.size / 2;
        if (p.format === "square") ctx.fillRect(p.cx - r, p.cy - r, p.size, p.size);
        else {
          ctx.beginPath();
          ctx.arc(p.cx, p.cy, r, 0, TAU);
          ctx.fill();
        }
      }
    };
    const apply = () => render(tNow * speed);

    document.fonts?.ready.then(() => {
      if (!alive) return;
      rebuild();
      apply();
    });

    rebuild();
    apply();

    let lastW = host.clientWidth;
    let lastH = host.clientHeight;
    const ro = new ResizeObserver(() => {
      if (host.clientWidth !== lastW || host.clientHeight !== lastH) {
        lastW = host.clientWidth;
        lastH = host.clientHeight;
        rebuild();
        apply();
      }
    });
    ro.observe(host);

    let raf = 0;
    let last = -1;
    let visible = true;
    const tick = (now: number) => {
      if (last >= 0) tNow = (tNow + (now - last) / 1000) % DUR;
      last = now;
      apply();
      raf = requestAnimationFrame(tick);
    };
    const start = () => {
      if (prefersReducedMotion || raf || !visible || document.hidden) return;
      last = -1;
      raf = requestAnimationFrame(tick);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(
      ([entry]) => {
        visible = entry.isIntersecting;
        if (visible) start();
        else stop();
      },
      { rootMargin: "120px" },
    );
    io.observe(canvas);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);
    start();

    return () => {
      alive = false;
      stop();
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVis);
    };
  }, [text, colorKey, theme, speed, prefersReducedMotion]);

  return (
    <div
      className={cn(
        "relative flex h-full w-full items-center justify-center overflow-hidden",
        className,
      )}
      style={{ background: backgroundColor }}
    >
      <div
        ref={hostRef}
        role="img"
        aria-label={text}
        className="relative z-[1] m-auto select-none overflow-hidden font-serif"
        style={{ width: "min(calc(100% - 48px), 1180px)", aspectRatio: "16 / 5" }}
      >
        <canvas ref={canvasRef} className="block h-full w-full" />
      </div>
    </div>
  );
}
```

---

# Echo Letters

> A serif wordmark between two offset equaliser discs, one pulsing in your primary colour and one cut from a plate.

Install: `npx @modus-ui/cli add echo-letters`

Two offset discs of rounded equaliser bars sit on a diagonal: the lower one pulses in the theme primary inside a dashed orbit, the upper one is a foreground plate with bars cut through it. An italic serif wordmark and a row of small glyphs float on frosted pills across the middle, tracking in from wide letter spacing each loop. Colours come from theme tokens unless you pass them, so it follows light and dark mode and the palette picker. It scales a 1080×1350 stage to fit its parent, pauses off screen and holds a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add echo-letters
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/echo-letters.tsx`.
3. Paste the code.

## Usage

```tsx
import { EchoLetters } from "@/components/ui/echo-letters";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full">
      <EchoLetters text="Modus UI" />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default      | Description                                                   |
| :---------------- | :------- | :----------- | :------------------------------------------------------------ |
| `text`            | `string` | `"Modus UI"` | Wordmark text.                                                |
| `accentColor`     | `string` | None         | Equaliser bar colour; defaults to the theme primary.          |
| `color`           | `string` | None         | Wordmark, glyph and plate colour; defaults to the foreground. |
| `backgroundColor` | `string` | None         | Scene background; defaults to the theme background.           |
| `duration`        | `number` | `4.7`        | Loop length in seconds.                                       |
| `className`       | `string` | None         | Extra classes for the root.                                   |

## Source

`components/ui/echo-letters.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Audio Wordmark (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface EchoLettersProps {
  /** Wordmark text. */
  text?: string;
  /** Equaliser bar colour; defaults to the theme primary. */
  accentColor?: string;
  /** Wordmark, glyph and plate colour; defaults to the theme foreground. */
  color?: string;
  /** Scene background; defaults to the theme background. */
  backgroundColor?: string;
  /** Loop length in seconds. */
  duration?: number;
  className?: string;
}

const W = 1080;
const H = 1350;

function sat(x: number) {
  return x < 0 ? 0 : x > 1 ? 1 : x;
}
function lerp(a: number, b: number, t: number) {
  return a + (b - a) * t;
}
function easeOut(t: number) {
  t = sat(t);
  return 1 - Math.pow(1 - t, 3);
}

/** Reads a bare-HSL theme token (e.g. `--primary`) as a CSS colour. */
function token(name: string) {
  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  return v ? `hsl(${v})` : "currentColor";
}

const GRAIN =
  "url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='.9' numOctaves='2' stitchTiles='stitch'/></filter><rect width='100%' height='100%' filter='url(%23n)'/></svg>\")";

function Icon({ kind, background }: { kind: "e" | "p" | "g" | "one"; background: string }) {
  return (
    <svg width="22" height="22" viewBox="0 0 24 24" className="block" aria-hidden="true">
      {kind === "e" && (
        <path
          d="M3 3.2h18.5a1.6 1.6 0 0 1 0 3.2H6.4v4.2h13.2a1.6 1.6 0 0 1 0 3.2H6.4v4.2h15.1a1.6 1.6 0 0 1 0 3.2H3.2A1.6 1.6 0 0 1 1.6 19V4.8A1.6 1.6 0 0 1 3.2 3.2Z"
          fill="currentColor"
        />
      )}
      {kind === "p" && (
        <>
          <circle cx="12" cy="12" r="10.2" fill="none" stroke="currentColor" strokeWidth="1.6" />
          <text
            x="12"
            y="16.2"
            textAnchor="middle"
            fontSize="12"
            fontWeight="700"
            fontFamily="Helvetica Neue, Helvetica, Arial, sans-serif"
            fill="currentColor"
          >
            P
          </text>
        </>
      )}
      {kind === "g" && (
        <>
          <circle cx="12" cy="12" r="10.2" fill="none" stroke="currentColor" strokeWidth="1.5" />
          <ellipse
            cx="12"
            cy="12"
            rx="4.2"
            ry="10.2"
            fill="none"
            stroke="currentColor"
            strokeWidth="1.3"
          />
          <path
            d="M2 12h20M4.2 7.2h15.6M4.2 16.8h15.6"
            fill="none"
            stroke="currentColor"
            strokeWidth="1.2"
          />
        </>
      )}
      {kind === "one" && (
        <>
          <circle cx="12" cy="12" r="10.4" fill="currentColor" />
          <text
            x="12"
            y="16.4"
            textAnchor="middle"
            fontSize="12"
            fontWeight="800"
            fontFamily="Helvetica Neue, Helvetica, Arial, sans-serif"
            fill={background}
          >
            1
          </text>
        </>
      )}
    </svg>
  );
}

export function EchoLetters({
  text = "Modus UI",
  accentColor,
  color,
  backgroundColor,
  duration = 4.7,
  className,
}: EchoLettersProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const stageRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const sceneRef = useRef<HTMLElement>(null);
  const wordRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const root = rootRef.current;
    const stage = stageRef.current;
    const canvas = canvasRef.current;
    const scene = sceneRef.current;
    const sr1 = wordRef.current;
    const ctx = canvas?.getContext("2d");
    if (!root || !stage || !canvas || !scene || !sr1 || !ctx) return;

    let accent = "";
    let plate = "";
    const readColors = () => {
      accent = accentColor ?? token("--primary");
      plate = color ?? token("--foreground");
    };
    readColors();

    const DUR = duration;
    const HOLD = 4.7;
    const FADE = 0.3;

    const fit = () => {
      const { width, height } = root.getBoundingClientRect();
      const s = Math.min(width / W, height / H);
      stage.style.transform = `translate(-50%,-50%) scale(${s})`;
    };
    const ro = new ResizeObserver(fit);
    ro.observe(root);
    fit();

    const roundRect = (x: number, y: number, w: number, h: number, r: number) => {
      r = Math.min(r, w / 2, h / 2);
      ctx.beginPath();
      ctx.moveTo(x + r, y);
      ctx.arcTo(x + w, y, x + w, y + h, r);
      ctx.arcTo(x + w, y + h, x, y + h, r);
      ctx.arcTo(x, y + h, x, y, r);
      ctx.arcTo(x, y, x + w, y, r);
      ctx.closePath();
    };

    const drawBars = (
      cx: number,
      cy: number,
      r: number,
      t: number,
      inverse: boolean,
      fill: string,
    ) => {
      const n = inverse ? 16 : 22;
      const pitch = (r * 2) / n;
      ctx.save();
      ctx.beginPath();
      ctx.arc(cx, cy, r, 0, Math.PI * 2);
      ctx.clip();
      ctx.fillStyle = fill;
      if (inverse) {
        ctx.fill();
        ctx.globalCompositeOperation = "destination-out";
        ctx.fillStyle = "black";
      }
      for (let i = 0; i < n; i++) {
        const x = -r + (i + 0.5) * pitch;
        const maxH = Math.sqrt(Math.max(0, r * r - x * x)) * 2;
        if (maxH < 6) continue;
        const pulse = 0.78 + 0.22 * Math.sin(t * 6.4 + i * 0.62) * Math.sin(t * 2.4 + i * 0.17);
        const bw = (inverse ? pitch * 0.38 : pitch * 0.62) * (inverse ? 1 : pulse);
        roundRect(cx + x - bw / 2, cy - maxH / 2, Math.max(2, bw), maxH, Math.min(bw, maxH) * 0.45);
        ctx.fill();
      }
      ctx.restore();
      ctx.globalCompositeOperation = "source-over";
    };

    const drawViz = (t: number) => {
      ctx.clearRect(0, 0, W, H);
      // Two discs on a diagonal: a plate with bars cut through it, then live primary bars.
      drawBars(540 + 120, 675 - 150, 190, t + 1.7, true, plate);
      drawBars(540 - 120, 675 + 150, 190, t, false, accent);
      ctx.strokeStyle = plate;
      ctx.globalAlpha = 0.35;
      ctx.lineWidth = 1.5;
      ctx.setLineDash([4, 8]);
      ctx.beginPath();
      ctx.arc(540 - 120, 675 + 150, 222, 0, Math.PI * 2);
      ctx.stroke();
      ctx.setLineDash([]);
      ctx.globalAlpha = 1;
    };

    const apply = (t: number) => {
      t = ((t % DUR) + DUR) % DUR;
      const slot = HOLD + FADE;
      const local = t % slot;
      const fadeOut = sat((local - HOLD) / FADE);
      const fadeIn = local < FADE ? sat(local / FADE) : 1;
      scene.style.opacity = String(fadeIn * (1 - fadeOut));
      drawViz(t);
      const p = easeOut(sat(local / 0.7));
      sr1.style.opacity = String(p);
      sr1.style.letterSpacing = lerp(0.18, -0.045, p) + "em";
    };

    let tNow = 0;
    const themeObserver = new MutationObserver(() => {
      readColors();
      apply(prefersReducedMotion ? 16.2 : tNow);
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette"],
    });

    if (prefersReducedMotion) {
      apply(16.2);
      return () => {
        ro.disconnect();
        themeObserver.disconnect();
      };
    }

    let last = -1;
    let raf = 0;
    let visible = true;
    const frame = (now: number) => {
      if (last >= 0) tNow = (tNow + (now - last) / 1000) % DUR;
      last = now;
      apply(tNow);
      raf = requestAnimationFrame(frame);
    };
    const start = () => {
      if (raf || !visible || document.hidden) return;
      last = -1;
      raf = requestAnimationFrame(frame);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(root);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);
    apply(0);
    start();
    return () => {
      stop();
      io.disconnect();
      ro.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVis);
    };
  }, [prefersReducedMotion, duration, accentColor, color]);

  return (
    <div
      ref={rootRef}
      className={cn("relative h-full w-full overflow-hidden bg-background", className)}
      style={backgroundColor ? { background: backgroundColor } : undefined}
    >
      <div
        ref={stageRef}
        className="absolute left-1/2 top-1/2 overflow-hidden"
        style={{
          width: W,
          height: H,
          transform: "translate(-50%,-50%)",
          transformOrigin: "center",
          color: color ?? "hsl(var(--foreground))",
          fontFamily: "var(--font-heading), ui-serif, Georgia, serif",
          WebkitFontSmoothing: "antialiased",
        }}
      >
        <section ref={sceneRef} className="absolute inset-0" style={{ opacity: 0 }}>
          <canvas ref={canvasRef} width={W} height={H} className="absolute inset-0" />
          <div className="absolute inset-0 z-[2] flex items-center justify-center">
            <div
              ref={wordRef}
              className="flex items-center whitespace-nowrap"
              style={{
                fontWeight: 500,
                fontStyle: "italic",
                fontSize: 68,
                letterSpacing: "-.045em",
                lineHeight: 1,
                gap: 14,
              }}
            >
              <span
                className="flex items-baseline rounded-full bg-background/85 px-8 py-4 backdrop-blur-md"
                style={{ gap: 12 }}
              >
                {text}
              </span>
              <span
                className="ml-1 flex items-center rounded-full bg-background/85 px-4 py-4 backdrop-blur-md"
                style={{ gap: 10 }}
              >
                <Icon kind="e" background="hsl(var(--background))" />
                <Icon kind="p" background="hsl(var(--background))" />
                <Icon kind="g" background="hsl(var(--background))" />
                <Icon kind="one" background="hsl(var(--background))" />
              </span>
            </div>
          </div>
        </section>
        <div
          className="pointer-events-none absolute inset-0 z-[8]"
          style={{ opacity: 0.06, mixBlendMode: "overlay", backgroundImage: GRAIN }}
        />
      </div>
    </div>
  );
}
```

---

# Cast Reel

> A 3D reel of team cards, as a tonal card wave or a contact-sheet filmstrip, coloured by your theme.

Install: `npx @modus-ui/cli add cast-reel`

Team cards fan out in 3D around a focused card on a dotted ground. By default they form a wave of cards tinted in a tonal ramp of the theme primary, with serif names, mono roles and a pill that fills with the primary colour on the focused card; the `filmstrip` variant lays them out as a ruled contact sheet whose portraits warm from greyscale as they come into focus. Move the pointer to scrub, scroll or use the arrow keys to step, and click a card to bring it forward; after a few idle seconds the deck drifts on its own. The wave can also flip between horizontal and vertical (double-click or Space). Everything follows light and dark mode and the palette picker. It pauses off screen and snaps instead of easing when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add cast-reel
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/cast-reel.tsx`.
3. Paste the code.

## Usage

```tsx
import { CastReel } from "@/components/ui/cast-reel";

export default function Example() {
  return (
    <div className="relative h-[520px] w-full">
      <CastReel variant="wave" />
    </div>
  );
}
```

## Props

| Prop          | Type                    | Default                                      | Description                                                |
| :------------ | :---------------------- | :------------------------------------------- | :--------------------------------------------------------- |
| `variant`     | `"filmstrip" \| "wave"` | `"wave"`                                     | A tonal card wave or a contact-sheet filmstrip.            |
| `items`       | `CastReelItem[]`        | nine sample profiles with Unsplash portraits | Cards to show (`name`, `role`, `image`, optional `color`). |
| `speed`       | `number`                | `1`                                          | Animation speed multiplier (0 to 2.5).                     |
| `scale`       | `number`                | `1`                                          | Deck scale (0.7 to 1.3).                                   |
| `opacity`     | `number`                | `1`                                          | Opacity of the scene (0.05 to 1).                          |
| `hue`         | `number`                | `0`                                          | Hue rotation in degrees.                                   |
| `saturation`  | `number`                | `1`                                          | Saturation multiplier.                                     |
| `brightness`  | `number`                | `1`                                          | Brightness multiplier.                                     |
| `followLabel` | `string`                | `"Say hello"`                                | Label on the wave variant's pill.                          |
| `className`   | `string`                | none                                         | Extra classes for the root.                                |

## Source

`components/ui/cast-reel.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Character Carousel (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface CastReelItem {
  name: string;
  role: string;
  image: string;
  /** Card colour (wave variant); defaults to a primary-tinted card. */
  color?: string;
}

export interface CastReelProps {
  /** Layout: a contact-sheet filmstrip or a card wave. */
  variant?: "filmstrip" | "wave";
  /** Cards to show. */
  items?: CastReelItem[];
  /** Animation speed multiplier (0 to 2.5). */
  speed?: number;
  /** Deck scale (0.7 to 1.3). */
  scale?: number;
  /** Opacity of the scene (0.05 to 1). */
  opacity?: number;
  /** Hue rotation in degrees. */
  hue?: number;
  /** Saturation multiplier. */
  saturation?: number;
  /** Brightness multiplier. */
  brightness?: number;
  /** Label on the wave variant's pill button. */
  followLabel?: string;
  className?: string;
}

const img = (id: string) =>
  `https://images.unsplash.com/${id}?w=480&h=720&fit=crop&crop=faces&q=80`;
const SOPHIE = img("photo-1494790108377-be9c29b29330");
const MARCUS = img("photo-1500648767791-00dcc994a43e");
const JULIAN = img("photo-1507003211169-0a1dd7228f2d");
const ELENA = img("photo-1438761681033-6461ffad8d80");

const DEFAULT_ITEMS: CastReelItem[] = [
  { name: "Ines Varga", role: "Type Designer", image: ELENA },
  { name: "Theo Okafor", role: "Motion Lead", image: MARCUS },
  { name: "Mara Lindqvist", role: "Design Engineer", image: SOPHIE },
  { name: "Ren Aoki", role: "Systems Architect", image: JULIAN },
  { name: "Ines Varga", role: "Type Designer", image: ELENA },
  { name: "Theo Okafor", role: "Motion Lead", image: MARCUS },
  { name: "Mara Lindqvist", role: "Design Engineer", image: SOPHIE },
  { name: "Ren Aoki", role: "Systems Architect", image: JULIAN },
  { name: "Theo Okafor", role: "Motion Lead", image: MARCUS },
];

/** Primary tint strength per card, so a default wave reads as a tonal ramp of the palette. */
const TINTS = [6, 16, 28, 12, 22];

const clamp = (v: number, a: number, b: number) => Math.min(b, Math.max(a, v));

const CSS = `
.cc-root{container-type:size;user-select:none;-webkit-tap-highlight-color:transparent}
.cc-root *{box-sizing:border-box}
.cc-root button{font:inherit}
.cc-stage{position:relative;width:100%;height:100%;overflow:hidden;isolation:isolate;touch-action:none;outline:none;color:hsl(var(--foreground))}
.cc-deck{position:absolute;inset:0;z-index:2;transform-style:preserve-3d;transform-origin:50% 50%}
.cc-card{--focus:0;position:absolute;top:50%;left:50%;appearance:none;outline:none;transform-style:preserve-3d;will-change:transform,opacity,filter;cursor:pointer}
.cc-mono{font-family:var(--font-mono,ui-monospace),ui-monospace,monospace;text-transform:uppercase}

.cc-film{font-family:var(--font-body),ui-sans-serif,system-ui,sans-serif;--pointer-x:50%;perspective:1450px;cursor:ew-resize;
  background:linear-gradient(90deg,hsl(var(--border)/.7) 1px,transparent 1px) 50% 0/12.5% 100%,radial-gradient(circle at var(--pointer-x) 50%,hsl(var(--primary)/.1),transparent 38%),hsl(var(--background))}
.cc-film::after{content:"";position:absolute;inset:0;z-index:4;pointer-events:none;background:linear-gradient(90deg,hsl(var(--background)),transparent 16%,transparent 84%,hsl(var(--background)))}
.cc-film .cc-card{width:clamp(150px,16cqw,228px);aspect-ratio:.72;padding:8px;overflow:hidden;border:1px solid hsl(var(--border));border-radius:calc(var(--radius,8px) * .6);background:hsl(var(--card));
  box-shadow:0 calc(8px + var(--focus)*22px) calc(16px + var(--focus)*34px) hsl(var(--foreground)/calc(.06 + var(--focus)*.12))}
.cc-film .cc-card:focus-visible{outline:2px solid hsl(var(--primary));outline-offset:3px}
.cc-film .portrait{position:absolute;inset:8px 8px 24%;overflow:hidden;border-radius:calc(var(--radius,8px) * .4);background:hsl(var(--muted))}
.cc-film .portrait img{display:block;width:100%;height:100%;object-fit:cover;transform:scale(calc(1.04 + (1 - var(--focus))*.06));filter:grayscale(calc(1 - var(--focus))) contrast(1.03)}
.cc-film .footer{position:absolute;right:8px;bottom:8px;left:8px;height:calc(24% - 8px);display:flex;flex-direction:column;justify-content:center;gap:clamp(2px,.3cqw,5px);padding:0 2px;text-align:left}
.cc-film .index{position:absolute;top:0;right:2px;color:hsl(var(--primary));font-size:clamp(7px,.62cqw,10px);letter-spacing:.14em}
.cc-film .name,.cc-film .role{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
.cc-film .name{font-family:var(--font-heading),ui-serif,Georgia,serif;font-size:clamp(11px,1.1cqw,17px);font-weight:500;letter-spacing:-.01em;line-height:1.1;color:hsl(var(--card-foreground))}
.cc-film .role{color:hsl(var(--muted-foreground));font-size:clamp(6px,.55cqw,9px);letter-spacing:.16em;line-height:1}
@container (max-width:650px){
  .cc-film{cursor:ns-resize}
  .cc-film .cc-card{width:clamp(142px,47cqw,180px)}
}

.cc-wave{font-family:var(--font-body),ui-sans-serif,system-ui,sans-serif;--pointer-x:50%;--pointer-y:50%;perspective:1100px;cursor:crosshair;
  background:radial-gradient(circle at var(--pointer-x) var(--pointer-y),hsl(var(--primary)/.08),transparent 26rem),radial-gradient(hsl(var(--border)) 1px,transparent 1.2px) 0 0/22px 22px,hsl(var(--background))}
.cc-wave .cc-card{width:clamp(122px,10.45cqw,164px);aspect-ratio:.69;padding:clamp(8px,.78cqw,12px);border:1px solid hsl(var(--border));border-radius:clamp(10px,1.05cqw,16px);color:hsl(var(--foreground));
  background:var(--card-color);
  box-shadow:0 calc(6px + var(--focus)*18px) calc(12px + var(--focus)*36px) hsl(var(--foreground)/calc(.08 + var(--focus)*.16))}
.cc-wave .cc-card:focus-visible{outline:2px solid hsl(var(--primary));outline-offset:3px}
.cc-wave .portrait{position:relative;width:100%;aspect-ratio:1;overflow:hidden;border-radius:clamp(7px,.75cqw,11px);background:hsl(var(--muted));transform:translateZ(7px)}
.cc-wave .portrait img{display:block;width:100%;height:100%;object-fit:cover;filter:grayscale(.35) contrast(1.02)}
.cc-wave .identity{display:grid;place-items:center;gap:clamp(2px,.25cqw,4px);margin-top:clamp(7px,.72cqw,11px);text-align:center;transform:translateZ(8px)}
.cc-wave .name{max-width:100%;overflow:hidden;font-family:var(--font-heading),ui-serif,Georgia,serif;font-size:clamp(9px,.8cqw,12px);font-weight:500;line-height:1.15;text-overflow:ellipsis;white-space:nowrap}
.cc-wave .role{max-width:100%;overflow:hidden;color:hsl(var(--muted-foreground));font-size:clamp(4px,.36cqw,6px);letter-spacing:.14em;line-height:1.15;text-overflow:ellipsis;white-space:nowrap}
.cc-wave .follow{margin-top:clamp(3px,.35cqw,6px);padding:clamp(3px,.28cqw,4px) clamp(9px,.85cqw,13px);border:1px solid hsl(var(--border));border-radius:999px;color:hsl(var(--foreground));background:hsl(var(--background));font-size:clamp(3px,.29cqw,5px);line-height:1;letter-spacing:.14em}
.cc-wave .cc-card[aria-current="true"] .follow{border-color:hsl(var(--primary));color:hsl(var(--primary-foreground));background:hsl(var(--primary))}
@container (max-width:680px){.cc-wave .cc-card{width:clamp(112px,31cqw,138px)}}
`;

export function CastReel({
  variant = "wave",
  items = DEFAULT_ITEMS,
  speed = 1,
  scale = 1,
  opacity = 1,
  hue = 0,
  saturation = 1,
  brightness = 1,
  followLabel = "Say hello",
  className,
}: CastReelProps) {
  const prefersReducedMotion = useReducedMotion();
  const stageRef = useRef<HTMLDivElement>(null);
  const deckRef = useRef<HTMLDivElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 2.5);
  const isFilm = variant !== "wave";

  useEffect(() => {
    const stage = stageRef.current;
    const deck = deckRef.current;
    if (!stage || !deck) return;
    const cards = Array.from(deck.querySelectorAll<HTMLButtonElement>(".cc-card"));
    const count = cards.length;
    if (!count) return;
    const reducedMotion = !!prefersReducedMotion;

    // virtual clock, scaled by `speed`
    let clock = 0;
    const now = () => clock;
    const size = () => ({ w: stage.clientWidth, h: stage.clientHeight });

    const wrappedDelta = (index: number, phase: number) => {
      let delta = index - phase;
      while (delta > count / 2) delta -= count;
      while (delta < -count / 2) delta += count;
      return delta;
    };

    const film = {
      phase: 3,
      target: 3,
      base: 3,
      pointerX: 0,
      pointerY: 0,
      active: false,
      lastInput: 0,
    };
    const narrowWave = () => size().w < 680;
    const wave = {
      phase: 2,
      targetPhase: 2,
      basePhase: 2,
      orientation: narrowWave() ? 1 : 0,
      targetOrientation: narrowWave() ? 1 : 0,
      pointerX: 0,
      pointerY: 0,
      tiltX: 0,
      tiltY: 0,
      active: false,
      manualOrientation: false,
      lastInput: 0,
    };

    const nearestIndex = () => {
      const phase = isFilm ? film.phase : wave.phase;
      return ((Math.round(phase) % count) + count) % count;
    };
    const step = (dir: number) => {
      if (isFilm) {
        film.base += dir;
        film.target = film.base;
        film.active = false;
        film.lastInput = now();
      } else {
        wave.basePhase += dir;
        wave.targetPhase = wave.basePhase;
        wave.active = false;
        wave.lastInput = now();
      }
    };
    const moveTo = (index: number) => {
      let delta = index - nearestIndex();
      if (delta > count / 2) delta -= count;
      if (delta < -count / 2) delta += count;
      if (isFilm) {
        film.base += delta;
        film.target = film.base;
        film.active = false;
        film.lastInput = now();
      } else {
        wave.basePhase += delta;
        wave.targetPhase = wave.basePhase;
        wave.lastInput = now();
      }
    };
    const toggleOrientation = () => {
      wave.manualOrientation = true;
      wave.targetOrientation = wave.targetOrientation > 0.5 ? 0 : 1;
      wave.targetPhase = wave.basePhase;
      wave.lastInput = now();
    };

    const cardHandlers = cards.map((card, index) => {
      const h = () => moveTo(index);
      card.addEventListener("click", h);
      card.addEventListener("focus", h);
      return h;
    });

    const onPointer = (event: PointerEvent) => {
      const rect = stage.getBoundingClientRect();
      const nx = Math.max(-1, Math.min(1, ((event.clientX - rect.left) / rect.width - 0.5) * 2));
      const ny = Math.max(-1, Math.min(1, ((event.clientY - rect.top) / rect.height - 0.5) * 2));
      if (isFilm) {
        film.pointerX = nx;
        film.pointerY = ny;
        film.active = true;
        film.target = film.base + (rect.width < 650 ? ny * 2.2 : nx * 3.1);
        film.lastInput = now();
        stage.style.setProperty("--pointer-x", `${(nx + 1) * 50}%`);
      } else {
        wave.pointerX = nx;
        wave.pointerY = ny;
        wave.tiltX = nx;
        wave.tiltY = ny;
        wave.active = true;
        wave.lastInput = now();
        const axis = wave.targetOrientation > 0.5 ? ny : nx;
        wave.targetPhase = wave.basePhase + axis * (rect.width < 680 ? 1.55 : 2.45);
        stage.style.setProperty("--pointer-x", `${((nx + 1) / 2) * 100}%`);
        stage.style.setProperty("--pointer-y", `${((ny + 1) / 2) * 100}%`);
      }
    };
    const onLeave = () => {
      if (isFilm) {
        film.active = false;
        film.pointerX = 0;
        film.pointerY = 0;
        film.target = film.base;
      } else {
        wave.active = false;
        wave.targetPhase = wave.basePhase;
        wave.pointerX = 0;
        wave.pointerY = 0;
        stage.style.setProperty("--pointer-y", "50%");
      }
      stage.style.setProperty("--pointer-x", "50%");
    };
    const onWheel = (event: WheelEvent) => {
      event.preventDefault();
      const direction = Math.sign(
        Math.abs(event.deltaY) > Math.abs(event.deltaX) ? event.deltaY : event.deltaX,
      );
      if (direction) step(direction);
    };
    const onKey = (event: KeyboardEvent) => {
      const forward = event.key === "ArrowRight" || event.key === "ArrowDown";
      const backward = event.key === "ArrowLeft" || event.key === "ArrowUp";
      if (!isFilm && event.key === " ") {
        event.preventDefault();
        toggleOrientation();
        return;
      }
      if (!forward && !backward) return;
      event.preventDefault();
      step(forward ? 1 : -1);
    };
    const onDbl = () => {
      if (!isFilm) toggleOrientation();
    };
    const ro = new ResizeObserver(() => {
      if (!isFilm && !wave.manualOrientation) wave.targetOrientation = narrowWave() ? 1 : 0;
    });
    ro.observe(stage);

    stage.addEventListener("pointermove", onPointer);
    stage.addEventListener("pointerdown", onPointer);
    stage.addEventListener("pointerleave", onLeave);
    stage.addEventListener("wheel", onWheel, { passive: false });
    stage.addEventListener("keydown", onKey);
    stage.addEventListener("dblclick", onDbl);

    const renderFilm = (time: number, deltaTime: number) => {
      const ease = reducedMotion ? 1 : 1 - Math.pow(0.001, deltaTime / 1000);
      if (!film.active && time - film.lastInput > 3600 && !reducedMotion) {
        const idle = time - film.lastInput - 3600;
        film.target = film.base + Math.sin(idle * 0.00042) * 2.45;
      }
      film.phase += (film.target - film.phase) * ease;
      const { w, h } = size();
      const compact = w < 650;
      const activeIndex = nearestIndex();
      const horizontalSpacing = Math.min(168, Math.max(112, w * 0.116));
      const verticalSpacing = Math.min(122, Math.max(88, h * 0.112));
      cards.forEach((card, index) => {
        const delta = wrappedDelta(index, film.phase);
        const distance = Math.abs(delta);
        const focus = Math.exp(-distance * distance * 1.28);
        const side = Math.max(0, 1 - distance / 5);
        const direction = Math.sign(delta);
        const x = compact ? delta * 24 + Math.sin(delta * 0.9) * 25 : delta * horizontalSpacing;
        const y = compact ? delta * verticalSpacing : distance * 8 + film.pointerY * focus * 10;
        const z = focus * 145 - distance * 148;
        const sc = 0.54 + side * 0.15 + focus * 0.54;
        const rotateX = compact ? delta * 2.1 : -film.pointerY * focus * 3.5;
        const rotateY = compact
          ? -delta * 5
          : -direction * (distance > 0.2 ? 14 + Math.min(distance, 3) * 5 : 0) +
            film.pointerX * focus * 3;
        const rotateZ = compact ? delta * -1.4 : delta * 0.7;
        card.style.setProperty("--focus", focus.toFixed(4));
        card.style.zIndex = String(Math.round(1000 - distance * 100));
        card.style.opacity = String(Math.max(0.13, side * 0.76 + focus * 0.24));
        card.style.filter = `blur(${Math.max(0, distance - 1.5) * 0.38}px)`;
        card.style.transform = `translate(-50%, -50%) translate3d(${x.toFixed(2)}px, ${y.toFixed(2)}px, ${z.toFixed(2)}px) rotateX(${rotateX.toFixed(2)}deg) rotateY(${rotateY.toFixed(2)}deg) rotateZ(${rotateZ.toFixed(2)}deg) scale(${sc.toFixed(4)})`;
        card.setAttribute("aria-current", index === activeIndex ? "true" : "false");
      });
    };

    const renderWave = (time: number, deltaTime: number) => {
      const ease = reducedMotion ? 1 : 1 - Math.pow(0.0007, deltaTime / 1000);
      if (
        !wave.active &&
        !wave.manualOrientation &&
        time - wave.lastInput > 4200 &&
        !reducedMotion
      ) {
        const idle = time - wave.lastInput - 4200;
        wave.targetPhase = wave.basePhase + Math.sin(idle * 0.00034) * 1.9;
        wave.targetOrientation = (Math.sin(idle * 0.00019 - Math.PI / 2) + 1) / 2;
      }
      wave.phase += (wave.targetPhase - wave.phase) * ease;
      wave.orientation += (wave.targetOrientation - wave.orientation) * ease * 0.72;
      wave.tiltX += ((wave.active ? wave.pointerX : 0) - wave.tiltX) * ease * 0.72;
      wave.tiltY += ((wave.active ? wave.pointerY : 0) - wave.tiltY) * ease * 0.72;
      const { w, h } = size();
      const horizontalSpacing = Math.min(150, Math.max(102, w * 0.096));
      const verticalSpacing = Math.min(136, Math.max(99, h * 0.148));
      const activeIndex = nearestIndex();
      const o = wave.orientation;
      cards.forEach((card, index) => {
        const delta = wrappedDelta(index, wave.phase);
        const distance = Math.abs(delta);
        const focus = Math.exp(-Math.pow(distance, 2) * 1.05);
        const side = Math.max(0, 1 - distance / 5);
        const direction = Math.sign(delta);
        const horizontalX = delta * horizontalSpacing;
        const horizontalY = -Math.pow(distance, 1.45) * 6 + Math.sin(delta * 0.8) * 5;
        const verticalX =
          Math.sin(delta * 0.82) * Math.min(78, w * 0.06) +
          direction * Math.pow(distance, 1.25) * 8;
        const verticalY = delta * verticalSpacing;
        const x = horizontalX * (1 - o) + verticalX * o;
        const y = horizontalY * (1 - o) + verticalY * o;
        const z = focus * 95 - distance * 78;
        const sc = 0.57 + side * 0.16 + focus * 0.38;
        const rotateX = -wave.tiltY * focus * 5 + delta * 2.2 * o;
        const rotateY = wave.tiltX * focus * 7 - delta * 8.5 * (1 - o);
        const rotateZ = delta * 2.25 * (1 - o) - delta * 1.4 * o;
        card.style.setProperty("--focus", focus.toFixed(4));
        card.style.zIndex = String(Math.round(1000 - distance * 100));
        card.style.opacity = String(Math.max(0.14, side * 0.82 + focus * 0.18));
        card.style.filter = `blur(${Math.max(0, distance - 1.35) * 0.45}px) saturate(${0.72 + focus * 0.28})`;
        card.style.transform = `translate(-50%, -50%) translate3d(${x.toFixed(2)}px, ${y.toFixed(2)}px, ${z.toFixed(2)}px) rotateX(${rotateX.toFixed(2)}deg) rotateY(${rotateY.toFixed(2)}deg) rotateZ(${rotateZ.toFixed(2)}deg) scale(${sc.toFixed(4)})`;
        card.setAttribute("aria-current", index === activeIndex ? "true" : "false");
      });
    };

    const render = isFilm ? renderFilm : renderWave;
    let raf = 0;
    let prevReal = -1;
    let visible = true;
    const frame = (real: number) => {
      raf = requestAnimationFrame(frame);
      const realDelta = prevReal < 0 ? 0 : real - prevReal;
      prevReal = real;
      const delta = Math.min(32, realDelta) * speedRef.current;
      clock += realDelta * speedRef.current;
      render(clock, delta);
    };
    const start = () => {
      if (raf || !visible || document.hidden) return;
      prevReal = -1;
      raf = requestAnimationFrame(frame);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(stage);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);
    render(0, 16);
    start();

    return () => {
      stop();
      io.disconnect();
      ro.disconnect();
      document.removeEventListener("visibilitychange", onVis);
      cards.forEach((card, i) => {
        card.removeEventListener("click", cardHandlers[i]);
        card.removeEventListener("focus", cardHandlers[i]);
      });
      stage.removeEventListener("pointermove", onPointer);
      stage.removeEventListener("pointerdown", onPointer);
      stage.removeEventListener("pointerleave", onLeave);
      stage.removeEventListener("wheel", onWheel);
      stage.removeEventListener("keydown", onKey);
      stage.removeEventListener("dblclick", onDbl);
    };
  }, [isFilm, items, prefersReducedMotion]);

  return (
    <div
      className={cn("cc-root relative h-full w-full overflow-hidden", className)}
      style={{ minHeight: 400 }}
    >
      <style dangerouslySetInnerHTML={{ __html: CSS }} />
      <div
        className="absolute inset-0"
        style={{
          opacity: clamp(opacity, 0.05, 1),
          filter: `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`,
        }}
      >
        <div
          ref={stageRef}
          tabIndex={0}
          role="region"
          aria-roledescription="carousel"
          aria-label={isFilm ? "Interactive team contact sheet" : "Interactive team card wave"}
          className={cn("cc-stage", isFilm ? "cc-film" : "cc-wave")}
        >
          <div
            ref={deckRef}
            className="cc-deck"
            style={{ transform: `scale(${clamp(scale, 0.7, 1.3)})` }}
          >
            {items.map((item, index) =>
              isFilm ? (
                <button
                  key={index}
                  type="button"
                  className="cc-card"
                  aria-label={`Focus ${item.name}, ${item.role}`}
                >
                  <span className="portrait">
                    {/* eslint-disable-next-line @next/next/no-img-element */}
                    <img src={item.image} alt={`Portrait of ${item.name}`} draggable={false} />
                  </span>
                  <span className="footer">
                    <span className="index cc-mono">{String(index + 1).padStart(2, "0")}</span>
                    <span className="meta">
                      <span className="name">{item.name}</span>
                      <span className="role cc-mono">{item.role}</span>
                    </span>
                  </span>
                </button>
              ) : (
                <button
                  key={index}
                  type="button"
                  className="cc-card"
                  aria-label={`Focus ${item.name}, ${item.role}`}
                  style={{
                    ["--card-color" as string]:
                      item.color ??
                      `color-mix(in hsl, hsl(var(--primary)) ${TINTS[index % TINTS.length]}%, hsl(var(--card)))`,
                  }}
                >
                  <span className="portrait">
                    {/* eslint-disable-next-line @next/next/no-img-element */}
                    <img src={item.image} alt={`Portrait of ${item.name}`} draggable={false} />
                  </span>
                  <span className="identity">
                    <span className="name">{item.name}</span>
                    <span className="role cc-mono">{item.role}</span>
                    <span className="follow cc-mono" aria-hidden="true">
                      {followLabel}
                    </span>
                  </span>
                </button>
              ),
            )}
          </div>
        </div>
      </div>
    </div>
  );
}
```

---

# Signal Relay

> A ticked progress readout in your theme colours, with a glowing percentage and press-room phase labels.

Install: `npx @modus-ui/cli add signal-relay`

Set on the page paper in the theme primary, a 56-tick progress bar fills through a scripted run, lighting each tick with a flash while a glowing mono percentage readout flickers above it and a status line steps through its phases. Scanlines, film grain and a glitch on each restart finish the look. It scales a 1200×800 stage to fit its parent, pauses off screen and shows a still frame at 50% when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add signal-relay
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/signal-relay.tsx`.
3. Paste the code.

## Usage

```tsx
import { SignalRelay } from "@/components/ui/signal-relay";

export default function Example() {
  return (
    <div className="relative h-[400px] w-full">
      <SignalRelay label="PRESS RUN" />
    </div>
  );
}
```

## Props

| Prop              | Type                 | Default                           | Description                                                    |
| :---------------- | :------------------- | :-------------------------------- | :------------------------------------------------------------- |
| `label`           | `string`             | `"PRESS RUN"`                     | Label above the progress bar.                                  |
| `phases`          | `[number, string][]` | five press phases from 0% to 100% | Status lines, each shown from its percentage threshold upward. |
| `duration`        | `number`             | `8600`                            | Duration of the 0 → 100 run, in milliseconds.                  |
| `color`           | `string`             | `"hsl(var(--primary))"`           | Accent colour for the lit ticks, readout and glow.             |
| `backgroundColor` | `string`             | `"hsl(var(--background))"`        | Screen background.                                             |

## Source

`components/ui/signal-relay.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Uplink Loader (MIT, © 2026 Meng To).

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface SignalRelayProps {
  /** Label above the progress bar. */
  label?: string;
  /** Status lines, each shown from its percentage threshold upward. */
  phases?: [number, string][];
  /** Duration of the 0 → 100 run, in milliseconds. */
  duration?: number;
  /** Accent colour for the lit ticks, readout and glow; any CSS colour. */
  color?: string;
  /** Screen background; any CSS colour. */
  backgroundColor?: string;
  className?: string;
}

const DEFAULT_PHASES: [number, string][] = [
  [0, "WARMING THE PRESS"],
  [24, "SETTING THE TYPE"],
  [52, "INKING THE PLATES"],
  [78, "PULLING THE PROOFS"],
  [100, "EDITION READY"],
];

const CSS = `
.ul-root{--s:1;--green-dim:color-mix(in srgb,var(--green) 26%,transparent);--line:color-mix(in srgb,var(--green) 46%,transparent);--ink-hi:hsl(var(--foreground));font-family:var(--font-jetbrains-mono),ui-monospace,SFMono-Regular,Menlo,monospace;-webkit-font-smoothing:antialiased}
.ul-root *{box-sizing:border-box;margin:0;padding:0}
.ul-root .pool{position:absolute;inset:0;pointer-events:none;background:radial-gradient(ellipse 60% 44% at 50% 52%,color-mix(in srgb,var(--green) 17%,transparent) 0%,color-mix(in srgb,var(--green) 8%,transparent) 38%,color-mix(in srgb,var(--green) 2%,transparent) 66%,transparent 100%)}
.ul-root .scene{position:absolute;inset:0;overflow:hidden}
.ul-root .stage{position:absolute;left:50%;top:50%;width:1200px;height:800px;transform:translate(-50%,-50%) scale(var(--s));transform-origin:center}
.ul-root .stage>*{position:absolute}
.ul-root .plate{left:530px;top:270px;width:140px;height:84px;background:var(--line);clip-path:polygon(14px 0,100% 0,100% calc(100% - 14px),calc(100% - 14px) 100%,0 100%,0 14px)}
.ul-root .plate::after{content:"";position:absolute;inset:1.2px;background:linear-gradient(180deg,hsl(var(--card)),hsl(var(--background)));clip-path:polygon(13px 0,100% 0,100% calc(100% - 13px),calc(100% - 13px) 100%,0 100%,0 13px)}
.ul-root .plate.hit{animation:ulPlateHit .5s ease-out}
@keyframes ulPlateHit{0%{background:hsl(var(--foreground))}100%{background:var(--line)}}
.ul-root .brk{width:9px;height:9px;pointer-events:none}
.ul-root .brk::before,.ul-root .brk::after{content:"";position:absolute;background:var(--green);opacity:.9}
.ul-root .brk::before{width:9px;height:1.2px}.ul-root .brk::after{width:1.2px;height:9px}
.ul-root .brk.tr{left:661px;top:270px}.ul-root .brk.tr::before{right:0;top:0}.ul-root .brk.tr::after{right:0;top:0}
.ul-root .brk.bl{left:530px;top:345px}.ul-root .brk.bl::before{left:0;bottom:0}.ul-root .brk.bl::after{left:0;bottom:0}
.ul-root .readout{left:530px;top:284.9px;width:140px;height:0;text-align:center;line-height:1;white-space:pre;color:var(--green);text-shadow:0 0 4px color-mix(in srgb,var(--green) 60%,transparent),0 0 14px color-mix(in srgb,var(--green) 55%,transparent),0 0 36px color-mix(in srgb,var(--green) 40%,transparent);animation:ulNeon 4.3s steps(1,end) infinite}
.ul-root .readout b{font-size:47px;font-weight:280;letter-spacing:2.4px}
.ul-root .readout u{font-size:15px;font-weight:400;letter-spacing:0;text-decoration:none;opacity:.62;position:relative;top:-1px;left:3px}
@keyframes ulNeon{0%,40%{opacity:1}41%{opacity:.55}42%{opacity:1}67%{opacity:1}68%{opacity:.72}69.5%{opacity:1}70.5%{opacity:.42}71.5%{opacity:1}}
.ul-root .haze{left:298px;top:438px;width:0;height:0;pointer-events:none}
.ul-root .haze i{position:absolute;left:0;top:0;width:calc(var(--lit-w,0px) + 250px);height:250px;transform:translate(-125px,-128px);background:radial-gradient(ellipse 50% 50% at center,color-mix(in srgb,var(--green) 26%,transparent) 0%,color-mix(in srgb,var(--green) 17%,transparent) 22%,color-mix(in srgb,var(--green) 8%,transparent) 45%,color-mix(in srgb,var(--green) 2%,transparent) 70%,transparent 100%);filter:blur(6px);transition:width .16s linear}
.ul-root .haze i.pulse{animation:ulHazePulse .3s ease-out}
@keyframes ulHazePulse{0%{filter:blur(6px) brightness(1.3)}100%{filter:blur(6px) brightness(1)}}
.ul-root .bar{left:298px;top:420px;width:604px;height:44px;display:flex;justify-content:space-between;align-items:flex-end}
.ul-root .tick{width:5.4px;height:32px;background:var(--green-dim);transform:skewX(12deg)}
.ul-root .tick.mk{height:44px}
.ul-root .tick.on{background:var(--green);box-shadow:0 0 4px color-mix(in srgb,var(--green) 60%,transparent),0 0 11px color-mix(in srgb,var(--green) 32%,transparent),0 0 24px color-mix(in srgb,var(--green) 16%,transparent)}
.ul-root .tick.flash{animation:ulIgnite .32s ease-out}
@keyframes ulIgnite{0%{background:hsl(var(--foreground));box-shadow:0 0 11px color-mix(in srgb,var(--green) 100%,transparent),0 0 28px color-mix(in srgb,var(--green) 85%,transparent),0 0 54px color-mix(in srgb,var(--green) 45%,transparent)}100%{background:var(--green);box-shadow:0 0 4px color-mix(in srgb,var(--green) 60%,transparent),0 0 11px color-mix(in srgb,var(--green) 32%,transparent),0 0 24px color-mix(in srgb,var(--green) 16%,transparent)}}
.ul-root .barlabel{left:298px;top:396.4px;font-size:20.4px;font-weight:500;letter-spacing:.9px;line-height:1;color:var(--ink-hi);text-shadow:0 0 3px color-mix(in srgb,var(--green) 34%,transparent),0 0 11px color-mix(in srgb,var(--green) 30%,transparent),0 0 26px color-mix(in srgb,var(--green) 22%,transparent)}
.ul-root .status{left:0;top:507px;width:1200px;text-align:center;font-size:14px;font-weight:500;line-height:1;letter-spacing:1.42px;text-indent:1.42px;color:hsl(var(--muted-foreground));white-space:pre;text-shadow:0 0 3px color-mix(in srgb,var(--green) 30%,transparent),0 0 10px color-mix(in srgb,var(--green) 22%,transparent)}
.ul-root .status .dots{letter-spacing:-1.9px;margin-left:-6px}
.ul-root .marker{width:0;height:0}
.ul-root .marker i{position:absolute;background:var(--green);opacity:.72}
.ul-root .marker .h{width:9px;height:1.2px}.ul-root .marker .v{width:1.2px;height:9px}
.ul-root .marker .a-h{left:-17px;top:-17px}.ul-root .marker .a-v{left:-17px;top:-17px}
.ul-root .marker .b-h{left:8px;top:-17px}.ul-root .marker .b-v{left:15.8px;top:-17px}
.ul-root .marker .c-h{left:-17px;top:15.8px}.ul-root .marker .c-v{left:-17px;top:8px}
.ul-root .marker .d-h{left:8px;top:15.8px}.ul-root .marker .d-v{left:15.8px;top:8px}
.ul-root .marker .dia{left:-4px;top:-4px;width:8px;height:8px;opacity:1;background:var(--green);transform:rotate(45deg);box-shadow:0 0 6px color-mix(in srgb,var(--green) 70%,transparent);animation:ulDiaPulse 3.2s ease-in-out infinite}
@keyframes ulDiaPulse{0%,100%{opacity:.55;transform:rotate(45deg) scale(.8)}50%{opacity:1;transform:rotate(45deg) scale(1)}}
.ul-root .m-tl{left:274px;top:340px}.ul-root .m-tr{left:926px;top:340px}
.ul-root .m-bl{left:274px;top:508px}.ul-root .m-br{left:926px;top:508px}
.ul-root .m-tr .dia{animation-delay:.5s}.ul-root .m-bl .dia{animation-delay:1.1s}.ul-root .m-br .dia{animation-delay:1.6s}
.ul-root .rail{left:0;top:0;width:1200px;height:800px}
.ul-root .rail.right{transform:scaleX(-1)}
.ul-root .rail>*{position:absolute}
.ul-root .rail .wire{left:104px;top:433px;width:92px;height:1.4px;background:color-mix(in srgb,var(--green) 24%,transparent)}
.ul-root .rail .cap{top:428px;height:5px;background:var(--green);box-shadow:0 0 5px color-mix(in srgb,var(--green) 60%,transparent)}
.ul-root .rail .cap.a{left:104px;width:10px}
.ul-root .rail .cap.b{left:181px;width:15px;animation:ulCapPulse 2.4s ease-in-out infinite}
@keyframes ulCapPulse{0%,100%{opacity:1}50%{opacity:.5}}
.ul-root .mod{left:204px;top:404px;width:36px;height:62px}
.ul-root .mod>*{position:absolute;left:0}
.ul-root .mod .hatch{top:0;width:36px;height:2px;background:hsl(var(--foreground))}
.ul-root .mod .ret{top:8px;left:3px;width:30px;height:30px;border-radius:50%;border:1.3px solid color-mix(in srgb,var(--green) 82%,transparent)}
.ul-root .mod .ret::before,.ul-root .mod .ret::after{content:"";position:absolute;background:color-mix(in srgb,var(--green) 45%,transparent)}
.ul-root .mod .ret::before{left:-3.5px;top:13.6px;width:35px;height:1px}
.ul-root .mod .ret::after{left:13.6px;top:-3.5px;width:1px;height:35px}
.ul-root .mod .dot{top:12.5px;left:15.5px;width:5px;height:5px;border-radius:50%;background:var(--green);box-shadow:0 0 6px color-mix(in srgb,var(--green) 90%,transparent);animation:ulDiaPulse 2.6s ease-in-out infinite}
.ul-root .mod .slab{top:46px;width:36px;height:5px;background:hsl(var(--foreground));clip-path:polygon(0 0,100% 0,100% 100%,5px 100%)}
.ul-root .mod .led{top:55px;height:2.6px;background:hsl(var(--muted-foreground))}
.ul-root .mod .led:nth-of-type(1){left:0;width:3px}
.ul-root .mod .led:nth-of-type(2){left:4.5px;width:4px}
.ul-root .mod .led:nth-of-type(3){left:27px;width:4px}
.ul-root .mod .led:nth-of-type(4){left:33px;width:3px}
.ul-root .scan{position:absolute;inset:0;pointer-events:none;opacity:.18;background:repeating-linear-gradient(to bottom,color-mix(in srgb,var(--green) 5%,transparent) 0 calc(1px * var(--s)),transparent calc(1px * var(--s)) calc(3px * var(--s)))}
.ul-root .grain{position:absolute;inset:-60px;pointer-events:none;background-repeat:repeat;background-size:80px 80px;animation:ulGrainShift .6s steps(1,end) infinite}
.ul-root .grain.mul{mix-blend-mode:overlay;opacity:.40}
.ul-root .grain.add{opacity:.035;animation-duration:.72s}
@keyframes ulGrainShift{0%{transform:translate(0,0)}20%{transform:translate(-22px,14px)}40%{transform:translate(17px,-19px)}60%{transform:translate(-13px,-9px)}80%{transform:translate(9px,21px)}100%{transform:translate(0,0)}}
.ul-root .stage.reset{animation:ulResetGlitch .42s ease-out}
@keyframes ulResetGlitch{0%{filter:brightness(1.8) saturate(.5)}18%{filter:brightness(.32)}30%{filter:brightness(1.2)}100%{filter:none}}
.ul-root[data-still] .grain,.ul-root[data-still] .readout,.ul-root[data-still] .marker .dia,.ul-root[data-still] .mod .dot,.ul-root[data-still] .rail .cap.b{animation:none!important}
`;

const TICKS = 56;
const MARK_EVERY = 8;
const KF: [number, number][] = [
  [0, 0],
  [0.045, 9],
  [0.115, 9.6],
  [0.16, 22],
  [0.205, 23],
  [0.3, 38],
  [0.345, 39.5],
  [0.4, 53],
  [0.475, 54],
  [0.545, 68],
  [0.6, 69],
  [0.665, 81],
  [0.735, 82],
  [0.8, 92],
  [0.855, 93],
  [0.925, 99],
  [0.985, 99.4],
  [1.0, 100],
];

function Marker({ className }: { className: string }) {
  return (
    <div className={cn("marker", className)}>
      {["a", "b", "c", "d"].map((k) => (
        <span key={k}>
          <i className={`h ${k}-h`} />
          <i className={`v ${k}-v`} />
        </span>
      ))}
      <i className="dia" />
    </div>
  );
}

function Rail({ side }: { side: "left" | "right" }) {
  return (
    <div className={cn("rail", side)}>
      <div className="wire" />
      <div className="cap a" />
      <div className="cap b" />
      <div className="mod">
        <div className="hatch" />
        <div className="ret" />
        <div className="dot" />
        <div className="slab" />
        <i className="led" />
        <i className="led" />
        <i className="led" />
        <i className="led" />
      </div>
    </div>
  );
}

function makeGrain(fn: (d: Uint8ClampedArray, o: number) => void) {
  const N = 160;
  const c = document.createElement("canvas");
  c.width = c.height = N;
  const ctx = c.getContext("2d");
  if (!ctx) return "";
  const img = ctx.createImageData(N, N);
  for (let i = 0; i < N * N; i++) fn(img.data, i * 4);
  ctx.putImageData(img, 0, 0);
  return c.toDataURL();
}

export function SignalRelay({
  label = "PRESS RUN",
  phases = DEFAULT_PHASES,
  duration = 8600,
  color = "hsl(var(--primary))",
  backgroundColor = "hsl(var(--background))",
  className,
}: SignalRelayProps) {
  const prefersReducedMotion = useReducedMotion();
  const rootRef = useRef<HTMLDivElement>(null);
  const phasesRef = useRef(phases);
  phasesRef.current = phases;

  useEffect(() => {
    const root = rootRef.current;
    if (!root) return;
    const q = <T extends HTMLElement>(s: string) => root.querySelector(s) as T;

    const fit = () => {
      const { width, height } = root.getBoundingClientRect();
      root.style.setProperty("--s", String(Math.min(width / 1200, height / 800)));
    };
    const ro = new ResizeObserver(fit);
    ro.observe(root);
    fit();

    const bar = q<HTMLDivElement>(".bar");
    bar.innerHTML = "";
    const ticks: HTMLElement[] = [];
    for (let i = 0; i < TICKS; i++) {
      const t = document.createElement("i");
      t.className = "tick" + ((i + 1) % MARK_EVERY === 0 ? " mk" : "");
      bar.appendChild(t);
      ticks.push(t);
    }

    const g = () => (Math.random() + Math.random() + Math.random() + Math.random()) / 4;
    q(".grain.mul").style.backgroundImage = `url(${makeGrain((d, o) => {
      const v = 128 + (g() - 0.5) * 300;
      d[o] = d[o + 1] = d[o + 2] = Math.max(0, Math.min(255, v));
      d[o + 3] = 255;
    })})`;
    q(".grain.add").style.backgroundImage = `url(${makeGrain((d, o) => {
      const v = Math.random();
      d[o] = d[o + 1] = d[o + 2] = 255;
      d[o + 3] = v < 0.86 ? 0 : Math.round(((v - 0.86) / 0.14) * 190);
    })})`;

    const RUN = duration;
    const HOLD = 1600;
    const BLANK = 420;
    const LOOP = RUN + HOLD + BLANK;
    const easeOut = (x: number) => 1 - Math.pow(1 - x, 2.1);
    const valueAt = (u: number) => {
      if (u >= 1) return 100;
      for (let i = 0; i < KF.length - 1; i++) {
        const [t0, v0] = KF[i];
        const [t1, v1] = KF[i + 1];
        if (u <= t1) return v0 + (v1 - v0) * easeOut((u - t0) / (t1 - t0));
      }
      return 100;
    };
    const phaseFor = (p: number) => {
      const list = phasesRef.current;
      let t = list[0]?.[1] ?? "";
      for (const [k, v] of list) if (p >= k) t = v;
      return t;
    };

    const num = q(".num");
    const dots = q(".dots");
    const statText = q(".stat-text");
    const haze = q(".haze i");
    const stage = q(".stage");
    const plate = q(".plate");
    const tickW = 5.4;
    const gap = (604 - TICKS * tickW) / (TICKS - 1);
    const pitch = tickW + gap;

    let lastLit = -1;
    let lastPct = -1;
    let lastDots = -1;
    let lastPhase = "";
    let cycle = 0;
    let elapsed = 0;
    let prev = -1;
    let raf = 0;
    let visible = true;
    const restart = (el: HTMLElement, cls: string) => {
      el.classList.remove(cls);
      void el.offsetWidth;
      el.classList.add(cls);
    };

    const render = (frozen: number | null) => {
      const e = elapsed % LOOP;
      const c = Math.floor(elapsed / LOOP);
      if (c !== cycle) {
        cycle = c;
        restart(stage, "reset");
      }
      let pct: number;
      let shownVisible = true;
      if (e < RUN) pct = valueAt(e / RUN);
      else if (e < RUN + HOLD) pct = 100;
      else {
        pct = 0;
        shownVisible = (e - RUN - HOLD) % 220 < 130;
      }
      if (frozen !== null) {
        pct = frozen;
        shownVisible = true;
      }
      const shown = Math.round(pct);
      if (shown !== lastPct) {
        num.textContent = String(shown);
        lastPct = shown;
        const ph = phaseFor(shown);
        if (ph !== lastPhase) {
          lastPhase = ph;
          statText.textContent = ph;
        }
      }
      (num.parentElement as HTMLElement).style.opacity = shownVisible ? "" : ".22";
      const lit = Math.round((pct / 100) * TICKS);
      if (lit !== lastLit) {
        for (let i = 0; i < TICKS; i++) ticks[i].classList.toggle("on", i < lit);
        if (lit > lastLit && lastLit >= 0 && lit > 0 && frozen === null) {
          restart(ticks[lit - 1], "flash");
          restart(haze, "pulse");
        }
        haze.style.setProperty(
          "--lit-w",
          (lit > 0 ? (lit - 1) * pitch + tickW + gap / 2 : 0) + "px",
        );
        if (lit === TICKS && frozen === null) restart(plate, "hit");
        lastLit = lit;
      }
      const d = shown >= 100 ? 0 : frozen !== null ? 3 : Math.floor((elapsed / 380) % 4);
      if (d !== lastDots) {
        dots.textContent = "...".slice(0, d);
        lastDots = d;
      }
    };

    if (prefersReducedMotion) {
      render(50);
      return () => ro.disconnect();
    }

    const frame = (now: number) => {
      if (prev >= 0) elapsed += now - prev;
      prev = now;
      render(null);
      raf = requestAnimationFrame(frame);
    };
    const start = () => {
      if (raf || !visible || document.hidden) return;
      prev = -1;
      raf = requestAnimationFrame(frame);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(root);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);
    start();
    return () => {
      stop();
      io.disconnect();
      ro.disconnect();
      document.removeEventListener("visibilitychange", onVis);
    };
  }, [duration, prefersReducedMotion]);

  return (
    <div
      ref={rootRef}
      role="progressbar"
      aria-label={label}
      data-still={prefersReducedMotion ? "" : undefined}
      className={cn("ul-root relative h-full w-full overflow-hidden", className)}
      style={{ background: backgroundColor, ["--green" as string]: color }}
    >
      <style dangerouslySetInnerHTML={{ __html: CSS }} />
      <div className="pool" />
      <div className="scene">
        <div className="stage">
          <div className="haze">
            <i />
          </div>
          <div className="plate" />
          <div className="brk tr" />
          <div className="brk bl" />
          <div className="readout">
            <b className="num">50</b>
            <u>%</u>
          </div>
          <div className="barlabel">{label}</div>
          <div className="bar" />
          <div className="status">
            <span className="stat-text">{phases[0]?.[1]}</span>
            <span className="dots">...</span>
          </div>
          <Marker className="m-tl" />
          <Marker className="m-tr" />
          <Marker className="m-bl" />
          <Marker className="m-br" />
          <Rail side="left" />
          <Rail side="right" />
        </div>
      </div>
      <div className="scan" />
      <div className="grain mul" />
      <div className="grain add" />
    </div>
  );
}
```

---

# Intaglio Deed

> A guilloche intaglio deed in theme ink whose rosette cycles through four lathe cams.

Install: `npx @modus-ui/cli add intaglio-deed`

A paper certificate drawn on Canvas 2D: an engraved wave field and guilloche border, a medal of two rosettes and a slowly drifting harmonic pass. Every few seconds it switches to the next cam, redrawing the rosettes. It pauses off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add intaglio-deed
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/intaglio-deed.tsx`.
3. Paste the code.

## Usage

```tsx
import { IntaglioDeed } from "@/components/ui/intaglio-deed";

export default function Example() {
  return (
    <div className="relative h-[560px] w-full">
      <IntaglioDeed label="Modus UI" title="Folio 07 · Plate" />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default               | Description                              |
| :---------------- | :------- | :-------------------- | :--------------------------------------- |
| `label`           | `string` | `"Modus Atelier"`     | Small mono label above the medal.        |
| `title`           | `string` | `"Folio 07 · Plate"`  | Headline before the cam letter.          |
| `caption`         | `string` | `"Current plate ·"`   | Caption before the cam letter.           |
| `inkColor`        | `string` | `"#1f3a30"`           | Engraving ink colour (hex).              |
| `paperColor`      | `string` | `"#f5efdf"`           | Certificate paper colour.                |
| `backgroundColor` | `string` | `"hsl(var(--muted))"` | Scene background behind the certificate. |
| `cycleInterval`   | `number` | `4200`                | Milliseconds between cam changes.        |

## Source

`components/ui/intaglio-deed.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Engraved Certificate (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface IntaglioDeedProps {
  /** Small mono label above the medal. */
  label?: string;
  /** Headline before the cam letter. */
  title?: string;
  /** Caption before the cam letter. */
  caption?: string;
  /** Engraving ink colour as hex; defaults to the theme primary. */
  inkColor?: string;
  /** Certificate paper colour; defaults to the theme card. */
  paperColor?: string;
  /** Scene background behind the certificate. */
  backgroundColor?: string;
  /** Milliseconds between cam changes. */
  cycleInterval?: number;
  className?: string;
}

const THEME_TOKENS = [
  "primary",
  "foreground",
  "muted-foreground",
  "background",
  "card",
  "border",
] as const;
type ThemeChannels = Record<(typeof THEME_TOKENS)[number], string>;

/** Reads the theme's bare HSL channels and re-reads them when the theme or palette changes. */
function useThemeChannels() {
  const [tokens, setTokens] = useState<ThemeChannels | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const next = Object.fromEntries(
        THEME_TOKENS.map((name) => [name, style.getPropertyValue(`--${name}`).trim()]),
      ) as ThemeChannels;
      setTokens((prev) => (prev && THEME_TOKENS.every((k) => prev[k] === next[k]) ? prev : next));
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

const TAU = Math.PI * 2;
const BARS = [
  { id: "A", m: 7, m2: 13, m3: 9 },
  { id: "B", m: 9, m2: 15, m3: 12 },
  { id: "C", m: 11, m2: 19, m3: 14 },
  { id: "D", m: 15, m2: 23, m3: 18 },
];

type Pt = [number, number];
type RailPt = [number, number, number, number];

function hexToRgb(hex: string) {
  const h = hex.replace("#", "");
  const full =
    h.length === 3
      ? h
          .split("")
          .map((c) => c + c)
          .join("")
      : h;
  const n = parseInt(full, 16);
  return `${(n >> 16) & 255},${(n >> 8) & 255},${n & 255}`;
}

function circleOutline(cx: number, cy: number, r: number, samples: number) {
  const pts: Pt[] = new Array(samples);
  for (let i = 0; i < samples; i++) {
    const th = (i / samples) * TAU;
    pts[i] = [cx + Math.cos(th) * r, cy + Math.sin(th) * r];
  }
  return pts;
}

function rectOutline(x: number, y: number, w: number, h: number, r: number) {
  const pts: Pt[] = [];
  const push = (px: number, py: number) => {
    const l = pts[pts.length - 1];
    if (l && Math.abs(l[0] - px) < 1e-4 && Math.abs(l[1] - py) < 1e-4) return;
    pts.push([px, py]);
  };
  const seg = (x0: number, y0: number, xe: number, ye: number) => {
    const n = Math.max(2, Math.round(Math.hypot(xe - x0, ye - y0) / 4));
    for (let i = 0; i <= n; i++) push(x0 + ((xe - x0) * i) / n, y0 + ((ye - y0) * i) / n);
  };
  const arc = (cx: number, cy: number, a0: number, a1: number) => {
    const n = Math.max(7, Math.round((Math.abs(a1 - a0) * r) / 1.6));
    for (let i = 0; i <= n; i++) {
      const a = a0 + ((a1 - a0) * i) / n;
      push(cx + Math.cos(a) * r, cy + Math.sin(a) * r);
    }
  };
  const x1 = x + w;
  const y1 = y + h;
  const HP = Math.PI / 2;
  seg(x + r, y, x1 - r, y);
  arc(x1 - r, y + r, -HP, 0);
  seg(x1, y + r, x1, y1 - r);
  arc(x1 - r, y1 - r, 0, HP);
  seg(x1 - r, y1, x + r, y1);
  arc(x + r, y1 - r, HP, Math.PI);
  seg(x, y1 - r, x, y + r);
  arc(x + r, y + r, Math.PI, Math.PI * 1.5);
  return pts;
}

function rail(pts: Pt[], M: number) {
  const nP = pts.length;
  const cum = new Float64Array(nP + 1);
  for (let i = 1; i <= nP; i++) {
    const p = pts[i % nP];
    const q = pts[i - 1];
    cum[i] = cum[i - 1] + Math.hypot(p[0] - q[0], p[1] - q[1]);
  }
  const L = cum[nP];
  const out: RailPt[] = new Array(M);
  let j = 0;
  for (let i = 0; i < M; i++) {
    const target = (i / M) * L;
    while (j < nP - 1 && cum[j + 1] < target) j++;
    const seg = cum[j + 1] - cum[j] || 1;
    const u = (target - cum[j]) / seg;
    const p = pts[j];
    const q = pts[(j + 1) % nP];
    out[i] = [
      p[0] + (q[0] - p[0]) * u,
      p[1] + (q[1] - p[1]) * u,
      (q[1] - p[1]) / seg,
      -(q[0] - p[0]) / seg,
    ];
  }
  return out;
}

function rand32(a: number) {
  return function () {
    a |= 0;
    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;
  };
}

export function IntaglioDeed({
  label = "Modus Atelier",
  title = "Folio 07 · Plate",
  caption = "Current plate ·",
  inkColor,
  paperColor,
  backgroundColor = "hsl(var(--muted))",
  cycleInterval = 4200,
  className,
}: IntaglioDeedProps) {
  const prefersReducedMotion = useReducedMotion();
  const certRef = useRef<HTMLElement>(null);
  const medalRef = useRef<HTMLElement>(null);
  const plateRef = useRef<HTMLCanvasElement>(null);
  const roseRef = useRef<HTMLCanvasElement>(null);
  const driftRef = useRef<HTMLCanvasElement>(null);
  const barNameRef = useRef<HTMLElement>(null);
  const capBarRef = useRef<HTMLSpanElement>(null);
  const theme = useThemeChannels();
  const inkRgb = inkColor ? hexToRgb(inkColor) : null;
  const inkCh = theme?.primary ?? "0 0% 10%";
  const paperCh = theme?.card ?? "0 0% 100%";
  const paper = paperColor ?? `hsl(${paperCh})`;
  /** Ink at an alpha: the hex override, or the theme primary. Usable in canvas and CSS. */
  const inkAt = (a: number) => (inkRgb ? `rgba(${inkRgb},${a})` : `hsl(${inkCh} / ${a})`);

  useEffect(() => {
    const cert = certRef.current;
    const medal = medalRef.current;
    const cPlate = plateRef.current;
    const cRose = roseRef.current;
    const cDrift = driftRef.current;
    if (!cert || !medal || !cPlate || !cRose || !cDrift) return;
    const ctxP = cPlate.getContext("2d");
    const ctxR = cRose.getContext("2d");
    const ctxD = cDrift.getContext("2d");
    if (!ctxP || !ctxR || !ctxD) return;
    const reduce = !!prefersReducedMotion;
    const ink = inkAt;
    let sel = 0;

    const fit = (
      canvas: HTMLCanvasElement,
      ctx: CanvasRenderingContext2D,
      w: number,
      h: number,
    ) => {
      const S = Math.min(window.devicePixelRatio || 1, 2);
      const W = Math.max(2, Math.round(w * S));
      const H = Math.max(2, Math.round(h * S));
      if (canvas.width !== W || canvas.height !== H) {
        canvas.width = W;
        canvas.height = H;
      }
      ctx.setTransform(S, 0, 0, S, 0, 0);
      ctx.clearRect(0, 0, w, h);
    };

    const band = (
      ctx: CanvasRenderingContext2D,
      r: RailPt[],
      o: { amp: number; waves: number; K: number; alpha: number; lw: number; phase?: number },
    ) => {
      const M = r.length;
      ctx.lineWidth = o.lw;
      ctx.strokeStyle = ink(o.alpha);
      ctx.beginPath();
      for (let k = 0; k < o.K; k++) {
        const ph = (o.phase || 0) + (k / o.K) * TAU;
        for (let i = 0; i <= M; i++) {
          const p = r[i % M];
          const u = (i % M) / M;
          const off = o.amp * Math.sin(o.waves * u * TAU + ph);
          const x = p[0] + p[2] * off;
          const y = p[1] + p[3] * off;
          if (i) ctx.lineTo(x, y);
          else ctx.moveTo(x, y);
        }
      }
      ctx.stroke();
    };

    const railLine = (
      ctx: CanvasRenderingContext2D,
      r: RailPt[],
      off: number,
      alpha: number,
      lw: number,
    ) => {
      const M = r.length;
      ctx.lineWidth = lw;
      ctx.strokeStyle = ink(alpha);
      ctx.beginPath();
      for (let i = 0; i <= M; i++) {
        const p = r[i % M];
        const x = p[0] + p[2] * off;
        const y = p[1] + p[3] * off;
        if (i) ctx.lineTo(x, y);
        else ctx.moveTo(x, y);
      }
      ctx.stroke();
    };

    const rosette = (
      ctx: CanvasRenderingContext2D,
      cx: number,
      cy: number,
      o: {
        A: number;
        d: number;
        m: number;
        n: number;
        pts: number;
        alpha: number;
        lw: number;
        dir?: number;
        shrink?: number;
        phase?: number;
      },
    ) => {
      const dir = o.dir || 1;
      const shrink = o.shrink === undefined ? 0.06 : o.shrink;
      ctx.lineWidth = o.lw;
      ctx.strokeStyle = ink(o.alpha);
      ctx.lineJoin = "round";
      ctx.beginPath();
      for (let k = 0; k < o.n; k++) {
        const f = k / o.n;
        const phi = (o.phase || 0) + dir * f * TAU;
        const a = o.A * (1 - shrink * f);
        for (let i = 0; i <= o.pts; i++) {
          const t = (i / o.pts) * TAU;
          const x = cx + a * Math.cos(t) + o.d * Math.cos(o.m * t + phi);
          const y = cy + a * Math.sin(t) - o.d * Math.sin(o.m * t + phi);
          if (i) ctx.lineTo(x, y);
          else ctx.moveTo(x, y);
        }
      }
      ctx.stroke();
    };

    const waveField = (ctx: CanvasRenderingContext2D, w: number, h: number) => {
      ctx.lineWidth = 0.5;
      ctx.strokeStyle = ink(0.075);
      const pitch = 6.2;
      const N = Math.ceil(h / pitch) + 2;
      const step = 7;
      ctx.beginPath();
      for (let i = 0; i < N; i++) {
        const y0 = i * pitch - 3;
        const ph = i * 0.44;
        for (let x = 0; x <= w; x += step) {
          const y =
            y0 +
            3.3 * Math.sin(x * 0.0139 + ph) +
            1.9 * Math.sin(x * 0.0327 - ph * 1.7) +
            0.9 * Math.sin(x * 0.0715 + ph * 0.6);
          if (x) ctx.lineTo(x, y);
          else ctx.moveTo(x, y);
        }
      }
      ctx.stroke();
    };

    const drawPlate = () => {
      const w = cert.clientWidth;
      const h = cert.clientHeight;
      if (!w || !h) return;
      fit(cPlate, ctxP, w, h);
      ctxP.fillStyle = paper;
      ctxP.fillRect(0, 0, w, h);
      let g = ctxP.createRadialGradient(
        w * 0.28,
        h * 0.16,
        8,
        w * 0.28,
        h * 0.16,
        Math.max(w, h) * 0.95,
      );
      g.addColorStop(0, `hsl(${paperCh} / 0.85)`);
      g.addColorStop(1, `hsl(${paperCh} / 0)`);
      ctxP.fillStyle = g;
      ctxP.fillRect(0, 0, w, h);
      g = ctxP.createRadialGradient(
        w * 0.88,
        h * 0.94,
        8,
        w * 0.88,
        h * 0.94,
        Math.max(w, h) * 0.85,
      );
      g.addColorStop(0, ink(0.06));
      g.addColorStop(1, ink(0));
      ctxP.fillStyle = g;
      ctxP.fillRect(0, 0, w, h);
      const rnd = rand32(4409);
      for (let i = 0; i < 1100; i++) {
        ctxP.fillStyle = ink(0.018 + rnd() * 0.05);
        ctxP.fillRect(rnd() * w, rnd() * h, 1, rnd() < 0.12 ? 2 : 1);
      }
      waveField(ctxP, w, h);
      const narrow = w < 520;
      const inset = narrow ? 7 : 10;
      const half = narrow ? 3.1 : 3.8;
      const br = rail(
        rectOutline(
          inset + half,
          inset + half,
          w - 2 * (inset + half),
          h - 2 * (inset + half),
          narrow ? 5 : 7,
        ),
        narrow ? 760 : 1240,
      );
      band(ctxP, br, { amp: half, waves: narrow ? 54 : 116, K: 9, alpha: 0.3, lw: 0.5 });
      railLine(ctxP, br, -half - 1.9, 0.34, 0.6);
      railLine(ctxP, br, half + 1.9, 0.3, 0.5);
      railLine(ctxP, br, half + 4.4, 0.13, 0.5);
    };

    const drawRosettes = () => {
      const w = medal.clientWidth;
      const h = medal.clientHeight;
      if (!w || !h) return;
      fit(cRose, ctxR, w, h);
      const cx = w / 2;
      const cy = h / 2;
      const R = Math.min(w, h) / 2;
      const bar = BARS[sel];
      const small = R < 130;
      const g = ctxR.createRadialGradient(cx, cy, R * 0.06, cx, cy, R);
      g.addColorStop(0, `hsl(${paperCh} / 0.92)`);
      g.addColorStop(0.76, `hsl(${paperCh} / 0.84)`);
      g.addColorStop(1, `hsl(${paperCh} / 0)`);
      ctxR.fillStyle = g;
      ctxR.beginPath();
      ctxR.arc(cx, cy, R, 0, TAU);
      ctxR.fill();
      const ring = rail(circleOutline(cx, cy, R * 0.93, 640), small ? 460 : 620);
      band(ctxR, ring, { amp: R * 0.036, waves: (bar.m + 1) * 5, K: 7, alpha: 0.3, lw: 0.5 });
      railLine(ctxR, ring, -R * 0.036 - 1.8, 0.34, 0.6);
      railLine(ctxR, ring, R * 0.036 + 1.8, 0.28, 0.5);
      rosette(ctxR, cx, cy, {
        A: R * 0.655,
        d: R * 0.215,
        m: bar.m,
        n: small ? 44 : 58,
        pts: small ? 340 : 470,
        alpha: 0.42,
        lw: 0.5,
        shrink: 0.035,
        phase: 0.2,
      });
      rosette(ctxR, cx, cy, {
        A: R * 0.335,
        d: R * 0.115,
        m: bar.m2,
        n: small ? 34 : 44,
        pts: small ? 280 : 380,
        alpha: 0.38,
        lw: 0.5,
        dir: -1,
        shrink: 0.05,
        phase: 0.9,
      });
      ctxR.beginPath();
      ctxR.arc(cx, cy, R * 0.07, 0, TAU);
      ctxR.fillStyle = `hsl(${paperCh} / 0.86)`;
      ctxR.fill();
      ctxR.lineWidth = 0.6;
      ctxR.strokeStyle = ink(0.32);
      ctxR.stroke();
      ctxR.beginPath();
      ctxR.arc(cx, cy, R * 0.04, 0, TAU);
      ctxR.strokeStyle = ink(0.24);
      ctxR.lineWidth = 0.5;
      ctxR.stroke();
    };

    let phase = 0;
    const drawDrift = () => {
      const w = medal.clientWidth;
      const h = medal.clientHeight;
      if (!w || !h) return;
      fit(cDrift, ctxD, w, h);
      const R = Math.min(w, h) / 2;
      const small = R < 130;
      rosette(ctxD, w / 2, h / 2, {
        A: R * 0.515,
        d: R * 0.165,
        m: BARS[sel].m3,
        n: small ? 26 : 34,
        pts: small ? 240 : 320,
        alpha: 0.3,
        lw: 0.5,
        shrink: 0.03,
        phase,
      });
    };

    const paintLabels = () => {
      const id = BARS[sel].id;
      if (barNameRef.current) barNameRef.current.textContent = id;
      if (capBarRef.current) capBarRef.current.textContent = id;
    };
    const drawAll = () => {
      drawPlate();
      drawRosettes();
      drawDrift();
    };
    paintLabels();
    drawAll();

    let timer = 0;
    let onScreen = true;
    const halt = () => {
      if (timer) {
        clearTimeout(timer);
        timer = 0;
      }
    };
    const schedule = () => {
      if (timer || reduce || !onScreen || document.hidden) return;
      timer = window.setTimeout(tick, 140);
    };
    function tick() {
      timer = 0;
      phase += 0.019;
      if (phase > TAU) phase -= TAU;
      drawDrift();
      schedule();
    }
    const cycleCam = () => {
      if (reduce || document.hidden || !onScreen) return;
      sel = (sel + 1) % BARS.length;
      paintLabels();
      drawRosettes();
      drawDrift();
    };

    const io = new IntersectionObserver(
      (entries) => {
        onScreen = entries[0].isIntersecting;
        if (onScreen) schedule();
        else halt();
      },
      { threshold: 0.02 },
    );
    io.observe(cert);
    const onVis = () => (document.hidden ? halt() : schedule());
    document.addEventListener("visibilitychange", onVis);
    let rt = 0;
    const ro = new ResizeObserver(() => {
      clearTimeout(rt);
      rt = window.setTimeout(drawAll, 120);
    });
    ro.observe(cert);
    const camTimer = reduce ? 0 : window.setInterval(cycleCam, cycleInterval);
    schedule();
    let alive = true;
    document.fonts?.ready.then(() => alive && drawAll()).catch(() => {});

    return () => {
      alive = false;
      halt();
      clearInterval(camTimer);
      clearTimeout(rt);
      io.disconnect();
      ro.disconnect();
      document.removeEventListener("visibilitychange", onVis);
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps -- inkAt derives from inkRgb and inkCh
  }, [prefersReducedMotion, inkRgb, inkCh, paperCh, paper, cycleInterval]);

  return (
    <div
      className={cn(
        "relative flex h-full w-full items-center justify-center overflow-hidden",
        className,
      )}
      style={{
        background: backgroundColor,
        color: inkAt(1),
        containerType: "size",
        WebkitFontSmoothing: "antialiased",
      }}
    >
      <style
        dangerouslySetInnerHTML={{
          __html:
            ".ec-cert{aspect-ratio:1.08/1}.ec-medal{width:min(58cqmin,280px);height:min(58cqmin,280px)}" +
            "@container (max-width:520px),(max-height:560px){.ec-cert{aspect-ratio:auto;height:100%}.ec-medal{width:min(62cqmin,240px);height:min(62cqmin,240px)}}",
        }}
      />
      <article
        ref={certRef}
        aria-label={`${label} certificate`}
        className="ec-cert relative flex flex-none flex-col items-center justify-center overflow-auto rounded-[3px]"
        style={{
          width: "min(calc(100% - 32px), 720px)",
          maxHeight: "calc(100% - 32px)",
          gap: "clamp(10px, 2.4cqmin, 18px)",
          padding: "clamp(16px, 4cqmin, 36px)",
          background: `repeating-linear-gradient(0deg, ${inkAt(0.045)} 0 0.5px, transparent 0.5px 6px), linear-gradient(168deg, color-mix(in srgb, ${paper} 92%, white) 0%, ${paper} 40%, color-mix(in srgb, ${paper} 94%, ${inkAt(1)}) 100%)`,
          boxShadow: `0 0 0 1px ${inkAt(0.13)}, 0 1px 0 hsl(${paperCh} / 0.55) inset, 0 30px 60px -34px hsl(var(--foreground) / 0.45), 0 3px 8px hsl(var(--foreground) / 0.08)`,
        }}
      >
        <canvas
          ref={plateRef}
          aria-hidden="true"
          className="pointer-events-none absolute inset-0 block h-full w-full rounded-[inherit]"
        />
        <div
          className="relative z-[1] flex flex-col items-center text-center"
          style={{ gap: "clamp(10px, 2.2cqmin, 16px)", width: "min(100%, 420px)" }}
        >
          <div
            className="font-mono uppercase"
            style={{
              fontSize: "clamp(9px, 1.7cqmin, 11px)",
              letterSpacing: "0.24em",
              color: inkAt(0.44),
            }}
          >
            {label}
          </div>
          <figure ref={medalRef} className="ec-medal relative mx-10 my-4 flex-none rounded-full">
            <canvas
              ref={roseRef}
              aria-hidden="true"
              className="pointer-events-none absolute inset-0 block h-full w-full"
            />
            <canvas
              ref={driftRef}
              aria-hidden="true"
              className="pointer-events-none absolute inset-0 block h-full w-full"
            />
          </figure>
          <h1
            className="m-0 font-serif"
            style={{
              fontSize: "clamp(22px, 4.8cqmin, 34px)",
              fontWeight: 500,
              letterSpacing: "0.02em",
              lineHeight: 1,
            }}
          >
            {title}{" "}
            <em ref={barNameRef} className="not-italic" style={{ color: inkAt(0.62) }}>
              A
            </em>
          </h1>
          <div
            className="font-mono uppercase"
            style={{
              fontSize: "clamp(9px, 1.7cqmin, 11px)",
              letterSpacing: "0.22em",
              color: inkAt(0.44),
            }}
          >
            {caption} <span ref={capBarRef}>A</span>
          </div>
        </div>
      </article>
    </div>
  );
}
```

---

# Pond Glide

> A draggable stack of three cards over a slow theme-tinted swirl, with pixel-tile reveals.

Install: `npx @modus-ui/cli add pond-glide`

Three cards sit in a tilted stack inside slowly turning orbit rings, set on theme surfaces with serif quotes and a mono seal. Drag left or tap for the next card, drag right for the previous one, or use the arrow keys. Each image is overlaid with a moving grid of hidden tiles that your cursor wipes away, and each new card inks its quote in word by word. A WebGL swirl tinted from the background and primary, with cursor ripples, fills the scene. Default images are koi photos from Wikimedia Commons (CC BY-SA); pass your own through `cards`. It re-reads the theme when the mode or palette changes, pauses off screen and stays still when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add pond-glide
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pond-glide.tsx`.
3. Paste the code.

## Usage

```tsx
import { PondGlide } from "@/components/ui/pond-glide";

export default function Example() {
  return (
    <div className="relative h-[600px] w-full overflow-hidden">
      <PondGlide />
    </div>
  );
}
```

## Props

| Prop              | Type               | Default                                           | Description                                                                                                |
| :---------------- | :----------------- | :------------------------------------------------ | :--------------------------------------------------------------------------------------------------------- |
| `cards`           | `PondGlideCard[]`  | three pond studies (Shallows, Ripple, Still Pool) | The cards of the stack, front first (`name`, `seal`, `lines`, `image`, optional `panel`, `ink`, `accent`). |
| `hint`            | `string`           | `"drag · tap · let it drift"`                     | Hint under the stack.                                                                                      |
| `backgroundColor` | `string`           | `"hsl(var(--background))"`                        | Scene background colour.                                                                                   |
| `swirlColors`     | `[string, string]` | Theme background → primary-tinted muted           | Two colours of the swirling background shader.                                                             |

## Source

`components/ui/pond-glide.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Koi Studies (MIT, © 2026 Meng To).

import { useEffect, useRef, useState, type CSSProperties } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface PondGlideCard {
  /** Name shown in the lockup. */
  name: string;
  /** Characters inside the seal. */
  seal: string;
  /** Quote, one entry per line. */
  lines: string[];
  /** Painting or photo for the upper field. */
  image: string;
  /** Card panel colour; defaults to a theme surface. */
  panel?: string;
  /** Text colour; defaults to the theme foreground. */
  ink?: string;
  /** Wash colour behind the quote; defaults to the theme primary. */
  accent?: string;
}

export interface PondGlideProps {
  /** The three cards of the stack, front first. */
  cards?: PondGlideCard[];
  /** Hint under the stack. */
  hint?: string;
  /** Scene background colour; defaults to the theme background. */
  backgroundColor?: string;
  /** Two colours of the swirling background shader; default to theme background and a primary-tinted muted tone. */
  swirlColors?: [string, string];
  className?: string;
}

const commons = (path: string) => `https://upload.wikimedia.org/wikipedia/commons/thumb/${path}`;

const DEFAULT_CARDS: PondGlideCard[] = [
  {
    name: "Shallows",
    seal: "II",
    lines: ["Slow water", "keeps its", "own time."],
    image: commons("7/76/Shusui.JPG/960px-Shusui.JPG"),
  },
  {
    name: "Ripple",
    seal: "III",
    lines: ["Every turn", "leaves a quiet", "ring."],
    image: commons("8/85/Ginrinshiroutsuri.JPG/960px-Ginrinshiroutsuri.JPG"),
    panel: "hsl(var(--muted))",
  },
  {
    name: "Still Pool",
    seal: "I",
    lines: ["Drift first,", "decide", "later."],
    image: commons(
      "e/e3/Kohaku_nishikigoi_Konishi_Koi_Farm_Martin_Kammerer_ID7185-.jpg/960px-Kohaku_nishikigoi_Konishi_Koi_Farm_Martin_Kammerer_ID7185-.jpg",
    ),
  },
];

const WIDTH = 676;
const HEIGHT = 644;
const TILE = 10;
const COLUMNS = Math.ceil(WIDTH / TILE);
const ROWS = Math.ceil(HEIGHT / TILE);
const MASK_FPS = 30;
const FRAME_COUNT = 300;
const LOOP_MS = (FRAME_COUNT / MASK_FPS) * 1000;
const MAX_TRAIL_POINTS = 16;
const ENTRY_REVEAL_MS = 940;
const STACK_ROTATIONS = [0, 3.4, -5.2];
const STACK_SCALE_STEP = 0.018;
const STACK_X = [0, -4.2, 5.4];
const STACK_Y = [0, 3.2, 6.8];
const STACK_Z = ["0px", "-14cqw", "-28cqw"];
const SEAL_ROTATIONS = [-2.4, 1.8, -1.1];
const MAX_RIPPLES = 8;

const clamp = (value: number, minimum: number, maximum: number) =>
  Math.max(minimum, Math.min(maximum, value));
const hash = (x: number, y: number) => {
  const value = Math.sin(x * 127.1 + y * 311.7) * 43758.5453;
  return value - Math.floor(value);
};

const CSS = `
.koi-root{--field:hsl(var(--background));--paper:hsl(var(--foreground));--accent:hsl(var(--primary));container-type:size;display:grid;place-items:center;isolation:isolate;font-family:var(--font-body),ui-sans-serif,sans-serif}
.koi-root *{box-sizing:border-box}
.koi-root .koi-veil{position:absolute;inset:0;z-index:1;pointer-events:none;background:radial-gradient(circle at 50% 46%,transparent 16%,hsl(var(--background)/.18) 100%),radial-gradient(circle at 52% 42%,hsl(var(--primary)/.065),transparent 30rem),linear-gradient(hsl(var(--background)/.16),hsl(var(--background)/.22))}
.koi-root .koi-fluid{position:absolute;inset:0;z-index:0;width:100%;height:100%;display:block;pointer-events:none}
.koi-root .stack-scene{position:relative;z-index:2;width:min(26.40625cqw,46.94444cqh);aspect-ratio:676/1010;perspective:900px;container-type:inline-size;isolation:isolate}
.koi-root .orbital-field{position:absolute;left:50%;top:50%;z-index:0;width:220%;aspect-ratio:1;pointer-events:none;translate:-50% -50%}
.koi-root .orbit{position:absolute;left:50%;top:50%;width:var(--orbit-size);aspect-ratio:1;border-radius:50%;background:conic-gradient(from var(--orbit-angle),transparent 0 13%,hsl(var(--foreground)/.07) 19%,hsl(var(--foreground)/.26) 27%,hsl(var(--primary)/.24) 34%,transparent 45% 67%,hsl(var(--foreground)/.17) 76%,transparent 88%);opacity:var(--orbit-opacity);translate:-50% -50%;rotate:0deg;-webkit-mask:radial-gradient(farthest-side,transparent calc(100% - var(--orbit-line)),black calc(100% - var(--orbit-line) + .75px));mask:radial-gradient(farthest-side,transparent calc(100% - var(--orbit-line)),black calc(100% - var(--orbit-line) + .75px));animation:koi-orbit-spin var(--orbit-speed) linear infinite;will-change:rotate}
.koi-root .orbit-one{--orbit-size:58%;--orbit-line:1.5px;--orbit-angle:18deg;--orbit-opacity:.9;--orbit-speed:18s}
.koi-root .orbit-two{--orbit-size:79%;--orbit-line:1px;--orbit-angle:154deg;--orbit-opacity:.7;--orbit-speed:27s;animation-direction:reverse}
.koi-root .orbit-three{--orbit-size:100%;--orbit-line:1px;--orbit-angle:252deg;--orbit-opacity:.5;--orbit-speed:36s}
@keyframes koi-orbit-spin{to{rotate:360deg}}
.koi-root .stack{position:absolute;inset:0;z-index:1;transform-style:preserve-3d}
.koi-root .stack-shell{--stack-x:0%;--stack-y:0%;--stack-z:0px;position:absolute;inset:0;cursor:grab;outline:none;touch-action:none;overscroll-behavior:none;user-select:none;transform:translate3d(var(--stack-x),var(--stack-y),var(--stack-z));transform-style:preserve-3d;transition:transform 360ms cubic-bezier(.22,1,.36,1);will-change:transform}
.koi-root .drag-plane{--drag-x:0px;--drag-y:0px;--drag-turn:0deg;--tilt-x:0deg;--tilt-y:0deg;--release-blur:0px;position:absolute;inset:0;transform:translate3d(var(--drag-x),var(--drag-y),0) rotateX(var(--tilt-x)) rotateY(var(--tilt-y)) rotateZ(var(--drag-turn));filter:blur(var(--release-blur));transform-style:preserve-3d;transition:transform 300ms cubic-bezier(.22,1,.36,1),opacity 180ms ease,filter 140ms ease;will-change:transform,opacity,filter}
.koi-root .stack-shell.is-tracking .drag-plane{transition-duration:70ms;transition-timing-function:linear}
.koi-root .stack-shell.is-dragging{cursor:grabbing}
.koi-root .stack-shell.is-dragging .drag-plane{transition:none}
.koi-root .stack-shell.is-releasing .drag-plane{transition:transform 180ms cubic-bezier(.32,0,.2,1),opacity 90ms ease-out,filter 120ms ease-out}
.koi-root .artwork{--stack-rotation:0deg;--stack-scale:1;position:absolute;inset:0;overflow:hidden;container-type:inline-size;background:var(--panel);border-radius:clamp(20px,2cqw,30px);box-shadow:0 2.6cqw 6.5cqw hsl(0 0% 0%/.3),inset 0 0 0 1px hsl(var(--card)/.1);transform:rotateZ(var(--stack-rotation)) scale(var(--stack-scale));transform-origin:90% 90%;transition:transform 420ms cubic-bezier(.22,1,.36,1),box-shadow 220ms ease;will-change:transform;-webkit-user-drag:none}
.koi-root .artwork::after{content:"";position:absolute;inset:0;z-index:3;border-radius:inherit;padding:1px;background:linear-gradient(145deg,hsl(var(--card)/.22),hsl(var(--foreground)/.11) 42%,hsl(var(--card)/.035) 72%,hsl(var(--primary)/.19));pointer-events:none;-webkit-mask:linear-gradient(white 0 0) content-box,linear-gradient(white 0 0);-webkit-mask-composite:xor;mask-composite:exclude}
.koi-root .image-field{position:absolute;inset:0 0 auto;width:100%;height:63.76238%;display:block;background:var(--panel);pointer-events:none}
.koi-root .copy-panel{position:absolute;inset:63.76238% 0 0;background:var(--panel);color:var(--ink);box-shadow:inset 0 1px hsl(var(--foreground)/.09)}
.koi-root .copy-panel::before{content:"";position:absolute;inset:-10% 16% 5% -12%;background:radial-gradient(ellipse at 24% 48%,var(--accent-card),transparent 44%),radial-gradient(ellipse at 58% 62%,hsl(var(--foreground)/.16),transparent 52%);opacity:0;filter:blur(1.8cqw);mix-blend-mode:screen;pointer-events:none;transform-origin:18% 52%}
.koi-root .copy{position:absolute;top:23.5%;left:6.7%;margin:0;font-family:var(--font-heading),serif;font-size:9.05cqw;font-weight:400;line-height:.92;letter-spacing:-.055em;text-wrap:balance}
.koi-root .word-reveal{display:inline-block;padding:.12em .035em;margin:-.12em -.035em;vertical-align:bottom}
.koi-root .reveal-word{display:inline-block}
.koi-root .brand-lockup{position:absolute;right:5.62%;bottom:5.15cqw;display:flex;align-items:center;gap:1.45cqw;color:var(--ink)}
.koi-root .wordmark{font-size:2.05cqw;font-weight:700;line-height:1;letter-spacing:.16em;text-transform:uppercase;white-space:nowrap}
.koi-root .hanko{position:relative;display:grid;place-items:center;flex:0 0 auto;width:9.3cqw;height:9.3cqw;overflow:hidden;color:var(--panel);background:radial-gradient(circle at 13% 24%,hsl(var(--background)/.42) 0 .26cqw,transparent .35cqw),radial-gradient(circle at 78% 17%,hsl(var(--background)/.34) 0 .2cqw,transparent .3cqw),radial-gradient(circle at 68% 82%,hsl(var(--background)/.38) 0 .24cqw,transparent .34cqw),radial-gradient(circle at 27% 74%,hsl(var(--background)/.3) 0 .17cqw,transparent .27cqw),hsl(var(--primary));border-radius:1.05cqw .72cqw 1.18cqw .82cqw;box-shadow:inset 0 0 0 .28cqw hsl(var(--background)/.2),inset .32cqw -.25cqw .7cqw hsl(var(--background)/.16),0 .45cqw 1.25cqw hsl(0 0% 0%/.16);filter:saturate(.96)}
.koi-root .hanko::before{content:"";position:absolute;inset:.72cqw;border:.26cqw solid currentColor;border-radius:.42cqw .26cqw .52cqw .22cqw;opacity:.82}
.koi-root .hanko::after{content:"";position:absolute;inset:0;pointer-events:none;background:linear-gradient(103deg,transparent 0 42%,hsl(var(--background)/.14) 44% 46%,transparent 48%),radial-gradient(ellipse at 22% 13%,hsl(var(--background)/.22) 0 .42cqw,transparent .58cqw),radial-gradient(ellipse at 89% 62%,hsl(var(--background)/.22) 0 .45cqw,transparent .62cqw);mix-blend-mode:multiply}
.koi-root .hanko span{position:relative;z-index:1;writing-mode:vertical-rl;text-orientation:upright;font-family:var(--font-mono),ui-monospace,monospace;font-size:3.38cqw;font-weight:900;line-height:.92;letter-spacing:-.14em;transform:translateY(-.03em)}
.koi-root .stack-scene.reveal-enabled .reveal-word,.koi-root .stack-scene.reveal-enabled .reveal-lockup{opacity:0;filter:blur(.32em);translate:0 .72em}
.koi-root .stack-scene.reveal-enabled .reveal-lockup{scale:.92}
.koi-root .stack-scene.reveal-enabled .stack-shell.is-active .copy-panel::before{animation:koi-paper-wash-bloom 1.25s cubic-bezier(.16,1,.3,1) 140ms both}
.koi-root .stack-scene.reveal-enabled .stack-shell.is-active .reveal-word{animation:koi-word-ink-in 720ms cubic-bezier(.16,1,.3,1) both;animation-delay:calc(250ms + var(--reveal-index)*68ms);will-change:opacity,filter,translate}
.koi-root .stack-scene.reveal-enabled .stack-shell.is-active .reveal-lockup{animation:koi-lockup-ink-in 660ms cubic-bezier(.16,1,.3,1) both;animation-delay:calc(285ms + var(--reveal-index)*68ms);will-change:opacity,filter,translate,scale}
@keyframes koi-word-ink-in{from{opacity:0;filter:blur(.32em);translate:0 .72em}to{opacity:1;filter:blur(0);translate:0 0}}
@keyframes koi-lockup-ink-in{from{opacity:0;filter:blur(.32em);translate:0 .72em;scale:.92}to{opacity:1;filter:blur(0);translate:0 0;scale:1}}
@keyframes koi-paper-wash-bloom{0%{opacity:0;translate:-8% 5%;scale:.52}55%{opacity:.16}100%{opacity:.045;translate:1% 0;scale:1.12}}
.koi-root .interaction-hint{position:absolute;left:50%;top:calc(100% + clamp(28px,4.5cqh,52px));z-index:2;margin:0;color:hsl(var(--foreground)/.5);font-size:clamp(9px,.72cqw,12px);font-weight:500;letter-spacing:.18em;line-height:1;text-transform:uppercase;white-space:nowrap;transform:translateX(-50%);transition:opacity 260ms ease}
.koi-root .stack-scene[data-interacted="true"] .interaction-hint{opacity:0}
@container (max-aspect-ratio:3/4){.koi-root .stack-scene{width:min(72cqw,44cqh)}}
.koi-root[data-still] .stack-shell,.koi-root[data-still] .artwork,.koi-root[data-still] .interaction-hint{transition-duration:1ms}
.koi-root[data-still] .orbit{animation:none}
.koi-root[data-still] .orbit-one{rotate:22deg}.koi-root[data-still] .orbit-two{rotate:148deg}.koi-root[data-still] .orbit-three{rotate:276deg}
.koi-root[data-still] .stack-scene.reveal-enabled .reveal-word,.koi-root[data-still] .stack-scene.reveal-enabled .reveal-lockup{opacity:1;filter:none;translate:none;scale:1;animation:none}
.koi-root[data-still] .stack-scene.reveal-enabled .copy-panel::before{display:none}
`;

const VERT = `attribute vec2 p;void main(){gl_Position=vec4(p,0.,1.);}`;
// Swirl + multiplied fractal noise + cursor ripples + watercolour bleed, after the
// "Fluid Pastels" preset the original loads from the shaders.com runtime.
const FRAG = `precision highp float;
uniform vec2 uRes;uniform float uTime;uniform vec3 uA;uniform vec3 uB;uniform float uDark;
uniform vec4 uRipples[${MAX_RIPPLES}];
float h(vec2 p){return fract(sin(dot(p,vec2(127.1,311.7)))*43758.5453);}
float n(vec2 p){vec2 i=floor(p),f=fract(p);vec2 u=f*f*(3.-2.*f);
  return mix(mix(h(i),h(i+vec2(1,0)),u.x),mix(h(i+vec2(0,1)),h(i+vec2(1,1)),u.x),u.y);}
float fbm(vec2 p,int o){float v=0.,a=.5;for(int i=0;i<4;i++){if(i>=o)break;v+=a*n(p);p*=2.03;a*=.5;}return v;}
vec3 cineon(vec3 c){c=max(vec3(0.),c-.004);return pow((c*(6.2*c+.5))/(c*(6.2*c+1.7)+.06),vec3(2.2));}
void main(){
  vec2 uv=gl_FragCoord.xy/uRes;vec2 q=(gl_FragCoord.xy-.5*uRes)/min(uRes.x,uRes.y);
  for(int i=0;i<${MAX_RIPPLES};i++){vec4 r=uRipples[i];if(r.w<=0.)continue;
    vec2 d=q-r.xy;float dist=length(d);float age=r.z;
    float wave=sin(dist*38.-age*9.)*exp(-age*3.3)*exp(-dist*2.2)*r.w;
    q+=normalize(d+1e-4)*wave*.0174;}
  float t=uTime*.06;
  vec2 w=q*1.4;float ang=length(w)*2.2-t*1.6;
  w=mat2(cos(ang),-sin(ang),sin(ang),cos(ang))*w;
  float s=fbm(w*1.2+vec2(t,-t*.7),3)*.6+.5*sin(w.x*1.6+t)*.4;
  vec3 col=mix(uA,uB,clamp(s,0.,1.));
  float a=radians(-32.);vec2 nq=mat2(cos(a),-sin(a),sin(a),cos(a))*q;
  float fn=fbm(nq*2.2*3.+vec2(uTime*.57*.15,0.),1);
  fn=clamp((fn-.5)*(1.+.54)+.5,0.,1.);
  col=mix(col,col*fn,.34*mix(.35,1.,uDark));
  float bleed=fbm(q*6.+fbm(q*3.,2)*2.9,2);
  col*=1.-.07*(bleed-.5);
  col=mix(col,cineon(col*1.1),uDark);
  gl_FragColor=vec4(col,1.);
}`;

/** Resolves any CSS colour (layers painted bottom-up) to linear 0–1 RGB via a 1×1 canvas. */
function colourToVec(...layers: string[]): [number, number, number] {
  const ctx = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
  if (!ctx) return [0, 0, 0];
  for (const layer of layers) {
    ctx.fillStyle = layer;
    ctx.fillRect(0, 0, 1, 1);
  }
  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
  return [r / 255, g / 255, b / 255];
}

/** Bumps on light/dark or palette changes so colours re-resolve. */
function useThemeVersion() {
  const [version, setVersion] = useState(0);
  useEffect(() => {
    const observer = new MutationObserver(() => setVersion((v) => v + 1));
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return version;
}

/** Procedural stand-in for the original's baked 300-frame mask: drifting blobs of hidden tiles. */
function maskHidden(column: number, row: number, frame: number) {
  const phi = (frame / FRAME_COUNT) * Math.PI * 2;
  const x = column / COLUMNS;
  const y = row / ROWS;
  const v =
    Math.sin(x * 5.1 + Math.sin(phi) * 1.8 + y * 1.3) +
    Math.sin(y * 4.3 - Math.cos(phi) * 1.6 + x * 0.9) +
    0.7 * Math.sin((x + y) * 6.2 + phi * 2) +
    (hash(column, row + frame * 0.01) - 0.5) * 0.5;
  return v > 0.95;
}

export function PondGlide({
  cards: cardData = DEFAULT_CARDS,
  hint = "drag · tap · let it drift",
  backgroundColor = "hsl(var(--background))",
  swirlColors,
  className,
}: PondGlideProps) {
  const prefersReducedMotion = useReducedMotion();
  const themeVersion = useThemeVersion();
  const rootRef = useRef<HTMLDivElement>(null);
  const fluidRef = useRef<HTMLCanvasElement>(null);
  const sceneRef = useRef<HTMLElement>(null);
  const swirlKey = swirlColors?.join("|") ?? "";

  // Background shader.
  useEffect(() => {
    const root = rootRef.current;
    const canvas = fluidRef.current;
    const gl = canvas?.getContext("webgl", { antialias: false, premultipliedAlpha: false });
    if (!root || !canvas || !gl) return;
    const compile = (type: number, src: string) => {
      const s = gl.createShader(type)!;
      gl.shaderSource(s, src);
      gl.compileShader(s);
      return s;
    };
    const prog = gl.createProgram()!;
    const vs = compile(gl.VERTEX_SHADER, VERT);
    const fs = compile(gl.FRAGMENT_SHADER, FRAG);
    gl.attachShader(prog, vs);
    gl.attachShader(prog, fs);
    gl.linkProgram(prog);
    if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) return;
    gl.useProgram(prog);
    const buf = gl.createBuffer();
    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
    const loc = gl.getAttribLocation(prog, "p");
    gl.enableVertexAttribArray(loc);
    gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
    const uRes = gl.getUniformLocation(prog, "uRes");
    const uTime = gl.getUniformLocation(prog, "uTime");
    const uRipples = gl.getUniformLocation(prog, "uRipples");
    const token = (name: string) =>
      `hsl(${getComputedStyle(document.documentElement).getPropertyValue(name).trim()})`;
    const [a, b] = swirlKey ? swirlKey.split("|") : [];
    const swirlA = a ? colourToVec(a) : colourToVec(token("--background"));
    const swirlB = b
      ? colourToVec(b)
      : colourToVec(token("--muted"), token("--primary").replace(")", " / 0.14)"));
    gl.uniform3fv(gl.getUniformLocation(prog, "uA"), swirlA);
    const [r, g, bl] = colourToVec(token("--background"));
    gl.uniform1f(gl.getUniformLocation(prog, "uDark"), r + g + bl < 1.5 ? 1 : 0);
    gl.uniform3fv(gl.getUniformLocation(prog, "uB"), swirlB);

    const ripples: { x: number; y: number; born: number }[] = [];
    let lastRipple = 0;
    let time = 0;
    const draw = () => {
      const data = new Float32Array(MAX_RIPPLES * 4);
      ripples.forEach((r, i) => {
        const age = time - r.born;
        data.set([r.x, r.y, age, age < 2 ? 1 : 0], i * 4);
      });
      gl.uniform4fv(uRipples, data);
      gl.uniform1f(uTime, time);
      gl.uniform2f(uRes, canvas.width, canvas.height);
      gl.drawArrays(gl.TRIANGLES, 0, 3);
    };
    const resize = () => {
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      const { width, height } = root.getBoundingClientRect();
      canvas.width = Math.max(1, Math.round(width * dpr * 0.5));
      canvas.height = Math.max(1, Math.round(height * dpr * 0.5));
      gl.viewport(0, 0, canvas.width, canvas.height);
      draw();
    };
    const ro = new ResizeObserver(resize);
    ro.observe(root);
    resize();

    const onMove = (event: PointerEvent) => {
      if (prefersReducedMotion) return;
      const rect = root.getBoundingClientRect();
      const m = Math.min(rect.width, rect.height);
      const x = (event.clientX - rect.left - rect.width / 2) / m;
      const y = (rect.height / 2 - (event.clientY - rect.top)) / m;
      if (time - lastRipple < 0.06) return;
      lastRipple = time;
      ripples.unshift({ x, y, born: time });
      if (ripples.length > MAX_RIPPLES) ripples.length = MAX_RIPPLES;
    };
    window.addEventListener("pointermove", onMove);

    let raf = 0;
    let last = -1;
    let visible = true;
    const frame = (now: number) => {
      raf = requestAnimationFrame(frame);
      if (last >= 0) time += Math.min(0.05, (now - last) / 1000);
      last = now;
      draw();
    };
    const start = () => {
      if (prefersReducedMotion || raf || !visible || document.hidden) return;
      last = -1;
      raf = requestAnimationFrame(frame);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(root);
    const onVis = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVis);
    start();
    return () => {
      stop();
      io.disconnect();
      ro.disconnect();
      window.removeEventListener("pointermove", onMove);
      document.removeEventListener("visibilitychange", onVis);
      gl.deleteBuffer(buf);
      gl.deleteProgram(prog);
      gl.deleteShader(vs);
      gl.deleteShader(fs);
    };
  }, [swirlKey, prefersReducedMotion, themeVersion]);

  // Card stack.
  useEffect(() => {
    const root = rootRef.current;
    const scene = sceneRef.current;
    if (!root || !scene) return;
    const reduced = !!prefersReducedMotion;
    const finePointer = window.matchMedia("(hover: hover) and (pointer: fine)");
    const shellElements = Array.from(scene.querySelectorAll<HTMLDivElement>(".stack-shell"));
    const edgeNoise = new Float32Array(COLUMNS * ROWS);
    const entryOrder = new Float32Array(COLUMNS * ROWS);
    for (let row = 0; row < ROWS; row += 1) {
      for (let column = 0; column < COLUMNS; column += 1) {
        const cell = row * COLUMNS + column;
        const jitter = hash(column * 1.91 + 17, row * 2.17 + 31);
        edgeNoise[cell] = hash(column, row) - 0.5;
        entryOrder[cell] = clamp(
          (column / Math.max(1, COLUMNS - 1)) * 0.72 +
            jitter * 0.24 +
            Math.abs(row / Math.max(1, ROWS - 1) - 0.5) * 0.04 +
            Math.sin(row * 0.48) * 0.035,
          0,
          1,
        );
      }
    }

    type Card = {
      id: number;
      shell: HTMLDivElement;
      dragPlane: HTMLDivElement;
      artwork: HTMLElement;
      canvas: HTMLCanvasElement;
      context: CanvasRenderingContext2D;
      image: HTMLImageElement;
      imageReady: boolean;
      imageUsable: boolean;
      panelColor: string;
      entryRevealStart: number;
      pointer: {
        currentFrame: number;
        hasInteracted: boolean;
        lastMove: number;
        targetFrame: number;
        x: number;
        y: number;
      };
      trail: { life: number; radius: number; x: number; y: number }[];
      suppressClickUntil: number;
    };

    const cards: Card[] = shellElements.map((shell, id) => {
      const canvas = shell.querySelector<HTMLCanvasElement>(".image-field")!;
      const artwork = shell.querySelector<HTMLElement>(".artwork")!;
      return {
        id,
        shell,
        dragPlane: shell.querySelector<HTMLDivElement>(".drag-plane")!,
        artwork,
        canvas,
        context: canvas.getContext("2d", { alpha: false })!,
        image: new Image(),
        imageReady: false,
        imageUsable: false,
        panelColor: getComputedStyle(artwork).getPropertyValue("--panel").trim(),
        entryRevealStart: 0,
        pointer: {
          currentFrame: 0,
          hasInteracted: false,
          lastMove: 0,
          targetFrame: 0,
          x: 0.5,
          y: 0.5,
        },
        trail: [],
        suppressClickUntil: 0,
      };
    });
    if (!cards.length) return;

    let order = cards.map((c) => c.id).reverse();
    let activeDrag: {
      card: Card;
      pointerId: number;
      startX: number;
      startY: number;
      committedDirection: number;
      traveled: number;
    } | null = null;
    let animationFrame = 0;
    let initialRevealReady = false;
    let inView = true;
    let lastFrameTime = performance.now();
    const startTime = performance.now();
    let transitioning = false;
    const timers: number[] = [];

    const topCard = () => cards[order[order.length - 1]];
    const canAnimateField = () => finePointer.matches && !reduced;
    const shouldAnimateCanvas = () =>
      cards.every((c) => c.imageReady) && inView && !document.hidden && !reduced;

    const setShellTransform = (card: Card, x = 0, y = 0, tiltX = 0, tiltY = 0, turn = 0) => {
      const s = card.dragPlane.style;
      s.setProperty("--drag-x", `${x.toFixed(2)}px`);
      s.setProperty("--drag-y", `${y.toFixed(2)}px`);
      s.setProperty("--tilt-x", `${tiltX.toFixed(2)}deg`);
      s.setProperty("--tilt-y", `${tiltY.toFixed(2)}deg`);
      s.setProperty("--drag-turn", `${turn.toFixed(2)}deg`);
    };
    const resetShellTransform = (card: Card) => {
      setShellTransform(card);
      card.dragPlane.style.opacity = "";
      card.dragPlane.style.setProperty("--release-blur", "0px");
      card.shell.classList.remove("is-dragging", "is-tracking", "is-releasing");
    };

    const updateStack = () => {
      const top = topCard();
      for (let index = 0; index < order.length; index += 1) {
        const card = cards[order[index]];
        const depth = order.length - index - 1;
        const isTop = card === top;
        const wasActive = card.shell.classList.contains("is-active");
        card.shell.style.zIndex = String(index + 1);
        card.shell.style.pointerEvents = isTop ? "auto" : "none";
        card.shell.tabIndex = isTop ? 0 : -1;
        card.shell.setAttribute("aria-hidden", isTop ? "false" : "true");
        card.shell.classList.toggle("is-active", isTop);
        if (isTop && !wasActive) card.entryRevealStart = performance.now();
        card.shell.style.setProperty("--stack-x", `${STACK_X[depth] ?? 0}%`);
        card.shell.style.setProperty("--stack-y", `${STACK_Y[depth] ?? 0}%`);
        card.shell.style.setProperty("--stack-z", STACK_Z[depth] ?? "0px");
        card.artwork.style.setProperty("--stack-rotation", `${STACK_ROTATIONS[depth] ?? 0}deg`);
        card.artwork.style.setProperty("--stack-scale", String(1 - depth * STACK_SCALE_STEP));
        if (!isTop) resetShellTransform(card);
      }
    };

    const drawMediaAndGrid = (card: Card) => {
      if (!card.imageReady) return;
      const { context } = card;
      context.fillStyle = card.panelColor;
      context.fillRect(0, 0, WIDTH, HEIGHT);
      if (!card.imageUsable) return;
      const source = card.image;
      const sourceWidth = source.naturalWidth || WIDTH;
      const sourceHeight = source.naturalHeight || HEIGHT;
      const targetRatio = WIDTH / HEIGHT;
      let sourceX = 0;
      let sourceY = 0;
      let cropWidth = sourceWidth;
      let cropHeight = sourceHeight;
      if (sourceWidth / sourceHeight > targetRatio) {
        cropWidth = sourceHeight * targetRatio;
        sourceX = (sourceWidth - cropWidth) / 2;
      } else {
        cropHeight = sourceWidth / targetRatio;
        sourceY = (sourceHeight - cropHeight) / 2;
      }
      context.drawImage(source, sourceX, sourceY, cropWidth, cropHeight, 0, 0, WIDTH, HEIGHT);
      context.save();
      context.globalAlpha = 0.18;
      context.strokeStyle = card.panelColor;
      context.lineWidth = 0.9;
      context.beginPath();
      for (let x = TILE; x < WIDTH; x += TILE) {
        context.moveTo(x + 0.5, 0);
        context.lineTo(x + 0.5, HEIGHT);
      }
      for (let y = TILE; y < HEIGHT; y += TILE) {
        context.moveTo(0, y + 0.5);
        context.lineTo(WIDTH, y + 0.5);
      }
      context.stroke();
      context.restore();
    };

    const revealAtCell = (card: Card, cellX: number, cellY: number, cell: number) => {
      for (const point of card.trail) {
        const dx = cellX - point.x;
        const dy = cellY - point.y;
        const radius = point.radius * (0.32 + point.life * 0.68);
        if (Math.sqrt(dx * dx + dy * dy) < radius + edgeNoise[cell] * 0.034) return true;
      }
      return false;
    };

    const drawMaskedFrame = (card: Card, frame: number, isTop: boolean, now: number) => {
      if (!card.imageReady) return;
      drawMediaAndGrid(card);
      const revealRaw = reduced ? 1 : clamp((now - card.entryRevealStart) / ENTRY_REVEAL_MS, 0, 1);
      const revealProgress = revealRaw * revealRaw * (3 - 2 * revealRaw);
      const ctx = card.context;
      ctx.save();
      ctx.fillStyle = card.panelColor;
      for (let row = 0; row < ROWS; row += 1) {
        for (let column = 0; column < COLUMNS; column += 1) {
          const cell = row * COLUMNS + column;
          const hidden = maskHidden(column, row, frame);
          const entryHidden = isTop && revealProgress < 1 && entryOrder[cell] > revealProgress;
          const pointerRevealed =
            isTop &&
            card.trail.length > 0 &&
            revealAtCell(card, (column + 0.5) / COLUMNS, (row + 0.5) / ROWS, cell);
          if ((hidden || entryHidden) && !pointerRevealed) {
            ctx.globalAlpha = entryHidden ? 1 : 0.82;
            ctx.fillRect(column * TILE, row * TILE, TILE, TILE);
          }
        }
      }
      ctx.restore();
    };

    const render = (now: number) => {
      animationFrame = 0;
      const deltaTime = Math.min(48, Math.max(0, now - lastFrameTime));
      const top = topCard();
      lastFrameTime = now;
      for (const card of cards) {
        for (let index = card.trail.length - 1; index >= 0; index -= 1) {
          card.trail[index].life -= deltaTime / 760;
          if (card.trail[index].life <= 0) card.trail.splice(index, 1);
        }
        const phaseOffset = card.id * LOOP_MS * 0.19;
        const autoFrame = Math.floor(
          (((now - startTime + phaseOffset) % LOOP_MS) * MASK_FPS) / 1000,
        );
        const usesPointer = card === top && card.pointer.hasInteracted;
        const response = 1 - Math.pow(0.72, deltaTime / 16.667);
        if (usesPointer)
          card.pointer.currentFrame +=
            (card.pointer.targetFrame - card.pointer.currentFrame) * response;
        else card.pointer.currentFrame = autoFrame;
        drawMaskedFrame(
          card,
          Math.round(card.pointer.currentFrame) % FRAME_COUNT,
          card === top,
          now,
        );
      }
      if (shouldAnimateCanvas()) animationFrame = requestAnimationFrame(render);
    };

    const syncAnimation = () => {
      if (!shouldAnimateCanvas()) {
        if (animationFrame) cancelAnimationFrame(animationFrame);
        animationFrame = 0;
        const now = performance.now();
        for (const card of cards) drawMaskedFrame(card, 0, card === topCard(), now);
        return;
      }
      if (!animationFrame) {
        lastFrameTime = performance.now();
        animationFrame = requestAnimationFrame(render);
      }
    };

    const startInitialPixelReveal = () => {
      if (initialRevealReady || !cards.every((c) => c.imageReady)) return;
      initialRevealReady = true;
      topCard().entryRevealStart = performance.now();
    };

    const updatePointerField = (event: PointerEvent) => {
      if (!canAnimateField() || (event.pointerType && event.pointerType !== "mouse")) return;
      const card = topCard();
      const now = performance.now();
      const rect = card.canvas.getBoundingClientRect();
      const x = (event.clientX - rect.left) / rect.width;
      const y = (event.clientY - rect.top) / rect.height;
      const elapsed = Math.max(8, now - card.pointer.lastMove);
      const distance = Math.hypot(x - card.pointer.x, y - card.pointer.y);
      const speed = clamp((distance * 1000) / elapsed / 2.2, 0, 1);
      const rootRect = root.getBoundingClientRect();
      const globalX = clamp((event.clientX - rootRect.left) / rootRect.width, 0, 1);
      const globalY = clamp((event.clientY - rootRect.top) / rootRect.height, 0, 1);
      const phase = clamp(globalX * 0.72 + (1 - globalY) * 0.28, 0, 1);
      card.pointer.hasInteracted = true;
      card.pointer.lastMove = now;
      card.pointer.targetFrame = phase * (FRAME_COUNT - 1);
      card.pointer.x = x;
      card.pointer.y = y;
      if (x > -0.3 && x < 1.3 && y > -0.3 && y < 1.3) {
        card.trail.unshift({ life: 1, radius: 0.105 + speed * 0.115, x, y });
        if (card.trail.length > MAX_TRAIL_POINTS) card.trail.length = MAX_TRAIL_POINTS;
      }
      syncAnimation();
    };

    const updatePointerTilt = (event: PointerEvent) => {
      if (!finePointer.matches || reduced || activeDrag || transitioning) return;
      const card = topCard();
      const rect = scene.getBoundingClientRect();
      const x = (event.clientX - rect.left) / rect.width;
      const y = (event.clientY - rect.top) / rect.height;
      if (!(x > -0.22 && x < 1.22 && y > -0.18 && y < 1.18)) {
        card.shell.classList.remove("is-tracking");
        setShellTransform(card);
        return;
      }
      card.shell.classList.add("is-tracking");
      setShellTransform(
        card,
        0,
        0,
        clamp((0.5 - y) * 10, -4.75, 4.75),
        clamp((x - 0.5) * 10, -4.75, 4.75),
        0,
      );
    };

    const markInteracted = () => {
      scene.dataset.interacted = "true";
    };
    const getDragCommitThreshold = () => clamp(scene.getBoundingClientRect().width * 0.18, 52, 88);
    const getCommittedDirection = (x: number, y: number, threshold: number) =>
      Math.abs(x) >= threshold && Math.abs(x) >= Math.abs(y) * 0.75 ? Math.sign(x) : 0;

    const later = (fn: () => void, ms: number) => {
      timers.push(window.setTimeout(fn, ms));
    };

    const sendToBack = (card: Card, vectorX = 1, vectorY = 0) => {
      if (transitioning || card !== topCard()) return;
      markInteracted();
      transitioning = true;
      const magnitude = Math.max(1, Math.hypot(vectorX, vectorY));
      const directionX = vectorX / magnitude;
      const directionY = vectorY / magnitude;
      const distance = Math.max(190, scene.getBoundingClientRect().width * 0.66);
      const duration = reduced ? 0 : 180;
      const incoming = cards[order[order.length - 2]];
      card.shell.classList.remove("is-dragging", "is-tracking");
      card.shell.classList.add("is-releasing");
      setShellTransform(
        card,
        directionX * distance,
        directionY * distance * 0.58,
        -directionY * 7,
        directionX * 8,
        directionX * 9,
      );
      card.dragPlane.style.opacity = duration ? "0" : "";
      card.dragPlane.style.setProperty("--release-blur", duration ? "16px" : "0px");
      later(() => {
        const hadFocus = document.activeElement === card.shell;
        order = [card.id, ...order.filter((id) => id !== card.id)];
        for (const el of [card.shell, card.dragPlane, incoming.shell, incoming.dragPlane])
          el.style.transition = "none";
        resetShellTransform(card);
        updateStack();
        void incoming.shell.offsetWidth;
        for (const el of [card.shell, card.dragPlane, incoming.shell, incoming.dragPlane])
          el.style.transition = "";
        transitioning = false;
        if (hadFocus) incoming.shell.focus({ preventScroll: true });
        syncAnimation();
      }, duration);
    };

    const bringPreviousToFront = () => {
      if (transitioning) return;
      markInteracted();
      transitioning = true;
      const outgoing = topCard();
      const incoming = cards[order[0]];
      const hadFocus = document.activeElement === outgoing.shell;
      const distance = Math.max(190, scene.getBoundingClientRect().width * 0.66);
      const duration = reduced ? 0 : 360;
      incoming.shell.style.transition = "none";
      incoming.dragPlane.style.transition = "none";
      setShellTransform(incoming, -distance, 0, 0, -6, -8);
      incoming.dragPlane.style.opacity = duration ? "0.12" : "";
      order = [...order.slice(1), incoming.id];
      updateStack();
      void incoming.shell.offsetWidth;
      incoming.shell.style.transition = "";
      incoming.dragPlane.style.transition = "";
      const reveal = () => {
        setShellTransform(incoming);
        incoming.dragPlane.style.opacity = "";
      };
      const finish = () => {
        transitioning = false;
        if (hadFocus) incoming.shell.focus({ preventScroll: true });
        syncAnimation();
      };
      if (duration) {
        later(reveal, 18);
        later(finish, duration);
      } else {
        reveal();
        finish();
      }
    };

    const cancelDrag = (event?: PointerEvent) => {
      if (
        !activeDrag ||
        (event?.pointerId !== undefined && event.pointerId !== activeDrag.pointerId)
      )
        return;
      const { card, pointerId } = activeDrag;
      activeDrag = null;
      try {
        if (card.shell.hasPointerCapture?.(pointerId)) card.shell.releasePointerCapture(pointerId);
      } catch {
        // capture may already be gone
      }
      card.shell.classList.remove("is-dragging");
      setShellTransform(card);
    };

    const handlePointerDown = (card: Card, event: PointerEvent) => {
      if (card !== topCard() || transitioning || (event.button !== undefined && event.button !== 0))
        return;
      activeDrag = {
        card,
        pointerId: event.pointerId,
        startX: event.clientX,
        startY: event.clientY,
        committedDirection: 0,
        traveled: 0,
      };
      card.shell.classList.remove("is-tracking");
      card.shell.classList.add("is-dragging");
      card.shell.focus({ preventScroll: true });
      try {
        card.shell.setPointerCapture?.(event.pointerId);
      } catch {
        cancelDrag(event);
        return;
      }
      event.preventDefault();
    };

    const handleDragPointerMove = (card: Card, event: PointerEvent) => {
      if (!activeDrag || activeDrag.card !== card || event.pointerId !== activeDrag.pointerId)
        return;
      const x = event.clientX - activeDrag.startX;
      const y = event.clientY - activeDrag.startY;
      const width = Math.max(1, scene.getBoundingClientRect().width);
      const committedDirection = getCommittedDirection(x, y, getDragCommitThreshold());
      activeDrag.traveled = Math.max(activeDrag.traveled, Math.hypot(x, y));
      if (committedDirection) activeDrag.committedDirection = committedDirection;
      setShellTransform(
        card,
        x,
        y,
        clamp((-y / width) * 6, -6, 6),
        clamp((x / width) * 7, -7, 7),
        clamp((x / width) * 11, -12, 12),
      );
      markInteracted();
      event.preventDefault();
    };

    const handlePointerUp = (card: Card, event: PointerEvent) => {
      if (!activeDrag || activeDrag.card !== card || event.pointerId !== activeDrag.pointerId)
        return;
      const { committedDirection: latched, startX, startY, traveled } = activeDrag;
      const x = event.clientX - startX;
      const y = event.clientY - startY;
      const committedDirection = getCommittedDirection(x, y, getDragCommitThreshold()) || latched;
      const isTap = traveled <= 3 && Math.hypot(x, y) <= 3;
      activeDrag = null;
      try {
        if (card.shell.hasPointerCapture?.(event.pointerId))
          card.shell.releasePointerCapture(event.pointerId);
      } catch {
        // already released
      }
      card.shell.classList.remove("is-dragging");
      card.suppressClickUntil = performance.now() + 360;
      if (committedDirection) {
        if (committedDirection < 0) sendToBack(card, -1, 0);
        else bringPreviousToFront();
      } else if (isTap) sendToBack(card, x || 1, y);
      else setShellTransform(card);
      event.preventDefault();
    };

    const onKeyDown = (event: KeyboardEvent) => {
      if (event.metaKey || event.ctrlKey || event.altKey) return;
      if (event.key === "ArrowLeft") {
        event.preventDefault();
        bringPreviousToFront();
      } else if (event.key === "ArrowRight") {
        event.preventDefault();
        sendToBack(topCard(), 1, 0);
      }
    };
    const onWindowMove = (event: PointerEvent) => {
      if (activeDrag) handleDragPointerMove(activeDrag.card, event);
      updatePointerField(event);
      updatePointerTilt(event);
    };
    const onWindowUp = (event: PointerEvent) => {
      if (activeDrag) handlePointerUp(activeDrag.card, event);
    };
    const onWindowCancel = (event: PointerEvent) => cancelDrag(event);
    const onMouseOut = (event: MouseEvent) => {
      if (!event.relatedTarget && !activeDrag) {
        const card = topCard();
        card.shell.classList.remove("is-tracking");
        setShellTransform(card);
      }
    };
    const onBlur = () => {
      cancelDrag();
      syncAnimation();
    };

    const cleanups: (() => void)[] = [];
    for (const card of cards) {
      card.context.imageSmoothingEnabled = true;
      const onLoad = () => {
        card.imageReady = true;
        card.imageUsable = true;
        startInitialPixelReveal();
        syncAnimation();
      };
      const onError = () => {
        card.imageReady = true;
        startInitialPixelReveal();
        syncAnimation();
      };
      card.image.crossOrigin = "anonymous";
      card.image.addEventListener("load", onLoad, { once: true });
      card.image.addEventListener("error", onError, { once: true });
      const down = (e: PointerEvent) => handlePointerDown(card, e);
      const lost = (e: PointerEvent) => cancelDrag(e);
      const click = () => {
        if (performance.now() >= card.suppressClickUntil) sendToBack(card, 1, 0);
      };
      const key = (e: KeyboardEvent) => {
        if (e.key === "Enter" || e.key === " ") {
          e.preventDefault();
          sendToBack(card, 1, 0);
        }
      };
      card.shell.addEventListener("pointerdown", down);
      card.shell.addEventListener("lostpointercapture", lost);
      card.shell.addEventListener("click", click);
      card.shell.addEventListener("keydown", key);
      cleanups.push(() => {
        card.image.removeEventListener("load", onLoad);
        card.image.removeEventListener("error", onError);
        card.shell.removeEventListener("pointerdown", down);
        card.shell.removeEventListener("lostpointercapture", lost);
        card.shell.removeEventListener("click", click);
        card.shell.removeEventListener("keydown", key);
      });
      card.image.src = cardData[card.id]?.image ?? "";
    }

    scene.classList.add("reveal-enabled");
    updateStack();
    root.addEventListener("keydown", onKeyDown);
    window.addEventListener("pointermove", onWindowMove);
    window.addEventListener("pointerup", onWindowUp);
    window.addEventListener("pointercancel", onWindowCancel);
    window.addEventListener("mouseout", onMouseOut);
    window.addEventListener("blur", onBlur);
    document.addEventListener("visibilitychange", syncAnimation);
    finePointer.addEventListener?.("change", syncAnimation);
    const observer = new IntersectionObserver(
      (entries) => {
        inView = entries[0]?.isIntersecting ?? true;
        syncAnimation();
      },
      { rootMargin: "100px" },
    );
    observer.observe(scene);

    return () => {
      if (animationFrame) cancelAnimationFrame(animationFrame);
      timers.forEach(clearTimeout);
      cleanups.forEach((fn) => fn());
      observer.disconnect();
      root.removeEventListener("keydown", onKeyDown);
      window.removeEventListener("pointermove", onWindowMove);
      window.removeEventListener("pointerup", onWindowUp);
      window.removeEventListener("pointercancel", onWindowCancel);
      window.removeEventListener("mouseout", onMouseOut);
      window.removeEventListener("blur", onBlur);
      document.removeEventListener("visibilitychange", syncAnimation);
      finePointer.removeEventListener?.("change", syncAnimation);
      scene.classList.remove("reveal-enabled");
      for (const card of cards) {
        card.shell.classList.remove("is-active");
        resetShellTransform(card);
      }
    };
  }, [cardData, prefersReducedMotion]);

  return (
    <div
      ref={rootRef}
      data-still={prefersReducedMotion ? "" : undefined}
      className={cn("koi-root absolute inset-0 overflow-hidden", className)}
      style={{
        background: `radial-gradient(circle at 52% 42%, hsl(var(--primary)/0.055), transparent 27rem), radial-gradient(circle at 45% 55%, hsl(var(--foreground)/0.035), transparent 40rem), ${backgroundColor}`,
      }}
    >
      <style dangerouslySetInnerHTML={{ __html: CSS }} />
      <canvas
        ref={fluidRef}
        className="koi-fluid"
        aria-hidden="true"
        style={{ background: backgroundColor }}
      />
      <div className="koi-veil" aria-hidden="true" />
      <main
        ref={sceneRef}
        className="stack-scene"
        aria-label="Interactive stack of koi studies"
        data-interacted="false"
      >
        <div className="orbital-field" aria-hidden="true">
          <span className="orbit orbit-one" />
          <span className="orbit orbit-two" />
          <span className="orbit orbit-three" />
        </div>
        <div
          className="stack"
          role="group"
          aria-label="Drag left for the next card or right for the previous card. Tap for next. Use the Left and Right Arrow keys."
        >
          {cardData.map((card, id) => {
            let wordIndex = 0;
            return (
              <div
                key={id}
                className="stack-shell"
                role="button"
                tabIndex={id === 0 ? 0 : -1}
                aria-label={`${card.name}: ${card.lines.join(" ")} Drag left for next or right for previous.`}
              >
                <div className="drag-plane">
                  <article
                    className="artwork"
                    style={
                      {
                        "--panel": card.panel ?? "hsl(var(--card))",
                        "--ink": card.ink ?? "hsl(var(--foreground))",
                        "--accent-card": card.accent ?? "hsl(var(--primary) / 0.35)",
                      } as CSSProperties
                    }
                  >
                    <canvas
                      className="image-field"
                      width={WIDTH}
                      height={HEIGHT}
                      aria-hidden="true"
                    />
                    <section className="copy-panel" aria-label={card.lines.join(" ")}>
                      <p className="copy" aria-hidden="true">
                        {card.lines.map((line, li) => (
                          <span key={li}>
                            {li > 0 && <br />}
                            {line.split(" ").map((word, wi) => (
                              <span key={wi}>
                                {wi > 0 && " "}
                                <span className="word-reveal">
                                  <span
                                    className="reveal-word"
                                    style={{ "--reveal-index": wordIndex++ } as CSSProperties}
                                  >
                                    {word}
                                  </span>
                                </span>
                              </span>
                            ))}
                          </span>
                        ))}
                      </p>
                      <div className="brand-lockup" aria-label={card.name}>
                        <span
                          className="wordmark reveal-lockup"
                          style={{ "--reveal-index": wordIndex } as CSSProperties}
                        >
                          {card.name}
                        </span>
                        <span
                          className="hanko reveal-lockup"
                          style={
                            {
                              "--reveal-index": wordIndex + 1,
                              transform: `rotate(${SEAL_ROTATIONS[id % SEAL_ROTATIONS.length]}deg)`,
                            } as CSSProperties
                          }
                          aria-hidden="true"
                        >
                          <span lang="ja">{card.seal}</span>
                        </span>
                      </div>
                    </section>
                  </article>
                </div>
              </div>
            );
          })}
        </div>
        <p className="interaction-hint" aria-hidden="true">
          {hint}
        </p>
      </main>
    </div>
  );
}
```

---

# Herbarium Study

> An ink-and-paper botanical plate in Three.js where line-drawn ferns and seed heads grow while seed fluff drifts past.

Install: `npx @modus-ui/cli add herbarium-study`

A Three.js scene drawn like a botanical study: ferns unfurl stroke by stroke from three clumps on a plate of contour rings, seed heads open on tall stalks and seed fluff drifts across on the wind. It enters with a slow ink-bleed reveal and a calm orbiting camera that leans toward the pointer. Every line takes its colour from the theme — ink on paper in light mode, pale strokes under a dusk glow in dark mode — and follows palette changes live. It fills its positioned parent, pauses when off screen or when the tab is hidden, and renders a still, fully grown frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add herbarium-study
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/herbarium-study.tsx`.
4. Paste the code.

## Usage

```tsx
import { HerbariumStudy } from "@/components/ui/herbarium-study";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <HerbariumStudy />
    </div>
  );
}
```

## Props

| Prop     | Type     | Default                                                                                  | Description                                      |
| :------- | :------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------- |
| `fronds` | `number` | `18`                                                                                     | Number of fern fronds drawn around the plate.    |
| `speed`  | `number` | `1`                                                                                      | Multiplier for the orbit, growth and seed drift. |
| `label`  | `string` | `"Ink-drawn ferns and seed heads growing on a paper plate while seed fluff drifts past"` | Accessible label for the scene.                  |

## Source

`components/ui/herbarium-study.tsx`

```tsx
"use client";
import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface HerbariumStudyProps {
  /** Number of fern fronds drawn around the plate. */
  fronds?: number;
  /** Multiplier for the orbit, growth and seed-drift speed. */
  speed?: number;
  /** Accessible label for the scene. */
  label?: string;
  className?: string;
}

type Ink = {
  ink: THREE.Color;
  ghost: THREE.Color;
  accent: THREE.Color;
  paper: THREE.Color;
  dark: boolean;
};

/* Theme tokens are bare HSL channels ("30 8% 12%"), so parse them by hand. */
function token(style: CSSStyleDeclaration, name: string) {
  const [h = 0, s = 0, l = 0] = style
    .getPropertyValue(name)
    .trim()
    .split(/[\s,/]+/)
    .map((part) => parseFloat(part));
  return new THREE.Color().setHSL(h / 360, s / 100, l / 100, THREE.SRGBColorSpace);
}

function readInk(): Ink {
  const style = getComputedStyle(document.documentElement);
  const paper = token(style, "--background");
  const hsl = { h: 0, s: 0, l: 0 };
  paper.getHSL(hsl);
  return {
    paper,
    ink: token(style, "--foreground"),
    ghost: token(style, "--muted-foreground"),
    accent: token(style, "--primary"),
    dark: hsl.l < 0.5,
  };
}

/* A seeded random so every mount draws the same plate. */
function rng(seed: number) {
  return () => {
    seed = (seed * 16807) % 2147483647;
    return (seed - 1) / 2147483646;
  };
}

/* One fern frond as line segments, ordered base → tip so a growing draw range unfurls it. */
function frond(
  rand: () => number,
  base: THREE.Vector3,
  angle: number,
  height: number,
  out: number[],
) {
  const dir = new THREE.Vector3(Math.cos(angle), 0, Math.sin(angle));
  const side = new THREE.Vector3(-dir.z, 0, dir.x);
  const lean = 0.45 + rand() * 0.35;
  const at = (t: number) =>
    dir
      .clone()
      .multiplyScalar(height * lean * t * t + 0.15)
      .setY(height * t * (1 - 0.32 * t))
      .add(new THREE.Vector3(base.x, 0, base.z));
  const steps = 20;
  for (let i = 0; i < steps; i++) {
    const t0 = i / steps;
    const t1 = (i + 1) / steps;
    const a = at(t0);
    const b = at(t1);
    out.push(a.x, a.y, a.z, b.x, b.y, b.z);
    if (i < 3) continue;
    const tangent = b.clone().sub(a).normalize();
    const len = height * 0.15 * Math.sin(Math.PI * t1) * (1 - 0.35 * t1);
    for (const s of [-1, 1]) {
      // each pinna: a short curved stroke with a few leaflets
      let p = b.clone();
      const reach = side.clone().multiplyScalar(s).addScaledVector(tangent, 0.55).normalize();
      for (let k = 0; k < 3; k++) {
        const q = p
          .clone()
          .addScaledVector(reach, len / 3)
          .addScaledVector(tangent, len * 0.06 * k);
        out.push(p.x, p.y, p.z, q.x, q.y, q.z);
        const leaf = q.clone().addScaledVector(tangent, len * 0.22);
        out.push(q.x, q.y, q.z, leaf.x, leaf.y, leaf.z);
        p = q;
      }
    }
  }
}

/* A seed head: a curved stalk, then a sphere of fine rays. */
function seedHead(rand: () => number, x: number, z: number, height: number, out: number[]) {
  const bend = (rand() - 0.5) * 0.5;
  let prev = new THREE.Vector3(x, 0, z);
  for (let i = 1; i <= 12; i++) {
    const t = i / 12;
    const next = new THREE.Vector3(x + bend * t * t, height * t, z + bend * 0.4 * t * t);
    out.push(prev.x, prev.y, prev.z, next.x, next.y, next.z);
    prev = next;
  }
  const rays = 64;
  for (let i = 0; i < rays; i++) {
    const y = 1 - (2 * (i + 0.5)) / rays;
    const r = Math.sqrt(1 - y * y);
    const phi = i * 2.399963;
    const ray = new THREE.Vector3(Math.cos(phi) * r, y, Math.sin(phi) * r).multiplyScalar(0.42);
    const tip = prev.clone().add(ray);
    out.push(prev.x, prev.y, prev.z, tip.x, tip.y, tip.z);
  }
}

function lines(points: number[], material: THREE.LineBasicMaterial) {
  const geometry = new THREE.BufferGeometry();
  geometry.setAttribute("position", new THREE.Float32BufferAttribute(points, 3));
  return new THREE.LineSegments(geometry, material);
}

function fluffTexture() {
  const size = 64;
  const canvas = document.createElement("canvas");
  canvas.width = canvas.height = size;
  const ctx = canvas.getContext("2d")!;
  ctx.strokeStyle = "white";
  ctx.lineWidth = 1.4;
  ctx.translate(size / 2, size / 2);
  for (let i = 0; i < 12; i++) {
    ctx.rotate((Math.PI * 2) / 12);
    ctx.beginPath();
    ctx.moveTo(0, 0);
    ctx.lineTo(0, -size * 0.42);
    ctx.stroke();
  }
  const texture = new THREE.CanvasTexture(canvas);
  texture.colorSpace = THREE.SRGBColorSpace;
  return texture;
}

function mountHerbarium(
  host: HTMLDivElement,
  canvas: HTMLCanvasElement,
  opts: { fronds: number; speed: number; still: boolean },
) {
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
  const scene = new THREE.Scene();
  scene.fog = new THREE.Fog(new THREE.Color(), 9, 22);
  const camera = new THREE.PerspectiveCamera(34, 1, 0.1, 60);

  const inkMat = new THREE.LineBasicMaterial({ transparent: true, opacity: 0.9 });
  const ghostMat = new THREE.LineBasicMaterial({ transparent: true, opacity: 0.45 });
  const accentMat = new THREE.LineBasicMaterial({ transparent: true, opacity: 0.95 });
  const fluffMat = new THREE.PointsMaterial({
    size: 0.16,
    map: fluffTexture(),
    transparent: true,
    depthWrite: false,
    opacity: 0.85,
  });

  const rand = rng(7);
  // three clumps; y carries each clump's base frond height
  const CLUMPS = [
    new THREE.Vector3(0, 2.6, 0),
    new THREE.Vector3(-2.6, 1.7, 1.4),
    new THREE.Vector3(2.2, 1.4, -2),
  ];
  const plants: THREE.LineSegments[] = [];
  for (let i = 0; i < opts.fronds; i++) {
    const pts: number[] = [];
    const clump = CLUMPS[i % CLUMPS.length]!;
    const ring = Math.floor(i / CLUMPS.length) % 2;
    const angle = rand() * Math.PI * 2;
    frond(rand, clump, angle, clump.y + rand() * 1.2, pts);
    plants.push(lines(pts, ring % 2 ? ghostMat : inkMat));
  }
  for (let i = 0; i < 5; i++) {
    const pts: number[] = [];
    const a = i * 1.37 + 0.6;
    const r = 1.6 + rand() * 1.6;
    seedHead(rand, Math.cos(a) * r, Math.sin(a) * r, 1.6 + rand() * 1.6, pts);
    plants.push(lines(pts, accentMat));
  }
  plants.forEach((plant) => scene.add(plant));

  // the plate: concentric contour rings and a few hatch strokes on the ground
  const ground: number[] = [];
  for (let r = 1; r <= 7; r += 0.75) {
    for (let i = 0; i < 96; i++) {
      if ((i + Math.round(r * 4)) % 9 === 0) continue;
      const a0 = (i / 96) * Math.PI * 2;
      const a1 = ((i + 1) / 96) * Math.PI * 2;
      ground.push(Math.cos(a0) * r, 0, Math.sin(a0) * r, Math.cos(a1) * r, 0, Math.sin(a1) * r);
    }
  }
  const groundLines = lines(ground, ghostMat);
  scene.add(groundLines);

  // drifting seed fluff
  const COUNT = 220;
  const fluffPos = new Float32Array(COUNT * 3);
  const fluffSeed = new Float32Array(COUNT);
  for (let i = 0; i < COUNT; i++) {
    fluffPos[i * 3] = (rand() - 0.5) * 14;
    fluffPos[i * 3 + 1] = rand() * 6;
    fluffPos[i * 3 + 2] = (rand() - 0.5) * 14;
    fluffSeed[i] = rand() * 100;
  }
  const fluffGeo = new THREE.BufferGeometry();
  fluffGeo.setAttribute("position", new THREE.BufferAttribute(fluffPos, 3));
  const fluff = new THREE.Points(fluffGeo, fluffMat);
  scene.add(fluff);

  const applyInk = () => {
    const ink = readInk();
    inkMat.color.copy(ink.ink);
    ghostMat.color.copy(ink.ghost);
    accentMat.color.copy(ink.accent);
    fluffMat.color.copy(ink.dark ? ink.ink : ink.ghost);
    (scene.fog as THREE.Fog).color.copy(ink.paper);
    ghostMat.opacity = ink.dark ? 0.35 : 0.5;
  };
  applyInk();

  const pointer = { x: 0, y: 0, sx: 0, sy: 0 };
  const onPointer = (event: PointerEvent) => {
    const box = host.getBoundingClientRect();
    pointer.x = ((event.clientX - box.left) / box.width) * 2 - 1;
    pointer.y = ((event.clientY - box.top) / box.height) * 2 - 1;
  };
  host.addEventListener("pointermove", onPointer);

  const GROW = 4.2;
  let elapsed = opts.still ? 60 : 0;
  let last = 0;
  let raf = 0;
  let active = true;

  const frame = (dt: number) => {
    elapsed += dt * opts.speed;
    const grow = Math.min(1, elapsed / GROW);
    plants.forEach((plant, i) => {
      const local = THREE.MathUtils.clamp(grow * 1.4 - (i % 7) * 0.05, 0, 1);
      const eased = 1 - Math.pow(1 - local, 3);
      const total = plant.geometry.getAttribute("position").count;
      plant.geometry.setDrawRange(0, Math.floor((total * eased) / 2) * 2);
    });
    // ink-bleed reveal: a soft round mask spreading from the centre of the plate
    const bleed = Math.min(1, elapsed / 2.6);
    const mask = `radial-gradient(circle at 50% 58%, black ${bleed * 95}%, transparent ${bleed * 95 + 18}%)`;
    canvas.style.maskImage = canvas.style.webkitMaskImage = bleed >= 1 ? "" : mask;

    if (!opts.still) {
      for (let i = 0; i < COUNT; i++) {
        const s = fluffSeed[i]!;
        fluffPos[i * 3] = fluffPos[i * 3]! + (0.18 + Math.sin(elapsed * 0.4 + s) * 0.12) * dt;
        fluffPos[i * 3 + 1] = fluffPos[i * 3 + 1]! + (0.08 + Math.sin(elapsed + s) * 0.05) * dt;
        if (fluffPos[i * 3]! > 7 || fluffPos[i * 3 + 1]! > 6.5) {
          fluffPos[i * 3] = -7;
          fluffPos[i * 3 + 1] = Math.random() * 2;
        }
      }
      fluffGeo.attributes.position!.needsUpdate = true;
    }

    pointer.sx += (pointer.x - pointer.sx) * 0.05;
    pointer.sy += (pointer.y - pointer.sy) * 0.05;
    const orbit = elapsed * 0.06 + 0.9 + pointer.sx * 0.25;
    camera.position.set(Math.cos(orbit) * 9.5, 3.4 - pointer.sy * 0.6, Math.sin(orbit) * 9.5);
    camera.lookAt(0, 1.4, 0);
    renderer.render(scene, camera);
  };

  const loop = (now: number) => {
    raf = requestAnimationFrame(loop);
    const dt = last ? Math.min(0.05, (now - last) / 1000) : 0;
    last = now;
    frame(dt);
  };
  const setActive = (next: boolean) => {
    active = next;
    cancelAnimationFrame(raf);
    raf = 0;
    last = 0;
    if (active && !opts.still) raf = requestAnimationFrame(loop);
  };

  const resize = () => {
    const w = host.clientWidth || 1;
    const h = host.clientHeight || 1;
    renderer.setSize(w, h, false);
    camera.aspect = w / h;
    camera.fov = w / h < 1 ? 48 : 34;
    camera.updateProjectionMatrix();
    frame(0);
  };
  resize();
  setActive(true);

  const themeObserver = new MutationObserver(() => {
    applyInk();
    frame(0);
  });
  themeObserver.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["class", "data-theme", "style"],
  });

  return {
    resize,
    setActive,
    dispose() {
      cancelAnimationFrame(raf);
      themeObserver.disconnect();
      host.removeEventListener("pointermove", onPointer);
      scene.traverse((object) => {
        if (object instanceof THREE.LineSegments || object instanceof THREE.Points) {
          object.geometry.dispose();
        }
      });
      fluffMat.map?.dispose();
      [inkMat, ghostMat, accentMat, fluffMat].forEach((material) => material.dispose());
      renderer.dispose();
    },
  };
}

export function HerbariumStudy({
  fronds = 18,
  speed = 1,
  label = "Ink-drawn ferns and seed heads growing on a paper plate while seed fluff drifts past",
  className,
}: HerbariumStudyProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    const study = mountHerbarium(host, canvas, { fronds, speed, still: !!prefersReducedMotion });

    let visible = true;
    const sync = () => study.setActive(visible && !document.hidden);
    const resizeObserver = new ResizeObserver(() => study.resize());
    resizeObserver.observe(host);
    const intersectionObserver = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      sync();
    });
    intersectionObserver.observe(host);
    document.addEventListener("visibilitychange", sync);
    return () => {
      resizeObserver.disconnect();
      intersectionObserver.disconnect();
      document.removeEventListener("visibilitychange", sync);
      study.dispose();
    };
  }, [fronds, speed, prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      role="img"
      aria-label={label}
      className={cn(
        "absolute inset-0 overflow-hidden",
        "bg-[radial-gradient(70%_55%_at_70%_18%,hsl(var(--muted))_0%,hsl(var(--background))_70%)]",
        "dark:bg-[radial-gradient(60%_50%_at_72%_16%,hsl(var(--primary)/0.22)_0%,hsl(var(--background))_70%)]",
        className,
      )}
    >
      <canvas ref={canvasRef} className="absolute inset-0 h-full w-full" />
      <span className="pointer-events-none absolute bottom-4 left-5 font-mono text-[10px] uppercase tracking-[0.2em] text-muted-foreground">
        Plate IV · Polypodiales
      </span>
    </div>
  );
}
```

---

# Winter Pagoda

> A five-tier pagoda on a snowy hillside among pines, in paper-white daylight or under a pale winter moon, coloured from your theme.

Install: `npx @modus-ui/cli add winter-pagoda`

A Three.js scene with a five-tier pagoda whose flared roofs carry snow, stone lanterns along a stepping-stone path, stands of snow-laden pines, faceted ridges fading into haze and steady snowfall. Every colour comes from the theme tokens: in light mode it is a daylight snowfield on the paper background with ink-toned pines, in dark mode a night under a pale moon with the windows and lanterns lit in the primary hue. It re-reads the tokens when the theme or palette changes. The camera drifts along a slow arc across the path and leans with the pointer. It fills its positioned parent, caps the pixel ratio, pauses when off screen or when the tab is hidden, and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add winter-pagoda
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/winter-pagoda.tsx`.
4. Paste the code.

## Usage

```tsx
import { WinterPagoda } from "@/components/ui/winter-pagoda";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <WinterPagoda />
    </div>
  );
}
```

## Props

| Prop              | Type     | Default | Description                                                                     |
| :---------------- | :------- | :------ | :------------------------------------------------------------------------------ |
| `snow`            | `number` | `0.6`   | Snowfall density, from `0` (light flurries) to `1` (heavy).                     |
| `backgroundColor` | `string` | —       | Colour shown behind the canvas while loading. Defaults to the theme background. |
| `className`       | `string` | —       | Additional CSS classes.                                                         |

## Source

`components/ui/winter-pagoda.tsx`

```tsx
"use client";
import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface WinterPagodaProps {
  /** Snowfall density, 0 to 1. */
  snow?: number;
  /** Colour shown behind the canvas while the scene loads. Defaults to the theme background. */
  backgroundColor?: string;
  className?: string;
}

const DPR_CAP = 1.75;

/* Theme tokens are bare HSL channels ("222 47% 11%"). */
function token(name: string) {
  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();
  const [h = 0, s = 0, l = 0] = raw.split(/[\s,/]+/).map((v) => parseFloat(v));
  return new THREE.Color().setHSL(h / 360, s / 100, l / 100, THREE.SRGBColorSpace);
}

/* The whole look comes from the theme: daylight on paper in light mode,
   a pale winter moon over the background in dark mode. */
function readTheme() {
  const bg = token("--background");
  const fg = token("--foreground");
  const primary = token("--primary");
  const muted = token("--muted");
  const hsl = { h: 0, s: 0, l: 0 };
  bg.getHSL(hsl, THREE.SRGBColorSpace);
  const dark = hsl.l < 0.5;
  /* mix in sRGB so ramps read the way the tokens do, not brightened by linear blending */
  const mix = (a: THREE.Color, b: THREE.Color, t: number) => {
    const x = a.getRGB({ r: 0, g: 0, b: 0 }, THREE.SRGBColorSpace);
    const y = b.getRGB({ r: 0, g: 0, b: 0 }, THREE.SRGBColorSpace);
    return new THREE.Color().setRGB(
      x.r + (y.r - x.r) * t,
      x.g + (y.g - x.g) * t,
      x.b + (y.b - x.b) * t,
      THREE.SRGBColorSpace,
    );
  };
  primary.getHSL(hsl, THREE.SRGBColorSpace);
  /* a saturated, readable accent even when the primary is near-black */
  const glow = new THREE.Color().setHSL(
    hsl.h,
    Math.max(hsl.s, 0.55),
    dark ? Math.max(hsl.l, 0.62) : 0.55,
    THREE.SRGBColorSpace,
  );
  if (dark) {
    return {
      dark,
      skyTop: mix(bg, glow, 0.06).multiplyScalar(0.75),
      skyLow: mix(bg, fg, 0.06),
      fog: mix(bg, fg, 0.05),
      snow: mix(bg, fg, 0.52),
      ink: mix(bg, glow, 0.12).multiplyScalar(0.8),
      wood: mix(bg, glow, 0.35),
      stone: mix(muted, fg, 0.15),
      disc: mix(fg, glow, 0.08),
      glow,
      window: glow.clone(),
      flake: mix(fg, bg, 0.1),
      sun: mix(fg, glow, 0.1),
      sunI: 0.9,
      hemiI: 0.8,
      lampI: 7,
    };
  }
  return {
    dark,
    skyTop: mix(bg, primary, 0.06),
    skyLow: mix(bg, glow, 0.1).lerp(new THREE.Color(1, 1, 1), 0.3),
    fog: mix(bg, muted, 0.35),
    snow: mix(bg, new THREE.Color(1, 1, 1), 0.6),
    ink: mix(fg, muted, 0.45),
    wood: mix(fg, glow, 0.4),
    stone: mix(muted, fg, 0.22),
    disc: mix(bg, glow, 0.18).lerp(new THREE.Color(1, 1, 1), 0.4),
    glow,
    window: mix(glow, bg, 0.35),
    flake: mix(fg, muted, 0.55),
    sun: new THREE.Color(1, 1, 1),
    sunI: 2.1,
    hemiI: 1.3,
    lampI: 0,
  };
}

function rand(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;
  };
}

/* gentle rolling snowfield that climbs into the slope behind the pagoda */
function groundHeight(x: number, z: number) {
  const rise = Math.max(0, -z - 8) * 0.28;
  return (
    Math.sin(x * 0.18) * 0.5 +
    Math.cos(z * 0.21 + x * 0.07) * 0.45 +
    Math.sin(x * 0.53 + z * 0.37) * 0.12 +
    rise -
    Math.exp(-(x * x + z * z) / 40) * 0.6
  );
}

function createWinterPagoda(canvas: HTMLCanvasElement, reduced: boolean, density: number) {
  const renderer = new THREE.WebGLRenderer({
    canvas,
    antialias: true,
    powerPreference: "high-performance",
  });
  renderer.outputColorSpace = THREE.SRGBColorSpace;
  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(34, 1, 0.3, 400);
  const disposables: { dispose(): void }[] = [];
  const track = <T extends { dispose(): void }>(d: T) => (disposables.push(d), d);

  const mats = {
    snow: track(new THREE.MeshLambertMaterial()),
    ink: track(new THREE.MeshLambertMaterial()),
    wood: track(new THREE.MeshLambertMaterial()),
    stone: track(new THREE.MeshLambertMaterial()),
    window: track(new THREE.MeshBasicMaterial()),
    lamp: track(new THREE.MeshBasicMaterial()),
  };
  const fog = new THREE.Fog(0, 18, 120);
  scene.fog = fog;
  const hemi = new THREE.HemisphereLight();
  const sun = new THREE.DirectionalLight();
  sun.position.set(-30, 26, 18);
  scene.add(hemi, sun);

  /* sky dome: vertical gradient, ignores fog */
  const skyMat = track(
    new THREE.ShaderMaterial({
      side: THREE.BackSide,
      depthWrite: false,
      uniforms: { uTop: { value: new THREE.Color() }, uLow: { value: new THREE.Color() } },
      vertexShader: `varying float vY; void main(){ vY = normalize(position).y; gl_Position = projectionMatrix * modelViewMatrix * vec4(position,1.); }`,
      fragmentShader: `uniform vec3 uTop; uniform vec3 uLow; varying float vY;
        void main(){ gl_FragColor = vec4(mix(uLow, uTop, smoothstep(-0.05, 0.55, vY)), 1.);
          #include <colorspace_fragment>
        }`,
    }),
  );
  scene.add(new THREE.Mesh(track(new THREE.SphereGeometry(300, 32, 16)), skyMat));

  /* sun or moon disc with a soft halo */
  const haloCanvas = document.createElement("canvas");
  haloCanvas.width = haloCanvas.height = 128;
  const hc = haloCanvas.getContext("2d")!;
  const grad = hc.createRadialGradient(64, 64, 0, 64, 64, 64);
  grad.addColorStop(0, "rgba(255,255,255,1)");
  grad.addColorStop(0.16, "rgba(255,255,255,1)");
  grad.addColorStop(0.2, "rgba(255,255,255,0.35)");
  grad.addColorStop(1, "rgba(255,255,255,0)");
  hc.fillStyle = grad;
  hc.fillRect(0, 0, 128, 128);
  const discMat = track(
    new THREE.SpriteMaterial({
      map: track(new THREE.CanvasTexture(haloCanvas)),
      fog: false,
      depthWrite: false,
      transparent: true,
    }),
  );
  const disc = new THREE.Sprite(discMat);
  disc.scale.setScalar(70);
  disc.position.set(-95, 62, -230);
  scene.add(disc);

  /* snowfield */
  const groundGeo = track(new THREE.PlaneGeometry(220, 220, 110, 110));
  groundGeo.rotateX(-Math.PI / 2);
  const gp = groundGeo.attributes.position as THREE.BufferAttribute;
  for (let i = 0; i < gp.count; i++) gp.setY(i, groundHeight(gp.getX(i), gp.getZ(i)));
  groundGeo.computeVertexNormals();
  scene.add(new THREE.Mesh(groundGeo, mats.snow));

  /* far ridges: faceted peaks fading into the haze */
  const r = rand(7);
  const peakGeo = track(new THREE.ConeGeometry(1, 1, 7, 1));
  const capGeo = track(new THREE.ConeGeometry(1, 1, 7, 1));
  for (let i = 0; i < 9; i++) {
    const w = 26 + r() * 30;
    const h = 22 + r() * 30;
    const x = -150 + i * 38 + r() * 12;
    const z = -150 - r() * 50;
    const peak = new THREE.Mesh(peakGeo, mats.ink);
    peak.scale.set(w, h, w * 0.7);
    peak.position.set(x, h / 2 - 4, z);
    peak.rotation.y = r() * 3;
    const cap = new THREE.Mesh(capGeo, mats.snow);
    cap.scale.set(w * 0.42, h * 0.42, w * 0.3);
    cap.position.set(x, h - 4 - h * 0.21 + 0.4, z);
    cap.rotation.y = peak.rotation.y;
    scene.add(peak, cap);
  }

  /* the pagoda: five diminishing tiers with flared, snow-laden roofs */
  const pagoda = new THREE.Group();
  const box = track(new THREE.BoxGeometry(1, 1, 1));
  const roofGeo = track(new THREE.ConeGeometry(1, 1, 4, 1, true));
  const roofCapGeo = track(new THREE.ConeGeometry(1, 1, 4, 1));
  const rail = track(new THREE.CylinderGeometry(1, 1, 1, 8));
  const base = new THREE.Mesh(box, mats.stone);
  base.scale.set(7.4, 1, 7.4);
  base.position.y = 0.5;
  pagoda.add(base);
  let y = 1;
  for (let t = 0; t < 5; t++) {
    const s = 4.6 - t * 0.62;
    const h = t === 0 ? 2.6 : 1.55;
    const body = new THREE.Mesh(box, mats.wood);
    body.scale.set(s, h, s);
    body.position.y = y + h / 2;
    pagoda.add(body);
    for (const side of [0, 1, 2, 3]) {
      const win = new THREE.Mesh(box, mats.window);
      const a = (side * Math.PI) / 2;
      win.scale.set(s * 0.42, h * 0.38, 0.05);
      win.position.set(Math.sin(a) * (s / 2 + 0.02), y + h * 0.5, Math.cos(a) * (s / 2 + 0.02));
      win.rotation.y = a;
      pagoda.add(win);
    }
    y += h;
    const rw = s * 1.06 + 1.5;
    const roof = new THREE.Mesh(roofGeo, mats.ink);
    roof.scale.set(rw, 1.15, rw);
    roof.rotation.y = Math.PI / 4;
    roof.position.y = y + 0.42;
    const snowCap = new THREE.Mesh(roofCapGeo, mats.snow);
    snowCap.scale.set(rw * 0.86, 0.9, rw * 0.86);
    snowCap.rotation.y = Math.PI / 4;
    snowCap.position.y = y + 0.56;
    pagoda.add(roof, snowCap);
    y += 0.35;
  }
  const spire = new THREE.Mesh(rail, mats.wood);
  spire.scale.set(0.09, 3.2, 0.09);
  spire.position.y = y + 1.8;
  pagoda.add(spire);
  for (let k = 0; k < 6; k++) {
    const ring = new THREE.Mesh(rail, mats.wood);
    ring.scale.set(0.3 - k * 0.025, 0.08, 0.3 - k * 0.025);
    ring.position.y = y + 0.9 + k * 0.38;
    pagoda.add(ring);
  }
  pagoda.position.set(0, groundHeight(0, 0) - 0.4, 0);
  scene.add(pagoda);

  /* stone lanterns lining the path up from the camera */
  const lampLights: THREE.PointLight[] = [];
  const lampSpots: [number, number][] = [
    [-2.6, 8],
    [2.6, 8],
    [-2.8, 15],
    [2.8, 15],
    [-3, 22],
  ];
  for (const [x, z] of lampSpots) {
    const g = new THREE.Group();
    const foot = new THREE.Mesh(rail, mats.stone);
    foot.scale.set(0.38, 0.3, 0.38);
    foot.position.y = 0.15;
    const post = new THREE.Mesh(rail, mats.stone);
    post.scale.set(0.14, 1.1, 0.14);
    post.position.y = 0.85;
    const lamp = new THREE.Mesh(box, mats.lamp);
    lamp.scale.set(0.42, 0.4, 0.42);
    lamp.position.y = 1.6;
    const hat = new THREE.Mesh(roofCapGeo, mats.stone);
    hat.scale.set(0.62, 0.38, 0.62);
    hat.rotation.y = Math.PI / 4;
    hat.position.y = 1.99;
    const hatSnow = new THREE.Mesh(roofCapGeo, mats.snow);
    hatSnow.scale.set(0.5, 0.3, 0.5);
    hatSnow.rotation.y = Math.PI / 4;
    hatSnow.position.y = 2.08;
    g.add(foot, post, lamp, hat, hatSnow);
    g.position.set(x, groundHeight(x, z) - 0.05, z);
    scene.add(g);
    if (Math.abs(z - 15) < 1) {
      const light = new THREE.PointLight(undefined, 0, 9, 1.6);
      light.position.set(x, g.position.y + 1.6, z);
      lampLights.push(light);
      scene.add(light);
    }
  }
  /* stepping stones */
  const stepGeo = track(new THREE.CylinderGeometry(0.55, 0.62, 0.14, 9));
  for (let z = 4.6; z < 26; z += 1.5) {
    const x = Math.sin(z * 0.35) * 0.4;
    const step = new THREE.Mesh(stepGeo, mats.stone);
    step.position.set(x, groundHeight(x, z) + 0.02, z);
    step.rotation.y = z;
    scene.add(step);
  }

  /* pine stands: three stacked cones with snow on their shoulders */
  const pr = rand(19);
  const pines: { x: number; z: number; s: number }[] = [];
  while (pines.length < 150) {
    const x = (pr() - 0.5) * 150;
    const z = 10 - pr() * 120;
    if (Math.abs(x) < 9 && z > -10) continue;
    if (Math.abs(x) < 5) continue;
    /* keep the sightline from the camera arc to the pagoda clear */
    if (z > -6 && x < 4 && x > -22 + z * 0.1) continue;
    pines.push({ x, z, s: 0.7 + pr() * 1.1 });
  }
  pines.push({ x: -24, z: 16, s: 2.4 }, { x: 9, z: 9, s: 2 });
  const needleGeo = track(new THREE.ConeGeometry(1, 1, 7));
  const pineSnowGeo = track(new THREE.ConeGeometry(1, 1, 7));
  const needles = new THREE.InstancedMesh(needleGeo, mats.ink, pines.length * 3);
  const pineSnow = new THREE.InstancedMesh(pineSnowGeo, mats.snow, pines.length * 3);
  const m = new THREE.Matrix4();
  const q = new THREE.Quaternion();
  const v = new THREE.Vector3();
  const sc = new THREE.Vector3();
  pines.forEach((p, i) => {
    const gy = groundHeight(p.x, p.z);
    for (let k = 0; k < 3; k++) {
      const w = (1.5 - k * 0.38) * p.s;
      const h = (2.4 - k * 0.4) * p.s;
      const cy = gy + (0.9 + k * 1.25) * p.s + h / 2;
      m.compose(v.set(p.x, cy, p.z), q, sc.set(w, h, w));
      needles.setMatrixAt(i * 3 + k, m);
      m.compose(v.set(p.x, cy + h * 0.2, p.z), q, sc.set(w * 0.62, h * 0.6, w * 0.62));
      pineSnow.setMatrixAt(i * 3 + k, m);
    }
  });
  scene.add(needles, pineSnow);

  /* snowfall: points drifting on a looping column around the camera */
  const COUNT = Math.round(600 + 2400 * Math.max(0, Math.min(1, density)));
  const flakeGeo = track(new THREE.BufferGeometry());
  const fp = new Float32Array(COUNT * 3);
  const fs = new Float32Array(COUNT);
  const fr = rand(3);
  for (let i = 0; i < COUNT; i++) {
    fp[i * 3] = (fr() - 0.5) * 60;
    fp[i * 3 + 1] = fr() * 26;
    fp[i * 3 + 2] = fr() * 50 - 20;
    fs[i] = 0.4 + fr();
  }
  flakeGeo.setAttribute("position", new THREE.BufferAttribute(fp, 3));
  flakeGeo.setAttribute("aSeed", new THREE.BufferAttribute(fs, 1));
  const flakeMat = track(
    new THREE.ShaderMaterial({
      transparent: true,
      depthWrite: false,
      uniforms: {
        uT: { value: 0 },
        uPx: { value: 600 },
        uColor: { value: new THREE.Color() },
        uAlpha: { value: 1 },
      },
      vertexShader: `uniform float uT; uniform float uPx; attribute float aSeed; varying float vA;
        void main(){
          vec3 p = position;
          p.y = mod(p.y - uT * (0.9 + aSeed * 0.8), 26.0) - 1.0;
          p.x += sin(uT * 0.6 * aSeed + p.y * 0.4 + aSeed * 9.0) * 0.6;
          vec4 mv = modelViewMatrix * vec4(p, 1.0);
          gl_PointSize = uPx * 0.035 * aSeed / -mv.z;
          vA = smoothstep(60.0, 8.0, -mv.z);
          gl_Position = projectionMatrix * mv;
        }`,
      fragmentShader: `uniform vec3 uColor; uniform float uAlpha; varying float vA;
        void main(){ float d = length(gl_PointCoord - 0.5); if (d > 0.5) discard;
          gl_FragColor = vec4(uColor, smoothstep(0.5, 0.15, d) * vA * uAlpha);
          #include <colorspace_fragment>
        }`,
    }),
  );
  scene.add(new THREE.Points(flakeGeo, flakeMat));

  function applyTheme() {
    const th = readTheme();
    skyMat.uniforms.uTop.value.copy(th.skyTop);
    skyMat.uniforms.uLow.value.copy(th.skyLow);
    fog.color.copy(th.fog);
    fog.near = th.dark ? 14 : 22;
    fog.far = th.dark ? 105 : 150;
    mats.snow.color.copy(th.snow);
    mats.ink.color.copy(th.ink);
    mats.wood.color.copy(th.wood);
    mats.stone.color.copy(th.stone);
    mats.window.color.copy(th.window);
    mats.lamp.color.copy(th.dark ? th.glow : th.stone.clone().lerp(th.window, 0.3));
    discMat.color.copy(th.disc);
    disc.scale.setScalar(th.dark ? 46 : 90);
    disc.position.y = th.dark ? 70 : 34;
    hemi.color.copy(th.dark ? th.disc : th.skyTop.clone().lerp(new THREE.Color(1, 1, 1), 0.5));
    hemi.groundColor.copy(th.dark ? th.ink : th.snow);
    hemi.intensity = th.hemiI;
    sun.color.copy(th.sun);
    sun.intensity = th.sunI;
    sun.position.set(th.dark ? -30 : 40, th.dark ? 30 : 14, th.dark ? -10 : -30);
    lampLights.forEach((l) => {
      l.color.copy(th.glow);
      l.intensity = th.lampI;
    });
    flakeMat.uniforms.uColor.value.copy(th.flake);
    flakeMat.uniforms.uAlpha.value = th.dark ? 0.85 : 0.6;
  }
  applyTheme();

  /* camera: a slow arc across the path, framing the pagoda off-centre */
  const pointer = { x: 0, y: 0, tx: 0, ty: 0 };
  let clock = 0;
  let prev = 0;
  function placeCamera() {
    const a = -0.42 + Math.sin(clock * 0.045) * 0.16;
    const rad = 30 - Math.sin(clock * 0.03) * 2;
    camera.position.set(
      Math.sin(a) * rad + pointer.x * 0.9,
      3.2 + pointer.y * 0.5,
      Math.cos(a) * rad,
    );
    const wide = camera.aspect > 1.2;
    camera.lookAt(wide ? -4.5 : 0, 6.8, 0);
  }

  function resize() {
    const w = Math.max(1, canvas.clientWidth);
    const h = Math.max(1, canvas.clientHeight);
    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, DPR_CAP));
    renderer.setSize(w, h, false);
    camera.aspect = w / h;
    camera.fov = camera.aspect < 1 ? 50 : 34;
    camera.updateProjectionMatrix();
    flakeMat.uniforms.uPx.value = h * renderer.getPixelRatio();
  }

  function render(now: number) {
    const dt = reduced ? 0 : Math.min(prev ? (now - prev) / 1000 : 0, 0.05);
    prev = now;
    clock += dt;
    pointer.x += (pointer.tx - pointer.x) * (1 - Math.exp(-2.5 * dt));
    pointer.y += (pointer.ty - pointer.y) * (1 - Math.exp(-2.5 * dt));
    flakeMat.uniforms.uT.value = reduced ? 7 : clock;
    placeCamera();
    renderer.render(scene, camera);
  }

  return {
    render,
    resize,
    applyTheme,
    setPointer(x: number, y: number) {
      pointer.tx = x;
      pointer.ty = y;
    },
    dispose() {
      disposables.forEach((d) => d.dispose());
      needles.dispose();
      pineSnow.dispose();
      renderer.dispose();
    },
  };
}

export function WinterPagoda({ snow = 0.6, backgroundColor, className }: WinterPagodaProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [state, setState] = useState<"loading" | "ready" | "unavailable">("loading");
  const [errorMessage, setErrorMessage] = useState("");

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    const reduced = !!prefersReducedMotion;
    let scene: ReturnType<typeof createWinterPagoda>;
    try {
      scene = createWinterPagoda(canvas, reduced, snow);
    } catch (error) {
      setErrorMessage(error instanceof Error ? error.message : "Unknown renderer error");
      setState("unavailable");
      return;
    }
    let frame = 0;
    let visible = true;
    let disposed = false;
    const schedule = () => {
      if (!disposed && visible && !document.hidden && !frame) frame = requestAnimationFrame(tick);
    };
    const tick = (time: number) => {
      frame = 0;
      scene.render(time);
      setState("ready");
      if (!reduced) schedule();
    };
    const resize = () => {
      scene.resize();
      schedule();
    };
    const onPointer = (event: PointerEvent) => {
      const b = canvas.getBoundingClientRect();
      scene.setPointer(
        ((event.clientX - b.left) / Math.max(1, b.width)) * 2 - 1,
        1 - ((event.clientY - b.top) / Math.max(1, b.height)) * 2,
      );
      schedule();
    };
    const clearPointer = () => {
      scene.setPointer(0, 0);
      schedule();
    };
    const onVisibility = () => {
      if (document.hidden && frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      } else schedule();
    };
    const themeObserver = new MutationObserver(() => {
      scene.applyTheme();
      schedule();
    });
    themeObserver.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(host);
    const intersectionObserver = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      if (!visible && frame) {
        cancelAnimationFrame(frame);
        frame = 0;
      } else schedule();
    });
    intersectionObserver.observe(host);
    canvas.addEventListener("pointermove", onPointer, { passive: true });
    canvas.addEventListener("pointerleave", clearPointer, { passive: true });
    document.addEventListener("visibilitychange", onVisibility);
    resize();
    return () => {
      disposed = true;
      if (frame) cancelAnimationFrame(frame);
      themeObserver.disconnect();
      resizeObserver.disconnect();
      intersectionObserver.disconnect();
      canvas.removeEventListener("pointermove", onPointer);
      canvas.removeEventListener("pointerleave", clearPointer);
      document.removeEventListener("visibilitychange", onVisibility);
      scene.dispose();
    };
  }, [prefersReducedMotion, snow]);

  return (
    <div
      ref={hostRef}
      data-state={state}
      className={cn("absolute inset-0 overflow-hidden bg-background", className)}
      style={backgroundColor ? { background: backgroundColor } : undefined}
    >
      <canvas
        ref={canvasRef}
        aria-label="A five-tier pagoda among snowy pines, under falling snow"
        className="block h-full w-full touch-none transition-opacity duration-700"
        style={{ opacity: state === "ready" ? 1 : 0 }}
      />
      {state === "unavailable" ? (
        <p
          role="status"
          className="absolute inset-0 m-0 grid place-items-center bg-background font-mono text-xs uppercase tracking-widest text-muted-foreground"
        >
          WebGL is unavailable: {errorMessage || "unsupported context"}.
        </p>
      ) : null}
    </div>
  );
}
```

---

# Survey Relief

> A procedural topographic relief model turning on a survey table, with contour bands in your theme colours.

Install: `npx @modus-ui/cli add survey-relief`

A Three.js relief model, carved from a seeded ridged-noise height field and cut into a slab whose walls show the strata. Contour lines are drawn in the shader every few metres, with a heavier index line every fifth band, and the model turns slowly under a low raking light. In light mode it is a paper model in studio daylight, inked in `--foreground`; in dark mode the contours glow in `--primary` over a night table. All colours come from the theme tokens and follow palette and mode changes. Drag to turn the model. The scene fills its positioned parent, pauses when off screen and shows a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add survey-relief
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/survey-relief.tsx`.
4. Paste the code.

## Usage

```tsx
import { SurveyRelief } from "@/components/ui/survey-relief";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SurveyRelief variant="nocturne" seed={12} />
    </div>
  );
}
```

## Props

| Prop        | Type                               | Default                      | Description                                                   |
| :---------- | :--------------------------------- | :--------------------------- | :------------------------------------------------------------ |
| `variant`   | `"auto" \| "studio" \| "nocturne"` | `"auto"`                     | Lighting state; `auto` follows the site's light or dark mode. |
| `seed`      | `number`                           | `7`                          | Seed of the procedural terrain.                               |
| `label`     | `string`                           | `"Topographic relief model"` | Accessible label for the scene.                               |
| `className` | `string`                           | -                            | Extra classes for the host element.                           |

## Source

`components/ui/survey-relief.tsx`

```tsx
"use client";

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

/** `auto` follows the site's light/dark mode; `studio` and `nocturne` force one look. */
export type SurveyReliefVariant = "auto" | "studio" | "nocturne";

interface SurveyReliefProps {
  /** Lighting state: `studio` (paper model in daylight), `nocturne` (glowing contours) or `auto`. */
  variant?: SurveyReliefVariant;
  /** Seed of the procedural terrain; each value carves a different relief. */
  seed?: number;
  label?: string;
  className?: string;
}

const SIZE = 6;
const SEGMENTS = 220;
const BASE = -0.42;
const SEA = 0.06;
const BANDS = 0.09;

/* ---- deterministic value noise and the terrain height field ---- */
function makeHeight(seed: number) {
  let a = (seed * 2654435761) >>> 0;
  const rand = () => {
    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;
  };
  const P = new Float32Array(256 * 256);
  for (let i = 0; i < P.length; i++) P[i] = rand();
  const at = (x: number, y: number) => P[(y & 255) * 256 + (x & 255)];
  const noise = (x: number, y: number) => {
    const xi = Math.floor(x),
      yi = Math.floor(y);
    const fx = x - xi,
      fy = y - yi;
    const u = fx * fx * (3 - 2 * fx),
      v = fy * fy * (3 - 2 * fy);
    const a0 = at(xi, yi) + (at(xi + 1, yi) - at(xi, yi)) * u;
    const a1 = at(xi, yi + 1) + (at(xi + 1, yi + 1) - at(xi, yi + 1)) * u;
    return a0 + (a1 - a0) * v;
  };
  const ox = rand() * 100,
    oy = rand() * 100;
  return (x: number, z: number) => {
    const nx = x / SIZE + ox,
      nz = z / SIZE + oy;
    let ridge = 0,
      amp = 0.6,
      freq = 1.6;
    for (let o = 0; o < 4; o++) {
      const r = 1 - Math.abs(noise(nx * freq, nz * freq) * 2 - 1);
      ridge += r * r * amp;
      amp *= 0.42;
      freq *= 2.0;
    }
    const swell = noise(nx * 0.9 + 7, nz * 0.9 + 3);
    const r = Math.hypot(x, z) / (SIZE * 0.62);
    const dome = 1 - Math.min(1, r * r) * 0.55;
    return Math.max(SEA, (ridge * 1.0 + swell * 0.6 - 0.12) * dome * 1.25);
  };
}

/* the model: relief top plus four cut walls down to the plinth line */
function buildRelief(height: (x: number, z: number) => number) {
  const top = new THREE.PlaneGeometry(SIZE, SIZE, SEGMENTS, SEGMENTS);
  top.rotateX(-Math.PI / 2);
  const p = top.attributes.position as THREE.BufferAttribute;
  for (let i = 0; i < p.count; i++) p.setY(i, height(p.getX(i), p.getZ(i)));
  top.computeVertexNormals();

  const pos: number[] = [];
  const idx: number[] = [];
  const h = SIZE / 2;
  const edges: [number, number, number, number][] = [
    [-h, h, h, h],
    [h, h, h, -h],
    [h, -h, -h, -h],
    [-h, -h, -h, h],
  ];
  for (const [x0, z0, x1, z1] of edges) {
    const start = pos.length / 3;
    for (let s = 0; s <= SEGMENTS; s++) {
      const t = s / SEGMENTS;
      const x = x0 + (x1 - x0) * t,
        z = z0 + (z1 - z0) * t;
      pos.push(x, height(x, z), z, x, BASE, z);
    }
    for (let s = 0; s < SEGMENTS; s++) {
      const a = start + s * 2;
      idx.push(a, a + 1, a + 2, a + 1, a + 3, a + 2);
    }
  }
  const walls = new THREE.BufferGeometry();
  walls.setAttribute("position", new THREE.Float32BufferAttribute(pos, 3));
  walls.setIndex(idx);
  walls.computeVertexNormals();
  return { top, walls };
}

const VERT = /* glsl */ `
  varying vec3 vPos;
  varying vec3 vNormal;
  void main() {
    vPos = position;
    vNormal = normalize(mat3(modelMatrix) * normal);
    gl_Position = projectionMatrix * viewMatrix * modelMatrix * vec4(position, 1.0);
  }
`;

const RELIEF_FRAG = /* glsl */ `
  uniform vec3 uPaper; uniform vec3 uInk; uniform vec3 uAccent; uniform vec3 uMuted;
  uniform float uNight; uniform vec3 uLight; uniform float uWall;
  varying vec3 vPos;
  varying vec3 vNormal;
  void main() {
    vec3 n = normalize(vNormal);
    float h = vPos.y;
    float k = h / ${BANDS.toFixed(3)};
    float band = floor(k);
    float t = clamp(band * ${BANDS.toFixed(3)} / 1.1, 0.0, 1.0);
    float fw = fwidth(k);
    float f = min(fract(k), 1.0 - fract(k));
    float major = step(4.5, mod(band + 0.5, 5.0));
    float line = 1.0 - smoothstep(0.0, fw * (1.0 + major), f);
    float halo = 1.0 - smoothstep(0.0, fw * 6.0, f);
    float sea = 1.0 - step(${(SEA + 0.002).toFixed(3)}, h);
    float lit = max(dot(n, normalize(uLight)), 0.0);
    float shade = mix(0.42, 1.08, lit);
    float hatch = smoothstep(0.55, 0.9, sin((vPos.x + vPos.z) * 70.0));
    if (uWall > 0.5) sea = 0.0;

    vec3 day = mix(uPaper, uMuted, 0.15 + 0.6 * (1.0 - t));
    day = mix(day, uAccent, 0.04 + 0.3 * t * t);
    day *= 1.0 - 0.06 * mod(band, 2.0);
    day = mix(day, mix(uMuted, uAccent, 0.35), sea * (0.7 + 0.2 * hatch));
    day *= shade;
    day = mix(day, uInk, line * (0.35 + 0.35 * major) * (1.0 - sea));

    vec3 dark = mix(uPaper, uMuted, 0.5 + 0.3 * t) * mix(0.35, 0.95, lit);
    dark = mix(dark, uPaper * 0.6, sea);
    vec3 glow = uAccent * (line * (0.35 + 0.9 * major) + halo * major * 0.25) * (0.35 + 0.8 * t);
    dark += glow * (1.0 - sea) + uAccent * sea * hatch * 0.05;

    gl_FragColor = vec4(mix(day, dark, uNight), 1.0);
    #include <colorspace_fragment>
  }
`;

const TABLE_FRAG = /* glsl */ `
  uniform vec3 uPaper; uniform vec3 uInk; uniform vec3 uMuted; uniform vec3 uAccent; uniform float uNight;
  varying vec3 vPos;
  void main() {
    vec2 q = abs(vPos.xz) / ${(SIZE / 2).toFixed(2)};
    float box = max(q.x, q.y);
    float shadow = 1.0 - smoothstep(0.92, 1.35, box);
    float fade = smoothstep(3.5, 11.0, length(vPos.xz));
    vec3 table = mix(uMuted, uPaper, 0.35 + 0.25 * uNight);
    table = mix(table, uInk, shadow * mix(0.16, 0.0, uNight));
    table += uAccent * shadow * 0.07 * uNight;
    vec2 g = abs(fract(vPos.xz * 0.5) - 0.5);
    float gl = 1.0 - smoothstep(0.0, fwidth(vPos.x), 0.5 - max(g.x, g.y));
    table = mix(table, mix(uInk, uAccent, uNight), gl * mix(0.1, 0.06, uNight) * (1.0 - fade));
    gl_FragColor = vec4(mix(table, uPaper, fade), 1.0);
    #include <colorspace_fragment>
  }
`;

function readToken(style: CSSStyleDeclaration, name: string, target: THREE.Color) {
  const raw = style.getPropertyValue(name).trim().replace(/,/g, " ").split(/\s+/);
  const [hh, ss, ll] = raw.map((v) => parseFloat(v));
  if ([hh, ss, ll].some((v) => Number.isNaN(v))) return 0.5;
  target.setHSL(hh / 360, ss / 100, ll / 100, THREE.SRGBColorSpace);
  return ll / 100;
}

function mountRelief(
  host: HTMLDivElement,
  canvas: HTMLCanvasElement,
  opts: { variant: SurveyReliefVariant; seed: number; still: boolean },
) {
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(26, 1, 0.1, 100);

  const uniforms = {
    uPaper: { value: new THREE.Color() },
    uInk: { value: new THREE.Color() },
    uAccent: { value: new THREE.Color() },
    uMuted: { value: new THREE.Color() },
    uNight: { value: 0 },
    uLight: { value: new THREE.Vector3(-0.85, 0.32, 0.35) },
    uWall: { value: 0 },
  };
  const background = new THREE.Color();
  scene.background = background;

  const { top, walls } = buildRelief(makeHeight(opts.seed));
  const topMat = new THREE.ShaderMaterial({
    uniforms,
    vertexShader: VERT,
    fragmentShader: RELIEF_FRAG,
  });
  const wallMat = new THREE.ShaderMaterial({
    uniforms: { ...uniforms, uWall: { value: 1 } },
    vertexShader: VERT,
    fragmentShader: RELIEF_FRAG,
    side: THREE.DoubleSide,
  });
  const model = new THREE.Group();
  model.add(new THREE.Mesh(top, topMat), new THREE.Mesh(walls, wallMat));
  scene.add(model);

  const tableGeo = new THREE.PlaneGeometry(40, 40);
  tableGeo.rotateX(-Math.PI / 2);
  tableGeo.translate(0, BASE, 0);
  const tableMat = new THREE.ShaderMaterial({
    uniforms,
    vertexShader: VERT,
    fragmentShader: TABLE_FRAG,
  });
  const table = new THREE.Mesh(tableGeo, tableMat);
  scene.add(table);

  function resolveTheme() {
    const style = getComputedStyle(document.documentElement);
    const bgL = readToken(style, "--background", uniforms.uPaper.value);
    readToken(style, "--foreground", uniforms.uInk.value);
    readToken(style, "--primary", uniforms.uAccent.value);
    readToken(style, "--muted", uniforms.uMuted.value);
    const night = opts.variant === "nocturne" || (opts.variant === "auto" && bgL < 0.5);
    uniforms.uNight.value = night ? 1 : 0;
    /* the glow needs a light accent at night; a dark --primary is lifted toward the ink */
    if (night) {
      const hsl = { h: 0, s: 0, l: 0 };
      uniforms.uAccent.value.getHSL(hsl, THREE.SRGBColorSpace);
      if (hsl.l < 0.55)
        uniforms.uAccent.value.setHSL(hsl.h, Math.max(hsl.s, 0.35), 0.68, THREE.SRGBColorSpace);
    }
    background.copy(uniforms.uPaper.value);
  }

  let angle = 0.6;
  let drag: number | null = null;
  function layout() {
    const w = host.clientWidth || 1,
      h = host.clientHeight || 1;
    renderer.setSize(w, h, false);
    camera.aspect = w / h;
    const fit = camera.aspect < 1 ? 1 / camera.aspect : 1;
    const dist = 14 * Math.max(1, fit * 0.85);
    const elev = 0.5;
    camera.position.set(0, Math.sin(elev) * dist, Math.cos(elev) * dist);
    camera.lookAt(0, 0.05, 0);
    camera.updateProjectionMatrix();
  }
  function render() {
    model.rotation.y = angle;
    renderer.render(scene, camera);
  }

  const onDown = (e: PointerEvent) => {
    drag = e.clientX;
    canvas.setPointerCapture(e.pointerId);
  };
  const onMove = (e: PointerEvent) => {
    if (drag === null) return;
    angle += (e.clientX - drag) * 0.006;
    drag = e.clientX;
    if (opts.still) render();
  };
  const onUp = () => {
    drag = null;
  };
  canvas.addEventListener("pointerdown", onDown);
  canvas.addEventListener("pointermove", onMove);
  canvas.addEventListener("pointerup", onUp);
  canvas.addEventListener("pointercancel", onUp);

  let raf = 0,
    prev = 0,
    visible = true,
    running = false;
  function frame(now: number) {
    const dt = Math.min(0.05, (now - prev) / 1000);
    prev = now;
    if (drag === null) angle += dt * 0.07;
    render();
    raf = requestAnimationFrame(frame);
  }
  function sync() {
    const want = !opts.still && visible && !document.hidden;
    if (want && !running) {
      running = true;
      prev = performance.now();
      raf = requestAnimationFrame(frame);
    } else if (!want && running) {
      running = false;
      cancelAnimationFrame(raf);
    }
  }

  const io = new IntersectionObserver((es) => {
    visible = es[0].isIntersecting;
    sync();
  });
  io.observe(host);
  const ro = new ResizeObserver(() => {
    layout();
    render();
  });
  ro.observe(host);
  const mo = new MutationObserver(() => {
    resolveTheme();
    render();
  });
  mo.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["class", "data-theme", "data-palette", "style"],
  });
  document.addEventListener("visibilitychange", sync);

  resolveTheme();
  layout();
  render();
  sync();

  return () => {
    running = false;
    cancelAnimationFrame(raf);
    io.disconnect();
    ro.disconnect();
    mo.disconnect();
    document.removeEventListener("visibilitychange", sync);
    canvas.removeEventListener("pointerdown", onDown);
    canvas.removeEventListener("pointermove", onMove);
    canvas.removeEventListener("pointerup", onUp);
    canvas.removeEventListener("pointercancel", onUp);
    [top, walls, tableGeo].forEach((g) => g.dispose());
    [topMat, wallMat, tableMat].forEach((m) => m.dispose());
    renderer.dispose();
  };
}

/** A procedural topographic relief model turning slowly on a survey table, with contour bands in theme colours. */
export function SurveyRelief({
  variant = "auto",
  seed = 7,
  label = "Topographic relief model",
  className,
}: SurveyReliefProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    return mountRelief(host, canvas, { variant, seed, still: !!prefersReducedMotion });
  }, [variant, seed, prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      role="img"
      aria-label={label}
      className={cn("absolute inset-0 overflow-hidden bg-background", className)}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full cursor-grab touch-none active:cursor-grabbing"
      />
    </div>
  );
}
```

---

# Form Foundry

> An abstract architectural form assembles itself block by block on a studio plinth, in daylight or at dusk.

Install: `npx @modus-ui/cli add form-foundry`

A Three.js construction study. Choose a stepped ziggurat, three stacked monoliths, a lattice spire, an arch, a ring tower or a field of columns: blocks drop course by course onto a two-step plinth, settle, hold, then clear and rebuild. Every colour comes from the theme tokens: in light mode the form sits in paper-white haze under a pale sun, in dark mode it is a dusk scene with a moon and a primary-tinted rim light, and it re-colours when the theme or palette changes. Drag to turn the view. When focused, `Space` pauses, `R` rebuilds and `S` changes the form. The scene pauses when off screen or in a hidden tab. When the user prefers reduced motion it shows the finished form as a still frame.

## Installation

### CLI

```bash
npx @modus-ui/cli add form-foundry
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/form-foundry.tsx`.
4. Paste the code.

## Usage

```tsx
import { FormFoundry } from "@/components/ui/form-foundry";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <FormFoundry variant="lattice" />
    </div>
  );
}
```

## Props

| Prop        | Type                                                                      | Default      | Description                               |
| :---------- | :------------------------------------------------------------------------ | :----------- | :---------------------------------------- |
| `variant`   | `"ziggurat" \| "monoliths" \| "lattice" \| "arch" \| "ring" \| "columns"` | `"ziggurat"` | Which form assembles on the plinth.       |
| `className` | `string`                                                                  | None         | Extra classes for the absolute container. |

## Source

`components/ui/form-foundry.tsx`

```tsx
"use client";

import { useEffect, useRef } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export type FormFoundryVariant = "ziggurat" | "monoliths" | "lattice" | "arch" | "ring" | "columns";

const VARIANTS: FormFoundryVariant[] = [
  "ziggurat",
  "monoliths",
  "lattice",
  "arch",
  "ring",
  "columns",
];

const LABELS: Record<FormFoundryVariant, string> = {
  ziggurat: "A stepped ziggurat",
  monoliths: "Three stacked monoliths",
  lattice: "A lattice spire",
  arch: "A stone arch",
  ring: "A ring tower",
  columns: "A field of columns",
};

interface FormFoundryProps {
  /** Which abstract form assembles on the plinth. */
  variant?: FormFoundryVariant;
  className?: string;
}

/** A block in the form: grid position and whether it carries the accent colour. */
interface Block {
  x: number;
  y: number;
  z: number;
  accent: boolean;
}

function buildForm(variant: FormFoundryVariant): Block[] {
  const out: Block[] = [];
  const add = (x: number, y: number, z: number, accent = false) => out.push({ x, y, z, accent });
  switch (variant) {
    case "ziggurat":
      for (let k = 0; k < 6; k++) {
        const h = 5 - k;
        for (let x = -h; x <= h; x++)
          for (let z = -h; z <= h; z++)
            add(x, k, z, k === 5 || (Math.abs(x) === h && Math.abs(z) === h));
      }
      break;
    case "monoliths":
      [
        { ox: -3, oz: 0.5, h: 8 },
        { ox: 0, oz: -1, h: 12 },
        { ox: 3, oz: 1, h: 6 },
      ].forEach(({ ox, oz, h }) => {
        for (let y = 0; y < h; y++)
          for (let dx = 0; dx < 2; dx++) add(ox + dx - 0.5, y, oz, y === h - 1);
      });
      break;
    case "lattice":
      for (let y = 0; y < 16; y++) {
        const r = y < 5 ? 2 : y < 10 ? 1.5 : y < 14 ? 1 : 0;
        if (r === 0) {
          add(0, y, 0, true);
          continue;
        }
        for (const sx of [-1, 1]) for (const sz of [-1, 1]) add(sx * r, y, sz * r);
        if (y % 3 === 2)
          for (let t = -r + 1; t <= r - 1; t += 1) {
            add(t, y, -r, true);
            add(t, y, r, true);
            add(-r, y, t, true);
            add(r, y, t, true);
          }
      }
      break;
    case "arch":
      for (let y = 0; y < 6; y++)
        for (const px of [-4, 4])
          for (let dx = 0; dx < 2; dx++) for (let z = 0; z < 2; z++) add(px + dx - 0.5, y, z - 0.5);
      for (let i = 0; i <= 12; i++) {
        const a = Math.PI - (i / 12) * Math.PI;
        for (let z = 0; z < 2; z++) add(Math.cos(a) * 4, 6 + Math.sin(a) * 4, z - 0.5, i === 6);
      }
      break;
    case "ring":
      for (let y = 0; y < 12; y++) {
        const n = 14;
        for (let i = 0; i < n; i++) {
          const a = (i / n) * Math.PI * 2 + (y % 2) * (Math.PI / n);
          add(Math.cos(a) * 3.2, y, Math.sin(a) * 3.2, y === 7 || y === 11);
        }
      }
      break;
    case "columns": {
      for (let x = -3; x <= 3; x++)
        for (let z = -3; z <= 3; z++) {
          if ((x + z) % 2 !== 0) continue;
          const h = Math.round(
            3 + 6 * Math.exp(-(x * x + z * z) / 8) + Math.sin(x * 1.7 + z) * 1.2,
          );
          for (let y = 0; y < h; y++) add(x * 1.4, y, z * 1.4, y === h - 1 && x === 0 && z === 0);
        }
      break;
    }
  }
  /* bottom-up, then outside-in, so each course reads as it is laid */
  return out.sort((a, b) => a.y - b.y || a.x * a.x + a.z * a.z - (b.x * b.x + b.z * b.z));
}

function readToken(name: string, fallback: string) {
  const v = getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback;
  const [h, s, l] = v.split(/\s+/).map((p) => parseFloat(p));
  return new THREE.Color().setHSL(
    (h || 0) / 360,
    (s || 0) / 100,
    (l || 0) / 100,
    THREE.SRGBColorSpace,
  );
}

function readPalette() {
  const background = readToken("--background", "0 0 98%");
  const foreground = readToken("--foreground", "0 0 8%");
  const primary = readToken("--primary", "0 0 10%");
  const muted = readToken("--muted", "0 0 92%");
  const dark = background.getHSL({ h: 0, s: 0, l: 0 }).l < 0.5;
  return { background, foreground, primary, muted, dark };
}

const BLOCK = 0.94;
const STEP = 0.07; // seconds between consecutive blocks
const FALL = 0.7; // seconds a block takes to settle
const HOLD = 3.2; // seconds the finished form is held before it is rebuilt

function mountScene(
  host: HTMLDivElement,
  canvas: HTMLCanvasElement,
  initial: FormFoundryVariant,
  still: boolean,
) {
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false });
  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
  renderer.shadowMap.enabled = true;
  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
  renderer.outputColorSpace = THREE.SRGBColorSpace;
  renderer.toneMapping = THREE.NoToneMapping;

  const scene = new THREE.Scene();
  scene.fog = new THREE.Fog(0xffffff, 26, 70);
  const camera = new THREE.PerspectiveCamera(32, 1, 0.1, 200);

  /* lights */
  const hemi = new THREE.HemisphereLight(0xffffff, 0xffffff, 1);
  const sun = new THREE.DirectionalLight(0xffffff, 2);
  sun.position.set(-12, 22, 10);
  sun.castShadow = true;
  sun.shadow.mapSize.set(1024, 1024);
  sun.shadow.camera.left = sun.shadow.camera.bottom = -14;
  sun.shadow.camera.right = sun.shadow.camera.top = 14;
  sun.shadow.bias = -0.0005;
  sun.shadow.normalBias = 0.03;
  const rim = new THREE.DirectionalLight(0xffffff, 1);
  rim.position.set(14, 6, -14);
  const glow = new THREE.PointLight(0xffffff, 0, 30, 1.6);
  scene.add(hemi, sun, rim, glow);

  /* ground, plinth and sky disc */
  const groundMat = new THREE.MeshStandardMaterial({ roughness: 1 });
  const ground = new THREE.Mesh(new THREE.CircleGeometry(90, 64), groundMat);
  ground.rotation.x = -Math.PI / 2;
  ground.receiveShadow = true;
  const plinthMat = new THREE.MeshStandardMaterial({ roughness: 0.85 });
  const plinth = new THREE.Group();
  [
    { r: 9, h: 0.5, y: 0.25 },
    { r: 7.6, h: 0.5, y: 0.75 },
  ].forEach(({ r, h, y }) => {
    const m = new THREE.Mesh(new THREE.CylinderGeometry(r, r + 0.15, h, 72), plinthMat);
    m.position.y = y;
    m.castShadow = m.receiveShadow = true;
    plinth.add(m);
  });
  const lineMat = new THREE.MeshBasicMaterial({ transparent: true, opacity: 0.5 });
  const line = new THREE.Mesh(new THREE.RingGeometry(7.0, 7.06, 96), lineMat);
  line.rotation.x = -Math.PI / 2;
  line.position.y = 1.01;
  plinth.add(line);
  const discMat = new THREE.MeshBasicMaterial({ fog: false, transparent: true });
  const disc = new THREE.Mesh(new THREE.CircleGeometry(5, 64), discMat);
  disc.position.set(-15, 8, -70);
  camera.add(disc);
  scene.add(ground, plinth, camera);

  /* the form: one instanced mesh, every block animated through its matrix */
  const blockGeo = new THREE.BoxGeometry(BLOCK, BLOCK, BLOCK);
  const blockMat = new THREE.MeshStandardMaterial({ roughness: 0.7, metalness: 0.05 });
  const MAX = 400;
  const mesh = new THREE.InstancedMesh(blockGeo, blockMat, MAX);
  mesh.castShadow = mesh.receiveShadow = true;
  mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
  scene.add(mesh);

  let variant = initial;
  let blocks = buildForm(variant);
  let jitter: number[] = [];
  let palette = readPalette();
  const dummy = new THREE.Object3D();
  const tmp = new THREE.Color();

  const applyColors = () => {
    const { background, foreground, primary, muted, dark } = palette;
    const bg = background.clone();
    scene.background = bg;
    (scene.fog as THREE.Fog).color.copy(bg);
    if (dark) {
      /* dusk: a dim cool key, a primary-tinted rim and accent blocks that glow */
      hemi.color.copy(muted).lerp(primary, 0.3);
      hemi.groundColor.copy(background);
      hemi.intensity = 0.55;
      sun.color.copy(foreground).lerp(primary, 0.25);
      sun.intensity = 0.9;
      rim.color.copy(primary);
      rim.intensity = 2.2;
      glow.color.copy(primary);
      glow.intensity = 26;
      groundMat.color.copy(background).lerp(foreground, 0.05);
      plinthMat.color.copy(background).lerp(foreground, 0.16);
      lineMat.color.copy(primary);
      discMat.color.copy(foreground).lerp(primary, 0.3);
      discMat.opacity = 0.9;
      disc.scale.setScalar(0.55);
    } else {
      /* daylight: paper haze, a bright sun and ink-toned stone */
      hemi.color.set(0xffffff);
      hemi.groundColor.copy(background).lerp(foreground, 0.12);
      hemi.intensity = 1.5;
      sun.color.copy(background).lerp(primary, 0.06);
      sun.intensity = 2.6;
      rim.color.copy(background);
      rim.intensity = 0.6;
      glow.intensity = 0;
      groundMat.color.copy(background).lerp(muted, 0.6);
      plinthMat.color.copy(background).lerp(foreground, 0.06);
      lineMat.color.copy(foreground);
      discMat.color.copy(background).lerp(primary, 0.08).offsetHSL(0, 0, 0.04);
      discMat.opacity = 0.75;
      disc.scale.setScalar(1);
    }
    const stone = dark
      ? background.clone().lerp(foreground, 0.42)
      : background.clone().lerp(muted, 0.5).lerp(foreground, 0.2);
    const accent = dark ? primary.clone().lerp(foreground, 0.2) : primary.clone();
    blocks.forEach((b, i) => {
      tmp.copy(b.accent ? accent : stone).offsetHSL(0, 0, jitter[i] * (b.accent ? 0.02 : 0.05));
      mesh.setColorAt(i, tmp);
    });
    if (mesh.instanceColor) mesh.instanceColor.needsUpdate = true;
  };

  const setForm = (v: FormFoundryVariant) => {
    variant = v;
    blocks = buildForm(v).slice(0, MAX);
    jitter = blocks.map(() => Math.random() * 2 - 1);
    mesh.count = blocks.length;
    const top = blocks.reduce((m, b) => Math.max(m, b.y), 0);
    glow.position.set(4, top * 0.6 + 3, 6);
    applyColors();
  };
  setForm(variant);

  /* camera: a low three-quarter view that slowly circles the plinth */
  let azimuth = 0.62;
  let dragging = false;
  let lastX = 0;
  const frame = (t: number) => {
    const top = blocks.reduce((m, b) => Math.max(m, b.y), 0);
    const dist = 19 + top * 0.6;
    const az = azimuth + (still ? 0 : t * 0.05);
    camera.position.set(Math.sin(az) * dist, 5 + top * 0.3, Math.cos(az) * dist);
    camera.lookAt(0, 1 + top * 0.42, 0);
  };

  const ease = (x: number) => 1 - Math.pow(1 - x, 3);
  let buildStart = 0;
  const layBlocks = (t: number) => {
    const elapsed = t - buildStart;
    const total = blocks.length * STEP + FALL;
    let out = 0;
    if (elapsed > total + HOLD) out = Math.min(1, (elapsed - total - HOLD) / 0.8);
    blocks.forEach((b, i) => {
      const p = still ? 1 : Math.min(1, Math.max(0, (elapsed - i * STEP) / FALL));
      const e = ease(p);
      const s = (p > 0 ? 1 : 0) * (1 - out);
      dummy.position.set(b.x, 1 + BLOCK / 2 + b.y + (1 - e) * 6, b.z);
      dummy.rotation.set(0, (1 - e) * 0.8, 0);
      dummy.scale.setScalar(Math.max(0.0001, s * (0.6 + 0.4 * e)));
      dummy.updateMatrix();
      mesh.setMatrixAt(i, dummy.matrix);
    });
    mesh.instanceMatrix.needsUpdate = true;
    if (out >= 1) buildStart = t;
  };

  const resize = () => {
    const w = host.clientWidth || 1;
    const h = host.clientHeight || 1;
    renderer.setSize(w, h, false);
    camera.aspect = w / h;
    camera.updateProjectionMatrix();
  };
  resize();

  const clock = new THREE.Clock();
  let raf = 0;
  let running = false;
  let paused = false;
  let visible = true;
  let time = 0;
  const render = () => {
    frame(time);
    layBlocks(time);
    renderer.render(scene, camera);
  };
  const tick = () => {
    raf = requestAnimationFrame(tick);
    const dt = Math.min(clock.getDelta(), 0.1);
    if (!paused) time += dt;
    render();
  };
  const sync = () => {
    const should = !still && visible && !document.hidden;
    if (should && !running) {
      running = true;
      clock.getDelta();
      raf = requestAnimationFrame(tick);
    } else if (!should && running) {
      running = false;
      cancelAnimationFrame(raf);
    }
  };
  const redraw = () => {
    if (!running) render();
  };

  const ro = new ResizeObserver(() => {
    resize();
    redraw();
  });
  ro.observe(host);
  const io = new IntersectionObserver((es) => {
    visible = es[0]?.isIntersecting ?? true;
    sync();
  });
  io.observe(host);
  document.addEventListener("visibilitychange", sync);
  const mo = new MutationObserver(() => {
    palette = readPalette();
    applyColors();
    redraw();
  });
  mo.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["class", "data-theme", "style"],
  });

  const onDown = (e: PointerEvent) => {
    dragging = true;
    lastX = e.clientX;
    canvas.setPointerCapture(e.pointerId);
  };
  const onMove = (e: PointerEvent) => {
    if (!dragging) return;
    azimuth -= (e.clientX - lastX) * 0.006;
    lastX = e.clientX;
    redraw();
  };
  const onUp = () => {
    dragging = false;
  };
  const onKey = (e: KeyboardEvent) => {
    if (e.key === " ") {
      e.preventDefault();
      paused = !paused;
    } else if (e.key === "r" || e.key === "R") {
      buildStart = time;
    } else if (e.key === "s" || e.key === "S") {
      setForm(VARIANTS[(VARIANTS.indexOf(variant) + 1) % VARIANTS.length]);
      buildStart = time;
    } else return;
    redraw();
  };
  canvas.addEventListener("pointerdown", onDown);
  canvas.addEventListener("pointermove", onMove);
  canvas.addEventListener("pointerup", onUp);
  canvas.addEventListener("pointercancel", onUp);
  host.addEventListener("keydown", onKey);

  render();
  sync();

  return () => {
    running = false;
    cancelAnimationFrame(raf);
    ro.disconnect();
    io.disconnect();
    mo.disconnect();
    document.removeEventListener("visibilitychange", sync);
    canvas.removeEventListener("pointerdown", onDown);
    canvas.removeEventListener("pointermove", onMove);
    canvas.removeEventListener("pointerup", onUp);
    canvas.removeEventListener("pointercancel", onUp);
    host.removeEventListener("keydown", onKey);
    scene.traverse((o) => {
      if (o instanceof THREE.Mesh) o.geometry.dispose();
    });
    [groundMat, plinthMat, lineMat, discMat, blockMat].forEach((m) => m.dispose());
    mesh.dispose();
    renderer.dispose();
  };
}

export function FormFoundry({ variant = "ziggurat", className }: FormFoundryProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return;
    return mountScene(host, canvas, variant, !!prefersReducedMotion);
  }, [variant, prefersReducedMotion]);

  return (
    <div
      ref={hostRef}
      tabIndex={0}
      role="img"
      aria-label={`${LABELS[variant] ?? LABELS.ziggurat} assembling block by block on a plinth`}
      className={cn("absolute inset-0 overflow-hidden outline-none", className)}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full cursor-grab touch-none"
      />
    </div>
  );
}
```

---

# Specimen Desk

> A Three.js desk study with a pinned fan of Modus type specimen cards, paper-white by day and lamplit by night.

Install: `npx @modus-ui/cli add specimen-desk`

A fan of seven type specimen cards pinned at one corner on a desk, beside a closed notebook, a pencil and an ink pot. Each card is set in a Modus font and toned from the theme, from paper through the primary to ink. Drag sideways, use the arrow keys or click a card to bring it to the front of the fan; click it again (or press Enter) to lift it for a closer look. In light mode the desk sits in pale daylight on a paper-white mat; in dark mode a single lamp pools light over an oak desk. Colours follow the theme and palette live. It fills its positioned parent, pauses when off screen or when the tab is hidden and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add specimen-desk
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/specimen-desk.tsx`.
4. Paste the code.

## Usage

```tsx
import { SpecimenDesk } from "@/components/ui/specimen-desk";

export default function Example() {
  return (
    <div className="relative h-[600px] w-full overflow-hidden">
      <SpecimenDesk />
    </div>
  );
}
```

## Props

| Prop        | Type                 | Default         | Description                                                                                                    |
| :---------- | :------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------- |
| `cards`     | `SpecimenDeskCard[]` | `DEFAULT_CARDS` | Cards in the fan, bottom first. Each has a `name`, a large `glyph` and a `face` (`heading`, `body` or `mono`). |
| `className` | `string`             | none            | Extra classes for the wrapper.                                                                                 |

## Source

`components/ui/specimen-desk.tsx`

```tsx
"use client";
import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { RoundedBoxGeometry } from "three/examples/jsm/geometries/RoundedBoxGeometry.js";
import { cn } from "@/lib/utils";

export interface SpecimenDeskCard {
  /** Short name printed on the card and in the caption. */
  name: string;
  /** Glyphs set large on the card face. */
  glyph: string;
  /** Which Modus font family the specimen is set in. */
  face: "heading" | "body" | "mono";
}

const DEFAULT_CARDS: SpecimenDeskCard[] = [
  { name: "Display", glyph: "Aa", face: "heading" },
  { name: "Text", glyph: "Rg", face: "body" },
  { name: "Code", glyph: "{}", face: "mono" },
  { name: "Italic", glyph: "&", face: "heading" },
  { name: "Numerals", glyph: "27", face: "body" },
  { name: "Labels", glyph: "Mx", face: "mono" },
  { name: "Capitals", glyph: "Q", face: "heading" },
];

// Neutral desk materials: oiled oak at night, a pale felt mat by day.
const OAK = "#4a3426";
const OAK_DARK = "#2a1d15";

const CARD_W = 1.15;
const CARD_L = 1.75;
const CARD_T = 0.018;
const SPREAD = 0.3;

type Tokens = {
  background: THREE.Color;
  foreground: THREE.Color;
  primary: THREE.Color;
  muted: THREE.Color;
  dark: boolean;
  css: { background: string; foreground: string; primary: string; muted: string };
  fonts: { heading: string; body: string; mono: string };
};

function readTokens(): Tokens {
  const root = getComputedStyle(document.documentElement);
  const body = getComputedStyle(document.body);
  const channel = (name: string) => root.getPropertyValue(name).trim() || "0 0% 50%";
  const toColor = (value: string) => {
    const [h, s, l] = value
      .replace(/%/g, "")
      .split(/[\s,]+/)
      .map(Number);
    return new THREE.Color().setHSL((h || 0) / 360, (s || 0) / 100, (l || 0) / 100);
  };
  const css = {
    background: channel("--background"),
    foreground: channel("--foreground"),
    primary: channel("--primary"),
    muted: channel("--muted"),
  };
  const background = toColor(css.background);
  const hsl = { h: 0, s: 0, l: 0 };
  background.getHSL(hsl);
  const font = (name: string, fallback: string) =>
    body.getPropertyValue(name).trim() || root.getPropertyValue(name).trim() || fallback;
  return {
    background,
    foreground: toColor(css.foreground),
    primary: toColor(css.primary),
    muted: toColor(css.muted),
    dark: hsl.l < 0.5,
    css,
    fonts: {
      heading: font("--font-heading", "Georgia, serif"),
      body: font("--font-body", "system-ui, sans-serif"),
      mono: "ui-monospace, SFMono-Regular, Menlo, monospace",
    },
  };
}

// Card stock tone i of n: a ramp from paper through the primary to ink.
function cardTone(tokens: Tokens, index: number, count: number) {
  const t = count > 1 ? index / (count - 1) : 0;
  const paper = tokens.background.clone().lerp(tokens.muted, 0.5);
  const ink = tokens.dark ? tokens.background.clone().lerp(tokens.primary, 0.12) : tokens.primary;
  const accent = tokens.primary.clone();
  const hsl = { h: 0, s: 0, l: 0 };
  accent.getHSL(hsl);
  accent.setHSL(hsl.h, Math.min(1, hsl.s + 0.25), tokens.dark ? 0.42 : 0.55);
  if (t < 0.5) return paper.lerp(accent, t * 2 * 0.85);
  return accent.lerp(ink, (t - 0.5) * 2);
}

function drawCardFace(tokens: Tokens, card: SpecimenDeskCard, index: number, count: number) {
  const canvas = document.createElement("canvas");
  canvas.width = 512;
  canvas.height = 780;
  const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
  const tone = cardTone(tokens, index, count);
  const hsl = { h: 0, s: 0, l: 0 };
  tone.getHSL(hsl);
  const light = hsl.l > 0.42;
  const ink = light ? "rgba(20,16,14,0.86)" : "rgba(255,252,246,0.92)";
  const faint = light ? "rgba(20,16,14,0.32)" : "rgba(255,252,246,0.36)";
  ctx.fillStyle = `#${tone.getHexString(THREE.SRGBColorSpace)}`;
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  ctx.strokeStyle = faint;
  ctx.lineWidth = 2;
  ctx.strokeRect(28, 28, canvas.width - 56, canvas.height - 56);
  const family = tokens.fonts[card.face];
  ctx.fillStyle = ink;
  ctx.font = `500 22px ${tokens.fonts.mono}`;
  ctx.textBaseline = "top";
  ctx.fillText(`NO. ${String(index + 1).padStart(2, "0")}`, 52, 56);
  ctx.textAlign = "right";
  ctx.fillText(card.face.toUpperCase(), canvas.width - 52, 56);
  ctx.textAlign = "center";
  ctx.textBaseline = "middle";
  ctx.font = `400 250px ${family}`;
  ctx.fillText(card.glyph, canvas.width / 2, 330);
  ctx.fillStyle = faint;
  ctx.fillRect(52, 520, canvas.width - 104, 2);
  ctx.fillStyle = ink;
  ctx.textAlign = "left";
  ctx.textBaseline = "alphabetic";
  ctx.font = `400 54px ${tokens.fonts.heading}`;
  ctx.fillText(card.name, 52, 600);
  ctx.font = `400 22px ${family}`;
  ctx.fillText("abcdefghijklm 0123456789", 52, 660);
  ctx.font = `500 18px ${tokens.fonts.mono}`;
  ctx.fillStyle = faint;
  ctx.fillText("MODUS SPECIMEN", 52, 712);
  const texture = new THREE.CanvasTexture(canvas);
  texture.colorSpace = THREE.SRGBColorSpace;
  texture.anisotropy = 4;
  return { texture, tone };
}

interface SceneOptions {
  cards: SpecimenDeskCard[];
  reducedMotion: boolean;
  onSelect: (index: number) => void;
}

function createSpecimenDesk(host: HTMLElement, canvas: HTMLCanvasElement, options: SceneOptions) {
  const { cards, reducedMotion, onSelect } = options;
  const count = cards.length;
  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false });
  renderer.outputColorSpace = THREE.SRGBColorSpace;
  renderer.toneMapping = THREE.ACESFilmicToneMapping;
  renderer.shadowMap.enabled = true;
  renderer.shadowMap.type = THREE.PCFSoftShadowMap;

  const scene = new THREE.Scene();
  scene.fog = new THREE.Fog(0xffffff, 7, 15);
  const camera = new THREE.PerspectiveCamera(32, 1, 0.1, 40);

  // Desk and mat.
  const desk = new THREE.Mesh(
    new THREE.PlaneGeometry(30, 30),
    new THREE.MeshStandardMaterial({ roughness: 0.85 }),
  );
  desk.rotation.x = -Math.PI / 2;
  desk.receiveShadow = true;
  scene.add(desk);
  const mat = new THREE.Mesh(
    new RoundedBoxGeometry(5.6, 0.02, 3.6, 2, 0.04),
    new THREE.MeshStandardMaterial({ roughness: 0.95 }),
  );
  mat.position.set(-0.2, 0.01, 0.1);
  mat.receiveShadow = true;
  scene.add(mat);

  // The fan of specimen cards, pinned at one corner.
  const pivot = new THREE.Vector3(0, 0.03, 1.15);
  const cardGeometry = new RoundedBoxGeometry(CARD_W, CARD_T, CARD_L, 2, 0.006);
  cardGeometry.translate(0, 0, -CARD_L / 2 + 0.12);
  const edgeMaterial = new THREE.MeshStandardMaterial({ roughness: 0.9 });
  const cardGroups: THREE.Group[] = [];
  const faceMaterials: THREE.MeshStandardMaterial[] = [];
  cards.forEach((_, index) => {
    const group = new THREE.Group();
    group.position.copy(pivot);
    group.position.y += index * (CARD_T + 0.004);
    const face = new THREE.MeshStandardMaterial({ roughness: 0.7 });
    faceMaterials.push(face);
    const mesh = new THREE.Mesh(cardGeometry, face);
    mesh.castShadow = true;
    mesh.receiveShadow = true;
    mesh.userData.index = index;
    group.add(mesh);
    scene.add(group);
    cardGroups.push(group);
  });
  const pin = new THREE.Mesh(
    new THREE.CylinderGeometry(0.06, 0.06, 0.2, 24),
    new THREE.MeshStandardMaterial({ metalness: 0.9, roughness: 0.3 }),
  );
  pin.position.set(pivot.x, 0.1, pivot.z);
  pin.castShadow = true;
  scene.add(pin);

  // Props: a closed notebook, a pencil and an ink pot.
  const notebook = new THREE.Mesh(
    new RoundedBoxGeometry(1.6, 0.12, 2.2, 2, 0.03),
    new THREE.MeshStandardMaterial({ roughness: 0.8 }),
  );
  notebook.position.set(-2.4, 0.07, -0.4);
  notebook.rotation.y = 0.28;
  notebook.castShadow = true;
  notebook.receiveShadow = true;
  scene.add(notebook);
  const pencil = new THREE.Mesh(
    new THREE.CylinderGeometry(0.035, 0.035, 1.7, 6),
    new THREE.MeshStandardMaterial({ roughness: 0.6 }),
  );
  pencil.rotation.set(Math.PI / 2, 0, -0.9);
  pencil.position.set(1.9, 0.05, 0.9);
  pencil.castShadow = true;
  scene.add(pencil);
  const pot = new THREE.Mesh(
    new THREE.CylinderGeometry(0.28, 0.32, 0.42, 32),
    new THREE.MeshStandardMaterial({ roughness: 0.15, metalness: 0.1 }),
  );
  pot.position.set(2.3, 0.21, -0.9);
  pot.castShadow = true;
  scene.add(pot);

  // Lights: a daylight window by day, a lamp pool by night.
  const hemi = new THREE.HemisphereLight(0xffffff, 0xffffff, 1);
  scene.add(hemi);
  const key = new THREE.SpotLight(0xffffff, 1, 18, 0.55, 0.85, 1.2);
  key.castShadow = true;
  key.shadow.mapSize.set(1024, 1024);
  key.shadow.bias = -0.0004;
  key.target.position.set(0, 0, 0);
  scene.add(key, key.target);

  let tokens = readTokens();
  let textures: THREE.Texture[] = [];

  function applyTheme() {
    tokens = readTokens();
    textures.forEach((texture) => texture.dispose());
    textures = [];
    const { background, foreground, primary, muted, dark } = tokens;
    const sky = dark
      ? background.clone().lerp(primary, 0.06).multiplyScalar(0.7)
      : background.clone().lerp(new THREE.Color(1, 1, 1), 0.3);
    scene.background = sky;
    (scene.fog as THREE.Fog).color.copy(sky);
    (desk.material as THREE.MeshStandardMaterial).color.set(
      dark ? OAK_DARK : background.clone().lerp(muted, 0.6),
    );
    (mat.material as THREE.MeshStandardMaterial).color.set(
      dark ? OAK : background.clone().lerp(new THREE.Color(1, 1, 1), 0.6),
    );
    const accent = primary.clone();
    const hsl = { h: 0, s: 0, l: 0 };
    accent.getHSL(hsl);
    (notebook.material as THREE.MeshStandardMaterial).color.setHSL(
      hsl.h,
      Math.min(1, hsl.s + 0.2),
      dark ? 0.3 : 0.4,
    );
    (pencil.material as THREE.MeshStandardMaterial).color.copy(foreground);
    (pot.material as THREE.MeshStandardMaterial).color.copy(
      dark ? foreground.clone().lerp(background, 0.85) : primary,
    );
    (pin.material as THREE.MeshStandardMaterial).color.setHSL(hsl.h, 0.35, 0.6);
    edgeMaterial.color.copy(background);
    cards.forEach((card, index) => {
      const { texture } = drawCardFace(tokens, card, index, count);
      textures.push(texture);
      faceMaterials[index].map = texture;
      faceMaterials[index].needsUpdate = true;
    });

    if (dark) {
      const lamp = foreground.clone().lerp(new THREE.Color().setHSL(hsl.h, 0.7, 0.7), 0.4);
      hemi.color.copy(sky).multiplyScalar(1.6);
      hemi.groundColor.copy(background);
      hemi.intensity = 0.9;
      key.color.copy(lamp);
      key.intensity = 70;
      key.angle = 0.75;
      key.penumbra = 0.9;
      key.position.set(-1.6, 4.4, -0.6);
      renderer.toneMappingExposure = 1.05;
    } else {
      hemi.color.copy(background).lerp(new THREE.Color(1, 1, 1), 0.5);
      hemi.groundColor.copy(muted);
      hemi.intensity = 1.5;
      key.color.copy(new THREE.Color(1, 1, 1).lerp(background, 0.3));
      key.intensity = 55;
      key.angle = 0.9;
      key.penumbra = 1;
      key.position.set(3.5, 7, -3);
      renderer.toneMappingExposure = 0.95;
    }
  }
  applyTheme();

  // Fan state.
  let selected = Math.floor(count / 2);
  let inspecting = false;
  const angles = cardGroups.map(() => 0);
  const lifts = cardGroups.map(() => 0);
  const tilts = cardGroups.map(() => 0);

  function targetFor(index: number) {
    const offset = index - selected;
    const angle = -offset * SPREAD;
    const isSel = index === selected;
    return {
      angle,
      lift: isSel ? (inspecting ? 0.9 : 0.18) : 0,
      tilt: isSel ? (inspecting ? 0.95 : 0.14) : 0,
    };
  }

  function layout(step: number) {
    cardGroups.forEach((group, index) => {
      const target = targetFor(index);
      angles[index] += (target.angle - angles[index]) * step;
      lifts[index] += (target.lift - lifts[index]) * step;
      tilts[index] += (target.tilt - tilts[index]) * step;
      group.position.y = pivot.y + index * (CARD_T + 0.004) + lifts[index];
      group.rotation.set(0, 0, 0);
      group.rotateY(angles[index]);
      group.rotateX(tilts[index]);
    });
  }
  layout(1);

  function resize() {
    const width = Math.max(1, host.clientWidth);
    const height = Math.max(1, host.clientHeight);
    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
    renderer.setSize(width, height, false);
    camera.aspect = width / height;
    // Pull back on narrow frames so the whole fan stays in shot.
    const distance = camera.aspect < 1 ? 7.5 / camera.aspect ** 0.6 : 6.2;
    camera.position.set(1.6, distance * 0.72, distance * 0.62 + 1);
    camera.lookAt(0.1, 0, 0.1);
    camera.updateProjectionMatrix();
    renderFrame();
  }

  let elapsed = 0;
  function renderFrame() {
    renderer.render(scene, camera);
  }

  // Loop, paused off screen and in hidden tabs.
  let frame = 0;
  let visible = true;
  let last = performance.now();
  function tick(now: number) {
    frame = 0;
    const delta = Math.min(0.05, (now - last) / 1000);
    last = now;
    elapsed += delta;
    layout(1 - Math.exp(-delta * 7));
    if (!reducedMotion) {
      key.position.x += Math.sin(elapsed * 0.4) * 0.0015;
    }
    renderFrame();
    start();
  }
  function start() {
    if (reducedMotion || frame || !visible || document.hidden) return;
    frame = requestAnimationFrame(tick);
  }
  function stop() {
    if (frame) cancelAnimationFrame(frame);
    frame = 0;
  }
  function refresh() {
    if (reducedMotion) {
      layout(1);
      renderFrame();
    } else {
      last = performance.now();
      start();
    }
  }

  const intersection = new IntersectionObserver(([entry]) => {
    visible = entry.isIntersecting;
    if (visible) refresh();
    else stop();
  });
  intersection.observe(host);
  const onVisibility = () => (document.hidden ? stop() : refresh());
  document.addEventListener("visibilitychange", onVisibility);

  const themeObserver = new MutationObserver(() => {
    applyTheme();
    renderFrame();
  });
  themeObserver.observe(document.documentElement, {
    attributes: true,
    attributeFilter: ["class", "data-theme", "style"],
  });

  function select(index: number) {
    const next = (index + count) % count;
    if (next === selected) inspecting = !inspecting;
    else {
      selected = next;
      inspecting = false;
    }
    onSelect(selected);
    refresh();
  }

  // Pointer: click a card to bring it forward, click again to lift it; drag sideways to fan.
  const raycaster = new THREE.Raycaster();
  const pointer = new THREE.Vector2();
  let downX = 0;
  let dragged = 0;
  const onDown = (event: PointerEvent) => {
    downX = event.clientX;
    dragged = 0;
  };
  const onMove = (event: PointerEvent) => {
    if (!event.buttons) return;
    const steps = Math.trunc((event.clientX - downX) / 60);
    if (steps !== 0) {
      dragged += Math.abs(steps);
      downX = event.clientX;
      selected = Math.max(0, Math.min(count - 1, selected - steps));
      inspecting = false;
      onSelect(selected);
      refresh();
    }
  };
  const onUp = (event: PointerEvent) => {
    if (dragged) return;
    const rect = canvas.getBoundingClientRect();
    pointer.set(
      ((event.clientX - rect.left) / rect.width) * 2 - 1,
      -((event.clientY - rect.top) / rect.height) * 2 + 1,
    );
    raycaster.setFromCamera(pointer, camera);
    const hit = raycaster.intersectObjects(cardGroups, true)[0];
    if (hit) select(hit.object.userData.index as number);
    else if (inspecting) {
      inspecting = false;
      refresh();
    }
  };
  const onKey = (event: KeyboardEvent) => {
    if (event.key === "ArrowLeft") select(Math.max(0, selected - 1));
    else if (event.key === "ArrowRight") select(Math.min(count - 1, selected + 1));
    else if (event.key === "Enter" || event.key === " ") select(selected);
    else if (event.key === "Escape" && inspecting) {
      inspecting = false;
      refresh();
    } else return;
    event.preventDefault();
  };
  canvas.addEventListener("pointerdown", onDown);
  canvas.addEventListener("pointermove", onMove);
  canvas.addEventListener("pointerup", onUp);
  host.addEventListener("keydown", onKey);

  resize();
  start();
  onSelect(selected);

  return {
    resize,
    dispose() {
      stop();
      intersection.disconnect();
      themeObserver.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      canvas.removeEventListener("pointerdown", onDown);
      canvas.removeEventListener("pointermove", onMove);
      canvas.removeEventListener("pointerup", onUp);
      host.removeEventListener("keydown", onKey);
      textures.forEach((texture) => texture.dispose());
      scene.traverse((object) => {
        const mesh = object as THREE.Mesh;
        mesh.geometry?.dispose();
        const material = mesh.material;
        if (Array.isArray(material)) material.forEach((m) => m.dispose());
        else material?.dispose();
      });
      edgeMaterial.dispose();
      renderer.dispose();
    },
  };
}

export interface SpecimenDeskProps {
  className?: string;
  /** Specimen cards fanned on the desk, bottom of the stack first. */
  cards?: SpecimenDeskCard[];
}

export function SpecimenDesk({ className, cards = DEFAULT_CARDS }: SpecimenDeskProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [selected, setSelected] = useState(Math.floor(cards.length / 2));
  const [error, setError] = useState("");

  useEffect(() => {
    const host = hostRef.current;
    const canvas = canvasRef.current;
    if (!host || !canvas) return undefined;
    let desk: ReturnType<typeof createSpecimenDesk>;
    try {
      desk = createSpecimenDesk(host, canvas, {
        cards,
        reducedMotion: !!prefersReducedMotion,
        onSelect: setSelected,
      });
    } catch (caught) {
      setError(caught instanceof Error ? caught.message : "unsupported context");
      return undefined;
    }
    const resizeObserver = new ResizeObserver(() => desk.resize());
    resizeObserver.observe(host);
    return () => {
      resizeObserver.disconnect();
      desk.dispose();
    };
  }, [cards, prefersReducedMotion]);

  const card = cards[selected];

  return (
    <div
      ref={hostRef}
      tabIndex={0}
      className={cn(
        "absolute inset-0 block h-full w-full overflow-hidden bg-background outline-none",
        className,
      )}
    >
      <canvas
        ref={canvasRef}
        className="absolute inset-0 block h-full w-full touch-none"
        aria-label="Fan of type specimen cards on a desk. Use the arrow keys to browse and Enter to lift a card."
      />
      {card ? (
        <div
          className="pointer-events-none absolute bottom-5 left-5 text-foreground"
          aria-live="polite"
        >
          <p className="m-0 font-mono text-[11px] uppercase tracking-[0.2em] text-muted-foreground">
            Specimen {String(selected + 1).padStart(2, "0")} /{" "}
            {String(cards.length).padStart(2, "0")}
          </p>
          <p className="m-0 font-serif text-3xl leading-tight">{card.name}</p>
        </div>
      ) : null}
      {error ? (
        <p
          className="absolute inset-0 m-0 grid place-items-center p-6 text-center text-foreground"
          role="status"
        >
          WebGL is unavailable: {error}.
        </p>
      ) : null}
    </div>
  );
}
```

---

# Dot Screen

> A printed dot screen whose rings roll in from the lower-left corner, inked in theme colours.

Install: `npx @modus-ui/cli add dot-screen`

A fine grid of round WebGL points whose size swells in rings rolling in from the lower-left corner, shaded diagonally from the theme's primary to its muted ink on the theme background. It fills its positioned parent, follows the active theme and palette in light and dark mode, pauses when off screen and renders a still frame when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add dot-screen
```

### Manual

1. Install `three`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/dot-screen.tsx`.
4. Paste the code.

## Usage

```tsx
import { DotScreen } from "@/components/ui/dot-screen";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <DotScreen />
      <div className="relative z-10 p-8">
        <h1>Content over the background</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default | Description                                                        |
| :---------------- | :------- | :------ | :----------------------------------------------------------------- |
| `speed`           | `number` | `0.6`   | Ripple time multiplier (0–3).                                      |
| `size`            | `number` | `0.75`  | Point size multiplier.                                             |
| `length`          | `number` | `1.4`   | Ripple wavelength multiplier; higher packs more rings.             |
| `density`         | `number` | `1.5`   | Grid density; tightens point spacing (0.25–2.5).                   |
| `color`           | `string` | —       | Primary gradient colour. Defaults to the theme primary.            |
| `secondaryColor`  | `string` | —       | Secondary gradient colour. Defaults to the theme muted foreground. |
| `backgroundColor` | `string` | —       | Clear colour. Defaults to the theme background.                    |
| `hue`             | `number` | `0`     | Hue rotation of the final frame, in degrees.                       |
| `saturation`      | `number` | `1`     | Saturation of the final frame.                                     |
| `brightness`      | `number` | `1`     | Brightness of the final frame.                                     |

## Source

`components/ui/dot-screen.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Amber Halftone (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import * as THREE from "three";
import { cn } from "@/lib/utils";

export interface DotScreenProps {
  className?: string;
  /** Time multiplier for the ripple. */
  speed?: number;
  /** Point size multiplier. */
  size?: number;
  /** Ripple wavelength multiplier (higher = more rings). */
  length?: number;
  /** Grid density; tightens point spacing. */
  density?: number;
  /** Top colour of the vertical gradient. Defaults to the theme's primary. */
  color?: string;
  /** Bottom colour of the vertical gradient. Defaults to the theme's muted foreground. */
  secondaryColor?: string;
  /** Clear colour behind the points. Defaults to the theme's background. */
  backgroundColor?: string;
  /** Final-frame grade, in degrees. */
  hue?: number;
  saturation?: number;
  brightness?: number;
}

const TOKENS = [
  "primary",
  "foreground",
  "background",
  "muted-foreground",
  "border",
  "card",
] as const;
type Tokens = Record<(typeof TOKENS)[number], string>;

/** Bare HSL channels of the Modus theme tokens, re-read when the theme or palette changes. */
function useThemeTokens(): Tokens | null {
  const [tokens, setTokens] = useState<Tokens | null>(null);
  useEffect(() => {
    const root = document.documentElement;
    const read = () => {
      const style = getComputedStyle(root);
      const next = Object.fromEntries(
        TOKENS.map((name) => [name, style.getPropertyValue(`--${name}`).trim()]),
      ) as Tokens;
      setTokens((prev) => (prev && TOKENS.every((k) => prev[k] === next[k]) ? prev : next));
    };
    read();
    const observer = new MutationObserver(read);
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return tokens;
}

/** `hsl(h, s%, l%)` from bare channels — the comma form THREE.Color parses. */
const hslOf = (channels: string) => `hsl(${channels.split(/\s+/).slice(0, 3).join(", ")})`;

const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

export function DotScreen({
  className,
  speed = 0.6,
  size = 0.75,
  length = 1.4,
  density = 1.5,
  color,
  secondaryColor,
  backgroundColor,
  hue = 0,
  saturation = 1,
  brightness = 1,
}: DotScreenProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const speedRef = useRef(speed);
  speedRef.current = clamp(speed, 0, 3);

  const tokens = useThemeTokens();
  const top = color ?? (tokens ? hslOf(tokens.primary) : null);
  const bottom = secondaryColor ?? (tokens ? hslOf(tokens["muted-foreground"]) : null);
  const clear = backgroundColor ?? (tokens ? hslOf(tokens.background) : null);

  useEffect(() => {
    const host = hostRef.current;
    if (!host || !top || !bottom || !clear) return;

    const safeSize = clamp(size, 0.05, 200);
    const safeLength = clamp(length, 0.35, 2.5);
    const safeDensity = clamp(density, 0.25, 2.5);
    // Density tightens spacing rather than growing the grid, as in ThreeUI.
    const spacing = Number((0.085 / Math.max(0.25, safeDensity)).toFixed(4));
    const gridSize = Math.max(12, Math.ceil(2.8 / spacing));
    const pointSize = Number((9 * safeSize).toFixed(2));
    const wave = Number((6 * safeLength).toFixed(2));

    const renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
    renderer.setClearColor(new THREE.Color(clear), 1);
    const canvas = renderer.domElement;
    canvas.style.display = "block";
    canvas.style.width = "100%";
    canvas.style.height = "100%";
    host.appendChild(canvas);

    const scene = new THREE.Scene();
    const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 10);
    camera.position.z = 1;

    const positions: number[] = [];
    const scales: number[] = [];
    for (let x = -gridSize; x <= gridSize; x++) {
      for (let y = -gridSize; y <= gridSize; y++) {
        positions.push(x * spacing, y * spacing, 0);
        scales.push(1);
      }
    }
    const geometry = new THREE.BufferGeometry();
    geometry.setAttribute("position", new THREE.Float32BufferAttribute(positions, 3));
    geometry.setAttribute("scale", new THREE.Float32BufferAttribute(scales, 1));

    const material = new THREE.ShaderMaterial({
      uniforms: {
        time: { value: 0 },
        color1: { value: new THREE.Color(top) },
        color2: { value: new THREE.Color(bottom) },
      },
      vertexShader: `
        attribute float scale;
        varying vec2 vUv;
        varying float vScale;
        uniform float time;

        void main() {
          vUv = position.xy;
          // Rings radiate from the lower-left corner rather than the centre.
          float dist = length(position.xy - vec2(-1.6, -1.1));
          float animatedScale = scale * (sin(dist * ${wave.toFixed(2)} - time * 2.5) * 0.5 + 0.5);
          vScale = animatedScale;

          gl_PointSize = animatedScale * ${pointSize.toFixed(2)};
          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
        }
      `,
      fragmentShader: `
        uniform vec3 color1;
        uniform vec3 color2;
        varying vec2 vUv;
        varying float vScale;

        void main() {
          vec2 coord = gl_PointCoord - vec2(0.5);
          if(length(coord) > 0.5) discard;

          vec3 finalColor = mix(color2, color1, clamp((vUv.x + vUv.y) * 0.35 + 0.5, 0.0, 1.0));
          gl_FragColor = vec4(finalColor, vScale * 0.9);
        }
      `,
      transparent: true,
    });
    // The authored shader mixes sRGB hex values directly; keep them unconverted.
    material.uniforms.color1.value.convertLinearToSRGB();
    material.uniforms.color2.value.convertLinearToSRGB();

    const points = new THREE.Points(geometry, material);
    scene.add(points);

    const resize = () => {
      const width = Math.max(1, host.clientWidth);
      const height = Math.max(1, host.clientHeight);
      renderer.setSize(width, height, false);
      const aspect = width / height;
      camera.left = -aspect;
      camera.right = aspect;
      camera.bottom = -1;
      camera.top = 1;
      camera.updateProjectionMatrix();
      renderer.render(scene, camera);
    };
    const observer = new ResizeObserver(resize);
    observer.observe(host);
    resize();

    let elapsed = 0;
    let last = 0;
    let raf = 0;
    let visible = true;
    const tick = (now: number) => {
      raf = requestAnimationFrame(tick);
      const dt = last ? Math.min(0.1, (now - last) / 1000) : 0;
      last = now;
      elapsed += dt * speedRef.current;
      material.uniforms.time.value = elapsed;
      renderer.render(scene, camera);
    };
    const start = () => {
      if (prefersReducedMotion || raf || !visible || document.hidden) return;
      last = 0;
      raf = requestAnimationFrame(tick);
    };
    const stop = () => {
      cancelAnimationFrame(raf);
      raf = 0;
    };
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible) start();
      else stop();
    });
    io.observe(host);
    const onVisibility = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVisibility);
    start();

    return () => {
      stop();
      io.disconnect();
      observer.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      geometry.dispose();
      material.dispose();
      renderer.dispose();
      canvas.remove();
    };
  }, [prefersReducedMotion, size, length, density, top, bottom, clear]);

  const safeHue = clamp(hue, -180, 180);
  const safeSaturation = clamp(saturation, 0, 2);
  const safeBrightness = clamp(brightness, 0.35, 1.65);
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      ref={hostRef}
      aria-hidden="true"
      className={cn("absolute inset-0 h-full w-full", className)}
      style={{ background: clear ?? "hsl(var(--background))", filter }}
    />
  );
}
```

---

# Tubelight

> Serif neon lettering on canvas, lit in the theme colour, that breathes and flickers one letter.

Install: `npx @modus-ui/cli add tubelight`

The heading serif is bent into outline glass tubing on a 2D canvas, drawn in layered passes — spill, bloom, a hot core and a specular streak — inside a rounded framing tube fed by two electrodes. The gas takes its colour from `--primary`: in dark mode the tubes glow, in light mode they read as unlit daylight glass on paper with a cast shadow. The sign breathes gently and one letter drops out and re-strikes on a seeded flicker schedule.

## Installation

### CLI

```bash
npx @modus-ui/cli add tubelight
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tubelight.tsx`.
3. Paste the code.

## Usage

```tsx
import { Tubelight } from "@/components/ui/tubelight";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full">
      <Tubelight text={"Open\nlate"} />
    </div>
  );
}
```

Any text the heading font can set is supported; use `\n` for a new line.

## Props

| Prop              | Type                          | Default   | Description                                                      |
| :---------------- | :---------------------------- | :-------- | :--------------------------------------------------------------- |
| `text`            | `string`                      | `"Modus"` | Lettering in the heading serif; `\n` starts a new line.          |
| `mode`            | `"auto" \| "dark" \| "light"` | `"auto"`  | Lit tubes, unlit daylight glass, or follow the site theme.       |
| `frame`           | `boolean`                     | `true`    | Bend a framing tube around the lettering, fed by two electrodes. |
| `backgroundColor` | `string`                      | —         | Stage colour. Defaults to the theme background.                  |
| `hue`             | `number`                      | `0`       | Hue rotation of the final frame, in degrees.                     |
| `saturation`      | `number`                      | `1`       | Saturation of the final frame.                                   |
| `brightness`      | `number`                      | `1`       | Brightness of the final frame.                                   |

## Source

`components/ui/tubelight.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Neon Sign (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { motion, useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface TubelightProps {
  className?: string;
  /** Lettering, set in the theme's heading serif; "\n" starts a new line. */
  text?: string;
  /** "dark" lights the tubes; "light" shows unlit daylight glass on paper. "auto" follows the site theme. */
  mode?: "auto" | "dark" | "light";
  /** Bend a framing tube around the lettering, fed by two electrodes. */
  frame?: boolean;
  /** Stage colour. Defaults to the theme background. */
  backgroundColor?: string;
  /** Final-frame grade, in degrees. */
  hue?: number;
  saturation?: number;
  brightness?: number;
}

type Glyph = { ch: string; x: number; y: number };
type Hsl = { h: number; s: number; l: number };
type Theme = { primary: Hsl; fg: Hsl; font: string; light: boolean };

const P = Math.PI;
const DEFAULT_TEXT = "Modus";
const SPILL_S = 0.34;
const BLOOM_S = 0.5;

function hsl(c: Hsl, a = 1, l = c.l, s = c.s) {
  return `hsla(${c.h} ${s}% ${l}% / ${a})`;
}
function readTheme(mode: TubelightProps["mode"]): Theme {
  const root = document.documentElement;
  const cs = getComputedStyle(root);
  const parse = (name: string): Hsl => {
    const [h, s, l] = cs
      .getPropertyValue(name)
      .trim()
      .split(/\s+/)
      .map((v) => parseFloat(v));
    return { h: h || 0, s: s || 0, l: l || 50 };
  };
  const probe = document.createElement("span");
  probe.className = "font-serif";
  probe.style.display = "none";
  document.body.appendChild(probe);
  const font = getComputedStyle(probe).fontFamily || "Georgia, serif";
  probe.remove();
  const light = mode === "auto" ? !root.classList.contains("dark") : mode === "light";
  return { primary: parse("--primary"), fg: parse("--foreground"), font, light };
}

function mk(w: number, h: number) {
  const c = document.createElement("canvas");
  c.width = Math.max(1, Math.round(w));
  c.height = Math.max(1, Math.round(h));
  return c;
}

/** A sign: serif glyphs stroked as outline tubing plus an optional rounded frame tube. */
type Sign = { glyphs: Glyph[]; frame: Path2D | null; ends: { x: number; y: number }[] };

function scale(x: CanvasRenderingContext2D, k: number) {
  x.setTransform(k, 0, 0, k, 0, 0);
}
function strokePass(
  x: CanvasRenderingContext2D,
  sign: Sign,
  font: string,
  w: number,
  blur: number,
  col: string,
  alpha: number,
  op: GlobalCompositeOperation = "lighter",
  dx = 0,
  dy = 0,
) {
  x.save();
  x.lineCap = "round";
  x.lineJoin = "round";
  if (blur > 0.25) x.filter = `blur(${blur.toFixed(2)}px)`;
  x.globalCompositeOperation = op;
  x.globalAlpha = alpha;
  x.lineWidth = w;
  x.strokeStyle = col;
  x.font = font;
  x.textBaseline = "alphabetic";
  x.translate(dx, dy);
  for (const g of sign.glyphs) x.strokeText(g.ch, g.x, g.y);
  if (sign.frame) x.stroke(sign.frame);
  x.restore();
}

/** Colour recipe per mode: lit gas on dark, or unlit tinted glass in daylight. */
function paintTubes(
  x: CanvasRenderingContext2D,
  sign: Sign,
  font: string,
  tube: number,
  t: Theme,
  lit: boolean,
) {
  const p = t.primary;
  const glowS = Math.max(p.s, 45);
  if (!t.light) {
    // glass wall, then the lit core in three heats
    strokePass(x, sign, font, tube, 0, hsl(p, 0.22, 18, glowS), 1, "source-over");
    if (!lit) return;
    strokePass(x, sign, font, tube * 0.88, tube * 0.1, hsl(p, 1, 55, glowS), 1);
    strokePass(x, sign, font, tube * 0.54, tube * 0.06, hsl(p, 1, 76, glowS), 1);
    strokePass(x, sign, font, tube * 0.24, tube * 0.035, hsl(p, 1, 97, p.s * 0.3), 1);
    return;
  }
  // daylight: a cast shadow on paper, tinted glass, the unlit gas channel and a specular streak
  strokePass(
    x,
    sign,
    font,
    tube,
    tube * 0.5,
    hsl(t.fg, 0.16),
    1,
    "source-over",
    tube * 0.35,
    tube * 0.9,
  );
  strokePass(x, sign, font, tube, 0, hsl(p, 0.28, Math.min(p.l + 30, 70), glowS), 1, "source-over");
  strokePass(
    x,
    sign,
    font,
    tube * 0.32,
    0,
    hsl(p, lit ? 1 : 0.6, Math.min(p.l + 18, 46), glowS),
    1,
    "source-over",
  );
  strokePass(
    x,
    sign,
    font,
    tube * 0.18,
    tube * 0.05,
    "rgba(255,255,255,0.85)",
    1,
    "source-over",
    -tube * 0.12,
    -tube * 0.22,
  );
}

function glow(sign: Sign, font: string, tube: number, t: Theme, W: number, H: number, k: number) {
  const c = mk(W * k, H * k);
  const x = c.getContext("2d")!;
  scale(x, k);
  const p = t.primary;
  const s = Math.max(p.s, 45);
  if (t.light) {
    strokePass(x, sign, font, tube * 1.6, tube * 0.9, hsl(p, 1, 60, s), 0.12, "source-over");
  } else {
    strokePass(x, sign, font, tube * 2.6, tube * 1.75, hsl(p, 1, 55, s), 0.3);
    strokePass(x, sign, font, tube * 1.34, tube * 0.58, hsl(p, 1, 70, s), 0.45);
  }
  return c;
}

function electrodes(x: CanvasRenderingContext2D, ends: Sign["ends"], tube: number, t: Theme) {
  const p = t.primary;
  x.save();
  for (const e of ends) {
    x.beginPath();
    x.moveTo(e.x, e.y);
    x.lineTo(e.x, e.y + tube * 2.2);
    x.lineCap = "round";
    x.lineWidth = tube * 0.5;
    x.strokeStyle = hsl(t.fg, t.light ? 0.55 : 0.35, t.light ? 25 : 12);
    x.stroke();
    x.beginPath();
    x.arc(e.x, e.y, tube * 0.75, 0, P * 2);
    x.fillStyle = hsl(t.fg, 1, t.light ? 22 : 8);
    x.fill();
    if (!t.light) {
      const g = x.createRadialGradient(e.x, e.y, 0, e.x, e.y, tube * 1.4);
      g.addColorStop(0, hsl(p, 0.9, 92, 40));
      g.addColorStop(0.3, hsl(p, 0.5, 60, Math.max(p.s, 45)));
      g.addColorStop(1, hsl(p, 0, 50));
      x.globalCompositeOperation = "lighter";
      x.beginPath();
      x.arc(e.x, e.y, tube * 1.4, 0, P * 2);
      x.fillStyle = g;
      x.fill();
      x.globalCompositeOperation = "source-over";
    }
  }
  x.restore();
}

export function Tubelight({
  className,
  text = DEFAULT_TEXT,
  mode = "auto",
  frame = true,
  backgroundColor,
  hue = 0,
  saturation = 1,
  brightness = 1,
}: TubelightProps) {
  const prefersReducedMotion = useReducedMotion();
  const boardRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const [themeKey, setThemeKey] = useState(0);

  // re-resolve tokens when the site theme or palette changes, and once the serif has loaded
  useEffect(() => {
    const bump = () => setThemeKey((k) => k + 1);
    const mo = new MutationObserver(bump);
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "style"],
    });
    document.fonts?.ready.then(bump);
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const board = boardRef.current;
    const cv = canvasRef.current;
    if (!board || !cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;
    const reduce = !!prefersReducedMotion;
    const theme = readTheme(mode);
    const LINES = text.split("\n").filter((l) => l.trim().length);

    let W = 0;
    let H = 0;
    let BASE: HTMLCanvasElement | null = null;
    let WLIT: HTMLCanvasElement | null = null;
    let dirty = { x: 0, y: 0, w: 0, h: 0 };
    let composed = false;
    let lastF = -1;

    function layout() {
      const m = mk(1, 1).getContext("2d")!;
      const font = (px: number) => `400 ${px}px ${theme.font}`;
      m.font = font(100);
      const widths = LINES.map((l) => m.measureText(l).width / 100);
      const lineH = 1.02;
      const blockW = Math.max(...widths);
      const blockH = LINES.length * lineH;
      const padX = frame ? 0.34 : 0.1;
      const padY = frame ? 0.3 : 0.1;
      const size = Math.min((W * 0.86) / (blockW + padX * 2), (H * 0.8) / (blockH + padY * 2));
      const tube = Math.max(1.5, size * 0.026);
      const x0 = (W - blockW * size) / 2;
      const y0 = (H - blockH * size) / 2;
      m.font = font(size);
      const glyphs: Glyph[] = [];
      LINES.forEach((line, i) => {
        const lx = x0 + ((blockW - widths[i]) * size) / 2;
        const by = y0 + (i * lineH + 0.78) * size;
        const chars = [...line];
        chars.forEach((ch, j) => {
          if (!ch.trim()) return;
          const before = m.measureText(chars.slice(0, j).join("")).width;
          glyphs.push({ ch, x: lx + before, y: by });
        });
      });
      let framePath: Path2D | null = null;
      const ends: Sign["ends"] = [];
      if (frame) {
        const fx = x0 - padX * size;
        const fy = y0 - padY * size * 0.75;
        const fw = (blockW + padX * 2) * size;
        const fh = (blockH + padY * 1.6) * size;
        const r = size * 0.16;
        const gap = size * 0.1;
        const cx = fx + fw / 2;
        const bottom = fy + fh;
        framePath = new Path2D();
        framePath.moveTo(cx - gap, bottom);
        framePath.arcTo(fx, bottom, fx, fy, r);
        framePath.arcTo(fx, fy, fx + fw, fy, r);
        framePath.arcTo(fx + fw, fy, fx + fw, bottom, r);
        framePath.arcTo(fx + fw, bottom, cx, bottom, r);
        framePath.lineTo(cx + gap, bottom);
        ends.push({ x: cx - gap, y: bottom }, { x: cx + gap, y: bottom });
      }
      return { glyphs, framePath, ends, tube, size, font: font(size) };
    }

    function bake() {
      const L = layout();
      // the flickering letter: second from the end of the last line
      const flickIdx = Math.max(0, L.glyphs.length - 2);
      const flick = L.glyphs[flickIdx];
      const steady: Sign = {
        glyphs: L.glyphs.filter((_, i) => i !== flickIdx),
        frame: L.framePath,
        ends: L.ends,
      };
      const one: Sign = { glyphs: flick ? [flick] : [], frame: null, ends: [] };
      const all: Sign = { glyphs: L.glyphs, frame: L.framePath, ends: L.ends };

      const base = mk(W, H);
      const b = base.getContext("2d")!;
      b.globalCompositeOperation = theme.light ? "source-over" : "lighter";
      b.drawImage(glow(steady, L.font, L.tube, theme, W, H, SPILL_S), 0, 0, W, H);
      if (!theme.light) b.drawImage(glow(steady, L.font, L.tube, theme, W, H, BLOOM_S), 0, 0, W, H);
      b.globalCompositeOperation = "source-over";
      // the dark glass of every tube, the flicker letter included, then the lit cores
      if (!theme.light) paintTubes(b, all, L.font, L.tube, theme, false);
      paintTubes(b, steady, L.font, L.tube, theme, true);
      if (theme.light && one.glyphs.length) paintTubes(b, one, L.font, L.tube, theme, false);
      electrodes(b, L.ends, L.tube, theme);
      BASE = base;

      const lit = mk(W, H);
      const w = lit.getContext("2d")!;
      if (flick) {
        w.drawImage(glow(one, L.font, L.tube, theme, W, H, SPILL_S), 0, 0, W, H);
        paintTubes(w, one, L.font, L.tube, theme, true);
        const pad = L.size * 0.9;
        dirty = {
          x: Math.max(0, Math.floor(flick.x - pad)),
          y: Math.max(0, Math.floor(flick.y - L.size - pad)),
          w: 0,
          h: 0,
        };
        dirty.w = Math.min(W - dirty.x, Math.ceil(L.size * 0.8 + pad * 2));
        dirty.h = Math.min(H - dirty.y, Math.ceil(L.size * 1.2 + pad * 2));
      } else {
        dirty = { x: 0, y: 0, w: 0, h: 0 };
      }
      WLIT = lit;
    }

    function compose(f: number) {
      if (!BASE || !ctx) return;
      const r = dirty.w > 0 && composed ? dirty : { x: 0, y: 0, w: W, h: H };
      ctx.globalCompositeOperation = "source-over";
      ctx.globalAlpha = 1;
      ctx.clearRect(r.x, r.y, r.w, r.h);
      ctx.drawImage(BASE, r.x, r.y, r.w, r.h, r.x, r.y, r.w, r.h);
      if (f > 0.002 && WLIT) {
        ctx.globalCompositeOperation = theme.light ? "source-over" : "lighter";
        ctx.globalAlpha = f;
        ctx.drawImage(WLIT, r.x, r.y, r.w, r.h, r.x, r.y, r.w, r.h);
      }
      composed = true;
      ctx.globalCompositeOperation = "source-over";
      ctx.globalAlpha = 1;
      lastF = f;
    }

    /* the flicker: a seeded schedule of dips on one letter, quickened for the preview as in ThreeUI */
    let fseed = 0x1981;
    const frnd = () => {
      fseed = (Math.imul(fseed, 1103515245) + 12345) >>> 0;
      return fseed / 4294967296;
    };
    type Ev = { t0: number; dur: number; segs: { d: number; v: number }[] };
    let ev: Ev | null = null;
    let clock = 0;
    function nextEvent(after: number): Ev {
      const segs: { d: number; v: number }[] = [];
      const n = 1 + (frnd() < 0.42 ? 1 : 0);
      for (let i = 0; i < n; i++) {
        segs.push({ d: 0.2 + frnd() * 0.26, v: 0.22 + frnd() * 0.4 });
        segs.push({ d: 0.24 + frnd() * 0.34, v: 1 });
      }
      const total = segs.reduce((a, s) => a + s.d, 0);
      return { t0: after + 1.25 + frnd() * 1.75, dur: total, segs };
    }
    function level(t: number) {
      if (!ev) ev = nextEvent(0.55);
      while (t > ev.t0 + ev.dur) ev = nextEvent(ev.t0 + ev.dur);
      if (t < ev.t0) return 1;
      let u = t - ev.t0;
      let prev = 1;
      for (const s of ev.segs) {
        if (u < s.d) {
          let p = u / s.d;
          p = p * p * (3 - 2 * p);
          return prev + (s.v - prev) * p;
        }
        u -= s.d;
        prev = s.v;
      }
      return 1;
    }

    function resize() {
      const w = Math.round(board!.clientWidth);
      const h = Math.round(board!.clientHeight);
      if (!w || !h || !LINES.length) return;
      if (w === W && h === H) return;
      W = w;
      H = h;
      cv!.width = W;
      cv!.height = H;
      bake();
      composed = false;
      compose(reduce ? 1 : level(clock));
    }

    let raf = 0;
    let last = 0;
    let visible = true;
    const stop = () => {
      if (raf) cancelAnimationFrame(raf);
      raf = 0;
    };
    const tick = (now: number) => {
      raf = requestAnimationFrame(tick);
      const dt = last ? Math.min(0.05, (now - last) / 1000) : 0;
      last = now;
      clock += dt;
      const f = level(clock);
      if (Math.abs(f - lastF) > 0.008) compose(f);
    };
    const start = () => {
      if (reduce || raf || !visible || document.hidden) return;
      last = 0;
      raf = requestAnimationFrame(tick);
    };

    resize();
    let rt = 0;
    const ro = new ResizeObserver(() => {
      window.clearTimeout(rt);
      if (!W) resize();
      else rt = window.setTimeout(resize, 180);
    });
    ro.observe(board);
    const onVisibility = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVisibility);
    const io = new IntersectionObserver(
      ([entry]) => {
        visible = entry.isIntersecting;
        if (visible) start();
        else stop();
      },
      { threshold: 0.01 },
    );
    io.observe(board);
    start();

    return () => {
      stop();
      window.clearTimeout(rt);
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
    };
  }, [text, mode, frame, prefersReducedMotion, themeKey]);

  const background = backgroundColor ?? "hsl(var(--background))";
  const safeHue = Math.min(180, Math.max(-180, hue));
  const safeSaturation = Math.min(2, Math.max(0, saturation));
  const safeBrightness = Math.min(1.65, Math.max(0.35, brightness));
  const grade =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;

  return (
    <div
      className={cn(
        "relative flex h-full w-full items-center justify-center overflow-hidden",
        className,
      )}
      style={{ background, filter: grade }}
    >
      <div
        ref={boardRef}
        className="relative aspect-video max-h-[calc(100%-32px)] w-[min(calc(100%-32px),1040px)]"
      >
        <motion.canvas
          ref={canvasRef}
          aria-hidden="true"
          className="block h-full w-full"
          style={{ transformOrigin: "50% 52%", willChange: "transform, opacity" }}
          initial={false}
          animate={
            prefersReducedMotion
              ? { y: 0, scale: 1, opacity: 1 }
              : {
                  y: [3, -3, 0, 3],
                  scale: [0.988, 1, 0.996, 0.988],
                  opacity: [0.88, 1, 0.96, 0.88],
                }
          }
          transition={
            prefersReducedMotion
              ? { duration: 0 }
              : {
                  duration: 5.6,
                  times: [0, 0.45, 0.68, 1],
                  ease: [0.22, 1, 0.36, 1],
                  repeat: Infinity,
                }
          }
        />
        <span className="sr-only">{text.replace(/\n/g, " ")}</span>
      </div>
    </div>
  );
}
```

---

# Salon Banner

> An oversized serif headline ringed by twelve plates mixed from your theme, orbiting while hovered.

Install: `npx @modus-ui/cli add salon-banner`

A two-line headline in the theme's heading face, set inside a tilted ring of twelve 4:3 plates. By default the plates are a tonal ladder mixed from the page, muted, primary and foreground tokens and shaded with a halftone field, so the gallery follows light, dark and every palette. The ring rests until a pointer is over it, then comes up to one orbit every 15 seconds and settles back to a stop on leave. The four original galleries — matte (sprung), glitch, riso and halftone — remain available through `variant`, each with its own palette, field, typeface and orbit.

## Installation

### CLI

```bash
npx @modus-ui/cli add salon-banner
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/salon-banner.tsx`.
3. Paste the code.

## Usage

```tsx
import { SalonBanner } from "@/components/ui/salon-banner";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SalonBanner variant="horizontal-sweep" text={"NEW WORK\nON THE WALL"} />
    </div>
  );
}
```

## Props

| Prop              | Type                                                                                          | Default   | Description                                                               |
| :---------------- | :-------------------------------------------------------------------------------------------- | :-------- | :------------------------------------------------------------------------ |
| `variant`         | `"tonal" \| "rising-diagonal" \| "falling-diagonal" \| "horizontal-sweep" \| "vertical-loop"` | `"tonal"` | Tonal theme gallery, or the matte, glitch, riso or halftone gallery.      |
| `text`            | `string`                                                                                      | —         | Two-line headline split on `\n`. Defaults to the variant's own.           |
| `font`            | `"heading" \| "serif" \| "didone" \| "oldstyle" \| "sans"`                                    | —         | Headline face. Defaults to the variant's face.                            |
| `weight`          | `"400" \| "700"`                                                                              | —         | Headline weight. Defaults to the variant's weight.                        |
| `headlineSize`    | `number`                                                                                      | —         | Headline size multiplier (0.6–1.8). Defaults to the variant's.            |
| `colors`          | `string[]`                                                                                    | —         | Twelve plate colours (any CSS colour). Defaults to the variant's palette. |
| `backgroundColor` | `string`                                                                                      | —         | Stage colour. Defaults to `hsl(var(--background))`.                       |
| `hue`             | `number`                                                                                      | `0`       | Hue rotation of the final frame, in degrees.                              |
| `saturation`      | `number`                                                                                      | `1`       | Saturation of the final frame.                                            |
| `brightness`      | `number`                                                                                      | `1`       | Brightness of the final frame.                                            |

## Source

`components/ui/salon-banner.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Gallery Heading (MIT, © 2026 Meng To).

import { useEffect, useRef, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

/* Four galleries: each brings its own orbit, twelve flat plate colours, the
   procedural field the plates are shaded with, the headline face, and the way
   the ring comes up to speed when a pointer arrives. */
const VARIANTS = {
  /* the house gallery: plates mixed from the theme tokens, set in the heading face */
  tonal: {
    headline: ["Twelve quiet", "studies in tone"],
    headlineWidths: [0, 0],
    axis: -14,
    phase: 90,
    direction: 1,
    field: "halftone",
    palette: null,
    type: { font: "heading", weight: "400", headlineSize: 1.3, tracking: 0 },
    motion: { spring: true, ease: 0.42 },
  },
  "rising-diagonal": {
    headline: ["TWELVE WORKS", "IN SLOW ORBIT"],
    headlineWidths: [1846, 2000],
    axis: 25.5,
    phase: 93,
    direction: 1,
    field: "matte",
    palette: [
      "#e9e5dd",
      "#20232a",
      "#c25a43",
      "#2f5b4e",
      "#d6cfc2",
      "#3a4763",
      "#dda45c",
      "#14161a",
      "#a7b3a4",
      "#f3f1ec",
      "#5a6670",
      "#8c4b3f",
    ],
    type: { font: "sans", weight: "400", headlineSize: 1.15, tracking: 0.1 },
    motion: { spring: true, ease: 0.42 },
  },
  "falling-diagonal": {
    headline: ["SIGNAL LOST", "IMAGE HOLDING"],
    headlineWidths: [1622, 1917],
    axis: -25.5,
    phase: 87,
    direction: -1,
    field: "glitch",
    palette: [
      "#0b0b12",
      "#ff2f6d",
      "#00e6ff",
      "#13f28a",
      "#f2f2f8",
      "#7a1bff",
      "#101018",
      "#ff7a1a",
      "#141a2e",
      "#e01f52",
      "#1a1a26",
      "#0ac2d8",
    ],
    type: { font: "sans", weight: "700", headlineSize: 1.2, tracking: 0 },
    motion: { spring: false, ease: 0.12 },
  },
  "horizontal-sweep": {
    headline: ["PRINTS FROM", "THE FLAT FILES"],
    headlineWidths: [1506, 1917],
    axis: 0,
    phase: 90,
    direction: 1,
    field: "riso",
    palette: [
      "#e0b64a",
      "#b1512a",
      "#6d7638",
      "#ecdfc2",
      "#2f6b66",
      "#8a3a2b",
      "#d69b3e",
      "#3c4630",
      "#c06e3a",
      "#e6d3a8",
      "#546d76",
      "#7a4726",
    ],
    type: { font: "oldstyle", weight: "700", headlineSize: 1.2, tracking: 0.03 },
    motion: { spring: false, ease: 0.9 },
  },
  "vertical-loop": {
    headline: ["ONE WALL", "TWELVE PLATES"],
    headlineWidths: [1132, 1840],
    axis: 90,
    phase: 0,
    direction: -1,
    field: "halftone",
    palette: [
      "#12110f",
      "#f2efe8",
      "#1c1b18",
      "#e4e0d7",
      "#2b2a26",
      "#d6d1c6",
      "#0a0a09",
      "#faf8f3",
      "#1f1e1a",
      "#eae6dd",
      "#161513",
      "#c0402c",
    ],
    type: { font: "didone", weight: "400", headlineSize: 1.25, tracking: 0.06 },
    motion: { spring: false, ease: 0.55 },
  },
} as const;

const FONTS = {
  heading: "", // resolved from --font-heading at runtime
  serif: '"Times New Roman",Times,"Liberation Serif","Nimbus Roman",serif',
  didone: 'Didot,"Bodoni 72","Bodoni MT","Playfair Display",Georgia,serif',
  oldstyle: '"Iowan Old Style","Palatino Linotype",Palatino,"Book Antiqua",Georgia,serif',
  sans: '"Helvetica Neue",Helvetica,"Inter",Arial,system-ui,sans-serif',
} as const;

export type SalonBannerVariant = keyof typeof VARIANTS;
export type SalonBannerFont = keyof typeof FONTS;

export interface SalonBannerProps {
  className?: string;
  /** Which gallery: tonal (theme plates), or the original matte, glitch, riso and halftone galleries. */
  variant?: SalonBannerVariant;
  /** Two-line headline, split on "\n". Defaults to the variant's own headline. */
  text?: string;
  /** Headline face. Defaults to the variant's face. */
  font?: SalonBannerFont;
  /** Headline weight. Defaults to the variant's weight. */
  weight?: "400" | "700";
  /** Headline size multiplier, 0.6–1.8. Defaults to the variant's size. */
  headlineSize?: number;
  /** Twelve plate colours (any CSS colour). Defaults to the variant's palette; tonal mixes them from the theme. */
  colors?: string[];
  /** Stage colour (any CSS colour). Defaults to hsl(var(--background)). */
  backgroundColor?: string;
  /** Final-frame grade, in degrees. */
  hue?: number;
  saturation?: number;
  brightness?: number;
}

type Ctx = CanvasRenderingContext2D;
type RGB = number[];

/* design frame: 2962 x 2160; every length below is in that space */
const DW = 2962;
const DH = 2160;
const DASP = DW / DH;
const DUR = 15.015; /* one full revolution */
const TS = 512; /* texture resolution */
const HEAD_CAP = 142;
const HEAD_MID = 1093;
const BAYER = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5];

function rng(seed: number) {
  let s = seed >>> 0;
  return () => {
    s ^= s << 13;
    s >>>= 0;
    s ^= s >>> 17;
    s ^= s << 5;
    s >>>= 0;
    return s / 4294967296;
  };
}
function mkc(w: number, h: number) {
  const c = document.createElement("canvas");
  c.width = w;
  c.height = h;
  return c;
}
/* plates arrive as resolved "rgb(r, g, b)" strings */
const rgbOf = (color: string): RGB =>
  (color.match(/[\d.]+/g) ?? ["0", "0", "0"]).slice(0, 3).map(Number);
/* resolves any CSS colour (including hsl(var(--token))) to "rgb(r, g, b)" */
function resolveColor(el: HTMLElement, color: string) {
  const probe = document.createElement("span");
  probe.style.color = color;
  probe.style.display = "none";
  el.appendChild(probe);
  const out = getComputedStyle(probe).color;
  probe.remove();
  return out;
}
const mixRGB = (a: RGB, b: RGB, t: number): RGB => [
  a[0] + (b[0] - a[0]) * t,
  a[1] + (b[1] - a[1]) * t,
  a[2] + (b[2] - a[2]) * t,
];
const cssRGB = (c: RGB) => `rgb(${c[0] | 0},${c[1] | 0},${c[2] | 0})`;
const luma = (c: RGB) => (c[0] * 0.299 + c[1] * 0.587 + c[2] * 0.114) / 255;

/* value noise on a 64x64 lattice, smoothstep-interpolated and wrapped */
function noiseField(seed: number) {
  const g = new Float32Array(4096);
  const r = rng(seed);
  for (let i = 0; i < 4096; i++) g[i] = r();
  return (x: number, y: number) => {
    const x0 = Math.floor(x);
    const y0 = Math.floor(y);
    let fx = x - x0;
    let fy = y - y0;
    fx = fx * fx * (3 - 2 * fx);
    fy = fy * fy * (3 - 2 * fy);
    const ra = (y0 & 63) * 64;
    const rb = ((y0 + 1) & 63) * 64;
    const ca = x0 & 63;
    const cb = (x0 + 1) & 63;
    const a = g[ra + ca];
    const b = g[ra + cb];
    const c = g[rb + ca];
    const d = g[rb + cb];
    return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
  };
}
type Noise = ReturnType<typeof noiseField>;
function fbm(n: Noise, x: number, y: number, oct: number) {
  let v = 0;
  let amp = 0.5;
  let f = 1;
  let tot = 0;
  for (let i = 0; i < oct; i++) {
    v += amp * n(x * f, y * f);
    tot += amp;
    amp *= 0.5;
    f *= 2;
  }
  return v / tot;
}

let grainTileCache: HTMLCanvasElement | null = null;
function grainTile() {
  if (grainTileCache) return grainTileCache;
  const c = mkc(160, 160);
  const x = c.getContext("2d")!;
  const d = x.createImageData(160, 160);
  const r = rng(0x51f3);
  for (let i = 0; i < d.data.length; i += 4) {
    const v = 128 + (r() - 0.5) * 116;
    d.data[i] = d.data[i + 1] = d.data[i + 2] = v;
    d.data[i + 3] = 255;
  }
  x.putImageData(d, 0, 0);
  grainTileCache = c;
  return c;
}
function fill(x: Ctx, style: string) {
  x.fillStyle = style;
  x.fillRect(0, 0, TS, TS);
}
function grain(x: Ctx, alpha: number) {
  x.save();
  x.globalCompositeOperation = "overlay";
  x.globalAlpha = alpha;
  x.fillStyle = x.createPattern(grainTile(), "repeat")!;
  x.fillRect(0, 0, TS, TS);
  x.restore();
}
/* paint a low-resolution field, then blow it up over the whole tile */
function fieldBuffer(N: number, shade: (u: number, v: number, px: number, py: number) => number[]) {
  const buf = mkc(N, N);
  const bx = buf.getContext("2d")!;
  const d = bx.createImageData(N, N);
  for (let py = 0; py < N; py++) {
    for (let px = 0; px < N; px++) {
      const c = shade((px + 0.5) / N, (py + 0.5) / N, px, py);
      const o = (py * N + px) * 4;
      d.data[o] = c[0] | 0;
      d.data[o + 1] = c[1] | 0;
      d.data[o + 2] = c[2] | 0;
      d.data[o + 3] = c.length > 3 ? c[3] | 0 : 255;
    }
  }
  bx.putImageData(d, 0, 0);
  return buf;
}
function blowUp(x: Ctx, buf: HTMLCanvasElement, smooth: boolean, alpha?: number) {
  x.save();
  x.imageSmoothingEnabled = smooth;
  if (alpha !== undefined) x.globalAlpha = alpha;
  x.drawImage(buf, 0, 0, TS, TS);
  x.restore();
}

/* matte — flat colour, one slow rise of noise, fine grain */
function paintMatte(x: Ctx, base: RGB, i: number) {
  const n = noiseField(0x2c41 + i * 9176);
  const hi = mixRGB(base, [255, 255, 255], 0.13);
  const lo = mixRGB(base, [0, 0, 0], 0.15);
  blowUp(
    x,
    fieldBuffer(160, (u, v) => {
      let s = 0.5 + (fbm(n, u * 6.5, v * 6.5, 5) - 0.5) * 1.9 + (v - 0.5) * 0.07;
      s = s < 0 ? 0 : s > 1 ? 1 : s;
      return s < 0.5 ? mixRGB(lo, base, s * 2) : mixRGB(base, hi, (s - 0.5) * 2);
    }),
    true,
  );
  grain(x, 0.1);
}

/* glitch — flat blocks torn from neighbours, rows slipped, channels off register */
function paintGlitch(x: Ctx, base: RGB, i: number, plates: readonly string[]) {
  const r = rng(0x51b7 + i * 30011);
  fill(x, cssRGB(base));
  for (let k = 0; k < 4; k++) {
    x.fillStyle = cssRGB(rgbOf(plates[(i + 1 + ((r() * 5) | 0)) % plates.length]));
    x.fillRect(
      Math.round((r() - 0.2) * TS),
      Math.round(r() * TS),
      Math.round((0.2 + r() * 0.55) * TS),
      Math.round((0.04 + r() * 0.2) * TS),
    );
  }
  blowUp(
    x,
    fieldBuffer(64, () => {
      const w = r() < 0.5 ? 250 : 6;
      return [w, w, w, r() < 0.2 ? 200 : 0];
    }),
    false,
    0.5,
  );
  const snap = mkc(TS, TS);
  snap.getContext("2d")!.drawImage(x.canvas, 0, 0);
  for (let k = 0; k < 11; k++) {
    const y0 = Math.round(r() * TS);
    const h = Math.round((0.01 + r() * 0.06) * TS);
    const dx = Math.round((r() - 0.5) * 0.36 * TS);
    x.clearRect(0, y0, TS, h);
    x.drawImage(snap, 0, y0, TS, h, dx, y0, TS, h);
    x.drawImage(snap, 0, y0, TS, h, dx + (dx < 0 ? TS : -TS), y0, TS, h);
  }
  const channel = (color: string) => {
    const g = mkc(TS, TS);
    const gx = g.getContext("2d")!;
    gx.drawImage(x.canvas, 0, 0);
    gx.globalCompositeOperation = "multiply";
    gx.fillStyle = color;
    gx.fillRect(0, 0, TS, TS);
    return g;
  };
  const red = channel("#ff3050");
  const cyan = channel("#30e0ff");
  x.save();
  x.globalCompositeOperation = "lighter";
  x.globalAlpha = 0.3;
  x.drawImage(red, -0.022 * TS, 0);
  x.drawImage(cyan, 0.022 * TS, 0);
  x.restore();
  x.save();
  x.fillStyle = "rgba(0,0,0,0.22)";
  for (let k = 0; k < TS; k += 4) x.fillRect(0, k, TS, 1);
  x.restore();
  grain(x, 0.24);
}

/* riso — a lit corner and noise quantised to three tones through an ordered dither */
function paintRiso(x: Ctx, base: RGB, i: number) {
  const n = noiseField(0x77a3 + i * 15731);
  const lo = mixRGB(base, [24, 14, 6], 0.66);
  const hi = mixRGB(base, [255, 238, 196], 0.5);
  const cx = 0.22 + (i % 3) * 0.28;
  const cy = 0.2 + ((i / 3) | 0) * 0.2;
  blowUp(
    x,
    fieldBuffer(100, (u, v, px, py) => {
      const d = Math.sqrt((u - cx) * (u - cx) + (v - cy) * (v - cy));
      const s = (1 - d * 1.25) * 0.72 + fbm(n, u * 3.2, v * 3.2, 3) * 0.52 - 0.1;
      const band = Math.floor(s * 2.4 + (BAYER[(py & 3) * 4 + (px & 3)] + 0.5) / 16);
      return band <= 0 ? lo : band === 1 ? base : hi;
    }),
    false,
  );
  x.save();
  x.fillStyle = "rgba(28,14,4,0.18)";
  for (let k = 0; k < TS; k += 6) x.fillRect(0, k, TS, 2);
  x.restore();
  grain(x, 0.22);
}

/* halftone — one ink on one stock, shaded only by dot size */
function paintHalftone(x: Ctx, base: RGB, i: number) {
  const n = noiseField(0x3f19 + i * 21467);
  fill(x, cssRGB(base));
  const dot = luma(base) > 0.5 ? mixRGB(base, [0, 0, 0], 0.88) : mixRGB(base, [255, 255, 255], 0.9);
  const pitch = TS / 30;
  const a = ((17 + (i % 4) * 9) * Math.PI) / 180;
  const ca = Math.cos(a);
  const sa = Math.sin(a);
  const span = Math.ceil(TS / pitch);
  x.save();
  x.fillStyle = cssRGB(dot);
  x.translate(TS / 2, TS / 2);
  x.rotate(a);
  for (let gy = -span; gy <= span; gy++) {
    for (let gx = -span; gx <= span; gx++) {
      const wx = gx * pitch;
      const wy = gy * pitch;
      const u = (wx * ca - wy * sa) / TS + 0.5;
      const v = (wx * sa + wy * ca) / TS + 0.5;
      if (u < -0.1 || u > 1.1 || v < -0.1 || v > 1.1) continue;
      const s = fbm(n, u * 2.7, v * 2.7, 4) * 0.95 + (0.55 - v) * 0.5;
      const rad = pitch * 0.66 * (s < 0 ? 0 : s > 1 ? 1 : s);
      if (rad < 0.4) continue;
      x.beginPath();
      x.arc(wx, wy, rad, 0, Math.PI * 2);
      x.fill();
    }
  }
  x.restore();
  grain(x, 0.12);
}

function roundRectPath(x: Ctx, w: number, h: number, r: number) {
  x.beginPath();
  x.moveTo(-w / 2 + r, -h / 2);
  x.lineTo(w / 2 - r, -h / 2);
  x.quadraticCurveTo(w / 2, -h / 2, w / 2, -h / 2 + r);
  x.lineTo(w / 2, h / 2 - r);
  x.quadraticCurveTo(w / 2, h / 2, w / 2 - r, h / 2);
  x.lineTo(-w / 2 + r, h / 2);
  x.quadraticCurveTo(-w / 2, h / 2, -w / 2, h / 2 - r);
  x.lineTo(-w / 2, -h / 2 + r);
  x.quadraticCurveTo(-w / 2, -h / 2, -w / 2 + r, -h / 2);
  x.closePath();
}

/* draw text whose inked box matches a cap height and (optional) width */
function fitText(
  x: Ctx,
  str: string,
  font: string,
  weight: string,
  cap: number,
  cx: number,
  capTop: number,
  targetW: number,
  color: string,
) {
  const probe = 100;
  x.font = `${weight} ${probe}px ${font}`;
  const m = x.measureText("H");
  const capUnit = (m.actualBoundingBoxAscent || 71) / probe;
  const size = cap / capUnit;
  x.font = `${weight} ${size}px ${font}`;
  const mm = x.measureText(str);
  const inkW = (mm.actualBoundingBoxRight || mm.width) + (mm.actualBoundingBoxLeft || 0);
  const sx = targetW ? targetW / inkW : 1;
  x.save();
  x.fillStyle = color;
  x.textBaseline = "alphabetic";
  x.translate(cx, capTop + cap);
  x.scale(sx, 1);
  x.textAlign = "center";
  x.fillText(str, 0, 0);
  x.restore();
}

export function SalonBanner({
  className,
  variant = "tonal",
  text,
  font,
  weight,
  headlineSize,
  colors,
  backgroundColor,
  hue = 0,
  saturation = 1,
  brightness = 1,
}: SalonBannerProps) {
  const prefersReducedMotion = useReducedMotion();
  const hostRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const v = VARIANTS[variant] ?? VARIANTS.tonal;
  const background = backgroundColor ?? "hsl(var(--background))";
  const plateKey = (colors ?? v.palette ?? []).join("|");
  /* re-resolve the theme tokens whenever the mode or palette on <html> changes */
  const [theme, setTheme] = useState(0);
  useEffect(() => {
    const mo = new MutationObserver(() => setTheme((t) => t + 1));
    mo.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "data-theme", "data-palette", "style"],
    });
    return () => mo.disconnect();
  }, []);

  useEffect(() => {
    const host = hostRef.current;
    const cv = canvasRef.current;
    if (!host || !cv) return;
    const ctx = cv.getContext("2d");
    if (!ctx) return;

    const token = (name: string) => rgbOf(resolveColor(host, `hsl(var(--${name}))`));
    const fg = token("foreground");
    const bg = token("background");
    const pr = token("primary");
    const mu = token("muted");
    /* tonal plates: a ladder from the page through muted and primary to the ink */
    const TONAL = [
      mixRGB(bg, pr, 0.12),
      mixRGB(pr, fg, 0.4),
      mixRGB(mu, pr, 0.35),
      pr,
      mixRGB(bg, mu, 0.7),
      mixRGB(pr, bg, 0.45),
      mixRGB(fg, bg, 0.12),
      mixRGB(mu, fg, 0.25),
      mixRGB(pr, bg, 0.7),
      mixRGB(pr, fg, 0.7),
      mixRGB(bg, pr, 0.3),
      mixRGB(mu, bg, 0.4),
    ].map(cssRGB);
    const PLATES = plateKey ? plateKey.split("|").map((c) => resolveColor(host, c)) : TONAL;
    const BG = resolveColor(host, background);
    const ink = [
      resolveColor(host, "hsl(var(--muted-foreground))"),
      resolveColor(host, "hsl(var(--foreground))"),
      BG,
    ];
    const fontKey = font ?? v.type.font;
    const SANS = fontKey === "heading" ? getComputedStyle(cv).fontFamily : FONTS[fontKey];
    const HEAD_WEIGHT = weight ?? v.type.weight;
    const HEAD_SIZE = Math.max(0.6, Math.min(1.8, headlineSize ?? v.type.headlineSize));
    const HEAD_TRACK = v.type.tracking;
    const HEAD_STYLE = v.field;
    const HEAD_SHADOW = ink[2];
    const HEAD_GHOST = [cssRGB(pr), resolveColor(host, "hsl(var(--muted-foreground))")];
    const EASE = v.motion.ease;
    const SPRING = v.motion.spring;
    const SPRING_K = 26;
    const SPRING_D = 5.7;
    const custom = text?.split("\n");
    const HEAD = [
      {
        s: custom ? (custom[0] ?? "") : v.headline[0],
        top: 930,
        w: custom ? 0 : v.headlineWidths[0],
        fill: ink[0],
      },
      {
        s: custom ? (custom[1] ?? "") : v.headline[1],
        top: 1114,
        w: custom ? 0 : v.headlineWidths[1],
        fill: ink[1],
      },
    ];
    const RING = {
      cx: 1484,
      cy: 1108,
      a: 712,
      ratio: 0.492,
      axis: v.axis,
      n: 12,
      tile: 346,
      aspect: 0.75 /* 4:3 landscape crop */,
      radius: 0.22,
      dist: 13,
      phase: v.phase,
    };

    /* plates: front face, and a darker washed-out reverse */
    const painter = (x: Ctx, i: number) => {
      const base = rgbOf(PLATES[i]);
      if (HEAD_STYLE === "glitch") paintGlitch(x, base, i, PLATES);
      else if (HEAD_STYLE === "riso") paintRiso(x, base, i);
      else if (HEAD_STYLE === "halftone") paintHalftone(x, base, i);
      else paintMatte(x, base, i);
    };
    const front: HTMLCanvasElement[] = [];
    const back: HTMLCanvasElement[] = [];
    for (let i = 0; i < PLATES.length; i++) {
      const c = mkc(TS, TS);
      painter(c.getContext("2d")!, i);
      front.push(c);
      const d = mkc(TS, TS);
      const y = d.getContext("2d")!;
      y.drawImage(c, 0, 0);
      y.globalCompositeOperation = "saturation";
      y.fillStyle = "rgba(128,128,128,0.2)";
      y.fillRect(0, 0, TS, TS);
      y.globalCompositeOperation = "multiply";
      y.fillStyle = "rgba(10,12,24,0.45)";
      y.fillRect(0, 0, TS, TS);
      back.push(d);
    }

    const ax = (RING.axis * Math.PI) / 180;
    const cf = RING.ratio;
    const sf = Math.sqrt(1 - cf * cf);
    const U = [Math.cos(ax), Math.sin(ax), 0];
    const V = [-Math.sin(ax) * cf, Math.cos(ax) * cf, sf];
    const AXIS = [U[1] * V[2] - U[2] * V[1], U[2] * V[0] - U[0] * V[2], U[0] * V[1] - U[1] * V[0]];

    let W = 0;
    let H = 0;
    let K = 1;
    let OX = 0;
    let OY = 0;
    let headLayer: HTMLCanvasElement = mkc(1, 1);
    const d2sx = (x: number) => OX + x * K;
    const d2sy = (y: number) => OY + y * K;

    function headPass(x: Ctx, dx: number, dy: number, tint: string | null) {
      for (const h of HEAD) {
        fitText(
          x,
          h.s,
          SANS,
          HEAD_WEIGHT,
          HEAD_CAP * HEAD_SIZE * K,
          d2sx(1481) + dx,
          d2sy(HEAD_MID + (h.top - HEAD_MID) * HEAD_SIZE) + dy,
          h.w * HEAD_SIZE * K,
          tint || h.fill,
        );
      }
    }
    function headGlitch(x: Ctx) {
      const w = headLayer.width;
      const h = headLayer.height;
      const snap = mkc(w, h);
      snap.getContext("2d")!.drawImage(headLayer, 0, 0);
      const r = rng(0x2e51);
      const top = d2sy(HEAD_MID) - HEAD_CAP * HEAD_SIZE * K * 2.1;
      const span = HEAD_CAP * HEAD_SIZE * K * 4.2;
      for (let i = 0; i < 7; i++) {
        const sy = Math.round(top + r() * span);
        const sh = Math.round((0.03 + r() * 0.11) * HEAD_CAP * HEAD_SIZE * K);
        const dx = Math.round((r() - 0.5) * 0.08 * w);
        x.clearRect(0, sy, w, sh);
        x.drawImage(snap, 0, sy, w, sh, dx, sy, w, sh);
      }
      const ghost = (color: string) => {
        const g = mkc(w, h);
        const gx = g.getContext("2d")!;
        gx.drawImage(snap, 0, 0);
        gx.globalCompositeOperation = "source-in";
        gx.fillStyle = color;
        gx.fillRect(0, 0, w, h);
        return g;
      };
      const off = 0.05 * HEAD_CAP * HEAD_SIZE * K;
      x.save();
      x.globalCompositeOperation = "destination-over";
      x.globalAlpha = 0.9;
      x.drawImage(ghost(HEAD_GHOST[0]), -off, 0);
      x.drawImage(ghost(HEAD_GHOST[1]), off, 0);
      x.restore();
    }
    function buildHead() {
      headLayer = mkc(Math.max(1, W), Math.max(1, H));
      const x = headLayer.getContext("2d")!;
      if (x.letterSpacing !== undefined)
        x.letterSpacing = `${(HEAD_TRACK * HEAD_CAP * HEAD_SIZE * K).toFixed(2)}px`;
      if (HEAD_STYLE === "riso") {
        const off = 0.055 * HEAD_CAP * HEAD_SIZE * K;
        headPass(x, off, off, HEAD_SHADOW);
      }
      headPass(x, 0, 0, null);
      if (HEAD_STYLE === "glitch") headGlitch(x);
    }
    function resize() {
      const dpr = Math.min(window.devicePixelRatio || 1, 2);
      W = Math.max(1, Math.round(host!.clientWidth * dpr));
      H = Math.max(1, Math.round(host!.clientHeight * dpr));
      cv!.width = W;
      cv!.height = H;
      const S = Math.min(W, H * DASP);
      K = S / DW;
      OX = (W - DW * K) / 2;
      OY = (H - DH * K) / 2;
      buildHead();
    }
    function project(p: number[]) {
      const k = (RING.a * K * RING.dist) / (RING.dist - p[2]);
      return [d2sx(RING.cx) + k * p[0], d2sy(RING.cy) + k * p[1], k];
    }
    function drawTile(i: number, psi: number) {
      const c = Math.cos(psi);
      const s = Math.sin(psi);
      const C = [c * U[0] + s * V[0], c * U[1] + s * V[1], c * U[2] + s * V[2]];
      const T = [-s * U[0] + c * V[0], -s * U[1] + c * V[1], -s * U[2] + c * V[2]];
      const h = RING.tile / (2 * RING.a);
      const p0 = project(C);
      const pT = project([C[0] + T[0] * h, C[1] + T[1] * h, C[2] + T[2] * h]);
      const pA = project([C[0] + AXIS[0] * h, C[1] + AXIS[1] * h, C[2] + AXIS[2] * h]);
      const ex = pT[0] - p0[0];
      const ey = pT[1] - p0[1];
      const fx = pA[0] - p0[0];
      const fy = pA[1] - p0[1];
      if (Math.abs(ex * fy - ey * fx) < 0.4) return;
      const img = (C[2] > 0 ? front : back)[i % front.length];
      ctx!.save();
      ctx!.setTransform((ex * 2) / TS, (ey * 2) / TS, (fx * 2) / TS, (fy * 2) / TS, p0[0], p0[1]);
      roundRectPath(ctx!, TS, TS * RING.aspect, TS * RING.aspect * RING.radius);
      ctx!.clip();
      ctx!.drawImage(img, -TS / 2, -TS / 2, TS, TS);
      ctx!.restore();
      ctx!.setTransform(1, 0, 0, 1, 0, 0);
    }
    function render(t: number) {
      ctx!.setTransform(1, 0, 0, 1, 0, 0);
      ctx!.fillStyle = BG;
      ctx!.fillRect(0, 0, W, H);
      ctx!.imageSmoothingQuality = "high";
      const spin = (t / DUR) * Math.PI * 2 * v.direction;
      const list: { i: number; psi: number; z: number }[] = [];
      for (let i = 0; i < RING.n; i++) {
        const psi = (RING.phase * Math.PI) / 180 - (i * 2 * Math.PI) / RING.n + spin;
        list.push({ i, psi, z: Math.cos(psi) * U[2] + Math.sin(psi) * V[2] });
      }
      list.sort((a, b) => a.z - b.z);
      let drawnText = false;
      for (const item of list) {
        if (!drawnText && item.z > 0) {
          ctx!.drawImage(headLayer, 0, 0);
          drawnText = true;
        }
        drawTile(item.i, item.psi);
      }
      if (!drawnText) ctx!.drawImage(headLayer, 0, 0);
    }

    /* the ring rests, and orbits only while a pointer is over it; matte is sprung */
    let tNow = 0;
    let hovering = false;
    let rate = 0;
    let vel = 0;
    let settled = false;
    let last = performance.now();
    let raf = 0;
    let visible = true;
    const reduce = !!prefersReducedMotion;
    const setHover = (state: boolean) => {
      if (hovering === state || reduce) return;
      hovering = state;
      settled = false;
      start();
    };
    function frame(now: number) {
      raf = 0;
      const dt = Math.min(0.05, Math.max(0, (now - last) / 1000));
      last = now;
      if (SPRING) {
        vel += (((hovering ? 1 : 0) - rate) * SPRING_K - vel * SPRING_D) * dt;
        rate += vel * dt;
      } else {
        rate += ((hovering ? 1 : 0) - rate) * (1 - Math.exp(-dt / EASE));
      }
      if (Math.abs(rate) > 0.0004 || Math.abs(vel) > 0.0004) {
        tNow = (((tNow + dt * rate) % DUR) + DUR) % DUR;
        render(tNow);
        settled = false;
      } else if (!settled) {
        rate = 0;
        vel = 0;
        render(tNow);
        settled = true;
      }
      if (!settled || hovering) raf = requestAnimationFrame(frame);
    }
    function start() {
      if (raf || !visible || document.hidden) return;
      last = performance.now();
      raf = requestAnimationFrame(frame);
    }
    function stop() {
      if (raf) cancelAnimationFrame(raf);
      raf = 0;
    }

    const onEnter = () => setHover(true);
    const onLeave = () => setHover(false);
    host.addEventListener("pointerenter", onEnter);
    host.addEventListener("pointermove", onEnter);
    host.addEventListener("pointerdown", onEnter);
    host.addEventListener("pointerleave", onLeave);
    host.addEventListener("pointercancel", onLeave);
    window.addEventListener("blur", onLeave);

    resize();
    render(tNow);
    const ro = new ResizeObserver(() => {
      resize();
      render(tNow);
    });
    ro.observe(host);
    const io = new IntersectionObserver(([entry]) => {
      visible = entry.isIntersecting;
      if (visible && (hovering || !settled)) start();
      else if (!visible) stop();
    });
    io.observe(host);
    const onVisibility = () => (document.hidden ? stop() : start());
    document.addEventListener("visibilitychange", onVisibility);

    return () => {
      stop();
      ro.disconnect();
      io.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      host.removeEventListener("pointerenter", onEnter);
      host.removeEventListener("pointermove", onEnter);
      host.removeEventListener("pointerdown", onEnter);
      host.removeEventListener("pointerleave", onLeave);
      host.removeEventListener("pointercancel", onLeave);
      window.removeEventListener("blur", onLeave);
    };
  }, [v, theme, background, plateKey, text, font, weight, headlineSize, prefersReducedMotion]);

  const safeHue = Math.min(180, Math.max(-180, hue));
  const safeSaturation = Math.min(2, Math.max(0, saturation));
  const safeBrightness = Math.min(1.65, Math.max(0.35, brightness));
  const filter =
    safeHue === 0 && safeSaturation === 1 && safeBrightness === 1
      ? undefined
      : `hue-rotate(${safeHue}deg) saturate(${safeSaturation}) brightness(${safeBrightness})`;
  const headline = text ?? v.headline.join("\n");

  return (
    <div
      ref={hostRef}
      className={cn("absolute inset-0 h-full w-full overflow-hidden", className)}
      style={{ background, filter }}
    >
      <canvas ref={canvasRef} aria-hidden="true" className="block h-full w-full font-serif" />
      <h2 className="sr-only">{headline.replace(/\n/g, " ")}</h2>
    </div>
  );
}
```

---

# Button Atlas

> Twenty-two rectangle buttons and animated CTAs, each drawn from your theme tokens and set in the Modus type.

Install: `npx @modus-ui/cli add button-atlas`

One button family with 22 treatments, from pressable keycaps and launch keys to dashed dot borders, rotating beams and glass pills. Every colour comes from the theme tokens (`--primary`, `--primary-foreground`, `--foreground`, `--card`, `--border`, `--muted`), so each button follows light and dark mode and the active palette without configuration. Labels use the Modus faces: mono caps, body sans and the italic heading serif. Each variant keeps its own hover, focus and press motion, and animations stop when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add button-atlas
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/button-atlas.tsx`.
3. Paste the code.

## Usage

```tsx
import { ButtonAtlas } from "@/components/ui/button-atlas";

export default function Example() {
  return (
    <div className="h-[300px] w-full">
      <ButtonAtlas variant="meridian-keycap-primary" label="Add to project" />
    </div>
  );
}
```

## Variants

`dark-pill`, `launch-button`, `dot-border-button`, `floating-dots-cta`, `sliding-text-cta`, `gradient-beam-cta`, `gradient-pill-button`, `generate-button`, `glassmorphism-cta`, `spinning-border-button`, `gradient-cta`, `lumen-cta`, `lumen-cta-ghost`, `trochil-signal`, `attune-thermal`, `tideform-outline`, `understory-arrow-pill`, `meridian-keycap-primary`, `meridian-keycap-secondary`, `halvorsen-arrow-pill`, `aster-glass-access`, `aster-glass-arrow`.

## Props

| Prop          | Type                             | Default                                                                               | Description                                                         |
| :------------ | :------------------------------- | :------------------------------------------------------------------------------------ | :------------------------------------------------------------------ |
| `variant`     | `ButtonAtlasVariant`             | `"meridian-keycap-primary"`                                                           | Which of the 22 treatments to render.                               |
| `label`       | `string`                         | Each variant's default copy                                                           | Button text.                                                        |
| `activeLabel` | `string`                         | `"Composing"`                                                                         | Text the Generate variant resolves to while focused.                |
| `hue`         | `number`                         | `0`                                                                                   | Hue rotation in degrees (-180 to 180).                              |
| `saturation`  | `number`                         | `1`                                                                                   | Saturation multiplier (0 to 2).                                     |
| `brightness`  | `number`                         | `1`                                                                                   | Brightness multiplier (0.35 to 1.65).                               |
| `background`  | `string`                         | `undefined`                                                                           | Stage background. Transparent by default, so it sits on its parent. |
| `avatarSrc`   | `string`                         | `"https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=128&h=128&fit=crop"` | Portrait shown in the Glassmorphism CTA.                            |
| `avatarAlt`   | `string`                         | `"Reviewer headshot"`                                                                 | Alt text for the portrait.                                          |
| `onClick`     | `MouseEventHandler<HTMLElement>` | `undefined`                                                                           | Click handler.                                                      |

## Source

`components/ui/button-atlas.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Rectangle Buttons (MIT, © 2026 Meng To).

import type { CSSProperties, MouseEventHandler, ReactNode } from "react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export const BUTTON_ATLAS_VARIANTS = [
  "ink-capsule",
  "keystroke-button",
  "stitch-frame-button",
  "rising-motes",
  "roll-label",
  "comet-ring-button",
  "satin-capsule",
  "conjure-button",
  "halo-invite",
  "halo-trace",
  "glaze-button",
  "ink-pill",
  "lumen-cta-ghost",
  "sheen-cta",
  "kiln-button",
  "hairline-cta",
  "orbit-chip-button",
  "meridian-keycap-primary",
  "meridian-keycap-secondary",
  "ink-endcap-button",
  "aster-glass-access",
  "aster-glass-arrow",
] as const;

export type ButtonAtlasVariant = (typeof BUTTON_ATLAS_VARIANTS)[number];

export interface ButtonAtlasProps {
  /** Which of the 22 treatments to render. Every one is drawn from the theme tokens. */
  variant?: ButtonAtlasVariant;
  /** Button text. Each variant has its own default copy when omitted. */
  label?: string;
  /** Second label the Generate variant resolves to while focused. */
  activeLabel?: string;
  hue?: number;
  saturation?: number;
  brightness?: number;
  /** Stage background behind the button. Transparent by default, so it sits on its parent. */
  background?: string;
  /** Portrait shown in the Glassmorphism CTA. */
  avatarSrc?: string;
  avatarAlt?: string;
  onClick?: MouseEventHandler<HTMLElement>;
  className?: string;
}

const clamp = (value: number, minimum: number, maximum: number) =>
  Math.min(maximum, Math.max(minimum, value));

const DEFAULT_LABELS: Record<ButtonAtlasVariant, string> = {
  "ink-capsule": "Explore",
  "keystroke-button": "Ship it",
  "stitch-frame-button": "Draft a layout",
  "rising-motes": "Join the list",
  "roll-label": "Browse components",
  "comet-ring-button": "Install",
  "satin-capsule": "Read the docs",
  "conjure-button": "Compose",
  "halo-invite": "Book a review",
  "halo-trace": "View source",
  "glaze-button": "Send invite",
  "ink-pill": "Get started",
  "lumen-cta-ghost": "Learn more",
  "sheen-cta": "Request access",
  "kiln-button": "Continue",
  "hairline-cta": "Index",
  "orbit-chip-button": "Next chapter",
  "meridian-keycap-primary": "Add to project",
  "meridian-keycap-secondary": "Copy command",
  "ink-endcap-button": "Open the kit",
  "aster-glass-access": "Sign in",
  "aster-glass-arrow": "Take a tour",
};

/* ------------------------------------------------------------------ *
 * Scoped styles. Every rule is prefixed `mrb-` so variants never leak.
 * Colours come only from the theme tokens (bare HSL channels), so each
 * treatment follows light/dark mode and the active palette.
 * ------------------------------------------------------------------ */
const STYLES = `
.mrb-stage { --mrb-sans: var(--font-body, ui-sans-serif), system-ui, sans-serif; --mrb-serif: var(--font-heading, ui-serif), Georgia, serif; --mrb-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; --mrb-tint: color-mix(in oklab, hsl(var(--primary)) 55%, white); --mrb-shade: color-mix(in oklab, hsl(var(--primary)) 62%, black); position: relative; display: grid; width: 100%; height: 100%; place-items: center; overflow: hidden; isolation: isolate; color: hsl(var(--foreground)); font-family: var(--mrb-sans); -webkit-font-smoothing: antialiased; }
.mrb-still, .mrb-still *, .mrb-still *::before, .mrb-still *::after { animation: none !important; transition: none !important; }
.mrb-stage button:focus-visible, .mrb-stage a:focus-visible { outline: 2px solid hsl(var(--ring)); outline-offset: 4px; }

/* Glass pill */
.mrb-glass-btn { position: relative; display: inline-flex; align-items: center; justify-content: center; height: 52px; padding: 0 34px; overflow: hidden; border: 0; border-radius: 999px; color: hsl(var(--foreground) / .8); background: transparent; font-family: var(--mrb-serif); font-size: 21px; font-style: italic; line-height: 1; cursor: pointer; transition: color .3s, transform .2s; }
.mrb-glass-btn::before, .mrb-glass-btn::after { position: absolute; inset: 0; border-radius: inherit; content: ""; }
.mrb-glass-btn::before { background: hsl(var(--card) / .75); box-shadow: inset 2px 4px 16px hsl(var(--foreground) / .06), 0 10px 26px -14px hsl(var(--foreground) / .45); -webkit-backdrop-filter: blur(30px); backdrop-filter: blur(30px); }
.mrb-glass-btn::after { z-index: 2; border: 1px solid hsl(var(--border)); pointer-events: none; }
.mrb-glass-title { position: relative; z-index: 4; }
.mrb-glass-circle { position: absolute; z-index: 3; top: calc(50% - 100px); left: calc(50% - 100px); width: 200px; height: 200px; pointer-events: none; }
.mrb-glass-circle::before, .mrb-glass-circle::after { position: absolute; inset: 0; border-radius: 50%; content: ""; }
.mrb-glass-circle::before { background: conic-gradient(from 180deg, hsl(var(--primary) / .02) 180deg, hsl(var(--primary) / .28) 360deg); filter: blur(15px); animation: mrb-glass-circle 3.6s linear infinite; transition: opacity .5s; }
.mrb-glass-circle::after { inset: 30px; background: hsl(var(--primary) / .3); opacity: 0; filter: blur(6px); transform: scale(.5); transition: opacity .5s, transform .7s; -webkit-mask-image: radial-gradient(50% 50%, black, transparent); mask-image: radial-gradient(50% 50%, black, transparent); }
.mrb-glass-btn:hover { color: hsl(var(--foreground)); }
.mrb-glass-btn:hover .mrb-glass-circle::before { opacity: 0; }
.mrb-glass-btn:hover .mrb-glass-circle::after { opacity: 1; transform: scale(1); }
.mrb-glass-btn:active { transform: scale(.98); }
@keyframes mrb-glass-circle { 0% { transform: translate(0) rotate(0); } 25% { transform: translateX(-30px) rotate(90deg); } 50% { transform: translate(0) rotate(180deg); } 75% { transform: translateX(30px) rotate(270deg); } 100% { transform: translate(0) rotate(360deg); } }

/* Launch key */
.mrb-launch { position: relative; border: 0; background: none; padding: 0; cursor: pointer; font: inherit; }
.mrb-launch-glow { position: absolute; inset: -4px; border-radius: 14px; background: hsl(var(--primary) / .4); opacity: .4; filter: blur(8px); transition: opacity .5s; }
.mrb-launch:hover .mrb-launch-glow { opacity: .75; }
.mrb-launch-face { position: relative; display: flex; align-items: center; gap: 12px; padding: 15px 30px; border-radius: 12px; color: hsl(var(--primary-foreground)); background: linear-gradient(180deg, var(--mrb-tint), hsl(var(--primary)) 55%, var(--mrb-shade)); box-shadow: 0 0 0 1px hsl(var(--primary) / .5), 0 4px 0 var(--mrb-shade), 0 10px 15px -3px hsl(var(--foreground) / .35); font-family: var(--mrb-mono); font-size: 13px; font-weight: 600; letter-spacing: .16em; text-transform: uppercase; transition: transform .15s, box-shadow .15s; }
.mrb-launch:active .mrb-launch-face { transform: translateY(2px); box-shadow: 0 0 0 1px hsl(var(--primary) / .5), 0 2px 0 var(--mrb-shade); }
.mrb-launch svg { width: 18px; height: 18px; fill: hsl(var(--primary-foreground) / .2); stroke: currentColor; stroke-width: 1.5; }

/* Dot Border Button */
.mrb-db-wrapper { --dot-size: 8px; --line-weight: 1px; --line-distance: 0.8rem 1rem; --animation-speed: 0.35s; --dot-color: hsl(var(--primary)); --grid-color: hsl(var(--border)); position: relative; display: inline-flex; justify-content: center; align-items: center; padding: var(--line-distance); user-select: none; isolation: isolate; }
.mrb-db-wrapper::after { content: ""; position: absolute; top: 0; left: 0; width: 100%; height: 100%; border-radius: inherit; pointer-events: none; background-image: repeating-linear-gradient(45deg, hsl(var(--primary) / .22) 0 1px, transparent 2px 5px); opacity: 0; z-index: -1; }
.mrb-db-wrapper:has(.mrb-db-btn:hover)::after { animation: mrb-db-opacity calc(var(--animation-speed) * 4) ease-in-out forwards; }
@keyframes mrb-db-opacity { 80% { opacity: 0; } 100% { opacity: 1; } }
.mrb-db-btn { position: relative; display: flex; justify-content: center; align-items: center; padding: 0.8rem 1.25rem; white-space: nowrap; background-color: hsl(var(--card)); border: 1px solid var(--grid-color); color: hsl(var(--foreground)); font-family: var(--mrb-sans); letter-spacing: -0.01em; font-size: 1rem; font-weight: 600; line-height: 1.5; border-radius: 6px; cursor: pointer; transition: transform .2s ease-in-out, letter-spacing .2s ease-in-out, background-color .2s, color .2s; }
.mrb-db-btn:hover, .mrb-db-btn:active { background-color: hsl(var(--primary)); color: hsl(var(--primary-foreground)); transform: scale(1.05); letter-spacing: .04em; }
.mrb-db-btn:active { transform: scale(.98); }
.mrb-db-svg { margin-left: .5rem; height: 24px; stroke-width: 1; stroke-linecap: round; stroke-linejoin: round; stroke: hsl(var(--muted-foreground)); fill: hsl(var(--muted)); transition: all .2s ease-in-out; }
.mrb-db-btn:hover .mrb-db-svg { stroke: hsl(var(--primary-foreground)); fill: hsl(var(--primary-foreground) / .2); }
.mrb-db-dot { position: absolute; width: var(--dot-size); aspect-ratio: 1; border-radius: 2px; background-color: var(--dot-color); transition: all .3s ease-in-out; opacity: 0; }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-dot.mrb-db-top.mrb-db-left { top: 50%; left: 20%; animation: mrb-db-tl var(--animation-speed) ease-in-out forwards; }
@keyframes mrb-db-tl { 90% { opacity: .6; } 100% { top: calc(var(--dot-size) * -0.5); left: calc(var(--dot-size) * -0.5); opacity: 1; } }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-dot.mrb-db-top.mrb-db-right { top: 50%; right: 20%; animation: mrb-db-tr var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * .6); }
@keyframes mrb-db-tr { 80% { opacity: .6; } 100% { top: calc(var(--dot-size) * -0.5); right: calc(var(--dot-size) * -0.5); opacity: 1; } }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-dot.mrb-db-bottom.mrb-db-right { bottom: 50%; right: 20%; animation: mrb-db-br var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * 1.2); }
@keyframes mrb-db-br { 80% { opacity: .6; } 100% { bottom: calc(var(--dot-size) * -0.5); right: calc(var(--dot-size) * -0.5); opacity: 1; } }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-dot.mrb-db-bottom.mrb-db-left { bottom: 50%; left: 20%; animation: mrb-db-bl var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * 1.8); }
@keyframes mrb-db-bl { 80% { opacity: .6; } 100% { bottom: calc(var(--dot-size) * -0.5); left: calc(var(--dot-size) * -0.5); opacity: 1; } }
.mrb-db-line { position: absolute; transition: all .3s ease-in-out; }
.mrb-db-line.mrb-db-h { height: var(--line-weight); width: 100%; background-image: repeating-linear-gradient(90deg, transparent 0 calc(var(--line-weight) * 2), var(--dot-color) calc(var(--line-weight) * 2) calc(var(--line-weight) * 4)); }
.mrb-db-line.mrb-db-top { top: calc(var(--line-weight) * -0.5); transform-origin: top left; transform: rotate(5deg) scaleX(0); }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-line.mrb-db-top { animation: mrb-db-draw-top var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * .8); }
@keyframes mrb-db-draw-top { 100% { transform: rotate(0deg) scaleX(1); } }
.mrb-db-line.mrb-db-bottom { bottom: calc(var(--line-weight) * -0.5); transform-origin: bottom right; transform: rotate(5deg) scaleX(0); }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-line.mrb-db-bottom { animation: mrb-db-draw-bottom var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * 2); }
@keyframes mrb-db-draw-bottom { 100% { transform: rotate(0deg) scaleX(1); } }
.mrb-db-line.mrb-db-v { width: var(--line-weight); height: 100%; background-image: repeating-linear-gradient(0deg, transparent 0 calc(var(--line-weight) * 2), var(--dot-color) calc(var(--line-weight) * 2) calc(var(--line-weight) * 4)); }
.mrb-db-line.mrb-db-left { left: calc(var(--line-weight) * -0.5); transform-origin: bottom left; transform: rotate(0deg) scaleY(0); }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-line.mrb-db-left { animation: mrb-db-draw-left var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * 2.4); }
@keyframes mrb-db-draw-left { 100% { transform: rotate(0deg) scaleY(1); } }
.mrb-db-line.mrb-db-right { right: calc(var(--line-weight) * -0.5); transform-origin: top right; transform: rotate(5deg) scaleY(0); }
.mrb-db-wrapper:has(.mrb-db-btn:hover) .mrb-db-line.mrb-db-right { animation: mrb-db-draw-right var(--animation-speed) ease-in-out forwards; animation-delay: calc(var(--animation-speed) * 1.4); }
@keyframes mrb-db-draw-right { 100% { transform: rotate(0deg) scaleY(1); } }

/* Floating Dots CTA */
.mrb-fd { --mrb-fd-fill: radial-gradient(65% 65% at 50% 100%, color-mix(in oklab, var(--mrb-tint) 80%, transparent) 0%, transparent 100%), hsl(var(--primary)); cursor: pointer; position: relative; display: inline-flex; align-items: center; justify-content: center; overflow: hidden; transition: all 0.25s ease; background: var(--mrb-fd-fill); border-radius: 0.75rem; border: none; outline: none; padding: 12px 20px; min-height: 48px; min-width: 102px; font: inherit; }
.mrb-fd::before, .mrb-fd::after { content: ""; position: absolute; transition: all 0.5s ease-in-out; z-index: 0; }
.mrb-fd::before { inset: 1px; border-radius: calc(0.75rem - 1px); background: linear-gradient(178deg, rgb(255 255 255 / .22) 0%, transparent 100%); }
.mrb-fd::after { inset: 2px; border-radius: calc(0.75rem - 2px); background: var(--mrb-fd-fill); }
.mrb-fd:active { transform: scale(0.95); }
.mrb-fd-points { overflow: hidden; width: 100%; height: 100%; pointer-events: none; position: absolute; z-index: 1; }
.mrb-fd-point { bottom: -10px; position: absolute; animation: mrb-fd-floating infinite ease-in-out; pointer-events: none; width: 2px; height: 2px; background-color: hsl(var(--primary-foreground)); border-radius: 9999px; }
@keyframes mrb-fd-floating { 0% { transform: translateY(0); } 85% { opacity: 0; } 100% { transform: translateY(-55px); opacity: 0; } }
.mrb-fd-inner { z-index: 2; gap: 6px; position: relative; width: 100%; color: hsl(var(--primary-foreground)); display: inline-flex; align-items: center; justify-content: center; font-family: var(--mrb-sans); font-size: 16px; font-weight: 500; line-height: 1.5; }
.mrb-fd-icon { width: 18px; height: 18px; transition: transform 0.3s ease; stroke: currentColor; fill: none; }
.mrb-fd:hover .mrb-fd-icon { transform: translateX(2px); }
.mrb-fd:hover .mrb-fd-icon path { animation: mrb-fd-dash 0.8s linear forwards; }
@keyframes mrb-fd-dash { 0% { stroke-dasharray: 0, 20; stroke-dashoffset: 0; } 50% { stroke-dasharray: 10, 10; stroke-dashoffset: -5; } 100% { stroke-dasharray: 20, 0; stroke-dashoffset: -10; } }

/* Gradient Beam CTA */
@keyframes mrb-gb-spin { to { transform: rotate(360deg); } }
@keyframes mrb-gb-dots { 0% { background-position: 0 0; } 100% { background-position: 24px 24px; } }

/* Gradient Pill Button */
.mrb-gp::before { content: ""; position: absolute; inset: 0; padding: 1px; border-radius: 9999px; -webkit-mask: linear-gradient(black 0 0) content-box, linear-gradient(black 0 0); -webkit-mask-composite: xor; mask-composite: exclude; background: linear-gradient(180deg, hsl(var(--foreground) / .45), hsl(var(--foreground) / .06), hsl(var(--foreground) / .45)); pointer-events: none; }

/* Generate Button (inverted ink, glow from --primary) */
.mrb-gen-wrap { position: relative; display: inline-block; isolation: isolate; }
.mrb-gen { --border-radius: 24px; --padding: 4px; --transition: .4s; --gen-glow: hsl(var(--primary)); position: relative; user-select: none; display: flex; justify-content: center; align-items: center; padding: .55rem 1.1rem; font-family: var(--mrb-mono); font-size: 13px; letter-spacing: .14em; text-transform: uppercase; line-height: 1.5; color: hsl(var(--background)); background-color: hsl(var(--foreground)); box-shadow: inset 0 1px 1px rgb(255 255 255 / .2), inset 0 2px 2px rgb(255 255 255 / .15), inset 0 4px 4px rgb(255 255 255 / .1), inset 0 8px 8px rgb(255 255 255 / .05), 0 -1px 1px rgb(0 0 0 / .02), 0 -2px 2px rgb(0 0 0 / .03), 0 -4px 4px rgb(0 0 0 / .05), 0 -8px 8px rgb(0 0 0 / .06); border: solid 1px hsl(var(--border) / .4); border-radius: var(--border-radius); cursor: pointer; outline: none; transition: box-shadow var(--transition), border var(--transition), background-color var(--transition); }
.mrb-gen::before { content: ""; position: absolute; top: calc(0px - var(--padding)); left: calc(0px - var(--padding)); width: calc(100% + var(--padding) * 2); height: calc(100% + var(--padding) * 2); border-radius: calc(var(--border-radius) + var(--padding)); pointer-events: none; background-image: linear-gradient(0deg, hsl(var(--foreground) / .12), hsl(var(--foreground) / .3)); z-index: -1; transition: box-shadow var(--transition); box-shadow: 1px 1px 1px rgb(255 255 255 / .13), 2px 2px 2px rgb(255 255 255 / .07), -1px -1px 1px rgb(0 0 0 / .13), -2px -2px 2px rgb(0 0 0 / .07); }
.mrb-gen::after { content: ""; position: absolute; inset: 0; border-radius: inherit; pointer-events: none; background-image: linear-gradient(0deg, var(--mrb-tint), var(--gen-glow), color-mix(in oklab, var(--gen-glow) 50%, transparent), 8%, transparent); opacity: 0; transition: opacity var(--transition), filter var(--transition); }
.mrb-gen-letter { position: relative; display: inline-block; color: hsl(var(--background) / .4); animation: mrb-gen-letter 2s ease-in-out infinite; transition: color var(--transition), text-shadow var(--transition); }
@keyframes mrb-gen-letter { 50% { text-shadow: 0 0 3px hsl(var(--background) / .6); color: hsl(var(--background)); } }
.mrb-gen-svg { flex-grow: 1; height: 22px; margin-right: .5rem; fill: color-mix(in oklab, hsl(var(--primary)) 55%, hsl(var(--background))); animation: mrb-gen-flicker 2s linear infinite; animation-delay: .5s; filter: drop-shadow(0 0 2px hsl(var(--primary) / .6)); transition: fill var(--transition), filter var(--transition); }
@keyframes mrb-gen-flicker { 50% { opacity: .3; } }
.mrb-gen-txt { position: relative; display: flex; align-items: center; min-width: 8em; }
.mrb-gen-t1, .mrb-gen-t2 { position: absolute; }
.mrb-gen-t1 { animation: mrb-gen-appear 1s ease-in-out forwards; }
.mrb-gen-t2 { opacity: 0; }
@keyframes mrb-gen-appear { 0% { opacity: 0; } 100% { opacity: 1; } }
.mrb-gen:focus .mrb-gen-t1 { animation: mrb-gen-opacity .3s ease-in-out forwards; animation-delay: 1s; }
.mrb-gen:focus .mrb-gen-t2 { animation: mrb-gen-opacity .3s ease-in-out reverse forwards; animation-delay: 1s; }
@keyframes mrb-gen-opacity { 0% { opacity: 1; } 100% { opacity: 0; } }
.mrb-gen:focus .mrb-gen-letter { animation: mrb-gen-focused 1s ease-in-out forwards, mrb-gen-letter 1.2s ease-in-out infinite; }
@keyframes mrb-gen-focused { 0%, 100% { filter: blur(0px); } 50% { transform: scale(2); filter: blur(10px) brightness(150%) drop-shadow(-36px 12px 12px hsl(var(--primary))); } }
.mrb-gen:focus .mrb-gen-svg { animation-duration: 1.2s; animation-delay: .2s; }
.mrb-gen:focus::before { box-shadow: 0 -8px 12px -6px rgb(255 255 255 / .2) inset, 0 -16px 16px -8px hsl(var(--primary) / .2) inset; }
.mrb-gen:focus::after { opacity: .6; -webkit-mask-image: linear-gradient(0deg, black, transparent); mask-image: linear-gradient(0deg, black, transparent); }
.mrb-gen:active { border: solid 1px hsl(var(--primary) / .7); }
.mrb-gen:active::before { box-shadow: 0 -8px 12px -6px rgb(255 255 255 / .6) inset, 0 -16px 16px -8px hsl(var(--primary) / .8) inset; }
.mrb-gen:active::after { opacity: 1; -webkit-mask-image: linear-gradient(0deg, black, transparent); mask-image: linear-gradient(0deg, black, transparent); filter: brightness(160%); }
.mrb-gen:active .mrb-gen-letter { text-shadow: 0 0 1px hsl(var(--primary)); animation: none; }
.mrb-gen:hover { border: solid 1px hsl(var(--primary) / .5); }
.mrb-gen:hover::before { box-shadow: 0 -8px 8px -6px rgb(255 255 255 / .6) inset, 0 -16px 16px -8px hsl(var(--primary) / .35) inset; }
.mrb-gen:hover::after { opacity: 1; -webkit-mask-image: linear-gradient(0deg, black, transparent); mask-image: linear-gradient(0deg, black, transparent); }
.mrb-gen:hover .mrb-gen-svg { filter: drop-shadow(0 0 4px hsl(var(--primary))); animation: none; }

/* Glassmorphism CTA */
@keyframes mrb-gm-beam { 0% { transform: translate(-50%,-50%) rotate(0deg); } 100% { transform: translate(-50%,-50%) rotate(360deg); } }

/* Page buttons */
.mrb-pb { position: relative; display: inline-flex; align-items: center; justify-content: center; border: 0; font: inherit; text-decoration: none; white-space: nowrap; cursor: pointer; -webkit-font-smoothing: antialiased; }
.mrb-page::before { content: ""; position: absolute; inset: 0; z-index: -1; pointer-events: none; background: radial-gradient(circle at 50% 50%, hsl(var(--primary) / .1), transparent 38%); }

.mrb-pb--trochil { height: 52px; padding: 0 30px; overflow: hidden; border: 1px solid hsl(var(--foreground) / .22); background: linear-gradient(180deg, hsl(var(--card)), hsl(var(--muted))); box-shadow: 0 14px 30px -10px hsl(var(--foreground) / .25), inset 0 1px hsl(var(--background) / .6); color: hsl(var(--foreground) / .82); font-family: var(--mrb-mono); font-size: 12px; letter-spacing: .14em; text-transform: uppercase; transition: border-color .28s ease, color .28s ease, transform .28s ease, box-shadow .28s ease; }
.mrb-pb--trochil::before { content: ""; position: absolute; inset: -1px; background: linear-gradient(105deg, transparent 17%, hsl(var(--primary) / .3) 48%, transparent 76%); transform: translateX(-125%); transition: transform .65s cubic-bezier(.22,.61,.36,1); }
.mrb-pb--trochil span { position: relative; }
.mrb-pb--trochil:hover { border-color: hsl(var(--primary) / .6); color: hsl(var(--foreground)); transform: translateY(-2px); box-shadow: 0 18px 38px -10px hsl(var(--foreground) / .3), 0 0 22px hsl(var(--primary) / .18); }
.mrb-pb--trochil:hover::before { transform: translateX(125%); }

.mrb-pb--attune { gap: 10px; height: 52px; padding: 0 22px; border-radius: 11px; background: linear-gradient(180deg, var(--mrb-tint) 0%, hsl(var(--primary)) 48%, var(--mrb-shade) 100%); box-shadow: inset 0 1px rgb(255 255 255 / .3), 0 8px 28px hsl(var(--primary) / .3); color: hsl(var(--primary-foreground)); font-family: var(--mrb-sans); font-size: 14px; font-weight: 650; letter-spacing: .012em; transition: filter .18s ease, transform .18s ease, box-shadow .18s ease; }
.mrb-pb--attune svg { width: 8px; height: 12px; fill: none; stroke: currentColor; stroke-width: 1.7; }
.mrb-pb--attune:hover { filter: brightness(1.08); transform: translateY(-2px); box-shadow: inset 0 1px rgb(255 255 255 / .38), 0 12px 34px hsl(var(--primary) / .4); }
.mrb-pb--attune:active { transform: translateY(1px); }

.mrb-pb--tideform { gap: 18px; padding: 17px 24px; border: 1px solid hsl(var(--foreground) / .25); background: hsl(var(--foreground) / .04); color: hsl(var(--foreground)); font-family: var(--mrb-mono); font-size: 11px; font-weight: 700; letter-spacing: .18em; text-transform: uppercase; transition: border-color .25s ease, background-color .25s ease, color .25s ease; }
.mrb-pb--tideform svg { width: 21px; height: 9px; fill: none; stroke: currentColor; stroke-width: 1.25; transition: transform .25s cubic-bezier(.2,.8,.2,1); }
.mrb-pb--tideform:hover { border-color: hsl(var(--primary)); color: hsl(var(--primary)); background: hsl(var(--primary) / .1); }
.mrb-pb--tideform:hover svg { transform: translateX(4px); }

.mrb-pb--arrow-pill { gap: 18px; height: 54px; padding: 0 11px 0 32px; border-radius: 999px; font-family: var(--mrb-serif); font-size: 21px; letter-spacing: -.005em; transition: background .3s ease, transform .3s ease, color .3s ease; }
.mrb-pb--arrow-pill .mrb-disc { display: grid; width: 32px; height: 32px; flex: none; place-items: center; border-radius: 50%; }
.mrb-pb--arrow-pill svg { width: 11px; height: 11px; fill: none; stroke: currentColor; stroke-width: 2; transition: transform .3s ease; }
.mrb-pb--arrow-pill:hover { transform: translateY(-2px); }
.mrb-pb--arrow-pill:hover svg { transform: translateX(2px); }
.mrb-pb--understory { background: hsl(var(--primary)); color: hsl(var(--primary-foreground)); box-shadow: 0 14px 30px -8px hsl(var(--primary) / .45); }
.mrb-pb--understory .mrb-disc { background: hsl(var(--primary-foreground)); color: hsl(var(--primary)); }
.mrb-pb--understory:hover { filter: brightness(1.06); }
.mrb-pb--halvorsen { background: hsl(var(--foreground)); color: hsl(var(--background)); box-shadow: 0 14px 30px -8px hsl(var(--foreground) / .4); }
.mrb-pb--halvorsen .mrb-disc { background: hsl(var(--primary)); color: hsl(var(--primary-foreground)); }
.mrb-pb--halvorsen:hover { background: hsl(var(--foreground) / .9); }

.mrb-pb--meridian { height: 62px; padding: 0 30px; border-radius: 15px; flex-shrink: 0; background: hsl(var(--muted)); box-shadow: inset 0 0 0 1px hsl(var(--border)); }
.mrb-pb--meridian::before { content: ""; position: absolute; inset: 3px 4px 9px; border-radius: 12px; background: linear-gradient(180deg, hsl(var(--card)), color-mix(in oklab, hsl(var(--card)) 88%, hsl(var(--foreground)))); box-shadow: 0 5px 0 color-mix(in oklab, hsl(var(--border)) 70%, hsl(var(--foreground))), 0 9px 15px -2px hsl(var(--foreground) / .2), inset 0 1px hsl(var(--background) / .5); transition: transform .13s cubic-bezier(.22,.61,.36,1), box-shadow .13s cubic-bezier(.22,.61,.36,1); }
.mrb-pb--meridian > span:not(.mrb-led) { position: relative; z-index: 1; color: hsl(var(--foreground)); font-family: var(--mrb-mono); font-size: 12px; font-weight: 600; letter-spacing: .12em; text-transform: uppercase; }
.mrb-pb--meridian .mrb-led { position: absolute; z-index: 1; top: 12px; left: 50%; width: 4px; height: 4px; border-radius: 50%; background: hsl(var(--foreground) / .18); transform: translateX(-50%); transition: background .22s ease, box-shadow .22s ease; }
.mrb-pb--meridian:hover::before, .mrb-pb--meridian:active::before { transform: translateY(4px); box-shadow: 0 1px 0 color-mix(in oklab, hsl(var(--border)) 70%, hsl(var(--foreground))), 0 3px 8px -2px hsl(var(--foreground) / .2), inset 0 1px hsl(var(--background) / .5); }
.mrb-pb--meridian:hover .mrb-led { background: hsl(var(--primary)); box-shadow: 0 0 7px hsl(var(--primary)); }
.mrb-pb--meridian-primary { background: hsl(var(--primary) / .18); box-shadow: inset 0 0 0 1px hsl(var(--primary) / .3); }
.mrb-pb--meridian-primary::before { background: linear-gradient(180deg, var(--mrb-tint), hsl(var(--primary))); box-shadow: 0 5px 0 var(--mrb-shade), 0 9px 18px -2px hsl(var(--primary) / .45), inset 0 1px rgb(255 255 255 / .45); }
.mrb-pb--meridian-primary > span:not(.mrb-led) { color: hsl(var(--primary-foreground)); }
.mrb-pb--meridian-primary .mrb-led { background: hsl(var(--primary-foreground) / .35); }
.mrb-pb--meridian-primary:hover::before, .mrb-pb--meridian-primary:active::before { box-shadow: 0 1px 0 var(--mrb-shade), 0 3px 10px -2px hsl(var(--primary) / .4), inset 0 1px rgb(255 255 255 / .45); }
.mrb-pb--meridian-primary:hover .mrb-led { background: hsl(var(--primary-foreground)); box-shadow: 0 0 6px hsl(var(--primary-foreground)); }

.mrb-pb--aster { height: 52px; border-radius: 12px; isolation: isolate; background: hsl(var(--foreground) / .05); color: hsl(var(--foreground)); font-family: var(--mrb-sans); font-size: 16px; letter-spacing: -.004em; box-shadow: 0 12px 34px -22px hsl(var(--foreground) / .5); backdrop-filter: blur(16px) saturate(1.25); -webkit-backdrop-filter: blur(16px) saturate(1.25); transition: transform .5s cubic-bezier(.22,1,.36,1), background .4s ease, box-shadow .5s cubic-bezier(.22,1,.36,1); }
.mrb-pb--aster::before { content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; padding: 1px; background: linear-gradient(148deg, hsl(var(--primary) / .8), hsl(var(--foreground) / .14) 34%, hsl(var(--foreground) / .05) 58%, hsl(var(--primary) / .4)); mask: linear-gradient(black 0 0) content-box, linear-gradient(black 0 0); mask-composite: exclude; -webkit-mask: linear-gradient(black 0 0) content-box, linear-gradient(black 0 0); -webkit-mask-composite: xor; pointer-events: none; transition: filter .45s cubic-bezier(.22,1,.36,1); }
.mrb-pb--aster::after { content: ""; position: absolute; inset: 0; z-index: -1; border-radius: inherit; background: linear-gradient(180deg, hsl(var(--background) / .5), transparent 46%); pointer-events: none; }
.mrb-pb--aster > span { position: relative; z-index: 1; }
.mrb-pb--aster:hover { transform: translateY(-1px); background: hsl(var(--primary) / .12); box-shadow: 0 8px 26px -12px hsl(var(--primary) / .5); }
.mrb-pb--aster:hover::before { filter: saturate(1.4); }
.mrb-pb--aster:active { transform: translateY(0); }
.mrb-pb--aster-access { padding: 0 31px; }
.mrb-pb--aster-arrow { gap: 17px; padding: 0 7px 0 22px; }
.mrb-pb--aster-arrow .mrb-chip { position: relative; display: grid; width: 36px; height: 36px; flex: none; place-items: center; border-radius: 9px; background: hsl(var(--primary)); color: hsl(var(--primary-foreground)); }
.mrb-pb--aster-arrow svg { width: 15px; height: 15px; fill: none; stroke: currentColor; stroke-width: 1.4; stroke-linecap: round; stroke-linejoin: round; transition: transform .5s cubic-bezier(.22,1,.36,1); }
.mrb-pb--aster-arrow:hover svg { transform: translateX(2px); }
`;

const FLOATING_POINTS: [string, number, number, number][] = [
  ["10%", 1, 2.35, 0.2],
  ["30%", 0.7, 2.5, 0.5],
  ["25%", 0.8, 2.2, 0.1],
  ["44%", 0.6, 2.05, 0],
  ["50%", 1, 1.9, 0],
  ["75%", 0.5, 1.5, 1.5],
  ["88%", 0.9, 2.2, 0.2],
  ["58%", 0.8, 2.25, 0.2],
  ["98%", 0.6, 2.6, 0.1],
  ["65%", 1, 2.5, 0.2],
];

const PAGE_VARIANTS = new Set<ButtonAtlasVariant>([
  "sheen-cta",
  "kiln-button",
  "hairline-cta",
  "orbit-chip-button",
  "meridian-keycap-primary",
  "meridian-keycap-secondary",
  "ink-endcap-button",
  "aster-glass-access",
  "aster-glass-arrow",
]);

function ArrowRight({ className, size = 16 }: { className?: string; size?: number }) {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width={size}
      height={size}
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
      aria-hidden="true"
      className={className}
    >
      <path d="M5 12h14" />
      <path d="m12 5 7 7-7 7" />
    </svg>
  );
}

function Chevron({ long = false }: { long?: boolean }) {
  return long ? (
    <svg viewBox="0 0 21 9" aria-hidden="true">
      <path d="M0 4.5h18M14.5 1.2 18.3 4.5l-3.8 3.3" />
    </svg>
  ) : (
    <svg viewBox="0 0 12 12" aria-hidden="true">
      <path d="M3 1.5 8 6 3 10.5" />
    </svg>
  );
}

function Letters({ text }: { text: string }) {
  return (
    <>
      {Array.from(text).map((ch, i) => (
        <span key={i} className="mrb-gen-letter" style={{ animationDelay: `${i * 0.08}s` }}>
          {ch === " " ? " " : ch}
        </span>
      ))}
    </>
  );
}

export function ButtonAtlas({
  variant = "meridian-keycap-primary",
  label,
  activeLabel = "Composing",
  hue = 0,
  saturation = 1,
  brightness = 1,
  background,
  avatarSrc = "https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=128&h=128&fit=crop",
  avatarAlt = "Reviewer headshot",
  onClick,
  className,
}: ButtonAtlasProps) {
  const prefersReducedMotion = useReducedMotion();
  const text = label ?? DEFAULT_LABELS[variant];
  const still = prefersReducedMotion ? "mrb-still" : undefined;
  const filter =
    hue === 0 && saturation === 1 && brightness === 1
      ? undefined
      : `hue-rotate(${clamp(hue, -180, 180)}deg) saturate(${clamp(saturation, 0, 2)}) brightness(${clamp(brightness, 0.35, 1.65)})`;

  let content: ReactNode = null;

  switch (variant) {
    case "ink-capsule":
      content = (
        <button type="button" className="mrb-glass-btn" onClick={onClick}>
          <span className="mrb-glass-title">{text}</span>
          <span className="mrb-glass-circle" aria-hidden="true" />
        </button>
      );
      break;

    case "keystroke-button":
      content = (
        <button type="button" onClick={onClick} className="mrb-launch">
          <span className="mrb-launch-glow" aria-hidden="true" />
          <span className="mrb-launch-face">
            <span>{text}</span>
            <svg
              viewBox="0 0 24 24"
              strokeLinecap="round"
              strokeLinejoin="round"
              aria-hidden="true"
            >
              <path d="M4 14a1 1 0 0 1-.78-1.63l9.9-10.2a.5.5 0 0 1 .86.46l-1.92 6.02A1 1 0 0 0 13 10h7a1 1 0 0 1 .78 1.63l-9.9 10.2a.5.5 0 0 1-.86-.46l1.92-6.02A1 1 0 0 0 11 14z" />
            </svg>
          </span>
        </button>
      );
      break;

    case "stitch-frame-button":
      content = (
        <div className="mrb-db-wrapper">
          <div className="mrb-db-line mrb-db-h mrb-db-top" />
          <div className="mrb-db-line mrb-db-v mrb-db-right" />
          <div className="mrb-db-line mrb-db-h mrb-db-bottom" />
          <div className="mrb-db-line mrb-db-v mrb-db-left" />
          <div className="mrb-db-dot mrb-db-top mrb-db-left" />
          <div className="mrb-db-dot mrb-db-top mrb-db-right" />
          <div className="mrb-db-dot mrb-db-bottom mrb-db-right" />
          <div className="mrb-db-dot mrb-db-bottom mrb-db-left" />
          <button type="button" className="mrb-db-btn" onClick={onClick}>
            <span>{text}</span>
            <svg className="mrb-db-svg" viewBox="0 0 24 24" aria-hidden="true">
              <path d="M17.6744 11.4075L15.7691 17.1233C15.7072 17.309 15.5586 17.4529 15.3709 17.5087L3.69348 20.9803C3.22819 21.1186 2.79978 20.676 2.95328 20.2155L6.74467 8.84131C6.79981 8.67588 6.92419 8.54263 7.08543 8.47624L12.472 6.25822C12.696 6.166 12.9535 6.21749 13.1248 6.38876L17.5294 10.7935C17.6901 10.9542 17.7463 11.1919 17.6744 11.4075Z" />
              <path d="M3.2959 20.6016L9.65986 14.2376" />
              <path d="M17.7917 11.0557L20.6202 8.22724C21.4012 7.44619 21.4012 6.17986 20.6202 5.39881L18.4989 3.27749C17.7178 2.49645 16.4515 2.49645 15.6704 3.27749L12.842 6.10592" />
              <path d="M11.7814 12.1163C11.1956 11.5305 10.2458 11.5305 9.66004 12.1163C9.07426 12.7021 9.07426 13.6519 9.66004 14.2376C10.2458 14.8234 11.1956 14.8234 11.7814 14.2376C12.3671 13.6519 12.3671 12.7021 11.7814 12.1163Z" />
            </svg>
          </button>
        </div>
      );
      break;

    case "rising-motes":
      content = (
        <button type="button" onClick={onClick} className="mrb-fd">
          <div className="mrb-fd-points">
            {FLOATING_POINTS.map(([left, opacity, duration, delay], index) => (
              <i
                key={index}
                className="mrb-fd-point"
                style={{
                  left,
                  opacity,
                  animationDuration: `${duration}s`,
                  animationDelay: `${delay}s`,
                }}
              />
            ))}
          </div>
          <span className="mrb-fd-inner">
            {text}
            <svg
              className="mrb-fd-icon"
              viewBox="0 0 24 24"
              strokeLinecap="round"
              strokeLinejoin="round"
              strokeWidth="1.5"
              aria-hidden="true"
            >
              <path d="M5 12h14" />
              <path d="m12 5 7 7-7 7" />
            </svg>
          </span>
        </button>
      );
      break;

    case "roll-label":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="group relative inline-flex min-w-[120px] cursor-pointer items-center justify-center overflow-hidden rounded-full border border-border bg-card px-[22px] py-[12px] font-sans font-medium tracking-tight text-muted-foreground shadow-[0_3px_2px_hsl(var(--foreground)/0.08),0_7px_5px_hsl(var(--foreground)/0.08),0_12px_10px_hsl(var(--foreground)/0.1)] transition-all duration-[1000ms] ease-[cubic-bezier(0.15,0.83,0.66,1)] hover:-translate-y-[3px] hover:text-foreground"
        >
          <span className="relative z-10 rounded-full transition-all duration-500 ease-out group-hover:translate-y-8 group-hover:opacity-0 group-hover:blur-md">
            {text}
          </span>
          <span
            aria-hidden="true"
            className="absolute inset-0 z-10 flex -translate-y-8 items-center justify-center rounded-full text-primary opacity-0 blur-md transition-all duration-300 ease-in-out group-hover:translate-y-0 group-hover:opacity-100 group-hover:blur-none"
          >
            {text}
          </span>
          <span
            aria-hidden="true"
            className="absolute bottom-0 left-1/2 h-[1px] w-[70%] -translate-x-1/2 rounded-full bg-gradient-to-r from-transparent via-primary to-transparent blur-[1px] transition-all duration-[1000ms] group-hover:opacity-80"
          />
          <span
            aria-hidden="true"
            className="pointer-events-none absolute inset-x-0 bottom-0 h-full rounded-full bg-gradient-to-t from-primary/10 via-primary/5 to-transparent transition-all duration-[1000ms] group-hover:opacity-60"
          />
        </button>
      );
      break;

    case "comet-ring-button":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="group relative isolate flex items-center justify-center overflow-hidden rounded-full px-12 py-5 font-mono text-xs uppercase tracking-[0.2em] text-foreground transition-all duration-500 hover:scale-[1.02] hover:shadow-[0_0_40px_-10px_hsl(var(--primary)/0.6)] focus:outline-none"
        >
          <div className="absolute inset-0 -z-20 overflow-hidden rounded-full p-[1px]">
            <div
              className="absolute inset-[-100%] bg-[conic-gradient(from_0deg,transparent_0_300deg,hsl(var(--primary))_360deg)]"
              style={{ animation: "mrb-gb-spin 3s linear infinite" }}
            />
            <div className="absolute inset-[1px] rounded-full bg-border" />
          </div>
          <div className="absolute inset-[2px] -z-10 overflow-hidden rounded-full bg-card">
            <div className="absolute inset-0 bg-gradient-to-b from-muted/80 to-transparent" />
            <div
              className="absolute inset-0 opacity-25"
              style={{
                backgroundImage:
                  "radial-gradient(hsl(var(--foreground) / 0.5) 1px, transparent 1px)",
                backgroundSize: "12px 12px",
                animation: "mrb-gb-dots 8s linear infinite",
              }}
            />
            <div className="pointer-events-none absolute bottom-0 left-1/2 h-1/2 w-2/3 -translate-x-1/2 rounded-full bg-primary/10 blur-2xl transition-colors duration-500 group-hover:bg-primary/30" />
          </div>
          <span className="relative z-10">{text}</span>
          <ArrowRight className="relative z-10 ml-2 text-primary transition-transform duration-300 group-hover:translate-x-1" />
        </button>
      );
      break;

    case "satin-capsule":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="mrb-gp relative flex items-center gap-2 rounded-full bg-gradient-to-b from-foreground/[0.08] via-foreground/[0.03] to-foreground/[0.08] px-6 py-3 font-sans text-sm font-medium text-foreground/75 shadow-[0_18px_35px_-12px_hsl(var(--foreground)/0.3)] transition-all hover:bg-primary/10 hover:text-foreground"
        >
          <span className="tracking-tight">{text}</span>
          <ArrowRight size={16} className="text-primary" />
        </button>
      );
      break;

    case "conjure-button":
      content = (
        <div className="mrb-gen-wrap">
          <button
            type="button"
            aria-label={text}
            title={text}
            onClick={onClick}
            className="mrb-gen"
          >
            <svg
              className="mrb-gen-svg"
              viewBox="0 0 24 24"
              width="24"
              height="24"
              aria-hidden="true"
            >
              <path d="M9.813 15.904 9 18.75l-.813-2.846a4.5 4.5 0 0 0-3.09-3.09L2.25 12l2.846-.813a4.5 4.5 0 0 0 3.09-3.09L9 5.25l.813 2.846a4.5 4.5 0 0 0 3.09 3.09L15.75 12l-2.846.813a4.5 4.5 0 0 0-3.09 3.09ZM18.259 8.715 18 9.75l-.259-1.035a3.375 3.375 0 0 0-2.455-2.456L14.25 6l1.036-.259a3.375 3.375 0 0 0 2.455-2.456L18 2.25l.259 1.035a3.375 3.375 0 0 0 2.456 2.456L21.75 6l-1.035.259a3.375 3.375 0 0 0-2.456 2.456ZM16.894 20.567 16.5 21.75l-.394-1.183a2.25 2.25 0 0 0-1.423-1.423L13.5 18.75l1.183-.394a2.25 2.25 0 0 0 1.423-1.423l.394-1.183.394 1.183a2.25 2.25 0 0 0 1.423 1.423l1.183.394-1.183.394a2.25 2.25 0 0 0-1.423 1.423Z" />
            </svg>
            <div className="mrb-gen-txt">
              <div className="mrb-gen-t1">
                <Letters text={text} />
              </div>
              <div className="mrb-gen-t2">
                <Letters text={activeLabel} />
              </div>
            </div>
          </button>
        </div>
      );
      break;

    case "halo-invite":
      content = (
        <a
          href="#"
          onClick={(event) => {
            event.preventDefault();
            onClick?.(event);
          }}
          className="group relative isolate inline-flex cursor-pointer overflow-hidden rounded-full font-sans no-underline shadow-[0_8px_40px_hsl(var(--primary)/0.25)] transition-all duration-300 hover:scale-105 hover:shadow-[0_0_40px_8px_hsl(var(--primary)/0.3)]"
        >
          <div className="absolute inset-0">
            <div className="absolute inset-[-200%] h-[400%] w-[400%]">
              <div
                className="absolute inset-0"
                style={{
                  background:
                    "conic-gradient(from 225deg, transparent 0, hsl(var(--primary) / 0.8) 90deg, transparent 90deg)",
                }}
              />
            </div>
          </div>
          <div className="absolute inset-[1px] rounded-full bg-foreground/5 backdrop-blur" />
          <div className="relative z-10 flex items-center gap-3 overflow-hidden rounded-full px-4 py-3 text-base font-medium text-foreground">
            <div
              style={{
                position: "absolute",
                width: "200%",
                height: "200%",
                top: "50%",
                left: "50%",
                transform: "translate(-50%, -50%)",
                background:
                  "linear-gradient(90deg, transparent, hsl(var(--primary) / 0.25), hsl(var(--primary) / 0.25), transparent)",
                animation: "mrb-gm-beam 4s infinite linear",
              }}
            />
            <div
              className="bg-card/90 backdrop-blur-md"
              style={{ position: "absolute", inset: 1, borderRadius: 9999 }}
            />
            {/* eslint-disable-next-line @next/next/no-img-element */}
            <img
              src={avatarSrc}
              alt={avatarAlt}
              className="relative z-10 m-0 h-8 w-8 rounded-full object-cover ring-2 ring-primary/30"
            />
            <span className="relative z-10 whitespace-nowrap">{text}</span>
            <span className="relative z-10 ml-1 inline-flex h-7 w-7 items-center justify-center rounded-full bg-primary text-primary-foreground">
              <svg
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                strokeWidth="1.5"
                strokeLinecap="round"
                strokeLinejoin="round"
                className="h-4 w-4"
                aria-hidden="true"
              >
                <path d="m21.64 3.64-1.28-1.28a1.21 1.21 0 0 0-1.72 0L2.36 18.64a1.21 1.21 0 0 0 0 1.72l1.28 1.28a1.2 1.2 0 0 0 1.72 0L21.64 5.36a1.2 1.2 0 0 0 0-1.72" />
                <path d="m14 7 3 3" />
                <path d="M5 6v4" />
                <path d="M19 14v4" />
                <path d="M10 2v2" />
                <path d="M7 8H3" />
                <path d="M21 16h-4" />
                <path d="M11 3H9" />
              </svg>
            </span>
          </div>
        </a>
      );
      break;

    case "halo-trace":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="group relative inline-flex items-center justify-center overflow-hidden rounded-full p-[1px] transition-all duration-300 hover:-translate-y-0.5 hover:shadow-[0_0_25px_hsl(var(--primary)/0.25)]"
        >
          <span
            className="absolute inset-[-100%] animate-spin opacity-0 transition-all duration-300 group-hover:opacity-100"
            style={{
              animationDuration: "3s",
              background:
                "conic-gradient(from 90deg at 50% 50%, transparent 0%, transparent 75%, hsl(var(--primary)) 100%)",
            }}
          />
          <span className="absolute inset-0 rounded-full bg-border transition-all duration-300 group-hover:opacity-0" />
          <span className="relative flex h-full w-full items-center justify-center gap-2 rounded-full bg-gradient-to-b from-card to-muted px-6 py-2.5 font-mono text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground shadow-[inset_0_1px_0_hsl(var(--background)/0.6)] transition-all duration-300 group-hover:text-foreground">
            <span className="relative z-10">{text}</span>
            <ArrowRight
              size={14}
              className="relative z-10 text-primary transition-all duration-300 group-hover:translate-x-0.5"
            />
          </span>
        </button>
      );
      break;

    case "glaze-button":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="group relative overflow-hidden rounded-full px-8 py-4 font-sans font-medium text-primary-foreground transition-all duration-300"
          style={{
            backgroundImage:
              "linear-gradient(to right, color-mix(in oklab, hsl(var(--primary)) 70%, white), hsl(var(--primary)))",
            boxShadow:
              "0 15px 33px -12px hsl(var(--primary) / 0.8), inset 0 4px 6px rgb(255 255 255 / 0.3), inset 0 -5px 6px color-mix(in oklab, hsl(var(--primary)) 70%, black)",
          }}
        >
          <div className="absolute inset-0 translate-y-full bg-primary-foreground/15 transition-transform duration-300 group-hover:translate-y-0" />
          <span className="relative flex items-center gap-2">
            {text}
            <svg
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              strokeWidth="1.5"
              strokeLinecap="round"
              strokeLinejoin="round"
              className="h-4 w-4"
              aria-hidden="true"
            >
              <path d="M14.536 21.686a.5.5 0 0 0 .937-.024l6.5-19a.496.496 0 0 0-.635-.635l-19 6.5a.5.5 0 0 0-.024.937l7.93 3.18a2 2 0 0 1 1.112 1.11z" />
              <path d="m21.854 2.147-10.94 10.939" />
            </svg>
          </span>
        </button>
      );
      break;

    case "ink-pill":
    case "lumen-cta-ghost": {
      const ghost = variant === "lumen-cta-ghost";
      content = (
        <button
          type="button"
          onClick={onClick}
          className={cn(
            "relative inline-flex h-[45px] cursor-pointer appearance-none items-center gap-[10px] whitespace-nowrap rounded-full border-0 font-sans text-[15px] font-semibold leading-none outline outline-1 transition-[background,filter,outline-color] duration-200",
            ghost
              ? "bg-foreground/[0.03] px-[33px] text-foreground outline-foreground/20 backdrop-blur-[12px] hover:bg-primary/10 hover:outline-primary/50"
              : "px-[30px] text-primary-foreground outline-foreground/10 hover:brightness-110",
          )}
          style={
            ghost
              ? undefined
              : {
                  background:
                    "linear-gradient(90deg, color-mix(in oklab, hsl(var(--primary)) 35%, hsl(var(--foreground))) 0%, hsl(var(--primary)) 60%, color-mix(in oklab, hsl(var(--primary)) 55%, white) 100%)",
                  boxShadow:
                    "0 4px 22px hsl(var(--primary) / 0.35), inset 0 1px 0 rgb(255 255 255 / 0.18)",
                }
          }
        >
          {text}
          <i
            aria-hidden="true"
            className={cn(
              "h-[7px] w-[7px] flex-none rounded-full border-[1.3px] border-solid",
              ghost ? "border-primary" : "border-primary-foreground/90",
            )}
          />
        </button>
      );
      break;
    }

    case "sheen-cta":
      content = (
        <button type="button" onClick={onClick} className="mrb-pb mrb-pb--trochil">
          <span>{text}</span>
        </button>
      );
      break;
    case "kiln-button":
      content = (
        <button type="button" onClick={onClick} className="mrb-pb mrb-pb--attune">
          <span>{text}</span>
          <Chevron />
        </button>
      );
      break;
    case "hairline-cta":
      content = (
        <button type="button" onClick={onClick} className="mrb-pb mrb-pb--tideform">
          <span>{text}</span>
          <Chevron long />
        </button>
      );
      break;
    case "orbit-chip-button":
    case "ink-endcap-button":
      content = (
        <button
          type="button"
          onClick={onClick}
          className={cn(
            "mrb-pb mrb-pb--arrow-pill",
            variant === "orbit-chip-button" ? "mrb-pb--understory" : "mrb-pb--halvorsen",
          )}
        >
          <span>{text}</span>
          <span className="mrb-disc">
            <Chevron />
          </span>
        </button>
      );
      break;
    case "meridian-keycap-primary":
    case "meridian-keycap-secondary":
      content = (
        <button
          type="button"
          onClick={onClick}
          className={cn(
            "mrb-pb mrb-pb--meridian",
            variant === "meridian-keycap-primary" && "mrb-pb--meridian-primary",
          )}
        >
          <span className="mrb-led" />
          <span>{text}</span>
        </button>
      );
      break;
    case "aster-glass-access":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="mrb-pb mrb-pb--aster mrb-pb--aster-access"
        >
          <span>{text}</span>
        </button>
      );
      break;
    case "aster-glass-arrow":
      content = (
        <button
          type="button"
          onClick={onClick}
          className="mrb-pb mrb-pb--aster mrb-pb--aster-arrow"
        >
          <span>{text}</span>
          <span className="mrb-chip">
            <svg viewBox="0 0 12 12" aria-hidden="true">
              <path d="M2 6h8M6.6 2.6 10 6 6.6 9.4" />
            </svg>
          </span>
        </button>
      );
      break;
  }

  return (
    <div
      className={cn("mrb-stage", PAGE_VARIANTS.has(variant) && "mrb-page", still, className)}
      data-variant={variant}
      style={{ background, filter } as CSSProperties}
    >
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      {content}
    </div>
  );
}
```

---

# Folio Opening

> A two-column opening spread with a serif headline, a ruled lede and an inked device illustration in your theme colours.

Install: `npx @modus-ui/cli add folio-opening`

An opening spread set like a book page: a mono chapter label with a pulsing dot, a large serif headline (wrap a word in `*asterisks*` to set it in italic primary), a ruled lede, and a device illustration inked in the foreground colour over primary circuit dots on faint ruled lines. Everything is drawn from theme tokens, so it follows light and dark mode and the palette picker. Type scales with the section through container query units and the layout stacks in narrow containers. The float, drift and pulse stop when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add folio-opening
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/folio-opening.tsx`.
3. Paste the code.

## Usage

```tsx
import { FolioOpening } from "@/components/ui/folio-opening";

export default function Example() {
  return (
    <div className="relative aspect-video w-full overflow-hidden">
      <FolioOpening title="Write it *once*." />
    </div>
  );
}
```

## Props

| Prop              | Type            | Default                                                                                                    | Description                                           |
| :---------------- | :-------------- | :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
| `label`           | `string`        | `"Chapter one"`                                                                                            | Mono label above the headline.                        |
| `title`           | `string`        | `"Quiet tools, *loud* work."`                                                                              | Serif headline; `*text*` is set in italic primary.    |
| `description`     | `string`        | `"An interface set like a good page: calm margins, clear type and nothing between you and the next idea."` | Ruled lede under the headline.                        |
| `backgroundColor` | `string`        | None                                                                                                       | Section background; defaults to the theme background. |
| `className`       | `string`        | None                                                                                                       | Extra classes for the section.                        |
| `style`           | `CSSProperties` | None                                                                                                       | Inline styles for the section.                        |

## Source

`components/ui/folio-opening.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Editorial Intro (MIT, © 2026 Meng To).

import { useReducedMotion } from "framer-motion";
import type { CSSProperties } from "react";

import { cn } from "@/lib/utils";

const DOTS_SVG = `<svg width="368" height="368" viewBox="0 0 368 368" fill="none" xmlns="http://www.w3.org/2000/svg"> <mask id="mask0_737_39123" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="0" y="0" width="368" height="368"> <circle cx="184" cy="184" r="184" fill="url(#paint0_radial_737_39123)"/> </mask> <g mask="url(#mask0_737_39123)"> <circle cx="83.5" cy="19.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="241.5" cy="291.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="56.6092" cy="303.609" r="0.609185" fill="white" fill-opacity="0.6"/> <circle cx="304.5" cy="307.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="290.5" cy="91.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="139.5" cy="90.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="248.542" cy="143.542" r="0.541998" fill="white" fill-opacity="0.4"/> <circle cx="67.6188" cy="210.619" r="0.618842" fill="white" fill-opacity="0.4"/> <circle cx="111.5" cy="37.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="151.5" cy="77.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="199.5" cy="333.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="53.5391" cy="158.539" r="0.539137" fill="white" fill-opacity="0.3"/> <circle cx="2.5" cy="114.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="287.5" cy="342.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="352.535" cy="162.535" r="0.535221" fill="white" fill-opacity="0.5"/> <circle cx="47.7309" cy="363.731" r="0.730863" fill="white" fill-opacity="0.5"/> <circle cx="105.5" cy="364.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="74.5" cy="80.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="153.5" cy="351.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="359.549" cy="327.549" r="0.548527" fill="white" fill-opacity="0.3"/> <circle cx="27.5" cy="13.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="328.66" cy="245.66" r="0.660459" fill="white" fill-opacity="0.6"/> <circle cx="181.633" cy="317.633" r="0.633273" fill="white" fill-opacity="0.4"/> <circle cx="8.66671" cy="229.667" r="0.666706" fill="white" fill-opacity="0.6"/> <circle cx="57.5" cy="153.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="315.602" cy="122.602" r="0.601793" fill="white" fill-opacity="0.5"/> <circle cx="338.5" cy="305.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="18.5" cy="157.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="298.5" cy="289.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="344.5" cy="94.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="280.5" cy="300.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="126.5" cy="293.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="64.6943" cy="345.694" r="0.694286" fill="white" fill-opacity="0.5"/> <circle cx="98.5" cy="80.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="16.5" cy="12.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="278.5" cy="171.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="91.5027" cy="277.503" r="0.502743" fill="white" fill-opacity="0.5"/> <circle cx="348.627" cy="362.627" r="0.626809" fill="white" fill-opacity="0.3"/> <circle cx="299.5" cy="80.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="224.502" cy="74.5016" r="0.501603" fill="white" fill-opacity="0.6"/> <circle cx="136.619" cy="108.619" r="0.619352" fill="white" fill-opacity="0.4"/> <circle cx="88.5" cy="276.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="296.5" cy="189.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="23.5" cy="325.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="54.5" cy="188.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="150.519" cy="-0.481285" r="0.518715" fill="white" fill-opacity="0.4"/> <circle cx="154.528" cy="345.528" r="0.52824" fill="white" fill-opacity="0.6"/> <circle cx="324.5" cy="357.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="67.5" cy="180.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="174.5" cy="366.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="266.5" cy="4.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="355.5" cy="193.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="48.5" cy="6.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="305.5" cy="228.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="229.643" cy="40.6431" r="0.643121" fill="white" fill-opacity="0.4"/> <circle cx="159.5" cy="45.5" r="0.5" fill="white" fill-opacity="0.4"/> <circle cx="236.5" cy="345.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="99.6489" cy="218.649" r="0.648878" fill="white" fill-opacity="0.4"/> <circle cx="336.749" cy="55.7492" r="0.74922" fill="white" fill-opacity="0.5"/> <circle cx="244.647" cy="109.647" r="0.64692" fill="white" fill-opacity="0.4"/> <circle cx="52.5" cy="211.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="352.5" cy="357.5" r="0.5" fill="white" fill-opacity="0.3"/> <circle cx="82.5" cy="362.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="159.5" cy="326.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="318.678" cy="122.678" r="0.678218" fill="white" fill-opacity="0.3"/> <circle cx="235.518" cy="74.518" r="0.518012" fill="white" fill-opacity="0.5"/> <circle cx="57.5" cy="278.5" r="0.5" fill="white" fill-opacity="0.6"/> <circle cx="331.5" cy="209.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="9.5" cy="346.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="68.5" cy="326.5" r="0.5" fill="white" fill-opacity="0.5"/> <circle cx="75.5" cy="81.5" r="0.5" fill="white" fill-opacity="0.4"/> </g> <defs> <radialGradient id="paint0_radial_737_39123" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(184 184) rotate(90) scale(184)"> <stop stop-color="#D9D9D9"/> <stop offset="1" stop-color="#737373" stop-opacity="0"/> </radialGradient> </defs> </svg>`;

const DEVICE_SVG = `<svg width="368" height="368" viewBox="0 0 368 368" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <g clip-path="url(#clip0_936_42034)"> <mask id="mask0_936_42034" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="0" y="0" width="368" height="368"> <path d="M184 368C285.62 368 368 285.62 368 184C368 82.3796 285.62 0 184 0C82.3796 0 0 82.3796 0 184C0 285.62 82.3796 368 184 368Z" fill="url(#paint0_radial_936_42034)"/> </mask> <g mask="url(#mask0_936_42034)"> <path opacity="0.5" d="M272 -106.607C283.138 -113.037 296.862 -113.037 308 -106.607L368.995 -71.3915C380.133 -64.9607 386.995 -53.0762 386.995 -40.2146V30.2162C386.995 43.0778 380.133 54.9623 368.995 61.3931L308 96.6085C296.862 103.039 283.138 103.039 272 96.6085L211.005 61.3931C199.867 54.9623 193.005 43.0778 193.005 30.2162V-40.2146C193.005 -53.0762 199.867 -64.9607 211.005 -71.3915L272 -106.607Z" fill="url(#paint1_linear_936_42034)"/> <path opacity="0.5" d="M63.0002 254.393C74.1386 247.963 87.8618 247.963 99.0002 254.393L159.995 289.609C171.133 296.039 177.995 307.924 177.995 320.786V391.216C177.995 404.078 171.133 415.963 159.995 422.393L99.0002 457.609C87.8618 464.039 74.1386 464.039 63.0002 457.609L2.00533 422.393C-9.13311 415.963 -15.9946 404.078 -15.9946 391.216V320.786C-15.9946 307.924 -9.13311 296.039 2.00533 289.609L63.0002 254.393Z" fill="url(#paint2_linear_936_42034)"/> <path opacity="0.1" d="M65.213 260.194C75.1215 254.466 87.3347 254.466 97.2433 260.194L155.643 293.953C165.535 299.672 171.628 310.231 171.628 321.657V389.246C171.628 400.672 165.535 411.232 155.643 416.95L97.2433 450.71C87.3348 456.438 75.1215 456.438 65.213 450.71L6.81348 416.95C-3.07883 411.232 -9.17139 400.672 -9.17139 389.246V321.657C-9.17139 310.231 -3.07884 299.672 6.81346 293.953L65.213 260.194Z" stroke="#F8F8F8" stroke-width="1.5"/> <path opacity="0.1" d="M273.983 260.194C283.891 254.466 296.104 254.466 306.013 260.194L364.412 293.953C374.305 299.672 380.397 310.231 380.397 321.657V389.246C380.397 400.672 374.305 411.232 364.412 416.95L306.013 450.71C296.104 456.438 283.891 456.438 273.983 450.71L215.583 416.95C205.691 411.232 199.598 400.672 199.598 389.246V321.657C199.598 310.231 205.691 299.672 215.583 293.953L273.983 260.194Z" stroke="#F8F8F8" stroke-width="1.5"/> <path opacity="0.1" d="M65.213 -100.384C75.1215 -106.112 87.3347 -106.112 97.2433 -100.384L155.643 -66.6244C165.535 -60.9059 171.628 -50.3466 171.628 -38.9203V28.6687C171.628 40.0949 165.535 50.6542 155.643 56.3727L97.2433 90.1323C87.3348 95.8602 75.1215 95.8602 65.213 90.1323L6.81348 56.3728C-3.07883 50.6542 -9.17139 40.0949 -9.17139 28.6687V-38.9203C-9.17139 -50.3466 -3.07884 -60.9059 6.81346 -66.6244L65.213 -100.384Z" stroke="#F8F8F8" stroke-width="1.5"/> <path opacity="0.1" d="M273.983 -100.384C283.891 -106.112 296.104 -106.112 306.013 -100.384L364.412 -66.6244C374.305 -60.9059 380.397 -50.3466 380.397 -38.9203V28.6687C380.397 40.0949 374.305 50.6542 364.412 56.3727L306.013 90.1323C296.104 95.8602 283.891 95.8602 273.983 90.1323L215.583 56.3728C205.691 50.6542 199.598 40.0949 199.598 28.6687V-38.9203C199.598 -50.3466 205.691 -60.9059 215.583 -66.6244L273.983 -100.384Z" stroke="#F8F8F8" stroke-width="1.5"/> <path opacity="0.05" d="M273.983 -100.384C283.891 -106.112 296.104 -106.112 306.013 -100.384L364.412 -66.6247C374.305 -60.9061 380.397 -50.3468 380.397 -38.9206V28.6684C380.397 40.0947 374.305 50.654 364.412 56.3725L306.013 90.132C296.104 95.8599 283.891 95.8599 273.983 90.132L215.583 56.3725C205.691 50.654 199.598 40.0947 199.598 28.6684V-38.9206C199.598 -50.3468 205.691 -60.9061 215.583 -66.6247L273.983 -100.384Z" fill="#F8F8F8"/> <path opacity="0.1" d="M-41.7812 77.2921C-31.8726 71.5641 -19.6594 71.5641 -9.75089 77.292L48.6486 111.052C58.5409 116.77 64.6335 127.33 64.6335 138.756V206.345C64.6335 217.771 58.541 228.33 48.6487 234.049L-9.75088 267.808C-19.6594 273.536 -31.8726 273.536 -41.7812 267.808L-100.181 234.049C-110.073 228.33 -116.166 217.771 -116.166 206.345V138.756C-116.166 127.33 -110.073 116.77 -100.181 111.052L-41.7812 77.2921Z" stroke="#F8F8F8" stroke-width="1.5"/> <path opacity="0.1" d="M375.756 77.2921C385.664 71.5641 397.878 71.5641 407.786 77.292L466.186 111.052C476.078 116.77 482.171 127.33 482.171 138.756V206.345C482.171 217.771 476.078 228.33 466.186 234.049L407.786 267.808C397.878 273.536 385.664 273.536 375.756 267.808L317.356 234.049C307.464 228.33 301.372 217.771 301.372 206.345V138.756C301.372 127.33 307.464 116.77 317.356 111.052L375.756 77.2921Z" stroke="#F8F8F8" stroke-width="1.5"/> <path opacity="0.5" d="M65.213 260.194C75.1215 254.466 87.3347 254.466 97.2433 260.194L155.643 293.953C165.535 299.672 171.628 310.231 171.628 321.657V389.246C171.628 400.672 165.535 411.232 155.643 416.95L97.2433 450.71C87.3348 456.438 75.1215 456.438 65.213 450.71L6.81348 416.95C-3.07883 411.232 -9.17139 400.672 -9.17139 389.246V321.657C-9.17139 310.231 -3.07884 299.672 6.81346 293.953L65.213 260.194Z" fill="url(#paint3_radial_936_42034)"/> </g> <path d="M230 110H138C131.373 110 126 115.373 126 122V246C126 252.627 131.373 258 138 258H230C236.627 258 242 252.627 242 246V122C242 115.373 236.627 110 230 110Z" fill="#F8F8F8" fill-opacity="0.02"/> <g filter="url(#filter0_i_936_42034)"> <path d="M230 132H138C128.059 132 120 140.059 120 150V217C120 226.941 128.059 235 138 235H230C239.941 235 248 226.941 248 217V150C248 140.059 239.941 132 230 132Z" fill="#282828" fill-opacity="0.7"/> <path d="M230 132.75H138C128.473 132.75 120.75 140.473 120.75 150V217C120.75 226.527 128.473 234.25 138 234.25H230C239.527 234.25 247.25 226.527 247.25 217V150C247.25 140.473 239.527 132.75 230 132.75Z" stroke="url(#paint4_linear_936_42034)" stroke-opacity="0.25" stroke-width="1.5"/> </g> <g filter="url(#filter1_d_936_42034)"> <path d="M230 138H138C131.373 138 126 143.373 126 150V202C126 208.627 131.373 214 138 214H230C236.627 214 242 208.627 242 202V150C242 143.373 236.627 138 230 138Z" fill="#F8F8F8" fill-opacity="0.05"/> <path d="M230 138.75H138C131.787 138.75 126.75 143.787 126.75 150V202C126.75 208.213 131.787 213.25 138 213.25H230C236.213 213.25 241.25 208.213 241.25 202V150C241.25 143.787 236.213 138.75 230 138.75Z" stroke="url(#paint5_linear_936_42034)" stroke-opacity="0.25" stroke-width="1.5"/> </g> <g filter="url(#filter2_i_936_42034)"> <path fill-rule="evenodd" clip-rule="evenodd" d="M175.2 222.84C171.176 222.84 167.352 219.609 163.329 219.609H116C112.686 219.609 110 222.296 110 225.609V229.609C110 232.923 112.686 235.609 116 235.609H252C255.314 235.609 258 232.923 258 229.609V225.609C258 222.296 255.314 219.609 252 219.609H204.672C200.648 219.609 196.824 222.84 192.8 222.84H175.2Z" fill="#282828" fill-opacity="0.7"/> <mask id="mask1_936_42034" style="mask-type:luminance" maskUnits="userSpaceOnUse" x="110" y="219" width="148" height="17"> <path fill-rule="evenodd" clip-rule="evenodd" d="M175.2 222.84C171.176 222.84 167.352 219.609 163.329 219.609H116C112.686 219.609 110 222.296 110 225.609V229.609C110 232.923 112.686 235.609 116 235.609H252C255.314 235.609 258 232.923 258 229.609V225.609C258 222.296 255.314 219.609 252 219.609H204.672C200.648 219.609 196.824 222.84 192.8 222.84H175.2Z" fill="white"/> </mask> <g mask="url(#mask1_936_42034)"> <path d="M116 221.109H163.329V218.109H116V221.109ZM111.5 225.609C111.5 223.124 113.515 221.109 116 221.109V218.109C111.858 218.109 108.5 221.467 108.5 225.609H111.5ZM111.5 229.609V225.609H108.5V229.609H111.5ZM116 234.109C113.515 234.109 111.5 232.095 111.5 229.609H108.5C108.5 233.752 111.858 237.109 116 237.109V234.109ZM252 234.109H116V237.109H252V234.109ZM256.5 229.609C256.5 232.095 254.485 234.109 252 234.109V237.109C256.142 237.109 259.5 233.752 259.5 229.609H256.5ZM256.5 225.609V229.609H259.5V225.609H256.5ZM252 221.109C254.485 221.109 256.5 223.124 256.5 225.609H259.5C259.5 221.467 256.142 218.109 252 218.109V221.109ZM204.672 221.109H252V218.109H204.672V221.109ZM192.8 221.34H175.2V224.34H192.8V221.34ZM204.672 218.109C202.309 218.109 200.065 219.055 198.165 219.838C196.141 220.671 194.462 221.34 192.8 221.34V224.34C195.162 224.34 197.406 223.394 199.307 222.612C201.33 221.779 203.01 221.109 204.672 221.109V218.109ZM163.329 221.109C164.99 221.109 166.67 221.779 168.693 222.612C170.594 223.394 172.838 224.34 175.2 224.34V221.34C173.538 221.34 171.859 220.671 169.835 219.838C167.935 219.055 165.691 218.109 163.329 218.109V221.109Z" fill="url(#paint6_linear_936_42034)" fill-opacity="0.25"/> </g> </g> <path opacity="0.1" d="M184 0V82" stroke="url(#paint7_linear_936_42034)" stroke-width="1.5"/> <path opacity="0.1" d="M184 286V368" stroke="url(#paint8_linear_936_42034)" stroke-width="1.5"/> <g filter="url(#filter3_di_936_42034)"> <path d="M184 90C187.314 90 190 87.3137 190 84C190 80.6863 187.314 78 184 78C180.686 78 178 80.6863 178 84C178 87.3137 180.686 90 184 90Z" fill="#F8F8F8" fill-opacity="0.01"/> <path d="M184 90C187.314 90 190 87.3137 190 84C190 80.6863 187.314 78 184 78C180.686 78 178 80.6863 178 84C178 87.3137 180.686 90 184 90Z" fill="#121212" fill-opacity="0.3"/> <path d="M184 89.25C186.899 89.25 189.25 86.8995 189.25 84C189.25 81.1005 186.899 78.75 184 78.75C181.101 78.75 178.75 81.1005 178.75 84C178.75 86.8995 181.101 89.25 184 89.25Z" stroke="url(#paint9_linear_936_42034)" stroke-opacity="0.25" stroke-width="1.5"/> </g> <path d="M184 87C185.657 87 187 85.6569 187 84C187 82.3431 185.657 81 184 81C182.343 81 181 82.3431 181 84C181 85.6569 182.343 87 184 87Z" fill="#F8F8F8"/> <g filter="url(#filter4_di_936_42034)"> <path d="M184 278C180.686 278 178 280.686 178 284C178 287.314 180.686 290 184 290C187.314 290 190 287.314 190 284C190 280.686 187.314 278 184 278Z" fill="#F8F8F8" fill-opacity="0.01"/> <path d="M184 278C180.686 278 178 280.686 178 284C178 287.314 180.686 290 184 290C187.314 290 190 287.314 190 284C190 280.686 187.314 278 184 278Z" fill="#121212" fill-opacity="0.3"/> <path d="M184 278.75C181.101 278.75 178.75 281.101 178.75 284C178.75 286.899 181.101 289.25 184 289.25C186.899 289.25 189.25 286.899 189.25 284C189.25 281.101 186.899 278.75 184 278.75Z" stroke="url(#paint10_linear_936_42034)" stroke-opacity="0.25" stroke-width="1.5"/> </g> <path d="M184 281C182.343 281 181 282.343 181 284C181 285.657 182.343 287 184 287C185.657 287 187 285.657 187 284C187 282.343 185.657 281 184 281Z" fill="#F8F8F8"/> <rect x="162" y="155" width="42" height="48" fill="url(#pattern0_936_42034)"/> </g> <defs> <filter id="filter0_i_936_42034" x="120" y="132" width="128" height="103" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"> <feFlood flood-opacity="0" result="BackgroundImageFix"/> <feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset/> <feGaussianBlur stdDeviation="4"/> <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/> <feColorMatrix type="matrix" values="0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0.25 0"/> <feBlend mode="normal" in2="shape" result="effect1_innerShadow_936_42034"/> </filter> <filter id="filter1_d_936_42034" x="102" y="138" width="164" height="124" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"> <feFlood flood-opacity="0" result="BackgroundImageFix"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset dy="24"/> <feGaussianBlur stdDeviation="12"/> <feComposite in2="hardAlpha" operator="out"/> <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.3 0"/> <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_936_42034"/> <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_936_42034" result="shape"/> </filter> <filter id="filter2_i_936_42034" x="110" y="219.609" width="148" height="16" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"> <feFlood flood-opacity="0" result="BackgroundImageFix"/> <feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset/> <feGaussianBlur stdDeviation="4"/> <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/> <feColorMatrix type="matrix" values="0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0.25 0"/> <feBlend mode="normal" in2="shape" result="effect1_innerShadow_936_42034"/> </filter> <filter id="filter3_di_936_42034" x="162" y="78" width="44" height="49.3333" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"> <feFlood flood-opacity="0" result="BackgroundImageFix"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset dy="21.3333"/> <feGaussianBlur stdDeviation="8"/> <feComposite in2="hardAlpha" operator="out"/> <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.4 0"/> <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_936_42034"/> <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_936_42034" result="shape"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset/> <feGaussianBlur stdDeviation="2.66667"/> <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/> <feColorMatrix type="matrix" values="0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0.25 0"/> <feBlend mode="normal" in2="shape" result="effect2_innerShadow_936_42034"/> </filter> <filter id="filter4_di_936_42034" x="162" y="278" width="44" height="49.3333" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"> <feFlood flood-opacity="0" result="BackgroundImageFix"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset dy="21.3333"/> <feGaussianBlur stdDeviation="8"/> <feComposite in2="hardAlpha" operator="out"/> <feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.4 0"/> <feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_936_42034"/> <feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_936_42034" result="shape"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset/> <feGaussianBlur stdDeviation="2.66667"/> <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/> <feColorMatrix type="matrix" values="0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0.25 0"/> <feBlend mode="normal" in2="shape" result="effect2_innerShadow_936_42034"/> </filter> <pattern id="pattern0_936_42034" patternContentUnits="objectBoundingBox" width="1" height="1"> <use xlink:href="#image0_936_42034" transform="scale(0.0119048 0.0104167)"/> </pattern> <radialGradient id="paint0_radial_936_42034" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(184 184) rotate(90) scale(184)"> <stop stop-color="#D9D9D9"/> <stop offset="1" stop-color="#737373" stop-opacity="0"/> </radialGradient> <linearGradient id="paint1_linear_936_42034" x1="222.5" y1="60.5008" x2="361.454" y2="-5.0957" gradientUnits="userSpaceOnUse"> <stop offset="0.16638" stop-color="#121212" stop-opacity="0.2"/> <stop offset="1" stop-color="#121212" stop-opacity="0"/> </linearGradient> <linearGradient id="paint2_linear_936_42034" x1="81.0002" y1="355.499" x2="136.931" y2="256.518" gradientUnits="userSpaceOnUse"> <stop stop-color="#121212" stop-opacity="0"/> <stop offset="0.83362" stop-color="#121212" stop-opacity="0.2"/> </linearGradient> <radialGradient id="paint3_radial_936_42034" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(81.2281 355.452) rotate(90) scale(104.516 104.384)"> <stop offset="0.259713" stop-color="white" stop-opacity="0.01"/> <stop offset="0.599179" stop-color="white" stop-opacity="0.05"/> <stop offset="0.894542" stop-color="#F8F8F8" stop-opacity="0"/> </radialGradient> <linearGradient id="paint4_linear_936_42034" x1="184" y1="132" x2="221.866" y2="250.786" gradientUnits="userSpaceOnUse"> <stop stop-color="white" stop-opacity="0.4"/> <stop offset="0.4" stop-color="white" stop-opacity="0.01"/> <stop offset="0.6" stop-color="white" stop-opacity="0.01"/> <stop offset="1" stop-color="white" stop-opacity="0.1"/> </linearGradient> <linearGradient id="paint5_linear_936_42034" x1="184" y1="138" x2="207.479" y2="228.461" gradientUnits="userSpaceOnUse"> <stop stop-color="white" stop-opacity="0.4"/> <stop offset="0.4" stop-color="white" stop-opacity="0.01"/> <stop offset="0.6" stop-color="white" stop-opacity="0.01"/> <stop offset="1" stop-color="white" stop-opacity="0.1"/> </linearGradient> <linearGradient id="paint6_linear_936_42034" x1="184" y1="219.609" x2="184.869" y2="239.899" gradientUnits="userSpaceOnUse"> <stop stop-color="white" stop-opacity="0.4"/> <stop offset="0.4" stop-color="white" stop-opacity="0.01"/> <stop offset="0.6" stop-color="white" stop-opacity="0.01"/> <stop offset="1" stop-color="white" stop-opacity="0.1"/> </linearGradient> <linearGradient id="paint7_linear_936_42034" x1="184.5" y1="-2.18551e-08" x2="184.5" y2="82" gradientUnits="userSpaceOnUse"> <stop stop-color="#F8F8F8" stop-opacity="0"/> <stop offset="1" stop-color="#F8F8F8"/> </linearGradient> <linearGradient id="paint8_linear_936_42034" x1="184.5" y1="286" x2="184.5" y2="368" gradientUnits="userSpaceOnUse"> <stop stop-color="#F8F8F8"/> <stop offset="1" stop-color="#F8F8F8" stop-opacity="0"/> </linearGradient> <linearGradient id="paint9_linear_936_42034" x1="184" y1="78" x2="189.22" y2="91.1775" gradientUnits="userSpaceOnUse"> <stop stop-color="white" stop-opacity="0.4"/> <stop offset="0.4" stop-color="white" stop-opacity="0.01"/> <stop offset="0.6" stop-color="white" stop-opacity="0.01"/> <stop offset="1" stop-color="white" stop-opacity="0.1"/> </linearGradient> <linearGradient id="paint10_linear_936_42034" x1="184" y1="290" x2="178.78" y2="276.823" gradientUnits="userSpaceOnUse"> <stop stop-color="white" stop-opacity="0.4"/> <stop offset="0.4" stop-color="white" stop-opacity="0.01"/> <stop offset="0.6" stop-color="white" stop-opacity="0.01"/> <stop offset="1" stop-color="white" stop-opacity="0.1"/> </linearGradient> <clipPath id="clip0_936_42034"> <rect width="368" height="368" fill="white"/> </clipPath> <image id="image0_936_42034" width="84" height="96" preserveAspectRatio="none" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFQAAABgCAYAAACDgFV6AAAACXBIWXMAABYlAAAWJQFJUiTwAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAOdEVYdFNvZnR3YXJlAEZpZ21hnrGWYwAAHzpJREFUeAHtnXmUVNW1xs+tbkCZFBGwneKAijgAuhJHwNkXCBGNghhH0GWiRM17MW/5oisal6gvOCXOJo4oihoTjYBDxKF5IiIoKKNg0DDI7MDUNb3vt/ucsmjpqlvV1YQ/3Gtdqrrq1r3n7LvHb+9zcO47+o6+o+/oOyqXIteMVFtb2y6Kol5fffXVIRs3bmy7du3ar3XM/frrr6f98pe/XOL+DXTffffVaCyDv/zyS7dq1aqxt95661xXQSrI0Gw2K35EWVfGdd9///1B69atG7po0aJ2n3/+udN7l06nXXV1tctkMk5MHStG//n222/fYox97LHHajZs2HDn4sWLa1avXu3Wr1/v9ICHjxo1aprm6sqc6yZUEYb6wUS8Qh999NFvPv30036SUCeGumQy6cJ3iUTCtWrVym2zzTbGWE3qzw8//PCfGUslJtTY+Lj+o48+etnChQsHz5kzx+4N6XXak08+OdzfG340aQxRjO+zRQabu4YG5T788MPLFyxYMGj8+PGoVG7gDQnGcj6kc5a0aNECSVnqmjihhmPjHjD0iSee6CqpfGTq1Kloxybn6ZwHn3rqqQezgfP14yprHE21oZEfBAOPpk+f3kuD/uNf//pXt2TJkkaZudkLRdESnT/i6aefnurqJ9NkaeEaekjtZGb6yWZe8MEHH7RbuXLlZscFU9u0aTN29913X3rttddmy713wjWBgqpfd9119mAkdUOnTZvmli5dWhIz/bVqdKk/nn766YNdEx80kskxevToGpmXhzSeyySZ7QppjM4fmkqlnhHj+wVBzde+uFQ2Q/PVSTYzmjBhws4aTK958+aZ8ymX9FAuGzx48LBwj2B7SxkXD5hD1/rNP//5zxrUfM2aNUXHJbPjdtppp8vuv//+9pLS3PxKoeoi3zeqdt7OMHC3fPnyqH379r0+/vhjRzjSVEJahgwZ0lbX/sNvf/vb3Mfhza9//et2okFS0ZqWLVtOHT58+Fj/u5xE8ZB32WWXGnl0J88e57bGvF133bWtpLid/vwKpja8dzEqJqHZRm5skqMbciTE0ITsVG95dvPolSBJ0yB54955H+Wr4MN6cMOkyv0UJVx9zz33nOnNj5kgmClbnFC4Vovzq6qqKngvztl2221dr169XJcuXT6/7bbbPucazG8z9y58LVcmoVIw89BDD40UKEeyPzXLli0r2XYWoKWygRMHDRqUQFKCvf7FL37RX0ysIRz717/+5aTSSOBQfZU444wzmI8xk7m9+eabo6TqrxS6Cczs1KmT69+/vzv44IOn6yH+lxxXlSKVxDHHHJNgnqWofTnGH0baIWYm3nvvPQZfNXny5FcV5zmYWgFaKwm86LPPPlusyWZef/31rJjlDjjggOyKFSueVjBeo8NOxO7tueeeJAyX6bz3lSxEX3zxRULmJ6HfVkljqvfbb7+d5b1HiOmd828CM3fbbTd33HHHrZV2jbjyyis/kAlJ6kh36NAhJSnNaJ4c2biBfzEb+i3Kem+kpxdpApFsTmLkyJH7kAnV1dW5SpDixFsULSyXGiaQfn2UkcS47bff/mQxoYYMJxAmhoe44447DpXpuYLzJbHGTGlNlSS0+p133lmlz67bd9998TSdwm9l913v3r2dJPl3N9544/y2bdvyAJhfVg8soQcYzBpqFyuUK0nlvR0xqRYzeYmkdpGcQzsYWq79RFI8rVUce9PYsWPflf2rFuOqYE7Xrl0TSJ2kcSjMbGhWJJVO3/cUc87gfI0pIRvMUSUmJfRgqqXKayT1r2ArSX+R7B49epC11SqfX6zLVGt+Vbq2/VamxB6mBMcFW5qNofsFJbRh6hkyG6lfJImJZGsi3Vg2v6odk5JEuFKYyKRat25tv9PvZ0vF7tV1bXKSnqyYmpWTsPP79et3iTRgp81pAeEQYZEYdZ6kcJKYukzXTIg5MMgYpaN61qxZbx900EG9v/e97+2m8MgpClgpLOHv3E+pcIbzNcc0TGW6ugZaaPOFHWH+haig+yMkakBmoGX0I2VCCUkL3r1KceMPpG6H4iDixKDk8vvvv7/j6Yuh86ZMmfLo30SSoHUMXDbMMhWkiQc6cODA03Sfc3lojV0fqRUDWup6R+n1VT3sDIyU5lRDkjYkPjNp0qSJ++yzzyKdM+vmm29++h//+McXRAH6PqPPMnrIGT3sjMIyxpHRg8rOnDnTmIktLza3kpySl1icURUqqAlWS4paaFDnzJ49e8jEiROLSqkG6k444QRXU1MzXynqy3fddddsmYo0zkDSh83gqJMZSWpiyfPPP/9YPYD/xE7GjSdFC2bMmAFAs9FLaEu9ttTnLXSPKjEtmK60ppMJ99UDrBPT67bbbrs6xiMhSemhpzwjgx0tSKU6JS5oBg8vKkeQkGomdPMu2NBiJgZmEp5ocrVi6vMMknCHV/2W69gDEyMjOQWShoF6P0wIUakOb68DDzxwhBh0s9R8FR/Ug2HZkKNHOB8+Rxt0YIJyg5ew2Ps99tgDUxRJ5bNjxoyxsM010SnlJDjkt4QvkhT7XIyJQt5cjKHYyyOOOIIAeuaZZ575Ap9Jmm2CfMeEA9MOO+yw1grBhnbs2HEYsSboUKnxra6359577/07adMeGi8/Tuv6aEIKO0lohErrMx4qdiQr6UzLiWUUTRDgZ2XCsgoLS0KgCjK0AYPsithPXnfeeeeQPSBRnVHHQpPeYYcdnByCk0d93g8MRgZVCuqUuf7667tJMm+WBPWX2jqA4HKTBZnOzt27d/9fVQcuPuqoo3aQ6UjBVH2FXULNU/osKWZx8FlaDy8tu5mRXbUxYueJf+PesyBDGwSy9h7x97GhESrBhIuFTATfyqunCERBBU0qsJ28F6NbPfTQQ8fJBv+3GPA/slmd3njjDVTPNYVwYD4B6PvDH/7w9htuuOFCvW4PA8VYmGuMZCySTmOopDMj6TTpZc6KZ7PCE8xaxMmYYsWhQd1JwwBC/GBhZEIqgqR2KuSMiPsIU6Q+H+m8tFextCQ09aMf/Wj7Bx544DdS78GvvfZat2effdbJ7rliEh+XeNDAiaBgiiJ6n3baabdqHicoTKqT+dmosdTh/GTfkYi0xpqWo81I3Y2hSGeAJ+OETbFsaLhQCHCJz7CfvEftNeg2hRiKjRTjnVLJFYQlOj/FAWMvuuiiY4RTdnzuuedAiEyiKogHGIU4FaaqouCUVp4mIKQF0inVtmhCmpaSk00ptU2LiaY5PkMqiYp5eRPNQkgL3ljftynEBOI8pFSxK3GmSSfOAXumuHEb0H1gv0ozsiHBWO4j5rVRbr+NmLtG79Oy72kxMyupRSoy4AeYNn5TSh4PxVL5/IuRvxPAo/qycdHll1/eGeksJKF8hwdXhtLC1TsEO3AS77777hvKblzPnj0NQstLQytKAaKTaaEC+7lqSIuRSsYhrUnDTEUUGUUFBsag6sF2RiUUD2N5+XwJ1Q0tPtMTNXBBA2wjJ1WQodgxqZI7+uiju/ogHnVP6Xepa6655sNPPvnk7hNPPHH5OeecY5ikgvqKMZbrUGFlvEom+HuGHuJV+gqpNNUWo9MK5tPy6Om99trL0CWYCSOjEiuxBVU+2E4fFBvg+sILL4BBRgxQ6hPJNrZB+gqlnHw3f/58gvqDxMxx3rOmNJEMsZ8YOUGnvf7II48cq4D/dOGS5uUBrEvBB/IpAMuyl9jvtbKhY1988cW/aexfouYaP6FRRmhZcEDmhPKZ6cqgWE4pSCgoNq8ahEkcmQ/OCYYWCykAhPUA9lM59/i8QDojGxp+GJ177rlvSgNIM0cff/zx65BWpKvkSYmZaI9wUCfJm11bW3v1vffe+6zi2g1kZPrOnCoNGLLtqLfzNjPblIqn3bvI9yFLsFcF9ZYlMRgZcmOuVL4TkFoxhhIGCXcE0B143nnndYSpktD8wUd+PAl5/ldvuummG8SYlWJISeqPVApFItuiieLvv//972+Riq/Wg6nS/UCdEgiIIov8+lNwQM7P15VLsUfKTXh6hDYUviCCeqlT581hlJsjVFixZmup+DWqLPYFmHD1jLSsCyzTjykhwGW1mPq/igAW8ds4kkok0a1bN3fKKacQoj0h4Hu8Pq6SrYaRVaBjAMfum5TaXvELCItnaNnS6VwJDEUC5f0AeyOlnfYZQT32EacUJ4vAHpJOypZ10uQvVTFsuJh7gEfgAwKUkAkxpsrubXzllVfukYQu/v73v1+QqUgmkODPf/5zN3fu3KeUFb3LNTzoAlgMVAnYzPjbCRI8R1lTl/D7oOpxi3GNUWxwJJBCnU1iU/1teXzcQhZMlVd3L7/8shPkd6ycxnWXXnrpXfKwfcFJQX5AnUgGuL8kar3q6g8rJV0NuLK5CiYmASep6zjhoC//7Gc/m7K5cSv2bH3SSScNUoh2vx7OWfIBI5X27q0Mzs4JtfimULGwKd++5Yi0M3wuSWsdV0IDYR7IiAjogeYEgHRSDn2xQqefSjpBnUxaFGKR82cEFa5SWWTMT37yE9e5c+dvXY+HIInDo88Xg6hyBvtjnhunqYexu4pxN8ohnaFrWiKiB9FFIdptAsi7Nigbl03FwJHwNpfPcmO8Y55qtIlrQxsSv8FkILW8l8c/WUy7Vnk/um2hjC+aZe64446PZRdrf/zjH28ipUgnqi5muQsvvHAMYwV552H436aHDx9+uBj6O73fkZg4r/OOObaVtN4hxu6TVzsqW0yLSWgubMLGgLzIhlLHzn1O2lmpaickZu1++OGHn0+uD3ji6lNVK0+IYS+LMesJ2wJhJgYMGMCDmaI4diUMBC/wv03Jpu6i4t0wyiebA1x8/NxW0cQflPnVhG6RcpkaR0LtH24UsFClnXZDD2S0qXQOLhXuJVt3nGeOMZX0UA5trTRkihAq8+hIp9JZ8Ep38cUXv4Qkk4kF8EU46PZXX331cKISuu4aSz68QLSVsxqBlOY3wJVKRePQhiAzSJP/gvIxr52a0hzWGEliTpGjaeExU5M2GCxUasYhhxziYCqvw4YN46G+K4R/pfPAC+eCyAvMHiD73HH69OlFMzk686T6+4waNcoa1bz6V777LgT12E7itUC+KQwGl9yhFod039aqm58Ioo606SMDpEeMGDH31VdffWnIkCHuyiuvdPLcH19yySXjXD3TAzNTYsh2en/0k08+GUDmgoRtxTcIXO5NCw6feVC5pLbGuGiTlQEIL3weHynkiOQduzCQcvPtYqQ49yTZa6qVqaD+qP6pp546TtJ5lTKu6/X5XQ8++CDSibonw7kXXHDBfqS7dATGIcwWpkya0fXss89uH/qawvxdTGmNG9hHPo/f5KJKP1vne81Kk5fSk30tKOkxAFN/YZlrR48evSI4H6QYNee9wI0OihRO1fellJ7NloJPCJWiccOa4fzagdj5fVxwxPBBjD8U0HqQJkKm5pJQSKHUfygQ311MNWZRD3KeqXkSaUU3vpMdTF911VUDp02b1gnbWeK9rBNPuf96muAo0NE1krcgo6iUxnFKOS8fQIRAGnybStV+GiOkVHbyCiFPu1JY8yXgHGM9U5MwvG/fvq1kB3+qGlLfP/3pT5YSxyUiBpWdaUhbcOeddxKaWd8rQLoPpWL1/MdpdMiGfEwSClNzcyVLioM0NZXomKMdUQ7jTdWFnhO2utp5aSGlpI1G9rybPP5FkyZN6vT888+b1y6FiGeVqYHmvyZokswhA4LPdz7ujjXJYs1iuWzJty/iBekMts8UhHfB2zc3QwNp0n0OPPDAPsqMPlWos1z3XUsaKVXdX5LVGkZSxycMKkVrwA2OPPJIp2svl2RPkWMCS7CKruBJKr12Xj4/GqOiiH1Q+UGDBpkN1YBDn2TkF265LU1kUxzhb2x4oRUem6OwTgoguk+fPu6ss85yc+bMeUw1shWS0irhAnSV0EZJdJPOs6MFpSfOogUjnyVFktCIsoJfHdcpDlq/JagQMwPzwio+inU4HzpZjj32WECVlePHj39QAMsMD/NxJJVhRaTaOCe0My98anTCccrIdhVKBKxBIq6TehlzxdTOze2USiEYFpgWGMeBAIBSgeRTYCRdlf0nnlokezxdgMz/TZw4cQ0MAy/lGqFHVPO1g+vHqYAWdUpcwK/04MJmoL10slihYqs+mkowgVQYiQJ94pX2H9lXegFWa5yLpcobZs6cueTxxx9fIjhwlVT5ax/bEnIxH4t6dB1jIFLMNSmb5yFRBe1oHKcUUQVE5BlkfuahAbZpzhi0FPIVzoUaT60igdXPPPPMYpVc6t5++22QDyuBOB8mejwiSFrWg9n2NxKtVDVLLSsQKXfI7T2y3yjFcUrOL1KwgfDUZDcj37zQemthKCCz1PdvKq+87+oZyNxYhAAjCfE4DayU9wY8e3Qq184oM0FZOyvvbkyjZ5SqKN3MMFSClSkGQsdtFsuSivHed4xYC47sZ+etwSEF0sPu7urnZNIoZrHQIfJtk+HIhIY1wBawAVqC+FsqT2uQdTXTFk6PP3GuX6ABNS1TCvaCxVc8paAqqAO2pdTSR3MS0YZixiMpwIVQL6//1FD8vK4/S2P1akgWWAF/S90tE4Ohvgki18LJa5zmh6K5PAwjj6enCfEHaaKnSUFwZyaxtXh4xqGxthYSdaSYZI6TEohv/Q5AddIz0cinr0lagnQk6RGVZKaVrKRhKCtDaBwrZRyxy8ikneE90B1SUElgGaeCc+Aop6+JsVDmUD7ew3+EszFp9B3K4WBBgh0gWPSJ6tykVD0p25migUxMtB5ROWAYasBQMWcUKE7YZC/8IxWIlOcaFlrJPk4cBjEi4AREDyetPqVen158MWbfK664ouvdd989x9VXPE3tWZyAKksSzZaCSuk1LT+QlvlKaz50LyfFwJRHtmgeyzExTtoJxWoJZ6EC1wS2o4/S1a8lck2lsPiLQFvgx+ra2toHJCEvklcTmJdKmCBqRyrkIaWhZRIJpEvZupX1HghKfNxgn3OImfaKWYCZqLpCpWyQTt88FmsMsWwobSrOSylMRbVmz569wjWBYCYPhRZDXXOmSht/VLniE5U1Juq7JXSnlKr6qD2rRvRwjjjssMNawESI1m/ec0gaN0q1N0rLYCyH2VGl1Cl9Zz2icroZBf2ZoOpRCRsRxOoP9RJqPU3YTlTe1+IXujIopIekhAsXLnzxlltueXTJkiXriWlxfAJ432NJYjm2FLRJUtpajDgKm4ltlH2uUxJSx4I6pFGmAedUJwmEkUmZspTmBENt+Q3MhJGhe9nVx6yV62CGPFqfX7OGqe+5EgnnQzaiCa0W4+5XFbPWJwfZEHCPGTNmiia+gfNKJby70kvs8SF6IKGHPqWHx7JtbKRJJIxGIuV8rNkWqRTWm66fXjZTTvcyVJShFKry1iblLs5kp0yZ8pJuus7FIKQN58PvxMAFf/nLX/4wefLkBSz+QiphJrGiTs189tln6wSlTfEpYUmE2vtNCQ5Q1rQ/jkjXtkoobd8sN1QKjWqnFbemZSvThEahcxlmRvU7Q8S2m5vMs9gJ3IS0k7VJ9DShUnhTSSctOeuWLVv2VMEb+E5imCM136BK5N9VPLtPsd5aMhbnO0PyDmOwbPRHJA7lqD0rPpBSxco/0L0tdCIMQhL1dUrhEB7cmAjWOWHChHRwPv4SDV9jU9HOEcQeb0cKRiqW93UGOyjwYaJAiPtkT63mECC0IJE4Hopfus6Ct956646XXnrpLS+JFs54yYRs4uH91KlT5+nhzS8nNMOEADXqeif86le/ag0zJZUE6nZPlssoUUnLtGSCkQzMLFXFv8WzYidgL0k99cSrNMFqqVK10PFWUt2W+q6V/qaxq6Vwxi6Cy3oId/yBbNPOHowgPFkya9asV2QvFzhvJ4Nqh9SQbMa/xwZGfrVwlcKnvnIaA10ZxLooxaOEZPdIMp+RaqcGDBhgmUhTeuiLUdENCPJXz4XOZee9Hp6eJXw8ZanyStmuN8WwiWxNIYnoINVa47wKewZbnuxzaUsJnQ+6XX0QHqqLtlpYTuIdPaCT9ZuSvRNjk/aAyh+pP5/hM79XSlm2MS7FMlCoPOriwQKTKoUhluvCWN86aF1vzquxmLuSZX7ec2fyliSGPqW6kAoG8imhrb+E6cqWvlbMO9mVQTgnMi7Z6h5S+Z6s73ffRCmuuaioDeWJhjYcJA3mSoWMsb5HHglL+yWHaa/O4dXeewaF3qMAStR5plqWoofDgtbwt9Xd+Y2Y8YErk3BOikQofxzt+/dDB4xNzzUDFQ3ss37Dq5DX5m0hYR46rDnyvUeG6oQ+pECunpHGLL/GMwdU6FphESsZTZDaZMAoJWVz9Zt5rgwiJmWXCdGJysTYLcxCwLAXU1Maaxujorm8b+0xyURCQbGBtpBO4K7Ir4jzvUdJ35uZ9A2zYcuLwCSTRpgHI/1BJpMMi1jDA3K+m47ryBnOcGUQEQINY/p92/79+3dlvmzchYD4RrCK634sG+qDe+pJBhyg4sR3rl5CWW9E0GxMC9AYR2iTgYFBtZFGgAn29iAdJC3Ug7J0kIxGnxtjdW7K78CQUYTxtp5pWQ0AOCclCjS2HQVaxjor+pV8mPStBrimUqxthqil6M8EbTgLFizI+LIqcFckOxWxGo5VcTguygiKT81e+RUj5riAyWA8SxH1WYogm4eCxPM9wDX7JXFbH8yHUkZaEoZzeqd9+/bHuBIJ1fb9oW3Zzwnwo3v37lYnQ1JDZlQpirtoYRPnpNfgzQ1DRF3ZxUZMyyE7Xq1NtXmv800aedVvUvK6gLshHbTVwGIcS63NBlPbAbPEtHAoIyvLORGusR2b6BNK4IqX2XPK5p0npRWjuEsT7Q+eqNTFJFFxpjEB5yPpSaK2clTGNJio1w0wVK8cdZKujVLrOkliUlKd1MRSMI2cmgX/mBLdAjDDnB6liHxbqsxpTqnOCUmnNs8ih3Hjxk2mm472GgkFVVzr/XQVtqOxN3EJMBZSSg4MOgMzAGQFmhiSI6YmYRowGQwOB1CZ4kHDHP0i/xQrgDVRC+wBJyg3IPlEEZgCXyyjEpnxLYwZXSN2wyfMZOOYoUOH8ufryvbAb6tor3HfdMNsWRuaT1GukTcnsbZOkwoo6yexhZIAmJMI3Wps1cMrO8zIJJAckP9n9SDMthKKCZiwNVCoI6oI40gUlN7yG1vLjn3W+awCebtPnz7H6JyOjfUDBODarwyhxfvTs88+exTbsBHqYd8p41AWJ3JxFaZSN8LKdTSzjRtOCibSiEsRTwwzZ0WqSg8RYVb4oSQwS1mBcrSrByhCTm2mBMlXJJHbdojdaUKSgC1lYzrZ2LWS7Md79OhxGdcMe0X5VXFW2qYBjMWzuv862enX+vXrJ20ft17mxZhItYF5+HFUnMoS9zxJTYROCvqfwvfEerziwGhjYfB51cPcWh0PUOQ2PAWE8ZupVrGkRpIEINpKDG2lc1qGQzWjbr179/6ppK8Dv0UiKfIdfPDBgCLzFSZ9KJSJBjCWqhCC0RhG6YPwDAeZ0riSmK68mlFFGFy2/cjmbWodQpBwBGrwWVh02xg4QXxoTWkyCWwCyHLsFpLKbUC22LtOP93Gt9jA6OohQ4b06Nmz594yLdvKvi5VOWXRyJEj5+VhBgErsOjD2/akrpkUIykXY3bK2v2mMSrI0Gzp/3VFlPfbTdaKxvktaBBLyFFN1ZhayIFg91opPjWGKiyjFNqyRX23Qgt2htTfCba25ALexGRCdBAaGUIYB0OJSHCiurZFDz4OrZj6F2sWK/VG2bzfulIor36D1NA5nPYOjomzzj0hh8JOi/QiJTxmavk6sWbYRy8ANuEIf/tXu5XfONCKcCGvrxRTS14v35wUgJhQISCEUuhjjokMC8zAh1C5VXPOAPpUyneIhHJKbvey8B6GSjotREOSfYtixee3RRlWjAL6E9VvgRlSzyo5n5aS2Ba+ShD2Aq2WpKJhSGsQjKDyxmzfamMYA9gBWZ28fR0JBXGvGJr22VLFQOdYy7u3FPlqo93aw4VZKq2ov97TyGV20aezBsQ40/pkXWj+ysda+U521wAXZWq2rx3q7jGGss1TISpld8YtQbnkAe/r6sFr2y2R956h4cgxz2+VbnhBgAbpppNEG8bg6jcJtH3tSC5InUOLYqWpefZFaxrlSw+bolo6ShMXnXEeN60DAsR70z2n1w3ERqF/iQPVDjir7DDofxr8gZQ5P/50FaYoxvdbWkqDx+d/TrACIaGU8n7bLoiN/tlOnb2VXf0mLwlfpg4hXtYDK6i34QLgB0h63g5imbx4eMuBI+7fwEzIJwyWWeHxUX/wU2A+kCpiSUncRr/v50aAatnJjR6sNlSLczAFwgRSijnTMJProOq5hqVmqNZtVV4+n77JTqPI75ufAG0XbmARADEqQgbQ0aFDhxAdZD38x2vWSyUhkm2j7u1ybo8m1wy0Vap8oLwwKgrqTxbF0mu/xCds7+Z8+6ON1fcBmDfP/79E6BTx17PLu2agWBuy/rvIQ4a5DQDIaigDI21hVYqvHhiBfoFo8T6gSUglEGHeNXlptnkVy+UrGqOVSwGIgXz3h733ALHzjiu3WiPs6h364iuZWhajrdaGFqBNuj+iAt3FzS2NJVNztqyUS5sbU4OMLtoax/0dlUn/D/IFqETGgDvZAAAAAElFTkSuQmCC"/> </defs> </svg>`;

const KEYBOARD_SVG = `<svg width="148" height="17" viewBox="0 0 148 17" fill="none" xmlns="http://www.w3.org/2000/svg"> <g filter="url(#filter0_bi_743_42277)"> <mask id="path-1-inside-1_743_42277" fill="white"> <path fill-rule="evenodd" clip-rule="evenodd" d="M65.2001 3.83905C61.1762 3.83905 57.3524 0.608398 53.3286 0.608398H6C2.68629 0.608398 0 3.29469 0 6.6084V10.6084C0 13.9221 2.68629 16.6084 6 16.6084H142C145.314 16.6084 148 13.9221 148 10.6084V6.6084C148 3.29469 145.314 0.608398 142 0.608398H94.6715C90.6476 0.608398 86.8239 3.83905 82.8 3.83905V3.83905H65.2001V3.83905Z"/> </mask> <path fill-rule="evenodd" clip-rule="evenodd" d="M65.2001 3.83905C61.1762 3.83905 57.3524 0.608398 53.3286 0.608398H6C2.68629 0.608398 0 3.29469 0 6.6084V10.6084C0 13.9221 2.68629 16.6084 6 16.6084H142C145.314 16.6084 148 13.9221 148 10.6084V6.6084C148 3.29469 145.314 0.608398 142 0.608398H94.6715C90.6476 0.608398 86.8239 3.83905 82.8 3.83905V3.83905H65.2001V3.83905Z" fill="#282828" fill-opacity="0.7" style="mix-blend-mode:luminosity"/> <path d="M6 2.1084H53.3286V-0.891602H6V2.1084ZM1.5 6.6084C1.5 4.12312 3.51472 2.1084 6 2.1084V-0.891602C1.85786 -0.891602 -1.5 2.46626 -1.5 6.6084H1.5ZM1.5 10.6084V6.6084H-1.5V10.6084H1.5ZM6 15.1084C3.51472 15.1084 1.5 13.0937 1.5 10.6084H-1.5C-1.5 14.7505 1.85786 18.1084 6 18.1084V15.1084ZM142 15.1084H6V18.1084H142V15.1084ZM146.5 10.6084C146.5 13.0937 144.485 15.1084 142 15.1084V18.1084C146.142 18.1084 149.5 14.7505 149.5 10.6084H146.5ZM146.5 6.6084V10.6084H149.5V6.6084H146.5ZM142 2.1084C144.485 2.1084 146.5 4.12312 146.5 6.6084H149.5C149.5 2.46626 146.142 -0.891602 142 -0.891602V2.1084ZM94.6715 2.1084H142V-0.891602H94.6715V2.1084ZM82.8 2.33905H65.2001V5.33905H82.8V2.33905ZM94.6715 -0.891602C92.3093 -0.891602 90.0651 0.0543403 88.1648 0.836662C86.1413 1.66967 84.4617 2.33905 82.8 2.33905V5.33905C85.1623 5.33905 87.4064 4.39311 89.3068 3.61078C91.3302 2.77778 93.0099 2.1084 94.6715 2.1084V-0.891602ZM53.3286 2.1084C54.9902 2.1084 56.6698 2.77778 58.6933 3.61079C60.5936 4.39311 62.8378 5.33905 65.2001 5.33905V2.33905C63.5384 2.33905 61.8588 1.66967 59.8353 0.836662C57.935 0.05434 55.6908 -0.891602 53.3286 -0.891602V2.1084Z" fill="url(#paint0_linear_743_42277)" fill-opacity="0.25" mask="url(#path-1-inside-1_743_42277)"/> </g> <defs> <filter id="filter0_bi_743_42277" x="-100" y="-99.3916" width="348" height="216" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"> <feFlood flood-opacity="0" result="BackgroundImageFix"/> <feGaussianBlur in="BackgroundImageFix" stdDeviation="50"/> <feComposite in2="SourceAlpha" operator="in" result="effect1_backgroundBlur_743_42277"/> <feBlend mode="normal" in="SourceGraphic" in2="effect1_backgroundBlur_743_42277" result="shape"/> <feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/> <feOffset/> <feGaussianBlur stdDeviation="4"/> <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/> <feColorMatrix type="matrix" values="0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0 0.972549 0 0 0 0.25 0"/> <feBlend mode="normal" in2="shape" result="effect2_innerShadow_743_42277"/> </filter> <linearGradient id="paint0_linear_743_42277" x1="74" y1="0.608398" x2="74.869" y2="20.8985" gradientUnits="userSpaceOnUse"> <stop stop-color="white" stop-opacity="0.4"/> <stop offset="0.4" stop-color="white" stop-opacity="0.01"/> <stop offset="0.6" stop-color="white" stop-opacity="0.01"/> <stop offset="1" stop-color="white" stop-opacity="0.1"/> </linearGradient> </defs> </svg>`;

const toMask = (svg: string) =>
  `url("data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}")`;
const masked = (src: string): CSSProperties => ({ WebkitMaskImage: src, maskImage: src });

const DOTS_SRC = toMask(DOTS_SVG);
const DEVICE_SRC = toMask(DEVICE_SVG);
const KEYBOARD_SRC = toMask(KEYBOARD_SVG);

const STYLES = `
.mei, .mei *, .mei *::before, .mei *::after { box-sizing: border-box; }
.mei { position: relative; width: 100%; height: 100%; min-width: 0; min-height: 0; overflow: hidden; color: hsl(var(--foreground)); background: var(--mei-bg, hsl(var(--background))); font-family: var(--font-body), ui-sans-serif, system-ui, sans-serif; -webkit-font-smoothing: antialiased; container-type: size; isolation: isolate; display: grid; grid-template-columns: 1.15fr 1fr; align-items: center; gap: clamp(12px, 4cqw, 56px); padding: clamp(20px, 7cqh, 64px) clamp(20px, 7cqw, 88px); text-align: left; }
.mei::before { position: absolute; inset: 0; z-index: -1; content: ""; background-image: linear-gradient(hsl(var(--border) / 0.6) 1px, transparent 1px); background-size: 100% clamp(24px, 8cqh, 48px); -webkit-mask-image: linear-gradient(90deg, transparent, black 30%, black 70%, transparent); mask-image: linear-gradient(90deg, transparent, black 30%, black 70%, transparent); opacity: 0.5; }
.mei-label { display: inline-flex; align-items: center; gap: 10px; margin-bottom: clamp(8px, 3cqh, 24px); color: hsl(var(--muted-foreground)); font-family: var(--font-mono, ui-monospace), ui-monospace, monospace; font-size: clamp(9px, 1.2cqw, 12px); letter-spacing: 0.2em; text-transform: uppercase; }
.mei-label__dot { width: 7px; height: 7px; border-radius: 50%; background: hsl(var(--primary)); box-shadow: 0 0 0 0 hsl(var(--primary) / 0.5); animation: mei-pulse 2.4s ease-out infinite; }
@keyframes mei-pulse { 0% { box-shadow: 0 0 0 0 hsl(var(--primary) / 0.45); } 70%, 100% { box-shadow: 0 0 0 8px hsl(var(--primary) / 0); } }
.mei-graphic { position: relative; justify-self: center; width: min(70cqh, 38cqw, 440px); aspect-ratio: 1; border-radius: 50%; background: radial-gradient(circle at 50% 45%, hsl(var(--primary) / 0.14), transparent 65%); }
.mei-graphic::after { position: absolute; inset: -4%; border: 1px dashed hsl(var(--border)); border-radius: 50%; content: ""; }
.mei-dots, .mei-device, .mei-device > span:first-child { position: absolute; inset: 0; width: 100%; height: 100%; }
.mei-ink { display: block; background: hsl(var(--foreground)); -webkit-mask-size: 100% 100%; mask-size: 100% 100%; -webkit-mask-repeat: no-repeat; mask-repeat: no-repeat; }
.mei-dots { background: hsl(var(--primary)); animation: mei-dots-drift 8s ease-in-out infinite alternate; }
.mei-device { animation: mei-device-float 6s ease-in-out infinite; }
.mei-keyboard { position: absolute; top: 59.6%; left: 50%; width: 40.2%; aspect-ratio: 148 / 17; transform: translateX(-50%); }
.mei-copy { position: relative; z-index: 2; }
.mei-copy h2 { margin: 0; font-family: var(--font-heading), ui-serif, Georgia, serif; font-size: clamp(24px, 7.2cqw, 92px); font-weight: 500; letter-spacing: -0.03em; line-height: 0.98; }
.mei-copy h2 em { color: hsl(var(--primary)); font-style: italic; }
.mei-copy p { max-width: 34ch; margin: clamp(8px, 3.6cqh, 28px) 0 0; padding-top: clamp(8px, 2.4cqh, 20px); border-top: 1px solid hsl(var(--border)); color: hsl(var(--muted-foreground)); font-size: clamp(10px, 1.7cqw, 20px); line-height: 1.5; }
@keyframes mei-device-float { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-5px); } }
@keyframes mei-dots-drift { from { transform: rotate(-0.4deg) scale(0.995); } to { transform: rotate(0.5deg) scale(1.008); } }
@container (max-width: 560px) { .mei { grid-template-columns: 1fr; text-align: center; } .mei-graphic { order: -1; width: min(42cqh, 60cqw); } .mei-copy p { margin-inline: auto; } }
.mei[data-still] *, .mei[data-still] *::before, .mei[data-still] *::after { animation: none !important; transition: none !important; }
`;

export interface FolioOpeningProps {
  label?: string;
  title?: string;
  description?: string;
  backgroundColor?: string;
  className?: string;
  style?: CSSProperties;
}

export function FolioOpening({
  label = "Chapter one",
  title = "Quiet tools, *loud* work.",
  description = "An interface set like a good page: calm margins, clear type and nothing between you and the next idea.",
  backgroundColor,
  className,
  style,
}: FolioOpeningProps) {
  const prefersReducedMotion = useReducedMotion();

  return (
    <section
      className={cn("mei", className)}
      data-still={prefersReducedMotion ? "" : undefined}
      style={backgroundColor ? { ...style, ["--mei-bg" as string]: backgroundColor } : style}
    >
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <div className="mei-copy">
        <span className="mei-label">
          <span className="mei-label__dot" aria-hidden="true" />
          {label}
        </span>
        <h2>{title.split("*").map((part, i) => (i % 2 ? <em key={i}>{part}</em> : part))}</h2>
        <p>{description}</p>
      </div>
      <div className="mei-graphic" aria-hidden="true">
        <span className="mei-ink mei-dots" style={masked(DOTS_SRC)} />
        <div className="mei-device">
          <span className="mei-ink" style={masked(DEVICE_SRC)} />
          <span className="mei-ink mei-keyboard" style={masked(KEYBOARD_SRC)} />
        </div>
      </div>
    </section>
  );
}
```

---

# Dispatch Colophon

> An editorial footer with an outlined serif sign-off, a ruled sign-up line and mono legal links, drawn from your theme.

Install: `npx @modus-ui/cli add dispatch-colophon`

An editorial footer that opens with a large outlined italic serif sign-off, then a ruled row with a mono issue number, a short blurb and an underlined email field whose primary button stretches into an inline success state. Legal links sit in a mono row underneath. Every colour comes from theme tokens, so it follows light and dark mode and the palette picker. All copy and links come from props, and `onSubmit` receives the entered email. Layout scales through container query units. Transitions stop when the user prefers reduced motion.

## Installation

### CLI

```bash
npx @modus-ui/cli add dispatch-colophon
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/dispatch-colophon.tsx`.
3. Paste the code.

## Usage

```tsx
import { DispatchColophon } from "@/components/ui/dispatch-colophon";

export default function Example() {
  return (
    <div className="relative aspect-video w-full overflow-hidden">
      <DispatchColophon onSubmit={(email) => console.log(email)} />
    </div>
  );
}
```

## Props

| Prop              | Type                                | Default                                                                                   | Description                                          |
| :---------------- | :---------------------------------- | :---------------------------------------------------------------------------------------- | :--------------------------------------------------- |
| `marker`          | `string`                            | `"01"`                                                                                    | Issue number shown as "No. 01".                      |
| `description`     | `string`                            | `"Letters from the studio, once a month:\nnew components, notes on craft, nothing else."` | Blurb beside the marker; `\n` breaks the line.       |
| `placeholder`     | `string`                            | `"you@studio.com"`                                                                        | Email field placeholder.                             |
| `buttonLabel`     | `string`                            | `"Subscribe"`                                                                             | Submit button label.                                 |
| `successLabel`    | `string`                            | `"On the list. Thank you."`                                                               | Button label after a successful submit.              |
| `closingPhrase`   | `string`                            | `"Until next issue."`                                                                     | Oversized outlined serif sign-off.                   |
| `copyright`       | `string`                            | `"© 2026 Modus. Set with care."`                                                          | Copyright text in the legal row.                     |
| `links`           | `{ label: string; href: string }[]` | Privacy, Terms and Contact anchors                                                        | Links in the legal row.                              |
| `onSubmit`        | `(email: string) => void`           | None                                                                                      | Called with the email when the form is submitted.    |
| `backgroundColor` | `string`                            | None                                                                                      | Footer background; defaults to the theme background. |
| `accentColor`     | `string`                            | None                                                                                      | Success-state colour; defaults to the theme primary. |
| `className`       | `string`                            | None                                                                                      | Extra classes for the footer.                        |
| `style`           | `CSSProperties`                     | None                                                                                      | Inline styles for the footer.                        |

## Source

`components/ui/dispatch-colophon.tsx`

```tsx
"use client";
// Ported from ThreeUI Community's Newsletter Footer (MIT, © 2026 Meng To).

import { useReducedMotion } from "framer-motion";
import { useState, type CSSProperties, type FormEvent } from "react";

import { cn } from "@/lib/utils";

const STYLES = `
.mnf, .mnf *, .mnf *::before, .mnf *::after { box-sizing: border-box; }
.mnf { position: relative; width: 100%; height: 100%; min-width: 0; min-height: 0; overflow: hidden; color: hsl(var(--foreground)); background: var(--mnf-bg, hsl(var(--background))); font-family: var(--font-body), ui-sans-serif, system-ui, sans-serif; -webkit-font-smoothing: antialiased; container-type: size; isolation: isolate; display: flex; flex-direction: column; justify-content: space-between; padding: clamp(18px, 6cqh, 56px) clamp(20px, 5cqw, 80px) clamp(12px, 3cqh, 24px); }
.mnf button, .mnf input { font: inherit; }
.mnf-wordmark { width: 100%; color: transparent; -webkit-text-stroke: 1px hsl(var(--primary) / 0.55); font-family: var(--font-heading), ui-serif, Georgia, serif; font-size: clamp(44px, 13.5cqw, 176px); font-style: italic; font-weight: 400; letter-spacing: -0.04em; line-height: 0.95; white-space: nowrap; }
.mnf-row { display: grid; grid-template-columns: auto 1fr minmax(0, 420px); align-items: end; gap: clamp(14px, 3cqw, 40px); padding-top: clamp(14px, 4cqh, 28px); border-top: 1px solid hsl(var(--border)); }
.mnf-mark { color: hsl(var(--primary)); font-family: var(--font-mono, ui-monospace), ui-monospace, monospace; font-size: clamp(10px, 1.3cqw, 13px); letter-spacing: 0.2em; text-transform: uppercase; }
.mnf-mark::before { content: "No. "; color: hsl(var(--muted-foreground)); }
.mnf-brand { margin: 0; color: hsl(var(--muted-foreground)); font-size: clamp(10px, 1.5cqw, 17px); line-height: 1.55; white-space: pre-line; }
.mnf-form { position: relative; display: flex; align-items: center; height: 48px; border-bottom: 1.5px solid hsl(var(--foreground)); transition: border-color 0.3s; }
.mnf-form:focus-within { border-color: hsl(var(--primary)); }
.mnf-form > svg { flex: none; margin-right: 10px; fill: none; stroke: hsl(var(--muted-foreground)); stroke-width: 1.5; pointer-events: none; transition: opacity 0.25s; }
.mnf-form input { flex: 1; min-width: 0; height: 100%; border: 0; outline: 0; color: hsl(var(--foreground)); background: transparent; font-size: 14px; transition: opacity 0.25s; }
.mnf-form input::placeholder { color: hsl(var(--muted-foreground)); }
.mnf-button { position: absolute; right: 0; bottom: 6px; display: inline-flex; align-items: center; gap: 8px; height: 36px; padding: 0 16px; border: 0; border-radius: var(--radius, 999px); color: hsl(var(--primary-foreground)); background: hsl(var(--primary)); font-family: var(--font-mono, ui-monospace), ui-monospace, monospace; font-size: 11px; letter-spacing: 0.14em; text-transform: uppercase; cursor: pointer; transition: transform 0.2s, width 0.45s cubic-bezier(0.32,0.72,0,1); }
.mnf-button:hover { transform: translateY(-1px); }
.mnf-button:active { transform: scale(0.97); }
.mnf-button__arrow { transition: transform 0.3s; }
.mnf-button:hover .mnf-button__arrow { transform: translateX(3px); }
.mnf-form.is-success > svg, .mnf-form.is-success input { opacity: 0; }
.mnf-form.is-success { border-color: var(--mnf-accent, hsl(var(--primary))); }
.mnf-form.is-success .mnf-button { left: 0; justify-content: center; background: var(--mnf-accent, hsl(var(--primary))); }
.mnf-legal { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 8px clamp(12px, 1.8cqw, 24px); margin-top: clamp(10px, 3cqh, 22px); color: hsl(var(--muted-foreground)); font-family: var(--font-mono, ui-monospace), ui-monospace, monospace; font-size: clamp(8px, 1cqw, 11px); letter-spacing: 0.14em; text-transform: uppercase; }
.mnf-legal nav { display: flex; gap: clamp(12px, 2cqw, 28px); }
.mnf-legal a { color: inherit; text-decoration: none; transition: color 0.2s; }
.mnf-legal a:hover { color: hsl(var(--primary)); }
@container (max-width: 720px) {
  .mnf-row { grid-template-columns: auto 1fr; }
  .mnf-form { grid-column: 1 / -1; }
}
.mnf[data-still] *, .mnf[data-still] *::before, .mnf[data-still] *::after { animation: none !important; transition: none !important; }
`;

export interface DispatchColophonLink {
  label: string;
  href: string;
}

export interface DispatchColophonProps {
  marker?: string;
  description?: string;
  placeholder?: string;
  buttonLabel?: string;
  successLabel?: string;
  closingPhrase?: string;
  copyright?: string;
  links?: DispatchColophonLink[];
  onSubmit?: (email: string) => void;
  backgroundColor?: string;
  accentColor?: string;
  className?: string;
  style?: CSSProperties;
}

const DEFAULT_LINKS: DispatchColophonLink[] = [
  { label: "Privacy", href: "#privacy" },
  { label: "Terms", href: "#terms" },
  { label: "Contact", href: "#contact" },
];

function EnvelopeIcon() {
  return (
    <svg width="20" height="20" viewBox="0 0 24 24" aria-hidden="true">
      <path
        fill="none"
        d="M20.5 9.55v4.9c0 1.56 0 2.34-.3 2.94a2.75 2.75 0 0 1-1.21 1.21c-.6.3-1.38.3-2.94.3h-8.1c-1.56 0-2.34 0-2.94-.3a2.75 2.75 0 0 1-1.21-1.21c-.3-.6-.3-1.38-.3-2.94v-4.9c0-1.56 0-2.34.3-2.94A2.75 2.75 0 0 1 5.01 5.4c.6-.3 1.38-.3 2.94-.3h8.1c1.56 0 2.34 0 2.94.3a2.75 2.75 0 0 1 1.21 1.21c.3.6.3 1.38.3 2.94Z"
      />
      <path d="m3.55 6 6.61 5.14a3 3 0 0 0 3.68 0L20.45 6" fill="none" />
    </svg>
  );
}

export function DispatchColophon({
  marker = "01",
  description = "Letters from the studio, once a month:\nnew components, notes on craft, nothing else.",
  placeholder = "you@studio.com",
  buttonLabel = "Subscribe",
  successLabel = "On the list. Thank you.",
  closingPhrase = "Until next issue.",
  copyright = "© 2026 Modus. Set with care.",
  links = DEFAULT_LINKS,
  onSubmit,
  backgroundColor,
  accentColor,
  className,
  style,
}: DispatchColophonProps) {
  const prefersReducedMotion = useReducedMotion();
  const [subscribed, setSubscribed] = useState(false);

  const submit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const email = new FormData(event.currentTarget).get("email");
    onSubmit?.(typeof email === "string" ? email : "");
    setSubscribed(true);
  };

  return (
    <footer
      className={cn("mnf", className)}
      data-still={prefersReducedMotion ? "" : undefined}
      style={{
        ...style,
        ...(backgroundColor && { ["--mnf-bg" as string]: backgroundColor }),
        ...(accentColor && { ["--mnf-accent" as string]: accentColor }),
      }}
    >
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <div className="mnf-wordmark" aria-label={closingPhrase}>
        {closingPhrase}
      </div>
      <div>
        <div className="mnf-row">
          <span className="mnf-mark">{marker}</span>
          <p className="mnf-brand">{description}</p>
          <form
            className={cn("mnf-form", subscribed && "is-success")}
            aria-label="Newsletter sign-up"
            onSubmit={submit}
          >
            <EnvelopeIcon />
            <input
              name="email"
              aria-label="Email address"
              type="email"
              placeholder={placeholder}
              required
            />
            <button className="mnf-button" type="submit">
              {subscribed ? successLabel : buttonLabel}
              {!subscribed && (
                <span className="mnf-button__arrow" aria-hidden="true">
                  →
                </span>
              )}
            </button>
          </form>
        </div>
        <div className="mnf-legal">
          <span>{copyright}</span>
          <nav aria-label="Legal">
            {links.map((link) => (
              <a key={link.label} href={link.href}>
                {link.label}
              </a>
            ))}
          </nav>
        </div>
      </div>
    </footer>
  );
}
```

---

# Curved Carousel Hero

> A landing hero with a curved, draggable carousel of video cards that drifts like the inside of a cylinder.

Install: `npx @modus-ui/cli add curved-carousel-hero`

A one-screen hero for showing work in motion: a badge, a two-line headline and a lede above an arched row of tall cards. The cards drift right to left on their own; drag or fling them, or press the arrow keys, and they coast to a stop before the drift carries on. Cards near the edges grow taller and lean outward, recomputed every frame as rounded quads. Handwritten notes and arrows draw themselves in. Colours come from theme tokens, so it follows light and dark mode and the palette picker. Below 820px it stacks into a centred column with a shorter carousel. With reduced motion there is no entrance, no drift and no video.

## Installation

### CLI

```bash
npx @modus-ui/cli add curved-carousel-hero
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/curved-carousel-hero.tsx`.
3. Paste the code.

## Usage

```tsx
import { CurvedCarouselHero } from "@/components/ui/curved-carousel-hero";

export default function Example() {
  return (
    <div className="relative h-screen w-full">
      <CurvedCarouselHero
        cards={[
          { video: "/clips/sneaker.mp4", image: "/clips/sneaker.jpg" },
          { image: "/clips/latte.jpg" },
        ]}
      />
    </div>
  );
}
```

## Props

| Prop              | Type                   | Default                                                                                                                           | Description                                                   |
| :---------------- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |
| `badge`           | `string`               | `"New · Curved carousel"`                                                                                                         | Pill above the headline.                                      |
| `title`           | `string`               | `"Every story,\nin motion"`                                                                                                       | Headline; a newline starts the second line.                   |
| `description`     | `string`               | `"Line your work up on a curved row that drifts on its own and answers to a drag. Drop in clips or images and it does the rest."` | Lede under the headline.                                      |
| `ctaLabel`        | `string`               | `"Get started"`                                                                                                                   | Button label.                                                 |
| `ctaHref`         | `string`               | `"#"`                                                                                                                             | Button link.                                                  |
| `note`            | `string`               | `"Drag\nthe row"`                                                                                                                 | Handwritten note by the carousel; a newline breaks it.        |
| `ctaNote`         | `string`               | `"It's free"`                                                                                                                     | Handwritten note by the button.                               |
| `cards`           | `CurvedCarouselCard[]` | `[]`                                                                                                                              | `{ video?, image? }` per card, repeated to fill at least ten. |
| `speed`           | `number`               | `50`                                                                                                                              | Drift speed in frame units (1/1440 of the width) per second.  |
| `backgroundColor` | `string`               | None                                                                                                                              | Section background; defaults to the theme background.         |
| `className`       | `string`               | None                                                                                                                              | Extra classes for the section.                                |
| `style`           | `CSSProperties`        | None                                                                                                                              | Inline styles for the section.                                |

## Source

`components/ui/curved-carousel-hero.tsx`

```tsx
"use client";

import { motion, useAnimationFrame, useReducedMotion } from "framer-motion";
import {
  useEffect,
  useRef,
  useState,
  type CSSProperties,
  type KeyboardEvent,
  type PointerEvent,
} from "react";

import { cn } from "@/lib/utils";

export interface CurvedCarouselCard {
  /** Looping clip, muted and cover-fitted. */
  video?: string;
  /** Still image, also the clip's poster. */
  image?: string;
}

const PITCH = 196;
const STYLES = `
.cch, .cch *, .cch *::before, .cch *::after { box-sizing: border-box; }
.cch { position: relative; width: 100%; height: 100%; min-height: 0; overflow: hidden; container-type: size; color: hsl(var(--foreground)); background: var(--cch-bg, hsl(var(--background))); font-family: var(--font-body), ui-sans-serif, system-ui, sans-serif; }
.cch-frame { --u: min(calc(100cqw / 1440), calc(100cqh / 1080)); --cch-units: 1440; position: absolute; top: 50%; left: 50%; width: calc(1440 * var(--u)); height: calc(1080 * var(--u)); transform: translate(-50%, -50%); }
.cch-badge { position: absolute; top: calc(115 * var(--u)); left: 50%; translate: -50% 0; display: inline-flex; align-items: center; height: calc(37 * var(--u)); padding: 0 calc(18 * var(--u)); border-radius: 999px; background: hsl(var(--primary) / 0.14); color: hsl(var(--primary)); font-size: calc(16.6 * var(--u)); font-weight: 500; white-space: nowrap; }
.cch-title { position: absolute; top: calc(176 * var(--u)); left: 0; right: 0; margin: 0; padding: 0; border: 0; color: inherit; text-align: center; font-family: var(--font-heading), ui-sans-serif, system-ui, sans-serif; font-size: calc(88 * var(--u)); font-weight: 700; line-height: calc(92 * var(--u)); letter-spacing: -0.035em; }
.cch-title > span { display: block; }
.cch-title > span + span { letter-spacing: -0.022em; }
.cch-lede { position: absolute; top: calc(394 * var(--u)); left: 50%; width: calc(560 * var(--u)); translate: -50% 0; margin: 0; text-align: center; color: hsl(var(--muted-foreground)); font-size: calc(20.8 * var(--u)); line-height: calc(32 * var(--u)); }
.cch-track-band { position: absolute; top: calc(495 * var(--u)); left: 50%; width: 100cqw; height: calc(390 * var(--u)); translate: -50% 0; overflow: hidden; --cch-cy: 192; }
.cch-cta { position: absolute; top: calc(901 * var(--u)); left: calc(626 * var(--u)); width: calc(190 * var(--u)); height: calc(74 * var(--u)); display: grid; place-items: center; border: 1.5px dashed hsl(var(--primary) / 0.6); border-radius: 999px; }
.cch-cta a { display: grid; place-items: center; width: calc(172 * var(--u)); height: calc(58 * var(--u)); border-radius: 999px; background: hsl(var(--primary)); color: hsl(var(--primary-foreground)); font-size: calc(17 * var(--u)); font-weight: 500; text-decoration: none; }
.cch-ink { position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none; color: hsl(var(--primary)); }
.cch-note { position: absolute; margin: 0; color: hsl(var(--primary)); font-family: Caveat, "Bradley Hand", "Segoe Print", cursive; font-size: calc(30 * var(--u)); font-weight: 600; line-height: 1; white-space: pre; transform-origin: left top; pointer-events: none; }
.cch-track { position: relative; width: 100%; height: 100%; cursor: grab; touch-action: pan-y; user-select: none; }
.cch-track[data-dragging] { cursor: grabbing; }
.cch-card { position: absolute; top: 0; left: 0; overflow: hidden; will-change: transform, clip-path; }
.cch-card > img, .cch-card > video, .cch-card > i { position: absolute; inset: 0; display: block; width: 100%; max-width: none; height: 100%; margin: 0; object-fit: cover; pointer-events: none; }
.cch-card > video { opacity: 0; transition: opacity 0.4s; }
.cch-card > video[data-ready] { opacity: 1; }
@container (max-width: 820px) {
  .cch-frame { position: static; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 12px; width: 100%; height: 100%; padding: 20px 0; transform: none; --cch-units: 640; }
  .cch-badge, .cch-title, .cch-lede, .cch-track-band, .cch-cta { position: static; translate: none; }
  .cch-badge { height: 30px; padding: 0 14px; font-size: 13px; }
  .cch-title { padding: 0 16px; font-size: clamp(24px, 8cqw, 56px); line-height: 1.04; }
  .cch-lede { width: auto; max-width: 40ch; padding: 0 16px; font-size: 13px; line-height: 1.5; }
  .cch-track-band { flex: 1 1 0; width: 100%; height: auto; min-height: 110px; max-height: 250px; }
  .cch-cta { width: 168px; height: 62px; }
  .cch-cta a { width: 152px; height: 48px; font-size: 15px; }
  .cch-ink, .cch-note { display: none; }
}
@container (max-width: 820px) and (max-height: 600px) { .cch-lede { display: none; } }
`;

type Pt = [number, number];

/** A closed path through four corners, each rounded with a quadratic curve of radius r. */
function roundedQuad(points: Pt[], r: number) {
  const toward = (from: Pt, to: Pt): Pt => {
    const dx = to[0] - from[0];
    const dy = to[1] - from[1];
    const k = r / Math.hypot(dx, dy);
    return [from[0] + dx * k, from[1] + dy * k];
  };
  const f = (p: Pt) => `${p[0].toFixed(2)} ${p[1].toFixed(2)}`;
  return (
    points
      .map((p, i) => {
        const a = toward(p, points[(i + 3) % 4]);
        const b = toward(p, points[(i + 1) % 4]);
        return `${i ? "L" : "M"} ${f(a)} Q ${f(p)} ${f(b)}`;
      })
      .join(" ") + " Z"
  );
}

function CarouselTrack({
  cards,
  speed,
  still,
}: {
  cards: CurvedCarouselCard[];
  speed: number;
  still: boolean;
}) {
  const trackRef = useRef<HTMLDivElement>(null);
  const cardRefs = useRef<(HTMLDivElement | null)[]>([]);
  const state = useRef({
    offset: 0,
    velocity: 0,
    dragging: false,
    lastX: 0,
    lastT: 0,
    units: 1440,
    cy: 192,
    scale: 1,
  });

  // At least enough cards to cover the row plus one off each edge.
  const [minCount, setMinCount] = useState(10);

  // Wide: the row spans the whole section at the frame's scale. Compact: a 640-unit row fitted to
  // the band. The stylesheet says which through --cch-units.
  useEffect(() => {
    const track = trackRef.current;
    if (!track) return;
    const measure = () => {
      const css = getComputedStyle(track);
      const s = state.current;
      if (Number(css.getPropertyValue("--cch-units")) === 640) {
        // Compact: fit a 640-unit row into whatever height the band has left.
        s.scale = Math.min(track.clientWidth / 640, track.clientHeight / 380);
        s.units = track.clientWidth / s.scale;
        s.cy = track.clientHeight / 2 / s.scale;
      } else {
        const frame = track.closest(".cch-frame") as HTMLElement;
        s.scale = frame.clientWidth / 1440;
        s.units = track.clientWidth / s.scale;
        s.cy = Number(css.getPropertyValue("--cch-cy")) || 192;
      }
      setMinCount(Math.ceil((s.units + 600) / PITCH));
    };
    measure();
    const observer = new ResizeObserver(measure);
    observer.observe(track);
    return () => observer.disconnect();
  }, []);

  // Repeating the whole set keeps a card's copies a full cycle apart instead of side by side.
  const filled = Array.from(
    { length: cards.length ? cards.length * Math.ceil(minCount / cards.length) : minCount },
    (_, i): CurvedCarouselCard => cards[i % cards.length] ?? {},
  );
  const loop = filled.length * PITCH;

  useAnimationFrame((_, delta) => {
    const s = state.current;
    const dt = Math.min(delta, 64) / 1000;
    if (!s.dragging) {
      s.offset += s.velocity * dt;
      s.velocity *= Math.pow(0.05, dt);
      if (!still) s.offset -= speed * dt;
    }

    const centre = s.units / 2;
    const radius = Math.max(706, centre - 14);
    cardRefs.current.forEach((el, i) => {
      if (!el) return;
      const t = ((((i * PITCH + s.offset) % loop) + loop * 1.5) % loop) - loop / 2;
      const x = centre + t * (1 + 0.083 * (t / radius) ** 2);
      const d = Math.abs(x - centre) / radius;
      el.style.visibility = d > 1.25 ? "hidden" : "";
      if (d > 1.25) return;
      const w = 170 + 48 * d * d;
      const edge = (ex: number) => 280 + 92 * (Math.abs(ex - centre) / radius) ** 2.6;
      const hl = edge(x - w / 2);
      const hr = edge(x + w / 2);
      const h = Math.max(hl, hr);
      const cy = s.cy - 12 * d * d;
      const k = s.scale;

      el.style.width = `${w * k}px`;
      el.style.height = `${h * k}px`;
      el.style.transform = `translate(${(x - w / 2) * k}px, ${(cy - h / 2) * k}px)`;
      el.style.clipPath = `path("${roundedQuad(
        [
          [0, ((h - hl) / 2) * k],
          [w * k, ((h - hr) / 2) * k],
          [w * k, ((h + hr) / 2) * k],
          [0, ((h + hl) / 2) * k],
        ],
        15 * k,
      )}")`;
    });
  });

  const onPointerDown = (event: PointerEvent<HTMLDivElement>) => {
    const s = state.current;
    s.dragging = true;
    s.velocity = 0;
    s.lastX = event.clientX;
    s.lastT = event.timeStamp;
    event.currentTarget.setPointerCapture(event.pointerId);
    event.currentTarget.dataset.dragging = "";
  };
  const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
    const s = state.current;
    if (!s.dragging) return;
    const dx = (event.clientX - s.lastX) / s.scale;
    const dt = Math.max(event.timeStamp - s.lastT, 1) / 1000;
    s.offset += dx;
    s.velocity = dx / dt;
    s.lastX = event.clientX;
    s.lastT = event.timeStamp;
  };
  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
    const push = { ArrowLeft: 600, ArrowRight: -600 }[event.key];
    if (push === undefined) return;
    event.preventDefault();
    state.current.velocity += push;
  };
  const onPointerUp = (event: PointerEvent<HTMLDivElement>) => {
    state.current.dragging = false;
    delete event.currentTarget.dataset.dragging;
  };

  return (
    <div
      ref={trackRef}
      className="cch-track"
      tabIndex={0}
      role="region"
      aria-roledescription="carousel"
      aria-label="Card carousel; use the arrow keys to move it"
      onKeyDown={onKeyDown}
      onPointerDown={onPointerDown}
      onPointerMove={onPointerMove}
      onPointerUp={onPointerUp}
      onPointerCancel={onPointerUp}
    >
      {filled.map((card, i) => (
        <div
          key={i}
          ref={(el) => {
            cardRefs.current[i] = el;
          }}
          className="cch-card"
        >
          <i
            style={{
              background: `linear-gradient(${150 + i * 37}deg, hsl(var(--primary) / ${0.35 + (i % 3) * 0.2}), hsl(var(--accent)) 70%, hsl(var(--muted)))`,
            }}
          />
          {card.image && <img src={card.image} alt="" draggable={false} />}
          {/* Rendered either way so the server HTML matches the client; reduced motion just never plays it. */}
          {card.video && (
            <video
              // React leaves `muted` out of the server HTML, so Chrome blocks autoplay until it is set here.
              ref={(video) => {
                if (!video || still) return;
                video.muted = true;
                video.play().catch(() => {});
              }}
              src={card.video}
              poster={card.image}
              autoPlay={!still}
              preload={still ? "none" : "auto"}
              muted
              loop
              playsInline
              onLoadedData={(event) => {
                event.currentTarget.dataset.ready = "";
              }}
            />
          )}
        </div>
      ))}
    </div>
  );
}

export interface CurvedCarouselHeroProps {
  badge?: string;
  /** Headline; a newline starts the second line. */
  title?: string;
  description?: string;
  ctaLabel?: string;
  ctaHref?: string;
  /** Handwritten note by the carousel; a newline breaks it. */
  note?: string;
  /** Handwritten note by the button. */
  ctaNote?: string;
  /** Card media, repeated to fill the arch. Cards without media show a theme-tinted tile. */
  cards?: CurvedCarouselCard[];
  /** Auto-scroll speed in frame units per second. */
  speed?: number;
  backgroundColor?: string;
  className?: string;
  style?: CSSProperties;
}

export function CurvedCarouselHero({
  badge = "New · Curved carousel",
  title = "Every story,\nin motion",
  description = "Line your work up on a curved row that drifts on its own and answers to a drag. Drop in clips or images and it does the rest.",
  ctaLabel = "Get started",
  ctaHref = "#",
  note = "Drag\nthe row",
  ctaNote = "It's free",
  cards = [],
  speed = 50,
  backgroundColor,
  className,
  style,
}: CurvedCarouselHeroProps) {
  const prefersReducedMotion = useReducedMotion();
  const still = !!prefersReducedMotion;

  // The server cannot know about reduced motion, so it always renders the hidden starting state. Keep
  // that state on the client too (so the markup matches) and, when motion is reduced, reach the end
  // state at once instead of omitting the animation, which would leave the content hidden.
  const instant = { duration: 0 };
  const enter = (delay: number, from: Record<string, number | string> = { opacity: 0, y: 16 }) => ({
    initial: from,
    animate: { opacity: 1, y: 0, scale: 1, filter: "blur(0px)" },
    transition: still ? instant : { delay, duration: 0.7, ease: [0.22, 1, 0.36, 1] as const },
  });
  const draw = (delay: number) => ({
    initial: { pathLength: 0 },
    animate: { pathLength: 1 },
    transition: still ? instant : { delay, duration: 0.9, ease: "easeInOut" as const },
  });

  return (
    <section
      className={cn("cch", className)}
      style={backgroundColor ? { ...style, ["--cch-bg" as string]: backgroundColor } : style}
    >
      <style dangerouslySetInnerHTML={{ __html: STYLES }} />
      <div className="cch-frame">
        <motion.span className="cch-badge" {...enter(0.1, { opacity: 0, scale: 0.85 })}>
          {badge}
        </motion.span>
        <h2 className="cch-title">
          {title.split("\n").map((line, i) => (
            <motion.span
              key={i}
              {...enter(0.2 + i * 0.12, { opacity: 0, y: 24, filter: "blur(10px)" })}
            >
              {line}
            </motion.span>
          ))}
        </h2>
        <motion.p className="cch-lede" {...enter(0.45)}>
          {description}
        </motion.p>
        <motion.div className="cch-track-band" {...enter(0.55, { opacity: 0, y: 60 })}>
          <CarouselTrack cards={cards} speed={speed} still={still} />
        </motion.div>
        <motion.div className="cch-cta" {...enter(0.8, { opacity: 0, scale: 0.8 })}>
          <a href={ctaHref}>{ctaLabel}</a>
        </motion.div>

        <svg className="cch-ink" viewBox="0 0 1440 1080" fill="none" aria-hidden="true">
          <g stroke="currentColor" strokeWidth="3" strokeLinecap="round" strokeLinejoin="round">
            <motion.path d="M268 410 L282 380 M284 414 L298 384" {...draw(0.9)} />
            <motion.path
              d="M1262 392 C1290 440 1282 500 1222 528 C1200 538 1186 536 1172 530"
              {...draw(1)}
            />
            <motion.path d="M1186 518 L1170 530 L1188 542" {...draw(1.6)} />
            <motion.path d="M584 1000 C604 996 616 978 620 952" {...draw(1.1)} />
            <motion.path d="M609 961 L620 950 L627 964" {...draw(1.6)} />
          </g>
        </svg>
        <motion.p
          className="cch-note"
          style={{ left: "calc(1212 * var(--u))", top: "calc(310 * var(--u))", rotate: 16 }}
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          transition={still ? instant : { delay: 1.1, duration: 0.6 }}
        >
          {note}
        </motion.p>
        <motion.p
          className="cch-note"
          style={{ left: "calc(486 * var(--u))", top: "calc(944 * var(--u))", rotate: 24 }}
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          transition={still ? instant : { delay: 1.2, duration: 0.6 }}
        >
          {ctaNote}
        </motion.p>
      </div>
    </section>
  );
}
```

---

# Aurora Veil

> Layered aurora curtains drifting over a night sky with soft noise, film grain and a vignette.

Install: `npx @modus-ui/cli add aurora-veil`

Aurora curtains screened over a deep night background, textured with soft-light simplex noise and film grain and framed by a vignette. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add aurora-veil
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/aurora-veil.tsx`.
4. Paste the code.

## Usage

```tsx
import { AuroraVeil } from "@/components/ui/aurora-veil";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <AuroraVeil />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default     | Description                                       |
| :---------------- | :------- | :---------- | :------------------------------------------------ |
| `colorA`          | `string` | `"#22d3ee"` | First curtain colour.                             |
| `colorB`          | `string` | `"#a855f7"` | Second curtain colour.                            |
| `colorC`          | `string` | `"#34d399"` | Third curtain colour.                             |
| `backgroundColor` | `string` | `"#030712"` | Sky colour behind the curtains and vignette tint. |
| `speed`           | `number` | `5`         | Animation speed (0 to 100 scale).                 |
| `intensity`       | `number` | `80`        | Brightness of the curtains (0 to 100).            |
| `curtainCount`    | `number` | `4`         | Number of aurora curtains.                        |
| `waviness`        | `number` | `50`        | How much the curtains undulate (0 to 100).        |
| `grain`           | `number` | `0.08`      | Film grain strength.                              |

## Source

`components/ui/aurora-veil.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { Aurora, FilmGrain, Shader, SimplexNoise, SolidColor, Vignette } from "shaders/react";
import { cn } from "@/lib/utils";

export interface AuroraVeilProps {
  colorA?: string;
  colorB?: string;
  colorC?: string;
  backgroundColor?: string;
  speed?: number;
  intensity?: number;
  curtainCount?: number;
  waviness?: number;
  grain?: number;
  className?: string;
}

export function AuroraVeil({
  colorA = "#22d3ee",
  colorB = "#a855f7",
  colorC = "#34d399",
  backgroundColor = "#030712",
  speed = 5,
  intensity = 80,
  curtainCount = 4,
  waviness = 50,
  grain = 0.08,
  className,
}: AuroraVeilProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <SolidColor color={backgroundColor} />
      <Aurora
        colorA={colorA}
        colorB={colorB}
        colorC={colorC}
        colorSpace="oklab"
        speed={reduce ? 0 : speed}
        intensity={intensity}
        curtainCount={curtainCount}
        waviness={waviness}
      />
      <SimplexNoise
        colorA="#000000"
        colorB="#ffffff"
        scale={3}
        speed={reduce ? 0 : 0.3}
        opacity={0.12}
        blendMode="softLight"
      />
      <FilmGrain strength={grain} animated={!reduce} />
      <Vignette color={backgroundColor} intensity={0.6} radius={0.7} />
    </Shader>
  );
}
```

---

# Silk Mesh

> A soft flowing mesh gradient in your theme colours with grain and noise texture.

Install: `npx @modus-ui/cli add silk-mesh`

A drifting mesh gradient whose colours default to your theme's background and primary tokens, textured with soft-light noise and film grain. Colours update when the theme changes. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add silk-mesh
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/silk-mesh.tsx`.
4. Paste the code.

## Usage

```tsx
import { SilkMesh } from "@/components/ui/silk-mesh";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <SilkMesh />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop         | Type     | Default     | Description                                         |
| :----------- | :------- | :---------- | :-------------------------------------------------- |
| `colorA`     | `string` | theme token | First colour. Defaults to the `--background` token. |
| `colorB`     | `string` | theme token | Second colour. Defaults to the `--primary` token.   |
| `speed`      | `number` | `0.6`       | Drift speed.                                        |
| `count`      | `number` | `4`         | Number of colour swaths.                            |
| `swirl`      | `number` | `0.5`       | Amount of swirl in the swaths.                      |
| `smoothness` | `number` | `0.6`       | Softness of the seams between swaths.               |
| `grain`      | `number` | `0.06`      | Film grain strength.                                |

## Source

`components/ui/silk-mesh.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useEffect, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { FilmGrain, MeshGradient, Shader, SimplexNoise } from "shaders/react";
import { cn } from "@/lib/utils";

type Theme = { primary: string; accent: string; background: string; foreground: string };

function readTheme(): Theme {
  const style = getComputedStyle(document.documentElement);
  const token = (name: string) => `hsl(${style.getPropertyValue(name).trim()})`;
  return {
    primary: token("--primary"),
    accent: token("--accent"),
    background: token("--background"),
    foreground: token("--foreground"),
  };
}

function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const update = () => setTheme(readTheme());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

export interface SilkMeshProps {
  colorA?: string;
  colorB?: string;
  speed?: number;
  count?: number;
  swirl?: number;
  smoothness?: number;
  grain?: number;
  className?: string;
}

export function SilkMesh({
  colorA,
  colorB,
  speed = 0.6,
  count = 4,
  swirl = 0.5,
  smoothness = 0.6,
  grain = 0.06,
  className,
}: SilkMeshProps) {
  const reduce = useReducedMotion();
  const theme = useTheme();
  const classes = cn("absolute inset-0 h-full w-full", className);
  if (!theme) return <div className={classes} />;
  return (
    <Shader className={classes}>
      <MeshGradient
        colorA={colorA ?? theme.background}
        colorB={colorB ?? theme.primary}
        colorSpace="oklab"
        speed={reduce ? 0 : speed}
        count={count}
        swirl={swirl}
        smoothness={smoothness}
      />
      <SimplexNoise
        colorA="hsl(0 0% 0%)"
        colorB="hsl(0 0% 100%)"
        scale={3}
        speed={reduce ? 0 : 0.5}
        opacity={0.12}
        blendMode="softLight"
      />
      <FilmGrain strength={grain} animated={!reduce} />
    </Shader>
  );
}
```

---

# Liquid Chrome Orb

> A molten liquid-metal torus, sphere or blob floating in a lit studio.

Install: `npx @modus-ui/cli add liquid-chrome-orb`

A 3D liquid-metal shape with flowing folds and prismatic edges, set against a studio backdrop. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add liquid-chrome-orb
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/liquid-chrome-orb.tsx`.
4. Paste the code.

## Usage

```tsx
import { LiquidChromeOrb } from "@/components/ui/liquid-chrome-orb";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <LiquidChromeOrb />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type                            | Default     | Description                    |
| :---------------- | :------------------------------ | :---------- | :----------------------------- |
| `shape`           | `"torus" \| "sphere" \| "blob"` | `"torus"`   | 3D shape to render.            |
| `lightColor`      | `string`                        | `"#eef0f6"` | Highlight colour of the metal. |
| `darkColor`       | `string`                        | `"#141414"` | Shadow colour of the metal.    |
| `backgroundColor` | `string`                        | `"#0b0b0f"` | Studio backdrop colour.        |
| `speed`           | `number`                        | `1`         | Flow speed of the metal.       |
| `turbulence`      | `number`                        | `1`         | Strength of the surface folds. |
| `dispersion`      | `number`                        | `0.6`       | Prismatic fringe on the edges. |
| `scale`           | `number`                        | `1`         | Size of the shape.             |

## Source

`components/ui/liquid-chrome-orb.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { LiquidMetal, Shader, StudioBackground } from "shaders/react";
import { cn } from "@/lib/utils";

export interface LiquidChromeOrbProps {
  shape?: "torus" | "sphere" | "blob";
  lightColor?: string;
  darkColor?: string;
  backgroundColor?: string;
  speed?: number;
  turbulence?: number;
  dispersion?: number;
  scale?: number;
  className?: string;
}

const SHAPES = {
  torus: { type: "torus3D", radius: 0.3, tube: 0.12, rotX: 55, rotY: 0, rotZ: 0 },
  sphere: { type: "sphere3D", radius: 0.35 },
  blob: { type: "blob3D", radius: 0.35 },
} as const;

export function LiquidChromeOrb({
  shape = "torus",
  lightColor = "#eef0f6",
  darkColor = "#141414",
  backgroundColor = "#0b0b0f",
  speed = 1,
  turbulence = 1,
  dispersion = 0.6,
  scale = 1,
  className,
}: LiquidChromeOrbProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <StudioBackground color={backgroundColor} brightness={15} ambientSpeed={reduce ? 0 : 0.5} />
      <LiquidMetal
        shape={SHAPES[shape]}
        lightColor={lightColor}
        darkColor={darkColor}
        speed={reduce ? 0 : speed}
        turbulence={turbulence}
        dispersion={dispersion}
        scale={scale}
      />
    </Shader>
  );
}
```

---

# Plasma Glow

> Glowing plasma with bloom, chromatic aberration and a vignette.

Install: `npx @modus-ui/cli add plasma-glow`

An animated plasma field with a bloom pass, a touch of chromatic aberration and a dark vignette. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add plasma-glow
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/plasma-glow.tsx`.
4. Paste the code.

## Usage

```tsx
import { PlasmaGlow } from "@/components/ui/plasma-glow";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <PlasmaGlow />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop         | Type     | Default     | Description                    |
| :----------- | :------- | :---------- | :----------------------------- |
| `colorA`     | `string` | `"#0b0221"` | Dark plasma colour.            |
| `colorB`     | `string` | `"#ff3fa4"` | Bright plasma colour.          |
| `speed`      | `number` | `1`         | Animation speed.               |
| `density`    | `number` | `1`         | Density of the plasma bands.   |
| `warp`       | `number` | `1`         | Amount of domain warping.      |
| `glow`       | `number` | `0.6`       | Bloom intensity.               |
| `aberration` | `number` | `0.3`       | Chromatic aberration strength. |

## Source

`components/ui/plasma-glow.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { ChromaticAberration, Glow, Plasma, Shader, Vignette } from "shaders/react";
import { cn } from "@/lib/utils";

export interface PlasmaGlowProps {
  colorA?: string;
  colorB?: string;
  speed?: number;
  density?: number;
  warp?: number;
  glow?: number;
  aberration?: number;
  className?: string;
}

export function PlasmaGlow({
  colorA = "#0b0221",
  colorB = "#ff3fa4",
  speed = 1,
  density = 1,
  warp = 1,
  glow = 0.6,
  aberration = 0.3,
  className,
}: PlasmaGlowProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <Plasma
        colorA={colorA}
        colorB={colorB}
        colorSpace="oklch"
        speed={reduce ? 0 : speed}
        density={density}
        warp={warp}
      />
      <Glow intensity={glow} threshold={0.4} size={20} />
      <ChromaticAberration strength={aberration} />
      <Vignette color="#000000" intensity={0.5} radius={0.75} />
    </Shader>
  );
}
```

---

# Nebula Orb

> A volumetric gas nebula sealed in a glass sphere over a twinkling star field.

Install: `npx @modus-ui/cli add nebula-orb`

Billowing emission clouds inside a glass sphere, floating over a radial gradient and a twinkling dot-grid star field. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add nebula-orb
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/nebula-orb.tsx`.
4. Paste the code.

## Usage

```tsx
import { NebulaOrb } from "@/components/ui/nebula-orb";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <NebulaOrb />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type     | Default     | Description                            |
| :---------------- | :------- | :---------- | :------------------------------------- |
| `coreColor`       | `string` | `"#ffd9b0"` | Colour of the hot cores.               |
| `gasColor`        | `string` | `"#ff5e7a"` | Main gas colour.                       |
| `veilColor`       | `string` | `"#3a5bdb"` | Colour of the outer veil.              |
| `backgroundColor` | `string` | `"#05030f"` | Outer colour of the backdrop gradient. |
| `speed`           | `number` | `1`         | Gas animation speed.                   |
| `density`         | `number` | `1`         | Density of the gas.                    |
| `glow`            | `number` | `1`         | Glow of the cores.                     |
| `radius`          | `number` | `0.38`      | Radius of the sphere.                  |

## Source

`components/ui/nebula-orb.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { DotGrid, Nebula, RadialGradient, Shader } from "shaders/react";
import { cn } from "@/lib/utils";

export interface NebulaOrbProps {
  coreColor?: string;
  gasColor?: string;
  veilColor?: string;
  backgroundColor?: string;
  speed?: number;
  density?: number;
  glow?: number;
  radius?: number;
  className?: string;
}

export function NebulaOrb({
  coreColor = "#ffd9b0",
  gasColor = "#ff5e7a",
  veilColor = "#3a5bdb",
  backgroundColor = "#05030f",
  speed = 1,
  density = 1,
  glow = 1,
  radius = 0.38,
  className,
}: NebulaOrbProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <RadialGradient colorA="#1b1145" colorB={backgroundColor} radius={0.9} colorSpace="oklab" />
      <DotGrid
        color="#ffffff"
        density={60}
        dotSize={0.08}
        twinkle={1}
        speed={reduce ? 0 : 1}
        opacity={0.35}
      />
      <Nebula
        shape={{ type: "sphere3D", radius }}
        coreColor={coreColor}
        gasColor={gasColor}
        veilColor={veilColor}
        speed={reduce ? 0 : speed}
        density={density}
        glow={glow}
      />
    </Shader>
  );
}
```

---

# Godray Haze

> Volumetric light rays through a hazy gradient sky.

Install: `npx @modus-ui/cli add godray-haze`

Volumetric god rays streaming from the top corner over a sky gradient, with soft fractal haze and a vignette. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add godray-haze
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/godray-haze.tsx`.
4. Paste the code.

## Usage

```tsx
import { GodrayHaze } from "@/components/ui/godray-haze";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <GodrayHaze />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop          | Type     | Default     | Description                      |
| :------------ | :------- | :---------- | :------------------------------- |
| `rayColor`    | `string` | `"#fde68a"` | Colour of the light rays.        |
| `skyColor`    | `string` | `"#1e293b"` | Top colour of the sky gradient.  |
| `groundColor` | `string` | `"#020617"` | Bottom colour and vignette tint. |
| `speed`       | `number` | `0.5`       | Ray animation speed.             |
| `intensity`   | `number` | `0.6`       | Brightness of the rays.          |
| `density`     | `number` | `0.3`       | Density of the rays.             |
| `spotty`      | `number` | `1`         | How broken up the rays are.      |

## Source

`components/ui/godray-haze.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { FractalNoise, Godrays, LinearGradient, Shader, Vignette } from "shaders/react";
import { cn } from "@/lib/utils";

export interface GodrayHazeProps {
  rayColor?: string;
  skyColor?: string;
  groundColor?: string;
  speed?: number;
  intensity?: number;
  density?: number;
  spotty?: number;
  className?: string;
}

export function GodrayHaze({
  rayColor = "#fde68a",
  skyColor = "#1e293b",
  groundColor = "#020617",
  speed = 0.5,
  intensity = 0.6,
  density = 0.3,
  spotty = 1,
  className,
}: GodrayHazeProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <LinearGradient colorA={skyColor} colorB={groundColor} angle={180} colorSpace="oklab" />
      <Godrays
        center={{ x: 0.2, y: 0 }}
        rayColor={rayColor}
        backgroundColor="transparent"
        speed={reduce ? 0 : speed}
        intensity={intensity}
        density={density}
        spotty={spotty}
        blendMode="screen"
      />
      <FractalNoise
        colorA="#000000"
        colorB="#ffffff"
        speed={reduce ? 0 : 0.2}
        opacity={0.15}
        blendMode="softLight"
      />
      <Vignette color={groundColor} intensity={0.5} radius={0.8} />
    </Shader>
  );
}
```

---

# Ink Canvas

> Drag to paint swirling ribbons of ink through a live fluid simulation.

Install: `npx @modus-ui/cli add ink-canvas`

An interactive fluid canvas: drag the cursor to paint ribbons of ink that keep swirling after you let go, with a soft glow. It fills its positioned parent. It only moves in response to the cursor, so it has no autoplaying motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add ink-canvas
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ink-canvas.tsx`.
4. Paste the code.

## Usage

```tsx
import { InkCanvas } from "@/components/ui/ink-canvas";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <InkCanvas />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop              | Type                    | Default     | Description                                   |
| :---------------- | :---------------------- | :---------- | :-------------------------------------------- |
| `backgroundColor` | `string`                | `"#07070b"` | Canvas colour.                                |
| `colorMode`       | `"rainbow" \| "single"` | `"rainbow"` | `rainbow` cycles hues; `single` uses `color`. |
| `color`           | `string`                | `"#ff2d7e"` | Ink colour when `colorMode` is `single`.      |
| `radius`          | `number`                | `1`         | Brush radius.                                 |
| `curl`            | `number`                | `0.5`       | Amount of curl in the flow.                   |
| `decay`           | `number`                | `0.6`       | How quickly the ink fades.                    |
| `glow`            | `number`                | `0.4`       | Glow intensity.                               |

## Source

`components/ui/ink-canvas.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { InkFlow, Glow, Shader, SolidColor } from "shaders/react";
import { useReducedMotion } from "framer-motion";
import { cn } from "@/lib/utils";

export interface InkCanvasProps {
  backgroundColor?: string;
  colorMode?: "rainbow" | "single";
  color?: string;
  radius?: number;
  curl?: number;
  decay?: number;
  glow?: number;
  className?: string;
}

export function InkCanvas({
  backgroundColor = "#07070b",
  colorMode = "rainbow",
  color = "#ff2d7e",
  radius = 1,
  curl = 0.5,
  decay = 0.6,
  glow = 0.4,
  className,
}: InkCanvasProps) {
  // Reduced motion keeps the ink where it is drawn instead of swirling it.
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <SolidColor color={backgroundColor} />
      <InkFlow
        colorMode={colorMode}
        color={color}
        radius={radius}
        curl={reduce ? 0 : curl}
        decay={decay}
      />
      <Glow intensity={glow} threshold={0.3} size={16} />
    </Shader>
  );
}
```

---

# Holo Foil

> An iridescent holographic foil card with glitter and rainbow sheen.

Install: `npx @modus-ui/cli add holo-foil`

A rounded holographic foil card with an animated rainbow sheen, crinkles and glitter, on a dark gradient with fine grain. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add holo-foil
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/holo-foil.tsx`.
4. Paste the code.

## Usage

```tsx
import { HoloFoil } from "@/components/ui/holo-foil";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <HoloFoil />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop             | Type     | Default     | Description                                |
| :--------------- | :------- | :---------- | :----------------------------------------- |
| `backgroundFrom` | `string` | `"#18181b"` | Gradient start colour.                     |
| `backgroundTo`   | `string` | `"#09090b"` | Gradient end colour.                       |
| `speed`          | `number` | `1`         | Sheen animation speed.                     |
| `saturation`     | `number` | `0.75`      | Saturation of the foil colours.            |
| `sparkle`        | `number` | `0.4`       | Amount of glitter.                         |
| `crinkle`        | `number` | `0.5`       | Amount of crinkle in the foil.             |
| `width`          | `number` | `0.32`      | Card half-width (fraction of the canvas).  |
| `height`         | `number` | `0.42`      | Card half-height (fraction of the canvas). |
| `rounding`       | `number` | `0.06`      | Corner rounding.                           |

## Source

`components/ui/holo-foil.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { FilmGrain, Holographic, LinearGradient, Shader } from "shaders/react";
import { cn } from "@/lib/utils";

export interface HoloFoilProps {
  backgroundFrom?: string;
  backgroundTo?: string;
  speed?: number;
  saturation?: number;
  sparkle?: number;
  crinkle?: number;
  width?: number;
  height?: number;
  rounding?: number;
  className?: string;
}

export function HoloFoil({
  backgroundFrom = "#18181b",
  backgroundTo = "#09090b",
  speed = 1,
  saturation = 0.75,
  sparkle = 0.4,
  crinkle = 0.5,
  width = 0.32,
  height = 0.42,
  rounding = 0.06,
  className,
}: HoloFoilProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <LinearGradient
        colorA={backgroundFrom}
        colorB={backgroundTo}
        angle={135}
        colorSpace="oklab"
      />
      <Holographic
        shape={{ type: "roundedRectSDF", width, height, rounding }}
        speed={reduce ? 0 : speed}
        saturation={saturation}
        sparkle={sparkle}
        crinkle={crinkle}
      />
      <FilmGrain strength={0.05} animated={!reduce} />
    </Shader>
  );
}
```

---

# Crystal Cells

> A faceted crystal lens refracting a shifting Voronoi cell field.

Install: `npx @modus-ui/cli add crystal-cells`

A moving Voronoi cell pattern seen through a hexagonal faceted crystal with dispersion, framed by a vignette. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add crystal-cells
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/crystal-cells.tsx`.
4. Paste the code.

## Usage

```tsx
import { CrystalCells } from "@/components/ui/crystal-cells";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <CrystalCells />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop          | Type     | Default     | Description                  |
| :------------ | :------- | :---------- | :--------------------------- |
| `colorA`      | `string` | `"#0f172a"` | Cell centre colour.          |
| `colorB`      | `string` | `"#6366f1"` | Cell edge colour.            |
| `borderColor` | `string` | `"#e0e7ff"` | Colour of the cell borders.  |
| `speed`       | `number` | `0.5`       | Cell animation speed.        |
| `scale`       | `number` | `6`         | Number of cells.             |
| `facets`      | `number` | `5`         | Number of crystal facets.    |
| `refraction`  | `number` | `0.5`       | Refraction strength.         |
| `dispersion`  | `number` | `0.5`       | Rainbow dispersion strength. |
| `radius`      | `number` | `0.32`      | Size of the crystal.         |

## Source

`components/ui/crystal-cells.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { Crystal, Shader, Vignette, Voronoi } from "shaders/react";
import { cn } from "@/lib/utils";

export interface CrystalCellsProps {
  colorA?: string;
  colorB?: string;
  borderColor?: string;
  speed?: number;
  scale?: number;
  facets?: number;
  refraction?: number;
  dispersion?: number;
  radius?: number;
  className?: string;
}

export function CrystalCells({
  colorA = "#0f172a",
  colorB = "#6366f1",
  borderColor = "#e0e7ff",
  speed = 0.5,
  scale = 6,
  facets = 5,
  refraction = 0.5,
  dispersion = 0.5,
  radius = 0.32,
  className,
}: CrystalCellsProps) {
  const reduce = useReducedMotion();
  return (
    <Shader className={cn("absolute inset-0 h-full w-full", className)}>
      <Voronoi
        colorA={colorA}
        colorB={colorB}
        colorBorder={borderColor}
        colorSpace="oklch"
        scale={scale}
        speed={reduce ? 0 : speed}
        edgeIntensity={0.6}
      />
      <Crystal
        shape={{ type: "polygonSDF", radius, sides: 6, rounding: 0 }}
        facets={facets}
        refraction={refraction}
        dispersion={dispersion}
      />
      <Vignette color="#000000" intensity={0.5} radius={0.75} />
    </Shader>
  );
}
```

---

# Fluted Gradient

> A flowing silk gradient seen through ribbed fluted glass.

Install: `npx @modus-ui/cli add fluted-gradient`

A four-colour flowing gradient refracted through vertical fluted glass bars, with fine grain. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add fluted-gradient
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/fluted-gradient.tsx`.
4. Paste the code.

## Usage

```tsx
import { FlutedGradient } from "@/components/ui/fluted-gradient";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <FlutedGradient />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop         | Type     | Default     | Description                              |
| :----------- | :------- | :---------- | :--------------------------------------- |
| `colorA`     | `string` | `"#0b1026"` | First gradient colour.                   |
| `colorB`     | `string` | `"#ff6b3d"` | Second gradient colour.                  |
| `colorC`     | `string` | `"#7c3aed"` | Third gradient colour.                   |
| `colorD`     | `string` | `"#22d3ee"` | Fourth gradient colour.                  |
| `speed`      | `number` | `0.6`       | Gradient flow speed.                     |
| `distortion` | `number` | `0.8`       | Gradient band distortion.                |
| `frequency`  | `number` | `10`        | Number of glass flutes.                  |
| `angle`      | `number` | `0`         | Angle of the flutes in degrees.          |
| `refraction` | `number` | `1.5`       | Refraction strength.                     |
| `aberration` | `number` | `0.2`       | Chromatic aberration at the flute edges. |

## Source

`components/ui/fluted-gradient.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { FilmGrain, FlowingGradient, FlutedGlass, Shader } from "shaders/react";
import { cn } from "@/lib/utils";

export interface FlutedGradientProps {
  colorA?: string;
  colorB?: string;
  colorC?: string;
  colorD?: string;
  speed?: number;
  distortion?: number;
  frequency?: number;
  angle?: number;
  refraction?: number;
  aberration?: number;
  className?: string;
}

export function FlutedGradient({
  colorA = "#0b1026",
  colorB = "#ff6b3d",
  colorC = "#7c3aed",
  colorD = "#22d3ee",
  speed = 0.6,
  distortion = 0.8,
  frequency = 10,
  angle = 0,
  refraction = 1.5,
  aberration = 0.2,
  className,
}: FlutedGradientProps) {
  const reduce = useReducedMotion();
  const classes = cn("absolute inset-0 h-full w-full", className);
  return (
    <Shader className={classes}>
      <FlowingGradient
        colorA={colorA}
        colorB={colorB}
        colorC={colorC}
        colorD={colorD}
        colorSpace="oklab"
        speed={reduce ? 0 : speed}
        distortion={distortion}
      />
      <FlutedGlass
        frequency={frequency}
        angle={angle}
        refraction={refraction}
        aberration={aberration}
        speed={reduce ? 0 : 1}
      />
      <FilmGrain strength={0.05} animated={!reduce} />
    </Shader>
  );
}
```

---

# Ripple Pool

> A swirling gradient that ripples like water under the cursor.

Install: `npx @modus-ui/cli add ripple-pool`

A slow swirling gradient with fluid ripples that trail the cursor. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add ripple-pool
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ripple-pool.tsx`.
4. Paste the code.

## Usage

```tsx
import { RipplePool } from "@/components/ui/ripple-pool";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <RipplePool />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop             | Type     | Default     | Description                  |
| :--------------- | :------- | :---------- | :--------------------------- |
| `colorA`         | `string` | `"#04121f"` | First swirl colour.          |
| `colorB`         | `string` | `"#38bdf8"` | Second swirl colour.         |
| `speed`          | `number` | `0.5`       | Swirl speed.                 |
| `detail`         | `number` | `1`         | Swirl detail.                |
| `intensity`      | `number` | `10`        | Ripple strength.             |
| `radius`         | `number` | `0.5`       | Ripple radius.               |
| `decay`          | `number` | `10`        | How quickly ripples settle.  |
| `chromaticSplit` | `number` | `1`         | Colour split in the ripples. |

## Source

`components/ui/ripple-pool.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useReducedMotion } from "framer-motion";
import { CursorRipples, Shader, Swirl } from "shaders/react";
import { cn } from "@/lib/utils";

export interface RipplePoolProps {
  colorA?: string;
  colorB?: string;
  speed?: number;
  detail?: number;
  intensity?: number;
  radius?: number;
  decay?: number;
  chromaticSplit?: number;
  className?: string;
}

export function RipplePool({
  colorA = "#04121f",
  colorB = "#38bdf8",
  speed = 0.5,
  detail = 1,
  intensity = 10,
  radius = 0.5,
  decay = 10,
  chromaticSplit = 1,
  className,
}: RipplePoolProps) {
  const reduce = useReducedMotion();
  const classes = cn("absolute inset-0 h-full w-full", className);
  return (
    <Shader className={classes}>
      <Swirl
        colorA={colorA}
        colorB={colorB}
        colorSpace="oklab"
        speed={reduce ? 0 : speed}
        detail={detail}
      />
      <CursorRipples
        intensity={intensity}
        radius={radius}
        decay={decay}
        chromaticSplit={chromaticSplit}
      />
    </Shader>
  );
}
```

---

# ASCII Flow

> Flowing fractal noise rendered as ASCII characters in your theme colours.

Install: `npx @modus-ui/cli add ascii-flow`

Fractal noise drawn in your theme's background and primary tokens, converted into ASCII character art. It fills its positioned parent and freezes its animation when the user prefers reduced motion. Built on the [shaders](https://shaders.com) library (MIT) and rendered with WebGPU.

## Installation

### CLI

```bash
npx @modus-ui/cli add ascii-flow
```

### Manual

1. Install `shaders` with `npm install shaders`.
2. Copy the code from the component tab.
3. Create a file at `components/ui/ascii-flow.tsx`.
4. Paste the code.

## Usage

```tsx
import { AsciiFlow } from "@/components/ui/ascii-flow";

export default function Example() {
  return (
    <div className="relative h-[500px] w-full overflow-hidden">
      <AsciiFlow />
      <div className="relative z-10 p-8">
        <h1>Content over the effect</h1>
      </div>
    </div>
  );
}
```

## Props

| Prop         | Type     | Default        | Description                                        |
| :----------- | :------- | :------------- | :------------------------------------------------- |
| `colorA`     | `string` | theme token    | Dark colour. Defaults to the `--background` token. |
| `colorB`     | `string` | theme token    | Light colour. Defaults to the `--primary` token.   |
| `characters` | `string` | `" .:-=+*#%@"` | Characters from darkest to brightest.              |
| `cellSize`   | `number` | `16`           | Character cell size in pixels.                     |
| `speed`      | `number` | `0.4`          | Noise animation speed.                             |
| `contrast`   | `number` | `1.2`          | Noise contrast.                                    |

## Source

`components/ui/ascii-flow.tsx`

```tsx
"use client";
// Built on the shaders library (MIT, © 2026 Shader Effects Inc.).

import { useEffect, useState } from "react";
import { useReducedMotion } from "framer-motion";
import { Ascii, FractalNoise, Shader } from "shaders/react";
import { cn } from "@/lib/utils";

type Theme = { primary: string; accent: string; background: string; foreground: string };

function readTheme(): Theme {
  const style = getComputedStyle(document.documentElement);
  const token = (name: string) => `hsl(${style.getPropertyValue(name).trim()})`;
  return {
    primary: token("--primary"),
    accent: token("--accent"),
    background: token("--background"),
    foreground: token("--foreground"),
  };
}

function useTheme() {
  const [theme, setTheme] = useState<Theme | null>(null);
  useEffect(() => {
    const update = () => setTheme(readTheme());
    update();
    const observer = new MutationObserver(update);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class", "style"],
    });
    return () => observer.disconnect();
  }, []);
  return theme;
}

export interface AsciiFlowProps {
  colorA?: string;
  colorB?: string;
  characters?: string;
  cellSize?: number;
  speed?: number;
  contrast?: number;
  className?: string;
}

export function AsciiFlow({
  colorA,
  colorB,
  characters = " .:-=+*#%@",
  cellSize = 16,
  speed = 0.4,
  contrast = 1.2,
  className,
}: AsciiFlowProps) {
  const reduce = useReducedMotion();
  const theme = useTheme();
  const classes = cn("absolute inset-0 h-full w-full", className);
  if (!theme) return <div className={classes} />;
  return (
    <Shader className={classes}>
      <FractalNoise
        colorA={colorA ?? theme.background}
        colorB={colorB ?? theme.primary}
        colorSpace="oklab"
        speed={reduce ? 0 : speed}
        contrast={contrast}
      />
      <Ascii characters={characters} cellSize={cellSize} />
    </Shader>
  );
}
```

---

# Swipe Actions

> A React Native list row that slides left to reveal action buttons, with rubber-banding, flick detection and screen reader actions.

Install: `npx @modus-ui/cli add swipe-actions`

A list row that slides left to reveal action buttons. It follows your finger, resists past either end, springs open or shut on release (a quick flick is enough), and every action is also exposed to screen readers as a custom action, so nothing depends on the gesture. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add swipe-actions
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/swipe-actions.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text } from "react-native";
import { SwipeActions } from "@/components/ui/swipe-actions";

export default function Example() {
  return (
    <SwipeActions
      actions={[
        { label: "Archive", onPress: () => console.log("archive") },
        { label: "Delete", color: "#dc2626", onPress: () => console.log("delete") },
      ]}
    >
      <Text style={{ padding: 16 }}>Swipe me left</Text>
    </SwipeActions>
  );
}
```

## Props

| Prop            | Type                          | Default | Description                                                                                        |
| :-------------- | :---------------------------- | :------ | :------------------------------------------------------------------------------------------------- |
| `actions`       | `SwipeActionItem[]`           | -       | Buttons revealed by the swipe. Each has a `label`, an `onPress` and an optional `color`.           |
| `actionWidth`   | `number`                      | `76`    | Width of each revealed action.                                                                     |
| `openThreshold` | `number`                      | `0.4`   | Fraction of the revealed width that commits the swipe when released. A fast flick also commits it. |
| `onOpenChange`  | `(open: boolean) => void`     | -       | Called when the row settles open or closed.                                                        |
| `colors`        | `Partial<SwipeActionsColors>` | -       | Overrides `surface`, `action` and `actionText`.                                                    |
| `style`         | `StyleProp<ViewStyle>`        | -       | Style for the outer container.                                                                     |

## Source

`components/ui/swipe-actions.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface SwipeActionItem {
  label: string;
  onPress: () => void;
  /** Background of this action. Defaults to `colors.action`. */
  color?: string;
}

export interface SwipeActionsColors {
  surface: string;
  action: string;
  actionText: string;
}

const DEFAULT_COLORS: SwipeActionsColors = {
  surface: "#ffffff",
  action: "#4f46e5",
  actionText: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SwipeActionsProps {
  children: ReactNode;
  /** Buttons revealed by swiping the row to the left. */
  actions: SwipeActionItem[];
  /** Width of each revealed action. */
  actionWidth?: number;
  /** Fraction of the revealed width, or a flick this fast, that commits the swipe. */
  openThreshold?: number;
  onOpenChange?: (open: boolean) => void;
  colors?: Partial<SwipeActionsColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A list row that slides left to reveal action buttons. Follows the finger with rubber-banding at
 * both ends, springs to open or closed on release (a quick flick is enough), and exposes each action
 * to screen readers as a custom action so nothing depends on the gesture.
 */
export function SwipeActions({
  children,
  actions,
  actionWidth = 76,
  openThreshold = 0.4,
  onOpenChange,
  colors,
  style,
}: SwipeActionsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const x = useRef(new Animated.Value(0)).current;
  const base = useRef(0);
  // True during a drag and for a moment after it: the click a mouse sends on release is not a tap.
  const dragging = useRef(false);
  const [open, setOpen] = useState(false);
  // Actions stay invisible until the row has moved, so no sliver shows past its edge at rest.
  const revealed = x.interpolate({
    inputRange: [-8, 0],
    outputRange: [1, 0],
    extrapolate: "clamp",
  });

  const width = actions.length * actionWidth;
  // The responder is created once, so it reads the latest values from here.
  const live = useRef({ width, openThreshold, reduceMotion, onOpenChange });
  live.current = { width, openThreshold, reduceMotion, onOpenChange };

  const settle = (target: number, velocity = 0) => {
    base.current = target;
    const isOpen = target !== 0;
    setOpen(isOpen);
    live.current.onOpenChange?.(isOpen);
    if (live.current.reduceMotion) {
      x.setValue(target);
      return;
    }
    Animated.spring(x, {
      toValue: target,
      velocity,
      stiffness: 380,
      damping: 34,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const pan = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 6 && Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => {
        dragging.current = true;
        x.stopAnimation();
      },
      onPanResponderMove: (_, g) => {
        const max = live.current.width;
        const raw = base.current + g.dx;
        // Past either end the row still moves, but a quarter as far.
        const next = raw > 0 ? raw / 4 : raw < -max ? -max + (raw + max) / 4 : raw;
        x.setValue(next);
      },
      onPanResponderRelease: (_, g) => {
        setTimeout(() => (dragging.current = false), 80);
        const { width: max, openThreshold: threshold } = live.current;
        const end = base.current + g.dx;
        const flickedOpen = g.vx < -0.5;
        const flickedShut = g.vx > 0.5;
        const pastThreshold = end < -max * threshold;
        settle(!flickedShut && (flickedOpen || pastThreshold) ? -max : 0, g.vx);
      },
      onPanResponderTerminate: () => {
        setTimeout(() => (dragging.current = false), 80);
        settle(base.current);
      },
    }),
  ).current;

  return (
    <View style={[styles.root, { backgroundColor: palette.surface }, style]}>
      <Animated.View
        style={[styles.actions, { width, opacity: revealed }]}
        pointerEvents={open ? "auto" : "none"}
      >
        {actions.map((action) => (
          <Pressable
            key={action.label}
            accessibilityRole="button"
            accessibilityLabel={action.label}
            onPress={() => {
              action.onPress();
              settle(0);
            }}
            style={({ pressed }) => [
              styles.action,
              { width: actionWidth, backgroundColor: action.color ?? palette.action },
              pressed && styles.actionPressed,
            ]}
          >
            <Text style={[styles.actionText, { color: palette.actionText }]} numberOfLines={1}>
              {action.label}
            </Text>
          </Pressable>
        ))}
      </Animated.View>
      <Animated.View
        {...pan.panHandlers}
        accessible
        accessibilityActions={actions.map((action) => ({
          name: action.label,
          label: action.label,
        }))}
        onAccessibilityAction={(event) =>
          actions.find((action) => action.label === event.nativeEvent.actionName)?.onPress()
        }
        style={[
          styles.content,
          { backgroundColor: palette.surface, transform: [{ translateX: x }] },
        ]}
      >
        <Pressable
          disabled={!open}
          accessible={false}
          onPress={() => {
            if (!dragging.current) settle(0);
          }}
          style={styles.fill}
        >
          <View pointerEvents={open ? "none" : "auto"}>{children}</View>
        </Pressable>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { overflow: "hidden" },
  actions: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    flexDirection: "row",
  },
  action: { alignItems: "center", justifyContent: "center", paddingHorizontal: 6 },
  actionPressed: { opacity: 0.8 },
  actionText: { fontSize: 14, fontWeight: "600" },
  // userSelect keeps a mouse drag on the web from selecting the row's text instead of moving it.
  content: { width: "100%", userSelect: "none" },
  fill: { width: "100%" },
});
```

---

# Snap Sheet

> A React Native bottom sheet with snap points, flick momentum, dismiss-by-drag and an adjustable handle for screen readers.

Install: `npx @modus-ui/cli add snap-sheet`

A bottom sheet with snap points. Drag the handle: release picks the nearest stop, a flick carries it to the next, and pulling past the lowest stop dismisses it. The sheet draws inside its parent, so it works in a screen, a tab or a `Modal`. The handle is also an adjustable control for screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add snap-sheet
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/snap-sheet.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, Text, View } from "react-native";
import { SnapSheet } from "@/components/ui/snap-sheet";

export default function Example() {
  const [open, setOpen] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Details" onPress={() => setOpen(true)} />
      <SnapSheet open={open} onClose={() => setOpen(false)} title="Delivery details">
        <Text>Arrives Thursday</Text>
      </SnapSheet>
    </View>
  );
}
```

The parent must fill the area the sheet should cover, because the sheet and its backdrop are sized to it.

## Props

| Prop           | Type                       | Default      | Description                                                                     |
| :------------- | :------------------------- | :----------- | :------------------------------------------------------------------------------ |
| `open`         | `boolean`                  | -            | Whether the sheet is showing.                                                   |
| `onClose`      | `() => void`               | -            | Called when the sheet is dismissed by dragging it down or tapping the backdrop. |
| `title`        | `string`                   | -            | Heading next to the handle. Also the handle's accessibility label.              |
| `snapPoints`   | `number[]`                 | `[0.4, 0.9]` | Visible height at each stop, as a fraction of the container, lowest first.      |
| `initialSnap`  | `number`                   | `0`          | Index into `snapPoints` the sheet opens at.                                     |
| `onSnapChange` | `(index: number) => void`  | -            | Called when the sheet settles on a stop.                                        |
| `colors`       | `Partial<SnapSheetColors>` | -            | Overrides `surface`, `handle`, `title` and `backdrop`.                          |
| `style`        | `StyleProp<ViewStyle>`     | -            | Style for the sheet.                                                            |

## Source

`components/ui/snap-sheet.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface SnapSheetColors {
  surface: string;
  handle: string;
  title: string;
  backdrop: string;
}

const DEFAULT_COLORS: SnapSheetColors = {
  surface: "#ffffff",
  handle: "#c7c7cc",
  title: "#111827",
  backdrop: "rgba(0, 0, 0, 0.45)",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SnapSheetProps {
  /** Whether the sheet is showing. Dragging it below the lowest stop calls `onClose`. */
  open: boolean;
  onClose: () => void;
  children: ReactNode;
  title?: string;
  /** Visible height at each stop, as a fraction of the container, lowest first. */
  snapPoints?: number[];
  /** Index into `snapPoints` the sheet opens at. */
  initialSnap?: number;
  onSnapChange?: (index: number) => void;
  colors?: Partial<SnapSheetColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A bottom sheet with snap points, drawn inside its parent so it works in a screen, a tab or a
 * Modal alike (the parent must fill the area the sheet should cover). Drag the handle: release
 * picks the nearest stop, a flick carries it to the next one, and pulling past the lowest stop
 * dismisses. The handle is also an adjustable control for screen readers.
 */
export function SnapSheet({
  open,
  onClose,
  children,
  title,
  snapPoints = [0.4, 0.9],
  initialSnap = 0,
  onSnapChange,
  colors,
  style,
}: SnapSheetProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [height, setHeight] = useState(0);
  const [snap, setSnap] = useState(initialSnap);
  const y = useRef(new Animated.Value(0)).current;
  const base = useRef(0);

  const stops = [...snapPoints].sort((a, b) => a - b);
  const sheetHeight = height * stops[stops.length - 1];
  // translateY of each stop (0 = fully raised), then the hidden position last.
  const offsets = stops.map((fraction) => height * (stops[stops.length - 1] - fraction));
  const hidden = sheetHeight;

  const live = useRef({ offsets, hidden, reduceMotion, onClose, onSnapChange });
  live.current = { offsets, hidden, reduceMotion, onClose, onSnapChange };

  const moveTo = (target: number, velocity = 0) => {
    base.current = target;
    if (live.current.reduceMotion) {
      y.setValue(target);
      return;
    }
    Animated.spring(y, {
      toValue: target,
      velocity,
      stiffness: 320,
      damping: 32,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const goToSnap = (index: number, velocity = 0) => {
    const clamped = Math.max(0, Math.min(live.current.offsets.length - 1, index));
    setSnap(clamped);
    live.current.onSnapChange?.(clamped);
    moveTo(live.current.offsets[clamped], velocity);
  };

  useEffect(() => {
    if (height === 0) return;
    if (open) goToSnap(initialSnap);
    else moveTo(hidden);
    // goToSnap and moveTo read everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [open, height]);

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderGrant: () => y.stopAnimation(),
      onPanResponderMove: (_, g) => {
        const { offsets: o, hidden: h } = live.current;
        const raw = base.current + g.dy;
        // Stretch a quarter as far above the top stop; follow the finger everywhere else.
        y.setValue(raw < o[0] ? o[0] + (raw - o[0]) / 4 : Math.min(raw, h));
      },
      onPanResponderRelease: (_, g) => {
        const { offsets: o, hidden: h, onClose: close } = live.current;
        const end = base.current + g.dy;
        // Project where a flick would land, then take the closest stop (or the hidden position).
        const projected = end + g.vy * 120;
        const candidates = [...o, h];
        const nearest = candidates.reduce(
          (best, offset, index) =>
            Math.abs(offset - projected) < Math.abs(candidates[best] - projected) ? index : best,
          0,
        );
        if (nearest === o.length) {
          moveTo(h, g.vy);
          close();
        } else {
          goToSnap(nearest, g.vy);
        }
      },
    }),
  ).current;

  const onLayout = (event: LayoutChangeEvent) => {
    const next = event.nativeEvent.layout.height;
    if (next !== height) {
      if (height === 0) y.setValue(next * stops[stops.length - 1]);
      setHeight(next);
    }
  };

  const backdropOpacity = y.interpolate({
    inputRange: [offsets[0] ?? 0, hidden || 1],
    outputRange: [1, 0],
    extrapolate: "clamp",
  });

  return (
    <View style={StyleSheet.absoluteFill} pointerEvents="box-none" onLayout={onLayout}>
      <Animated.View
        pointerEvents={open ? "auto" : "none"}
        style={[
          StyleSheet.absoluteFill,
          { backgroundColor: palette.backdrop, opacity: backdropOpacity },
        ]}
      >
        <Pressable
          accessibilityLabel="Close"
          accessibilityRole="button"
          onPress={onClose}
          style={StyleSheet.absoluteFill}
        />
      </Animated.View>
      <Animated.View
        accessibilityViewIsModal={open}
        pointerEvents={open ? "auto" : "none"}
        style={[
          styles.sheet,
          { height: sheetHeight, backgroundColor: palette.surface, transform: [{ translateY: y }] },
          style,
        ]}
      >
        <View
          {...pan.panHandlers}
          accessible
          accessibilityRole="adjustable"
          accessibilityLabel={title ?? "Sheet"}
          accessibilityValue={{ text: `Stop ${snap + 1} of ${stops.length}` }}
          aria-valuetext={`Stop ${snap + 1} of ${stops.length}`}
          accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
          onAccessibilityAction={(event) =>
            goToSnap(snap + (event.nativeEvent.actionName === "increment" ? 1 : -1))
          }
          style={styles.grab}
        >
          <View style={[styles.handle, { backgroundColor: palette.handle }]} />
          {title ? <Text style={[styles.title, { color: palette.title }]}>{title}</Text> : null}
        </View>
        <View style={styles.body}>{children}</View>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  sheet: {
    position: "absolute",
    left: 0,
    right: 0,
    bottom: 0,
    borderTopLeftRadius: 24,
    borderTopRightRadius: 24,
    overflow: "hidden",
    boxShadow: "0 -8px 32px rgba(0, 0, 0, 0.18)",
  },
  // userSelect keeps a mouse drag on the web from selecting the title instead of moving the sheet.
  grab: {
    alignItems: "center",
    paddingTop: 10,
    paddingBottom: 12,
    paddingHorizontal: 20,
    userSelect: "none",
  },
  handle: { width: 40, height: 5, borderRadius: 3 },
  title: { marginTop: 14, alignSelf: "flex-start", fontSize: 18, fontWeight: "700" },
  body: { flex: 1, paddingHorizontal: 20 },
});
```

---

# Glide Segments

> A React Native segmented control whose thumb glides between options on a spring and stretches as it travels.

Install: `npx @modus-ui/cli add glide-segments`

A segmented control whose thumb glides between options on a spring and stretches slightly as it travels. Segments share the width equally, each is a full touch target, and screen readers hear them as tabs. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add glide-segments
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/glide-segments.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { GlideSegments } from "@/components/ui/glide-segments";

export default function Example() {
  const [range, setRange] = useState("week");

  return (
    <GlideSegments
      value={range}
      onChange={setRange}
      options={[
        { value: "day", label: "Day" },
        { value: "week", label: "Week" },
        { value: "month", label: "Month" },
      ]}
    />
  );
}
```

## Props

| Prop       | Type                           | Default | Description                                            |
| :--------- | :----------------------------- | :------ | :----------------------------------------------------- |
| `options`  | `GlideSegmentsOption[]`        | -       | The segments, each with a `value` and a `label`.       |
| `value`    | `string`                       | -       | The selected option's `value`.                         |
| `onChange` | `(value: string) => void`      | -       | Called with the tapped option's `value`.               |
| `height`   | `number`                       | `40`    | Height of the control.                                 |
| `colors`   | `Partial<GlideSegmentsColors>` | -       | Overrides `track`, `thumb`, `text` and `selectedText`. |
| `style`    | `StyleProp<ViewStyle>`         | -       | Style for the track.                                   |

## Source

`components/ui/glide-segments.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const PADDING = 3;

export interface GlideSegmentsOption {
  value: string;
  label: string;
}

export interface GlideSegmentsColors {
  track: string;
  thumb: string;
  text: string;
  selectedText: string;
}

const DEFAULT_COLORS: GlideSegmentsColors = {
  track: "#e5e7eb",
  thumb: "#ffffff",
  text: "#6b7280",
  selectedText: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface GlideSegmentsProps {
  options: GlideSegmentsOption[];
  value: string;
  onChange: (value: string) => void;
  /** Height of the control. */
  height?: number;
  colors?: Partial<GlideSegmentsColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A segmented control whose thumb glides between options on a spring and stretches slightly as it
 * travels. Segments share the width equally, take the full touch target, and read as tabs to
 * screen readers.
 */
export function GlideSegments({
  options,
  value,
  onChange,
  height = 40,
  colors,
  style,
}: GlideSegmentsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const x = useRef(new Animated.Value(0)).current;
  const stretch = useRef(new Animated.Value(1)).current;

  const index = Math.max(
    0,
    options.findIndex((option) => option.value === value),
  );
  const segment = options.length > 0 ? (width - PADDING * 2) / options.length : 0;

  useEffect(() => {
    if (segment === 0) return;
    const target = index * segment;
    if (reduceMotion) {
      x.setValue(target);
      return;
    }
    Animated.parallel([
      Animated.spring(x, {
        toValue: target,
        stiffness: 420,
        damping: 32,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }),
      Animated.sequence([
        Animated.timing(stretch, { toValue: 1.12, duration: 110, useNativeDriver: NATIVE_DRIVER }),
        Animated.spring(stretch, {
          toValue: 1,
          stiffness: 300,
          damping: 20,
          mass: 1,
          useNativeDriver: NATIVE_DRIVER,
        }),
      ]),
    ]).start();
  }, [index, segment, reduceMotion, x, stretch]);

  return (
    <View
      accessibilityRole="tablist"
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={[
        styles.track,
        { height, borderRadius: height / 2, backgroundColor: palette.track },
        style,
      ]}
    >
      {segment > 0 ? (
        <Animated.View
          pointerEvents="none"
          style={[
            styles.thumb,
            {
              width: segment,
              borderRadius: (height - PADDING * 2) / 2,
              backgroundColor: palette.thumb,
              transform: [{ translateX: x }, { scaleX: stretch }],
            },
          ]}
        />
      ) : null}
      {options.map((option) => {
        const selected = option.value === value;
        return (
          <Pressable
            key={option.value}
            accessibilityRole="tab"
            accessibilityState={{ selected }}
            aria-selected={selected}
            onPress={() => onChange(option.value)}
            style={styles.segment}
          >
            <Text
              numberOfLines={1}
              style={[styles.label, { color: selected ? palette.selectedText : palette.text }]}
            >
              {option.label}
            </Text>
          </Pressable>
        );
      })}
    </View>
  );
}

const styles = StyleSheet.create({
  track: { flexDirection: "row", padding: PADDING, userSelect: "none" },
  thumb: {
    position: "absolute",
    top: PADDING,
    bottom: PADDING,
    left: PADDING,
    boxShadow: "0 1px 3px rgba(0, 0, 0, 0.16)",
  },
  segment: { flex: 1, alignItems: "center", justifyContent: "center", paddingHorizontal: 8 },
  label: { fontSize: 14, fontWeight: "600" },
});
```

---

# Swipe Deck

> A React Native card stack swiped away one at a time, with tilt, a rising next card, like and pass stamps, and screen reader actions.

Install: `npx @modus-ui/cli add swipe-deck`

A stack of cards swiped away one at a time. The top card follows the finger and tilts with it, the card underneath grows to take its place, and release either flies the card off or springs it back. Each swipe is also a screen reader action, so the deck works without the gesture. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add swipe-deck
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/swipe-deck.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text, View } from "react-native";
import { SwipeDeck } from "@/components/ui/swipe-deck";

const places = [
  { id: "lisbon", city: "Lisbon" },
  { id: "kyoto", city: "Kyoto" },
];

export default function Example() {
  return (
    <View style={{ height: 420, padding: 20 }}>
      <SwipeDeck
        data={places}
        keyExtractor={(place) => place.id}
        renderCard={(place) => <Text style={{ padding: 20, fontSize: 28 }}>{place.city}</Text>}
        onSwipe={(place, direction) => console.log(place.city, direction)}
      />
    </View>
  );
}
```

The deck fills its parent, so give the parent a height.

## Props

| Prop           | Type                                      | Default  | Description                                                                                   |
| :------------- | :---------------------------------------- | :------- | :-------------------------------------------------------------------------------------------- |
| `data`         | `T[]`                                     | -        | The items to swipe through, first item on top.                                                |
| `renderCard`   | `(item: T, index: number) => ReactNode`   | -        | Renders a card's content. The deck draws the card itself.                                     |
| `keyExtractor` | `(item: T, index: number) => string`      | -        | A stable key for each item.                                                                   |
| `onSwipe`      | `(item: T, direction: Direction) => void` | -        | Called once a card has left the deck, with `"left"` or `"right"`.                             |
| `empty`        | `ReactNode`                               | -        | Shown when every card has been swiped.                                                        |
| `visible`      | `number`                                  | `3`      | How many cards are drawn at once, the top one included.                                       |
| `threshold`    | `number`                                  | `0.3`    | Fraction of the deck's width a drag must cover to send the card away. A fast flick also does. |
| `rightLabel`   | `string`                                  | `"Like"` | Stamp on the card, and screen reader action, for a swipe to the right.                        |
| `leftLabel`    | `string`                                  | `"Pass"` | Stamp on the card, and screen reader action, for a swipe to the left.                         |
| `colors`       | `Partial<SwipeDeckColors>`                | -        | Overrides `card`, `border`, `like` and `pass`.                                                |
| `style`        | `StyleProp<ViewStyle>`                    | -        | Style for the deck container.                                                                 |

## Source

`components/ui/swipe-deck.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Each card behind the top one sits this much smaller and lower.
const DEPTH_SCALE = 0.05;
const DEPTH_LIFT = 12;

type Direction = "left" | "right";

export interface SwipeDeckColors {
  card: string;
  border: string;
  like: string;
  pass: string;
}

const DEFAULT_COLORS: SwipeDeckColors = {
  card: "#ffffff",
  border: "#e5e7eb",
  like: "#16a34a",
  pass: "#dc2626",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SwipeDeckProps<T> {
  data: T[];
  renderCard: (item: T, index: number) => ReactNode;
  keyExtractor: (item: T, index: number) => string;
  /** Called once a card has left the deck. */
  onSwipe?: (item: T, direction: Direction) => void;
  /** Shown when every card has been swiped. */
  empty?: ReactNode;
  /** How many cards are drawn at once, the top one included. */
  visible?: number;
  /** Fraction of the deck's width a drag must cover to send the card away. A fast flick also does. */
  threshold?: number;
  /** Stamp on the card, and screen reader action, for a swipe to the right. */
  rightLabel?: string;
  /** Stamp on the card, and screen reader action, for a swipe to the left. */
  leftLabel?: string;
  colors?: Partial<SwipeDeckColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A stack of cards swiped away one at a time. The top card follows the finger and tilts with it,
 * the card underneath grows to take its place, and release either flies the card off or springs it
 * back. Each swipe is also a screen reader action, so the deck works without the gesture.
 */
export function SwipeDeck<T>({
  data,
  renderCard,
  keyExtractor,
  onSwipe,
  empty,
  visible = 3,
  threshold = 0.3,
  rightLabel = "Like",
  leftLabel = "Pass",
  colors,
  style,
}: SwipeDeckProps<T>) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const [index, setIndex] = useState(0);
  // 0 to 1 as the top card is dragged toward leaving; the cards beneath rise with it.
  const progress = useRef(new Animated.Value(0)).current;

  const cards = data.slice(index, index + visible);

  const handleSwiped = (item: T, direction: Direction) => {
    progress.setValue(0);
    setIndex((current) => current + 1);
    onSwipe?.(item, direction);
  };

  return (
    <View
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={[styles.root, style]}
    >
      {cards.length === 0 ? <View style={styles.empty}>{empty}</View> : null}
      {width > 0
        ? cards
            .map((item, depth) => (
              <DeckCard
                key={keyExtractor(item, index + depth)}
                depth={depth}
                width={width}
                threshold={threshold}
                progress={progress}
                reduceMotion={reduceMotion}
                colors={palette}
                rightLabel={rightLabel}
                leftLabel={leftLabel}
                onSwiped={(direction) => handleSwiped(item, direction)}
              >
                {renderCard(item, index + depth)}
              </DeckCard>
            ))
            // The top card is drawn last, so it sits above the rest.
            .reverse()
        : null}
    </View>
  );
}

interface DeckCardProps {
  children: ReactNode;
  depth: number;
  width: number;
  threshold: number;
  progress: Animated.Value;
  reduceMotion: boolean;
  colors: SwipeDeckColors;
  rightLabel: string;
  leftLabel: string;
  onSwiped: (direction: Direction) => void;
}

function DeckCard({
  children,
  depth,
  width,
  threshold,
  progress,
  reduceMotion,
  colors,
  rightLabel,
  leftLabel,
  onSwiped,
}: DeckCardProps) {
  const x = useRef(new Animated.Value(0)).current;
  const y = useRef(new Animated.Value(0)).current;
  const live = useRef({ depth, width, threshold, reduceMotion, onSwiped });
  live.current = { depth, width, threshold, reduceMotion, onSwiped };
  const leaving = useRef(false);

  const fling = (direction: Direction) => {
    if (leaving.current) return;
    leaving.current = true;
    const { width: w, reduceMotion: reduce, onSwiped: done } = live.current;
    const target = (direction === "right" ? 1 : -1) * w * 1.4;
    if (reduce) {
      done(direction);
      return;
    }
    Animated.timing(x, { toValue: target, duration: 220, useNativeDriver: NATIVE_DRIVER }).start(
      () => done(direction),
    );
  };

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => live.current.depth === 0,
      onMoveShouldSetPanResponder: (_, g) =>
        live.current.depth === 0 && Math.abs(g.dx) > 4 && Math.abs(g.dx) > Math.abs(g.dy) * 0.6,
      onPanResponderGrant: () => {
        x.stopAnimation();
        y.stopAnimation();
      },
      onPanResponderMove: (_, g) => {
        x.setValue(g.dx);
        y.setValue(g.dy * 0.4);
        const reach = live.current.width * live.current.threshold;
        progress.setValue(Math.min(1, Math.abs(g.dx) / reach));
      },
      onPanResponderRelease: (_, g) => {
        const { width: w, threshold: t } = live.current;
        const flick = Math.abs(g.vx) > 0.8;
        if (Math.abs(g.dx) > w * t || (flick && g.dx * g.vx > 0)) {
          fling(g.dx > 0 ? "right" : "left");
          return;
        }
        const back = (value: Animated.Value) =>
          Animated.spring(value, {
            toValue: 0,
            stiffness: 360,
            damping: 28,
            mass: 1,
            useNativeDriver: NATIVE_DRIVER,
          });
        progress.setValue(0);
        if (live.current.reduceMotion) {
          x.setValue(0);
          y.setValue(0);
        } else {
          Animated.parallel([back(x), back(y)]).start();
        }
      },
    }),
  ).current;

  const top = depth === 0;
  const rotate = reduceMotion
    ? "0deg"
    : x.interpolate({ inputRange: [-width, 0, width], outputRange: ["-14deg", "0deg", "14deg"] });
  const scale = top
    ? 1
    : progress.interpolate({
        inputRange: [0, 1],
        outputRange: [1 - depth * DEPTH_SCALE, 1 - (depth - 1) * DEPTH_SCALE],
      });
  const lift = top
    ? 0
    : progress.interpolate({
        inputRange: [0, 1],
        outputRange: [depth * DEPTH_LIFT, (depth - 1) * DEPTH_LIFT],
      });
  const likeOpacity = x.interpolate({
    inputRange: [0, width * 0.3],
    outputRange: [0, 1],
    extrapolate: "clamp",
  });
  const passOpacity = x.interpolate({
    inputRange: [-width * 0.3, 0],
    outputRange: [1, 0],
    extrapolate: "clamp",
  });

  return (
    <Animated.View
      {...(top ? pan.panHandlers : {})}
      accessible={top}
      accessibilityActions={
        top
          ? [
              { name: "swipeRight", label: rightLabel },
              { name: "swipeLeft", label: leftLabel },
            ]
          : undefined
      }
      onAccessibilityAction={(event) =>
        fling(event.nativeEvent.actionName === "swipeRight" ? "right" : "left")
      }
      pointerEvents={top ? "auto" : "none"}
      style={[
        styles.card,
        {
          backgroundColor: colors.card,
          borderColor: colors.border,
          transform: [
            { translateX: x },
            { translateY: Animated.add(y, lift) },
            { rotate },
            { scale },
          ],
        },
      ]}
    >
      {children}
      {top ? (
        <>
          <Animated.View
            pointerEvents="none"
            style={[
              styles.stamp,
              styles.stampLeft,
              { borderColor: colors.like, opacity: likeOpacity },
            ]}
          >
            <Text style={[styles.stampText, { color: colors.like }]}>{rightLabel}</Text>
          </Animated.View>
          <Animated.View
            pointerEvents="none"
            style={[
              styles.stamp,
              styles.stampRight,
              { borderColor: colors.pass, opacity: passOpacity },
            ]}
          >
            <Text style={[styles.stampText, { color: colors.pass }]}>{leftLabel}</Text>
          </Animated.View>
        </>
      ) : null}
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1 },
  // userSelect keeps a mouse drag on the web from selecting the card's text instead of moving it.
  card: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    borderRadius: 24,
    borderWidth: 1,
    overflow: "hidden",
    userSelect: "none",
    boxShadow: "0 10px 30px rgba(0, 0, 0, 0.14)",
  },
  empty: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
  },
  stamp: {
    position: "absolute",
    top: 24,
    borderWidth: 3,
    borderRadius: 10,
    paddingHorizontal: 12,
    paddingVertical: 4,
  },
  stampLeft: { left: 20, transform: [{ rotate: "-12deg" }] },
  stampRight: { right: 20, transform: [{ rotate: "12deg" }] },
  stampText: { fontSize: 22, fontWeight: "800", letterSpacing: 1, textTransform: "uppercase" },
});
```

---

# Fan Menu

> A React Native floating button that fans its actions out along an arc, springing them out one after another.

Install: `npx @modus-ui/cli add fan-menu`

A floating button that fans its actions out along an arc. The items spring out one after another, the plus turns into a cross, and picking an item folds the fan away. Place it with `style`; the items are positioned from the button, so keep room for the arc on that side. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add fan-menu
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/fan-menu.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text, View } from "react-native";
import { FanMenu } from "@/components/ui/fan-menu";

export default function Example() {
  return (
    <View style={{ flex: 1 }}>
      <FanMenu
        style={{ position: "absolute", right: 24, bottom: 24 }}
        items={[
          { label: "New note", icon: <Text>✎</Text>, onPress: () => console.log("note") },
          { label: "Email", icon: <Text>✉</Text>, onPress: () => console.log("email") },
        ]}
      />
    </View>
  );
}
```

## Props

| Prop         | Type                     | Default     | Description                                                              |
| :----------- | :----------------------- | :---------- | :----------------------------------------------------------------------- |
| `items`      | `FanMenuItem[]`          | -           | The actions. Each has a spoken `label`, an `icon` and an `onPress`.      |
| `label`      | `string`                 | `"Actions"` | Spoken label of the main button.                                         |
| `size`       | `number`                 | `58`        | Diameter of the main button.                                             |
| `radius`     | `number`                 | `104`       | Distance from the main button to each item.                              |
| `startAngle` | `number`                 | `180`       | Where the fan starts, in degrees: 0 is right, 90 down, 180 left, 270 up. |
| `endAngle`   | `number`                 | `270`       | Where the fan ends, in degrees.                                          |
| `colors`     | `Partial<FanMenuColors>` | -           | Overrides `button`, `bar` and `item`.                                    |
| `style`      | `StyleProp<ViewStyle>`   | -           | Style for the button's container, for example to position it.            |

## Source

`components/ui/fan-menu.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const ITEM_SIZE = 46;

export interface FanMenuItem {
  /** Spoken label, since the button shows only its icon. */
  label: string;
  icon: ReactNode;
  onPress: () => void;
}

export interface FanMenuColors {
  button: string;
  bar: string;
  item: string;
}

const DEFAULT_COLORS: FanMenuColors = {
  button: "#4f46e5",
  bar: "#ffffff",
  item: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface FanMenuProps {
  items: FanMenuItem[];
  /** Spoken label of the main button. */
  label?: string;
  /** Diameter of the main button. */
  size?: number;
  /** Distance from the main button to each item. */
  radius?: number;
  /** Where the fan starts, in degrees: 0 is right, 90 down, 180 left, 270 up. */
  startAngle?: number;
  /** Where the fan ends, in degrees. */
  endAngle?: number;
  colors?: Partial<FanMenuColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A floating button that fans its actions out along an arc. The items spring out one after another,
 * the plus turns into a cross, and picking an item folds the fan away. Place it with `style`; the
 * items are positioned from the button, so keep room for the arc on that side.
 */
export function FanMenu({
  items,
  label = "Actions",
  size = 58,
  radius = 104,
  startAngle = 180,
  endAngle = 270,
  colors,
  style,
}: FanMenuProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [open, setOpen] = useState(false);
  const progress = useRef(items.map(() => new Animated.Value(0))).current;
  const turn = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    const target = open ? 1 : 0;
    if (reduceMotion) {
      progress.forEach((value) => value.setValue(target));
      turn.setValue(target);
      return;
    }
    Animated.parallel([
      Animated.spring(turn, {
        toValue: target,
        stiffness: 300,
        damping: 22,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }),
      Animated.stagger(
        45,
        (open ? progress : [...progress].reverse()).map((value) =>
          Animated.spring(value, {
            toValue: target,
            stiffness: 260,
            damping: 17,
            mass: 1,
            useNativeDriver: NATIVE_DRIVER,
          }),
        ),
      ),
    ]).start();
  }, [open, reduceMotion, progress, turn]);

  const spread = items.length > 1 ? (endAngle - startAngle) / (items.length - 1) : 0;
  const first = items.length > 1 ? startAngle : (startAngle + endAngle) / 2;

  return (
    <View style={[{ width: size, height: size }, style]}>
      {items.map((item, i) => {
        const radians = ((first + spread * i) * Math.PI) / 180;
        const value = progress[i];
        return (
          <Animated.View
            key={item.label}
            pointerEvents={open ? "auto" : "none"}
            style={[
              styles.item,
              {
                width: ITEM_SIZE,
                height: ITEM_SIZE,
                borderRadius: ITEM_SIZE / 2,
                left: (size - ITEM_SIZE) / 2,
                top: (size - ITEM_SIZE) / 2,
                backgroundColor: palette.item,
                opacity: value.interpolate({ inputRange: [0, 0.4, 1], outputRange: [0, 1, 1] }),
                transform: [
                  {
                    translateX: value.interpolate({
                      inputRange: [0, 1],
                      outputRange: [0, Math.cos(radians) * radius],
                    }),
                  },
                  {
                    translateY: value.interpolate({
                      inputRange: [0, 1],
                      outputRange: [0, Math.sin(radians) * radius],
                    }),
                  },
                  { scale: value.interpolate({ inputRange: [0, 1], outputRange: [0.4, 1] }) },
                ],
              },
            ]}
          >
            <Pressable
              accessibilityRole="button"
              accessibilityLabel={item.label}
              onPress={() => {
                setOpen(false);
                item.onPress();
              }}
              style={({ pressed }) => [styles.itemPress, pressed && styles.pressed]}
            >
              {item.icon}
            </Pressable>
          </Animated.View>
        );
      })}
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={label}
        accessibilityState={{ expanded: open }}
        aria-expanded={open}
        onPress={() => setOpen((current) => !current)}
        style={({ pressed }) => [
          styles.button,
          { width: size, height: size, borderRadius: size / 2, backgroundColor: palette.button },
          pressed && styles.pressed,
        ]}
      >
        <Animated.View
          style={{
            width: size * 0.34,
            height: size * 0.34,
            transform: [
              { rotate: turn.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "135deg"] }) },
            ],
          }}
        >
          <View style={[styles.bar, styles.barAcross, { backgroundColor: palette.bar }]} />
          <View style={[styles.bar, styles.barDown, { backgroundColor: palette.bar }]} />
        </Animated.View>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  item: {
    position: "absolute",
    boxShadow: "0 4px 14px rgba(0, 0, 0, 0.2)",
  },
  itemPress: { flex: 1, alignItems: "center", justifyContent: "center", borderRadius: 999 },
  button: {
    alignItems: "center",
    justifyContent: "center",
    boxShadow: "0 6px 18px rgba(0, 0, 0, 0.25)",
  },
  pressed: { opacity: 0.85 },
  bar: { position: "absolute", borderRadius: 2 },
  barAcross: { left: 0, right: 0, top: "50%", height: 3, marginTop: -1.5 },
  barDown: { top: 0, bottom: 0, left: "50%", width: 3, marginLeft: -1.5 },
});
```

---

# Pin Pad

> A React Native numeric keypad for PINs and passcodes, with popping dots, a shake on a wrong PIN and spoken progress.

Install: `npx @modus-ui/cli add pin-pad`

A numeric keypad for PINs and passcodes. Dots fill with a small pop as digits go in, a wrong PIN shakes the row and clears it, and a right one turns the dots green. Every key is a full-size button with a spoken label, and the dots announce progress as a single value. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add pin-pad
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pin-pad.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { PinPad } from "@/components/ui/pin-pad";

export default function Example() {
  return (
    <PinPad
      title="Enter your PIN"
      onComplete={async (pin) => {
        const response = await fetch("/api/unlock", { method: "POST", body: pin });
        return response.ok;
      }}
    />
  );
}
```

## Props

| Prop         | Type                                           | Default                  | Description                                                                             |
| :----------- | :--------------------------------------------- | :----------------------- | :-------------------------------------------------------------------------------------- |
| `onComplete` | `(pin: string) => boolean \| Promise<boolean>` | -                        | Receives the full PIN. Return true to accept it; false shakes the dots and clears them. |
| `length`     | `number`                                       | `4`                      | How many digits make a PIN.                                                             |
| `title`      | `string`                                       | -                        | Heading above the dots.                                                                 |
| `errorText`  | `string`                                       | `"Wrong PIN, try again"` | Shown under the dots after a wrong PIN.                                                 |
| `colors`     | `Partial<PinPadColors>`                        | -                        | Overrides `text`, `mutedText`, `dot`, `key`, `keyText`, `error` and `success`.          |
| `style`      | `StyleProp<ViewStyle>`                         | -                        | Style for the container.                                                                |

## Source

`components/ui/pin-pad.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const KEYS = ["1", "2", "3", "4", "5", "6", "7", "8", "9", "", "0", "delete"] as const;

export interface PinPadColors {
  text: string;
  mutedText: string;
  dot: string;
  key: string;
  keyText: string;
  error: string;
  success: string;
}

const DEFAULT_COLORS: PinPadColors = {
  text: "#111827",
  mutedText: "#6b7280",
  dot: "#9ca3af",
  key: "#f3f4f6",
  keyText: "#111827",
  error: "#dc2626",
  success: "#16a34a",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface PinPadProps {
  /** Receives the full PIN. Return true to accept it; false shakes the dots and clears them. */
  onComplete: (pin: string) => boolean | Promise<boolean>;
  /** How many digits make a PIN. */
  length?: number;
  title?: string;
  /** Shown under the dots after a wrong PIN. */
  errorText?: string;
  colors?: Partial<PinPadColors>;
  style?: StyleProp<ViewStyle>;
}

type Status = "idle" | "checking" | "error" | "ok";

/**
 * A numeric keypad for PINs and passcodes. Dots fill with a small pop as digits go in, a wrong PIN
 * shakes the row and clears it, and a right one turns the dots green. Every key is a full-size
 * button with a spoken label; the dots announce progress as a single value.
 */
export function PinPad({
  onComplete,
  length = 4,
  title,
  errorText = "Wrong PIN, try again",
  colors,
  style,
}: PinPadProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [pin, setPin] = useState("");
  const [status, setStatus] = useState<Status>("idle");
  const shake = useRef(new Animated.Value(0)).current;

  const submit = async (value: string) => {
    setStatus("checking");
    const accepted = await onComplete(value);
    if (accepted) {
      setStatus("ok");
      return;
    }
    setStatus("error");
    if (!reduceMotion) {
      Animated.sequence(
        [-12, 12, -9, 9, -5, 0].map((toValue) =>
          Animated.timing(shake, { toValue, duration: 55, useNativeDriver: NATIVE_DRIVER }),
        ),
      ).start();
    }
    setTimeout(() => {
      setPin("");
      setStatus("idle");
    }, 700);
  };

  const press = (key: (typeof KEYS)[number]) => {
    if (status === "checking" || status === "error" || status === "ok") return;
    if (key === "delete") {
      setPin((current) => current.slice(0, -1));
      return;
    }
    if (key === "" || pin.length >= length) return;
    const next = pin + key;
    setPin(next);
    if (next.length === length) submit(next);
  };

  const dotColor =
    status === "error" ? palette.error : status === "ok" ? palette.success : palette.dot;

  return (
    <View style={[styles.root, style]}>
      {title ? <Text style={[styles.title, { color: palette.text }]}>{title}</Text> : null}
      <Animated.View
        accessible
        accessibilityRole="progressbar"
        accessibilityLabel="PIN"
        accessibilityValue={{ min: 0, max: length, now: pin.length }}
        aria-valuemin={0}
        aria-valuemax={length}
        aria-valuenow={pin.length}
        style={[styles.dots, { transform: [{ translateX: shake }] }]}
      >
        {Array.from({ length }, (_, i) => (
          <Dot key={i} filled={i < pin.length} color={dotColor} reduceMotion={reduceMotion} />
        ))}
      </Animated.View>
      <Text
        accessibilityLiveRegion="polite"
        style={[styles.error, { color: palette.error, opacity: status === "error" ? 1 : 0 }]}
      >
        {errorText}
      </Text>
      <View style={styles.grid}>
        {KEYS.map((key) =>
          key === "" ? (
            <View key="blank" style={styles.key} />
          ) : (
            <Pressable
              key={key}
              accessibilityRole="button"
              accessibilityLabel={key === "delete" ? "Delete" : key}
              onPress={() => press(key)}
              style={({ pressed }) => [
                styles.key,
                { backgroundColor: key === "delete" ? "transparent" : palette.key },
                pressed && styles.pressed,
              ]}
            >
              <Text
                style={[
                  styles.keyText,
                  { color: key === "delete" ? palette.mutedText : palette.keyText },
                  key === "delete" && styles.deleteText,
                ]}
              >
                {key === "delete" ? "⌫" : key}
              </Text>
            </Pressable>
          ),
        )}
      </View>
    </View>
  );
}

function Dot({
  filled,
  color,
  reduceMotion,
}: {
  filled: boolean;
  color: string;
  reduceMotion: boolean;
}) {
  const scale = useRef(new Animated.Value(filled ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      scale.setValue(filled ? 1 : 0);
      return;
    }
    Animated.spring(scale, {
      toValue: filled ? 1 : 0,
      stiffness: 520,
      damping: 16,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [filled, reduceMotion, scale]);

  return (
    <View style={[styles.dot, { borderColor: color }]}>
      <Animated.View
        style={[styles.fill, { backgroundColor: color, transform: [{ scale }], opacity: scale }]}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  root: { alignItems: "center", userSelect: "none" },
  title: { fontSize: 20, fontWeight: "700", marginBottom: 22 },
  dots: { flexDirection: "row", gap: 18, height: 20, alignItems: "center" },
  dot: { width: 18, height: 18, borderRadius: 9, borderWidth: 2, overflow: "hidden" },
  fill: { flex: 1 },
  error: { marginTop: 14, height: 18, fontSize: 13, fontWeight: "600" },
  grid: { width: 264, flexDirection: "row", flexWrap: "wrap", gap: 12, marginTop: 18 },
  key: { width: 80, height: 64, borderRadius: 32, alignItems: "center", justifyContent: "center" },
  keyText: { fontSize: 26, fontWeight: "600" },
  deleteText: { fontSize: 24 },
  pressed: { opacity: 0.6 },
});
```

---

# Flick Toast

> A React Native stack of toasts you flick away, with a countdown line that waits while you hold, older toasts scaled back, and screen reader dismiss.

Install: `npx @modus-ui/cli add flick-toast`

A stack of toasts you flick away. The newest slides in at the front with the older ones scaled back behind it. A thin line counts down the front toast's time and waits while you hold it, and a sideways or toward-the-edge flick sends it off. The host owns the list: remove a toast in `onDismiss`. Each toast is a live region with a dismiss action for screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add flick-toast
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/flick-toast.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, View } from "react-native";
import { FlickToast, type FlickToastItem } from "@/components/ui/flick-toast";

export default function Example() {
  const [toasts, setToasts] = useState<FlickToastItem[]>([]);

  return (
    <View style={{ flex: 1 }}>
      <Button
        title="Save"
        onPress={() =>
          setToasts((all) => [
            ...all,
            { id: String(Date.now()), title: "Changes saved", tone: "success" },
          ])
        }
      />
      <FlickToast
        toasts={toasts}
        onDismiss={(id) => setToasts((all) => all.filter((toast) => toast.id !== id))}
      />
    </View>
  );
}
```

The parent must fill the area the toasts should float over. Only the newest three are drawn; the rest wait their turn.

## Props

| Prop        | Type                        | Default | Description                                                                                           |
| :---------- | :-------------------------- | :------ | :---------------------------------------------------------------------------------------------------- |
| `toasts`    | `FlickToastItem[]`          | -       | The toasts to show, oldest first. Each has an `id`, a `title`, and optional `description` and `tone`. |
| `onDismiss` | `(id: string) => void`      | -       | Called once a toast has left, whether it timed out, was flicked away or dismissed by a screen reader. |
| `duration`  | `number`                    | `4000`  | Milliseconds the front toast stays before it leaves. 0 keeps toasts until they are dismissed.         |
| `position`  | `"top" \| "bottom"`         | `"top"` | Which edge the stack sits against.                                                                    |
| `colors`    | `Partial<FlickToastColors>` | -       | Overrides `surface`, `text`, `mutedText`, `border`, `accent`, `success` and `error`.                  |
| `style`     | `StyleProp<ViewStyle>`      | -       | Style for the overlay that holds the toasts.                                                          |

## Source

`components/ui/flick-toast.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const MAX_VISIBLE = 3;
// Each toast behind the front one sits this much smaller and further from the edge.
const DEPTH_SCALE = 0.05;
const DEPTH_SHIFT = 10;

type Tone = "default" | "success" | "error";
type Exit = "left" | "right" | "edge";

export interface FlickToastItem {
  id: string;
  title: string;
  description?: string;
  tone?: Tone;
}

export interface FlickToastColors {
  surface: string;
  text: string;
  mutedText: string;
  border: string;
  accent: string;
  success: string;
  error: string;
}

const DEFAULT_COLORS: FlickToastColors = {
  surface: "#111827",
  text: "#ffffff",
  mutedText: "#d1d5db",
  border: "rgba(255, 255, 255, 0.12)",
  accent: "#818cf8",
  success: "#22c55e",
  error: "#ef4444",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface FlickToastProps {
  /** The toasts to show, oldest first. The host owns the list: remove a toast in `onDismiss`. */
  toasts: FlickToastItem[];
  /** Called once a toast has left, whether it timed out, was flicked away or dismissed by a screen reader. */
  onDismiss: (id: string) => void;
  /** Milliseconds the front toast stays before it leaves. 0 keeps toasts until they are dismissed. */
  duration?: number;
  /** Which edge the stack sits against. */
  position?: "top" | "bottom";
  colors?: Partial<FlickToastColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A stack of toasts you flick away. The newest slides in at the front with the older ones scaled back
 * behind it, a thin line counts down the front toast's time (and waits while you hold it), and a
 * sideways or toward-the-edge flick sends it off. Draws inside its parent, which must fill the area
 * the toasts should float over. Each toast is a live region with a dismiss action for screen readers.
 */
export function FlickToast({
  toasts,
  onDismiss,
  duration = 4000,
  position = "top",
  colors,
  style,
}: FlickToastProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  // Newest first, so a toast's index is its depth in the stack.
  const visible = toasts.slice(-MAX_VISIBLE).reverse();

  return (
    <View pointerEvents="box-none" style={[styles.root, style]}>
      {/* The front toast is drawn last, so it sits above the rest. */}
      {[...visible].reverse().map((item) => (
        <ToastCard
          key={item.id}
          item={item}
          depth={visible.indexOf(item)}
          position={position}
          duration={duration}
          colors={palette}
          reduceMotion={reduceMotion}
          onDismiss={onDismiss}
        />
      ))}
    </View>
  );
}

interface ToastCardProps {
  item: FlickToastItem;
  depth: number;
  position: "top" | "bottom";
  duration: number;
  colors: FlickToastColors;
  reduceMotion: boolean;
  onDismiss: (id: string) => void;
}

function ToastCard({
  item,
  depth,
  position,
  duration,
  colors,
  reduceMotion,
  onDismiss,
}: ToastCardProps) {
  // -1 when the edge is up (top), 1 when it is down (bottom): the direction "toward the edge".
  const edge = position === "top" ? -1 : 1;
  const enter = useRef(new Animated.Value(reduceMotion ? 1 : 0)).current;
  const stack = useRef(new Animated.Value(depth)).current;
  const fade = useRef(new Animated.Value(1)).current;
  const x = useRef(new Animated.Value(0)).current;
  const y = useRef(new Animated.Value(0)).current;
  // 1 to 0 over `duration`. Driven from JS so its current level can be read when paused.
  const remaining = useRef(new Animated.Value(1)).current;
  const level = useRef(1);
  const size = useRef({ width: 360, height: 72 });
  const leaving = useRef(false);
  const holding = useRef(false);
  const isFront = depth === 0;
  const live = useRef({ duration, edge, reduceMotion, onDismiss, isFront });
  live.current = { duration, edge, reduceMotion, onDismiss, isFront };

  useEffect(() => {
    const id = remaining.addListener(({ value }) => (level.current = value));
    return () => remaining.removeListener(id);
  }, [remaining]);

  useEffect(() => {
    if (!live.current.reduceMotion) {
      Animated.spring(enter, {
        toValue: 1,
        stiffness: 300,
        damping: 24,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
  }, [enter]);

  useEffect(() => {
    if (reduceMotion) {
      stack.setValue(depth);
      return;
    }
    Animated.spring(stack, {
      toValue: depth,
      stiffness: 320,
      damping: 26,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [depth, reduceMotion, stack]);

  const run = () => {
    const total = live.current.duration;
    if (total <= 0 || leaving.current || holding.current) return;
    Animated.timing(remaining, {
      toValue: 0,
      duration: total * level.current,
      easing: Easing.linear,
      useNativeDriver: false,
    }).start(({ finished }) => {
      if (finished) leave("edge");
    });
  };

  const leave = (exit: Exit) => {
    if (leaving.current) return;
    leaving.current = true;
    remaining.stopAnimation();
    const { edge: toward, reduceMotion: reduce, onDismiss: done } = live.current;
    if (reduce) {
      done(item.id);
      return;
    }
    const { width, height } = size.current;
    const move =
      exit === "edge"
        ? Animated.timing(y, {
            toValue: toward * (height + 80),
            duration: 220,
            useNativeDriver: NATIVE_DRIVER,
          })
        : Animated.timing(x, {
            toValue: (exit === "right" ? 1 : -1) * (width + 60),
            duration: 220,
            useNativeDriver: NATIVE_DRIVER,
          });
    Animated.parallel([
      move,
      Animated.timing(fade, { toValue: 0, duration: 220, useNativeDriver: NATIVE_DRIVER }),
    ]).start(() => done(item.id));
  };

  // The countdown belongs to the front toast; one pushed behind keeps the time it has left.
  useEffect(() => {
    if (isFront) run();
    return () => remaining.stopAnimation();
    // run reads everything through refs, so it only needs to start when the toast reaches the front.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [isFront, duration]);

  const springBack = () => {
    holding.current = false;
    if (live.current.reduceMotion) {
      x.setValue(0);
      y.setValue(0);
    } else {
      const back = (value: Animated.Value) =>
        Animated.spring(value, {
          toValue: 0,
          stiffness: 360,
          damping: 28,
          mass: 1,
          useNativeDriver: NATIVE_DRIVER,
        });
      Animated.parallel([back(x), back(y)]).start();
    }
    if (live.current.isFront) run();
  };

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onMoveShouldSetPanResponder: () => true,
      onPanResponderGrant: () => {
        // Holding a toast stops its clock.
        holding.current = true;
        remaining.stopAnimation();
        x.stopAnimation();
        y.stopAnimation();
      },
      onPanResponderMove: (_, g) => {
        x.setValue(g.dx);
        // Toward the edge it follows the finger; the other way it resists.
        y.setValue(g.dy * live.current.edge > 0 ? g.dy : g.dy / 5);
      },
      onPanResponderRelease: (_, g) => {
        const toward = g.dy * live.current.edge;
        const towardSpeed = g.vy * live.current.edge;
        const sideways = Math.abs(g.dx) > 90 || (Math.abs(g.vx) > 0.8 && g.dx * g.vx > 0);
        if (sideways) {
          holding.current = false;
          leave(g.dx > 0 ? "right" : "left");
        } else if (toward > 40 || towardSpeed > 0.7) {
          holding.current = false;
          leave("edge");
        } else {
          springBack();
        }
      },
      onPanResponderTerminate: () => springBack(),
    }),
  ).current;

  const tone = item.tone ?? "default";
  const toneColor =
    tone === "success" ? colors.success : tone === "error" ? colors.error : colors.accent;

  const enterShift = enter.interpolate({ inputRange: [0, 1], outputRange: [edge * 28, 0] });
  const stackShift = stack.interpolate({
    inputRange: [0, 1, 2],
    outputRange: [0, -edge * DEPTH_SHIFT, -edge * DEPTH_SHIFT * 2],
  });
  const scale = stack.interpolate({
    inputRange: [0, 1, 2],
    outputRange: [1, 1 - DEPTH_SCALE, 1 - DEPTH_SCALE * 2],
  });
  const stackOpacity = stack.interpolate({ inputRange: [0, 1, 2], outputRange: [1, 0.85, 0.7] });
  const tilt = reduceMotion
    ? "0deg"
    : x.interpolate({ inputRange: [-300, 0, 300], outputRange: ["-6deg", "0deg", "6deg"] });

  return (
    <Animated.View
      {...pan.panHandlers}
      accessible
      accessibilityRole="alert"
      accessibilityLiveRegion={tone === "error" ? "assertive" : "polite"}
      accessibilityLabel={item.description ? `${item.title}. ${item.description}` : item.title}
      accessibilityActions={[{ name: "dismiss", label: "Dismiss" }]}
      onAccessibilityAction={() => leave("edge")}
      onLayout={(event: LayoutChangeEvent) => (size.current = event.nativeEvent.layout)}
      pointerEvents={isFront ? "auto" : "none"}
      style={[
        styles.card,
        position === "top" ? styles.atTop : styles.atBottom,
        {
          backgroundColor: colors.surface,
          borderColor: colors.border,
          opacity: Animated.multiply(Animated.multiply(enter, stackOpacity), fade),
          transform: [
            { translateX: x },
            { translateY: Animated.add(Animated.add(enterShift, stackShift), y) },
            { rotate: tilt },
            { scale },
          ],
        },
      ]}
    >
      <View style={styles.row}>
        <View style={[styles.dot, { backgroundColor: toneColor }]} />
        <View style={styles.copy}>
          <Text numberOfLines={1} style={[styles.title, { color: colors.text }]}>
            {item.title}
          </Text>
          {item.description ? (
            <Text numberOfLines={2} style={[styles.description, { color: colors.mutedText }]}>
              {item.description}
            </Text>
          ) : null}
        </View>
      </View>
      {duration > 0 ? (
        <View pointerEvents="none" style={styles.track}>
          <Animated.View
            style={[
              styles.line,
              { backgroundColor: toneColor, transform: [{ scaleX: remaining }] },
            ]}
          />
        </View>
      ) : null}
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  root: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  // userSelect keeps a mouse drag on the web from selecting the text instead of moving the toast.
  card: {
    position: "absolute",
    left: 16,
    right: 16,
    borderRadius: 16,
    borderWidth: 1,
    overflow: "hidden",
    userSelect: "none",
    boxShadow: "0 10px 28px rgba(0, 0, 0, 0.28)",
  },
  atTop: { top: 16 },
  atBottom: { bottom: 16 },
  row: {
    flexDirection: "row",
    alignItems: "flex-start",
    gap: 12,
    paddingHorizontal: 16,
    paddingVertical: 14,
  },
  dot: { width: 8, height: 8, borderRadius: 4, marginTop: 6 },
  copy: { flex: 1, gap: 2 },
  title: { fontSize: 15, fontWeight: "600" },
  description: { fontSize: 13, lineHeight: 18 },
  track: { height: 3, width: "100%" },
  line: { height: 3, width: "100%", transformOrigin: "left", opacity: 0.9 },
});
```

---

# Fold Panel

> A React Native accordion whose panels grow to the measured height of their content, with a turning chevron and screen reader state.

Install: `npx @modus-ui/cli add fold-panel`

An accordion whose panels grow to exactly the height of their content, measured rather than guessed, so any content works. The chevron turns as a panel opens, and every header is a button that tells screen readers whether it is expanded. Closed panels are hidden from them. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add fold-panel
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/fold-panel.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text } from "react-native";
import { FoldPanel } from "@/components/ui/fold-panel";

export default function Example() {
  return (
    <FoldPanel
      defaultOpen={["shipping"]}
      items={[
        {
          id: "shipping",
          title: "How long does shipping take?",
          content: <Text>Three to five working days.</Text>,
        },
        {
          id: "returns",
          title: "Can I return an item?",
          content: <Text>Yes, within 30 days.</Text>,
        },
      ]}
    />
  );
}
```

## Props

| Prop          | Type                       | Default | Description                                                                            |
| :------------ | :------------------------- | :------ | :------------------------------------------------------------------------------------- |
| `items`       | `FoldPanelItem[]`          | -       | The panels. Each has an `id`, a `title` and its `content`.                             |
| `multiple`    | `boolean`                  | `false` | Whether several panels can be open at once. When false, opening one closes the others. |
| `defaultOpen` | `string[]`                 | `[]`    | Ids of the panels that start open.                                                     |
| `colors`      | `Partial<FoldPanelColors>` | -       | Overrides `surface`, `text`, `mutedText` and `border`.                                 |
| `style`       | `StyleProp<ViewStyle>`     | -       | Style for the panel container.                                                         |

## Source

`components/ui/fold-panel.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface FoldPanelItem {
  id: string;
  title: string;
  content: ReactNode;
}

export interface FoldPanelColors {
  surface: string;
  text: string;
  mutedText: string;
  border: string;
}

const DEFAULT_COLORS: FoldPanelColors = {
  surface: "#ffffff",
  text: "#111827",
  mutedText: "#6b7280",
  border: "#e5e7eb",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface FoldPanelProps {
  items: FoldPanelItem[];
  /** Whether several panels can be open at once. When false, opening one closes the others. */
  multiple?: boolean;
  /** Ids of the panels that start open. */
  defaultOpen?: string[];
  colors?: Partial<FoldPanelColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * An accordion whose panels grow to exactly the height of their content, measured rather than
 * guessed, so any content works. The chevron turns as a panel opens, and every header is a button
 * that tells screen readers whether it is expanded. Closed panels are hidden from them.
 */
export function FoldPanel({
  items,
  multiple = false,
  defaultOpen = [],
  colors,
  style,
}: FoldPanelProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [open, setOpen] = useState<string[]>(defaultOpen);

  const toggle = (id: string) =>
    setOpen((current) =>
      current.includes(id)
        ? current.filter((value) => value !== id)
        : multiple
          ? [...current, id]
          : [id],
    );

  return (
    <View
      style={[
        styles.root,
        { backgroundColor: palette.surface, borderColor: palette.border },
        style,
      ]}
    >
      {items.map((item, index) => (
        <FoldRow
          key={item.id}
          item={item}
          open={open.includes(item.id)}
          last={index === items.length - 1}
          colors={palette}
          reduceMotion={reduceMotion}
          onToggle={() => toggle(item.id)}
        />
      ))}
    </View>
  );
}

interface FoldRowProps {
  item: FoldPanelItem;
  open: boolean;
  last: boolean;
  colors: FoldPanelColors;
  reduceMotion: boolean;
  onToggle: () => void;
}

function FoldRow({ item, open, last, colors, reduceMotion, onToggle }: FoldRowProps) {
  const [measured, setMeasured] = useState(0);
  // Height can't use the native driver, so it gets its own value; the turn and fade ride the native one.
  const height = useRef(new Animated.Value(0)).current;
  const turn = useRef(new Animated.Value(open ? 1 : 0)).current;
  const placed = useRef(false);

  useEffect(() => {
    const target = open ? measured : 0;
    // The first measurement sets the height outright, so a panel that starts open does not animate in.
    if (!placed.current) {
      if (measured === 0) return;
      placed.current = true;
      height.setValue(target);
      return;
    }
    if (reduceMotion) {
      height.setValue(target);
      return;
    }
    Animated.timing(height, {
      toValue: target,
      duration: 260,
      useNativeDriver: false,
    }).start();
  }, [open, measured, reduceMotion, height]);

  useEffect(() => {
    if (reduceMotion) {
      turn.setValue(open ? 1 : 0);
      return;
    }
    Animated.spring(turn, {
      toValue: open ? 1 : 0,
      stiffness: 300,
      damping: 26,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [open, reduceMotion, turn]);

  return (
    <View style={!last && { borderBottomWidth: 1, borderBottomColor: colors.border }}>
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={item.title}
        accessibilityState={{ expanded: open }}
        aria-expanded={open}
        onPress={onToggle}
        style={({ pressed }) => [styles.header, pressed && styles.pressed]}
      >
        <Text style={[styles.title, { color: colors.text }]}>{item.title}</Text>
        <Animated.View
          style={[
            styles.chevron,
            {
              borderColor: colors.mutedText,
              transform: [
                {
                  rotate: turn.interpolate({
                    inputRange: [0, 1],
                    outputRange: ["45deg", "225deg"],
                  }),
                },
              ],
            },
          ]}
        />
      </Pressable>
      <Animated.View style={[styles.clip, { height }]}>
        <Animated.View
          accessibilityElementsHidden={!open}
          importantForAccessibility={open ? "auto" : "no-hide-descendants"}
          aria-hidden={!open}
          pointerEvents={open ? "auto" : "none"}
          onLayout={(event: LayoutChangeEvent) => setMeasured(event.nativeEvent.layout.height)}
          style={[styles.body, { opacity: turn }]}
        >
          {item.content}
        </Animated.View>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { borderWidth: 1, borderRadius: 18, overflow: "hidden" },
  header: {
    minHeight: 56,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    gap: 12,
    paddingHorizontal: 18,
    paddingVertical: 12,
  },
  pressed: { opacity: 0.7 },
  title: { flex: 1, fontSize: 16, fontWeight: "600" },
  chevron: {
    width: 9,
    height: 9,
    marginBottom: 3,
    borderRightWidth: 2,
    borderBottomWidth: 2,
  },
  clip: { overflow: "hidden" },
  // Absolute so the body lays out at its natural height, whatever height the clip is animating to.
  body: {
    position: "absolute",
    top: 0,
    left: 0,
    right: 0,
    paddingHorizontal: 18,
    paddingBottom: 18,
  },
});
```

---

# Snap Carousel

> A React Native carousel that settles on one card at a time, with neighbors that shrink and fade and dots that stretch to follow.

Install: `npx @modus-ui/cli add snap-carousel`

A horizontal carousel that settles on one card at a time. The centered card is full size and opaque, its neighbors shrink and fade with the scroll position, and the dots below stretch to follow. Tap a dot or a neighboring card to go there. The dots row doubles as an adjustable control for screen readers, and on desktop the cards can be dragged with a mouse. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add snap-carousel
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/snap-carousel.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text } from "react-native";
import { SnapCarousel } from "@/components/ui/snap-carousel";

const places = [
  { id: "ridge", name: "Ridge Cabin" },
  { id: "harbor", name: "Harbor Loft" },
  { id: "orchard", name: "Orchard House" },
];

export default function Example() {
  return (
    <SnapCarousel
      data={places}
      keyExtractor={(place) => place.id}
      renderItem={(place) => <Text style={{ padding: 24, fontSize: 20 }}>{place.name}</Text>}
      onIndexChange={(index) => console.log(index)}
    />
  );
}
```

The carousel is as wide as its parent and as tall as its tallest card. Give the cards a background, since the carousel draws none.

## Props

| Prop            | Type                                    | Default | Description                                                                |
| :-------------- | :-------------------------------------- | :------ | :------------------------------------------------------------------------- |
| `data`          | `T[]`                                   | -       | The items to show.                                                         |
| `renderItem`    | `(item: T, index: number) => ReactNode` | -       | Renders a card's content. The carousel sizes and animates the card itself. |
| `keyExtractor`  | `(item: T, index: number) => string`    | -       | A stable key for each item.                                                |
| `itemWidth`     | `number`                                | `0.72`  | Card width as a fraction of the carousel's width.                          |
| `gap`           | `number`                                | `12`    | Space between cards.                                                       |
| `onIndexChange` | `(index: number) => void`               | -       | Called when a different card becomes the centered one.                     |
| `initialIndex`  | `number`                                | `0`     | Index of the card centered at first.                                       |
| `showDots`      | `boolean`                               | `true`  | Whether to draw the dots under the cards.                                  |
| `colors`        | `Partial<SnapCarouselColors>`           | -       | Overrides `dot` and `activeDot`.                                           |
| `style`         | `StyleProp<ViewStyle>`                  | -       | Style for the carousel container.                                          |

## Source

`components/ui/snap-carousel.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  PanResponder,
  Pressable,
  StyleSheet,
  View,
  type LayoutChangeEvent,
  type NativeScrollEvent,
  type NativeSyntheticEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

// The one method used from the scroll view's instance.
type Scroller = { scrollTo: (options: { x: number; animated?: boolean }) => void };
// How small and faint the cards beside the centered one are drawn.
const SIDE_SCALE = 0.88;
const SIDE_OPACITY = 0.55;
const DOT = 8;
const DOT_ACTIVE = 22;

export interface SnapCarouselColors {
  dot: string;
  activeDot: string;
}

const DEFAULT_COLORS: SnapCarouselColors = {
  dot: "#d1d5db",
  activeDot: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SnapCarouselProps<T> {
  data: T[];
  /** Renders a card's content. The carousel sizes and animates the card itself. */
  renderItem: (item: T, index: number) => ReactNode;
  keyExtractor: (item: T, index: number) => string;
  /** Card width as a fraction of the carousel's width. */
  itemWidth?: number;
  /** Space between cards. */
  gap?: number;
  /** Called when a different card becomes the centered one. */
  onIndexChange?: (index: number) => void;
  /** Index of the card centered at first. */
  initialIndex?: number;
  /** Whether to draw the dots under the cards. */
  showDots?: boolean;
  colors?: Partial<SnapCarouselColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A horizontal carousel that settles on one card at a time. The centered card is full size and
 * opaque, its neighbors shrink and fade with the scroll position, and the dots below stretch to
 * follow. Tap a dot or a neighboring card to go there. The dots row doubles as an adjustable
 * control for screen readers, and on desktop the cards can be dragged with a mouse.
 */
export function SnapCarousel<T>({
  data,
  renderItem,
  keyExtractor,
  itemWidth = 0.72,
  gap = 12,
  onIndexChange,
  initialIndex = 0,
  showDots = true,
  colors,
  style,
}: SnapCarouselProps<T>) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const [index, setIndex] = useState(initialIndex);
  const scroll = useRef<Scroller>(null);
  const x = useRef(new Animated.Value(0)).current;
  const offset = useRef(0);
  const current = useRef(initialIndex);
  // True during a mouse drag and for a moment after it: the click a mouse sends on release is not a tap.
  const dragging = useRef(false);
  const dragStart = useRef(0);

  const card = width * itemWidth;
  const step = card + gap;
  const side = (width - card) / 2;
  const last = data.length - 1;

  const live = useRef({ step, last, reduceMotion, onIndexChange });
  live.current = { step, last, reduceMotion, onIndexChange };

  const goTo = (target: number, animated = !live.current.reduceMotion) => {
    const clamped = Math.max(0, Math.min(live.current.last, target));
    scroll.current?.scrollTo({ x: clamped * live.current.step, animated });
  };

  // Put the initial card in the middle once the width is known.
  useEffect(() => {
    if (step <= 0) return;
    const start = Math.max(0, Math.min(last, initialIndex)) * step;
    x.setValue(start);
    offset.current = start;
    scroll.current?.scrollTo({ x: start, animated: false });
    // Only the first measurement positions the carousel.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [step > 0]);

  const track = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
    const next = Math.max(
      0,
      Math.min(
        live.current.last,
        Math.round(event.nativeEvent.contentOffset.x / live.current.step),
      ),
    );
    offset.current = event.nativeEvent.contentOffset.x;
    if (next !== current.current) {
      current.current = next;
      setIndex(next);
      live.current.onIndexChange?.(next);
      AccessibilityInfo.announceForAccessibility(`Item ${next + 1} of ${live.current.last + 1}`);
    }
  };

  // A mouse cannot drag a scroll view, so on desktop browsers the cards are dragged by hand.
  const mouseDrag = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        Platform.OS === "web" &&
        typeof window !== "undefined" &&
        window.matchMedia("(pointer: fine)").matches &&
        Math.abs(g.dx) > 6 &&
        Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => {
        dragging.current = true;
        dragStart.current = offset.current;
      },
      onPanResponderMove: (_, g) => {
        scroll.current?.scrollTo({ x: dragStart.current - g.dx, animated: false });
      },
      onPanResponderRelease: (_, g) => {
        setTimeout(() => (dragging.current = false), 80);
        // Carry a flick on to the next card, otherwise settle on the nearest one.
        const projected = offset.current - g.vx * 160;
        goTo(Math.round(projected / live.current.step));
      },
      onPanResponderTerminate: () => {
        setTimeout(() => (dragging.current = false), 80);
        goTo(Math.round(offset.current / live.current.step));
      },
    }),
  ).current;

  return (
    <View
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={[styles.root, style]}
    >
      {width > 0 ? (
        <View {...mouseDrag.panHandlers} style={styles.drag}>
          <Animated.ScrollView
            ref={scroll as never}
            horizontal
            snapToInterval={step}
            decelerationRate="fast"
            showsHorizontalScrollIndicator={false}
            scrollEventThrottle={16}
            onScroll={Animated.event([{ nativeEvent: { contentOffset: { x } } }], {
              useNativeDriver: NATIVE_DRIVER,
              listener: track,
            })}
            contentContainerStyle={{ paddingHorizontal: side }}
          >
            {data.map((item, i) => {
              const range = [(i - 1) * step, i * step, (i + 1) * step];
              return (
                <Animated.View
                  key={keyExtractor(item, i)}
                  style={{
                    width: card,
                    marginRight: i < last ? gap : 0,
                    opacity: x.interpolate({
                      inputRange: range,
                      outputRange: [SIDE_OPACITY, 1, SIDE_OPACITY],
                      extrapolate: "clamp",
                    }),
                    transform: [
                      {
                        scale: x.interpolate({
                          inputRange: range,
                          outputRange: [SIDE_SCALE, 1, SIDE_SCALE],
                          extrapolate: "clamp",
                        }),
                      },
                    ],
                  }}
                >
                  <Pressable
                    accessible={false}
                    disabled={i === index}
                    onPress={() => {
                      if (!dragging.current) goTo(i);
                    }}
                    style={styles.card}
                  >
                    <View pointerEvents={i === index ? "auto" : "none"} style={styles.card}>
                      {renderItem(item, i)}
                    </View>
                  </Pressable>
                </Animated.View>
              );
            })}
          </Animated.ScrollView>
        </View>
      ) : null}
      <View
        accessible
        accessibilityRole="adjustable"
        accessibilityLabel="Carousel"
        accessibilityValue={{ text: `Item ${index + 1} of ${data.length}` }}
        aria-valuetext={`Item ${index + 1} of ${data.length}`}
        accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
        onAccessibilityAction={(event) =>
          goTo(index + (event.nativeEvent.actionName === "increment" ? 1 : -1))
        }
        style={showDots ? styles.dots : styles.noDots}
      >
        {showDots
          ? data.map((item, i) => (
              <Dot
                key={keyExtractor(item, i)}
                active={i === index}
                colors={palette}
                reduceMotion={reduceMotion}
                onPress={() => goTo(i)}
              />
            ))
          : null}
      </View>
    </View>
  );
}

function Dot({
  active,
  colors,
  reduceMotion,
  onPress,
}: {
  active: boolean;
  colors: SnapCarouselColors;
  reduceMotion: boolean;
  onPress: () => void;
}) {
  const size = useRef(new Animated.Value(active ? DOT_ACTIVE : DOT)).current;

  useEffect(() => {
    const target = active ? DOT_ACTIVE : DOT;
    if (reduceMotion) {
      size.setValue(target);
      return;
    }
    // Width is not supported by the native driver, so the dots run on the JS thread.
    Animated.spring(size, {
      toValue: target,
      stiffness: 360,
      damping: 24,
      mass: 1,
      useNativeDriver: false,
    }).start();
  }, [active, reduceMotion, size]);

  return (
    <Pressable accessible={false} hitSlop={8} onPress={onPress}>
      <Animated.View
        style={[
          styles.dot,
          { width: size, backgroundColor: active ? colors.activeDot : colors.dot },
        ]}
      />
    </Pressable>
  );
}

const styles = StyleSheet.create({
  root: { width: "100%" },
  // userSelect keeps a mouse drag on the web from selecting the cards' text instead of moving them.
  drag: { width: "100%", userSelect: "none" },
  card: { flex: 1 },
  dots: {
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "center",
    gap: 6,
    paddingTop: 14,
    height: 30,
  },
  noDots: { height: 0 },
  dot: { height: DOT, borderRadius: DOT / 2 },
});
```

---

# Slide Switch

> A React Native switch whose thumb can be dragged as well as tapped, stretching while held and settling on the nearer side.

Install: `npx @modus-ui/cli add slide-switch`

A switch whose thumb can be dragged as well as tapped. It stretches while held, follows the finger, and settles on whichever side it is nearer to (a flick decides it sooner). The track cross-fades between the two colors, and screen readers get a standard switch with its state. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add slide-switch
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/slide-switch.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { SlideSwitch } from "@/components/ui/slide-switch";

export default function Example() {
  const [enabled, setEnabled] = useState(false);

  return <SlideSwitch label="Notifications" value={enabled} onValueChange={setEnabled} />;
}
```

The switch is controlled: it shows `value`, and a tap or drag calls `onValueChange` with the new one. Update `value` there to accept the change.

## Props

| Prop            | Type                         | Default | Description                                          |
| :-------------- | :--------------------------- | :------ | :--------------------------------------------------- |
| `value`         | `boolean`                    | -       | Whether the switch is on.                            |
| `onValueChange` | `(value: boolean) => void`   | -       | Called with the new value after a tap or a drag.     |
| `disabled`      | `boolean`                    | `false` | Dims the switch and ignores touches.                 |
| `size`          | `number`                     | `32`    | Height of the track. The track is 1.8 times as wide. |
| `label`         | `string`                     | -       | Spoken name of the switch.                           |
| `colors`        | `Partial<SlideSwitchColors>` | -       | Overrides `off`, `on` and `thumb`.                   |
| `style`         | `StyleProp<ViewStyle>`       | -       | Style for the switch's container.                    |

## Source

`components/ui/slide-switch.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Pressable,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const PADDING = 3;

export interface SlideSwitchColors {
  off: string;
  on: string;
  thumb: string;
}

const DEFAULT_COLORS: SlideSwitchColors = {
  off: "#d1d5db",
  on: "#4f46e5",
  thumb: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SlideSwitchProps {
  value: boolean;
  onValueChange: (value: boolean) => void;
  /** Dims the switch and ignores touches. */
  disabled?: boolean;
  /** Height of the track. The track is 1.8 times as wide. */
  size?: number;
  /** Spoken name of the switch. */
  label?: string;
  colors?: Partial<SlideSwitchColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A switch whose thumb can be dragged as well as tapped. It stretches while held, follows the
 * finger, and settles on whichever side it is nearer to (a flick decides it sooner). The track
 * cross-fades between the two colors, and screen readers get a standard switch with its state.
 */
export function SlideSwitch({
  value,
  onValueChange,
  disabled = false,
  size = 32,
  label,
  colors,
  style,
}: SlideSwitchProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  const trackWidth = size * 1.8;
  const thumb = size - PADDING * 2;
  const stretch = thumb * 0.28;
  // Space the thumb can travel; less while it is stretched, so it never leaves the track.
  const travel = trackWidth - PADDING * 2 - thumb;

  // 0 is off, 1 is on, and anything between is mid-drag.
  const pos = useRef(new Animated.Value(value ? 1 : 0)).current;
  const grow = useRef(new Animated.Value(0)).current;
  const posNow = useRef(value ? 1 : 0);
  const pressed = useRef(false);
  const dragging = useRef(false);
  const dragStart = useRef(0);

  const live = useRef({ value, disabled, travel, reduceMotion, onValueChange });
  live.current = { value, disabled, travel, reduceMotion, onValueChange };

  useEffect(() => {
    const id = pos.addListener(({ value: next }) => (posNow.current = next));
    return () => pos.removeListener(id);
  }, [pos]);

  const animate = (node: Animated.Value, toValue: number) => {
    if (live.current.reduceMotion) {
      node.setValue(toValue);
      return;
    }
    // Width and colors are not supported by the native driver, so the switch runs on the JS thread.
    Animated.spring(node, {
      toValue,
      stiffness: 520,
      damping: 30,
      mass: 1,
      useNativeDriver: false,
    }).start();
  };

  const syncGrow = () => animate(grow, pressed.current || dragging.current ? 1 : 0);

  // Follow the value when the parent changes it (and settle after a drag the parent accepted).
  useEffect(() => {
    if (!dragging.current) animate(pos, value ? 1 : 0);
    // animate reads everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [value, reduceMotion]);

  const pan = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        !live.current.disabled && Math.abs(g.dx) > 3 && Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => {
        dragging.current = true;
        dragStart.current = posNow.current;
        syncGrow();
      },
      onPanResponderMove: (_, g) => {
        pos.setValue(Math.max(0, Math.min(1, dragStart.current + g.dx / live.current.travel)));
      },
      onPanResponderRelease: (_, g) => {
        // A flick decides at once; a slow drag goes to the nearer side.
        const next = Math.abs(g.vx) > 0.3 ? g.vx > 0 : posNow.current > 0.5;
        // The click a mouse sends on release is not a tap, so keep dragging set a moment longer.
        setTimeout(() => (dragging.current = false), 80);
        animate(pos, next ? 1 : 0);
        syncGrow();
        if (next !== live.current.value) live.current.onValueChange(next);
      },
      onPanResponderTerminate: () => {
        setTimeout(() => (dragging.current = false), 80);
        animate(pos, live.current.value ? 1 : 0);
        syncGrow();
      },
    }),
  ).current;

  const thumbWidth = grow.interpolate({
    inputRange: [0, 1],
    outputRange: [thumb, thumb + stretch],
  });
  const room = grow.interpolate({ inputRange: [0, 1], outputRange: [travel, travel - stretch] });

  return (
    <View {...pan.panHandlers} style={[styles.root, { opacity: disabled ? 0.5 : 1 }, style]}>
      <Pressable
        accessibilityRole="switch"
        accessibilityLabel={label}
        accessibilityState={{ checked: value, disabled }}
        aria-checked={value}
        aria-label={label}
        disabled={disabled}
        onPress={() => {
          if (!dragging.current) onValueChange(!value);
        }}
        onPressIn={() => {
          pressed.current = true;
          syncGrow();
        }}
        onPressOut={() => {
          pressed.current = false;
          syncGrow();
        }}
        style={[
          styles.track,
          { width: trackWidth, height: size, borderRadius: size / 2, backgroundColor: palette.off },
        ]}
      >
        <Animated.View
          pointerEvents="none"
          style={[
            styles.fill,
            { borderRadius: size / 2, backgroundColor: palette.on, opacity: pos },
          ]}
        />
        <Animated.View
          pointerEvents="none"
          style={[
            styles.thumb,
            {
              top: PADDING,
              left: PADDING,
              width: thumbWidth,
              height: thumb,
              borderRadius: thumb / 2,
              backgroundColor: palette.thumb,
              transform: [{ translateX: Animated.multiply(pos, room) }],
            },
          ]}
        />
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  // userSelect keeps a mouse drag on the web from selecting text instead of moving the thumb.
  root: { alignSelf: "flex-start", userSelect: "none" },
  track: { overflow: "hidden" },
  fill: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  thumb: { position: "absolute", boxShadow: "0 1px 3px rgba(0, 0, 0, 0.3)" },
});
```

---

# Shimmer Block

> A React Native loading placeholder with a soft highlight that sweeps across it, stacked lines that shimmer together, and one spoken "Loading" for the whole block.

Install: `npx @modus-ui/cli add shimmer-block`

A loading placeholder with a soft highlight that sweeps across it. Ask for several `lines` and they sweep in step, with the last one shorter like the end of a paragraph. Screen readers hear a single "Loading" for the whole block, or nothing at all when the block is `decorative` and its parent already announces the wait. With reduced motion the block stays still. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add shimmer-block
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/shimmer-block.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { View } from "react-native";
import { ShimmerBlock } from "@/components/ui/shimmer-block";

export default function Example({
  loading,
  children,
}: {
  loading: boolean;
  children: React.ReactNode;
}) {
  if (!loading) return <>{children}</>;

  return (
    <View style={{ gap: 16 }}>
      <ShimmerBlock height={20} width="50%" />
      <ShimmerBlock lines={3} height={12} />
    </View>
  );
}
```

When several blocks sit inside one parent that already announces "Loading", mark each block `decorative` so a screen reader does not read the wait once per block.

## Props

| Prop         | Type                          | Default  | Description                                                                                             |
| :----------- | :---------------------------- | :------- | :------------------------------------------------------------------------------------------------------ |
| `width`      | `DimensionValue`              | `"100%"` | Width of the block, or of the whole stack when `lines` is more than 1.                                  |
| `height`     | `number`                      | `16`     | Height of each line.                                                                                    |
| `radius`     | `number`                      | `8`      | Corner radius of each line.                                                                             |
| `lines`      | `number`                      | `1`      | How many stacked lines to draw. The last of several is shorter, like the end of a paragraph.            |
| `duration`   | `number`                      | `1400`   | Time for the highlight to cross the block, in milliseconds.                                             |
| `decorative` | `boolean`                     | `false`  | Hide the block from screen readers. Use it for blocks inside a parent that already announces "Loading". |
| `colors`     | `Partial<ShimmerBlockColors>` | -        | Overrides `base` (the block) and `highlight` (the sweeping band).                                       |
| `style`      | `StyleProp<ViewStyle>`        | -        | Style for the block, or for the stack of lines.                                                         |

## Source

`components/ui/shimmer-block.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  View,
  type DimensionValue,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const GAP = 10;

// Opacity of each strip across the highlight band: a smooth bell, so the band has soft edges.
const STRIPS = 13;
const BELL = Array.from(
  { length: STRIPS },
  (_, i) => 0.75 * Math.sin((Math.PI * (i + 0.5)) / STRIPS) ** 2,
);

export interface ShimmerBlockColors {
  base: string;
  highlight: string;
}

const DEFAULT_COLORS: ShimmerBlockColors = {
  base: "#e5e7eb",
  highlight: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ShimmerBlockProps {
  /** Width of the block, or of the whole stack when `lines` is more than 1. */
  width?: DimensionValue;
  /** Height of each line. */
  height?: number;
  radius?: number;
  /** How many stacked lines to draw. The last of several is shorter, like the end of a paragraph. */
  lines?: number;
  /** Time for the highlight to cross the block, in milliseconds. */
  duration?: number;
  /** Hide the block from screen readers. Use it for blocks inside a parent that already announces "Loading". */
  decorative?: boolean;
  colors?: Partial<ShimmerBlockColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A loading placeholder with a soft highlight that sweeps across it. The lines of a stack start
 * together and take the same time, so they shimmer in step. Screen readers hear a single "Loading"
 * for the whole block, or
 * nothing when it is `decorative`; with reduced motion the block stays still.
 */
export function ShimmerBlock({
  width = "100%",
  height = 16,
  radius = 8,
  lines = 1,
  duration = 1400,
  decorative = false,
  colors,
  style,
}: ShimmerBlockProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  const count = Math.max(1, Math.floor(lines));

  return (
    <View
      accessible={!decorative}
      accessibilityRole={decorative ? undefined : "progressbar"}
      accessibilityLabel={decorative ? undefined : "Loading"}
      accessibilityState={decorative ? undefined : { busy: true }}
      aria-hidden={decorative || undefined}
      importantForAccessibility={decorative ? "no-hide-descendants" : "auto"}
      style={[{ width, gap: GAP }, style]}
    >
      {Array.from({ length: count }, (_, i) => (
        <Line
          key={i}
          animated={!reduceMotion}
          duration={duration}
          width={count > 1 && i === count - 1 ? "60%" : "100%"}
          height={height}
          radius={radius}
          colors={palette}
        />
      ))}
    </View>
  );
}

function Line({
  animated,
  duration,
  width,
  height,
  radius,
  colors,
}: {
  animated: boolean;
  duration: number;
  width: DimensionValue;
  height: number;
  radius: number;
  colors: ShimmerBlockColors;
}) {
  const [measured, setMeasured] = useState(0);
  const band = Math.max(96, measured * 0.5);
  // The band is moved by its own value, not an interpolation made during render, and its style is
  // memoized below: react-native-web detaches a value whose animated props are rebuilt, and that
  // stops the animation.
  const translateX = useRef(new Animated.Value(0)).current;

  const bandStyle = useMemo(
    () => [styles.band, { width: band, transform: [{ translateX }] }],
    [band, translateX],
  );

  useEffect(() => {
    if (!animated || measured === 0) return;
    translateX.setValue(-band);
    const loop = Animated.loop(
      Animated.timing(translateX, {
        toValue: measured,
        duration,
        easing: Easing.inOut(Easing.quad),
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [animated, band, duration, measured, translateX]);

  return (
    <View
      aria-hidden
      onLayout={(event: LayoutChangeEvent) => setMeasured(event.nativeEvent.layout.width)}
      style={[styles.line, { width, height, borderRadius: radius, backgroundColor: colors.base }]}
    >
      {animated ? (
        <Animated.View pointerEvents="none" style={bandStyle}>
          {BELL.map((opacity, i) => (
            <View key={i} style={{ flex: 1, backgroundColor: colors.highlight, opacity }} />
          ))}
        </Animated.View>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  line: { overflow: "hidden" },
  band: { position: "absolute", top: 0, bottom: 0, left: 0, flexDirection: "row" },
});
```

---

# Parallax Header

> A React Native scroll view whose hero stretches on overscroll, drifts at half speed, and collapses into a compact title bar.

Install: `npx @modus-ui/cli add parallax-header`

A scroll view with a hero that stretches when pulled past the top, drifts at half speed as you scroll, and ends as a compact bar whose title fades in. The content slides over the hero, so give the hero a full-bleed background. With reduced motion the hero scrolls with the content and the bar simply appears once it is covered. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add parallax-header
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/parallax-header.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text, View } from "react-native";
import { ParallaxHeader } from "@/components/ui/parallax-header";

export default function Example() {
  return (
    <ParallaxHeader
      title="Coastal Trails"
      header={<View style={{ flex: 1, backgroundColor: "#2f7fb8" }} />}
    >
      <Text style={{ padding: 20 }}>Scrolling content goes here.</Text>
    </ParallaxHeader>
  );
}
```

The component fills its parent, so give the parent a height (a screen with `flex: 1` is enough).

## Props

| Prop              | Type                            | Default | Description                                                                 |
| :---------------- | :------------------------------ | :------ | :-------------------------------------------------------------------------- |
| `header`          | `ReactNode`                     | -       | The hero's content. It fills the hero, so give it a background or an image. |
| `headerHeight`    | `number`                        | `220`   | Height of the hero before any scrolling.                                    |
| `collapsedHeight` | `number`                        | `56`    | Height of the bar the hero collapses into.                                  |
| `title`           | `string`                        | -       | Shown in the collapsed bar.                                                 |
| `colors`          | `Partial<ParallaxHeaderColors>` | -       | Overrides `background`, `bar`, `title` and `border`.                        |
| `style`           | `StyleProp<ViewStyle>`          | -       | Style for the container.                                                    |

## Source

`components/ui/parallax-header.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface ParallaxHeaderColors {
  background: string;
  bar: string;
  title: string;
  border: string;
}

const DEFAULT_COLORS: ParallaxHeaderColors = {
  background: "#ffffff",
  bar: "#ffffff",
  title: "#111827",
  border: "#e5e7eb",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ParallaxHeaderProps {
  /** The hero's content. It fills the hero, so give it a background or an image. */
  header: ReactNode;
  /** The scrolling content. */
  children: ReactNode;
  /** Height of the hero before any scrolling. */
  headerHeight?: number;
  /** Height of the bar the hero collapses into. */
  collapsedHeight?: number;
  /** Shown in the collapsed bar. */
  title?: string;
  colors?: Partial<ParallaxHeaderColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A scroll view with a hero that stretches when pulled past the top, drifts at half speed as you
 * scroll, and ends as a compact bar whose title fades in. The content slides over the hero, so give
 * the hero a full-bleed background. With reduced motion the hero scrolls with the content and the
 * bar simply appears once it is covered.
 */
export function ParallaxHeader({
  header,
  children,
  headerHeight = 220,
  collapsedHeight = 56,
  title,
  colors,
  style,
}: ParallaxHeaderProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const scrollY = useRef(new Animated.Value(0)).current;
  const [viewport, setViewport] = useState(0);

  // Scroll distance over which the hero collapses into the bar.
  const range = Math.max(1, headerHeight - collapsedHeight);

  const heroTranslate = reduceMotion
    ? scrollY.interpolate({ inputRange: [-1, 0, 1], outputRange: [0, 0, -1] })
    : scrollY.interpolate({
        inputRange: [-headerHeight, 0, headerHeight],
        // Pulled down, the hero is pushed half as far as it grows, which keeps its top edge fixed.
        outputRange: [headerHeight / 2, 0, -headerHeight * 0.5],
      });
  const heroScale = reduceMotion
    ? 1
    : scrollY.interpolate({
        inputRange: [-headerHeight, 0],
        outputRange: [2, 1],
        extrapolateRight: "clamp",
      });
  const barOpacity = reduceMotion
    ? scrollY.interpolate({
        inputRange: [range - 1, range],
        outputRange: [0, 1],
        extrapolate: "clamp",
      })
    : scrollY.interpolate({
        inputRange: [range * 0.55, range],
        outputRange: [0, 1],
        extrapolate: "clamp",
      });

  return (
    <View
      onLayout={(event: LayoutChangeEvent) => setViewport(event.nativeEvent.layout.height)}
      style={[styles.root, { backgroundColor: palette.background }, style]}
    >
      <Animated.View
        accessibilityElementsHidden={false}
        style={[
          styles.hero,
          {
            height: headerHeight,
            transform: [{ translateY: heroTranslate }, { scale: heroScale }],
          },
        ]}
      >
        {header}
      </Animated.View>
      <Animated.ScrollView
        scrollEventThrottle={16}
        onScroll={Animated.event([{ nativeEvent: { contentOffset: { y: scrollY } } }], {
          useNativeDriver: NATIVE_DRIVER,
        })}
        style={styles.scroll}
        contentContainerStyle={{ paddingTop: headerHeight - 24 }}
      >
        <View
          style={[styles.sheet, { backgroundColor: palette.background, minHeight: viewport + 24 }]}
        >
          {children}
        </View>
      </Animated.ScrollView>
      <Animated.View
        pointerEvents="none"
        style={[
          styles.bar,
          {
            height: collapsedHeight,
            backgroundColor: palette.bar,
            borderBottomColor: palette.border,
            opacity: barOpacity,
          },
        ]}
      >
        {title ? (
          <Text
            accessibilityRole="header"
            numberOfLines={1}
            style={[styles.title, { color: palette.title }]}
          >
            {title}
          </Text>
        ) : null}
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, overflow: "hidden" },
  hero: { position: "absolute", top: 0, left: 0, right: 0, overflow: "hidden" },
  scroll: { flex: 1, backgroundColor: "transparent" },
  // The content overlaps the hero's lower edge, so its rounded top corners read as a sheet.
  sheet: { borderTopLeftRadius: 24, borderTopRightRadius: 24, overflow: "hidden" },
  bar: {
    position: "absolute",
    top: 0,
    left: 0,
    right: 0,
    justifyContent: "center",
    paddingHorizontal: 20,
    borderBottomWidth: StyleSheet.hairlineWidth,
  },
  title: { fontSize: 17, fontWeight: "700" },
});
```

---

# Bubble Tab Bar

> A React Native bottom tab bar where a rounded pill slides behind the selected tab and the selected tab opens to show its label.

Install: `npx @modus-ui/cli add bubble-tab-bar`

A bottom tab bar where a rounded pill slides behind the selected tab, stretching a little as it travels. The selected tab opens up to show its label next to the icon; the others stay icon-only. Every tab is at least 44 points tall and wide, and the bar is a tablist to screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add bubble-tab-bar
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/bubble-tab-bar.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Text } from "react-native";
import { BubbleTabBar } from "@/components/ui/bubble-tab-bar";

const tabs = [
  { id: "home", label: "Home", icon: (color: string) => <Text style={{ color }}>⌂</Text> },
  { id: "saved", label: "Saved", icon: (color: string) => <Text style={{ color }}>♡</Text> },
  { id: "profile", label: "Profile", icon: (color: string) => <Text style={{ color }}>☺</Text> },
];

export default function Example() {
  const [tab, setTab] = useState("home");

  return <BubbleTabBar tabs={tabs} value={tab} onChange={setTab} />;
}
```

An icon can be a node, or a function that receives the tab's current color (white on the pill, muted elsewhere) and returns the node. The bar fills its parent's width.

## Props

| Prop       | Type                          | Default | Description                                          |
| :--------- | :---------------------------- | :------ | :--------------------------------------------------- |
| `tabs`     | `BubbleTab[]`                 | -       | The tabs. Each has an `id`, a `label` and an `icon`. |
| `value`    | `string`                      | -       | The `id` of the selected tab.                        |
| `onChange` | `(id: string) => void`        | -       | Called with the `id` of the tab that was pressed.    |
| `colors`   | `Partial<BubbleTabBarColors>` | -       | Overrides `bar`, `pill`, `active` and `inactive`.    |
| `style`    | `StyleProp<ViewStyle>`        | -       | Style for the bar.                                   |

## Source

`components/ui/bubble-tab-bar.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const PAD = 6;
const TAB_HEIGHT = 52;
const INACTIVE_WIDTH = 56;
const STRETCH = 16;

export interface BubbleTab {
  id: string;
  label: string;
  /** The tab's icon, or a function that receives the tab's current color and returns it. */
  icon: ReactNode | ((color: string) => ReactNode);
}

export interface BubbleTabBarColors {
  bar: string;
  pill: string;
  active: string;
  inactive: string;
}

const DEFAULT_COLORS: BubbleTabBarColors = {
  bar: "#ffffff",
  pill: "#4f46e5",
  active: "#ffffff",
  inactive: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface BubbleTabBarProps {
  tabs: BubbleTab[];
  /** The `id` of the selected tab. */
  value: string;
  onChange: (id: string) => void;
  colors?: Partial<BubbleTabBarColors>;
  style?: StyleProp<ViewStyle>;
}

interface TabValues {
  width: Animated.Value;
  label: Animated.Value;
}

/**
 * A bottom tab bar where a rounded pill slides behind the selected tab, stretching a little as it
 * travels. The selected tab opens up to show its label next to the icon; the others stay icon-only.
 * Every tab is at least 44 points tall and wide, and the bar is a tablist to screen readers.
 */
export function BubbleTabBar({ tabs, value, onChange, colors, style }: BubbleTabBarProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [barWidth, setBarWidth] = useState(0);

  const index = Math.max(
    0,
    tabs.findIndex((tab) => tab.id === value),
  );
  const count = tabs.length;
  const inner = Math.max(0, barWidth - PAD * 2);
  const activeWidth = Math.max(INACTIVE_WIDTH, inner - (count - 1) * INACTIVE_WIDTH);

  const pillLeft = useRef(new Animated.Value(PAD)).current;
  const pillWidth = useRef(new Animated.Value(INACTIVE_WIDTH)).current;
  const stretch = useRef(new Animated.Value(0)).current;
  const perTab = useRef(new Map<string, TabValues>()).current;
  // The last layout the animated values were set for; a change of width jumps instead of animating.
  const settled = useRef({ width: 0, index: -1 });

  const valuesFor = (id: string): TabValues => {
    let values = perTab.get(id);
    if (!values) {
      values = { width: new Animated.Value(INACTIVE_WIDTH), label: new Animated.Value(0) };
      perTab.set(id, values);
    }
    return values;
  };

  const ids = tabs.map((tab) => tab.id).join("|");

  useEffect(() => {
    if (barWidth === 0) return;
    const jump = reduceMotion || settled.current.width !== barWidth || settled.current.index === -1;
    settled.current = { width: barWidth, index };

    const leftTarget = PAD + index * INACTIVE_WIDTH;
    const items = ids.split("|").map((id, i) => ({
      values: valuesFor(id),
      width: i === index ? activeWidth : INACTIVE_WIDTH,
      label: i === index ? 1 : 0,
    }));

    if (jump) {
      pillLeft.setValue(leftTarget);
      pillWidth.setValue(activeWidth);
      stretch.setValue(0);
      items.forEach((item) => {
        item.values.width.setValue(item.width);
        item.values.label.setValue(item.label);
      });
      return;
    }

    // Layout properties (left, width) cannot use the native driver.
    const spring = (value: Animated.Value, toValue: number) =>
      Animated.spring(value, {
        toValue,
        stiffness: 320,
        damping: 26,
        mass: 1,
        useNativeDriver: false,
      });
    const animation = Animated.parallel([
      spring(pillLeft, leftTarget),
      spring(pillWidth, activeWidth),
      Animated.sequence([
        Animated.timing(stretch, { toValue: 1, duration: 110, useNativeDriver: false }),
        Animated.spring(stretch, {
          toValue: 0,
          stiffness: 260,
          damping: 18,
          mass: 1,
          useNativeDriver: false,
        }),
      ]),
      ...items.map((item) => spring(item.values.width, item.width)),
      ...items.map((item) =>
        Animated.timing(item.values.label, {
          toValue: item.label,
          duration: 180,
          useNativeDriver: NATIVE_DRIVER,
        }),
      ),
    ]);
    animation.start();
    return () => animation.stop();
    // valuesFor only reads refs, and the animated values are stable.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [index, barWidth, activeWidth, ids, reduceMotion]);

  const animatedPillWidth = useMemo(
    () =>
      Animated.add(
        pillWidth,
        stretch.interpolate({ inputRange: [0, 1], outputRange: [0, STRETCH] }),
      ),
    [pillWidth, stretch],
  );
  const pillStyle = useMemo(
    () => [
      styles.pill,
      { backgroundColor: palette.pill, left: pillLeft, width: animatedPillWidth },
    ],
    [palette.pill, pillLeft, animatedPillWidth],
  );

  return (
    <View
      accessibilityRole="tablist"
      onLayout={(event: LayoutChangeEvent) => setBarWidth(event.nativeEvent.layout.width)}
      style={[styles.bar, { backgroundColor: palette.bar }, style]}
    >
      <Animated.View pointerEvents="none" style={pillStyle} />
      {tabs.map((tab) => (
        <TabItem
          key={tab.id}
          tab={tab}
          selected={tab.id === value}
          values={valuesFor(tab.id)}
          colors={palette}
          onPress={() => onChange(tab.id)}
        />
      ))}
    </View>
  );
}

function TabItem({
  tab,
  selected,
  values,
  colors,
  onPress,
}: {
  tab: BubbleTab;
  selected: boolean;
  values: TabValues;
  colors: BubbleTabBarColors;
  onPress: () => void;
}) {
  const color = selected ? colors.active : colors.inactive;
  const boxStyle = useMemo(() => [styles.tab, { width: values.width }], [values.width]);
  const labelStyle = useMemo(() => [styles.label, { opacity: values.label }], [values.label]);

  return (
    <Animated.View style={boxStyle}>
      <Pressable
        accessibilityRole="tab"
        accessibilityLabel={tab.label}
        accessibilityState={{ selected }}
        aria-selected={selected}
        onPress={onPress}
        style={({ pressed }) => [styles.press, pressed && styles.pressed]}
      >
        {typeof tab.icon === "function" ? tab.icon(color) : tab.icon}
        <Animated.Text numberOfLines={1} style={[labelStyle, { color }]}>
          {tab.label}
        </Animated.Text>
      </Pressable>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  bar: {
    flexDirection: "row",
    alignItems: "center",
    padding: PAD,
    borderRadius: (TAB_HEIGHT + PAD * 2) / 2,
    userSelect: "none",
    boxShadow: "0 6px 22px rgba(0, 0, 0, 0.14)",
  },
  pill: {
    position: "absolute",
    top: PAD,
    height: TAB_HEIGHT,
    borderRadius: TAB_HEIGHT / 2,
  },
  tab: { height: TAB_HEIGHT, borderRadius: TAB_HEIGHT / 2, overflow: "hidden" },
  press: {
    flex: 1,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "center",
    gap: 8,
    paddingHorizontal: 10,
  },
  pressed: { opacity: 0.7 },
  label: { fontSize: 14, fontWeight: "700" },
});
```

---

# Roll Number

> A React Native odometer whose digits roll to their new value, last digit first, with separators, decimals and negative numbers.

Install: `npx @modus-ui/cli add roll-number`

An odometer. Each digit is a column that rolls to its new value, starting from the last digit and moving left. Thousands separators stay put, the number may grow or shrink in length, and screen readers get the whole value as one piece of text instead of a column of digits. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add roll-number
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/roll-number.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, View } from "react-native";
import { RollNumber } from "@/components/ui/roll-number";

export default function Example() {
  const [balance, setBalance] = useState(12480.62);

  return (
    <View style={{ alignItems: "center", gap: 16 }}>
      <RollNumber value={balance} decimals={2} prefix="$" />
      <Button title="Add $100" onPress={() => setBalance((value) => value + 100)} />
    </View>
  );
}
```

## Props

| Prop       | Type                        | Default | Description                                                         |
| :--------- | :-------------------------- | :------ | :------------------------------------------------------------------ |
| `value`    | `number`                    | -       | The number to show. Negative values get a minus sign.               |
| `decimals` | `number`                    | `0`     | Digits after the decimal point.                                     |
| `prefix`   | `string`                    | -       | Text before the number, such as a currency symbol.                  |
| `suffix`   | `string`                    | -       | Text after the number, such as a unit.                              |
| `fontSize` | `number`                    | `40`    | Size of the digits. Their column width follows it.                  |
| `colors`   | `Partial<RollNumberColors>` | -       | Overrides `text`, the color of the digits and the surrounding text. |
| `duration` | `number`                    | `700`   | How long each digit takes to roll, in milliseconds.                 |
| `style`    | `StyleProp<ViewStyle>`      | -       | Style for the container.                                            |

## Source

`components/ui/roll-number.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface RollNumberColors {
  /** Color of the digits and the surrounding text. */
  text: string;
}

const DEFAULT_COLORS: RollNumberColors = { text: "#111827" };
const DIGITS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
// Each digit, counting from the right, starts rolling this much later than the one after it.
const STAGGER = 45;

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

type Token = { key: string; digit: number; position: number } | { key: string; text: string };

function format(value: number, decimals: number) {
  const fixed = Math.abs(value).toFixed(Math.max(0, decimals));
  const [whole, fraction] = fixed.split(".");
  const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
  return {
    // A value that rounds to zero is not shown as negative.
    negative: value < 0 && Number(fixed) !== 0,
    text: `${grouped}${fraction ? `.${fraction}` : ""}`,
  };
}

/** Splits the text into digits and fixed characters. A digit is keyed by its place from the right,
 *  so adding or removing a digit on the left never moves the columns that stay. */
function tokenize(text: string): Token[] {
  const tokens: Token[] = [];
  let position = 0;
  for (let i = text.length - 1; i >= 0; i--) {
    const char = text[i];
    if (/\d/.test(char)) {
      tokens.unshift({ key: `d${position}`, digit: Number(char), position });
      position++;
    } else {
      tokens.unshift({
        key: `t${position}${char === "," ? "c" : char === "." ? "p" : "m"}`,
        text: char,
      });
    }
  }
  return tokens;
}

export interface RollNumberProps {
  value: number;
  /** Digits after the decimal point. */
  decimals?: number;
  /** Text before the number, such as a currency symbol. */
  prefix?: string;
  /** Text after the number, such as a unit. */
  suffix?: string;
  fontSize?: number;
  colors?: Partial<RollNumberColors>;
  /** How long each digit takes to roll, in milliseconds. */
  duration?: number;
  style?: StyleProp<ViewStyle>;
}

/**
 * An odometer. Each digit is a column that rolls to its new value, starting from the last digit and
 * moving left. Thousands separators stay put, the number may grow or shrink in length, and screen
 * readers get the whole value as one piece of text instead of a column of digits.
 */
export function RollNumber({
  value,
  decimals = 0,
  prefix,
  suffix,
  fontSize = 40,
  colors,
  duration = 700,
  style,
}: RollNumberProps) {
  const color = { ...DEFAULT_COLORS, ...colors }.text;
  const reduceMotion = useReduceMotion();
  const { negative, text } = format(value, decimals);
  const tokens = tokenize(text);
  const lineHeight = Math.round(fontSize * 1.25);
  const textStyle = { fontSize, lineHeight, color };

  return (
    <View
      accessible
      accessibilityRole="text"
      accessibilityLabel={`${negative ? "-" : ""}${prefix ?? ""}${text}${suffix ?? ""}`}
      style={[styles.row, { height: lineHeight }, style]}
    >
      {negative ? (
        <Text aria-hidden style={[styles.char, textStyle]}>
          -
        </Text>
      ) : null}
      {prefix ? (
        <Text aria-hidden style={[styles.char, textStyle]}>
          {prefix}
        </Text>
      ) : null}
      {tokens.map((token) =>
        "digit" in token ? (
          <DigitColumn
            key={token.key}
            digit={token.digit}
            position={token.position}
            fontSize={fontSize}
            lineHeight={lineHeight}
            color={color}
            duration={duration}
            reduceMotion={reduceMotion}
          />
        ) : (
          <Text key={token.key} aria-hidden style={[styles.char, textStyle]}>
            {token.text}
          </Text>
        ),
      )}
      {suffix ? (
        <Text aria-hidden style={[styles.char, textStyle]}>
          {suffix}
        </Text>
      ) : null}
    </View>
  );
}

function DigitColumn({
  digit,
  position,
  fontSize,
  lineHeight,
  color,
  duration,
  reduceMotion,
}: {
  digit: number;
  position: number;
  fontSize: number;
  lineHeight: number;
  color: string;
  duration: number;
  reduceMotion: boolean;
}) {
  // A new column starts on its digit, so growing the number does not roll in from zero.
  const y = useRef(new Animated.Value(-digit * lineHeight)).current;
  const strip = useMemo(() => ({ transform: [{ translateY: y }] }), [y]);

  useEffect(() => {
    const target = -digit * lineHeight;
    if (reduceMotion || duration <= 0) {
      y.setValue(target);
      return;
    }
    const roll = Animated.timing(y, {
      toValue: target,
      duration,
      delay: position * STAGGER,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: NATIVE_DRIVER,
    });
    roll.start();
    return () => roll.stop();
  }, [digit, lineHeight, position, duration, reduceMotion, y]);

  return (
    <View
      aria-hidden
      importantForAccessibility="no-hide-descendants"
      accessibilityElementsHidden
      style={{ height: lineHeight, width: Math.round(fontSize * 0.62), overflow: "hidden" }}
    >
      <Animated.View style={strip}>
        {DIGITS.map((n) => (
          <Text key={n} style={[styles.digit, { fontSize, lineHeight, height: lineHeight, color }]}>
            {n}
          </Text>
        ))}
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "flex-start", userSelect: "none" },
  char: { fontWeight: "700", fontVariant: ["tabular-nums"] },
  digit: { fontWeight: "700", textAlign: "center", fontVariant: ["tabular-nums"] },
});
```

---

# Star Rating

> A React Native star rating you can tap or scrub, with half stars, popping fills and adjustable screen reader support.

Install: `npx @modus-ui/cli add star-rating`

A star rating you can tap or scrub. Drag across the row and the rating follows the pointer, snapping to whole stars (or halves); dragging past the left edge clears it. Each star pops as it fills. Screen readers get an adjustable control that says "3 of 5", and a read-only rating is announced as an image with the same text. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add star-rating
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/star-rating.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { StarRating } from "@/components/ui/star-rating";

export default function Example() {
  const [rating, setRating] = useState(4);

  return <StarRating value={rating} onChange={setRating} allowHalf />;
}
```

## Props

| Prop        | Type                        | Default    | Description                                                             |
| :---------- | :-------------------------- | :--------- | :---------------------------------------------------------------------- |
| `value`     | `number`                    | -          | The current rating, from 0 to `max`.                                    |
| `onChange`  | `(value: number) => void`   | -          | Called with the new rating whenever a tap or drag changes it.           |
| `max`       | `number`                    | `5`        | How many stars there are.                                               |
| `size`      | `number`                    | `34`       | Width and height of each star.                                          |
| `allowHalf` | `boolean`                   | `false`    | Lets the rating land on halves: the left half of a star counts as half. |
| `readOnly`  | `boolean`                   | `false`    | Shows the rating without letting anyone change it.                      |
| `label`     | `string`                    | `"Rating"` | Spoken name of the control.                                             |
| `colors`    | `Partial<StarRatingColors>` | -          | Overrides `filled` and `empty`.                                         |
| `style`     | `StyleProp<ViewStyle>`      | -          | Style for the row.                                                      |

## Source

`components/ui/star-rating.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface StarRatingColors {
  filled: string;
  empty: string;
}

const DEFAULT_COLORS: StarRatingColors = {
  filled: "#f59e0b",
  empty: "#d1d5db",
};

// userSelect keeps a mouse drag on the web from selecting the glyphs instead of scrubbing.
const styles = StyleSheet.create({ row: { alignSelf: "flex-start", userSelect: "none" } });

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface StarRatingProps {
  /** The current rating, from 0 to `max`. */
  value: number;
  /** Called with the new rating whenever a tap or drag changes it. */
  onChange?: (value: number) => void;
  /** How many stars there are. */
  max?: number;
  /** Width and height of each star. */
  size?: number;
  /** Lets the rating land on halves: the left half of a star counts as half. */
  allowHalf?: boolean;
  /** Shows the rating without letting anyone change it. */
  readOnly?: boolean;
  /** Spoken name of the control. */
  label?: string;
  colors?: Partial<StarRatingColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A star rating you can tap or scrub. Drag across the row and the rating follows the pointer,
 * snapping to whole stars (or halves); dragging past the left edge clears it. Each star pops as it
 * fills. Screen readers get an adjustable control that says "3 of 5", and a read-only rating is
 * announced as an image with the same text.
 */
export function StarRating({
  value,
  onChange,
  max = 5,
  size = 34,
  allowHalf = false,
  readOnly = false,
  label = "Rating",
  colors,
  style,
}: StarRatingProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  const gap = Math.round(size * 0.12);
  const step = allowHalf ? 0.5 : 1;
  const text = `${value} of ${max}`;

  // The responder is created once, so it reads the latest values from here.
  const live = useRef({ value, onChange, max, size, gap, allowHalf, step });
  live.current = { value, onChange, max, size, gap, allowHalf, step };
  const touch = useRef({ startX: 0, moved: false });

  /** The rating under a horizontal position inside the row. */
  const valueAt = (x: number, scrubbing: boolean) => {
    const { max: count, size: width, gap: space, allowHalf: halves } = live.current;
    if (scrubbing && x < 0) return 0;
    const cell = width + space;
    const index = Math.max(0, Math.min(count - 1, Math.floor(x / cell)));
    const into = Math.max(0, Math.min(1, (x - index * cell) / width));
    return halves ? index + (into <= 0.5 ? 0.5 : 1) : index + 1;
  };

  const commit = (next: number) => {
    if (next !== live.current.value) live.current.onChange?.(next);
  };

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderGrant: (event) => {
        touch.current = { startX: event.nativeEvent.locationX, moved: false };
      },
      onPanResponderMove: (_, g) => {
        if (!touch.current.moved && Math.abs(g.dx) < 4) return;
        touch.current.moved = true;
        commit(valueAt(touch.current.startX + g.dx, true));
      },
      // Nothing here is a Pressable, so the click a mouse sends after a drag has nothing to hit.
      onPanResponderRelease: () => {
        if (!touch.current.moved) commit(valueAt(touch.current.startX, false));
      },
    }),
  ).current;

  const nudge = (direction: 1 | -1) => {
    const next = Math.max(0, Math.min(max, value + direction * step));
    if (next !== value) onChange?.(next);
  };

  const rowWidth = max * size + (max - 1) * gap;

  return (
    <View
      {...(readOnly ? {} : pan.panHandlers)}
      accessible
      accessibilityRole={readOnly ? "image" : "adjustable"}
      accessibilityLabel={readOnly ? `${label}: ${text}` : label}
      accessibilityValue={readOnly ? undefined : { min: 0, max, now: value, text }}
      aria-valuemin={readOnly ? undefined : 0}
      aria-valuemax={readOnly ? undefined : max}
      aria-valuenow={readOnly ? undefined : value}
      aria-valuetext={readOnly ? undefined : text}
      accessibilityActions={readOnly ? undefined : [{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(event) =>
        nudge(event.nativeEvent.actionName === "increment" ? 1 : -1)
      }
      style={[styles.row, { width: rowWidth, height: size }, style]}
    >
      {/* Stars ignore the pointer, so locationX is always measured from the row. */}
      <View
        pointerEvents="none"
        accessibilityElementsHidden
        importantForAccessibility="no-hide-descendants"
        style={{ flexDirection: "row", gap }}
      >
        {Array.from({ length: max }, (_, index) => (
          <Star
            key={index}
            fraction={Math.max(0, Math.min(1, value - index))}
            size={size}
            colors={palette}
            reduceMotion={reduceMotion}
          />
        ))}
      </View>
    </View>
  );
}

interface StarProps {
  /** How much of the star is filled, 0 to 1. */
  fraction: number;
  size: number;
  colors: StarRatingColors;
  reduceMotion: boolean;
}

function Star({ fraction, size, colors, reduceMotion }: StarProps) {
  const filled = fraction > 0;
  const scale = useRef(new Animated.Value(1)).current;
  const wasFilled = useRef(filled);
  // Mounted up front and memoized, so react-native-web never rebuilds the animated style.
  const popStyle = useMemo(() => ({ transform: [{ scale }] }), [scale]);

  useEffect(() => {
    if (filled && !wasFilled.current && !reduceMotion) {
      scale.setValue(0.78);
      Animated.spring(scale, {
        toValue: 1,
        stiffness: 520,
        damping: 11,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
    wasFilled.current = filled;
  }, [filled, reduceMotion, scale]);

  const glyph = {
    position: "absolute",
    top: 0,
    left: 0,
    width: size,
    height: size,
    fontSize: size * 0.9,
    lineHeight: size,
    textAlign: "center",
    includeFontPadding: false,
    userSelect: "none",
  } as const;

  return (
    <Animated.View style={[{ width: size, height: size }, popStyle]}>
      <Text style={[glyph, { color: colors.empty }]}>★</Text>
      <View
        style={{
          position: "absolute",
          top: 0,
          left: 0,
          bottom: 0,
          width: fraction * size,
          overflow: "hidden",
        }}
      >
        <Text style={[glyph, { color: colors.filled }]}>★</Text>
      </View>
    </Animated.View>
  );
}
```

---

# Value Slider

> A React Native slider with a value bubble, step snapping, tap-to-jump and adjustable screen reader support.

Install: `npx @modus-ui/cli add value-slider`

A slider you can drag or tap. Touching the track jumps the thumb there; grabbing the thumb moves it without a jump. The thumb grows while held and a bubble above it reads out the value, which snaps to `step` and stays within `min` and `max`. Screen readers get an adjustable control with increment and decrement actions. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add value-slider
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/value-slider.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { ValueSlider } from "@/components/ui/value-slider";

export default function Example() {
  const [volume, setVolume] = useState(40);

  return (
    <ValueSlider
      label="Volume"
      value={volume}
      onValueChange={setVolume}
      onSlidingComplete={(final) => console.log("saved", final)}
    />
  );
}
```

The slider fills the width of its parent.

## Props

| Prop                | Type                         | Default   | Description                                                    |
| :------------------ | :--------------------------- | :-------- | :------------------------------------------------------------- |
| `value`             | `number`                     | -         | The current value.                                             |
| `onValueChange`     | `(value: number) => void`    | -         | Called with the snapped value as the thumb moves.              |
| `onSlidingComplete` | `(value: number) => void`    | -         | Called once with the final value when the finger lifts.        |
| `min`               | `number`                     | `0`       | The value at the left end.                                     |
| `max`               | `number`                     | `100`     | The value at the right end.                                    |
| `step`              | `number`                     | `1`       | Values snap to multiples of this, counted from `min`.          |
| `showBubble`        | `boolean`                    | `true`    | Shows the current value above the thumb while it is held.      |
| `disabled`          | `boolean`                    | `false`   | Dims the slider and ignores touches.                           |
| `label`             | `string`                     | `"Value"` | Spoken name of the slider.                                     |
| `colors`            | `Partial<ValueSliderColors>` | -         | Overrides `track`, `fill`, `thumb`, `bubble` and `bubbleText`. |
| `style`             | `StyleProp<ViewStyle>`       | -         | Style for the slider.                                          |

## Source

`components/ui/value-slider.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const THUMB = 26;
const TRACK = 6;
// Room above the track for the value bubble.
const BUBBLE_ZONE = 40;
const BUBBLE_WIDTH = 48;

export interface ValueSliderColors {
  track: string;
  fill: string;
  thumb: string;
  bubble: string;
  bubbleText: string;
}

const DEFAULT_COLORS: ValueSliderColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  thumb: "#ffffff",
  bubble: "#111827",
  bubbleText: "#ffffff",
};

// userSelect keeps a mouse drag on the web from selecting text instead of moving the thumb.
const styles = StyleSheet.create({ root: { alignSelf: "stretch", userSelect: "none" } });

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

/** How many decimals a step has, so snapped values do not pick up float noise (0.1 + 0.2). */
function decimalsOf(step: number) {
  const [, fraction = ""] = String(step).split(".");
  return fraction.length;
}

export interface ValueSliderProps {
  value: number;
  /** Called with the snapped value as the thumb moves. */
  onValueChange: (value: number) => void;
  /** Called once with the final value when the finger lifts. */
  onSlidingComplete?: (value: number) => void;
  /** The value at the left end. */
  min?: number;
  /** The value at the right end. */
  max?: number;
  /** Values snap to multiples of this, counted from `min`. */
  step?: number;
  /** Shows the current value above the thumb while it is held. */
  showBubble?: boolean;
  /** Dims the slider and ignores touches. */
  disabled?: boolean;
  /** Spoken name of the slider. */
  label?: string;
  colors?: Partial<ValueSliderColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A slider you can drag or tap. Touching the track jumps the thumb there; grabbing the thumb moves
 * it without a jump. The thumb grows while held and a bubble above it reads out the value, which
 * snaps to `step` and stays within `min` and `max`. Screen readers get an adjustable control with
 * increment and decrement actions.
 */
export function ValueSlider({
  value,
  onValueChange,
  onSlidingComplete,
  min = 0,
  max = 100,
  step = 1,
  showBubble = true,
  disabled = false,
  label = "Value",
  colors,
  style,
}: ValueSliderProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);

  const range = max - min || 1;
  const span = Math.max(0, width - THUMB);
  const ratioOf = (next: number) => Math.max(0, Math.min(1, (next - min) / range));

  // 0 to 1 along the track. Widths cannot use the native driver, so this one runs on the JS thread.
  const pos = useRef(new Animated.Value(ratioOf(value))).current;
  const posNow = useRef(ratioOf(value));
  const grow = useRef(new Animated.Value(0)).current;
  const bubble = useRef(new Animated.Value(0)).current;
  const [holding, setHolding] = useState(false);

  // Built once per width and reused, so react-native-web does not rebuild the animated styles.
  const thumbX = useMemo(
    () => pos.interpolate({ inputRange: [0, 1], outputRange: [0, span] }),
    [pos, span],
  );
  const fillWidth = useMemo(
    () => pos.interpolate({ inputRange: [0, 1], outputRange: [THUMB / 2, THUMB / 2 + span] }),
    [pos, span],
  );
  const thumbScale = useMemo(
    () => grow.interpolate({ inputRange: [0, 1], outputRange: [1, 1.25] }),
    [grow],
  );
  const bubbleStyle = useMemo(
    () => ({
      opacity: bubble,
      transform: [
        { translateY: bubble.interpolate({ inputRange: [0, 1], outputRange: [8, 0] }) },
        { scale: bubble.interpolate({ inputRange: [0, 1], outputRange: [0.7, 1] }) },
      ],
    }),
    [bubble],
  );

  const live = useRef({
    value,
    min,
    max,
    step,
    span,
    disabled,
    reduceMotion,
    onValueChange,
    onSlidingComplete,
  });
  live.current = {
    value,
    min,
    max,
    step,
    span,
    disabled,
    reduceMotion,
    onValueChange,
    onSlidingComplete,
  };
  const drag = useRef({ active: false, startX: 0, offset: 0, last: value });

  useEffect(() => {
    const id = pos.addListener(({ value: next }) => (posNow.current = next));
    return () => pos.removeListener(id);
  }, [pos]);

  const animate = (node: Animated.Value, toValue: number, native: boolean) => {
    if (live.current.reduceMotion) {
      node.setValue(toValue);
      return;
    }
    Animated.spring(node, {
      toValue,
      stiffness: 420,
      damping: 28,
      mass: 1,
      useNativeDriver: native,
    }).start();
  };

  // Follow the value when the parent changes it, except while the thumb is under a finger.
  useEffect(() => {
    if (!drag.current.active) animate(pos, ratioOf(value), false);
    // animate and ratioOf read from refs and props that the dependencies below already cover.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [value, min, max, reduceMotion]);

  const snap = (raw: number) => {
    const { min: lo, max: hi, step: unit } = live.current;
    const snapped = lo + Math.round((raw - lo) / unit) * unit;
    return Number(Math.max(lo, Math.min(hi, snapped)).toFixed(decimalsOf(unit)));
  };

  /** Moves the thumb to a horizontal position inside the slider and reports the snapped value. */
  const moveTo = (x: number) => {
    const { span: room, min: lo, max: hi } = live.current;
    if (room <= 0) return;
    const ratio = Math.max(0, Math.min(1, (x + drag.current.offset - THUMB / 2) / room));
    const next = snap(lo + ratio * (hi - lo));
    pos.setValue((next - lo) / (hi - lo || 1));
    if (next !== drag.current.last) {
      drag.current.last = next;
      live.current.onValueChange(next);
    }
  };

  const hold = (on: boolean) => {
    setHolding(on);
    animate(grow, on ? 1 : 0, NATIVE_DRIVER);
    animate(bubble, on ? 1 : 0, NATIVE_DRIVER);
  };

  const release = () => {
    if (!drag.current.active) return;
    drag.current.active = false;
    hold(false);
    live.current.onSlidingComplete?.(drag.current.last);
  };

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => !live.current.disabled,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: (event) => {
        const x = event.nativeEvent.locationX;
        const center = THUMB / 2 + posNow.current * live.current.span;
        const onThumb = Math.abs(x - center) <= THUMB / 2 + 8;
        drag.current = {
          active: true,
          startX: x,
          // Grabbing the thumb keeps it where it is; touching the track jumps it to the finger.
          offset: onThumb ? center - x : 0,
          last: live.current.value,
        };
        hold(true);
        if (!onThumb) moveTo(x);
      },
      onPanResponderMove: (_, g) => moveTo(drag.current.startX + g.dx),
      onPanResponderRelease: release,
      onPanResponderTerminate: release,
    }),
  ).current;

  const nudge = (direction: 1 | -1) => {
    const next = Number(
      Math.max(min, Math.min(max, value + direction * step)).toFixed(decimalsOf(step)),
    );
    if (next === value) return;
    onValueChange(next);
    onSlidingComplete?.(next);
  };

  const height = BUBBLE_ZONE + THUMB;
  const trackTop = BUBBLE_ZONE + (THUMB - TRACK) / 2;

  return (
    <View
      {...(disabled ? {} : pan.panHandlers)}
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      accessible
      accessibilityRole="adjustable"
      accessibilityLabel={label}
      accessibilityState={{ disabled }}
      accessibilityValue={{ min, max, now: value }}
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(event) =>
        nudge(event.nativeEvent.actionName === "increment" ? 1 : -1)
      }
      style={[styles.root, { height, opacity: disabled ? 0.5 : 1 }, style]}
    >
      {/* Everything inside ignores the pointer, so locationX is always measured from the slider. */}
      <View
        pointerEvents="none"
        accessibilityElementsHidden
        importantForAccessibility="no-hide-descendants"
        style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }}
      >
        <View
          style={{
            position: "absolute",
            left: 0,
            right: 0,
            top: trackTop,
            height: TRACK,
            borderRadius: TRACK / 2,
            backgroundColor: palette.track,
          }}
        />
        <Animated.View
          style={{
            position: "absolute",
            left: 0,
            top: trackTop,
            height: TRACK,
            width: fillWidth,
            borderRadius: TRACK / 2,
            backgroundColor: palette.fill,
          }}
        />
        <Animated.View
          style={{
            position: "absolute",
            left: 0,
            top: BUBBLE_ZONE,
            width: THUMB,
            height: THUMB,
            transform: [{ translateX: thumbX }],
          }}
        >
          <Animated.View
            style={{
              width: THUMB,
              height: THUMB,
              borderRadius: THUMB / 2,
              backgroundColor: palette.thumb,
              borderWidth: 2,
              borderColor: palette.fill,
              boxShadow: "0 2px 6px rgba(0, 0, 0, 0.25)",
              transform: [{ scale: thumbScale }],
            }}
          />
          {showBubble ? (
            <Animated.View
              style={[
                {
                  position: "absolute",
                  bottom: THUMB + 8,
                  left: (THUMB - BUBBLE_WIDTH) / 2,
                  width: BUBBLE_WIDTH,
                  height: 28,
                  borderRadius: 8,
                  alignItems: "center",
                  justifyContent: "center",
                  backgroundColor: palette.bubble,
                },
                bubbleStyle,
              ]}
            >
              <Text
                numberOfLines={1}
                aria-hidden={!holding}
                style={{
                  fontSize: 13,
                  fontWeight: "700",
                  color: palette.bubbleText,
                  userSelect: "none",
                }}
              >
                {value}
              </Text>
            </Animated.View>
          ) : null}
        </Animated.View>
      </View>
    </View>
  );
}
```

---

# Expand Search

> A React Native search field that starts as a round button and springs open to full width, with a clear button and a Cancel that folds it away.

Install: `npx @modus-ui/cli add expand-search`

A search field that starts as a round button and springs open to the full width, where the cursor is waiting. A clear button shows while there is text, and Cancel (or Escape on the web) folds the field away and clears it. The magnifier is drawn with plain views, so there is no icon package. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add expand-search
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/expand-search.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { View } from "react-native";
import { ExpandSearch } from "@/components/ui/expand-search";

export default function Example() {
  const [query, setQuery] = useState("");

  return (
    <View style={{ padding: 20 }}>
      <ExpandSearch value={query} onChangeText={setQuery} onSubmit={(text) => console.log(text)} />
    </View>
  );
}
```

The field is as wide as its parent allows, so the parent decides how far it opens.

## Props

| Prop               | Type                          | Default    | Description                                                                    |
| :----------------- | :---------------------------- | :--------- | :----------------------------------------------------------------------------- |
| `value`            | `string`                      | -          | The text in the field. Leave it out to let the component keep the text itself. |
| `onChangeText`     | `(text: string) => void`      | -          | Called as the text changes, and with an empty string on clear or Cancel.       |
| `onSubmit`         | `(text: string) => void`      | -          | Called when the keyboard's search key is pressed.                              |
| `placeholder`      | `string`                      | `"Search"` | Placeholder text, also the field's accessibility label.                        |
| `defaultExpanded`  | `boolean`                     | `false`    | Whether the field starts open.                                                 |
| `onExpandedChange` | `(expanded: boolean) => void` | -          | Called when the field opens or closes.                                         |
| `colors`           | `Partial<ExpandSearchColors>` | -          | Overrides `field`, `icon`, `text` and `placeholder`.                           |
| `style`            | `StyleProp<ViewStyle>`        | -          | Style for the container, which is as wide as its parent allows.                |

## Source

`components/ui/expand-search.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  Animated,
  Pressable,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const SIZE = 44;
const CANCEL_WIDTH = 76;

export interface ExpandSearchColors {
  field: string;
  icon: string;
  text: string;
  placeholder: string;
}

const DEFAULT_COLORS: ExpandSearchColors = {
  field: "#f3f4f6",
  icon: "#374151",
  text: "#111827",
  placeholder: "#9ca3af",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ExpandSearchProps {
  /** The text in the field. Leave it out to let the component keep the text itself. */
  value?: string;
  onChangeText?: (text: string) => void;
  /** Called when the keyboard's search key is pressed. */
  onSubmit?: (text: string) => void;
  placeholder?: string;
  /** Whether the field starts open. */
  defaultExpanded?: boolean;
  onExpandedChange?: (expanded: boolean) => void;
  colors?: Partial<ExpandSearchColors>;
  /** Style for the container, which is as wide as its parent allows. Place it with this. */
  style?: StyleProp<ViewStyle>;
}

/**
 * A search field that starts as a round button and springs open to the full width, where the cursor
 * is waiting. A clear button shows while there is text, and Cancel (or Escape on the web) folds the
 * field away and clears it. The magnifier is drawn with plain views, so there is no icon package.
 */
export function ExpandSearch({
  value,
  onChangeText,
  onSubmit,
  placeholder = "Search",
  defaultExpanded = false,
  onExpandedChange,
  colors,
  style,
}: ExpandSearchProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [expanded, setExpanded] = useState(defaultExpanded);
  const [inner, setInner] = useState("");
  const [width, setWidth] = useState(0);
  const input = useRef<ElementRef<typeof TextInput>>(null);
  // 0 is the round button, 1 the open field. Width is not a native-driver property.
  const progress = useRef(new Animated.Value(defaultExpanded ? 1 : 0)).current;

  const text = value ?? inner;

  useEffect(() => {
    if (reduceMotion) {
      progress.setValue(expanded ? 1 : 0);
      return;
    }
    Animated.spring(progress, {
      toValue: expanded ? 1 : 0,
      stiffness: 320,
      damping: 30,
      mass: 1,
      useNativeDriver: false,
    }).start();
  }, [expanded, reduceMotion, progress]);

  // Built once per width so react-native-web does not restart the spring on every keystroke.
  const motion = useMemo(
    () => ({
      fieldWidth: progress.interpolate({
        inputRange: [0, 1],
        outputRange: [SIZE, Math.max(SIZE, width - CANCEL_WIDTH)],
      }),
      cancelOffset: progress.interpolate({ inputRange: [0, 1], outputRange: [12, 0] }),
    }),
    [progress, width],
  );

  const change = (next: string) => {
    setInner(next);
    onChangeText?.(next);
  };

  const open = () => {
    setExpanded(true);
    onExpandedChange?.(true);
    // Focus inside the press so mobile browsers raise the keyboard.
    input.current?.focus();
  };

  const close = () => {
    input.current?.blur();
    change("");
    setExpanded(false);
    onExpandedChange?.(false);
  };

  return (
    <View
      onLayout={(event) => setWidth(event.nativeEvent.layout.width)}
      style={[styles.root, style]}
    >
      <Animated.View
        style={[styles.field, { width: motion.fieldWidth, backgroundColor: palette.field }]}
      >
        <Pressable
          accessible={!expanded}
          accessibilityRole="button"
          accessibilityLabel="Search"
          onPress={expanded ? () => input.current?.focus() : open}
          style={styles.iconSlot}
        >
          <View style={styles.magnifier}>
            <View style={[styles.ring, { borderColor: palette.icon }]} />
            <View style={[styles.handle, { backgroundColor: palette.icon }]} />
          </View>
        </Pressable>
        <Animated.View
          pointerEvents={expanded ? "auto" : "none"}
          style={[styles.inputSlot, { opacity: progress }]}
        >
          <TextInput
            ref={input}
            accessibilityRole="search"
            accessibilityLabel={placeholder}
            value={text}
            onChangeText={change}
            onSubmitEditing={() => onSubmit?.(text)}
            onKeyPress={(event) => {
              if (event.nativeEvent.key === "Escape") close();
            }}
            placeholder={placeholder}
            placeholderTextColor={palette.placeholder}
            returnKeyType="search"
            autoCorrect={false}
            tabIndex={expanded ? 0 : -1}
            style={[styles.input, { color: palette.text }]}
          />
        </Animated.View>
        {expanded && text.length > 0 ? (
          <Pressable
            accessibilityRole="button"
            accessibilityLabel="Clear search"
            hitSlop={8}
            onPress={() => {
              change("");
              input.current?.focus();
            }}
            style={[styles.clear, { backgroundColor: palette.placeholder }]}
          >
            <Text style={[styles.clearGlyph, { color: palette.field }]}>×</Text>
          </Pressable>
        ) : null}
      </Animated.View>
      <Animated.View
        pointerEvents={expanded ? "auto" : "none"}
        style={[
          styles.cancel,
          { opacity: progress, transform: [{ translateX: motion.cancelOffset }] },
        ]}
      >
        <Pressable
          accessibilityRole="button"
          accessibilityLabel="Cancel"
          onPress={close}
          style={styles.cancelPress}
        >
          <Text style={[styles.cancelText, { color: palette.text }]}>Cancel</Text>
        </Pressable>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { width: "100%", height: SIZE, flexDirection: "row", alignItems: "center" },
  field: {
    height: SIZE,
    borderRadius: SIZE / 2,
    flexDirection: "row",
    alignItems: "center",
    overflow: "hidden",
  },
  iconSlot: { width: SIZE, height: SIZE, alignItems: "center", justifyContent: "center" },
  magnifier: { width: 18, height: 18 },
  ring: { width: 12, height: 12, borderRadius: 6, borderWidth: 2 },
  handle: {
    position: "absolute",
    left: 9.2,
    top: 11.7,
    width: 7,
    height: 2,
    borderRadius: 1,
    transform: [{ rotate: "45deg" }],
  },
  inputSlot: { flex: 1, height: SIZE, justifyContent: "center" },
  input: { height: SIZE, fontSize: 16, paddingRight: 8, outlineWidth: 0 },
  clear: {
    width: 20,
    height: 20,
    borderRadius: 10,
    marginRight: 12,
    alignItems: "center",
    justifyContent: "center",
  },
  clearGlyph: { fontSize: 16, lineHeight: 18, fontWeight: "700" },
  cancel: { position: "absolute", right: 0, width: CANCEL_WIDTH, height: SIZE },
  cancelPress: { flex: 1, alignItems: "center", justifyContent: "center", paddingLeft: 8 },
  cancelText: { fontSize: 16, fontWeight: "500" },
});
```

---

# Intro Pager

> A swipeable React Native onboarding pager where the art drifts against the text, the dots stretch, and Next turns into the final action.

Install: `npx @modus-ui/cli add intro-pager`

A swipeable onboarding pager. The art drifts against the text as you swipe, the dots stretch to show where you are, and the button turns from Next into the final action on the last page. On the web it also pages with a mouse drag, which a scroll view does not do by itself. With reduced motion the art stays put. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add intro-pager
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/intro-pager.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text, View } from "react-native";
import { IntroPager } from "@/components/ui/intro-pager";

const pages = [
  {
    id: "plan",
    title: "Plan the week",
    description: "See every task on the day it belongs to.",
    art: <View style={{ width: 160, height: 160, borderRadius: 80, backgroundColor: "#c7d2fe" }} />,
  },
  {
    id: "focus",
    title: "Stay in focus",
    description: "One card at a time.",
    art: <Text style={{ fontSize: 96 }}>🎯</Text>,
  },
];

export default function Example() {
  return (
    <View style={{ flex: 1 }}>
      <IntroPager pages={pages} onDone={() => console.log("done")} />
    </View>
  );
}
```

The pager fills its parent, so give the parent a height (a screen with `flex: 1` is enough).

## Props

| Prop        | Type                        | Default         | Description                                                                             |
| :---------- | :-------------------------- | :-------------- | :-------------------------------------------------------------------------------------- |
| `pages`     | `IntroPage[]`               | -               | The pages. Each has an `id`, a `title`, a `description` and an `art` node.              |
| `onDone`    | `() => void`                | -               | Called when the button is pressed on the last page.                                     |
| `skipLabel` | `string`                    | `"Skip"`        | Label of the skip button, shown until the last page.                                    |
| `nextLabel` | `string`                    | `"Next"`        | Label of the button until the last page.                                                |
| `doneLabel` | `string`                    | `"Get started"` | Label the button morphs into on the last page.                                          |
| `colors`    | `Partial<IntroPagerColors>` | -               | Overrides `background`, `title`, `text`, `dot`, `activeDot`, `button` and `buttonText`. |
| `style`     | `StyleProp<ViewStyle>`      | -               | Style for the container.                                                                |

## Source

`components/ui/intro-pager.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ElementRef, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  ScrollView,
  StyleSheet,
  Text,
  View,
  type NativeScrollEvent,
  type NativeSyntheticEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const BUTTON_MIN = 120;
const BUTTON_MAX = 184;
const IS_WEB = Platform.OS === "web";

export interface IntroPage {
  id: string;
  title: string;
  description: string;
  /** The picture above the text. It is centered in its area and drifts against the text as you swipe. */
  art: ReactNode;
}

export interface IntroPagerColors {
  background: string;
  title: string;
  text: string;
  dot: string;
  activeDot: string;
  button: string;
  buttonText: string;
}

const DEFAULT_COLORS: IntroPagerColors = {
  background: "#ffffff",
  title: "#111827",
  text: "#6b7280",
  dot: "#d1d5db",
  activeDot: "#4f46e5",
  button: "#4f46e5",
  buttonText: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface IntroPagerProps {
  pages: IntroPage[];
  /** Called when the button is pressed on the last page. */
  onDone: () => void;
  /** Label of the skip button, shown until the last page. */
  skipLabel?: string;
  /** Label of the button until the last page. */
  nextLabel?: string;
  /** Label the button morphs into on the last page. */
  doneLabel?: string;
  colors?: Partial<IntroPagerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A swipeable onboarding pager. The art drifts against the text as you swipe, the dots stretch to
 * show where you are, and the button turns from Next into the final action on the last page. On
 * the web it also pages with a mouse drag, which a scroll view does not do by itself. The pager
 * fills its parent, so give the parent a height.
 */
export function IntroPager({
  pages,
  onDone,
  skipLabel = "Skip",
  nextLabel = "Next",
  doneLabel = "Get started",
  colors,
  style,
}: IntroPagerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const [index, setIndex] = useState(0);
  const [dragging, setDragging] = useState(false);
  const scroll = useRef<ElementRef<typeof ScrollView>>(null);
  // Width drives the dots, so the scroll position uses the JS driver on every platform.
  const scrollX = useRef(new Animated.Value(0)).current;
  const offset = useRef(0);
  const live = useRef({ width, index, count: pages.length });
  live.current = { width, index, count: pages.length };

  const count = pages.length;
  const last = index >= count - 1;

  const goTo = (page: number, animated = true) => {
    const target = Math.max(0, Math.min(count - 1, page));
    scroll.current?.scrollTo({ x: target * width, animated: animated && !reduceMotion });
  };

  const onScroll = Animated.event([{ nativeEvent: { contentOffset: { x: scrollX } } }], {
    useNativeDriver: false,
    listener: (event: NativeSyntheticEvent<NativeScrollEvent>) => {
      offset.current = event.nativeEvent.contentOffset.x;
      const { width: w, index: current } = live.current;
      const page = w > 0 ? Math.round(offset.current / w) : 0;
      if (page !== current) setIndex(page);
    },
  });

  // Mouse drag for the web: browsers scroll a div with touch and wheel but not with a mouse drag.
  const mouse = useRef(false);
  const dragStart = useRef(0);
  const pan = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        IS_WEB && mouse.current && Math.abs(g.dx) > 6 && Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => {
        dragStart.current = offset.current;
        setDragging(true);
      },
      onPanResponderMove: (_, g) => {
        scroll.current?.scrollTo({ x: dragStart.current - g.dx, animated: false });
      },
      onPanResponderRelease: (_, g) => {
        const { width: w, count: total } = live.current;
        const start = Math.round(dragStart.current / w);
        const flick = Math.abs(g.vx) > 0.4;
        const forward = g.dx < -w * 0.2 || (flick && g.vx < 0);
        const back = g.dx > w * 0.2 || (flick && g.vx > 0);
        const target = Math.max(0, Math.min(total - 1, start + (forward ? 1 : back ? -1 : 0)));
        setDragging(false);
        scroll.current?.scrollTo({ x: target * w, animated: true });
      },
      onPanResponderTerminate: () => setDragging(false),
    }),
  ).current;

  // Built once per width so react-native-web does not restart animations on every page change.
  const motion = useMemo(() => {
    const pageRange = (i: number) => [(i - 1) * width, i * width, (i + 1) * width];
    const still = (value: number) => ({ inputRange: [0, 1], outputRange: [value, value] });
    return {
      art: pages.map((_, i) =>
        width === 0 || reduceMotion
          ? scrollX.interpolate(still(0))
          : scrollX.interpolate({
              inputRange: pageRange(i),
              outputRange: [width * 0.35, 0, -width * 0.35],
            }),
      ),
      fade: pages.map((_, i) =>
        width === 0 || reduceMotion
          ? scrollX.interpolate(still(1))
          : scrollX.interpolate({
              inputRange: pageRange(i),
              outputRange: [0, 1, 0],
              extrapolate: "clamp",
            }),
      ),
      dotWidth: pages.map((_, i) =>
        width === 0
          ? scrollX.interpolate(still(8))
          : scrollX.interpolate({
              inputRange: pageRange(i),
              outputRange: [8, 24, 8],
              extrapolate: "clamp",
            }),
      ),
      dotFill: pages.map((_, i) =>
        width === 0
          ? scrollX.interpolate(still(0))
          : scrollX.interpolate({
              inputRange: pageRange(i),
              outputRange: [0, 1, 0],
              extrapolate: "clamp",
            }),
      ),
      toDone: scrollX.interpolate({
        inputRange: [Math.max(0, (count - 2) * width), Math.max(1, (count - 1) * width)],
        outputRange: [0, 1],
        extrapolate: "clamp",
      }),
    };
  }, [scrollX, width, count, pages, reduceMotion]);

  const buttonWidth = motion.toDone.interpolate({
    inputRange: [0, 1],
    outputRange: [BUTTON_MIN, BUTTON_MAX],
  });
  const nextOpacity = motion.toDone.interpolate({ inputRange: [0, 1], outputRange: [1, 0] });
  const skipOpacity = motion.toDone.interpolate({ inputRange: [0, 1], outputRange: [1, 0] });

  return (
    <View
      onLayout={(event) => setWidth(event.nativeEvent.layout.width)}
      style={[styles.root, { backgroundColor: palette.background }, style]}
    >
      {width > 0 ? (
        <View
          style={styles.pages}
          onPointerDown={(event) => {
            mouse.current = event.nativeEvent.pointerType === "mouse";
          }}
          {...pan.panHandlers}
        >
          <Animated.ScrollView
            ref={scroll}
            horizontal
            pagingEnabled={!dragging}
            showsHorizontalScrollIndicator={false}
            scrollEventThrottle={16}
            onScroll={onScroll}
            style={styles.scroll}
            contentContainerStyle={styles.track}
          >
            {pages.map((page, i) => (
              <View
                key={page.id}
                role="group"
                accessibilityLabel={`Page ${i + 1} of ${count}`}
                style={[styles.page, { width }]}
              >
                <Animated.View style={[styles.art, { transform: [{ translateX: motion.art[i] }] }]}>
                  {page.art}
                </Animated.View>
                <Animated.View style={[styles.copy, { opacity: motion.fade[i] }]}>
                  <Text accessibilityRole="header" style={[styles.title, { color: palette.title }]}>
                    {page.title}
                  </Text>
                  <Text style={[styles.description, { color: palette.text }]}>
                    {page.description}
                  </Text>
                </Animated.View>
              </View>
            ))}
          </Animated.ScrollView>
        </View>
      ) : null}
      <Animated.View
        pointerEvents={last ? "none" : "auto"}
        style={[styles.skip, { opacity: skipOpacity }]}
      >
        <Pressable
          accessibilityRole="button"
          accessibilityLabel={skipLabel}
          hitSlop={8}
          onPress={() => goTo(count - 1)}
        >
          <Text style={[styles.skipText, { color: palette.text }]}>{skipLabel}</Text>
        </Pressable>
      </Animated.View>
      <View style={styles.footer}>
        <View accessible={false} style={styles.dots}>
          {pages.map((page, i) => (
            <Animated.View
              key={page.id}
              style={[styles.dot, { width: motion.dotWidth[i], backgroundColor: palette.dot }]}
            >
              <Animated.View
                style={[
                  styles.dotFill,
                  { backgroundColor: palette.activeDot, opacity: motion.dotFill[i] },
                ]}
              />
            </Animated.View>
          ))}
        </View>
        <Animated.View style={{ width: buttonWidth }}>
          <Pressable
            accessibilityRole="button"
            accessibilityLabel={last ? doneLabel : nextLabel}
            onPress={() => (last ? onDone() : goTo(index + 1))}
            style={({ pressed }) => [
              styles.button,
              { backgroundColor: palette.button },
              pressed && styles.pressed,
            ]}
          >
            <Animated.Text
              style={[styles.label, { color: palette.buttonText, opacity: nextOpacity }]}
            >
              {nextLabel}
            </Animated.Text>
            <Animated.Text
              style={[
                styles.label,
                styles.labelDone,
                { color: palette.buttonText, opacity: motion.toDone },
              ]}
            >
              {doneLabel}
            </Animated.Text>
          </Pressable>
        </Animated.View>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, overflow: "hidden" },
  pages: { flex: 1, userSelect: "none" },
  scroll: { flex: 1 },
  track: { flexGrow: 1 },
  page: { paddingHorizontal: 32, paddingTop: 56 },
  art: { flex: 1, alignItems: "center", justifyContent: "center" },
  copy: { paddingTop: 24, paddingBottom: 16, gap: 10 },
  title: { fontSize: 28, fontWeight: "800", textAlign: "center" },
  description: { fontSize: 16, lineHeight: 23, textAlign: "center" },
  skip: { position: "absolute", top: 18, right: 22 },
  skipText: { fontSize: 15, fontWeight: "600" },
  footer: {
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    paddingHorizontal: 24,
    paddingTop: 8,
    paddingBottom: 24,
  },
  dots: { flexDirection: "row", gap: 6, alignItems: "center" },
  dot: { height: 8, borderRadius: 4, overflow: "hidden" },
  dotFill: { flex: 1 },
  button: { height: 48, borderRadius: 24, alignItems: "center", justifyContent: "center" },
  pressed: { opacity: 0.85 },
  label: { fontSize: 16, fontWeight: "700" },
  labelDone: { position: "absolute" },
});
```

---

# Drag List

> A React Native reorderable list where you drag a grip and the other rows spring out of the way, with move actions for screen readers.

Install: `npx @modus-ui/cli add drag-list`

A reorderable list. Press the grip on a row and drag: the row lifts and follows the pointer, the rows it passes spring out of the way, and on release it settles into its slot. Each grip is also an accessible control with move up and move down actions, so reordering never needs a gesture. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add drag-list
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/drag-list.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Text } from "react-native";
import { DragList } from "@/components/ui/drag-list";

export default function Example() {
  const [items, setItems] = useState([
    { id: "a", title: "First" },
    { id: "b", title: "Second" },
    { id: "c", title: "Third" },
  ]);

  return (
    <DragList
      data={items}
      keyExtractor={(item) => item.id}
      onReorder={setItems}
      renderItem={(item) => <Text style={{ padding: 20 }}>{item.title}</Text>}
    />
  );
}
```

The list is controlled: it reorders only when you pass it a new `data`. It is as tall as its rows, so put it inside a `ScrollView` if there are many.

## Props

| Prop           | Type                                                   | Default | Description                                                                                    |
| :------------- | :----------------------------------------------------- | :------ | :--------------------------------------------------------------------------------------------- |
| `data`         | `T[]`                                                  | -       | The items, in order. The list reorders only when `data` does.                                  |
| `renderItem`   | `(item: T, state: { dragging: boolean }) => ReactNode` | -       | Renders a row's content. The grip handle is added beside it.                                   |
| `keyExtractor` | `(item: T, index: number) => string`                   | -       | A stable key for each item.                                                                    |
| `onReorder`    | `(next: T[]) => void`                                  | -       | Called once, after a dragged row has settled, with the new order. Not called if nothing moved. |
| `rowHeight`    | `number`                                               | `64`    | Height of every row. Rows have a fixed height so slots can be computed exactly.                |
| `colors`       | `Partial<DragListColors>`                              | -       | Overrides `row`, `border` and `handle`.                                                        |
| `style`        | `StyleProp<ViewStyle>`                                 | -       | Style for the list container.                                                                  |

## Source

`components/ui/drag-list.tsx`

```tsx
import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const HANDLE_WIDTH = 48;

export interface DragListColors {
  row: string;
  border: string;
  handle: string;
}

const DEFAULT_COLORS: DragListColors = {
  row: "#ffffff",
  border: "#e5e7eb",
  handle: "#9ca3af",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface DragListProps<T> {
  /** The items, in order. The list is controlled: it reorders only when `data` does. */
  data: T[];
  /** Renders a row's content. The grip handle is added beside it. */
  renderItem: (item: T, state: { dragging: boolean }) => ReactNode;
  keyExtractor: (item: T, index: number) => string;
  /** Called once, after a dragged row has settled, with the new order. Not called if nothing moved. */
  onReorder: (next: T[]) => void;
  /** Height of every row. Rows have a fixed height so slots can be computed exactly. */
  rowHeight?: number;
  colors?: Partial<DragListColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A reorderable list. Press the grip on a row and drag: the row lifts and follows the pointer, the
 * rows it passes spring out of the way, and on release it settles into its slot. Each grip is also
 * an accessible control with move up and move down actions, so reordering never needs a gesture.
 */
export function DragList<T>({
  data,
  renderItem,
  keyExtractor,
  onReorder,
  rowHeight = 64,
  colors,
  style,
}: DragListProps<T>) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [draggingKey, setDraggingKey] = useState<string | null>(null);

  const keys = data.map((item, index) => keyExtractor(item, index));
  const order = keys.join("\u0000");
  // Per-row displacement from the row's resting slot, while a drag is in progress.
  const offsets = useRef(new Map<string, Animated.Value>()).current;
  const offsetOf = (key: string) => {
    let value = offsets.get(key);
    if (!value) {
      value = new Animated.Value(0);
      offsets.set(key, value);
    }
    return value;
  };

  const drag = useRef<{ key: string; from: number; target: number } | null>(null);
  const live = useRef({ data, keys, order, rowHeight, reduceMotion, onReorder });
  live.current = { data, keys, order, rowHeight, reduceMotion, onReorder };

  // A new order moves every row's resting slot, so the displacements start again from zero.
  useLayoutEffect(() => {
    offsets.forEach((value) => value.setValue(0));
  }, [order, offsets]);

  const glide = (value: Animated.Value, toValue: number, after?: () => void) => {
    if (live.current.reduceMotion) {
      value.setValue(toValue);
      after?.();
      return;
    }
    Animated.spring(value, {
      toValue,
      stiffness: 420,
      damping: 34,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start(after ? () => after() : undefined);
  };

  const controls = useRef({
    start: (key: string) => {
      const { keys: current } = live.current;
      const from = current.indexOf(key);
      if (from < 0) return;
      offsets.forEach((value) => value.stopAnimation());
      drag.current = { key, from, target: from };
      setDraggingKey(key);
    },
    move: (key: string, dy: number) => {
      const state = drag.current;
      if (!state || state.key !== key) return;
      const { keys: current, rowHeight: height } = live.current;
      const last = current.length - 1;
      const raw = Math.max(0, Math.min(last * height, state.from * height + dy));
      offsetOf(key).setValue(raw - state.from * height);
      const target = Math.max(0, Math.min(last, Math.round(raw / height)));
      if (target === state.target) return;
      state.target = target;
      current.forEach((other, index) => {
        if (index === state.from) return;
        let shift = 0;
        if (state.from < target && index > state.from && index <= target) shift = -height;
        if (state.from > target && index < state.from && index >= target) shift = height;
        glide(offsetOf(other), shift);
      });
    },
    end: (key: string) => {
      const state = drag.current;
      if (!state || state.key !== key) return;
      drag.current = null;
      setDraggingKey(null);
      const { from, target } = state;
      const { rowHeight: height } = live.current;
      glide(offsetOf(key), (target - from) * height, () => {
        const { data: items, order: before, onReorder: commit } = live.current;
        if (target === from) return;
        const next = [...items];
        const [moved] = next.splice(from, 1);
        next.splice(target, 0, moved);
        commit(next);
        // If the parent kept the old order, put the rows back.
        setTimeout(() => {
          if (live.current.order === before) offsets.forEach((value) => glide(value, 0));
        }, 0);
      });
    },
    nudge: (index: number, direction: -1 | 1) => {
      const { data: items, onReorder: commit } = live.current;
      const to = index + direction;
      if (to < 0 || to >= items.length) return;
      const next = [...items];
      const [moved] = next.splice(index, 1);
      next.splice(to, 0, moved);
      commit(next);
    },
  }).current;

  return (
    <View style={[{ height: data.length * rowHeight }, style]}>
      {data.map((item, index) => {
        const key = keys[index];
        return (
          <DragRow
            key={key}
            itemKey={key}
            index={index}
            height={rowHeight}
            offset={offsetOf(key)}
            dragging={draggingKey === key}
            anyDragging={draggingKey !== null}
            reduceMotion={reduceMotion}
            colors={palette}
            controls={controls}
          >
            {renderItem(item, { dragging: draggingKey === key })}
          </DragRow>
        );
      })}
    </View>
  );
}

interface DragRowProps {
  itemKey: string;
  index: number;
  height: number;
  offset: Animated.Value;
  dragging: boolean;
  anyDragging: boolean;
  reduceMotion: boolean;
  colors: DragListColors;
  controls: {
    start: (key: string) => void;
    move: (key: string, dy: number) => void;
    end: (key: string) => void;
    nudge: (index: number, direction: -1 | 1) => void;
  };
  children: ReactNode;
}

function DragRow({
  itemKey,
  index,
  height,
  offset,
  dragging,
  anyDragging,
  reduceMotion,
  colors,
  controls,
  children,
}: DragRowProps) {
  const lift = useRef(new Animated.Value(1)).current;
  const live = useRef({ itemKey, index });
  live.current = { itemKey, index };

  useEffect(() => {
    const toValue = dragging ? 1.03 : 1;
    if (reduceMotion) {
      lift.setValue(toValue);
      return;
    }
    Animated.spring(lift, {
      toValue,
      stiffness: 420,
      damping: 28,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [dragging, reduceMotion, lift]);

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: () => controls.start(live.current.itemKey),
      onPanResponderMove: (_, g) => controls.move(live.current.itemKey, g.dy),
      onPanResponderRelease: () => controls.end(live.current.itemKey),
      onPanResponderTerminate: () => controls.end(live.current.itemKey),
    }),
  ).current;

  return (
    <Animated.View
      style={[
        styles.row,
        {
          top: index * height,
          height,
          backgroundColor: colors.row,
          borderBottomColor: colors.border,
          zIndex: dragging ? 10 : 0,
          transform: [{ translateY: offset }, { scale: lift }],
        },
        dragging && styles.lifted,
      ]}
    >
      <View style={styles.content} pointerEvents={anyDragging ? "none" : "auto"}>
        {children}
      </View>
      <View
        {...pan.panHandlers}
        accessible
        accessibilityRole="button"
        accessibilityLabel="Reorder"
        accessibilityHint="Drag to move this row, or use the move actions"
        accessibilityActions={[
          { name: "moveUp", label: "Move up" },
          { name: "moveDown", label: "Move down" },
        ]}
        onAccessibilityAction={(event) =>
          controls.nudge(live.current.index, event.nativeEvent.actionName === "moveUp" ? -1 : 1)
        }
        style={styles.handle}
      >
        {[0, 1, 2].map((rowIndex) => (
          <View key={rowIndex} style={styles.grip}>
            <View style={[styles.dot, { backgroundColor: colors.handle }]} />
            <View style={[styles.dot, { backgroundColor: colors.handle }]} />
          </View>
        ))}
      </View>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  row: {
    position: "absolute",
    left: 0,
    right: 0,
    flexDirection: "row",
    alignItems: "center",
    borderBottomWidth: StyleSheet.hairlineWidth,
  },
  lifted: { boxShadow: "0 10px 24px rgba(0, 0, 0, 0.22)" },
  content: { flex: 1, minWidth: 0 },
  // userSelect keeps a mouse drag on the web from selecting text instead of moving the row.
  handle: {
    width: HANDLE_WIDTH,
    alignSelf: "stretch",
    alignItems: "center",
    justifyContent: "center",
    gap: 4,
    userSelect: "none",
  },
  grip: { flexDirection: "row", gap: 4 },
  dot: { width: 4, height: 4, borderRadius: 2 },
});
```

---

# Long Press Menu

> A React Native menu that springs out from a trigger you press and hold, with every item also exposed as an accessibility action.

Install: `npx @modus-ui/cli add long-press-menu`

Press and hold a trigger to open a menu beside it. The trigger shrinks a little under your finger, the menu springs out from its corner, and choosing an item, tapping elsewhere or pressing Escape folds it away. Every item is also an accessibility action on the trigger, so nothing depends on the long press. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add long-press-menu
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/long-press-menu.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text, View } from "react-native";
import { LongPressMenu } from "@/components/ui/long-press-menu";

export default function Example() {
  return (
    <LongPressMenu
      items={[
        { label: "Reply", onPress: () => console.log("reply") },
        { label: "Delete", destructive: true, onPress: () => console.log("delete") },
      ]}
    >
      <View style={{ padding: 16, borderRadius: 16, backgroundColor: "#eee" }}>
        <Text>Press and hold me</Text>
      </View>
    </LongPressMenu>
  );
}
```

On iOS and Android the menu opens in a transparent `Modal`, so a tap anywhere on the screen closes it. On the web it renders inline, which keeps it inside the page area you place it in.

## Props

| Prop        | Type                           | Default   | Description                                                                       |
| :---------- | :----------------------------- | :-------- | :-------------------------------------------------------------------------------- |
| `items`     | `LongPressMenuItem[]`          | -         | The menu entries. Each has a `label`, an `onPress` and an optional `destructive`. |
| `delay`     | `number`                       | `350`     | How long to hold, in milliseconds.                                                |
| `placement` | `"below" \| "above"`           | `"below"` | Which side of the trigger the menu opens on.                                      |
| `colors`    | `Partial<LongPressMenuColors>` | -         | Overrides `menu`, `text`, `destructive` and `border`.                             |
| `style`     | `StyleProp<ViewStyle>`         | -         | Style for the wrapper around the trigger.                                         |

## Source

`components/ui/long-press-menu.tsx`

```tsx
import { useEffect, useRef, useState, type ComponentRef, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Dimensions,
  Modal,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const GAP = 8;

export interface LongPressMenuItem {
  label: string;
  onPress: () => void;
  /** Draws the item in the destructive color. */
  destructive?: boolean;
}

export interface LongPressMenuColors {
  menu: string;
  text: string;
  destructive: string;
  border: string;
}

const DEFAULT_COLORS: LongPressMenuColors = {
  menu: "#ffffff",
  text: "#111827",
  destructive: "#dc2626",
  border: "#e5e7eb",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

interface Anchor {
  x: number;
  y: number;
  width: number;
  height: number;
}

export interface LongPressMenuProps {
  items: LongPressMenuItem[];
  /** The trigger. Press and hold it to open the menu. */
  children: ReactNode;
  /** How long to hold, in milliseconds. */
  delay?: number;
  /** Which side of the trigger the menu opens on. */
  placement?: "below" | "above";
  colors?: Partial<LongPressMenuColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * Press and hold a trigger to open a menu beside it. The trigger shrinks a little under your finger,
 * the menu springs out from its corner, and choosing an item, tapping elsewhere or pressing Escape
 * folds it away. Every item is also an accessibility action on the trigger, so nothing depends on
 * the long press.
 */
export function LongPressMenu({
  items,
  children,
  delay = 350,
  placement = "below",
  colors,
  style,
}: LongPressMenuProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [open, setOpen] = useState(false);
  const [anchor, setAnchor] = useState<Anchor | null>(null);
  const rootRef = useRef<ComponentRef<typeof View>>(null);
  const progress = useRef(new Animated.Value(0)).current;
  const squeeze = useRef(new Animated.Value(1)).current;
  const below = placement === "below";

  const spring = (value: Animated.Value, toValue: number) => {
    if (reduceMotion) {
      value.setValue(toValue);
      return;
    }
    Animated.spring(value, {
      toValue,
      stiffness: 380,
      damping: 26,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  useEffect(() => {
    spring(progress, open ? 1 : 0);
    spring(squeeze, open ? 0.96 : 1);
    // spring only reads the reduced-motion flag, which is covered by the dependency below.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [open, reduceMotion]);

  useEffect(() => {
    if (!open || Platform.OS !== "web" || typeof document === "undefined") return;
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape") setOpen(false);
    };
    document.addEventListener("keydown", onKey);
    return () => document.removeEventListener("keydown", onKey);
  }, [open]);

  const show = () => {
    if (Platform.OS === "web") {
      setOpen(true);
      return;
    }
    // The native menu lives in a Modal, which needs the trigger's place on screen.
    rootRef.current?.measureInWindow((x, y, width, height) => {
      setAnchor({ x, y, width, height });
      setOpen(true);
    });
  };

  const choose = (item: LongPressMenuItem) => {
    setOpen(false);
    item.onPress();
  };

  const origin = below ? "top left" : "bottom left";
  const menu = (position: ViewStyle) => (
    <Animated.View
      accessibilityRole="menu"
      pointerEvents={open ? "auto" : "none"}
      style={[
        styles.menu,
        position,
        {
          backgroundColor: palette.menu,
          borderColor: palette.border,
          opacity: progress,
          transformOrigin: origin,
          transform: [
            { scale: progress.interpolate({ inputRange: [0, 1], outputRange: [0.82, 1] }) },
          ],
        },
      ]}
    >
      {items.map((item, index) => (
        <Pressable
          key={item.label}
          accessibilityRole="menuitem"
          accessibilityLabel={item.label}
          onPress={() => choose(item)}
          style={({ pressed }) => [
            styles.item,
            index > 0 && {
              borderTopColor: palette.border,
              borderTopWidth: StyleSheet.hairlineWidth,
            },
            pressed && styles.pressed,
          ]}
        >
          <Text
            style={[
              styles.itemText,
              { color: item.destructive ? palette.destructive : palette.text },
            ]}
          >
            {item.label}
          </Text>
        </Pressable>
      ))}
    </Animated.View>
  );

  const trigger = (
    <Animated.View style={{ transform: [{ scale: squeeze }] }}>
      <Pressable
        accessibilityRole="button"
        accessibilityHint="Long press for options"
        accessibilityActions={items.map((item) => ({ name: item.label, label: item.label }))}
        onAccessibilityAction={(event) =>
          items.find((item) => item.label === event.nativeEvent.actionName)?.onPress()
        }
        aria-haspopup="menu"
        aria-expanded={open}
        delayLongPress={delay}
        onLongPress={show}
        style={styles.trigger}
      >
        {children}
      </Pressable>
    </Animated.View>
  );

  if (Platform.OS !== "web") {
    // Touches outside a parent's bounds are ignored on Android, so an inline backdrop could not catch
    // a tap elsewhere. A transparent Modal covers the screen on native; on the web it would portal
    // out of the docs preview, so the web branch below renders inline instead.
    const windowHeight = Dimensions.get("window").height;
    const position: ViewStyle = anchor
      ? below
        ? { left: anchor.x, top: anchor.y + anchor.height + GAP }
        : { left: anchor.x, bottom: windowHeight - anchor.y + GAP }
      : {};
    return (
      <View ref={rootRef} collapsable={false} style={style}>
        {trigger}
        <Modal
          transparent
          visible={open}
          animationType="none"
          onRequestClose={() => setOpen(false)}
        >
          <Pressable
            accessibilityLabel="Close menu"
            onPress={() => setOpen(false)}
            style={styles.fill}
          />
          {menu(position)}
        </Modal>
      </View>
    );
  }

  return (
    <View style={[styles.root, { zIndex: open ? 50 : 0 }, style]}>
      {open ? (
        // Oversized and transparent: any press around the trigger closes the menu, and the frame it
        // sits in clips it to the preview.
        <Pressable
          accessibilityLabel="Close menu"
          onPress={() => setOpen(false)}
          style={styles.backdrop}
        />
      ) : null}
      {trigger}
      {menu(
        below
          ? { left: 0, top: "100%", marginTop: GAP }
          : { left: 0, bottom: "100%", marginBottom: GAP },
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  root: { alignSelf: "flex-start" },
  trigger: { alignSelf: "flex-start", userSelect: "none" },
  backdrop: { position: "absolute", top: -3000, right: -3000, bottom: -3000, left: -3000 },
  fill: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  menu: {
    position: "absolute",
    minWidth: 190,
    borderRadius: 14,
    borderWidth: 1,
    overflow: "hidden",
    zIndex: 60,
    boxShadow: "0 12px 32px rgba(0, 0, 0, 0.22)",
  },
  item: { paddingHorizontal: 16, paddingVertical: 13, minHeight: 44, justifyContent: "center" },
  itemText: { fontSize: 16, fontWeight: "500" },
  pressed: { opacity: 0.6 },
});
```

---

# Slide Confirm

> A React Native slide-to-confirm control. Drag the thumb to the end to confirm, release early to spring back, and confirm with a screen reader or keyboard action.

Install: `npx @modus-ui/cli add slide-confirm`

A "slide to confirm" control for actions that should not happen by accident, like paying or deleting. Drag the thumb along the track: the track fills behind it, the label fades away, and letting go early springs it back. It is also one button for screen readers and the keyboard, so confirming never depends on the gesture. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add slide-confirm
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/slide-confirm.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { SlideConfirm } from "@/components/ui/slide-confirm";

export default function Example() {
  return (
    <SlideConfirm
      label="Slide to pay"
      confirmedLabel="Paid"
      onConfirm={() => console.log("paid")}
    />
  );
}
```

`onConfirm` runs once per confirmation. With `resetAfter` set, the thumb springs back after that many milliseconds and can be used again.

## Props

| Prop             | Type                          | Default              | Description                                                                                             |
| :--------------- | :---------------------------- | :------------------- | :------------------------------------------------------------------------------------------------------ |
| `onConfirm`      | `() => void`                  | -                    | Called once when the thumb reaches the end, or when a screen reader or the keyboard activates it.       |
| `label`          | `string`                      | `"Slide to confirm"` | Text on the track before confirming.                                                                    |
| `confirmedLabel` | `string`                      | `"Confirmed"`        | Shown on the track once confirmed.                                                                      |
| `threshold`      | `number`                      | `0.9`                | Fraction of the track the thumb must cover for the slide to count.                                      |
| `height`         | `number`                      | `56`                 | Height of the track; the thumb is a little smaller.                                                     |
| `disabled`       | `boolean`                     | `false`              | Dims the control and ignores drags and activation.                                                      |
| `resetAfter`     | `number`                      | `0`                  | Milliseconds after confirming until the thumb springs back and can be used again. 0 keeps it confirmed. |
| `colors`         | `Partial<SlideConfirmColors>` | -                    | Overrides `track`, `fill`, `thumb`, `icon`, `text` and `confirmedText`.                                 |
| `style`          | `StyleProp<ViewStyle>`        | -                    | Style for the track.                                                                                    |

## Source

`components/ui/slide-confirm.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Gap between the thumb and the edge of the track.
const PAD = 4;

export interface SlideConfirmColors {
  track: string;
  fill: string;
  thumb: string;
  icon: string;
  text: string;
  confirmedText: string;
}

const DEFAULT_COLORS: SlideConfirmColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  thumb: "#ffffff",
  icon: "#4f46e5",
  text: "#374151",
  confirmedText: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SlideConfirmProps {
  /** Called once when the thumb reaches the end, or when a screen reader activates the control. */
  onConfirm: () => void;
  label?: string;
  /** Shown on the track once confirmed. */
  confirmedLabel?: string;
  /** Fraction of the track the thumb must cover for the slide to count. */
  threshold?: number;
  /** Height of the track; the thumb is a little smaller. */
  height?: number;
  disabled?: boolean;
  /** Milliseconds after confirming until the thumb springs back and can be used again. 0 keeps it confirmed. */
  resetAfter?: number;
  colors?: Partial<SlideConfirmColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A "slide to confirm" control for actions that should not happen by accident, like paying or
 * deleting. Drag the thumb along the track: the track fills behind it, the label fades away, and
 * letting go early springs it back. It is also one button for screen readers and the keyboard, so
 * confirming never depends on the gesture.
 */
export function SlideConfirm({
  onConfirm,
  label = "Slide to confirm",
  confirmedLabel = "Confirmed",
  threshold = 0.9,
  height = 56,
  disabled = false,
  resetAfter = 0,
  colors,
  style,
}: SlideConfirmProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [confirmed, setConfirmed] = useState(false);
  const thumb = height - PAD * 2;

  const x = useRef(new Animated.Value(0)).current;
  // How far the thumb can travel; the fill and the label are derived from it, so they stay in step.
  const travelValue = useRef(new Animated.Value(1)).current;
  const doneValue = useRef(new Animated.Value(0)).current;
  const [derived] = useState(() => {
    const progress = Animated.divide(x, travelValue);
    return {
      fill: Animated.subtract(x, travelValue),
      labelOpacity: progress.interpolate({
        inputRange: [0, 0.55],
        outputRange: [1, 0],
        extrapolate: "clamp",
      }),
      labelShift: progress.interpolate({ inputRange: [0, 1], outputRange: [0, 28] }),
    };
  });

  const fired = useRef(false);
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
  // The responder is created once, so it reads the latest props from here.
  const live = useRef({ travel: 1, threshold, disabled, reduceMotion, onConfirm, resetAfter });
  live.current = { ...live.current, threshold, disabled, reduceMotion, onConfirm, resetAfter };

  useEffect(() => () => clearTimeout(timer.current), []);

  const spring = (value: Animated.Value, toValue: number) => {
    if (live.current.reduceMotion) {
      value.setValue(toValue);
      return;
    }
    Animated.spring(value, {
      toValue,
      stiffness: 380,
      damping: 30,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const reset = () => {
    fired.current = false;
    setConfirmed(false);
    spring(x, 0);
    spring(doneValue, 0);
  };

  const complete = () => {
    if (fired.current || live.current.disabled) return;
    fired.current = true;
    setConfirmed(true);
    spring(x, live.current.travel);
    spring(doneValue, 1);
    live.current.onConfirm();
    if (live.current.resetAfter > 0) {
      timer.current = setTimeout(reset, live.current.resetAfter);
    }
  };

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => !live.current.disabled && !fired.current,
      onMoveShouldSetPanResponder: () => !live.current.disabled && !fired.current,
      onPanResponderGrant: () => x.stopAnimation(),
      onPanResponderMove: (_, g) => x.setValue(Math.max(0, Math.min(live.current.travel, g.dx))),
      onPanResponderRelease: (_, g) => {
        const { travel, threshold: needed } = live.current;
        if (g.dx >= travel * needed) complete();
        else spring(x, 0);
      },
      onPanResponderTerminate: () => spring(x, 0),
    }),
  ).current;

  const onLayout = (event: LayoutChangeEvent) => {
    const travel = Math.max(1, event.nativeEvent.layout.width - thumb - PAD * 2);
    live.current.travel = travel;
    travelValue.setValue(travel);
    if (fired.current) x.setValue(travel);
  };

  const spoken = confirmed ? confirmedLabel : label;

  return (
    <View
      accessible
      accessibilityRole="button"
      accessibilityLabel={spoken}
      aria-label={spoken}
      accessibilityState={{ disabled }}
      aria-disabled={disabled}
      accessibilityActions={[{ name: "activate", label }]}
      onAccessibilityAction={(event) => {
        if (event.nativeEvent.actionName === "activate") complete();
      }}
      focusable={!disabled}
      onKeyDown={(event) => {
        const key = event.nativeEvent.key;
        if (key === "Enter" || key === " ") complete();
      }}
      onLayout={onLayout}
      style={[
        styles.track,
        {
          height,
          borderRadius: height / 2,
          backgroundColor: palette.track,
          opacity: disabled ? 0.5 : 1,
        },
        style,
      ]}
    >
      <Animated.View
        pointerEvents="none"
        style={[
          styles.fill,
          {
            backgroundColor: palette.fill,
            borderRadius: height / 2,
            transform: [{ translateX: derived.fill }],
          },
        ]}
      />
      <Animated.View
        pointerEvents="none"
        style={[
          styles.center,
          {
            paddingLeft: thumb + PAD * 2,
            opacity: derived.labelOpacity,
            transform: [{ translateX: derived.labelShift }],
          },
        ]}
      >
        <Text numberOfLines={1} style={[styles.label, { color: palette.text }]}>
          {label}
        </Text>
      </Animated.View>
      <Animated.View pointerEvents="none" style={[styles.center, { opacity: doneValue }]}>
        <Text numberOfLines={1} style={[styles.label, { color: palette.confirmedText }]}>
          {confirmedLabel}
        </Text>
      </Animated.View>
      <Animated.View
        {...pan.panHandlers}
        style={[
          styles.thumb,
          {
            width: thumb,
            height: thumb,
            borderRadius: thumb / 2,
            backgroundColor: palette.thumb,
            transform: [{ translateX: x }],
          },
        ]}
      >
        <Text style={[styles.icon, { fontSize: thumb * 0.46, color: palette.icon }]}>
          {confirmed ? "✓" : "→"}
        </Text>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  // userSelect keeps a mouse drag on the web from selecting the label instead of moving the thumb.
  track: { overflow: "hidden", justifyContent: "center", userSelect: "none" },
  fill: { position: "absolute", top: 0, bottom: 0, left: 0, width: "100%" },
  center: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
    paddingHorizontal: 16,
  },
  label: { fontSize: 16, fontWeight: "600" },
  thumb: {
    position: "absolute",
    top: PAD,
    left: PAD,
    alignItems: "center",
    justifyContent: "center",
    boxShadow: "0 2px 6px rgba(0, 0, 0, 0.22)",
  },
  icon: { fontWeight: "700" },
});
```

---

# Calendar Strip

> A React Native horizontal strip of days with a pill that glides to the selected day, event dots, and full dates read out to screen readers.

Install: `npx @modus-ui/cli add calendar-strip`

A horizontal strip of days. A pill glides behind the selected day on a spring, and the strip scrolls to keep that day centred. Dates are local dates in `YYYY-MM-DD` form, so nothing shifts a day near midnight or across time zones. Each day is a button that reads out its full date, and days with events say so. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add calendar-strip
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/calendar-strip.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { CalendarStrip } from "@/components/ui/calendar-strip";

export default function Example() {
  const [day, setDay] = useState("2026-11-04");

  return (
    <CalendarStrip
      selected={day}
      onSelect={setDay}
      startDate="2026-11-01"
      marked={["2026-11-03", "2026-11-10"]}
    />
  );
}
```

## Props

| Prop        | Type                           | Default | Description                                                              |
| :---------- | :----------------------------- | :------ | :----------------------------------------------------------------------- |
| `selected`  | `string`                       | -       | The selected day, as `YYYY-MM-DD`.                                       |
| `onSelect`  | `(date: string) => void`       | -       | Called with the tapped day as `YYYY-MM-DD`.                              |
| `startDate` | `string`                       | -       | First day shown, as `YYYY-MM-DD`. Defaults to today in local time.       |
| `days`      | `number`                       | `21`    | How many days the strip covers.                                          |
| `marked`    | `string[]`                     | -       | Days (`YYYY-MM-DD`) that show a small dot, for example days with events. |
| `colors`    | `Partial<CalendarStripColors>` | -       | Overrides `pill`, `text`, `selectedText`, `mutedText` and `dot`.         |
| `style`     | `StyleProp<ViewStyle>`         | -       | Style for the container.                                                 |

## Source

`components/ui/calendar-strip.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  ScrollView,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const CELL = 52;
const CELL_HEIGHT = 76;
const PILL_INSET = 4;

export interface CalendarStripColors {
  pill: string;
  text: string;
  selectedText: string;
  mutedText: string;
  dot: string;
}

const DEFAULT_COLORS: CalendarStripColors = {
  pill: "#4f46e5",
  text: "#111827",
  selectedText: "#ffffff",
  mutedText: "#6b7280",
  dot: "#f59e0b",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

const pad = (n: number) => String(n).padStart(2, "0");

/** YYYY-MM-DD for a local date. Dates here are always local, never UTC, so a day never shifts. */
function toISO(date: Date) {
  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
}

/** Builds a local date from YYYY-MM-DD. `new Date("YYYY-MM-DD")` would be UTC and can land on the day before. */
function fromISO(iso: string) {
  const [year, month, day] = iso.split("-").map(Number);
  return new Date(year, month - 1, day);
}

export interface CalendarStripProps {
  /** The selected day, as YYYY-MM-DD. */
  selected: string;
  onSelect: (date: string) => void;
  /** First day shown, as YYYY-MM-DD. Defaults to today in local time. */
  startDate?: string;
  /** How many days the strip covers. */
  days?: number;
  /** Days (YYYY-MM-DD) that show a small dot, for example days with events. */
  marked?: string[];
  colors?: Partial<CalendarStripColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A horizontal strip of days. A pill glides behind the selected day on a spring, and the strip
 * scrolls to keep that day centred. Dates are local dates in YYYY-MM-DD form, so nothing shifts a
 * day near midnight or across time zones. Each day is a button that reads out its full date.
 */
export function CalendarStrip({
  selected,
  onSelect,
  startDate,
  days = 21,
  marked,
  colors,
  style,
}: CalendarStripProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const scroll = useRef<ElementRef<typeof ScrollView>>(null);
  const pillX = useRef(new Animated.Value(0)).current;
  const placed = useRef(false);

  const start = startDate ?? toISO(new Date());
  const list = useMemo(() => {
    const first = fromISO(start);
    return Array.from({ length: days }, (_, i) => {
      const date = new Date(first.getFullYear(), first.getMonth(), first.getDate() + i);
      return { iso: toISO(date), date };
    });
  }, [start, days]);

  const weekday = useMemo(() => new Intl.DateTimeFormat(undefined, { weekday: "short" }), []);
  const spoken = useMemo(
    () => new Intl.DateTimeFormat(undefined, { weekday: "long", day: "numeric", month: "long" }),
    [],
  );
  const markedSet = useMemo(() => new Set(marked), [marked]);

  const index = list.findIndex((day) => day.iso === selected);

  useEffect(() => {
    if (index < 0 || width === 0) return;
    const target = index * CELL;
    const offset = Math.max(0, target - (width - CELL) / 2);
    if (!placed.current || reduceMotion) {
      placed.current = true;
      pillX.setValue(target);
      scroll.current?.scrollTo({ x: offset, animated: false });
      return;
    }
    Animated.spring(pillX, {
      toValue: target,
      stiffness: 420,
      damping: 30,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
    scroll.current?.scrollTo({ x: offset, animated: true });
  }, [index, width, reduceMotion, pillX]);

  return (
    <View
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={style}
    >
      <ScrollView
        ref={scroll}
        horizontal
        showsHorizontalScrollIndicator={false}
        contentContainerStyle={{ width: list.length * CELL }}
      >
        {index >= 0 ? (
          <Animated.View
            pointerEvents="none"
            style={[
              styles.pill,
              {
                backgroundColor: palette.pill,
                transform: [{ translateX: pillX }],
              },
            ]}
          />
        ) : null}
        {list.map(({ iso, date }) => {
          const isSelected = iso === selected;
          const hasEvents = markedSet.has(iso);
          return (
            <Pressable
              key={iso}
              accessibilityRole="button"
              accessibilityLabel={`${spoken.format(date)}${hasEvents ? ", has events" : ""}`}
              accessibilityState={{ selected: isSelected }}
              aria-selected={isSelected}
              aria-current={isSelected ? "date" : undefined}
              onPress={() => onSelect(iso)}
              style={({ pressed }) => [styles.cell, pressed && styles.pressed]}
            >
              <Text
                style={[
                  styles.weekday,
                  { color: isSelected ? palette.selectedText : palette.mutedText },
                ]}
              >
                {weekday.format(date)}
              </Text>
              <Text
                style={[styles.day, { color: isSelected ? palette.selectedText : palette.text }]}
              >
                {date.getDate()}
              </Text>
              <View
                style={[styles.dot, { backgroundColor: palette.dot, opacity: hasEvents ? 1 : 0 }]}
              />
            </Pressable>
          );
        })}
      </ScrollView>
    </View>
  );
}

const styles = StyleSheet.create({
  pill: {
    position: "absolute",
    top: 0,
    bottom: 0,
    left: PILL_INSET,
    width: CELL - PILL_INSET * 2,
    borderRadius: (CELL - PILL_INSET * 2) / 2,
  },
  cell: {
    width: CELL,
    height: CELL_HEIGHT,
    alignItems: "center",
    justifyContent: "center",
    gap: 4,
    userSelect: "none",
  },
  pressed: { opacity: 0.7 },
  weekday: { fontSize: 11, fontWeight: "600", letterSpacing: 0.4, textTransform: "uppercase" },
  day: { fontSize: 19, fontWeight: "700" },
  dot: { width: 5, height: 5, borderRadius: 3 },
});
```

---

# Step Tracker

> A React Native progress tracker built from plain Views, with popping checks, a pulsing current step and connectors that fill as you advance.

Install: `npx @modus-ui/cli add step-tracker`

A progress tracker made from plain Views, with no icon or SVG packages. Complete steps show a check that pops in, the step in progress has a soft pulsing ring, and the connector between two steps fills as `current` moves past it. Vertical rows size to their text, and horizontal columns give each title two lines. Each step reads to a screen reader as "Step 2 of 4: Packed, current". Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add step-tracker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/step-tracker.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, View } from "react-native";
import { StepTracker } from "@/components/ui/step-tracker";

const steps = [
  { id: "ordered", title: "Ordered" },
  { id: "packed", title: "Packed", description: "Boxed at the warehouse" },
  { id: "shipped", title: "Shipped" },
];

export default function Example() {
  const [current, setCurrent] = useState(1);

  return (
    <View style={{ padding: 20 }}>
      <StepTracker steps={steps} current={current} />
      <Button title="Next" onPress={() => setCurrent((n) => n + 1)} />
    </View>
  );
}
```

In the horizontal layout each step gets a 64pt column, so it suits about four or five short titles on a phone; descriptions are shown only in the vertical layout.

## Props

| Prop          | Type                         | Default      | Description                                                                                    |
| :------------ | :--------------------------- | :----------- | :--------------------------------------------------------------------------------------------- |
| `steps`       | `StepTrackerStep[]`          | -            | The steps, each with an `id`, a `title` and an optional `description`.                         |
| `current`     | `number`                     | -            | Index of the step in progress. Earlier steps are complete; a value past the end completes all. |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Whether steps stack top to bottom or run left to right.                                        |
| `colors`      | `Partial<StepTrackerColors>` | -            | Overrides `complete`, `current`, `upcoming`, `line`, `text` and `mutedText`.                   |
| `style`       | `StyleProp<ViewStyle>`       | -            | Style for the container.                                                                       |

## Source

`components/ui/step-tracker.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const NODE = 32;
// Width of a step's column in the horizontal layout; the connectors share what is left.
const COLUMN = 64;

export interface StepTrackerStep {
  id: string;
  title: string;
  description?: string;
}

export interface StepTrackerColors {
  complete: string;
  current: string;
  upcoming: string;
  line: string;
  text: string;
  mutedText: string;
}

const DEFAULT_COLORS: StepTrackerColors = {
  complete: "#16a34a",
  current: "#4f46e5",
  upcoming: "#d1d5db",
  line: "#e5e7eb",
  text: "#111827",
  mutedText: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

type Status = "complete" | "current" | "upcoming";

export interface StepTrackerProps {
  steps: StepTrackerStep[];
  /** Index of the step in progress. Earlier steps are complete; a value past the end completes all. */
  current: number;
  orientation?: "vertical" | "horizontal";
  colors?: Partial<StepTrackerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A progress tracker made from plain Views. Complete steps show a check that pops in, the step in
 * progress has a soft pulsing ring, and the connector between two steps fills as `current` moves
 * past it. Vertical rows size to their text; horizontal columns give titles two lines.
 */
export function StepTracker({
  steps,
  current,
  orientation = "vertical",
  colors,
  style,
}: StepTrackerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const vertical = orientation === "vertical";

  const statusOf = (index: number): Status =>
    index < current ? "complete" : index === current ? "current" : "upcoming";

  const labelOf = (step: StepTrackerStep, index: number, status: Status) =>
    `Step ${index + 1} of ${steps.length}: ${step.title}, ${status}${
      step.description ? `. ${step.description}` : ""
    }`;

  return (
    <View role="list" style={[vertical ? undefined : styles.horizontal, style]}>
      {steps.map((step, index) => {
        const status = statusOf(index);
        const last = index === steps.length - 1;
        const titleColor = status === "upcoming" ? palette.mutedText : palette.text;

        if (vertical) {
          return (
            <View
              key={step.id}
              role="listitem"
              accessible
              accessibilityLabel={labelOf(step, index, status)}
              aria-current={status === "current" ? "step" : undefined}
              style={styles.row}
            >
              <View style={styles.rail}>
                <StepNode
                  index={index}
                  status={status}
                  palette={palette}
                  reduceMotion={reduceMotion}
                />
                {last ? null : (
                  <Connector
                    filled={index < current}
                    vertical
                    palette={palette}
                    reduceMotion={reduceMotion}
                  />
                )}
              </View>
              <View style={[styles.copy, last ? undefined : styles.copyGap]}>
                <Text style={[styles.title, { color: titleColor }]}>{step.title}</Text>
                {step.description ? (
                  <Text style={[styles.description, { color: palette.mutedText }]}>
                    {step.description}
                  </Text>
                ) : null}
              </View>
            </View>
          );
        }

        return (
          <View key={step.id} style={[styles.horizontalItem, last && styles.horizontalLast]}>
            <View
              role="listitem"
              accessible
              accessibilityLabel={labelOf(step, index, status)}
              aria-current={status === "current" ? "step" : undefined}
              style={styles.column}
            >
              <StepNode
                index={index}
                status={status}
                palette={palette}
                reduceMotion={reduceMotion}
              />
              <Text style={[styles.columnTitle, { color: titleColor }]} numberOfLines={2}>
                {step.title}
              </Text>
            </View>
            {last ? null : (
              <Connector
                filled={index < current}
                vertical={false}
                palette={palette}
                reduceMotion={reduceMotion}
              />
            )}
          </View>
        );
      })}
    </View>
  );
}

function StepNode({
  index,
  status,
  palette,
  reduceMotion,
}: {
  index: number;
  status: Status;
  palette: StepTrackerColors;
  reduceMotion: boolean;
}) {
  const scale = useRef(new Animated.Value(1)).current;
  // 1 means the ring is fully faded, which is where it rests unless this is the current step.
  const pulse = useRef(new Animated.Value(1)).current;
  const wasComplete = useRef(status === "complete");

  useEffect(() => {
    const complete = status === "complete";
    if (complete && !wasComplete.current && !reduceMotion) {
      scale.setValue(0.55);
      Animated.spring(scale, {
        toValue: 1,
        stiffness: 420,
        damping: 13,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
    wasComplete.current = complete;
  }, [status, reduceMotion, scale]);

  useEffect(() => {
    if (status !== "current" || reduceMotion) {
      pulse.stopAnimation();
      pulse.setValue(1);
      return;
    }
    pulse.setValue(0);
    const loop = Animated.loop(
      Animated.timing(pulse, { toValue: 1, duration: 1500, useNativeDriver: NATIVE_DRIVER }),
    );
    loop.start();
    return () => loop.stop();
  }, [status, reduceMotion, pulse]);

  const ringStyle = useMemo(
    () => ({
      transform: [{ scale: pulse.interpolate({ inputRange: [0, 1], outputRange: [1, 1.7] }) }],
      opacity: pulse.interpolate({ inputRange: [0, 1], outputRange: [0.4, 0] }),
    }),
    [pulse],
  );
  const nodeStyle = useMemo(() => ({ transform: [{ scale }] }), [scale]);

  const filled = status !== "upcoming";
  const fill = status === "complete" ? palette.complete : palette.current;

  return (
    <View style={styles.nodeWrap}>
      <Animated.View
        pointerEvents="none"
        style={[styles.ring, { borderColor: palette.current }, ringStyle]}
      />
      <Animated.View
        style={[
          styles.node,
          filled
            ? { backgroundColor: fill, borderColor: fill }
            : { backgroundColor: "transparent", borderColor: palette.upcoming },
          nodeStyle,
        ]}
      >
        <Text style={[styles.nodeText, { color: filled ? "#ffffff" : palette.mutedText }]}>
          {status === "complete" ? "✓" : index + 1}
        </Text>
      </Animated.View>
    </View>
  );
}

function Connector({
  filled,
  vertical,
  palette,
  reduceMotion,
}: {
  filled: boolean;
  vertical: boolean;
  palette: StepTrackerColors;
  reduceMotion: boolean;
}) {
  const progress = useRef(new Animated.Value(filled ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      progress.setValue(filled ? 1 : 0);
      return;
    }
    // Size is layout, so this runs on the JS driver.
    Animated.timing(progress, {
      toValue: filled ? 1 : 0,
      duration: 420,
      useNativeDriver: false,
    }).start();
  }, [filled, reduceMotion, progress]);

  const fillStyle = useMemo(() => {
    const size = progress.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] });
    return vertical
      ? { width: "100%" as const, height: size }
      : { height: "100%" as const, width: size };
  }, [progress, vertical]);

  return (
    <View
      accessibilityElementsHidden
      importantForAccessibility="no-hide-descendants"
      style={[
        vertical ? styles.trackVertical : styles.trackHorizontal,
        { backgroundColor: palette.line },
      ]}
    >
      <Animated.View style={[fillStyle, { backgroundColor: palette.complete }]} />
    </View>
  );
}

const styles = StyleSheet.create({
  horizontal: { flexDirection: "row", alignItems: "flex-start" },
  horizontalItem: { flexDirection: "row", flex: 1, alignItems: "flex-start" },
  // The last column has no connector, so it takes only its own width and the others share the rest.
  horizontalLast: { flex: 0 },
  row: { flexDirection: "row", gap: 14 },
  rail: { alignItems: "center", width: NODE },
  copy: { flex: 1, paddingTop: 5 },
  copyGap: { paddingBottom: 22 },
  title: { fontSize: 16, fontWeight: "600" },
  description: { marginTop: 2, fontSize: 13, lineHeight: 18 },
  column: { width: COLUMN, alignItems: "center", gap: 8 },
  columnTitle: { fontSize: 12, fontWeight: "600", textAlign: "center" },
  nodeWrap: { width: NODE, height: NODE, alignItems: "center", justifyContent: "center" },
  ring: {
    position: "absolute",
    top: 0,
    left: 0,
    width: NODE,
    height: NODE,
    borderRadius: NODE / 2,
    borderWidth: 2,
  },
  node: {
    width: NODE,
    height: NODE,
    borderRadius: NODE / 2,
    borderWidth: 2,
    alignItems: "center",
    justifyContent: "center",
  },
  nodeText: { fontSize: 14, fontWeight: "700" },
  trackVertical: {
    width: 2,
    flex: 1,
    minHeight: 14,
    marginVertical: 4,
    borderRadius: 1,
    overflow: "hidden",
  },
  trackHorizontal: {
    flex: 1,
    minWidth: 8,
    height: 2,
    marginTop: NODE / 2 - 1,
    borderRadius: 1,
    overflow: "hidden",
  },
});
```

---

# Chip Input

> A React Native tag input where Enter or a comma turns text into chips that pop in, wrap, and can each be removed.

Install: `npx @modus-ui/cli add chip-input`

A tag input. Type and press Enter or a comma to turn the text into a chip. Chips pop in, wrap onto new lines, and each has its own remove button with a full 44pt touch target. Backspace on an empty field removes the last chip, and leaving the field keeps whatever was typed instead of losing it. Additions and removals are announced to screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add chip-input
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/chip-input.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { ChipInput } from "@/components/ui/chip-input";

export default function Example() {
  const [tags, setTags] = useState(["design", "mobile"]);

  return (
    <ChipInput
      value={tags}
      onChange={setTags}
      placeholder="Add a topic"
      maxChips={6}
      validate={(text) => text.length <= 20}
    />
  );
}
```

Pasting `a,b,c` adds a and b as chips and leaves c in the field. A repeat is ignored in any letter case unless `allowDuplicates` is set.

## Props

| Prop              | Type                        | Default       | Description                                                                         |
| :---------------- | :-------------------------- | :------------ | :---------------------------------------------------------------------------------- |
| `value`           | `string[]`                  | -             | The current chips.                                                                  |
| `onChange`        | `(next: string[]) => void`  | -             | Called with the new list when a chip is added or removed.                           |
| `placeholder`     | `string`                    | `"Add a tag"` | Hint shown in the empty field, and the input's accessibility label.                 |
| `maxChips`        | `number`                    | `8`           | No more chips are added once there are this many.                                   |
| `validate`        | `(text: string) => boolean` | -             | Return false to reject a chip. It receives the trimmed text.                        |
| `allowDuplicates` | `boolean`                   | `false`       | Allow the same chip twice. Without it a repeat, in any letter case, is ignored.     |
| `colors`          | `Partial<ChipInputColors>`  | -             | Overrides `field`, `chip`, `chipText`, `text`, `placeholder`, `border` and `focus`. |
| `style`           | `StyleProp<ViewStyle>`      | -             | Style for the outer container.                                                      |

## Source

`components/ui/chip-input.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ComponentRef } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type TextInputKeyPressEvent,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface ChipInputColors {
  field: string;
  chip: string;
  chipText: string;
  text: string;
  placeholder: string;
  border: string;
  focus: string;
}

const DEFAULT_COLORS: ChipInputColors = {
  field: "#ffffff",
  chip: "#eef2ff",
  chipText: "#3730a3",
  text: "#111827",
  placeholder: "#9ca3af",
  border: "#d1d5db",
  focus: "#4f46e5",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ChipInputProps {
  value: string[];
  onChange: (next: string[]) => void;
  placeholder?: string;
  /** No more chips are added once there are this many. */
  maxChips?: number;
  /** Return false to reject a chip. It receives the trimmed text. */
  validate?: (text: string) => boolean;
  /** Allow the same chip twice. Without it a repeat, in any letter case, is ignored. */
  allowDuplicates?: boolean;
  colors?: Partial<ChipInputColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A tag input. Type and press Enter or comma to turn the text into a chip; chips pop in, wrap onto
 * new lines, and each has its own remove button. Backspace on an empty field removes the last chip,
 * and leaving the field keeps whatever was typed. Additions and removals are announced.
 */
export function ChipInput({
  value,
  onChange,
  placeholder = "Add a tag",
  maxChips = 8,
  validate,
  allowDuplicates = false,
  colors,
  style,
}: ChipInputProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const inputRef = useRef<ComponentRef<typeof TextInput>>(null);
  const [text, setText] = useState("");
  const [focused, setFocused] = useState(false);
  const [status, setStatus] = useState("");

  // Chips accepted from `raw`, in order, on top of `list`. Rejected text is dropped.
  const accept = (list: string[], raw: string[]) => {
    const next = [...list];
    const added: string[] = [];
    for (const piece of raw) {
      const chip = piece.trim();
      if (!chip || next.length >= maxChips) continue;
      if (!allowDuplicates && next.some((item) => item.toLowerCase() === chip.toLowerCase()))
        continue;
      if (validate && !validate(chip)) continue;
      next.push(chip);
      added.push(chip);
    }
    return { next, added };
  };

  const commit = (raw: string[]) => {
    const { next, added } = accept(value, raw);
    if (added.length > 0) {
      onChange(next);
      setStatus(`Added ${added.join(", ")}`);
    }
    return added.length > 0;
  };

  const handleChangeText = (incoming: string) => {
    if (!incoming.includes(",")) {
      setText(incoming);
      return;
    }
    // Typing or pasting "a,b,c" adds a and b; c stays in the field as the next chip.
    const pieces = incoming.split(",");
    const rest = pieces.pop() ?? "";
    commit(pieces);
    setText(rest);
  };

  const handleSubmit = () => {
    if (commit([text])) setText("");
  };

  const handleKeyPress = (event: TextInputKeyPressEvent) => {
    if (event.nativeEvent.key === "Backspace" && text === "" && value.length > 0) {
      removeAt(value.length - 1);
    }
  };

  const handleBlur = () => {
    setFocused(false);
    // Leaving the field keeps a half-typed chip instead of silently losing it.
    if (commit([text]) || text.trim() === "") setText("");
  };

  const removeAt = (index: number) => {
    setStatus(`Removed ${value[index]}`);
    onChange(value.filter((_, i) => i !== index));
  };

  return (
    <View style={style}>
      <Pressable
        accessible={false}
        onPress={() => inputRef.current?.focus()}
        style={[
          styles.field,
          { backgroundColor: palette.field, borderColor: focused ? palette.focus : palette.border },
        ]}
      >
        {value.map((chip, index) => (
          <Chip
            // The same text can appear twice when duplicates are allowed, so the position joins the key.
            key={`${index}:${chip}`}
            label={chip}
            palette={palette}
            reduceMotion={reduceMotion}
            onRemove={() => removeAt(index)}
          />
        ))}
        <TextInput
          ref={inputRef}
          value={text}
          onChangeText={handleChangeText}
          onSubmitEditing={handleSubmit}
          // react-native-web only reads blurOnSubmit; without it a single-line field blurs on Enter.
          blurOnSubmit={false}
          onKeyPress={handleKeyPress}
          onFocus={() => setFocused(true)}
          onBlur={handleBlur}
          submitBehavior="submit"
          returnKeyType="done"
          autoCapitalize="none"
          autoCorrect={false}
          placeholder={value.length >= maxChips ? "" : placeholder}
          placeholderTextColor={palette.placeholder}
          accessibilityLabel={placeholder}
          selectionColor={palette.focus}
          style={[styles.input, { color: palette.text }]}
        />
      </Pressable>
      <Text accessibilityLiveRegion="polite" aria-live="polite" style={styles.status}>
        {status}
      </Text>
    </View>
  );
}

function Chip({
  label,
  palette,
  reduceMotion,
  onRemove,
}: {
  label: string;
  palette: ChipInputColors;
  reduceMotion: boolean;
  onRemove: () => void;
}) {
  const pop = useRef(new Animated.Value(reduceMotion ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      pop.setValue(1);
      return;
    }
    Animated.spring(pop, {
      toValue: 1,
      stiffness: 380,
      damping: 16,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [reduceMotion, pop]);

  const popStyle = useMemo(
    () => ({
      opacity: pop.interpolate({ inputRange: [0, 0.6, 1], outputRange: [0, 1, 1] }),
      transform: [{ scale: pop.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) }],
    }),
    [pop],
  );

  return (
    <Animated.View style={[styles.chip, { backgroundColor: palette.chip }, popStyle]}>
      <Text numberOfLines={1} style={[styles.chipText, { color: palette.chipText }]}>
        {label}
      </Text>
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={`Remove ${label}`}
        // The glyph is small; the extra slop makes the touch target 44pt.
        hitSlop={{ top: 11, bottom: 11, left: 11, right: 11 }}
        onPress={onRemove}
        style={({ pressed }) => [styles.remove, pressed && styles.pressed]}
      >
        <Text style={[styles.removeText, { color: palette.chipText }]}>×</Text>
      </Pressable>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  field: {
    flexDirection: "row",
    flexWrap: "wrap",
    alignItems: "center",
    gap: 6,
    minHeight: 48,
    padding: 8,
    borderWidth: 1.5,
    borderRadius: 14,
  },
  chip: {
    flexDirection: "row",
    alignItems: "center",
    gap: 4,
    maxWidth: "100%",
    paddingLeft: 12,
    paddingRight: 6,
    height: 30,
    borderRadius: 15,
  },
  chipText: { flexShrink: 1, fontSize: 14, fontWeight: "600" },
  remove: {
    width: 22,
    height: 22,
    borderRadius: 11,
    alignItems: "center",
    justifyContent: "center",
  },
  removeText: { fontSize: 18, lineHeight: 20, fontWeight: "600" },
  pressed: { opacity: 0.6 },
  input: {
    flexGrow: 1,
    flexBasis: 90,
    minWidth: 90,
    height: 30,
    paddingVertical: 0,
    paddingHorizontal: 4,
    fontSize: 15,
    // On the web the browser draws its own focus outline; the field's border is the focus ring here.
    outlineWidth: 0,
  },
  // Present for screen readers only: one pixel, fully transparent.
  status: { position: "absolute", width: 1, height: 1, opacity: 0 },
});
```

---

# Typing Dots

> A React Native chat typing indicator whose dots bounce in a staggered wave, with a bubble behind them and a single spoken label.

Install: `npx @modus-ui/cli add typing-dots`

The three bouncing dots of a chat typing indicator. A wave runs through the dots, each lifting and brightening in turn. With reduced motion they sit still at a medium brightness. Screen readers hear one element with the label, not the dots. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add typing-dots
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/typing-dots.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { View } from "react-native";
import { TypingDots } from "@/components/ui/typing-dots";

export default function Example() {
  const someoneIsTyping = true;

  return <View style={{ padding: 16 }}>{someoneIsTyping ? <TypingDots /> : null}</View>;
}
```

Render it only while the other person is typing. For dots without the bubble, for example inside your own bubble, pass `bubble={false}`.

## Props

| Prop     | Type                        | Default    | Description                                                       |
| :------- | :-------------------------- | :--------- | :---------------------------------------------------------------- |
| `size`   | `number`                    | `8`        | Diameter of each dot.                                             |
| `count`  | `number`                    | `3`        | How many dots.                                                    |
| `bubble` | `boolean`                   | `true`     | Draw the rounded chat bubble behind the dots.                     |
| `speed`  | `number`                    | `1200`     | Length of one full wave, in milliseconds.                         |
| `label`  | `string`                    | `"Typing"` | Spoken label. The dots themselves are hidden from screen readers. |
| `colors` | `Partial<TypingDotsColors>` | -          | Overrides `dot` and `bubble`.                                     |
| `style`  | `StyleProp<ViewStyle>`      | -          | Style for the bubble, or for the dots when `bubble` is off.       |

## Source

`components/ui/typing-dots.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Share of one cycle each dot spends bouncing; the rest of the cycle it rests.
const BOUNCE_WINDOW = 0.4;
const REST_OPACITY = 0.5;

export interface TypingDotsColors {
  dot: string;
  bubble: string;
}

const DEFAULT_COLORS: TypingDotsColors = {
  dot: "#6b7280",
  bubble: "#e5e7eb",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface TypingDotsProps {
  /** Diameter of each dot. */
  size?: number;
  /** How many dots. */
  count?: number;
  /** Draw the rounded chat bubble behind the dots. */
  bubble?: boolean;
  /** Length of one full wave, in milliseconds. */
  speed?: number;
  /** Spoken label. The dots themselves are hidden from screen readers. */
  label?: string;
  colors?: Partial<TypingDotsColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * The three bouncing dots of a chat typing indicator. A wave runs through the dots, each lifting
 * and brightening in turn. With reduced motion they sit still at a medium brightness. Screen
 * readers hear one element with the label, not the dots.
 */
export function TypingDots({
  size = 8,
  count = 3,
  bubble = true,
  speed = 1200,
  label = "Typing",
  colors,
  style,
}: TypingDotsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  // One value drives every dot, so the wave can never drift out of step.
  const cycle = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    if (reduceMotion) {
      // Past every dot's window: all of them at rest.
      cycle.setValue(1);
      return;
    }
    cycle.setValue(0);
    const loop = Animated.loop(
      Animated.timing(cycle, {
        toValue: 1,
        duration: speed,
        easing: Easing.linear,
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [reduceMotion, speed, cycle]);

  // The interpolations are built once per size and count. Rebuilding them on every render makes
  // react-native-web drop the running animation.
  const motion = useMemo(() => {
    const step = (1 - BOUNCE_WINDOW) / Math.max(1, count);
    return Array.from({ length: count }, (_, i) => {
      const start = i * step;
      const inputRange = [0, start, start + BOUNCE_WINDOW / 2, start + BOUNCE_WINDOW, 1];
      return {
        translateY: cycle.interpolate({
          inputRange,
          outputRange: [0, 0, -size * 0.9, 0, 0],
        }),
        opacity: cycle.interpolate({
          inputRange,
          outputRange: [REST_OPACITY, REST_OPACITY, 1, REST_OPACITY, REST_OPACITY],
        }),
      };
    });
  }, [cycle, count, size]);

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel={label}
      aria-label={label}
      aria-busy
      style={[
        bubble && {
          alignSelf: "flex-start",
          paddingHorizontal: size * 1.5,
          paddingVertical: size * 1.2,
          borderRadius: size * 1.8,
          backgroundColor: palette.bubble,
        },
        style,
      ]}
    >
      <View
        accessibilityElementsHidden
        importantForAccessibility="no-hide-descendants"
        aria-hidden
        style={{ flexDirection: "row", alignItems: "center", gap: size * 0.7, height: size }}
      >
        {motion.map((dot, i) => (
          <Animated.View
            key={`dot-${i}`}
            style={{
              width: size,
              height: size,
              borderRadius: size / 2,
              backgroundColor: palette.dot,
              opacity: dot.opacity,
              transform: [{ translateY: dot.translateY }],
            }}
          />
        ))}
      </View>
    </View>
  );
}
```

---

# Marquee Ticker

> A React Native endless scrolling strip with a seamless loop, either direction, press and hold to pause, and a still fallback for reduced motion.

Install: `npx @modus-ui/cli add marquee-ticker`

An endless strip of scrolling content. The content is measured and repeated to fill the strip plus one spare copy, and the strip travels exactly one copy per loop, so the seam is invisible. Press and hold to pause. With reduced motion the content stands still, left aligned and clipped. Screen readers read the first copy only. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add marquee-ticker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/marquee-ticker.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text } from "react-native";
import { MarqueeTicker } from "@/components/ui/marquee-ticker";

export default function Example() {
  return (
    <MarqueeTicker speed={60}>
      <Text style={{ paddingVertical: 12 }}>
        Free shipping on orders over $50 · New arrivals every Friday
      </Text>
    </MarqueeTicker>
  );
}
```

The strip is as wide as its parent and as tall as its content.

## Props

| Prop           | Type                           | Default  | Description                                           |
| :------------- | :----------------------------- | :------- | :---------------------------------------------------- |
| `speed`        | `number`                       | `60`     | Scroll speed in pixels per second.                    |
| `direction`    | `"left" \| "right"`            | `"left"` | Which way the content travels.                        |
| `gap`          | `number`                       | `32`     | Space between one repeat of the content and the next. |
| `pauseOnPress` | `boolean`                      | `true`   | Pause while the strip is pressed and held.            |
| `colors`       | `Partial<MarqueeTickerColors>` | -        | Overrides `background`.                               |
| `style`        | `StyleProp<ViewStyle>`         | -        | Style for the strip.                                  |

## Source

`components/ui/marquee-ticker.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface MarqueeTickerColors {
  background: string;
}

const DEFAULT_COLORS: MarqueeTickerColors = {
  background: "transparent",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface MarqueeTickerProps {
  /** The content that scrolls. It repeats as many times as it takes to fill the strip. */
  children: ReactNode;
  /** Scroll speed in pixels per second. */
  speed?: number;
  /** Which way the content travels. */
  direction?: "left" | "right";
  /** Space between one repeat of the content and the next. */
  gap?: number;
  /** Pause while the strip is pressed and held. */
  pauseOnPress?: boolean;
  colors?: Partial<MarqueeTickerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * An endless strip of scrolling content. The content is measured and repeated to fill the strip
 * plus one spare copy; the strip then travels exactly one copy per loop, so the seam is
 * invisible. Press and hold to pause. With reduced motion the content stands still, left aligned
 * and clipped. Screen readers read the first copy only.
 */
export function MarqueeTicker({
  children,
  speed = 60,
  direction = "left",
  gap = 32,
  pauseOnPress = true,
  colors,
  style,
}: MarqueeTickerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [containerWidth, setContainerWidth] = useState(0);
  // Width of one repeat of the content, its trailing gap included.
  const [unit, setUnit] = useState(0);
  // 0 to 1 is one full copy of travel.
  const progress = useRef(new Animated.Value(0)).current;
  const running = useRef<Animated.CompositeAnimation | null>(null);
  const held = useRef(false);

  const total = unit > 0 ? (unit / Math.max(1, speed)) * 1000 : 0;

  const startFrom = (from: number) => {
    running.current?.stop();
    if (unit === 0) return;
    const loop = () => {
      progress.setValue(0);
      running.current = Animated.loop(
        Animated.timing(progress, {
          toValue: 1,
          duration: total,
          easing: Easing.linear,
          useNativeDriver: NATIVE_DRIVER,
        }),
      );
      running.current.start();
    };
    if (from <= 0) {
      loop();
      return;
    }
    // Finish the copy that was interrupted, then settle into the regular loop.
    progress.setValue(from);
    running.current = Animated.timing(progress, {
      toValue: 1,
      duration: total * (1 - from),
      easing: Easing.linear,
      useNativeDriver: NATIVE_DRIVER,
    });
    running.current.start(({ finished }) => {
      if (finished) loop();
    });
  };

  useEffect(() => {
    if (reduceMotion || unit === 0) {
      progress.setValue(direction === "left" ? 0 : 1);
      return;
    }
    startFrom(0);
    return () => running.current?.stop();
    // startFrom reads everything it needs from this render's unit, total and progress.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [reduceMotion, unit, speed, direction]);

  // Built once per width and direction: rebuilding it each render drops the running animation
  // on react-native-web.
  const translateX = useMemo(
    () =>
      progress.interpolate({
        inputRange: [0, 1],
        outputRange: direction === "left" ? [0, -unit] : [-unit, 0],
      }),
    [progress, unit, direction],
  );

  const copies = unit > 0 && containerWidth > 0 ? Math.ceil(containerWidth / unit) + 1 : 2;

  const pause = () => {
    if (!pauseOnPress || reduceMotion || unit === 0) return;
    held.current = true;
    running.current?.stop();
    progress.stopAnimation((value) => {
      // Released before the value came back: carry straight on.
      if (!held.current) startFrom(value >= 1 ? 0 : value);
    });
  };

  const resume = () => {
    if (!held.current) return;
    held.current = false;
    progress.stopAnimation((value) => startFrom(value >= 1 ? 0 : value));
  };

  return (
    <Pressable
      accessible={false}
      disabled={!pauseOnPress || reduceMotion}
      onPressIn={pause}
      onPressOut={resume}
      onLayout={(event: LayoutChangeEvent) => setContainerWidth(event.nativeEvent.layout.width)}
      style={[styles.root, { backgroundColor: palette.background }, style]}
    >
      <Animated.View
        style={[
          styles.track,
          unit > 0 && { width: unit * copies },
          { transform: [{ translateX }] },
        ]}
      >
        {Array.from({ length: copies }, (_, i) => (
          <View
            key={`copy-${i}`}
            onLayout={
              i === 0
                ? (event: LayoutChangeEvent) => {
                    const next = Math.round(event.nativeEvent.layout.width * 100) / 100;
                    setUnit((current) => (Math.abs(current - next) > 0.5 ? next : current));
                  }
                : undefined
            }
            {...(i > 0
              ? {
                  accessibilityElementsHidden: true,
                  importantForAccessibility: "no-hide-descendants" as const,
                  "aria-hidden": true,
                }
              : {})}
            style={[styles.copy, { paddingRight: gap }]}
          >
            {children}
          </View>
        ))}
      </Animated.View>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  // userSelect keeps a mouse press on the web from selecting the text instead of pausing.
  root: { overflow: "hidden", userSelect: "none" },
  track: { flexDirection: "row", alignSelf: "flex-start" },
  copy: { flexDirection: "row", alignItems: "center", flexShrink: 0 },
});
```

---

# Choice Chips

> React Native chips for one choice or several, blending to the selected color while a check mark opens in front of the label.

Install: `npx @modus-ui/cli add choice-chips`

Selectable chips for a single choice or several. Selecting blends the chip to its selected color and opens a check mark in front of the label, the chip pushes in while pressed, and everything wraps onto as many lines as it needs. Each chip is at least 44pt tall and reads as a radio button or checkbox to screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add choice-chips
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/choice-chips.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { ChoiceChips } from "@/components/ui/choice-chips";

const sizes = [
  { value: "s", label: "Small" },
  { value: "m", label: "Medium" },
  { value: "l", label: "Large" },
];

export default function Example() {
  const [size, setSize] = useState(["m"]);

  return <ChoiceChips min={1} options={sizes} value={size} onChange={setSize} />;
}
```

The selection is always an array of values. In the default single mode it holds at most one.

## Props

| Prop       | Type                         | Default | Description                                                                                            |
| :--------- | :--------------------------- | :------ | :----------------------------------------------------------------------------------------------------- |
| `options`  | `ChoiceChipOption[]`         | -       | The chips, each with a `value` and a `label`.                                                          |
| `value`    | `string[]`                   | -       | The selected values.                                                                                   |
| `onChange` | `(next: string[]) => void`   | -       | Called with the new selection.                                                                         |
| `multiple` | `boolean`                    | `false` | Allow more than one chip to be selected. Otherwise it behaves like a radio group.                      |
| `min`      | `number`                     | `0`     | The fewest chips that may stay selected. With `1`, the last selected chip cannot be turned off.        |
| `max`      | `number`                     | -       | The most chips that may be selected at once, in multiple mode. Further chips dim until one is removed. |
| `colors`   | `Partial<ChoiceChipsColors>` | -       | Overrides `chip`, `selectedChip`, `text`, `selectedText` and `border`.                                 |
| `style`    | `StyleProp<ViewStyle>`       | -       | Style for the container.                                                                               |

## Source

`components/ui/choice-chips.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Width reserved for the check mark, which opens up as a chip is selected.
const CHECK_WIDTH = 20;

export interface ChoiceChipOption {
  value: string;
  label: string;
}

export interface ChoiceChipsColors {
  chip: string;
  selectedChip: string;
  text: string;
  selectedText: string;
  border: string;
}

const DEFAULT_COLORS: ChoiceChipsColors = {
  chip: "#f3f4f6",
  selectedChip: "#4f46e5",
  text: "#374151",
  selectedText: "#ffffff",
  border: "#d1d5db",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ChoiceChipsProps {
  options: ChoiceChipOption[];
  /** The selected values. */
  value: string[];
  onChange: (next: string[]) => void;
  /** Allow more than one chip to be selected. Otherwise it behaves like a radio group. */
  multiple?: boolean;
  /** The fewest chips that may stay selected. With 1, the last selected chip cannot be turned off. */
  min?: number;
  /** The most chips that may be selected at once, in multiple mode. Further chips dim until one is removed. */
  max?: number;
  colors?: Partial<ChoiceChipsColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * Selectable chips for a single choice or several. Selecting blends the chip to its selected color
 * and opens a check mark in front of the label, the chip pushes in while pressed, and everything
 * wraps onto as many lines as it needs. Each chip is at least 44pt tall and reads as a radio button
 * or checkbox to screen readers.
 */
export function ChoiceChips({
  options,
  value,
  onChange,
  multiple = false,
  min = 0,
  max,
  colors,
  style,
}: ChoiceChipsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const atMax = multiple && max !== undefined && value.length >= max;

  const toggle = (option: string) => {
    const selected = value.includes(option);
    if (!multiple) {
      if (selected) {
        if (min < 1) onChange([]);
        return;
      }
      onChange([option]);
      return;
    }
    if (selected) {
      if (value.length > min) onChange(value.filter((item) => item !== option));
      return;
    }
    if (!atMax) onChange([...value, option]);
  };

  return (
    <View role={multiple ? "group" : "radiogroup"} style={[styles.row, style]}>
      {options.map((option) => {
        const selected = value.includes(option.value);
        return (
          <Chip
            key={option.value}
            label={option.label}
            selected={selected}
            multiple={multiple}
            disabled={!selected && atMax}
            reduceMotion={reduceMotion}
            palette={palette}
            onPress={() => toggle(option.value)}
          />
        );
      })}
    </View>
  );
}

interface ChipProps {
  label: string;
  selected: boolean;
  multiple: boolean;
  disabled: boolean;
  reduceMotion: boolean;
  palette: ChoiceChipsColors;
  onPress: () => void;
}

function Chip({ label, selected, multiple, disabled, reduceMotion, palette, onPress }: ChipProps) {
  // 0 = off, 1 = on. Everything that changes with selection reads from this one value.
  const progress = useRef(new Animated.Value(selected ? 1 : 0)).current;
  const press = useRef(new Animated.Value(1)).current;

  useEffect(() => {
    if (reduceMotion) {
      progress.setValue(selected ? 1 : 0);
      return;
    }
    Animated.spring(progress, {
      toValue: selected ? 1 : 0,
      stiffness: 380,
      damping: 26,
      mass: 1,
      // Width and color are layout and paint properties, so this one runs on the JS driver.
      useNativeDriver: false,
    }).start();
  }, [selected, reduceMotion, progress]);

  // Built once per palette so the animated styles keep their identity between renders.
  const animated = useMemo(() => {
    const clamp = { extrapolate: "clamp" as const };
    return {
      fill: progress.interpolate({ inputRange: [0, 1], outputRange: [0, 1], ...clamp }),
      checkWidth: progress.interpolate({
        inputRange: [0, 1],
        outputRange: [0, CHECK_WIDTH],
        ...clamp,
      }),
      checkScale: progress.interpolate({ inputRange: [0, 1], outputRange: [0.4, 1], ...clamp }),
      textColor: progress.interpolate({
        inputRange: [0, 1],
        outputRange: [palette.text, palette.selectedText],
        ...clamp,
      }),
      borderColor: progress.interpolate({
        inputRange: [0, 1],
        outputRange: [palette.border, palette.selectedChip],
        ...clamp,
      }),
    };
  }, [progress, palette.text, palette.selectedText, palette.border, palette.selectedChip]);

  const pressTo = (toValue: number) => {
    if (reduceMotion) return;
    Animated.spring(press, {
      toValue,
      stiffness: 520,
      damping: 28,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  return (
    <Animated.View style={{ transform: [{ scale: press }], opacity: disabled ? 0.45 : 1 }}>
      <Pressable
        role={multiple ? "checkbox" : "radio"}
        accessibilityState={{ checked: selected, disabled }}
        aria-checked={selected}
        aria-disabled={disabled}
        disabled={disabled}
        hitSlop={4}
        onPress={onPress}
        onPressIn={() => pressTo(0.95)}
        onPressOut={() => pressTo(1)}
      >
        <Animated.View
          style={[
            styles.chip,
            { backgroundColor: palette.chip, borderColor: animated.borderColor },
          ]}
        >
          <Animated.View
            pointerEvents="none"
            style={[styles.fill, { backgroundColor: palette.selectedChip, opacity: animated.fill }]}
          />
          <Animated.View style={[styles.check, { width: animated.checkWidth }]}>
            <Animated.Text
              style={[
                styles.checkGlyph,
                { color: palette.selectedText, transform: [{ scale: animated.checkScale }] },
              ]}
            >
              ✓
            </Animated.Text>
          </Animated.View>
          <Animated.Text style={[styles.label, { color: animated.textColor }]}>
            {label}
          </Animated.Text>
        </Animated.View>
      </Pressable>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", flexWrap: "wrap", gap: 10 },
  // userSelect keeps a quick double press on the web from selecting the label.
  chip: {
    minHeight: 44,
    paddingHorizontal: 16,
    borderRadius: 22,
    borderWidth: 1,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "center",
    overflow: "hidden",
    userSelect: "none",
  },
  fill: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  check: { overflow: "hidden", alignItems: "flex-start", justifyContent: "center" },
  checkGlyph: { fontSize: 14, fontWeight: "700" },
  label: { fontSize: 15, fontWeight: "600" },
});
```

---

# Hold Stepper

> A React Native plus and minus stepper that repeats while held, speeding up the longer you hold, with the value sliding in from the direction it moved.

Install: `npx @modus-ui/cli add hold-stepper`

A plus and minus stepper. A tap changes the value by one step. Holding a button repeats, slowly at first and then faster, and stops the moment the button is released, the pointer leaves or the limit is reached. The value slides in from the direction it moved. Both buttons are 44pt, the pair reads as one adjustable control to screen readers, and reduced motion drops the slide. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add hold-stepper
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/hold-stepper.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { HoldStepper } from "@/components/ui/hold-stepper";

export default function Example() {
  const [guests, setGuests] = useState(2);

  return <HoldStepper label="guests" min={1} max={12} value={guests} onChange={setGuests} />;
}
```

## Props

| Prop        | Type                         | Default | Description                                                                         |
| :---------- | :--------------------------- | :------ | :---------------------------------------------------------------------------------- |
| `value`     | `number`                     | -       | The current value.                                                                  |
| `onChange`  | `(next: number) => void`     | -       | Called with the new value on each tap and each repeat.                              |
| `min`       | `number`                     | `0`     | The lowest value. The minus button dims and stops here.                             |
| `max`       | `number`                     | `99`    | The highest value. The plus button dims and stops here.                             |
| `step`      | `number`                     | `1`     | How much one tap, or one repeat, changes the value.                                 |
| `holdDelay` | `number`                     | `400`   | Milliseconds a button must be held before it starts repeating.                      |
| `label`     | `string`                     | -       | What the value counts, for example "Guests". Spoken with the buttons and the group. |
| `colors`    | `Partial<HoldStepperColors>` | -       | Overrides `button`, `glyph` and `text`.                                             |
| `style`     | `StyleProp<ViewStyle>`       | -       | Style for the container.                                                            |

## Source

`components/ui/hold-stepper.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// The value slides this far in from the direction it moved.
const SLIDE = 14;
// Repeat speed: start slow, end fast.
const SLOW_MS = 120;
const FAST_MS = 40;

export interface HoldStepperColors {
  button: string;
  glyph: string;
  text: string;
}

const DEFAULT_COLORS: HoldStepperColors = {
  button: "#f3f4f6",
  glyph: "#111827",
  text: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface HoldStepperProps {
  value: number;
  onChange: (next: number) => void;
  /** The lowest value. The minus button dims and stops here. */
  min?: number;
  /** The highest value. The plus button dims and stops here. */
  max?: number;
  /** How much one tap, or one repeat, changes the value. */
  step?: number;
  /** Milliseconds a button must be held before it starts repeating. */
  holdDelay?: number;
  /** What the value counts, for example "Guests". Spoken with the buttons and the group. */
  label?: string;
  colors?: Partial<HoldStepperColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A plus and minus stepper. A tap changes the value by one step. Holding a button repeats, slowly
 * at first and then faster, and stops the moment the button is released, the pointer leaves or the
 * limit is reached. The value slides in from the direction it moved. Both buttons are 44pt, the
 * pair reads as one adjustable control to screen readers, and reduced motion drops the slide.
 */
export function HoldStepper({
  value,
  onChange,
  min = 0,
  max = 99,
  step = 1,
  holdDelay = 400,
  label,
  colors,
  style,
}: HoldStepperProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const slide = useRef(new Animated.Value(0)).current;
  const fade = useRef(new Animated.Value(1)).current;
  const previous = useRef(value);

  // The press handlers outlive a render, so they read what they need from here.
  const live = useRef({ value, min, max, step, holdDelay, onChange });
  live.current = { value, min, max, step, holdDelay, onChange };
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);

  const stop = () => {
    if (timer.current) clearTimeout(timer.current);
    timer.current = null;
  };

  // Slide the new value in from the side it came from.
  useEffect(() => {
    const direction = Math.sign(value - previous.current);
    previous.current = value;
    if (direction === 0 || reduceMotion) return;
    slide.setValue(direction * SLIDE);
    fade.setValue(0);
    Animated.parallel([
      Animated.spring(slide, {
        toValue: 0,
        stiffness: 420,
        damping: 28,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }),
      Animated.timing(fade, { toValue: 1, duration: 140, useNativeDriver: NATIVE_DRIVER }),
    ]).start();
  }, [value, reduceMotion, slide, fade]);

  useEffect(() => stop, []);

  /** Moves one step. Returns false when already at the limit. */
  const move = (direction: 1 | -1) => {
    const { value: current, min: low, max: high, step: size, onChange: change } = live.current;
    const next = Math.min(high, Math.max(low, current + direction * size));
    if (next === current) return false;
    // Updated now so a fast repeat does not read the value from before the parent re-rendered.
    live.current.value = next;
    change(next);
    return true;
  };

  const begin = (direction: 1 | -1) => {
    stop();
    if (!move(direction)) return;
    const startedAt = Date.now();
    const tick = () => {
      if (!move(direction)) {
        stop();
        return;
      }
      const held = Math.max(0, Date.now() - startedAt - live.current.holdDelay);
      const delay = Math.max(FAST_MS, SLOW_MS - held * ((SLOW_MS - FAST_MS) / 1000));
      timer.current = setTimeout(tick, delay);
    };
    timer.current = setTimeout(tick, live.current.holdDelay);
  };

  const atMin = value <= min;
  const atMax = value >= max;
  const noun = label ? ` ${label}` : "";

  return (
    <View
      accessible
      accessibilityRole="adjustable"
      accessibilityLabel={label ?? "Value"}
      accessibilityValue={{ min, max, now: value }}
      aria-valuemin={min}
      aria-valuemax={max}
      aria-valuenow={value}
      aria-valuetext={String(value)}
      accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(event) => {
        if (event.nativeEvent.actionName === "increment") move(1);
        else if (event.nativeEvent.actionName === "decrement") move(-1);
      }}
      style={[styles.row, style]}
    >
      <StepButton
        glyph="minus"
        label={`Decrease${noun}`}
        disabled={atMin}
        palette={palette}
        reduceMotion={reduceMotion}
        onPressIn={() => begin(-1)}
        onRelease={stop}
      />
      <View style={styles.valueBox}>
        <Animated.Text
          style={[
            styles.value,
            { color: palette.text, opacity: fade, transform: [{ translateY: slide }] },
          ]}
        >
          {value}
        </Animated.Text>
      </View>
      <StepButton
        glyph="plus"
        label={`Increase${noun}`}
        disabled={atMax}
        palette={palette}
        reduceMotion={reduceMotion}
        onPressIn={() => begin(1)}
        onRelease={stop}
      />
    </View>
  );
}

interface StepButtonProps {
  glyph: "plus" | "minus";
  label: string;
  disabled: boolean;
  palette: HoldStepperColors;
  reduceMotion: boolean;
  onPressIn: () => void;
  onRelease: () => void;
}

function StepButton({
  glyph,
  label,
  disabled,
  palette,
  reduceMotion,
  onPressIn,
  onRelease,
}: StepButtonProps) {
  const scale = useRef(new Animated.Value(1)).current;
  // A press that began this render's gesture, so a keyboard click is not counted twice.
  const stepped = useRef(false);

  const scaleTo = (toValue: number) => {
    if (reduceMotion) return;
    Animated.spring(scale, {
      toValue,
      stiffness: 520,
      damping: 28,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  return (
    <Animated.View style={{ transform: [{ scale }], opacity: disabled ? 0.35 : 1 }}>
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={label}
        aria-label={label}
        accessibilityState={{ disabled }}
        aria-disabled={disabled}
        disabled={disabled}
        onPressIn={() => {
          stepped.current = true;
          scaleTo(0.9);
          onPressIn();
        }}
        onPress={() => {
          // Pointer and touch presses already stepped in onPressIn; this covers a keyboard click.
          if (!stepped.current) onPressIn();
          stepped.current = false;
        }}
        onPressOut={() => {
          scaleTo(1);
          onRelease();
        }}
        onBlur={onRelease}
        style={[styles.button, { backgroundColor: palette.button }]}
      >
        <View style={[styles.bar, { backgroundColor: palette.glyph }]} />
        {glyph === "plus" ? (
          <View style={[styles.bar, styles.barUp, { backgroundColor: palette.glyph }]} />
        ) : null}
      </Pressable>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 6, alignSelf: "flex-start" },
  // userSelect keeps a mouse hold on the web from selecting text instead of repeating.
  button: {
    width: 44,
    height: 44,
    borderRadius: 22,
    alignItems: "center",
    justifyContent: "center",
    userSelect: "none",
  },
  bar: { position: "absolute", width: 16, height: 2.5, borderRadius: 2 },
  barUp: { transform: [{ rotate: "90deg" }] },
  valueBox: {
    minWidth: 56,
    height: 40,
    alignItems: "center",
    justifyContent: "center",
    overflow: "hidden",
  },
  value: { fontSize: 24, fontWeight: "700", fontVariant: ["tabular-nums"] },
});
```

---

# Action Tray

> A React Native bottom action list that slides up over a dimmed backdrop, with grouped actions, a separate cancel button and drag to dismiss.

Install: `npx @modus-ui/cli add action-tray`

A bottom action list in the style of a native action sheet. It slides up from the bottom of its parent over a dimmed backdrop, with the actions as one rounded group and Cancel as a separate button. Tap the backdrop, press Escape on the web, or drag the handle down to close it. It is drawn inside its parent, so it works in a screen, a tab or a `Modal` alike, and on the web it stays inside whatever frame holds it. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add action-tray
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/action-tray.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, View } from "react-native";
import { ActionTray } from "@/components/ui/action-tray";

export default function Example() {
  const [open, setOpen] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Options" onPress={() => setOpen(true)} />
      <ActionTray
        open={open}
        onClose={() => setOpen(false)}
        title="Photo"
        actions={[
          { label: "Share", onPress: () => console.log("share") },
          { label: "Delete", onPress: () => console.log("delete"), destructive: true },
        ]}
      />
    </View>
  );
}
```

The parent must fill the area the tray should cover, because the tray and its backdrop are sized to it. Picking an action runs it and then calls `onClose`.

## Props

| Prop          | Type                        | Default    | Description                                                                                       |
| :------------ | :-------------------------- | :--------- | :------------------------------------------------------------------------------------------------ |
| `open`        | `boolean`                   | -          | Whether the tray is showing.                                                                      |
| `onClose`     | `() => void`                | -          | Called when the tray should close: backdrop tap, Escape, a drag down, Cancel, or after an action. |
| `title`       | `string`                    | -          | Heading above the actions. Also the tray's accessibility label.                                   |
| `message`     | `string`                    | -          | A line of smaller text under the title.                                                           |
| `actions`     | `ActionTrayAction[]`        | -          | The actions. Each has a `label`, an `onPress`, and optional `destructive` and `disabled` flags.   |
| `cancelLabel` | `string`                    | `"Cancel"` | Label of the separate cancel button.                                                              |
| `colors`      | `Partial<ActionTrayColors>` | -          | Overrides `backdrop`, `surface`, `text`, `mutedText`, `destructive`, `divider` and `handle`.      |
| `style`       | `StyleProp<ViewStyle>`      | -          | Style for the container that covers the parent.                                                   |

## Source

`components/ui/action-tray.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Space left under the tray when it is hidden, so its shadow never peeks out.
const HIDE_GAP = 24;
// How far, or how fast, a drag must go to dismiss the tray.
const DISMISS_DISTANCE = 80;
const DISMISS_VELOCITY = 0.8;

export interface ActionTrayAction {
  label: string;
  onPress: () => void;
  /** Draws the action in the destructive color. */
  destructive?: boolean;
  disabled?: boolean;
}

export interface ActionTrayColors {
  backdrop: string;
  surface: string;
  text: string;
  mutedText: string;
  destructive: string;
  divider: string;
  handle: string;
}

const DEFAULT_COLORS: ActionTrayColors = {
  backdrop: "rgba(0, 0, 0, 0.4)",
  surface: "#ffffff",
  text: "#111827",
  mutedText: "#6b7280",
  destructive: "#dc2626",
  divider: "#e5e7eb",
  handle: "#d1d5db",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ActionTrayProps {
  /** Whether the tray is showing. */
  open: boolean;
  /** Called when the tray should close: backdrop tap, Escape, a drag down, Cancel, or after an action. */
  onClose: () => void;
  title?: string;
  /** A line of smaller text under the title. */
  message?: string;
  actions: ActionTrayAction[];
  cancelLabel?: string;
  colors?: Partial<ActionTrayColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A bottom action list in the style of a native action sheet. It slides up from the bottom of its
 * parent over a dimmed backdrop, with the actions as one rounded group and Cancel as a separate
 * button. Tap the backdrop, press Escape, or drag the handle down to close it. It is drawn inside
 * its parent, so the parent must fill the area the tray should cover.
 */
export function ActionTray({
  open,
  onClose,
  title,
  message,
  actions,
  cancelLabel = "Cancel",
  colors,
  style,
}: ActionTrayProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [height, setHeight] = useState(0);
  // Distance the tray is pushed down: 0 when open, `height + HIDE_GAP` when hidden.
  const y = useRef(new Animated.Value(0)).current;

  const live = useRef({ open, onClose, height, reduceMotion });
  live.current = { open, onClose, height, reduceMotion };

  const moveTo = (target: number) => {
    if (live.current.reduceMotion) {
      y.setValue(target);
      return;
    }
    Animated.spring(y, {
      toValue: target,
      stiffness: 360,
      damping: 34,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  useEffect(() => {
    if (height === 0) return;
    moveTo(open ? 0 : height + HIDE_GAP);
    // moveTo reads everything it needs through the ref.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [open, height]);

  // Escape closes the tray on the web.
  useEffect(() => {
    if (!open || Platform.OS !== "web") return;
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape") live.current.onClose();
    };
    document.addEventListener("keydown", onKey);
    return () => document.removeEventListener("keydown", onKey);
  }, [open]);

  const pan = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderGrant: () => y.stopAnimation(),
      onPanResponderMove: (_, g) => y.setValue(Math.max(0, g.dy)),
      onPanResponderRelease: (_, g) => {
        if (g.dy > DISMISS_DISTANCE || g.vy > DISMISS_VELOCITY) {
          moveTo(live.current.height + HIDE_GAP);
          live.current.onClose();
          // If the parent ignores the request the tray is still open: bring it back.
          setTimeout(() => {
            if (live.current.open) moveTo(0);
          }, 80);
        } else {
          moveTo(0);
        }
      },
      onPanResponderTerminate: () => moveTo(0),
    }),
  ).current;

  const onLayout = (event: LayoutChangeEvent) => {
    const next = event.nativeEvent.layout.height;
    if (next === height) return;
    // Start hidden, so the first open slides in instead of appearing.
    if (height === 0) y.setValue(next + HIDE_GAP);
    setHeight(next);
  };

  const backdropOpacity = y.interpolate({
    inputRange: [0, (height || 1) + HIDE_GAP],
    outputRange: [1, 0],
    extrapolate: "clamp",
  });

  return (
    <View
      pointerEvents={open ? "box-none" : "none"}
      aria-hidden={!open}
      style={[styles.root, style]}
    >
      <Animated.View
        aria-hidden
        pointerEvents={open ? "auto" : "none"}
        style={[styles.fill, { backgroundColor: palette.backdrop, opacity: backdropOpacity }]}
      >
        <Pressable accessible={false} focusable={false} onPress={onClose} style={styles.fill} />
      </Animated.View>
      <Animated.View
        role="dialog"
        aria-modal
        aria-label={title ?? "Actions"}
        accessibilityViewIsModal={open}
        onLayout={onLayout}
        style={[styles.tray, { opacity: height > 0 ? 1 : 0, transform: [{ translateY: y }] }]}
      >
        <View style={[styles.group, { backgroundColor: palette.surface }]}>
          <View {...pan.panHandlers} style={styles.header}>
            <View style={[styles.handle, { backgroundColor: palette.handle }]} />
            {title ? (
              <Text accessibilityRole="header" style={[styles.title, { color: palette.text }]}>
                {title}
              </Text>
            ) : null}
            {message ? (
              <Text style={[styles.message, { color: palette.mutedText }]}>{message}</Text>
            ) : null}
          </View>
          {actions.map((action) => (
            <Pressable
              key={action.label}
              accessibilityRole="button"
              accessibilityLabel={action.label}
              accessibilityState={{ disabled: !!action.disabled }}
              aria-disabled={!!action.disabled}
              disabled={action.disabled}
              focusable={open && !action.disabled}
              onPress={() => {
                action.onPress();
                onClose();
              }}
              style={({ pressed }) => [
                styles.action,
                { borderTopColor: palette.divider },
                action.disabled && styles.disabled,
                pressed && styles.pressed,
              ]}
            >
              <Text
                style={[
                  styles.actionText,
                  { color: action.destructive ? palette.destructive : palette.text },
                ]}
              >
                {action.label}
              </Text>
            </Pressable>
          ))}
        </View>
        <Pressable
          accessibilityRole="button"
          accessibilityLabel={cancelLabel}
          focusable={open}
          onPress={onClose}
          style={({ pressed }) => [
            styles.cancel,
            { backgroundColor: palette.surface },
            pressed && styles.pressed,
          ]}
        >
          <Text style={[styles.cancelText, { color: palette.text }]}>{cancelLabel}</Text>
        </Pressable>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    justifyContent: "flex-end",
  },
  fill: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  tray: { paddingHorizontal: 10, paddingBottom: 12, gap: 8 },
  group: { borderRadius: 16, overflow: "hidden" },
  // userSelect keeps a mouse drag on the web from selecting the title instead of moving the tray.
  header: {
    alignItems: "center",
    paddingTop: 8,
    paddingBottom: 12,
    paddingHorizontal: 16,
    gap: 4,
    userSelect: "none",
  },
  handle: { width: 36, height: 4, borderRadius: 2, marginBottom: 6 },
  title: { fontSize: 15, fontWeight: "700", textAlign: "center" },
  message: { fontSize: 13, textAlign: "center" },
  action: {
    minHeight: 54,
    alignItems: "center",
    justifyContent: "center",
    paddingHorizontal: 16,
    borderTopWidth: StyleSheet.hairlineWidth,
  },
  actionText: { fontSize: 17, fontWeight: "500" },
  cancel: {
    minHeight: 54,
    alignItems: "center",
    justifyContent: "center",
    borderRadius: 16,
  },
  cancelText: { fontSize: 17, fontWeight: "700" },
  disabled: { opacity: 0.4 },
  pressed: { opacity: 0.6 },
});
```

---

# Confirm Dialog

> A React Native alert dialog that pops in on a spring, starts focus on Cancel so Enter never confirms by accident, and locks while work is under way.

Install: `npx @modus-ui/cli add confirm-dialog`

A centred alert dialog, drawn inside its parent so it works in a screen, a tab or a `Modal` alike. It pops in on a spring over a dimmed backdrop. On the web focus starts on Cancel, so pressing Enter can never confirm a destructive action by accident, and Escape cancels. While `loading` the confirm button shows a spinner and the dialog cannot be dismissed. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add confirm-dialog
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/confirm-dialog.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, View } from "react-native";
import { ConfirmDialog } from "@/components/ui/confirm-dialog";

export default function Example() {
  const [open, setOpen] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Delete" onPress={() => setOpen(true)} />
      <ConfirmDialog
        open={open}
        destructive
        title="Delete this project?"
        message="This cannot be undone."
        confirmLabel="Delete"
        onConfirm={() => setOpen(false)}
        onCancel={() => setOpen(false)}
      />
    </View>
  );
}
```

The parent must fill the area the dialog should cover, because the dialog and its backdrop are sized to it.

## Props

| Prop           | Type                           | Default     | Description                                                                                                              |
| :------------- | :----------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |
| `open`         | `boolean`                      | -           | Whether the dialog is showing.                                                                                           |
| `onConfirm`    | `() => void`                   | -           | Called when the confirm button is pressed.                                                                               |
| `onCancel`     | `() => void`                   | -           | Called by the cancel button, a backdrop tap or Escape on the web.                                                        |
| `title`        | `string`                       | -           | The dialog's heading, also its spoken label.                                                                             |
| `message`      | `string`                       | -           | Text under the heading.                                                                                                  |
| `confirmLabel` | `string`                       | `"Confirm"` | Text of the confirm button.                                                                                              |
| `cancelLabel`  | `string`                       | `"Cancel"`  | Text of the cancel button.                                                                                               |
| `destructive`  | `boolean`                      | `false`     | Styles the confirm button as a warning, for actions that cannot be undone.                                               |
| `loading`      | `boolean`                      | `false`     | Shows a spinner in the confirm button and disables the dialog while work is under way.                                   |
| `colors`       | `Partial<ConfirmDialogColors>` | -           | Overrides `surface`, `backdrop`, `title`, `message`, `border`, `cancelText`, `confirm`, `confirmText` and `destructive`. |
| `style`        | `StyleProp<ViewStyle>`         | -           | Style for the dialog card.                                                                                               |

## Source

`components/ui/confirm-dialog.tsx`

```tsx
import { useEffect, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  ActivityIndicator,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Past this many characters a label no longer fits two side-by-side buttons.
const LONG_LABEL = 14;

export interface ConfirmDialogColors {
  surface: string;
  backdrop: string;
  title: string;
  message: string;
  border: string;
  cancelText: string;
  confirm: string;
  confirmText: string;
  destructive: string;
}

const DEFAULT_COLORS: ConfirmDialogColors = {
  surface: "#ffffff",
  backdrop: "rgba(0, 0, 0, 0.5)",
  title: "#111827",
  message: "#6b7280",
  border: "#e5e7eb",
  cancelText: "#111827",
  confirm: "#4f46e5",
  confirmText: "#ffffff",
  destructive: "#dc2626",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ConfirmDialogProps {
  open: boolean;
  onConfirm: () => void;
  onCancel: () => void;
  title: string;
  message?: string;
  confirmLabel?: string;
  cancelLabel?: string;
  /** Styles the confirm button as a warning, for actions that cannot be undone. */
  destructive?: boolean;
  /** Shows a spinner in the confirm button and disables the dialog while work is under way. */
  loading?: boolean;
  colors?: Partial<ConfirmDialogColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A centred alert dialog, drawn inside its parent so it works in a screen, a tab or a Modal alike.
 * It pops in on a spring over a dimmed backdrop. On the web focus starts on Cancel, so pressing Enter
 * can never confirm a destructive action by accident, and Escape cancels. While `loading` it cannot
 * be dismissed.
 */
export function ConfirmDialog({
  open,
  onConfirm,
  onCancel,
  title,
  message,
  confirmLabel = "Confirm",
  cancelLabel = "Cancel",
  destructive = false,
  loading = false,
  colors,
  style,
}: ConfirmDialogProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const t = useRef(new Animated.Value(0)).current;
  const [mounted, setMounted] = useState(open);
  const cancelButton = useRef<ElementRef<typeof View>>(null);

  const live = useRef({ onCancel, loading });
  live.current = { onCancel, loading };

  useEffect(() => {
    if (open) setMounted(true);
    if (reduceMotion) {
      t.setValue(open ? 1 : 0);
      if (!open) setMounted(false);
      return;
    }
    Animated.spring(t, {
      toValue: open ? 1 : 0,
      stiffness: 360,
      damping: 28,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start(({ finished }) => {
      if (finished && !open) setMounted(false);
    });
  }, [open, reduceMotion, t]);

  // Web: start on Cancel and let Escape cancel.
  useEffect(() => {
    if (!open || !mounted || Platform.OS !== "web") return;
    const focus = setTimeout(
      () => (cancelButton.current as unknown as HTMLElement | null)?.focus?.(),
      30,
    );
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape" && !live.current.loading) live.current.onCancel();
    };
    window.addEventListener("keydown", onKey);
    return () => {
      clearTimeout(focus);
      window.removeEventListener("keydown", onKey);
    };
  }, [open, mounted]);

  if (!mounted) return null;

  const stacked = confirmLabel.length > LONG_LABEL || cancelLabel.length > LONG_LABEL;
  const accent = destructive ? palette.destructive : palette.confirm;

  return (
    <View style={styles.root} pointerEvents={open ? "auto" : "none"}>
      <Animated.View
        aria-hidden
        style={[styles.fill, { backgroundColor: palette.backdrop, opacity: t }]}
      >
        <Pressable accessible={false} disabled={loading} onPress={onCancel} style={styles.fill} />
      </Animated.View>
      <Animated.View
        role="alertdialog"
        accessibilityLabel={title}
        aria-label={title}
        aria-modal
        accessibilityViewIsModal
        style={[
          styles.card,
          {
            backgroundColor: palette.surface,
            opacity: t,
            transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.92, 1] }) }],
          },
          style,
        ]}
      >
        <Text style={[styles.title, { color: palette.title }]}>{title}</Text>
        {message ? (
          <Text style={[styles.message, { color: palette.message }]}>{message}</Text>
        ) : null}
        <View style={[styles.buttons, stacked && styles.stacked]}>
          <Pressable
            ref={cancelButton}
            accessibilityRole="button"
            accessibilityLabel={cancelLabel}
            accessibilityState={{ disabled: loading }}
            aria-disabled={loading}
            disabled={loading}
            onPress={onCancel}
            style={({ pressed }) => [
              styles.button,
              { borderColor: palette.border, borderWidth: 1 },
              stacked && styles.fullWidth,
              (pressed || loading) && styles.dim,
            ]}
          >
            <Text style={[styles.buttonText, { color: palette.cancelText }]}>{cancelLabel}</Text>
          </Pressable>
          <Pressable
            accessibilityRole="button"
            accessibilityLabel={loading ? `${confirmLabel}, working` : confirmLabel}
            accessibilityState={{ disabled: loading, busy: loading }}
            aria-disabled={loading}
            aria-busy={loading}
            disabled={loading}
            onPress={onConfirm}
            style={({ pressed }) => [
              styles.button,
              { backgroundColor: accent },
              stacked && styles.fullWidth,
              pressed && styles.dim,
            ]}
          >
            {loading ? (
              <ActivityIndicator color={palette.confirmText} />
            ) : (
              <Text style={[styles.buttonText, { color: palette.confirmText }]}>
                {confirmLabel}
              </Text>
            )}
          </Pressable>
        </View>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
    padding: 24,
  },
  fill: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  card: {
    width: "100%",
    maxWidth: 320,
    borderRadius: 20,
    padding: 20,
    gap: 8,
    boxShadow: "0 20px 50px rgba(0, 0, 0, 0.3)",
  },
  title: { fontSize: 18, fontWeight: "700" },
  message: { fontSize: 15, lineHeight: 21 },
  buttons: { flexDirection: "row", gap: 10, marginTop: 14 },
  stacked: { flexDirection: "column-reverse" },
  button: {
    flex: 1,
    minHeight: 46,
    borderRadius: 12,
    alignItems: "center",
    justifyContent: "center",
    paddingHorizontal: 12,
    userSelect: "none",
  },
  fullWidth: { flex: 0, width: "100%" },
  buttonText: { fontSize: 15, fontWeight: "600" },
  dim: { opacity: 0.7 },
});
```

---

# Code Boxes

> A React Native one-time-code input drawn as separate boxes, with paste, SMS autofill, a blinking caret, a pop for each digit and a shake on error.

Install: `npx @modus-ui/cli add code-boxes`

A one-time-code field drawn as separate boxes. One real, invisible input sits over them, so paste, the keyboard and SMS autofill all work, and the boxes only show what it holds. The active box has a ring and a blinking caret, each character pops in, and a wrong code shakes the row. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add code-boxes
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/code-boxes.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { CodeBoxes } from "@/components/ui/code-boxes";

export default function Example() {
  const [code, setCode] = useState("");
  const [wrong, setWrong] = useState(false);

  return (
    <CodeBoxes
      value={code}
      onChange={setCode}
      error={wrong}
      onComplete={async (entered) => setWrong(!(await verify(entered)))}
    />
  );
}
```

## Props

| Prop         | Type                       | Default | Description                                                              |
| :----------- | :------------------------- | :------ | :----------------------------------------------------------------------- |
| `value`      | `string`                   | -       | The code entered so far.                                                 |
| `onChange`   | `(next: string) => void`   | -       | Called with the cleaned code as characters are typed, pasted or removed. |
| `length`     | `number`                   | `6`     | How many characters make the code.                                       |
| `onComplete` | `(code: string) => void`   | -       | Called once when the last character arrives, with the full code.         |
| `numeric`    | `boolean`                  | `true`  | Accept digits only and show a numeric keyboard.                          |
| `autoFocus`  | `boolean`                  | `false` | Focus the field when it mounts.                                          |
| `error`      | `boolean`                  | `false` | Turns the boxes the error color and shakes them.                         |
| `disabled`   | `boolean`                  | `false` | Dims the boxes and ignores input.                                        |
| `colors`     | `Partial<CodeBoxesColors>` | -       | Overrides `box`, `border`, `focusBorder`, `text` and `error`.            |
| `style`      | `StyleProp<ViewStyle>`     | -       | Style for the container.                                                 |

## Source

`components/ui/code-boxes.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const BOX_HEIGHT = 58;

export interface CodeBoxesColors {
  box: string;
  border: string;
  focusBorder: string;
  text: string;
  error: string;
}

const DEFAULT_COLORS: CodeBoxesColors = {
  box: "#ffffff",
  border: "#d1d5db",
  focusBorder: "#4f46e5",
  text: "#111827",
  error: "#dc2626",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface CodeBoxesProps {
  /** The code entered so far. */
  value: string;
  onChange: (next: string) => void;
  /** How many characters make the code. */
  length?: number;
  /** Called once when the last character arrives, with the full code. */
  onComplete?: (code: string) => void;
  /** Accept digits only and show a numeric keyboard. */
  numeric?: boolean;
  autoFocus?: boolean;
  /** Turns the boxes the error color and shakes them. */
  error?: boolean;
  disabled?: boolean;
  colors?: Partial<CodeBoxesColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A one-time-code field drawn as separate boxes. One real, invisible input sits over them, so paste,
 * the keyboard and SMS autofill all work, and the boxes only show what it holds. The active box has
 * a ring and a blinking caret, each character pops in, and a wrong code shakes the row.
 */
export function CodeBoxes({
  value,
  onChange,
  length = 6,
  onComplete,
  numeric = true,
  autoFocus = false,
  error = false,
  disabled = false,
  colors,
  style,
}: CodeBoxesProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [focused, setFocused] = useState(false);
  // Re-rendering with an unchanged value makes the input drop a character we refused (a letter in
  // numeric mode); bumping this is how we force that.
  const [, setRefresh] = useState(0);
  const blink = useRef(new Animated.Value(1)).current;
  const shake = useRef(new Animated.Value(0)).current;
  const completedFor = useRef<string | null>(null);
  const wasError = useRef(false);

  const clean = (raw: string) =>
    (numeric ? raw.replace(/\D/g, "") : raw.replace(/[^a-z0-9]/gi, "")).slice(0, length);

  const handleChangeText = (raw: string) => {
    const next = clean(raw);
    if (next !== value) onChange(next);
    else if (raw !== value) setRefresh((n) => n + 1);
  };

  // Report completion once per complete code, and again only after it has been edited.
  const onCompleteRef = useRef(onComplete);
  onCompleteRef.current = onComplete;
  useEffect(() => {
    if (value.length < length) {
      completedFor.current = null;
      return;
    }
    if (value.length === length && completedFor.current !== value) {
      completedFor.current = value;
      onCompleteRef.current?.(value);
    }
  }, [value, length]);

  // The caret blinks on its own value, so it keeps running while the active box moves.
  useEffect(() => {
    blink.setValue(1);
    if (!focused || reduceMotion || disabled) return;
    const loop = Animated.loop(
      Animated.sequence([
        Animated.timing(blink, { toValue: 0, duration: 500, useNativeDriver: NATIVE_DRIVER }),
        Animated.timing(blink, { toValue: 1, duration: 500, useNativeDriver: NATIVE_DRIVER }),
      ]),
    );
    loop.start();
    return () => loop.stop();
  }, [focused, reduceMotion, disabled, blink]);

  // Shake once each time the error turns on.
  useEffect(() => {
    if (error && !wasError.current && !reduceMotion) {
      Animated.sequence(
        [-10, 10, -7, 7, -3, 0].map((toValue) =>
          Animated.timing(shake, { toValue, duration: 55, useNativeDriver: NATIVE_DRIVER }),
        ),
      ).start();
    }
    wasError.current = error;
  }, [error, reduceMotion, shake]);

  const rowStyle = useMemo(() => ({ transform: [{ translateX: shake }] }), [shake]);
  const active = Math.min(value.length, length - 1);

  return (
    <View style={[styles.root, style]}>
      <Animated.View style={[styles.wrap, rowStyle]}>
        <View
          pointerEvents="none"
          style={styles.row}
          accessibilityElementsHidden
          importantForAccessibility="no-hide-descendants"
          aria-hidden
        >
          {Array.from({ length }, (_, index) => (
            <Box
              key={`box-${index}`}
              char={value[index] ?? ""}
              isActive={focused && !disabled && index === active}
              showCaret={value.length < length && index === value.length}
              error={error}
              disabled={disabled}
              blink={blink}
              reduceMotion={reduceMotion}
              palette={palette}
            />
          ))}
        </View>
        <TextInput
          value={value}
          onChangeText={handleChangeText}
          onFocus={() => setFocused(true)}
          onBlur={() => setFocused(false)}
          editable={!disabled}
          autoFocus={autoFocus}
          keyboardType={numeric ? "number-pad" : "default"}
          inputMode={numeric ? "numeric" : "text"}
          textContentType="oneTimeCode"
          autoComplete="sms-otp"
          autoCapitalize="none"
          autoCorrect={false}
          // react-native-web blurs a single-line field on Enter unless told not to.
          blurOnSubmit={false}
          caretHidden
          selectionColor="transparent"
          accessibilityLabel="Verification code"
          aria-label="Verification code"
          aria-disabled={disabled}
          style={styles.input}
        />
      </Animated.View>
      <Text accessibilityLiveRegion="polite" style={styles.status}>
        {`${value.length} of ${length} ${numeric ? "digits" : "characters"} entered`}
      </Text>
    </View>
  );
}

function Box({
  char,
  isActive,
  showCaret,
  error,
  disabled,
  blink,
  reduceMotion,
  palette,
}: {
  char: string;
  isActive: boolean;
  showCaret: boolean;
  error: boolean;
  disabled: boolean;
  blink: Animated.Value;
  reduceMotion: boolean;
  palette: CodeBoxesColors;
}) {
  const scale = useRef(new Animated.Value(1)).current;
  const previous = useRef(char);

  // Pop when a character lands in an empty box.
  useEffect(() => {
    if (char && !previous.current && !reduceMotion) {
      scale.setValue(0.8);
      Animated.spring(scale, {
        toValue: 1,
        stiffness: 520,
        damping: 14,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
    previous.current = char;
  }, [char, reduceMotion, scale]);

  const popStyle = useMemo(() => ({ transform: [{ scale }] }), [scale]);
  const caretStyle = useMemo(() => ({ opacity: blink }), [blink]);
  const borderColor = error ? palette.error : isActive ? palette.focusBorder : palette.border;

  return (
    <Animated.View
      style={[
        styles.box,
        {
          backgroundColor: palette.box,
          borderColor,
          borderWidth: isActive || error ? 2 : 1.5,
          opacity: disabled ? 0.5 : 1,
        },
        popStyle,
      ]}
    >
      <Text style={[styles.char, { color: error ? palette.error : palette.text }]}>{char}</Text>
      {/* Always mounted so its blink never restarts; only its visibility follows the active box. */}
      <View
        pointerEvents="none"
        style={[styles.caretSlot, { opacity: isActive && showCaret ? 1 : 0 }]}
      >
        <Animated.View
          style={[styles.caret, { backgroundColor: palette.focusBorder }, caretStyle]}
        />
      </View>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  // userSelect keeps a mouse press on the web from selecting the digits.
  root: { alignSelf: "stretch", userSelect: "none" },
  wrap: { alignSelf: "stretch" },
  row: { flexDirection: "row", gap: 8 },
  box: {
    flex: 1,
    maxWidth: 56,
    height: BOX_HEIGHT,
    borderRadius: 12,
    alignItems: "center",
    justifyContent: "center",
  },
  char: { fontSize: 26, fontWeight: "700" },
  caretSlot: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
  },
  caret: { width: 2, height: 28, borderRadius: 1 },
  // Covers the boxes so a tap anywhere focuses it and paste lands in it, but shows nothing itself.
  input: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    opacity: 0,
    color: "transparent",
  },
  // Visually hidden, but still announced by screen readers.
  status: { position: "absolute", width: 1, height: 1, overflow: "hidden", opacity: 0 },
});
```

---

# Hue Picker

> A React Native colour picker built from plain Views, with a hue strip, a lightness strip for the chosen hue, one-tap swatches and a live preview.

Install: `npx @modus-ui/cli add hue-picker`

A colour picker built from plain Views, with no gradient or SVG packages. Drag the hue strip, then the lightness strip, which runs dark to light in the hue you chose, or tap a swatch. Hue, saturation and lightness are kept as numbers while you drag and only turned into hex on the way out, so the hex never drifts and the hue survives passing through black or white. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add hue-picker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/hue-picker.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { HuePicker } from "@/components/ui/hue-picker";

export default function Example() {
  const [color, setColor] = useState("#4f46e5");

  return <HuePicker value={color} onChange={setColor} />;
}
```

`value` is expected to echo `onChange`. If you set it to something else, the picker adopts it.

## Props

| Prop        | Type                       | Default    | Description                                                     |
| :---------- | :------------------------- | :--------- | :-------------------------------------------------------------- |
| `value`     | `string`                   | -          | The colour as a hex string such as `#4f46e5`.                   |
| `onChange`  | `(hex: string) => void`    | -          | Called with a lowercase `#rrggbb` string as the colour changes. |
| `swatches`  | `string[]`                 | eight hues | Colours offered as one-tap swatches.                            |
| `showValue` | `boolean`                  | `true`     | Show the hex text next to the preview.                          |
| `colors`    | `Partial<HuePickerColors>` | -          | Overrides `ring` and `text`.                                    |
| `style`     | `StyleProp<ViewStyle>`     | -          | Style for the container.                                        |

## Source

`components/ui/hue-picker.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const THUMB = 28;
const TRACK_INSET = 5;
const HUE_SEGMENTS = 72;
const LIGHT_SEGMENTS = 24;
const STEP = 5;
// Hue 360 is the same colour as 0, so the far end of the strip stops just short of it and the thumb
// never jumps back to the start.
const MAX_HUE = 359.99;
const FALLBACK = "#4f46e5";

export interface HuePickerColors {
  ring: string;
  text: string;
}

const DEFAULT_COLORS: HuePickerColors = {
  ring: "#111827",
  text: "#111827",
};

const DEFAULT_SWATCHES = [
  "#ef4444",
  "#f97316",
  "#eab308",
  "#22c55e",
  "#14b8a6",
  "#3b82f6",
  "#8b5cf6",
  "#ec4899",
];

const HUE_COLORS = Array.from(
  { length: HUE_SEGMENTS },
  (_, i) => `hsl(${(i + 0.5) * (360 / HUE_SEGMENTS)}, 100%, 50%)`,
);

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

interface Hsl {
  /** Degrees, 0 to 360. */
  h: number;
  /** Percent. */
  s: number;
  /** Percent. */
  l: number;
}

/** "#abc" or "#aabbcc", any case, to "#aabbcc"; null when it is not a hex colour. */
function normalizeHex(input: string): string | null {
  const match = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(input.trim());
  if (!match) return null;
  const digits = match[1].toLowerCase();
  const full = digits.length === 3 ? digits.replace(/./g, (c) => c + c) : digits;
  return `#${full}`;
}

function hexToHsl(hex: string): Hsl {
  const r = parseInt(hex.slice(1, 3), 16) / 255;
  const g = parseInt(hex.slice(3, 5), 16) / 255;
  const b = parseInt(hex.slice(5, 7), 16) / 255;
  const max = Math.max(r, g, b);
  const min = Math.min(r, g, b);
  const d = max - min;
  const l = (max + min) / 2;
  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
  let h = 0;
  if (d !== 0) {
    if (max === r) h = ((g - b) / d) % 6;
    else if (max === g) h = (b - r) / d + 2;
    else h = (r - g) / d + 4;
  }
  return { h: (h * 60 + 360) % 360, s: s * 100, l: l * 100 };
}

function hslToHex({ h, s, l }: Hsl): string {
  const sat = s / 100;
  const light = l / 100;
  const chroma = (1 - Math.abs(2 * light - 1)) * sat;
  const sector = (((h % 360) + 360) % 360) / 60;
  const x = chroma * (1 - Math.abs((sector % 2) - 1));
  const [r, g, b] =
    sector < 1
      ? [chroma, x, 0]
      : sector < 2
        ? [x, chroma, 0]
        : sector < 3
          ? [0, chroma, x]
          : sector < 4
            ? [0, x, chroma]
            : sector < 5
              ? [x, 0, chroma]
              : [chroma, 0, x];
  const m = light - chroma / 2;
  const byte = (v: number) =>
    Math.max(0, Math.min(255, Math.round((v + m) * 255)))
      .toString(16)
      .padStart(2, "0");
  return `#${byte(r)}${byte(g)}${byte(b)}`;
}

export interface HuePickerProps {
  /** The colour as a hex string such as "#4f46e5". Expected to echo `onChange`. */
  value: string;
  /** Called with a lowercase "#rrggbb" string as the colour changes. */
  onChange: (hex: string) => void;
  /** Colours offered as one-tap swatches. */
  swatches?: string[];
  /** Show the hex text next to the preview. */
  showValue?: boolean;
  colors?: Partial<HuePickerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A colour picker built from plain Views: a hue strip, a lightness strip for the chosen hue, and
 * swatches. Hue, saturation and lightness are kept as numbers while you drag and only turned into
 * hex on the way out, so the hex never drifts and the hue survives passing through black or white.
 */
export function HuePicker({
  value,
  onChange,
  swatches = DEFAULT_SWATCHES,
  showValue = true,
  colors,
  style,
}: HuePickerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const initial = normalizeHex(value) ?? FALLBACK;
  const [hsl, setHsl] = useState<Hsl>(() => hexToHsl(initial));
  const [width, setWidth] = useState(0);
  const emitted = useRef(initial);
  const dragging = useRef<"hue" | "light" | null>(null);
  const placed = useRef(false);
  const start = useRef(0);
  const hueX = useRef(new Animated.Value(0)).current;
  const lightX = useRef(new Animated.Value(0)).current;
  const hueGrow = useRef(new Animated.Value(0)).current;
  const lightGrow = useRef(new Animated.Value(0)).current;

  const span = Math.max(0, width - THUMB);
  const hex = hslToHex(hsl);

  // The responders are created once, so they read the latest values from here.
  const live = useRef({ hsl, onChange, span, reduceMotion });
  live.current = { hsl: live.current.hsl, onChange, span, reduceMotion };

  // Adopt a colour the parent changed, but not the one we just reported.
  useEffect(() => {
    const next = normalizeHex(value);
    if (next && next !== emitted.current) {
      emitted.current = next;
      const parsed = hexToHsl(next);
      live.current.hsl = parsed;
      setHsl(parsed);
    }
  }, [value]);

  const apply = (next: Hsl) => {
    live.current.hsl = next;
    setHsl(next);
    const nextHex = hslToHex(next);
    if (nextHex !== emitted.current) {
      emitted.current = nextHex;
      live.current.onChange(nextHex);
    }
  };

  const spring = (node: Animated.Value, toValue: number) => {
    if (live.current.reduceMotion) {
      node.setValue(toValue);
      return;
    }
    Animated.spring(node, {
      toValue,
      stiffness: 420,
      damping: 28,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  // Put the thumbs where the colour says. Dragging moves them directly, so skip it then.
  useEffect(() => {
    if (span <= 0 || dragging.current) return;
    const targets: [Animated.Value, number][] = [
      [hueX, (hsl.h / 360) * span],
      [lightX, (hsl.l / 100) * span],
    ];
    for (const [node, px] of targets) {
      if (!placed.current) node.setValue(px);
      else spring(node, px);
    }
    placed.current = true;
    // spring reads from refs; the dependencies below are what should re-run it.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [hsl.h, hsl.l, span, reduceMotion]);

  const move = (kind: "hue" | "light", x: number) => {
    const room = live.current.span;
    if (room <= 0) return;
    const ratio = Math.max(0, Math.min(1, (x - THUMB / 2) / room));
    if (kind === "hue") {
      hueX.setValue(ratio * room);
      apply({ ...live.current.hsl, h: Math.min(MAX_HUE, ratio * 360) });
    } else {
      lightX.setValue(ratio * room);
      apply({ ...live.current.hsl, l: ratio * 100 });
    }
  };

  const makePan = (kind: "hue" | "light") => {
    const grow = kind === "hue" ? hueGrow : lightGrow;
    const finish = () => {
      if (dragging.current !== kind) return;
      dragging.current = null;
      spring(grow, 0);
    };
    return PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: (event) => {
        dragging.current = kind;
        start.current = event.nativeEvent.locationX;
        spring(grow, 1);
        // Touching the strip puts the thumb under the finger.
        move(kind, start.current);
      },
      onPanResponderMove: (_, g) => move(kind, start.current + g.dx),
      onPanResponderRelease: finish,
      onPanResponderTerminate: finish,
    });
  };
  const huePan = useRef(makePan("hue")).current;
  const lightPan = useRef(makePan("light")).current;

  const nudge = (kind: "hue" | "light", direction: 1 | -1) => {
    const current = live.current.hsl;
    if (kind === "hue") {
      apply({ ...current, h: Math.max(0, Math.min(MAX_HUE, current.h + direction * STEP)) });
    } else {
      apply({ ...current, l: Math.max(0, Math.min(100, current.l + direction * STEP)) });
    }
  };

  const choose = (swatch: string) => {
    const normal = normalizeHex(swatch);
    if (!normal) return;
    const parsed = hexToHsl(normal);
    live.current.hsl = parsed;
    setHsl(parsed);
    if (normal !== emitted.current) {
      emitted.current = normal;
      live.current.onChange(normal);
    }
  };

  // The lightness strip runs dark to light in the chosen hue and saturation.
  const hueKey = Math.round(hsl.h);
  const satKey = Math.round(hsl.s);
  const lightColors = useMemo(
    () =>
      Array.from(
        { length: LIGHT_SEGMENTS },
        (_, i) => `hsl(${hueKey}, ${satKey}%, ${(i / (LIGHT_SEGMENTS - 1)) * 100}%)`,
      ),
    [hueKey, satKey],
  );

  return (
    <View
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={[styles.root, style]}
    >
      <View style={styles.preview}>
        <View style={[styles.chip, { backgroundColor: hex }]} />
        {showValue ? <Text style={[styles.hex, { color: palette.text }]}>{hex}</Text> : null}
      </View>
      <Strip
        label="Hue"
        segments={HUE_COLORS}
        x={hueX}
        grow={hueGrow}
        thumbColor={`hsl(${hueKey}, 100%, 50%)`}
        panHandlers={huePan.panHandlers}
        now={Math.round(hsl.h)}
        max={360}
        text={`${Math.round(hsl.h)} degrees`}
        onNudge={(direction) => nudge("hue", direction)}
      />
      <Strip
        label="Lightness"
        segments={lightColors}
        x={lightX}
        grow={lightGrow}
        thumbColor={hex}
        panHandlers={lightPan.panHandlers}
        now={Math.round(hsl.l)}
        max={100}
        text={`${Math.round(hsl.l)} percent`}
        onNudge={(direction) => nudge("light", direction)}
      />
      <View style={styles.swatches}>
        {swatches.map((swatch, index) => (
          <Swatch
            key={`swatch-${index}`}
            hex={normalizeHex(swatch) ?? swatch}
            selected={normalizeHex(swatch) === hex}
            ring={palette.ring}
            reduceMotion={reduceMotion}
            onPress={() => choose(swatch)}
          />
        ))}
      </View>
    </View>
  );
}

function Strip({
  label,
  segments,
  x,
  grow,
  thumbColor,
  panHandlers,
  now,
  max,
  text,
  onNudge,
}: {
  label: string;
  segments: string[];
  x: Animated.Value;
  grow: Animated.Value;
  thumbColor: string;
  panHandlers: object;
  now: number;
  max: number;
  text: string;
  onNudge: (direction: 1 | -1) => void;
}) {
  // Built once so react-native-web never restarts a running spring when this re-renders.
  const thumbStyle = useMemo(
    () => ({
      transform: [
        { translateX: x },
        { scale: grow.interpolate({ inputRange: [0, 1], outputRange: [1, 1.18] }) },
      ],
    }),
    [x, grow],
  );

  return (
    <View
      {...panHandlers}
      accessible
      accessibilityRole="adjustable"
      accessibilityLabel={label}
      aria-label={label}
      accessibilityValue={{ min: 0, max, now, text }}
      aria-valuemin={0}
      aria-valuemax={max}
      aria-valuenow={now}
      aria-valuetext={text}
      accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(event) =>
        onNudge(event.nativeEvent.actionName === "increment" ? 1 : -1)
      }
      style={styles.strip}
    >
      <View pointerEvents="none" style={styles.clip}>
        {segments.map((color, index) => (
          <View key={`segment-${index}`} style={[styles.segment, { backgroundColor: color }]} />
        ))}
      </View>
      <Animated.View
        pointerEvents="none"
        style={[styles.thumb, { backgroundColor: thumbColor }, thumbStyle]}
      />
    </View>
  );
}

function Swatch({
  hex,
  selected,
  ring,
  reduceMotion,
  onPress,
}: {
  hex: string;
  selected: boolean;
  ring: string;
  reduceMotion: boolean;
  onPress: () => void;
}) {
  const shown = useRef(new Animated.Value(selected ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      shown.setValue(selected ? 1 : 0);
      return;
    }
    Animated.spring(shown, {
      toValue: selected ? 1 : 0,
      stiffness: 420,
      damping: 24,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [selected, reduceMotion, shown]);

  const ringStyle = useMemo(
    () => ({
      opacity: shown,
      transform: [{ scale: shown.interpolate({ inputRange: [0, 1], outputRange: [0.75, 1] }) }],
    }),
    [shown],
  );

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={hex}
      aria-label={hex}
      accessibilityState={{ selected }}
      aria-selected={selected}
      hitSlop={6}
      onPress={onPress}
      style={styles.swatchHit}
    >
      <Animated.View
        pointerEvents="none"
        style={[styles.swatchRing, { borderColor: ring }, ringStyle]}
      />
      <View style={[styles.swatch, { backgroundColor: hex }]} />
    </Pressable>
  );
}

const styles = StyleSheet.create({
  // userSelect keeps a mouse drag on the web from selecting text instead of moving a thumb.
  root: { alignSelf: "stretch", gap: 16, userSelect: "none" },
  preview: { flexDirection: "row", alignItems: "center", gap: 12 },
  chip: {
    width: 48,
    height: 48,
    borderRadius: 14,
    borderWidth: 1,
    borderColor: "rgba(0, 0, 0, 0.12)",
  },
  hex: { fontSize: 18, fontWeight: "700", letterSpacing: 0.5 },
  strip: { height: THUMB, justifyContent: "center" },
  clip: {
    position: "absolute",
    top: TRACK_INSET,
    bottom: TRACK_INSET,
    left: 0,
    right: 0,
    flexDirection: "row",
    borderRadius: 10,
    overflow: "hidden",
  },
  segment: { flex: 1 },
  thumb: {
    position: "absolute",
    left: 0,
    top: 0,
    width: THUMB,
    height: THUMB,
    borderRadius: THUMB / 2,
    borderWidth: 3,
    borderColor: "#ffffff",
    boxShadow: "0 1px 5px rgba(0, 0, 0, 0.35)",
  },
  swatches: { flexDirection: "row", flexWrap: "wrap", gap: 10 },
  swatchHit: { width: 34, height: 34, alignItems: "center", justifyContent: "center" },
  swatch: { width: 26, height: 26, borderRadius: 13 },
  swatchRing: {
    position: "absolute",
    top: 0,
    left: 0,
    right: 0,
    bottom: 0,
    borderRadius: 17,
    borderWidth: 2.5,
  },
});
```

---

# Tab Pager

> A React Native tab header over swipeable pages, with an underline that follows your finger and labels that blend as their page arrives.

Install: `npx @modus-ui/cli add tab-pager`

Swipeable pages under a row of tabs. The underline follows your finger between the two tabs it is travelling across, growing or shrinking to each label's width, and the labels blend from muted to active as their page arrives. Tapping a tab scrolls to its page, and a long row of tabs scrolls to keep the selected one in view. On desktop browsers the pages can also be dragged with a mouse. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add tab-pager
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tab-pager.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Text } from "react-native";
import { TabPager } from "@/components/ui/tab-pager";

const tabs = [
  { id: "inbox", label: "Inbox" },
  { id: "sent", label: "Sent" },
  { id: "drafts", label: "Drafts" },
];

export default function Example() {
  const [tab, setTab] = useState("inbox");

  return (
    <TabPager
      tabs={tabs}
      value={tab}
      onChange={setTab}
      renderPage={(item) => <Text style={{ padding: 20 }}>{item.label}</Text>}
    />
  );
}
```

The pager fills its parent, so give the parent a height (a screen with `flex: 1` is enough).

## Props

| Prop         | Type                                             | Default | Description                                                             |
| :----------- | :----------------------------------------------- | :------ | :---------------------------------------------------------------------- |
| `tabs`       | `TabPagerTab[]`                                  | -       | The tabs, each with an `id` and a `label`.                              |
| `renderPage` | `(tab: TabPagerTab, index: number) => ReactNode` | -       | Renders the content of one page.                                        |
| `value`      | `string`                                         | -       | The `id` of the selected tab.                                           |
| `onChange`   | `(id: string) => void`                           | -       | Called with the new tab's `id` after a swipe or a tap.                  |
| `colors`     | `Partial<TabPagerColors>`                        | -       | Overrides `text`, `activeText`, `indicator`, `border` and `background`. |
| `style`      | `StyleProp<ViewStyle>`                           | -       | Style for the container.                                                |

## Source

`components/ui/tab-pager.tsx`

```tsx
import { useEffect, useRef, useState, type ElementRef, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  ScrollView,
  StyleSheet,
  View,
  type LayoutChangeEvent,
  type NativeScrollEvent,
  type NativeSyntheticEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface TabPagerTab {
  id: string;
  label: string;
}

export interface TabPagerColors {
  text: string;
  activeText: string;
  indicator: string;
  border: string;
  background: string;
}

const DEFAULT_COLORS: TabPagerColors = {
  text: "#6b7280",
  activeText: "#111827",
  indicator: "#4f46e5",
  border: "#e5e7eb",
  background: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface TabPagerProps {
  tabs: TabPagerTab[];
  /** Renders the content of one page. */
  renderPage: (tab: TabPagerTab, index: number) => ReactNode;
  /** The id of the selected tab. */
  value: string;
  onChange: (id: string) => void;
  colors?: Partial<TabPagerColors>;
  style?: StyleProp<ViewStyle>;
}

interface Box {
  x: number;
  width: number;
}

/**
 * Swipeable pages under a row of tabs. The underline follows your finger between the two tabs it is
 * travelling across, growing or shrinking to each label's width, and the labels blend from muted to
 * active as their page arrives. Tapping a tab scrolls to its page. On desktop browsers the pages can
 * also be dragged with a mouse.
 */
export function TabPager({ tabs, renderPage, value, onChange, colors, style }: TabPagerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const [boxes, setBoxes] = useState<Box[]>([]);
  // Paging snaps the scroll back on the web, so it is switched off while a mouse drags the pages.
  const [snapping, setSnapping] = useState(true);
  const pages = useRef<ElementRef<typeof ScrollView>>(null);
  const header = useRef<ElementRef<typeof ScrollView>>(null);
  const scrollX = useRef(new Animated.Value(0)).current;
  const offset = useRef(0);
  const current = useRef(
    Math.max(
      0,
      tabs.findIndex((tab) => tab.id === value),
    ),
  );
  // True during a mouse drag and for a moment after it: the click a mouse sends on release is not a tap.
  const dragging = useRef(false);
  const dragStart = useRef(0);
  const headerWidth = useRef(0);

  const index = Math.max(
    0,
    tabs.findIndex((tab) => tab.id === value),
  );
  const last = tabs.length - 1;

  const live = useRef({ width, last, reduceMotion, onChange, tabs, boxes });
  live.current = { width, last, reduceMotion, onChange, tabs, boxes };

  const goTo = (target: number, animated = !live.current.reduceMotion) => {
    const clamped = Math.max(0, Math.min(live.current.last, target));
    pages.current?.scrollTo({ x: clamped * live.current.width, animated });
  };

  // Keep the selected tab's page in view when `value` changes from outside.
  useEffect(() => {
    if (width <= 0 || index === current.current) return;
    current.current = index;
    goTo(index);
    // goTo reads everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [index, width]);

  // Put the first page in place once the width is known.
  useEffect(() => {
    if (width <= 0) return;
    scrollX.setValue(index * width);
    pages.current?.scrollTo({ x: index * width, animated: false });
    // Only the first measurement positions the pages.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [width > 0]);

  // Slide the header so the selected label stays visible when there are many tabs.
  useEffect(() => {
    const box = boxes[index];
    if (!box || headerWidth.current <= 0) return;
    header.current?.scrollTo({
      x: Math.max(0, box.x - (headerWidth.current - box.width) / 2),
      animated: !reduceMotion,
    });
  }, [index, boxes, reduceMotion]);

  const settle = (x: number) => {
    offset.current = x;
    const next = Math.max(0, Math.min(live.current.last, Math.round(x / live.current.width)));
    if (next !== current.current) {
      current.current = next;
      live.current.onChange(live.current.tabs[next].id);
      AccessibilityInfo.announceForAccessibility(
        `${live.current.tabs[next].label}, tab ${next + 1} of ${live.current.last + 1}`,
      );
    }
  };

  const onScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
    offset.current = event.nativeEvent.contentOffset.x;
  };

  // A mouse cannot drag a scroll view, so on desktop browsers the pages are dragged by hand.
  const mouseDrag = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        Platform.OS === "web" &&
        typeof window !== "undefined" &&
        window.matchMedia("(pointer: fine)").matches &&
        Math.abs(g.dx) > 6 &&
        Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => {
        dragging.current = true;
        dragStart.current = offset.current;
        setSnapping(false);
      },
      onPanResponderMove: (_, g) => {
        pages.current?.scrollTo({ x: dragStart.current - g.dx, animated: false });
      },
      onPanResponderRelease: (_, g) => {
        setTimeout(() => (dragging.current = false), 80);
        setSnapping(true);
        // Carry a flick on to the next page, otherwise settle on the nearest one.
        const target = Math.round((offset.current - g.vx * 160) / live.current.width);
        const clamped = Math.max(0, Math.min(live.current.last, target));
        goTo(clamped);
        settle(clamped * live.current.width);
      },
      onPanResponderTerminate: () => {
        setTimeout(() => (dragging.current = false), 80);
        setSnapping(true);
        goTo(Math.round(offset.current / live.current.width));
      },
    }),
  ).current;

  const ready = width > 0 && boxes.length === tabs.length && tabs.length > 1;
  const inputRange = tabs.map((_, i) => i * width);

  const indicatorX = ready
    ? scrollX.interpolate({
        inputRange,
        outputRange: boxes.map((box) => box.x),
        extrapolate: "clamp",
      })
    : 0;
  const indicatorWidth = ready
    ? scrollX.interpolate({
        inputRange,
        outputRange: boxes.map((box) => box.width),
        extrapolate: "clamp",
      })
    : (boxes[0]?.width ?? 0);

  return (
    <View style={[styles.root, { backgroundColor: palette.background }, style]}>
      <View style={[styles.headerWrap, { borderBottomColor: palette.border }]}>
        <ScrollView
          ref={header}
          horizontal
          showsHorizontalScrollIndicator={false}
          onLayout={(event: LayoutChangeEvent) => {
            headerWidth.current = event.nativeEvent.layout.width;
          }}
          accessibilityRole="tablist"
          contentContainerStyle={styles.header}
        >
          {tabs.map((tab, i) => {
            const selected = i === index;
            const color = ready
              ? scrollX.interpolate({
                  inputRange: [(i - 1) * width, i * width, (i + 1) * width],
                  outputRange: [palette.text, palette.activeText, palette.text],
                  extrapolate: "clamp",
                })
              : selected
                ? palette.activeText
                : palette.text;
            return (
              <Pressable
                key={tab.id}
                accessibilityRole="tab"
                accessibilityState={{ selected }}
                aria-selected={selected}
                onLayout={(event: LayoutChangeEvent) => {
                  const { x, width: w } = event.nativeEvent.layout;
                  setBoxes((all) => {
                    const next = [...all];
                    next[i] = { x, width: w };
                    return next;
                  });
                }}
                onPress={() => {
                  if (dragging.current) return;
                  goTo(i);
                  settle(i * live.current.width);
                }}
                style={styles.tab}
              >
                <Animated.Text numberOfLines={1} style={[styles.label, { color }]}>
                  {tab.label}
                </Animated.Text>
              </Pressable>
            );
          })}
          {boxes.length > 0 ? (
            <Animated.View
              pointerEvents="none"
              style={[
                styles.indicator,
                {
                  backgroundColor: palette.indicator,
                  width: indicatorWidth,
                  transform: [{ translateX: indicatorX }],
                },
              ]}
            />
          ) : null}
        </ScrollView>
      </View>
      <View
        onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
        style={styles.body}
      >
        {width > 0 ? (
          <View {...mouseDrag.panHandlers} style={styles.drag}>
            <Animated.ScrollView
              ref={pages}
              horizontal
              pagingEnabled={snapping}
              showsHorizontalScrollIndicator={false}
              scrollEventThrottle={16}
              onScroll={Animated.event([{ nativeEvent: { contentOffset: { x: scrollX } } }], {
                useNativeDriver: false,
                listener: onScroll,
              })}
              onMomentumScrollEnd={(event) => settle(event.nativeEvent.contentOffset.x)}
              onScrollEndDrag={(event) => {
                // Without momentum (a slow drag that stops on a page) the momentum event never fires.
                if (!live.current.reduceMotion) return;
                settle(event.nativeEvent.contentOffset.x);
              }}
            >
              {tabs.map((tab, i) => (
                <View
                  key={tab.id}
                  accessibilityLabel={`${tab.label}, page ${i + 1} of ${tabs.length}`}
                  role="tabpanel"
                  style={{ width }}
                >
                  {renderPage(tab, i)}
                </View>
              ))}
            </Animated.ScrollView>
          </View>
        ) : null}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1 },
  headerWrap: { borderBottomWidth: StyleSheet.hairlineWidth },
  header: { paddingHorizontal: 8, position: "relative" },
  tab: { minHeight: 48, paddingHorizontal: 14, justifyContent: "center", userSelect: "none" },
  label: { fontSize: 15, fontWeight: "600" },
  indicator: { position: "absolute", left: 0, bottom: 0, height: 3, borderRadius: 2 },
  body: { flex: 1 },
  // userSelect keeps a mouse drag on the web from selecting the page's text instead of moving the pages.
  drag: { flex: 1, userSelect: "none" },
});
```

---

# Wheel Picker

> A React Native scrolling wheel that snaps rows to the middle, fades them with distance, and settles reliably even when a mouse wheel stops.

Install: `npx @modus-ui/cli add wheel-picker`

An iOS-style scrolling wheel. Rows snap to the middle, shrink and fade with their distance from it, and `onChange` fires when the wheel comes to rest, including when a mouse wheel stops, not on every frame of the scroll. A tap on a row brings it to the middle, and screen readers can step through the options. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add wheel-picker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/wheel-picker.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { WheelPicker } from "@/components/ui/wheel-picker";

const sizes = ["Small", "Medium", "Large", "Extra large"].map((name) => ({
  value: name.toLowerCase(),
  label: name,
}));

export default function Example() {
  const [size, setSize] = useState("medium");

  return <WheelPicker label="Size" options={sizes} value={size} onChange={setSize} />;
}
```

## Props

| Prop           | Type                         | Default    | Description                                                                 |
| :------------- | :--------------------------- | :--------- | :-------------------------------------------------------------------------- |
| `options`      | `WheelPickerOption[]`        | -          | The rows, each with a `value` and a `label`.                                |
| `value`        | `string`                     | -          | The selected option's `value`.                                              |
| `onChange`     | `(value: string) => void`    | -          | Called once the wheel settles on a different option.                        |
| `itemHeight`   | `number`                     | `40`       | Height of one row.                                                          |
| `visibleCount` | `number`                     | `5`        | How many rows are visible. Use an odd number so one row sits in the middle. |
| `label`        | `string`                     | `"Picker"` | Spoken name of the wheel, for example "Hour".                               |
| `colors`       | `Partial<WheelPickerColors>` | -          | Overrides `text`, `selectedText` and `highlight`.                           |
| `style`        | `StyleProp<ViewStyle>`       | -          | Style for the wheel.                                                        |

## Source

`components/ui/wheel-picker.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  ScrollView,
  StyleSheet,
  View,
  type NativeScrollEvent,
  type NativeSyntheticEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// How long the scroll must be still before a mouse wheel counts as settled.
const SETTLE_MS = 140;

export interface WheelPickerOption {
  value: string;
  label: string;
}

export interface WheelPickerColors {
  text: string;
  selectedText: string;
  highlight: string;
}

const DEFAULT_COLORS: WheelPickerColors = {
  text: "#6b7280",
  selectedText: "#111827",
  highlight: "#f3f4f6",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface WheelPickerProps {
  options: WheelPickerOption[];
  /** The selected option's `value`. */
  value: string;
  /** Called once the wheel settles on a different option, not on every frame of the scroll. */
  onChange: (value: string) => void;
  /** Height of one row. */
  itemHeight?: number;
  /** How many rows are visible. Use an odd number so one row sits in the middle. */
  visibleCount?: number;
  /** Spoken name of the wheel, for example "Hour". */
  label?: string;
  colors?: Partial<WheelPickerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * An iOS-style scrolling wheel. Rows snap to the middle, shrink and fade with their distance from it,
 * and `onChange` fires when the wheel comes to rest, including when a mouse wheel stops. A tap on a
 * row brings it to the middle, and screen readers can step through the options.
 */
export function WheelPicker({
  options,
  value,
  onChange,
  itemHeight = 40,
  visibleCount = 5,
  label = "Picker",
  colors,
  style,
}: WheelPickerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const scroll = useRef<ElementRef<typeof ScrollView>>(null);
  const y = useRef(new Animated.Value(0)).current;
  const offset = useRef(0);
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);

  const index = Math.max(
    0,
    options.findIndex((option) => option.value === value),
  );
  // The option the wheel last settled on, so a settle that changes nothing stays quiet.
  const settled = useRef(index);
  const rows = Math.max(1, visibleCount);
  const pad = Math.floor(rows / 2) * itemHeight;

  const live = useRef({ options, itemHeight, reduceMotion, onChange });
  live.current = { options, itemHeight, reduceMotion, onChange };

  const scrollToIndex = (target: number, animated = !live.current.reduceMotion) => {
    scroll.current?.scrollTo({ y: target * live.current.itemHeight, animated });
  };

  const settle = () => {
    const { options: list, itemHeight: h } = live.current;
    const next = Math.max(0, Math.min(list.length - 1, Math.round(offset.current / h)));
    // On the web a wheel can stop between rows, so finish the snap by hand.
    if (Math.abs(offset.current - next * h) > 1) scrollToIndex(next);
    if (next !== settled.current) {
      settled.current = next;
      live.current.onChange(list[next].value);
    }
  };

  const queueSettle = () => {
    if (timer.current) clearTimeout(timer.current);
    timer.current = setTimeout(settle, SETTLE_MS);
  };

  useEffect(
    () => () => {
      if (timer.current) clearTimeout(timer.current);
    },
    [],
  );

  // Start on the selected row, and follow `value` when it changes from outside.
  useEffect(() => {
    if (index === settled.current && Math.abs(offset.current - index * itemHeight) < 2) return;
    settled.current = index;
    scrollToIndex(index, offset.current !== 0);
    // scrollToIndex reads everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [index, itemHeight]);

  const onScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
    offset.current = event.nativeEvent.contentOffset.y;
    queueSettle();
  };

  const step = (direction: 1 | -1) => {
    const next = Math.max(0, Math.min(options.length - 1, index + direction));
    if (next === index) return;
    settled.current = next;
    scrollToIndex(next);
    onChange(options[next].value);
  };

  const rowStyles = useMemo(
    () =>
      options.map((_, i) => {
        const at = (n: number) => (i + n) * itemHeight;
        const range = [at(-2), at(-1), at(0), at(1), at(2)];
        return {
          opacity: y.interpolate({
            inputRange: range,
            outputRange: [0.25, 0.5, 1, 0.5, 0.25],
            extrapolate: "clamp",
          }),
          scale: reduceMotion
            ? 1
            : y.interpolate({
                inputRange: range,
                outputRange: [0.8, 0.9, 1, 0.9, 0.8],
                extrapolate: "clamp",
              }),
          // The selected colour fades in over the plain one as a row nears the middle.
          selected: y.interpolate({
            inputRange: [at(-1), at(0), at(1)],
            outputRange: [0, 1, 0],
            extrapolate: "clamp",
          }),
        };
      }),
    [options, itemHeight, y, reduceMotion],
  );

  return (
    <View
      accessible
      accessibilityRole="adjustable"
      accessibilityLabel={label}
      aria-label={label}
      accessibilityValue={{ text: options[index]?.label }}
      aria-valuetext={options[index]?.label}
      accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(event) => step(event.nativeEvent.actionName === "increment" ? 1 : -1)}
      style={[styles.root, { height: itemHeight * rows }, style]}
    >
      <View
        pointerEvents="none"
        style={[styles.band, { top: pad, height: itemHeight, backgroundColor: palette.highlight }]}
      />
      <Animated.ScrollView
        ref={scroll}
        showsVerticalScrollIndicator={false}
        snapToInterval={itemHeight}
        decelerationRate="fast"
        scrollEventThrottle={16}
        contentContainerStyle={{ paddingVertical: pad }}
        onScroll={Animated.event([{ nativeEvent: { contentOffset: { y } } }], {
          useNativeDriver: NATIVE_DRIVER,
          listener: onScroll,
        })}
        onMomentumScrollEnd={settle}
        onScrollEndDrag={queueSettle}
      >
        {options.map((option, i) => (
          <Pressable
            key={option.value}
            accessible={false}
            aria-hidden
            onPress={() => {
              scrollToIndex(i);
              offset.current = i * itemHeight;
              queueSettle();
            }}
            style={{ height: itemHeight, justifyContent: "center", alignItems: "center" }}
          >
            <Animated.View
              style={{
                opacity: rowStyles[i].opacity,
                transform: [{ scale: rowStyles[i].scale }],
              }}
            >
              <Animated.Text style={[styles.label, { color: palette.text }]}>
                {option.label}
              </Animated.Text>
              <Animated.Text
                style={[
                  styles.label,
                  styles.over,
                  { color: palette.selectedText, opacity: rowStyles[i].selected },
                ]}
              >
                {option.label}
              </Animated.Text>
            </Animated.View>
          </Pressable>
        ))}
      </Animated.ScrollView>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { overflow: "hidden", userSelect: "none" },
  band: { position: "absolute", left: 0, right: 0, borderRadius: 10 },
  label: { fontSize: 20, fontWeight: "600", textAlign: "center" },
  over: { position: "absolute", left: 0, right: 0, top: 0 },
});
```

---

# Avatar Stack

> A React Native stack of overlapping avatars that spreads apart on a press, collapses extras into a plus count, and reads out who is in it.

Install: `npx @modus-ui/cli add avatar-stack`

Overlapping avatars that spread apart when you press them. Each avatar shows a photo when it has one, or coloured initials with a stable colour per name, and sits in a ring so the overlaps read as separate. Anyone past `max` collapses into a "+N" avatar that opens the rest. The group is read out as a sentence such as "Maya Chen, Leo Park and 3 others". Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add avatar-stack
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/avatar-stack.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { AvatarStack } from "@/components/ui/avatar-stack";

const people = [
  { id: "1", name: "Maya Chen" },
  { id: "2", name: "Leo Park", image: "https://example.com/leo.jpg" },
  { id: "3", name: "Ines Duarte" },
];

export default function Example() {
  return (
    <AvatarStack people={people} max={3} onPersonPress={(person) => console.log(person.name)} />
  );
}
```

## Props

| Prop            | Type                             | Default | Description                                                                                       |
| :-------------- | :------------------------------- | :------ | :------------------------------------------------------------------------------------------------ |
| `people`        | `AvatarPerson[]`                 | -       | Who is in the stack. Each has an `id`, a `name` and an optional `image` URL.                      |
| `max`           | `number`                         | `4`     | How many avatars show before the rest collapse into a "+N" avatar.                                |
| `size`          | `number`                         | `40`    | Diameter of each avatar.                                                                          |
| `overlap`       | `number`                         | `12`    | How far each avatar covers the one before it, in pixels.                                          |
| `expandOnPress` | `boolean`                        | `true`  | Pressing the stack spreads the avatars apart and reveals the ones past `max`.                     |
| `onPersonPress` | `(person: AvatarPerson) => void` | -       | Called with the person whose avatar is pressed, once the stack is spread (or if it can't spread). |
| `colors`        | `Partial<AvatarStackColors>`     | -       | Overrides `ring`, `text` and `plus`.                                                              |
| `style`         | `StyleProp<ViewStyle>`           | -       | Style for the stack.                                                                              |

## Source

`components/ui/avatar-stack.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Image,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

// How far apart avatars sit when the stack is spread, in place of the overlap.
const SPREAD_GAP = 8;
const RING = 2;
// Initials avatars take a stable color from this list, chosen by the person's name.
const PALETTE = [
  "#6366f1",
  "#0ea5e9",
  "#14b8a6",
  "#22c55e",
  "#f59e0b",
  "#ef4444",
  "#ec4899",
  "#8b5cf6",
];

export interface AvatarPerson {
  id: string;
  name: string;
  /** A photo URL. Without one the avatar shows the person's initials. */
  image?: string;
}

export interface AvatarStackColors {
  /** The ring around each avatar, normally the surface color, so overlaps read as separate. */
  ring: string;
  /** Initials. */
  text: string;
  /** Background of the "+N" avatar. */
  plus: string;
}

const DEFAULT_COLORS: AvatarStackColors = {
  ring: "#ffffff",
  text: "#ffffff",
  plus: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

const initialsOf = (name: string) =>
  name
    .split(/\s+/)
    .filter(Boolean)
    .slice(0, 2)
    .map((word) => word[0].toUpperCase())
    .join("");

const colorFor = (name: string) => {
  let sum = 0;
  for (const char of name) sum += char.charCodeAt(0);
  return PALETTE[sum % PALETTE.length];
};

/** "Maya Chen, Leo Park and 3 others": the first two names, then a count. */
function describe(people: AvatarPerson[]) {
  const [first, second] = people;
  if (!first) return "No people";
  if (!second) return first.name;
  const rest = people.length - 2;
  if (rest === 0) return `${first.name} and ${second.name}`;
  return `${first.name}, ${second.name} and ${rest} ${rest === 1 ? "other" : "others"}`;
}

export interface AvatarStackProps {
  people: AvatarPerson[];
  /** How many avatars show before the rest collapse into a "+N" avatar. */
  max?: number;
  /** Diameter of each avatar. */
  size?: number;
  /** How far each avatar covers the one before it, in pixels. */
  overlap?: number;
  /** Pressing the stack spreads the avatars apart and reveals the ones past `max`. */
  expandOnPress?: boolean;
  /** Called with the person whose avatar is pressed, once the stack is spread (or if it can't spread). */
  onPersonPress?: (person: AvatarPerson) => void;
  colors?: Partial<AvatarStackColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * Overlapping avatars with a "+N" for the rest. Press the stack and the avatars spring apart one after
 * another, showing everyone; press again, or anywhere outside, and they fold back. The group reads out
 * as "Maya Chen, Leo Park and 3 others", and with reduced motion it spreads without animating.
 */
export function AvatarStack({
  people,
  max = 4,
  size = 40,
  overlap = 12,
  expandOnPress = true,
  onPersonPress,
  colors,
  style,
}: AvatarStackProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  // `open` is the target; `showAll` stays true while the avatars fold back, then drops the extras.
  const [open, setOpen] = useState(false);
  const [showAll, setShowAll] = useState(false);
  // One 0 to 1 value per avatar, so they can spread one after another.
  const spreads = useRef(new Map<string, Animated.Value>());

  const hidden = Math.max(0, people.length - max);
  const shown = showAll ? people : people.slice(0, max);
  const showPlus = hidden > 0 && !showAll;

  const spreadFor = (key: string) => {
    let value = spreads.current.get(key);
    if (!value) {
      value = new Animated.Value(0);
      spreads.current.set(key, value);
    }
    return value;
  };

  useEffect(() => {
    const values = [...spreads.current.values()];
    const target = open ? 1 : 0;
    if (reduceMotion) {
      values.forEach((value) => value.setValue(target));
      if (!open) setShowAll(false);
      return;
    }
    // marginLeft is a layout property, so these springs cannot use the native driver.
    Animated.stagger(
      45,
      values.map((value) =>
        Animated.spring(value, {
          toValue: target,
          stiffness: 260,
          damping: 18,
          mass: 1,
          useNativeDriver: false,
        }),
      ),
    ).start(({ finished }) => {
      if (finished && !open) setShowAll(false);
    });
  }, [open, showAll, reduceMotion]);

  const toggle = () => {
    if (open) {
      setOpen(false);
      return;
    }
    setShowAll(true);
    setOpen(true);
  };

  const pressPerson = (person: AvatarPerson) => {
    // A press first spreads a folded stack; once it is spread (or if it cannot spread) it picks the person.
    if (expandOnPress && !open) {
      toggle();
      return;
    }
    if (onPersonPress) onPersonPress(person);
    else if (expandOnPress) toggle();
  };

  const interactive = expandOnPress || !!onPersonPress;
  const hitSlop = Math.max(0, Math.ceil((44 - size) / 2));

  const avatarStyle = (key: string, index: number, extra: boolean) => {
    const spread = spreadFor(key);
    return {
      marginLeft:
        index === 0
          ? 0
          : spread.interpolate({ inputRange: [0, 1], outputRange: [-overlap, SPREAD_GAP] }),
      // Avatars past `max` fade and grow in as the stack spreads.
      ...(extra
        ? {
            opacity: spread.interpolate({ inputRange: [0, 0.4, 1], outputRange: [0, 1, 1] }),
            transform: [
              { scale: spread.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) },
            ],
          }
        : null),
    };
  };

  const ring = {
    width: size,
    height: size,
    borderRadius: size / 2,
    borderWidth: RING,
    borderColor: palette.ring,
  };

  return (
    <View
      role="group"
      accessibilityLabel={describe(people)}
      aria-label={describe(people)}
      style={[styles.root, style]}
    >
      {open ? (
        // Pressing anywhere outside folds the stack. Touches outside a parent's bounds are ignored on
        // Android, where the stack's own avatars and the toggle still work.
        <Pressable
          accessible={false}
          importantForAccessibility="no"
          onPress={() => setOpen(false)}
          style={styles.backdrop}
        />
      ) : null}
      <View style={styles.row}>
        {shown.map((person, index) => (
          <Animated.View key={person.id} style={avatarStyle(person.id, index, index >= max)}>
            <Pressable
              disabled={!interactive}
              accessibilityRole={interactive ? "button" : undefined}
              accessibilityLabel={person.name}
              accessibilityState={expandOnPress ? { expanded: open } : undefined}
              aria-label={person.name}
              aria-expanded={expandOnPress ? open : undefined}
              hitSlop={hitSlop}
              onPress={() => pressPerson(person)}
              style={[
                styles.avatar,
                ring,
                { backgroundColor: person.image ? palette.plus : colorFor(person.name) },
              ]}
            >
              {person.image ? (
                <Image
                  accessibilityIgnoresInvertColors
                  alt=""
                  source={{ uri: person.image }}
                  style={{
                    width: size - RING * 2,
                    height: size - RING * 2,
                    borderRadius: size / 2,
                  }}
                />
              ) : (
                <Text style={[styles.initials, { color: palette.text, fontSize: size * 0.36 }]}>
                  {initialsOf(person.name)}
                </Text>
              )}
            </Pressable>
          </Animated.View>
        ))}
        {showPlus ? (
          <Animated.View key="plus" style={avatarStyle("plus", shown.length, false)}>
            <Pressable
              disabled={!expandOnPress}
              accessibilityRole={expandOnPress ? "button" : undefined}
              accessibilityLabel={`${hidden} more ${hidden === 1 ? "person" : "people"}`}
              accessibilityState={expandOnPress ? { expanded: open } : undefined}
              aria-label={`${hidden} more ${hidden === 1 ? "person" : "people"}`}
              aria-expanded={expandOnPress ? open : undefined}
              hitSlop={hitSlop}
              onPress={toggle}
              style={[styles.avatar, ring, { backgroundColor: palette.plus }]}
            >
              <Text style={[styles.initials, { color: palette.text, fontSize: size * 0.34 }]}>
                +{hidden}
              </Text>
            </Pressable>
          </Animated.View>
        ) : null}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { alignSelf: "flex-start" },
  backdrop: { position: "absolute", top: -4000, right: -4000, bottom: -4000, left: -4000 },
  // userSelect keeps a quick double press on the web from selecting the initials.
  row: { flexDirection: "row", alignItems: "center", userSelect: "none" },
  avatar: { alignItems: "center", justifyContent: "center", overflow: "hidden" },
  initials: { fontWeight: "700", letterSpacing: 0.3 },
});
```

---

# Stripe Progress

> A React Native progress bar whose fill grows on a spring and whose diagonal stripes drift, with an indeterminate mode and no gradient packages.

Install: `npx @modus-ui/cli add stripe-progress`

A progress bar whose fill grows with a spring and whose diagonal stripes drift along it. Leave `value` out and a segment travels across the track instead. The stripes are plain rotated views, so it needs no gradient or SVG package. With reduced motion nothing drifts or travels, but the fill still follows the value. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add stripe-progress
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/stripe-progress.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { StripeProgress } from "@/components/ui/stripe-progress";

export default function Example() {
  return (
    <>
      <StripeProgress label="Uploading" value={0.64} showPercent />
      <StripeProgress label="Syncing" />
    </>
  );
}
```

## Props

| Prop          | Type                            | Default      | Description                                                  |
| :------------ | :------------------------------ | :----------- | :----------------------------------------------------------- |
| `value`       | `number`                        | -            | Progress from 0 to 1. Leave it out for an indeterminate bar. |
| `height`      | `number`                        | `10`         | Height of the bar.                                           |
| `striped`     | `boolean`                       | `true`       | Draws diagonal stripes on the fill.                          |
| `animated`    | `boolean`                       | `true`       | Lets the stripes drift while the bar is determinate.         |
| `label`       | `string`                        | `"Progress"` | Spoken name of the bar.                                      |
| `showPercent` | `boolean`                       | `false`      | Shows the percentage next to the bar.                        |
| `colors`      | `Partial<StripeProgressColors>` | -            | Overrides `track`, `fill`, `stripe` and `text`.              |
| `style`       | `StyleProp<ViewStyle>`          | -            | Style for the row that holds the bar and the percentage.     |

## Source

`components/ui/stripe-progress.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// The indeterminate segment is this fraction of the track.
const SEGMENT = 0.4;
// Horizontal distance between two stripes.
const MIN_PERIOD = 16;

export interface StripeProgressColors {
  track: string;
  fill: string;
  stripe: string;
  text: string;
}

const DEFAULT_COLORS: StripeProgressColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  stripe: "rgba(255, 255, 255, 0.3)",
  text: "#374151",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface StripeProgressProps {
  /** Progress from 0 to 1. Leave it out for an indeterminate bar. */
  value?: number;
  /** Height of the bar. */
  height?: number;
  /** Draws diagonal stripes on the fill. */
  striped?: boolean;
  /** Lets the stripes drift while the bar is determinate. */
  animated?: boolean;
  /** Spoken name of the bar. */
  label?: string;
  /** Shows the percentage next to the bar. */
  showPercent?: boolean;
  colors?: Partial<StripeProgressColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A progress bar whose fill grows with a spring and whose diagonal stripes drift along it. Leave
 * `value` out and a segment travels across the track instead. Stripes are plain rotated views, so it
 * needs no gradient or SVG package. With reduced motion nothing drifts or travels, but the fill still
 * follows the value.
 */
export function StripeProgress({
  value,
  height = 10,
  striped = true,
  animated = true,
  label = "Progress",
  showPercent = false,
  colors,
  style,
}: StripeProgressProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const indeterminate = value === undefined;
  const clamped = Math.max(0, Math.min(1, value ?? 0));
  const percent = Math.round(clamped * 100);

  const fill = useRef(new Animated.Value(clamped)).current;
  const drift = useRef(new Animated.Value(0)).current;
  const travel = useRef(new Animated.Value(0)).current;

  const period = Math.max(MIN_PERIOD, height * 2);
  const stripeCount = width > 0 ? Math.ceil(width / period) + 3 : 0;
  const moving = !reduceMotion;

  // The fill follows the value.
  useEffect(() => {
    if (indeterminate) return;
    if (reduceMotion) {
      fill.setValue(clamped);
      return;
    }
    Animated.timing(fill, {
      toValue: clamped,
      duration: 450,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: false,
    }).start();
  }, [clamped, indeterminate, reduceMotion, fill]);

  // Both loops start once the width is known, on views that are mounted from the start.
  useEffect(() => {
    if (width <= 0 || !moving) return;
    const loops: Animated.CompositeAnimation[] = [];
    if (striped && animated && !indeterminate) {
      drift.setValue(0);
      loops.push(
        Animated.loop(
          Animated.timing(drift, {
            toValue: period,
            duration: 900,
            easing: Easing.linear,
            useNativeDriver: NATIVE_DRIVER,
          }),
        ),
      );
    }
    if (indeterminate) {
      travel.setValue(0);
      loops.push(
        Animated.loop(
          Animated.timing(travel, {
            toValue: 1,
            duration: 1300,
            easing: Easing.inOut(Easing.quad),
            useNativeDriver: NATIVE_DRIVER,
          }),
        ),
      );
    }
    loops.forEach((loop) => loop.start());
    return () => loops.forEach((loop) => loop.stop());
  }, [width, moving, striped, animated, indeterminate, period, drift, travel]);

  const fillWidth = useMemo(
    () => fill.interpolate({ inputRange: [0, 1], outputRange: [0, width], extrapolate: "clamp" }),
    [fill, width],
  );
  const segmentWidth = width * SEGMENT;
  const segmentX = useMemo(
    () => travel.interpolate({ inputRange: [0, 1], outputRange: [-segmentWidth, width] }),
    [travel, width, segmentWidth],
  );
  const stripeList = useMemo(() => Array.from({ length: stripeCount }, (_, i) => i), [stripeCount]);

  return (
    <View style={[styles.row, style]}>
      <View
        accessible
        accessibilityRole="progressbar"
        accessibilityLabel={label}
        aria-label={label}
        accessibilityValue={
          indeterminate ? { text: "In progress" } : { min: 0, max: 100, now: percent }
        }
        aria-valuemin={0}
        aria-valuemax={100}
        aria-valuenow={indeterminate ? undefined : percent}
        aria-valuetext={indeterminate ? "In progress" : `${percent} percent`}
        aria-busy={indeterminate}
        onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
        style={[styles.track, { height, borderRadius: height / 2, backgroundColor: palette.track }]}
      >
        <Animated.View
          style={[
            styles.fill,
            {
              width: fillWidth,
              backgroundColor: palette.fill,
              borderRadius: height / 2,
              opacity: indeterminate ? 0 : 1,
            },
          ]}
        >
          {striped ? (
            <Animated.View
              pointerEvents="none"
              style={[
                styles.stripes,
                {
                  left: -period * 2,
                  width: stripeCount * period,
                  transform: [{ translateX: drift }],
                },
              ]}
            >
              {stripeList.map((i) => (
                <View
                  key={i}
                  style={{
                    position: "absolute",
                    top: -height,
                    left: i * period,
                    width: period * 0.36,
                    height: height * 3,
                    backgroundColor: palette.stripe,
                    transform: [{ rotate: "45deg" }],
                  }}
                />
              ))}
            </Animated.View>
          ) : null}
        </Animated.View>
        <Animated.View
          pointerEvents="none"
          style={[
            styles.segment,
            {
              width: segmentWidth,
              backgroundColor: palette.fill,
              borderRadius: height / 2,
              opacity: indeterminate ? 1 : 0,
              transform: [{ translateX: moving ? segmentX : (width - segmentWidth) / 2 }],
            },
          ]}
        />
      </View>
      {showPercent ? (
        <Text style={[styles.percent, { color: palette.text }]}>
          {indeterminate ? "" : `${percent}%`}
        </Text>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 10 },
  track: { flex: 1, overflow: "hidden" },
  fill: { position: "absolute", top: 0, bottom: 0, left: 0, overflow: "hidden" },
  stripes: { position: "absolute", top: 0, bottom: 0 },
  segment: { position: "absolute", top: 0, bottom: 0, left: 0 },
  percent: { minWidth: 40, textAlign: "right", fontSize: 13, fontWeight: "600" },
});
```

---

# Range Slider

> A React Native slider with two thumbs for choosing a range, where the thumbs never cross, values snap to a step, and each thumb is adjustable for screen readers.

Install: `npx @modus-ui/cli add range-slider`

A slider with two thumbs for choosing a range, such as a price band. Each thumb drags on its own and can never cross the other, values snap to `step`, a bubble shows the value above the thumb you hold, and tapping the bare track moves the nearest thumb. Both thumbs are adjustable controls for screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add range-slider
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/range-slider.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { RangeSlider } from "@/components/ui/range-slider";

export default function Example() {
  const [price, setPrice] = useState<[number, number]>([100, 300]);

  return (
    <RangeSlider
      label="Price"
      value={price}
      onValueChange={setPrice}
      min={0}
      max={500}
      step={5}
      format={(value) => `$${value}`}
    />
  );
}
```

## Props

| Prop                | Type                                | Default   | Description                                                       |
| :------------------ | :---------------------------------- | :-------- | :---------------------------------------------------------------- |
| `value`             | `[number, number]`                  | -         | The selected range as `[low, high]`.                              |
| `onValueChange`     | `(value: [number, number]) => void` | -         | Called as either thumb moves.                                     |
| `onSlidingComplete` | `(value: [number, number]) => void` | -         | Called once when a drag ends, or after a tap on the track.        |
| `min`               | `number`                            | `0`       | The lowest value.                                                 |
| `max`               | `number`                            | `100`     | The highest value.                                                |
| `step`              | `number`                            | `1`       | Values snap to multiples of this from `min`.                      |
| `minGap`            | `number`                            | `0`       | The least the two thumbs may be apart.                            |
| `showBubbles`       | `boolean`                           | `true`    | Floats the thumb's value above it while it is held.               |
| `disabled`          | `boolean`                           | `false`   | Dims the slider and ignores input.                                |
| `label`             | `string`                            | `"Range"` | Spoken name of the range; the thumbs add "minimum" and "maximum". |
| `format`            | `(value: number) => string`         | -         | Turns a value into the text shown in the bubble and read out.     |
| `colors`            | `Partial<RangeSliderColors>`        | -         | Overrides `track`, `fill`, `thumb`, `bubble` and `bubbleText`.    |
| `style`             | `StyleProp<ViewStyle>`              | -         | Style for the slider.                                             |

## Source

`components/ui/range-slider.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const THUMB = 28;

export interface RangeSliderColors {
  track: string;
  fill: string;
  thumb: string;
  bubble: string;
  bubbleText: string;
}

const DEFAULT_COLORS: RangeSliderColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  thumb: "#ffffff",
  bubble: "#111827",
  bubbleText: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface RangeSliderProps {
  /** The selected range as [low, high]. */
  value: [number, number];
  onValueChange: (value: [number, number]) => void;
  /** Called once when a drag ends. */
  onSlidingComplete?: (value: [number, number]) => void;
  min?: number;
  max?: number;
  step?: number;
  /** The least the two thumbs may be apart. */
  minGap?: number;
  /** Floats the thumb's value above it while it is held. */
  showBubbles?: boolean;
  disabled?: boolean;
  /** Spoken name of the range; the thumbs add "minimum" and "maximum". */
  label?: string;
  /** Turns a value into the text shown in the bubble and read out. */
  format?: (value: number) => string;
  colors?: Partial<RangeSliderColors>;
  style?: StyleProp<ViewStyle>;
}

type Which = 0 | 1;

/**
 * A slider with two thumbs for choosing a range, such as a price band. Each thumb drags on its own and
 * can never cross the other, values snap to `step`, and tapping the track moves the nearest thumb.
 * Both thumbs are adjustable controls for screen readers.
 */
export function RangeSlider({
  value,
  onValueChange,
  onSlidingComplete,
  min = 0,
  max = 100,
  step = 1,
  minGap = 0,
  showBubbles = true,
  disabled = false,
  label = "Range",
  format = String,
  colors,
  style,
}: RangeSliderProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const [active, setActive] = useState<Which | null>(null);
  const [top, setTop] = useState<Which>(1);
  const grow = useRef([new Animated.Value(0), new Animated.Value(0)]).current;
  const startValue = useRef(0);

  const live = useRef({
    value,
    min,
    max,
    step,
    minGap,
    width,
    disabled,
    onValueChange,
    onSlidingComplete,
  });
  live.current = {
    value,
    min,
    max,
    step,
    minGap,
    width,
    disabled,
    onValueChange,
    onSlidingComplete,
  };

  const travel = Math.max(1, width - THUMB);
  const toX = (v: number) => ((v - min) / (max - min)) * travel;
  const lowX = toX(value[0]);
  const highX = toX(value[1]);

  const snap = (raw: number) => {
    const { min: lo, max: hi, step: s } = live.current;
    const snapped = Math.round((raw - lo) / s) * s + lo;
    return Math.max(lo, Math.min(hi, Number(snapped.toFixed(6))));
  };

  const setThumb = (which: Which, raw: number) => {
    const { value: current, minGap: gap, min: lo, max: hi } = live.current;
    const next: [number, number] = [current[0], current[1]];
    const snapped = snap(raw);
    next[which] =
      which === 0 ? Math.min(snapped, current[1] - gap) : Math.max(snapped, current[0] + gap);
    next[which] = Math.max(lo, Math.min(hi, next[which]));
    if (next[0] !== current[0] || next[1] !== current[1]) live.current.onValueChange(next);
  };

  const press = (which: Which, down: boolean) => {
    setActive(down ? which : null);
    if (down) setTop(which);
    if (reduceMotion) return;
    Animated.spring(grow[which], {
      toValue: down ? 1 : 0,
      stiffness: 420,
      damping: 24,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const makeResponder = (which: Which) =>
    PanResponder.create({
      onStartShouldSetPanResponder: () => !live.current.disabled,
      onMoveShouldSetPanResponder: () => !live.current.disabled,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: () => {
        startValue.current = live.current.value[which];
        press(which, true);
      },
      onPanResponderMove: (_, g) => {
        const { min: lo, max: hi, width: w } = live.current;
        const perPixel = (hi - lo) / Math.max(1, w - THUMB);
        setThumb(which, startValue.current + g.dx * perPixel);
      },
      onPanResponderRelease: () => {
        press(which, false);
        live.current.onSlidingComplete?.(live.current.value);
      },
      onPanResponderTerminate: () => press(which, false),
    });
  // Responders are created once per thumb and read everything through `live`.
  const responders = useRef([makeResponder(0), makeResponder(1)]).current;

  // Touching the bare track moves whichever thumb is closer to it, and the drag carries on from there.
  const trackWhich = useRef<Which>(0);
  const trackResponder = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => !live.current.disabled,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: (event) => {
        const { value: current, min: lo, max: hi, width: w } = live.current;
        const x = event.nativeEvent.locationX;
        const raw = lo + ((x - THUMB / 2) / Math.max(1, w - THUMB)) * (hi - lo);
        if (!Number.isFinite(raw)) return;
        const which: Which = Math.abs(raw - current[0]) <= Math.abs(raw - current[1]) ? 0 : 1;
        trackWhich.current = which;
        setThumb(which, raw);
        startValue.current = snap(raw);
        press(which, true);
      },
      onPanResponderMove: (_, g) => {
        const { min: lo, max: hi, width: w } = live.current;
        setThumb(
          trackWhich.current,
          startValue.current + g.dx * ((hi - lo) / Math.max(1, w - THUMB)),
        );
      },
      onPanResponderRelease: () => {
        press(trackWhich.current, false);
        live.current.onSlidingComplete?.(live.current.value);
      },
      onPanResponderTerminate: () => press(trackWhich.current, false),
    }),
  ).current;

  const adjust = (which: Which, direction: 1 | -1) =>
    setThumb(which, value[which] + direction * step);

  const thumb = (which: Which) => {
    const x = which === 0 ? lowX : highX;
    const name = which === 0 ? "minimum" : "maximum";
    const text = format(value[which]);
    const scale = grow[which].interpolate({ inputRange: [0, 1], outputRange: [1, 1.18] });
    return (
      <Animated.View
        key={which}
        {...responders[which].panHandlers}
        accessible
        accessibilityRole="adjustable"
        accessibilityLabel={`${label} ${name}`}
        aria-label={`${label} ${name}`}
        accessibilityValue={{ min, max, now: value[which], text }}
        aria-valuemin={min}
        aria-valuemax={max}
        aria-valuenow={value[which]}
        aria-valuetext={text}
        aria-disabled={disabled}
        accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
        onAccessibilityAction={(event) =>
          adjust(which, event.nativeEvent.actionName === "increment" ? 1 : -1)
        }
        style={[
          styles.thumb,
          {
            left: x,
            zIndex: top === which ? 2 : 1,
            backgroundColor: palette.thumb,
            transform: [{ scale }],
          },
        ]}
      >
        {showBubbles && active === which ? (
          <View pointerEvents="none" style={styles.bubbleWrap}>
            <View style={[styles.bubble, { backgroundColor: palette.bubble }]}>
              <Text style={[styles.bubbleText, { color: palette.bubbleText }]}>{text}</Text>
            </View>
          </View>
        ) : null}
      </Animated.View>
    );
  };

  return (
    <View
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={[styles.root, disabled && styles.disabled, style]}
    >
      <View {...trackResponder.panHandlers} style={styles.hit}>
        <View style={[styles.track, { backgroundColor: palette.track }]} />
        <View
          pointerEvents="none"
          style={[
            styles.fill,
            {
              left: lowX + THUMB / 2,
              width: Math.max(0, highX - lowX),
              backgroundColor: palette.fill,
            },
          ]}
        />
      </View>
      {width > 0 ? [thumb(0), thumb(1)] : null}
    </View>
  );
}

const styles = StyleSheet.create({
  root: { height: 44, justifyContent: "center", userSelect: "none" },
  hit: { height: 44, justifyContent: "center" },
  track: { height: 6, borderRadius: 3 },
  fill: { position: "absolute", top: 19, height: 6, borderRadius: 3 },
  thumb: {
    position: "absolute",
    top: (44 - THUMB) / 2,
    width: THUMB,
    height: THUMB,
    borderRadius: THUMB / 2,
    boxShadow: "0 2px 6px rgba(0, 0, 0, 0.3)",
  },
  // Wider than the thumb and centred on it, so the bubble sits right above whatever its width is.
  bubbleWrap: {
    position: "absolute",
    bottom: THUMB + 6,
    left: -40,
    width: THUMB + 80,
    alignItems: "center",
  },
  bubble: {
    minWidth: 36,
    paddingHorizontal: 8,
    paddingVertical: 4,
    borderRadius: 8,
    alignItems: "center",
  },
  bubbleText: { fontSize: 12, fontWeight: "700" },
  disabled: { opacity: 0.4 },
});
```

---

# Tick Box

> A React Native checkbox that pops its fill in on a spring, grows its tick, and has a mixed state for select-all boxes.

Install: `npx @modus-ui/cli add tick-box`

A checkbox whose fill pops in on a spring and whose tick grows out of the box. It also has a "mixed" state for a select-all box over partly checked children. The whole row is the touch target, pressing the label toggles it, and the state is read out as checked, unchecked or mixed. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add tick-box
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tick-box.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { TickBox } from "@/components/ui/tick-box";

export default function Example() {
  const [agreed, setAgreed] = useState(false);

  return <TickBox label="I agree to the terms" checked={agreed} onChange={setAgreed} />;
}
```

## Props

| Prop          | Type                      | Default | Description                                                                      |
| :------------ | :------------------------ | :------ | :------------------------------------------------------------------------------- |
| `checked`     | `boolean \| "mixed"`      | -       | Checked, unchecked, or `"mixed"` for a parent whose children are partly checked. |
| `onChange`    | `(next: boolean) => void` | -       | Called with the new state when pressed. A mixed box becomes checked.             |
| `label`       | `string`                  | -       | Text beside the box. Pressing it toggles the box too.                            |
| `description` | `string`                  | -       | A second, smaller line under the label.                                          |
| `size`        | `number`                  | `24`    | Side of the box.                                                                 |
| `round`       | `boolean`                 | `false` | Draws a circle instead of a rounded square.                                      |
| `disabled`    | `boolean`                 | `false` | Dims the row and ignores presses.                                                |
| `colors`      | `Partial<TickBoxColors>`  | -       | Overrides `border`, `fill`, `tick`, `text` and `description`.                    |
| `style`       | `StyleProp<ViewStyle>`    | -       | Style for the row.                                                               |

## Source

`components/ui/tick-box.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface TickBoxColors {
  border: string;
  fill: string;
  tick: string;
  text: string;
  description: string;
}

const DEFAULT_COLORS: TickBoxColors = {
  border: "#9ca3af",
  fill: "#4f46e5",
  tick: "#ffffff",
  text: "#111827",
  description: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface TickBoxProps {
  /** Checked, unchecked, or "mixed" for a parent whose children are partly checked. */
  checked: boolean | "mixed";
  /** Called with the new state when pressed. A "mixed" box becomes checked. */
  onChange: (next: boolean) => void;
  /** Text beside the box. Pressing it toggles the box too. */
  label?: string;
  /** A second, smaller line under the label. */
  description?: string;
  /** Side of the box. */
  size?: number;
  /** Draws a circle instead of a rounded square. */
  round?: boolean;
  disabled?: boolean;
  /** Extra content shown after the label. */
  children?: ReactNode;
  colors?: Partial<TickBoxColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A checkbox whose fill pops in on a spring and whose tick grows out of its corner. It also has the
 * "mixed" state for a select-all box over partly checked children. The whole row is the touch target,
 * with the state read out as checked, unchecked or mixed.
 */
export function TickBox({
  checked,
  onChange,
  label,
  description,
  size = 24,
  round = false,
  disabled = false,
  children,
  colors,
  style,
}: TickBoxProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const on = checked === true;
  const mixed = checked === "mixed";
  const fill = useRef(new Animated.Value(on || mixed ? 1 : 0)).current;
  const tick = useRef(new Animated.Value(on ? 1 : 0)).current;
  const bar = useRef(new Animated.Value(mixed ? 1 : 0)).current;
  const press = useRef(new Animated.Value(1)).current;

  useEffect(() => {
    const to = (value: Animated.Value, toValue: number, stiffness = 380) =>
      reduceMotion
        ? value.setValue(toValue)
        : Animated.spring(value, {
            toValue,
            stiffness,
            damping: 22,
            mass: 1,
            useNativeDriver: NATIVE_DRIVER,
          }).start();
    to(fill, on || mixed ? 1 : 0);
    to(tick, on ? 1 : 0, 300);
    to(bar, mixed ? 1 : 0, 300);
  }, [on, mixed, reduceMotion, fill, tick, bar]);

  const dip = (down: boolean) => {
    if (reduceMotion) return;
    Animated.spring(press, {
      toValue: down ? 0.92 : 1,
      stiffness: 500,
      damping: 24,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const radius = round ? size / 2 : size * 0.26;
  const stem = size * 0.5;
  const foot = size * 0.26;

  return (
    <Pressable
      accessibilityRole="checkbox"
      accessibilityLabel={label}
      accessibilityState={{ checked: mixed ? "mixed" : on, disabled }}
      aria-checked={mixed ? "mixed" : on}
      aria-disabled={disabled}
      disabled={disabled}
      hitSlop={6}
      onPress={() => onChange(!on)}
      onPressIn={() => dip(true)}
      onPressOut={() => dip(false)}
      style={[styles.row, disabled && styles.disabled, style]}
    >
      <Animated.View
        style={{
          width: size,
          height: size,
          borderRadius: radius,
          borderWidth: 2,
          borderColor: on || mixed ? palette.fill : palette.border,
          alignItems: "center",
          justifyContent: "center",
          transform: [{ scale: press }],
        }}
      >
        <Animated.View
          style={[
            StyleSheet.absoluteFill,
            {
              borderRadius: Math.max(0, radius - 2),
              backgroundColor: palette.fill,
              opacity: fill,
              transform: [
                { scale: fill.interpolate({ inputRange: [0, 1], outputRange: [0.4, 1] }) },
              ],
            },
          ]}
        />
        <Animated.View
          style={{
            width: foot,
            height: stem,
            marginTop: -size * 0.06,
            borderRightWidth: 2.5,
            borderBottomWidth: 2.5,
            borderColor: palette.tick,
            opacity: tick,
            transform: [
              { rotate: "45deg" },
              { scale: tick.interpolate({ inputRange: [0, 1], outputRange: [0.3, 1] }) },
            ],
          }}
        />
        <Animated.View
          style={{
            position: "absolute",
            width: size * 0.5,
            height: 2.5,
            borderRadius: 2,
            backgroundColor: palette.tick,
            opacity: bar,
            transform: [{ scaleX: bar.interpolate({ inputRange: [0, 1], outputRange: [0.2, 1] }) }],
          }}
        />
      </Animated.View>
      {label || description || children ? (
        <View style={styles.text}>
          {label ? <Text style={[styles.label, { color: palette.text }]}>{label}</Text> : null}
          {description ? (
            <Text style={[styles.description, { color: palette.description }]}>{description}</Text>
          ) : null}
          {children}
        </View>
      ) : null}
    </Pressable>
  );
}

const styles = StyleSheet.create({
  row: {
    flexDirection: "row",
    alignItems: "flex-start",
    gap: 12,
    minHeight: 44,
    paddingVertical: 8,
    userSelect: "none",
  },
  text: { flex: 1, gap: 2 },
  label: { fontSize: 16, fontWeight: "600", lineHeight: 24 },
  description: { fontSize: 13, lineHeight: 18 },
  disabled: { opacity: 0.45 },
});
```

---

# Notice Banner

> A React Native inline alert in four tones that slides in, collapses its height on the way out, and can be swiped away or closed with a button.

Install: `npx @modus-ui/cli add notice-banner`

An inline alert in one of four tones: info, success, warning and error. It slides in and collapses its height on the way out, so the content below follows smoothly. With `onDismiss` it shows a close button and can also be swiped sideways. Errors and warnings are announced at once, and the other tones wait politely. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add notice-banner
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/notice-banner.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { NoticeBanner } from "@/components/ui/notice-banner";

export default function Example() {
  const [open, setOpen] = useState(true);

  return (
    <NoticeBanner
      tone="warning"
      title="Storage almost full"
      message="You have used 9.2 of 10 GB."
      visible={open}
      onDismiss={() => setOpen(false)}
      action={{ label: "Manage", onPress: () => console.log("manage") }}
    />
  );
}
```

## Props

| Prop        | Type                                     | Default  | Description                                                                        |
| :---------- | :--------------------------------------- | :------- | :--------------------------------------------------------------------------------- |
| `title`     | `string`                                 | -        | The banner's heading.                                                              |
| `message`   | `string`                                 | -        | Text under the heading.                                                            |
| `tone`      | `NoticeTone`                             | `"info"` | One of `"info"`, `"success"`, `"warning"` and `"error"`.                           |
| `visible`   | `boolean`                                | `true`   | Shows or hides the banner. It slides in and collapses out.                         |
| `onDismiss` | `() => void`                             | -        | When given, the banner shows a close button and can be swiped away.                |
| `action`    | `{ label: string; onPress: () => void }` | -        | A button under the message, for example "Undo" or "View".                          |
| `colors`    | `Partial<NoticeBannerColors>`            | -        | Overrides `info`, `success`, `warning`, `error`, `surface`, `title` and `message`. |
| `style`     | `StyleProp<ViewStyle>`                   | -        | Style for the banner card.                                                         |

## Source

`components/ui/notice-banner.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const SWIPE_AWAY = 90;

export type NoticeTone = "info" | "success" | "warning" | "error";

export interface NoticeBannerColors {
  info: string;
  success: string;
  warning: string;
  error: string;
  surface: string;
  title: string;
  message: string;
}

const DEFAULT_COLORS: NoticeBannerColors = {
  info: "#2563eb",
  success: "#16a34a",
  warning: "#d97706",
  error: "#dc2626",
  surface: "#ffffff",
  title: "#111827",
  message: "#4b5563",
};

const GLYPH: Record<NoticeTone, string> = { info: "i", success: "✓", warning: "!", error: "×" };

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface NoticeBannerProps {
  title: string;
  message?: string;
  tone?: NoticeTone;
  /** Shows or hides the banner. It slides in and collapses out, so the content below follows smoothly. */
  visible?: boolean;
  /** When given, the banner shows a close button and can be swiped away. */
  onDismiss?: () => void;
  /** A button under the message, for example "Undo" or "View". */
  action?: { label: string; onPress: () => void };
  colors?: Partial<NoticeBannerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * An inline alert in one of four tones. It slides in and collapses its height on the way out, so the
 * content below follows smoothly, and with `onDismiss` it can be closed with a button or swiped
 * sideways. Errors and warnings are announced at once; the other tones wait politely.
 */
export function NoticeBanner({
  title,
  message,
  tone = "info",
  visible = true,
  onDismiss,
  action,
  colors,
  style,
}: NoticeBannerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [shown, setShown] = useState(visible);
  const [mounted, setMounted] = useState(visible);
  const [height, setHeight] = useState(0);
  const t = useRef(new Animated.Value(visible ? 1 : 0)).current;
  const x = useRef(new Animated.Value(0)).current;
  // True during a drag and for a moment after it: the click a mouse sends on release is not a tap.
  const dragging = useRef(false);

  const live = useRef({ onDismiss, reduceMotion });
  live.current = { onDismiss, reduceMotion };

  // Follow the `visible` prop.
  useEffect(() => setShown(visible), [visible]);

  useEffect(() => {
    if (shown) setMounted(true);
    x.setValue(0);
    if (reduceMotion) {
      t.setValue(shown ? 1 : 0);
      if (!shown) setMounted(false);
      return;
    }
    Animated.timing(t, {
      toValue: shown ? 1 : 0,
      duration: 260,
      useNativeDriver: false,
    }).start(({ finished }) => {
      if (finished && !shown) setMounted(false);
    });
  }, [shown, reduceMotion, t, x]);

  const dismiss = () => {
    setShown(false);
    live.current.onDismiss?.();
  };

  const pan = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        !!live.current.onDismiss && Math.abs(g.dx) > 8 && Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => {
        dragging.current = true;
      },
      onPanResponderMove: (_, g) => x.setValue(g.dx),
      onPanResponderRelease: (_, g) => {
        setTimeout(() => (dragging.current = false), 80);
        if (Math.abs(g.dx) > SWIPE_AWAY || Math.abs(g.vx) > 0.8) {
          dismiss();
          return;
        }
        if (live.current.reduceMotion) x.setValue(0);
        else
          Animated.spring(x, {
            toValue: 0,
            stiffness: 360,
            damping: 28,
            mass: 1,
            useNativeDriver: NATIVE_DRIVER,
          }).start();
      },
      onPanResponderTerminate: () => {
        setTimeout(() => (dragging.current = false), 80);
        x.setValue(0);
      },
    }),
  ).current;

  if (!mounted) return null;

  const accent = palette[tone];
  const urgent = tone === "error" || tone === "warning";

  return (
    <Animated.View
      style={{
        height:
          height > 0 ? t.interpolate({ inputRange: [0, 1], outputRange: [0, height] }) : undefined,
        opacity: t,
        overflow: "hidden",
      }}
    >
      <View onLayout={(event: LayoutChangeEvent) => setHeight(event.nativeEvent.layout.height)}>
        <Animated.View
          {...pan.panHandlers}
          role={urgent ? "alert" : "status"}
          accessibilityLiveRegion={urgent ? "assertive" : "polite"}
          aria-live={urgent ? "assertive" : "polite"}
          style={[
            styles.card,
            {
              backgroundColor: palette.surface,
              borderColor: accent,
              transform: [{ translateX: x }],
            },
            style,
          ]}
        >
          <View style={[styles.glyph, { backgroundColor: accent }]} accessible={false}>
            <Text style={styles.glyphText}>{GLYPH[tone]}</Text>
          </View>
          <View style={styles.body}>
            <Text style={[styles.title, { color: palette.title }]}>{title}</Text>
            {message ? (
              <Text style={[styles.message, { color: palette.message }]}>{message}</Text>
            ) : null}
            {action ? (
              <Pressable
                accessibilityRole="button"
                hitSlop={8}
                onPress={() => {
                  if (!dragging.current) action.onPress();
                }}
                style={({ pressed }) => [styles.action, pressed && styles.dim]}
              >
                <Text style={[styles.actionText, { color: accent }]}>{action.label}</Text>
              </Pressable>
            ) : null}
          </View>
          {onDismiss ? (
            <Pressable
              accessibilityRole="button"
              accessibilityLabel="Dismiss"
              hitSlop={12}
              onPress={() => {
                if (!dragging.current) dismiss();
              }}
              style={({ pressed }) => [styles.close, pressed && styles.dim]}
            >
              <Text style={[styles.closeText, { color: palette.message }]}>×</Text>
            </Pressable>
          ) : null}
        </Animated.View>
      </View>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  card: {
    flexDirection: "row",
    alignItems: "flex-start",
    gap: 12,
    padding: 14,
    borderRadius: 14,
    borderWidth: 1,
    borderLeftWidth: 4,
    userSelect: "none",
  },
  glyph: {
    width: 24,
    height: 24,
    borderRadius: 12,
    alignItems: "center",
    justifyContent: "center",
    marginTop: 1,
  },
  glyphText: { color: "#ffffff", fontSize: 14, fontWeight: "800", lineHeight: 18 },
  body: { flex: 1, gap: 2 },
  title: { fontSize: 15, fontWeight: "700", lineHeight: 22 },
  message: { fontSize: 14, lineHeight: 20 },
  action: { alignSelf: "flex-start", minHeight: 32, justifyContent: "center", marginTop: 4 },
  actionText: { fontSize: 14, fontWeight: "700" },
  close: { width: 28, height: 28, alignItems: "center", justifyContent: "center" },
  closeText: { fontSize: 22, lineHeight: 24 },
  dim: { opacity: 0.6 },
});
```

---

# Side Drawer

> A React Native panel that slides in from the left or right edge, follows your finger as you drag it shut, and can be pulled open by a swipe from the screen edge.

Install: `npx @modus-ui/cli add side-drawer`

A panel that slides in from the left or right edge of its parent. Drag it toward its edge to close it, tap the backdrop, or press Escape on the web. Give it `onOpen` and a swipe that starts at the screen edge pulls it open, following your finger, then settles open or shut by how far and how fast you went. It is drawn inside the screen it belongs to, so the parent must fill that screen. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add side-drawer
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/side-drawer.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Button, Text, View } from "react-native";
import { SideDrawer } from "@/components/ui/side-drawer";

export default function Example() {
  const [open, setOpen] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Menu" onPress={() => setOpen(true)} />
      <SideDrawer open={open} onOpen={() => setOpen(true)} onClose={() => setOpen(false)}>
        <Text style={{ padding: 20 }}>Drawer content</Text>
      </SideDrawer>
    </View>
  );
}
```

## Props

| Prop      | Type                        | Default  | Description                                                                               |
| :-------- | :-------------------------- | :------- | :---------------------------------------------------------------------------------------- |
| `open`    | `boolean`                   | -        | Whether the drawer is showing.                                                            |
| `onClose` | `() => void`                | -        | Called when the drawer is closed by a backdrop tap, a drag or Escape on the web.          |
| `onOpen`  | `() => void`                | -        | Called when a swipe from the screen edge pulls it open. Without it the edge swipe is off. |
| `side`    | `"left" \| "right"`         | `"left"` | Which edge the drawer comes from.                                                         |
| `width`   | `number`                    | `280`    | Width of the panel.                                                                       |
| `label`   | `string`                    | `"Menu"` | Spoken name of the drawer.                                                                |
| `colors`  | `Partial<SideDrawerColors>` | -        | Overrides `surface`, `backdrop` and `border`.                                             |
| `style`   | `StyleProp<ViewStyle>`      | -        | Style for the panel.                                                                      |

## Source

`components/ui/side-drawer.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
// Width of the strip along the edge that a swipe can start from.
const EDGE = 22;

export interface SideDrawerColors {
  surface: string;
  backdrop: string;
  border: string;
}

const DEFAULT_COLORS: SideDrawerColors = {
  surface: "#ffffff",
  backdrop: "rgba(0, 0, 0, 0.45)",
  border: "#e5e7eb",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SideDrawerProps {
  open: boolean;
  /** Called when the drawer is closed by a backdrop tap, a drag or Escape on the web. */
  onClose: () => void;
  /** Called when a swipe from the screen edge pulls it open. Without it the edge swipe is off. */
  onOpen?: () => void;
  /** Which edge the drawer comes from. */
  side?: "left" | "right";
  /** Width of the panel. */
  width?: number;
  /** Spoken name of the drawer. */
  label?: string;
  children: ReactNode;
  colors?: Partial<SideDrawerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A panel that slides in from the left or right edge of its parent. Drag it toward its edge to close
 * it, tap the backdrop, or press Escape on the web. Give it `onOpen` and a swipe that starts at the
 * screen edge pulls it open, following your finger. Draw it inside the screen it belongs to, so the
 * parent must fill that screen.
 */
export function SideDrawer({
  open,
  onClose,
  onOpen,
  side = "left",
  width = 280,
  label = "Menu",
  children,
  colors,
  style,
}: SideDrawerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  // 0 is closed, 1 is open, and a drag sets it anywhere between.
  const p = useRef(new Animated.Value(open ? 1 : 0)).current;
  const current = useRef(open ? 1 : 0);
  const sign = side === "left" ? -1 : 1;

  const live = useRef({ open, onClose, onOpen, width, reduceMotion, sign });
  live.current = { open, onClose, onOpen, width, reduceMotion, sign };

  const animateTo = (target: 0 | 1, velocity = 0) => {
    current.current = target;
    if (live.current.reduceMotion) {
      p.setValue(target);
      return;
    }
    Animated.spring(p, {
      toValue: target,
      velocity,
      stiffness: 320,
      damping: 32,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  useEffect(() => {
    animateTo(open ? 1 : 0);
    // animateTo reads everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [open, reduceMotion]);

  // Escape closes it on the web.
  useEffect(() => {
    if (!open || Platform.OS !== "web") return;
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape") live.current.onClose();
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [open]);

  const settle = (progress: number, vx: number, wasOpen: boolean) => {
    const { sign: dir, width: w } = live.current;
    // Velocity toward the open direction (positive) or away from it (negative), in progress per ms.
    const along = (vx * -dir) / w;
    const target: 0 | 1 = along > 0.0015 ? 1 : along < -0.0015 ? 0 : progress > 0.5 ? 1 : 0;
    animateTo(target, along * 1000);
    if (target === 1 && !wasOpen) live.current.onOpen?.();
    if (target === 0 && wasOpen) live.current.onClose();
  };

  // Drag the open panel toward its edge to close it.
  const closeDrag = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        live.current.open && Math.abs(g.dx) > 6 && Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => p.stopAnimation(),
      onPanResponderMove: (_, g) => {
        const { sign: dir, width: w } = live.current;
        p.setValue(Math.max(0, Math.min(1, 1 + (g.dx * dir) / w)));
      },
      onPanResponderRelease: (_, g) => {
        const { sign: dir, width: w } = live.current;
        settle(Math.max(0, Math.min(1, 1 + (g.dx * dir) / w)), g.vx, true);
      },
      onPanResponderTerminate: () => animateTo(live.current.open ? 1 : 0),
    }),
  ).current;

  // A swipe from the screen edge pulls the closed panel open.
  const edgeDrag = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => !live.current.open && !!live.current.onOpen,
      onMoveShouldSetPanResponder: (_, g) =>
        !live.current.open &&
        !!live.current.onOpen &&
        Math.abs(g.dx) > 4 &&
        Math.abs(g.dx) > Math.abs(g.dy),
      onPanResponderGrant: () => p.stopAnimation(),
      onPanResponderMove: (_, g) => {
        const { sign: dir, width: w } = live.current;
        p.setValue(Math.max(0, Math.min(1, (g.dx * -dir) / w)));
      },
      onPanResponderRelease: (_, g) => {
        const { sign: dir, width: w } = live.current;
        settle(Math.max(0, Math.min(1, (g.dx * -dir) / w)), g.vx, false);
      },
      onPanResponderTerminate: () => animateTo(0),
    }),
  ).current;

  const translateX = p.interpolate({ inputRange: [0, 1], outputRange: [sign * width, 0] });

  return (
    <View style={styles.root} pointerEvents="box-none">
      <Animated.View
        aria-hidden
        pointerEvents={open ? "auto" : "none"}
        style={[styles.fill, { backgroundColor: palette.backdrop, opacity: p }]}
      >
        <Pressable accessible={false} onPress={onClose} style={styles.fill} />
      </Animated.View>
      {!open && onOpen ? (
        <View
          {...edgeDrag.panHandlers}
          style={[styles.edge, side === "left" ? { left: 0 } : { right: 0 }]}
        />
      ) : null}
      <Animated.View
        {...closeDrag.panHandlers}
        role="dialog"
        aria-modal={open}
        aria-label={label}
        aria-hidden={!open}
        accessibilityLabel={label}
        accessibilityViewIsModal={open}
        importantForAccessibility={open ? "yes" : "no-hide-descendants"}
        style={[
          styles.panel,
          side === "left" ? { left: 0 } : { right: 0 },
          {
            width,
            backgroundColor: palette.surface,
            borderColor: palette.border,
            [side === "left" ? "borderRightWidth" : "borderLeftWidth"]: StyleSheet.hairlineWidth,
            transform: [{ translateX }],
          },
          style,
        ]}
      >
        {children}
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0, overflow: "hidden" },
  fill: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
  edge: { position: "absolute", top: 0, bottom: 0, width: EDGE },
  panel: {
    position: "absolute",
    top: 0,
    bottom: 0,
    userSelect: "none",
    boxShadow: "0 0 40px rgba(0, 0, 0, 0.25)",
  },
});
```

---

# Reaction Bar

> A React Native row of emoji reactions whose emoji pops and wobbles when chosen, with counts that roll to their new number.

Install: `npx @modus-ui/cli add reaction-bar`

A row of emoji reactions. Choosing one pops and wobbles its emoji, tints the pill and rolls the count to its new number, and pressing your choice again takes it back. You can hold one reaction at a time. Each pill reads out as "Love, 9, selected" and mirrors its state for screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add reaction-bar
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/reaction-bar.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { ReactionBar } from "@/components/ui/reaction-bar";

const reactions = [
  { id: "like", emoji: "👍", label: "Like" },
  { id: "love", emoji: "❤️", label: "Love" },
];

export default function Example() {
  const [mine, setMine] = useState<string | null>(null);

  return (
    <ReactionBar
      reactions={reactions}
      counts={{ like: 12, love: 4 }}
      value={mine}
      onChange={setMine}
    />
  );
}
```

`counts` holds what everyone else chose. Your own choice is added on top, so the bar always shows the right total.

## Props

| Prop        | Type                             | Default | Description                                                                       |
| :---------- | :------------------------------- | :------ | :-------------------------------------------------------------------------------- |
| `reactions` | `Reaction[]`                     | -       | The reactions, each with an `id`, an `emoji` and a spoken `label`.                |
| `counts`    | `Record<string, number>`         | -       | How many other people chose each reaction, by `id`.                               |
| `value`     | `string \| null`                 | -       | The reaction you chose, or `null`.                                                |
| `onChange`  | `(next: string \| null) => void` | -       | Called with the reaction you chose, or `null` when you take it back.              |
| `hideZero`  | `boolean`                        | `true`  | Hides the count on reactions nobody chose.                                        |
| `colors`    | `Partial<ReactionBarColors>`     | -       | Overrides `pill`, `selectedPill`, `border`, `selectedBorder`, `text` and `count`. |
| `style`     | `StyleProp<ViewStyle>`           | -       | Style for the row.                                                                |

## Source

`components/ui/reaction-bar.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface Reaction {
  id: string;
  emoji: string;
  /** Spoken name, for example "Love". */
  label: string;
}

export interface ReactionBarColors {
  pill: string;
  selectedPill: string;
  border: string;
  selectedBorder: string;
  text: string;
  count: string;
}

const DEFAULT_COLORS: ReactionBarColors = {
  pill: "#f3f4f6",
  selectedPill: "#e0e7ff",
  border: "transparent",
  selectedBorder: "#4f46e5",
  text: "#111827",
  count: "#4b5563",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ReactionBarProps {
  reactions: Reaction[];
  /** How many other people chose each reaction, by id. Your own choice is added on top. */
  counts: Record<string, number>;
  /** The reaction you chose, or null. */
  value: string | null;
  /** Called with the reaction you chose, or null when you take yours back. */
  onChange: (next: string | null) => void;
  /** Hides the count on reactions nobody chose. */
  hideZero?: boolean;
  colors?: Partial<ReactionBarColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A row of emoji reactions. Choosing one pops and wobbles its emoji, tints the pill and rolls the
 * count to its new number; pressing your choice again takes it back. You can hold one reaction at a
 * time. Each pill reads out as "Love, 9, selected" and mirrors its state for screen readers.
 */
export function ReactionBar({
  reactions,
  counts,
  value,
  onChange,
  hideZero = true,
  colors,
  style,
}: ReactionBarProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  return (
    <View accessibilityRole="toolbar" style={[styles.row, style]}>
      {reactions.map((reaction) => {
        const mine = value === reaction.id;
        return (
          <Pill
            key={reaction.id}
            reaction={reaction}
            count={(counts[reaction.id] ?? 0) + (mine ? 1 : 0)}
            selected={mine}
            hideZero={hideZero}
            palette={palette}
            onPress={() => onChange(mine ? null : reaction.id)}
          />
        );
      })}
    </View>
  );
}

interface PillProps {
  reaction: Reaction;
  count: number;
  selected: boolean;
  hideZero: boolean;
  palette: ReactionBarColors;
  onPress: () => void;
}

function Pill({ reaction, count, selected, hideZero, palette, onPress }: PillProps) {
  const reduceMotion = useReduceMotion();
  const tint = useRef(new Animated.Value(selected ? 1 : 0)).current;
  const pop = useRef(new Animated.Value(0)).current;
  const roll = useRef(new Animated.Value(0)).current;
  const press = useRef(new Animated.Value(1)).current;
  const previous = useRef({ count, selected });

  useEffect(() => {
    const was = previous.current;
    previous.current = { count, selected };
    if (reduceMotion) {
      tint.setValue(selected ? 1 : 0);
      return;
    }
    Animated.timing(tint, {
      toValue: selected ? 1 : 0,
      duration: 180,
      useNativeDriver: false,
    }).start();
    if (selected && !was.selected) {
      pop.setValue(0);
      Animated.timing(pop, {
        toValue: 1,
        duration: 480,
        easing: Easing.out(Easing.quad),
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
    if (count !== was.count) {
      // The new number slides in from the direction it moved.
      roll.setValue(count > was.count ? 1 : -1);
      Animated.timing(roll, {
        toValue: 0,
        duration: 220,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
  }, [count, selected, reduceMotion, tint, pop, roll]);

  const dip = (down: boolean) => {
    if (reduceMotion) return;
    Animated.spring(press, {
      toValue: down ? 0.94 : 1,
      stiffness: 500,
      damping: 24,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const showCount = !(hideZero && count === 0);

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={`${reaction.label}, ${count}${selected ? ", selected" : ""}`}
      accessibilityState={{ selected }}
      aria-pressed={selected}
      aria-selected={selected}
      hitSlop={4}
      onPress={onPress}
      onPressIn={() => dip(true)}
      onPressOut={() => dip(false)}
    >
      <Animated.View
        style={[
          styles.pill,
          {
            backgroundColor: tint.interpolate({
              inputRange: [0, 1],
              outputRange: [palette.pill, palette.selectedPill],
            }),
            borderColor: tint.interpolate({
              inputRange: [0, 1],
              outputRange: [palette.border, palette.selectedBorder],
            }),
            transform: [{ scale: press }],
          },
        ]}
      >
        <Animated.Text
          style={[
            styles.emoji,
            {
              transform: [
                { scale: pop.interpolate({ inputRange: [0, 0.4, 1], outputRange: [1, 1.55, 1] }) },
                {
                  rotate: pop.interpolate({
                    inputRange: [0, 0.25, 0.5, 0.75, 1],
                    outputRange: ["0deg", "-16deg", "12deg", "-6deg", "0deg"],
                  }),
                },
              ],
            },
          ]}
        >
          {reaction.emoji}
        </Animated.Text>
        {showCount ? (
          <View style={styles.countClip}>
            <Animated.Text
              style={[
                styles.count,
                {
                  color: selected ? palette.text : palette.count,
                  opacity: roll.interpolate({ inputRange: [-1, 0, 1], outputRange: [0, 1, 0] }),
                  transform: [
                    {
                      translateY: roll.interpolate({ inputRange: [-1, 1], outputRange: [-10, 10] }),
                    },
                  ],
                },
              ]}
            >
              {count}
            </Animated.Text>
          </View>
        ) : null}
      </Animated.View>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", flexWrap: "wrap", gap: 8 },
  pill: {
    minHeight: 40,
    paddingHorizontal: 12,
    borderRadius: 20,
    borderWidth: 1.5,
    flexDirection: "row",
    alignItems: "center",
    gap: 6,
    userSelect: "none",
  },
  emoji: { fontSize: 18 },
  countClip: { overflow: "hidden", minWidth: 10 },
  count: { fontSize: 14, fontWeight: "700", fontVariant: ["tabular-nums"] },
});
```

---

# Suggest Input

> A React Native text field with a suggestion list that narrows as you type, bolds what matched, and works with arrow keys, Enter and Escape on the web.

Install: `npx @modus-ui/cli add suggest-input`

A text field with a list of suggestions that narrows as you type. Suggestions that start with your text come first, and the part that matched is bold. On the web the arrow keys move through the list, Enter chooses and Escape closes it; on a phone you tap a suggestion. It is a combobox to screen readers, with the highlighted option announced as you move. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add suggest-input
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/suggest-input.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { SuggestInput } from "@/components/ui/suggest-input";

const cities = ["Lisbon", "Lima", "Lyon", "Kyoto"];

export default function Example() {
  const [text, setText] = useState("");

  return (
    <SuggestInput
      label="City"
      value={text}
      onChangeText={setText}
      suggestions={cities}
      onSelect={setText}
    />
  );
}
```

The suggestion list opens over whatever sits below the field, so leave room for it.

## Props

| Prop             | Type                           | Default        | Description                                                                                              |
| :--------------- | :----------------------------- | :------------- | :------------------------------------------------------------------------------------------------------- |
| `value`          | `string`                       | -              | The text in the field.                                                                                   |
| `onChangeText`   | `(text: string) => void`       | -              | Called as the text changes.                                                                              |
| `suggestions`    | `string[]`                     | -              | Everything that can be suggested, narrowed by what is typed.                                             |
| `onSelect`       | `(suggestion: string) => void` | -              | Called with the suggestion that was chosen.                                                              |
| `placeholder`    | `string`                       | `"Search"`     | Text shown while the field is empty.                                                                     |
| `minChars`       | `number`                       | `1`            | How many characters must be typed before suggestions show.                                               |
| `maxSuggestions` | `number`                       | `5`            | The most suggestions shown at once.                                                                      |
| `emptyText`      | `string`                       | `"No matches"` | Shown when nothing matches.                                                                              |
| `label`          | `string`                       | `"Search"`     | Spoken name of the field.                                                                                |
| `colors`         | `Partial<SuggestInputColors>`  | -              | Overrides `field`, `border`, `focusBorder`, `text`, `placeholder`, `panel`, `highlight` and `activeRow`. |
| `style`          | `StyleProp<ViewStyle>`         | -              | Style for the field's container.                                                                         |

## Source

`components/ui/suggest-input.tsx`

```tsx
import { useEffect, useId, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type TextInputKeyPressEvent,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const FIELD_HEIGHT = 48;
const ROW_HEIGHT = 44;
// On the web the field loses focus before a tap on a suggestion lands, so closing waits a moment.
const BLUR_DELAY = 160;

export interface SuggestInputColors {
  field: string;
  border: string;
  focusBorder: string;
  text: string;
  placeholder: string;
  panel: string;
  highlight: string;
  activeRow: string;
}

const DEFAULT_COLORS: SuggestInputColors = {
  field: "#ffffff",
  border: "#d1d5db",
  focusBorder: "#4f46e5",
  text: "#111827",
  placeholder: "#9ca3af",
  panel: "#ffffff",
  highlight: "#4f46e5",
  activeRow: "#eef2ff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SuggestInputProps {
  value: string;
  onChangeText: (text: string) => void;
  /** Everything that can be suggested. The list under the field is these, narrowed by what is typed. */
  suggestions: string[];
  /** Called with the suggestion that was chosen. */
  onSelect: (suggestion: string) => void;
  placeholder?: string;
  /** How many characters must be typed before suggestions show. */
  minChars?: number;
  /** The most suggestions shown at once. */
  maxSuggestions?: number;
  /** Shown when nothing matches. */
  emptyText?: string;
  /** Spoken name of the field. */
  label?: string;
  colors?: Partial<SuggestInputColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A text field with a list of suggestions that narrows as you type. Matches that start with the text
 * come first and the part that matched is bold. On the web the arrow keys move through the list, Enter
 * chooses and Escape closes it; on a phone you tap. It is a combobox to screen readers.
 */
export function SuggestInput({
  value,
  onChangeText,
  suggestions,
  onSelect,
  placeholder = "Search",
  minChars = 1,
  maxSuggestions = 5,
  emptyText = "No matches",
  label = "Search",
  colors,
  style,
}: SuggestInputProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const id = useId();
  const [focused, setFocused] = useState(false);
  const [dismissed, setDismissed] = useState(false);
  const [active, setActive] = useState(-1);
  const t = useRef(new Animated.Value(0)).current;
  const blurTimer = useRef<ReturnType<typeof setTimeout> | null>(null);

  const query = value.trim().toLowerCase();
  const matches = useMemo(() => {
    if (query.length < minChars) return [];
    const found = suggestions.filter((item) => item.toLowerCase().includes(query));
    // Suggestions that start with the text come before those that only contain it.
    found.sort(
      (a, b) =>
        Number(b.toLowerCase().startsWith(query)) - Number(a.toLowerCase().startsWith(query)),
    );
    return found.slice(0, maxSuggestions);
  }, [suggestions, query, minChars, maxSuggestions]);

  const open = focused && !dismissed && query.length >= minChars;
  const rows = matches.length > 0 ? matches.length : 1;

  useEffect(() => {
    if (reduceMotion) {
      t.setValue(open ? 1 : 0);
      return;
    }
    Animated.timing(t, {
      toValue: open ? 1 : 0,
      duration: 140,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [open, reduceMotion, t]);

  useEffect(
    () => () => {
      if (blurTimer.current) clearTimeout(blurTimer.current);
    },
    [],
  );

  const choose = (item: string) => {
    onSelect(item);
    setDismissed(true);
    setActive(-1);
  };

  const onKeyPress = (event: TextInputKeyPressEvent) => {
    const key = event.nativeEvent.key;
    if (key === "ArrowDown" || key === "ArrowUp") {
      if (!open && matches.length > 0) setDismissed(false);
      if (matches.length === 0) return;
      const step = key === "ArrowDown" ? 1 : -1;
      setActive((current) => (current + step + matches.length) % matches.length);
    } else if (key === "Enter" && open && active >= 0 && matches[active]) {
      choose(matches[active]);
    } else if (key === "Escape") {
      setDismissed(true);
      setActive(-1);
    }
  };

  const optionId = (i: number) => `${id}-option-${i}`;

  return (
    <View style={[styles.root, style]}>
      <TextInput
        value={value}
        onChangeText={(text) => {
          onChangeText(text);
          setDismissed(false);
          setActive(-1);
        }}
        onKeyPress={onKeyPress}
        onFocus={() => {
          if (blurTimer.current) clearTimeout(blurTimer.current);
          setFocused(true);
        }}
        onBlur={() => {
          blurTimer.current = setTimeout(() => setFocused(false), BLUR_DELAY);
        }}
        // react-native-web only reads blurOnSubmit; without it a single-line field blurs on Enter.
        blurOnSubmit={false}
        placeholder={placeholder}
        placeholderTextColor={palette.placeholder}
        autoCapitalize="none"
        autoCorrect={false}
        returnKeyType="search"
        accessibilityLabel={label}
        aria-label={label}
        role="combobox"
        aria-expanded={open}
        aria-autocomplete="list"
        aria-controls={`${id}-list`}
        aria-activedescendant={open && active >= 0 ? optionId(active) : undefined}
        selectionColor={palette.focusBorder}
        style={[
          styles.input,
          {
            backgroundColor: palette.field,
            color: palette.text,
            borderColor: focused ? palette.focusBorder : palette.border,
          },
        ]}
      />
      <Animated.View
        nativeID={`${id}-list`}
        // React Native's role type has no "listbox", but the web build passes it through, and the options need it.
        {...({ role: "listbox" } as object)}
        aria-label={`${label} suggestions`}
        pointerEvents={open ? "auto" : "none"}
        style={[
          styles.panel,
          {
            backgroundColor: palette.panel,
            borderColor: palette.border,
            opacity: t,
            transform: [
              { translateY: t.interpolate({ inputRange: [0, 1], outputRange: [-6, 0] }) },
            ],
            height: rows * ROW_HEIGHT,
          },
        ]}
      >
        {matches.length === 0 ? (
          <View style={styles.row}>
            <Text style={[styles.empty, { color: palette.placeholder }]}>{emptyText}</Text>
          </View>
        ) : (
          matches.map((item, i) => {
            const at = item.toLowerCase().indexOf(query);
            return (
              <Pressable
                key={item}
                nativeID={optionId(i)}
                role="option"
                aria-selected={i === active}
                accessibilityState={{ selected: i === active }}
                accessibilityLabel={item}
                onPress={() => choose(item)}
                style={[styles.row, i === active && { backgroundColor: palette.activeRow }]}
              >
                <Text style={[styles.text, { color: palette.text }]} numberOfLines={1}>
                  {item.slice(0, at)}
                  <Text style={[styles.match, { color: palette.highlight }]}>
                    {item.slice(at, at + query.length)}
                  </Text>
                  {item.slice(at + query.length)}
                </Text>
              </Pressable>
            );
          })
        )}
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { height: FIELD_HEIGHT, zIndex: 10 },
  input: {
    height: FIELD_HEIGHT,
    borderRadius: 14,
    borderWidth: 1.5,
    paddingHorizontal: 16,
    fontSize: 16,
  },
  panel: {
    position: "absolute",
    top: FIELD_HEIGHT + 6,
    left: 0,
    right: 0,
    borderRadius: 14,
    borderWidth: 1,
    overflow: "hidden",
    boxShadow: "0 12px 30px rgba(0, 0, 0, 0.18)",
  },
  row: { height: ROW_HEIGHT, justifyContent: "center", paddingHorizontal: 16 },
  text: { fontSize: 16 },
  match: { fontWeight: "800" },
  empty: { fontSize: 15 },
});
```

---

# Expand Card

> A React Native card that grows from a compact row into a full detail view, with its picture swelling from a thumbnail to a banner and its details fading in.

Install: `npx @modus-ui/cli add expand-card`

A card that grows from a compact row into a full detail view. The picture swells from a thumbnail to a banner, the title slides down beneath it, the details fade in, and the chevron turns over, all driven by one value so the parts stay in step. Pressing the header toggles it, and the details stay interactive when open. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add expand-card
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/expand-card.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Text, View } from "react-native";
import { ExpandCard } from "@/components/ui/expand-card";

export default function Example() {
  const [open, setOpen] = useState(false);

  return (
    <ExpandCard
      title="Harbor Loft"
      subtitle="Halifax, Nova Scotia"
      expanded={open}
      onExpandedChange={setOpen}
      hero={<View style={{ flex: 1, alignSelf: "stretch", backgroundColor: "#4f9bd9" }} />}
    >
      <Text>Top floor, harbour view.</Text>
    </ExpandCard>
  );
}
```

## Props

| Prop               | Type                          | Default | Description                                                             |
| :----------------- | :---------------------------- | :------ | :---------------------------------------------------------------------- |
| `expanded`         | `boolean`                     | -       | Whether the card is open.                                               |
| `onExpandedChange` | `(expanded: boolean) => void` | -       | Called when the header is pressed.                                      |
| `title`            | `string`                      | -       | The card's heading.                                                     |
| `subtitle`         | `string`                      | -       | A smaller line under the heading.                                       |
| `hero`             | `ReactNode`                   | -       | Drawn inside the picture box, which grows from a thumbnail to a banner. |
| `collapsedHeight`  | `number`                      | `88`    | Height of the closed card.                                              |
| `expandedHeight`   | `number`                      | `340`   | Height of the open card.                                                |
| `heroHeight`       | `number`                      | `160`   | Height of the picture when the card is open.                            |
| `colors`           | `Partial<ExpandCardColors>`   | -       | Overrides `surface`, `border`, `hero`, `title` and `subtitle`.          |
| `style`            | `StyleProp<ViewStyle>`        | -       | Style for the card.                                                     |

## Source

`components/ui/expand-card.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const PAD = 12;

export interface ExpandCardColors {
  surface: string;
  border: string;
  hero: string;
  title: string;
  subtitle: string;
}

const DEFAULT_COLORS: ExpandCardColors = {
  surface: "#ffffff",
  border: "#e5e7eb",
  hero: "#c7d2fe",
  title: "#111827",
  subtitle: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ExpandCardProps {
  expanded: boolean;
  onExpandedChange: (expanded: boolean) => void;
  title: string;
  subtitle?: string;
  /** Drawn inside the picture box, which grows from a thumbnail to a banner. */
  hero?: ReactNode;
  /** The details revealed when the card is open. */
  children?: ReactNode;
  /** Height of the closed card. */
  collapsedHeight?: number;
  /** Height of the open card. */
  expandedHeight?: number;
  /** Height of the picture when the card is open. */
  heroHeight?: number;
  colors?: Partial<ExpandCardColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A card that grows from a compact row into a full detail view. The picture swells from a thumbnail
 * to a banner, the title slides under it, the details fade in, and the chevron turns over, all from
 * one value so the parts stay in step. Pressing the header toggles it; the details stay interactive.
 */
export function ExpandCard({
  expanded,
  onExpandedChange,
  title,
  subtitle,
  hero,
  children,
  collapsedHeight = 88,
  expandedHeight = 340,
  heroHeight = 160,
  colors,
  style,
}: ExpandCardProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const t = useRef(new Animated.Value(expanded ? 1 : 0)).current;
  const [width, setWidth] = useState(0);

  useEffect(() => {
    if (reduceMotion) {
      t.setValue(expanded ? 1 : 0);
      return;
    }
    Animated.timing(t, {
      toValue: expanded ? 1 : 0,
      duration: 380,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: false,
    }).start();
  }, [expanded, reduceMotion, t]);

  const thumb = collapsedHeight - PAD * 2;
  const mix = (from: number, to: number) =>
    t.interpolate({ inputRange: [0, 1], outputRange: [from, to] });
  const headerHeight = heroHeight + 70;
  const detailsTop = headerHeight + 4;

  return (
    <Animated.View
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      style={[
        styles.card,
        {
          height: mix(collapsedHeight, expandedHeight),
          backgroundColor: palette.surface,
          borderColor: palette.border,
        },
        style,
      ]}
    >
      <Animated.View
        style={[
          styles.hero,
          {
            backgroundColor: palette.hero,
            left: mix(PAD, 0),
            top: mix(PAD, 0),
            width: width > 0 ? mix(thumb, width) : thumb,
            height: mix(thumb, heroHeight),
            borderRadius: mix(12, 0),
          },
        ]}
      >
        {hero}
      </Animated.View>
      <Animated.View
        style={[
          styles.titles,
          { left: mix(thumb + PAD * 2, 20), top: mix(PAD + (thumb - 44) / 2, heroHeight + 14) },
        ]}
        pointerEvents="none"
      >
        <Text numberOfLines={1} style={[styles.title, { color: palette.title }]}>
          {title}
        </Text>
        {subtitle ? (
          <Text numberOfLines={1} style={[styles.subtitle, { color: palette.subtitle }]}>
            {subtitle}
          </Text>
        ) : null}
      </Animated.View>
      <Animated.View
        pointerEvents="none"
        style={[
          styles.chevron,
          {
            top: mix(collapsedHeight / 2 - 10, heroHeight + 18),
            transform: [
              {
                rotate: mix(0, 180).interpolate({
                  inputRange: [0, 180],
                  outputRange: ["0deg", "180deg"],
                }),
              },
            ],
          },
        ]}
      >
        <Text style={{ fontSize: 18, color: palette.subtitle }}>⌄</Text>
      </Animated.View>
      <Animated.View
        aria-hidden={!expanded}
        pointerEvents={expanded ? "auto" : "none"}
        style={[
          styles.details,
          { top: detailsTop, opacity: t, transform: [{ translateY: mix(14, 0) }] },
        ]}
      >
        {children}
      </Animated.View>
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={`${title}, ${expanded ? "collapse" : "expand"}`}
        accessibilityState={{ expanded }}
        aria-expanded={expanded}
        onPress={() => onExpandedChange(!expanded)}
        style={[styles.header, { height: expanded ? headerHeight : collapsedHeight }]}
      />
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  card: { overflow: "hidden", borderRadius: 20, borderWidth: 1, userSelect: "none" },
  hero: {
    position: "absolute",
    overflow: "hidden",
    alignItems: "center",
    justifyContent: "center",
  },
  titles: { position: "absolute", right: 44 },
  title: { fontSize: 17, fontWeight: "700" },
  subtitle: { fontSize: 13, marginTop: 2 },
  chevron: { position: "absolute", right: 16 },
  details: { position: "absolute", left: 20, right: 20, bottom: 0 },
  header: { position: "absolute", top: 0, left: 0, right: 0 },
});
```

---

# Ring Meter

> A React Native circular progress ring drawn with plain views and no SVG package, that sweeps smoothly all the way round and holds any content in its middle.

Install: `npx @modus-ui/cli add ring-meter`

A circular progress ring built from plain views, with no SVG or gradient package. Two half rings, each a bordered circle clipped to one side, are turned by the same value: the right half sweeps first, then the left takes over, so the arc grows smoothly all the way round. The middle shows the percentage, or any content you put inside it. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add ring-meter
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/ring-meter.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text } from "react-native";
import { RingMeter } from "@/components/ui/ring-meter";

export default function Example() {
  return (
    <RingMeter value={0.74} size={160} thickness={14} label="Daily steps">
      <Text style={{ fontSize: 28, fontWeight: "800" }}>7,420</Text>
    </RingMeter>
  );
}
```

## Props

| Prop        | Type                       | Default      | Description                                                    |
| :---------- | :------------------------- | :----------- | :------------------------------------------------------------- |
| `value`     | `number`                   | -            | Progress from 0 to 1.                                          |
| `size`      | `number`                   | `120`        | Diameter of the ring.                                          |
| `thickness` | `number`                   | `10`         | Width of the ring's stroke.                                    |
| `showValue` | `boolean`                  | `true`       | Shows the percentage in the middle when there are no children. |
| `animated`  | `boolean`                  | `true`       | Animates the ring to each new value.                           |
| `label`     | `string`                   | `"Progress"` | Spoken name of the meter.                                      |
| `colors`    | `Partial<RingMeterColors>` | -            | Overrides `track`, `fill` and `text`.                          |
| `style`     | `StyleProp<ViewStyle>`     | -            | Style for the ring.                                            |

## Source

`components/ui/ring-meter.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface RingMeterColors {
  track: string;
  fill: string;
  text: string;
}

const DEFAULT_COLORS: RingMeterColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  text: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface RingMeterProps {
  /** Progress from 0 to 1. */
  value: number;
  /** Diameter of the ring. */
  size?: number;
  /** Width of the ring's stroke. */
  thickness?: number;
  /** Shows the percentage in the middle when there are no children. */
  showValue?: boolean;
  /** Animates the ring to each new value. */
  animated?: boolean;
  /** Spoken name of the meter. */
  label?: string;
  /** Replaces the percentage in the middle. */
  children?: ReactNode;
  colors?: Partial<RingMeterColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A circular progress ring built from plain views, with no SVG package. Two half rings, each a
 * bordered circle clipped to one side, are turned by the same value: the right half sweeps first,
 * then the left takes over, so the arc grows smoothly all the way round.
 */
export function RingMeter({
  value,
  size = 120,
  thickness = 10,
  showValue = true,
  animated = true,
  label = "Progress",
  children,
  colors,
  style,
}: RingMeterProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const clamped = Math.max(0, Math.min(1, value));
  const percent = Math.round(clamped * 100);
  const p = useRef(new Animated.Value(clamped)).current;

  useEffect(() => {
    if (!animated || reduceMotion) {
      p.setValue(clamped);
      return;
    }
    Animated.timing(p, {
      toValue: clamped,
      duration: 700,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [clamped, animated, reduceMotion, p]);

  // A circle whose top and right borders are coloured shows a half ring. Turned by -135 degrees it
  // lies in the left half and is clipped away; turned by +45 it fills the right half exactly.
  const right = p.interpolate({
    inputRange: [0, 0.5, 1],
    outputRange: ["-135deg", "45deg", "45deg"],
  });
  const left = p.interpolate({
    inputRange: [0, 0.5, 1],
    outputRange: ["45deg", "45deg", "225deg"],
  });

  const half = size / 2;
  const arc = {
    position: "absolute" as const,
    top: 0,
    width: size,
    height: size,
    borderRadius: half,
    borderWidth: thickness,
    borderColor: "transparent",
    borderTopColor: palette.fill,
    borderRightColor: palette.fill,
  };

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel={label}
      aria-label={label}
      accessibilityValue={{ min: 0, max: 100, now: percent }}
      aria-valuemin={0}
      aria-valuemax={100}
      aria-valuenow={percent}
      aria-valuetext={`${percent} percent`}
      style={[{ width: size, height: size }, style]}
    >
      <View
        style={{
          width: size,
          height: size,
          borderRadius: half,
          borderWidth: thickness,
          borderColor: palette.track,
        }}
      />
      <View style={[styles.clip, { left: half, width: half, height: size }]}>
        <Animated.View style={[arc, { left: -half, transform: [{ rotate: right }] }]} />
      </View>
      <View style={[styles.clip, { left: 0, width: half, height: size }]}>
        <Animated.View style={[arc, { left: 0, transform: [{ rotate: left }] }]} />
      </View>
      <View pointerEvents="none" style={styles.center}>
        {children ??
          (showValue ? (
            <Text style={[styles.value, { color: palette.text, fontSize: size * 0.24 }]}>
              {percent}%
            </Text>
          ) : null)}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  clip: { position: "absolute", top: 0, overflow: "hidden" },
  center: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
  },
  value: { fontWeight: "800" },
});
```

---

# Count Badge

> A React Native notification count that sits on an icon's corner, pops in when it appears, pulses as the number changes, and reads out with its label.

Install: `npx @modus-ui/cli add count-badge`

A count bubble that sits on the corner of an icon or avatar. It pops in when the count first appears, pulses each time the number changes, and shrinks away when it returns to zero. Large counts read "99+", it can be a plain dot instead, and the label and number are read out together. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add count-badge
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/count-badge.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Text } from "react-native";
import { CountBadge } from "@/components/ui/count-badge";

export default function Example() {
  return (
    <CountBadge count={7} label="Messages">
      <Text style={{ fontSize: 24 }}>✉</Text>
    </CountBadge>
  );
}
```

## Props

| Prop       | Type                        | Default           | Description                                          |
| :--------- | :-------------------------- | :---------------- | :--------------------------------------------------- |
| `count`    | `number`                    | -                 | The number to show.                                  |
| `max`      | `number`                    | `99`              | Counts above this show as "max+", for example "99+". |
| `dot`      | `boolean`                   | `false`           | Shows a small dot instead of the number.             |
| `hideZero` | `boolean`                   | `true`            | Hides the badge when the count is zero.              |
| `label`    | `string`                    | `"Notifications"` | What is being counted. Read out with the number.     |
| `colors`   | `Partial<CountBadgeColors>` | -                 | Overrides `badge`, `text` and `ring`.                |
| `style`    | `StyleProp<ViewStyle>`      | -                 | Style for the wrapper around the icon.               |

## Source

`components/ui/count-badge.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface CountBadgeColors {
  badge: string;
  text: string;
  ring: string;
}

const DEFAULT_COLORS: CountBadgeColors = {
  badge: "#dc2626",
  text: "#ffffff",
  ring: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface CountBadgeProps {
  /** The number to show. */
  count: number;
  /** Counts above this show as "max+", for example "99+". */
  max?: number;
  /** Shows a small dot instead of the number. */
  dot?: boolean;
  /** Hides the badge when the count is zero. */
  hideZero?: boolean;
  /** What is being counted, for example "Notifications". Read out with the number. */
  label?: string;
  /** The icon or avatar the badge sits on the corner of. */
  children?: ReactNode;
  colors?: Partial<CountBadgeColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A count bubble that sits on the corner of an icon. It pops in when the count first appears, pulses
 * each time the number changes, and shrinks away when it returns to zero. Large counts read "99+",
 * and the label and number are read out together.
 */
export function CountBadge({
  count,
  max = 99,
  dot = false,
  hideZero = true,
  label = "Notifications",
  children,
  colors,
  style,
}: CountBadgeProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const visible = !(hideZero && count <= 0);
  const show = useRef(new Animated.Value(visible ? 1 : 0)).current;
  const pulse = useRef(new Animated.Value(1)).current;
  const previous = useRef(count);

  useEffect(() => {
    if (reduceMotion) {
      show.setValue(visible ? 1 : 0);
      return;
    }
    Animated.spring(show, {
      toValue: visible ? 1 : 0,
      stiffness: 420,
      damping: 18,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [visible, reduceMotion, show]);

  // Each change in the number gives the badge a small bump.
  useEffect(() => {
    if (previous.current === count) return;
    previous.current = count;
    if (reduceMotion || !visible) return;
    pulse.setValue(1.35);
    Animated.spring(pulse, {
      toValue: 1,
      stiffness: 380,
      damping: 12,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [count, visible, reduceMotion, pulse]);

  const text = count > max ? `${max}+` : String(count);
  const spoken = `${label}, ${visible ? (count > max ? `more than ${max}` : count) : "none"}`;

  return (
    <View
      accessible
      accessibilityLabel={spoken}
      aria-label={spoken}
      accessibilityLiveRegion="polite"
      style={[styles.anchor, style]}
    >
      {children}
      <Animated.View
        pointerEvents="none"
        style={[
          dot ? styles.dot : styles.badge,
          {
            backgroundColor: palette.badge,
            borderColor: palette.ring,
            opacity: show,
            transform: [{ scale: Animated.multiply(show, pulse) }],
          },
        ]}
      >
        {dot ? null : <Text style={[styles.text, { color: palette.text }]}>{text}</Text>}
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  anchor: { alignSelf: "flex-start" },
  badge: {
    position: "absolute",
    top: -6,
    right: -8,
    minWidth: 20,
    height: 20,
    paddingHorizontal: 5,
    borderRadius: 10,
    borderWidth: 2,
    alignItems: "center",
    justifyContent: "center",
  },
  dot: {
    position: "absolute",
    top: -2,
    right: -2,
    width: 12,
    height: 12,
    borderRadius: 6,
    borderWidth: 2,
  },
  text: { fontSize: 11, fontWeight: "800", lineHeight: 14 },
});
```

---

# Float Field

> A React Native text field whose label floats up from inside the box, with an animated focus border, an error shake, a clear button and a Show toggle for passwords.

Install: `npx @modus-ui/cli add float-field`

A text field whose label starts inside the box and floats up to the top as you focus or type. The border blends to the focus colour, a new error shakes the field and turns it red, and the message is announced to screen readers. It clears with one tap and can hide its text behind a Show button for passwords. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add float-field
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/float-field.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { FloatField } from "@/components/ui/float-field";

export default function Example() {
  const [email, setEmail] = useState("");

  return (
    <FloatField
      label="Email"
      value={email}
      onChangeText={setEmail}
      keyboardType="email-address"
      helper="We only use it to sign you in"
    />
  );
}
```

## Props

| Prop              | Type                                                                | Default     | Description                                                                             |
| :---------------- | :------------------------------------------------------------------ | :---------- | :-------------------------------------------------------------------------------------- |
| `value`           | `string`                                                            | -           | The text in the field.                                                                  |
| `onChangeText`    | `(text: string) => void`                                            | -           | Called as the text changes.                                                             |
| `label`           | `string`                                                            | -           | The field's name. It floats up when there is text or focus.                             |
| `helper`          | `string`                                                            | -           | A hint under the field.                                                                 |
| `error`           | `string`                                                            | -           | Replaces the hint, turns the border red and shakes the field when it first appears.     |
| `secureTextEntry` | `boolean`                                                           | `false`     | Hides the text, with a Show and Hide button.                                            |
| `clearable`       | `boolean`                                                           | `true`      | Shows a clear button while the field has text.                                          |
| `disabled`        | `boolean`                                                           | `false`     | Dims the field and stops editing.                                                       |
| `keyboardType`    | `"default" \| "email-address" \| "numeric" \| "phone-pad" \| "url"` | `"default"` | Which keyboard to show.                                                                 |
| `colors`          | `Partial<FloatFieldColors>`                                         | -           | Overrides `background`, `border`, `focusBorder`, `label`, `text`, `error` and `helper`. |
| `style`           | `StyleProp<ViewStyle>`                                              | -           | Style for the field and its message.                                                    |

## Source

`components/ui/float-field.tsx`

```tsx
import { useEffect, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const HEIGHT = 60;

export interface FloatFieldColors {
  background: string;
  border: string;
  focusBorder: string;
  label: string;
  text: string;
  error: string;
  helper: string;
}

const DEFAULT_COLORS: FloatFieldColors = {
  background: "#ffffff",
  border: "#d1d5db",
  focusBorder: "#4f46e5",
  label: "#6b7280",
  text: "#111827",
  error: "#dc2626",
  helper: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface FloatFieldProps {
  value: string;
  onChangeText: (text: string) => void;
  /** The field's name. It sits inside the field, then floats up when there is text or focus. */
  label: string;
  /** A hint under the field. */
  helper?: string;
  /** Replaces the hint, turns the border red and shakes the field when it first appears. */
  error?: string;
  /** Hides the text, with a Show and Hide button. */
  secureTextEntry?: boolean;
  /** Shows a clear button while the field has text. */
  clearable?: boolean;
  disabled?: boolean;
  keyboardType?: "default" | "email-address" | "numeric" | "phone-pad" | "url";
  colors?: Partial<FloatFieldColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A text field whose label starts inside the box and floats up to the top as you focus or type. The
 * border blends to the focus colour, a new error shakes the field and turns it red, and the message
 * is announced. It can hide its text with a Show button, and clears with one tap.
 */
export function FloatField({
  value,
  onChangeText,
  label,
  helper,
  error,
  secureTextEntry = false,
  clearable = true,
  disabled = false,
  keyboardType = "default",
  colors,
  style,
}: FloatFieldProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const input = useRef<ElementRef<typeof TextInput>>(null);
  const [focused, setFocused] = useState(false);
  const [revealed, setRevealed] = useState(false);
  const floated = focused || value.length > 0;
  const float = useRef(new Animated.Value(floated ? 1 : 0)).current;
  const glow = useRef(new Animated.Value(focused ? 1 : 0)).current;
  const shake = useRef(new Animated.Value(0)).current;
  const hadError = useRef(false);

  useEffect(() => {
    if (reduceMotion) {
      float.setValue(floated ? 1 : 0);
      return;
    }
    Animated.timing(float, {
      toValue: floated ? 1 : 0,
      duration: 160,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [floated, reduceMotion, float]);

  useEffect(() => {
    if (reduceMotion) {
      glow.setValue(focused ? 1 : 0);
      return;
    }
    Animated.timing(glow, {
      toValue: focused ? 1 : 0,
      duration: 160,
      useNativeDriver: false,
    }).start();
  }, [focused, reduceMotion, glow]);

  // A shake when an error first appears, not every time it is re-rendered.
  useEffect(() => {
    const has = !!error;
    if (has && !hadError.current && !reduceMotion) {
      Animated.sequence(
        [-8, 8, -6, 6, -3, 0].map((toValue) =>
          Animated.timing(shake, { toValue, duration: 50, useNativeDriver: NATIVE_DRIVER }),
        ),
      ).start();
    }
    hadError.current = has;
  }, [error, reduceMotion, shake]);

  const borderColor = error
    ? palette.error
    : glow.interpolate({ inputRange: [0, 1], outputRange: [palette.border, palette.focusBorder] });
  const labelColor = error ? palette.error : focused ? palette.focusBorder : palette.label;
  const message = error ?? helper;
  const clear = () => {
    onChangeText("");
    input.current?.focus();
  };

  return (
    <View style={style}>
      <Animated.View
        style={[
          styles.box,
          {
            backgroundColor: palette.background,
            borderColor,
            borderWidth: focused || error ? 2 : 1.5,
            transform: [{ translateX: shake }],
            opacity: disabled ? 0.5 : 1,
          },
        ]}
      >
        <Animated.Text
          pointerEvents="none"
          numberOfLines={1}
          style={[
            styles.label,
            {
              color: labelColor,
              transform: [
                { translateY: float.interpolate({ inputRange: [0, 1], outputRange: [0, -12] }) },
                { scale: float.interpolate({ inputRange: [0, 1], outputRange: [1, 0.76] }) },
              ],
            },
          ]}
        >
          {label}
        </Animated.Text>
        <TextInput
          ref={input}
          value={value}
          onChangeText={onChangeText}
          onFocus={() => setFocused(true)}
          onBlur={() => setFocused(false)}
          editable={!disabled}
          secureTextEntry={secureTextEntry && !revealed}
          keyboardType={keyboardType}
          autoCapitalize="none"
          autoCorrect={false}
          accessibilityLabel={label}
          aria-label={label}
          aria-invalid={!!error}
          aria-disabled={disabled}
          accessibilityHint={message}
          selectionColor={palette.focusBorder}
          style={[styles.input, { color: palette.text }]}
        />
        {clearable && value.length > 0 && !secureTextEntry ? (
          <Pressable
            accessibilityRole="button"
            accessibilityLabel={`Clear ${label}`}
            hitSlop={10}
            // It stays mounted whenever there is text: on the web, pressing a button blurs the field
            // first, and a button that only showed while focused would vanish before the click landed.
            onPress={clear}
            style={styles.action}
          >
            <Text style={[styles.clear, { color: palette.label }]}>×</Text>
          </Pressable>
        ) : null}
        {secureTextEntry && value.length > 0 ? (
          <Pressable
            accessibilityRole="button"
            accessibilityLabel={revealed ? `Hide ${label}` : `Show ${label}`}
            hitSlop={10}
            onPress={() => setRevealed((shown) => !shown)}
            style={styles.action}
          >
            <Text style={[styles.toggle, { color: palette.focusBorder }]}>
              {revealed ? "Hide" : "Show"}
            </Text>
          </Pressable>
        ) : null}
      </Animated.View>
      {message ? (
        <Text
          accessibilityLiveRegion="polite"
          style={[styles.message, { color: error ? palette.error : palette.helper }]}
        >
          {message}
        </Text>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  box: { height: HEIGHT, borderRadius: 12, justifyContent: "center", paddingHorizontal: 14 },
  label: {
    position: "absolute",
    left: 14,
    top: 18,
    fontSize: 16,
    transformOrigin: "left center",
  },
  input: {
    fontSize: 16,
    paddingTop: 20,
    paddingBottom: 4,
    paddingRight: 44,
    height: HEIGHT - 4,
    outlineStyle: "none",
  } as object,
  action: {
    position: "absolute",
    right: 12,
    top: 0,
    bottom: 0,
    minWidth: 32,
    alignItems: "center",
    justifyContent: "center",
  },
  clear: { fontSize: 24, lineHeight: 26 },
  toggle: { fontSize: 13, fontWeight: "700" },
  message: { marginTop: 6, marginHorizontal: 4, fontSize: 13, lineHeight: 18 },
});
```

---

# Month Grid

> A React Native month calendar with a pill that glides to the selected day, swipe to change month, event dots, and local dates that never shift across time zones.

Install: `npx @modus-ui/cli add month-grid`

A month calendar. A pill glides to the selected day, the grid slides in from the side when the month changes, and a horizontal swipe changes the month too. Days outside the month are faded but still selectable, and days with events show a dot and say so to screen readers. Dates are local `YYYY-MM-DD` strings, so nothing shifts a day near midnight or across time zones. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add month-grid
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/month-grid.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { MonthGrid } from "@/components/ui/month-grid";

export default function Example() {
  const [month, setMonth] = useState("2026-11");
  const [day, setDay] = useState<string | null>("2026-11-04");

  return (
    <MonthGrid
      month={month}
      onMonthChange={setMonth}
      selected={day}
      onSelect={setDay}
      marked={["2026-11-09", "2026-11-16"]}
    />
  );
}
```

## Props

| Prop            | Type                       | Default | Description                                                              |
| :-------------- | :------------------------- | :------ | :----------------------------------------------------------------------- |
| `month`         | `string`                   | -       | The month shown, as `YYYY-MM`.                                           |
| `onMonthChange` | `(month: string) => void`  | -       | Called with the new month from the arrows, a swipe, or a faded day.      |
| `selected`      | `string \| null`           | -       | The selected day as `YYYY-MM-DD`, or `null` for none.                    |
| `onSelect`      | `(date: string) => void`   | -       | Called with the tapped day as `YYYY-MM-DD`.                              |
| `marked`        | `string[]`                 | -       | Days (`YYYY-MM-DD`) that show a small dot, for example days with events. |
| `weekStart`     | `0 \| 1`                   | `1`     | The first column: 1 for Monday, 0 for Sunday.                            |
| `colors`        | `Partial<MonthGridColors>` | -       | Overrides `text`, `mutedText`, `pill`, `pillText`, `today` and `dot`.    |
| `style`         | `StyleProp<ViewStyle>`     | -       | Style for the calendar.                                                  |

## Source

`components/ui/month-grid.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const ROW = 44;
const ROWS = 6;

export interface MonthGridColors {
  text: string;
  mutedText: string;
  pill: string;
  pillText: string;
  today: string;
  dot: string;
}

const DEFAULT_COLORS: MonthGridColors = {
  text: "#111827",
  mutedText: "#9ca3af",
  pill: "#4f46e5",
  pillText: "#ffffff",
  today: "#4f46e5",
  dot: "#f59e0b",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

const pad = (n: number) => String(n).padStart(2, "0");
/** YYYY-MM-DD for a local date. Dates here are local, never UTC, so a day cannot shift. */
const toISO = (date: Date) =>
  `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
const toMonth = (date: Date) => `${date.getFullYear()}-${pad(date.getMonth() + 1)}`;
/** The first day of a YYYY-MM month, as a local date. */
const firstOf = (month: string) => {
  const [year, m] = month.split("-").map(Number);
  return new Date(year, m - 1, 1);
};
const addMonths = (month: string, delta: number) => {
  const first = firstOf(month);
  return toMonth(new Date(first.getFullYear(), first.getMonth() + delta, 1));
};

export interface MonthGridProps {
  /** The month shown, as YYYY-MM. */
  month: string;
  onMonthChange: (month: string) => void;
  /** The selected day, as YYYY-MM-DD, or null for none. */
  selected: string | null;
  onSelect: (date: string) => void;
  /** Days (YYYY-MM-DD) that show a small dot, for example days with events. */
  marked?: string[];
  /** The first column: 1 for Monday, 0 for Sunday. */
  weekStart?: 0 | 1;
  colors?: Partial<MonthGridColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A month calendar. A pill glides to the selected day, the grid slides in from the side when the
 * month changes, and a horizontal swipe changes the month too. Days outside the month are faded but
 * still selectable. Dates are local YYYY-MM-DD strings, so nothing shifts a day across time zones.
 */
export function MonthGrid({
  month,
  onMonthChange,
  selected,
  onSelect,
  marked,
  weekStart = 1,
  colors,
  style,
}: MonthGridProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const pill = useRef(new Animated.ValueXY()).current;
  const pillOn = useRef(new Animated.Value(0)).current;
  const slide = useRef(new Animated.Value(0)).current;
  const fade = useRef(new Animated.Value(1)).current;
  const previousMonth = useRef(month);
  const placed = useRef(false);
  // True during a swipe and for a moment after it: the click that follows a mouse drag is not a tap.
  const dragging = useRef(false);

  const live = useRef({ month, onMonthChange });
  live.current = { month, onMonthChange };

  const todayISO = useMemo(() => toISO(new Date()), []);
  const markedSet = useMemo(() => new Set(marked), [marked]);
  const title = useMemo(
    () =>
      new Intl.DateTimeFormat(undefined, { month: "long", year: "numeric" }).format(firstOf(month)),
    [month],
  );
  const weekdays = useMemo(() => {
    const format = new Intl.DateTimeFormat(undefined, { weekday: "narrow" });
    const spoken = new Intl.DateTimeFormat(undefined, { weekday: "long" });
    // 2023-01-01 was a Sunday.
    return Array.from({ length: 7 }, (_, i) => {
      const date = new Date(2023, 0, 1 + ((i + weekStart) % 7));
      return { short: format.format(date), long: spoken.format(date) };
    });
  }, [weekStart]);
  const spokenDay = useMemo(
    () =>
      new Intl.DateTimeFormat(undefined, {
        weekday: "long",
        day: "numeric",
        month: "long",
        year: "numeric",
      }),
    [],
  );

  const cells = useMemo(() => {
    const first = firstOf(month);
    const lead = (first.getDay() - weekStart + 7) % 7;
    return Array.from({ length: ROWS * 7 }, (_, i) => {
      const date = new Date(first.getFullYear(), first.getMonth(), 1 - lead + i);
      return { iso: toISO(date), date, inMonth: toMonth(date) === month };
    });
  }, [month, weekStart]);

  const cell = width / 7;
  const selectedIndex = selected ? cells.findIndex((c) => c.iso === selected) : -1;

  // The pill glides to the selected day, or fades out when it is not on this page.
  useEffect(() => {
    if (cell <= 0) return;
    const to = { x: (selectedIndex % 7) * cell, y: Math.floor(selectedIndex / 7) * ROW };
    if (selectedIndex < 0) {
      Animated.timing(pillOn, {
        toValue: 0,
        duration: 120,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
      return;
    }
    if (!placed.current || reduceMotion) {
      placed.current = true;
      pill.setValue(to);
      pillOn.setValue(1);
      return;
    }
    Animated.parallel([
      Animated.spring(pill, {
        toValue: to,
        stiffness: 420,
        damping: 30,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }),
      Animated.timing(pillOn, { toValue: 1, duration: 120, useNativeDriver: NATIVE_DRIVER }),
    ]).start();
  }, [selectedIndex, cell, reduceMotion, pill, pillOn]);

  // The grid slides in from the side the new month lies on.
  useEffect(() => {
    if (previousMonth.current === month) return;
    const direction = month > previousMonth.current ? 1 : -1;
    previousMonth.current = month;
    if (reduceMotion) return;
    slide.setValue(direction * 28);
    fade.setValue(0);
    Animated.parallel([
      Animated.spring(slide, {
        toValue: 0,
        stiffness: 320,
        damping: 28,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }),
      Animated.timing(fade, { toValue: 1, duration: 180, useNativeDriver: NATIVE_DRIVER }),
    ]).start();
  }, [month, reduceMotion, slide, fade]);

  const swipe = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        Math.abs(g.dx) > 12 && Math.abs(g.dx) > Math.abs(g.dy) * 1.5,
      onPanResponderGrant: () => {
        dragging.current = true;
      },
      onPanResponderRelease: (_, g) => {
        setTimeout(() => (dragging.current = false), 80);
        if (Math.abs(g.dx) < 50 && Math.abs(g.vx) < 0.5) return;
        live.current.onMonthChange(addMonths(live.current.month, g.dx < 0 ? 1 : -1));
      },
      onPanResponderTerminate: () => setTimeout(() => (dragging.current = false), 80),
    }),
  ).current;

  const nav = (label: string, glyph: string, delta: number) => (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={label}
      hitSlop={6}
      onPress={() => onMonthChange(addMonths(month, delta))}
      style={({ pressed }) => [styles.nav, pressed && styles.dim]}
    >
      <Text style={[styles.navGlyph, { color: palette.text }]}>{glyph}</Text>
    </Pressable>
  );

  return (
    <View style={style}>
      <View style={styles.header}>
        {nav("Previous month", "‹", -1)}
        <Text
          accessibilityRole="header"
          accessibilityLiveRegion="polite"
          style={[styles.title, { color: palette.text }]}
        >
          {title}
        </Text>
        {nav("Next month", "›", 1)}
      </View>
      <View style={styles.week}>
        {weekdays.map((day, i) => (
          <Text
            key={`${i}-${day.long}`}
            accessibilityLabel={day.long}
            style={[styles.weekday, { color: palette.mutedText }]}
          >
            {day.short}
          </Text>
        ))}
      </View>
      <View
        {...swipe.panHandlers}
        onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
        style={styles.gridWrap}
      >
        <Animated.View
          style={{ height: ROW * ROWS, opacity: fade, transform: [{ translateX: slide }] }}
        >
          {cell > 0 ? (
            <Animated.View
              pointerEvents="none"
              style={[
                styles.pill,
                {
                  width: cell,
                  height: ROW,
                  opacity: pillOn,
                  transform: [{ translateX: pill.x }, { translateY: pill.y }],
                },
              ]}
            >
              <View style={[styles.pillInner, { backgroundColor: palette.pill }]} />
            </Animated.View>
          ) : null}
          <View style={styles.cells}>
            {cells.map(({ iso, date, inMonth }) => {
              const isSelected = iso === selected;
              const isToday = iso === todayISO;
              const hasEvents = markedSet.has(iso);
              return (
                <Pressable
                  key={iso}
                  accessibilityRole="button"
                  accessibilityLabel={`${spokenDay.format(date)}${hasEvents ? ", has events" : ""}`}
                  accessibilityState={{ selected: isSelected }}
                  aria-selected={isSelected}
                  aria-current={isToday ? "date" : undefined}
                  onPress={() => {
                    if (dragging.current) return;
                    if (!inMonth) onMonthChange(toMonth(date));
                    onSelect(iso);
                  }}
                  style={[styles.cell, { width: `${100 / 7}%` }]}
                >
                  <View
                    style={[
                      styles.day,
                      isToday && !isSelected && { borderColor: palette.today, borderWidth: 1.5 },
                    ]}
                  >
                    <Text
                      style={[
                        styles.dayText,
                        {
                          color: isSelected
                            ? palette.pillText
                            : inMonth
                              ? palette.text
                              : palette.mutedText,
                          fontWeight: isSelected || isToday ? "800" : "500",
                        },
                      ]}
                    >
                      {date.getDate()}
                    </Text>
                  </View>
                  <View
                    style={[
                      styles.dot,
                      { backgroundColor: palette.dot, opacity: hasEvents ? 1 : 0 },
                    ]}
                  />
                </Pressable>
              );
            })}
          </View>
        </Animated.View>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  header: {
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    marginBottom: 8,
  },
  nav: {
    width: 44,
    height: 44,
    alignItems: "center",
    justifyContent: "center",
    userSelect: "none",
  },
  navGlyph: { fontSize: 28, lineHeight: 30, fontWeight: "600" },
  dim: { opacity: 0.5 },
  title: { fontSize: 17, fontWeight: "800" },
  week: { flexDirection: "row", marginBottom: 4 },
  weekday: { flex: 1, textAlign: "center", fontSize: 12, fontWeight: "700" },
  gridWrap: { overflow: "hidden", userSelect: "none" },
  cells: { flexDirection: "row", flexWrap: "wrap" },
  cell: { height: ROW, alignItems: "center", justifyContent: "center" },
  day: {
    width: 34,
    height: 34,
    borderRadius: 17,
    alignItems: "center",
    justifyContent: "center",
    borderColor: "transparent",
    borderWidth: 1.5,
  },
  dayText: { fontSize: 15 },
  dot: { position: "absolute", bottom: 3, width: 4, height: 4, borderRadius: 2 },
  pill: { position: "absolute", top: 0, left: 0, alignItems: "center", justifyContent: "center" },
  pillInner: { width: 34, height: 34, borderRadius: 17 },
});
```

---

# Chat Bubble

> A React Native chat message that springs in from its own corner, shows delivery ticks that turn blue when read, and becomes a retry button when it fails.

Install: `npx @modus-ui/cli add chat-bubble`

A chat message bubble. It springs in from its own corner, shows delivery ticks that move from sending to sent, delivered and read, and a failed message turns red and becomes a retry button. A run of messages from one sender can share a single tail. The sender, text, time and delivery state are read out as one sentence. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add chat-bubble
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/chat-bubble.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { ChatBubble } from "@/components/ui/chat-bubble";

export default function Example() {
  return (
    <>
      <ChatBubble side="them" name="Maya" text="Are we still on for Thursday?" time="9:38" />
      <ChatBubble side="me" text="Yes! Same place as last time." time="9:39" status="read" />
    </>
  );
}
```

## Props

| Prop        | Type                                                       | Default  | Description                                                                        |
| :---------- | :--------------------------------------------------------- | :------- | :--------------------------------------------------------------------------------- |
| `text`      | `string`                                                   | -        | The message text.                                                                  |
| `side`      | `"me" \| "them"`                                           | `"them"` | Whose message it is. Your own sit on the right.                                    |
| `name`      | `string`                                                   | -        | The sender's name, read out and shown above messages from others.                  |
| `time`      | `string`                                                   | -        | The time shown under the message, for example "9:41".                              |
| `status`    | `"sending" \| "sent" \| "delivered" \| "read" \| "failed"` | -        | Delivery state of one of your own messages.                                        |
| `tail`      | `boolean`                                                  | `true`   | Draws the small tail. Turn it off for all but the last message of a run.           |
| `onRetry`   | `() => void`                                               | -        | Called when a failed message is pressed.                                           |
| `animateIn` | `boolean`                                                  | `true`   | Slides and scales the bubble in when it first appears.                             |
| `colors`    | `Partial<ChatBubbleColors>`                                | -        | Overrides `mine`, `theirs`, `mineText`, `theirsText`, `meta`, `read` and `failed`. |
| `style`     | `StyleProp<ViewStyle>`                                     | -        | Style for the row that holds the bubble.                                           |

## Source

`components/ui/chat-bubble.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export type ChatStatus = "sending" | "sent" | "delivered" | "read" | "failed";

export interface ChatBubbleColors {
  mine: string;
  theirs: string;
  mineText: string;
  theirsText: string;
  meta: string;
  read: string;
  failed: string;
}

const DEFAULT_COLORS: ChatBubbleColors = {
  mine: "#4f46e5",
  theirs: "#f3f4f6",
  mineText: "#ffffff",
  theirsText: "#111827",
  meta: "#9ca3af",
  read: "#38bdf8",
  failed: "#dc2626",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

const STATUS_TEXT: Record<ChatStatus, string> = {
  sending: "sending",
  sent: "sent",
  delivered: "delivered",
  read: "read",
  failed: "failed to send",
};

export interface ChatBubbleProps {
  /** The message text. */
  text?: string;
  /** Replaces the text, for an image or any other content. */
  children?: ReactNode;
  /** Whose message it is: your own sit on the right. */
  side?: "me" | "them";
  /** The sender's name, read out and shown above messages from others. */
  name?: string;
  /** The time shown under the message, for example "9:41". */
  time?: string;
  /** Delivery state of one of your own messages. */
  status?: ChatStatus;
  /** Draws the small tail. Turn it off for all but the last message of a run. */
  tail?: boolean;
  /** Called when a failed message is pressed. */
  onRetry?: () => void;
  /** Slides and scales the bubble in when it first appears. */
  animateIn?: boolean;
  colors?: Partial<ChatBubbleColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A chat message bubble. It springs in from its own corner, shows delivery ticks that turn to read,
 * and a failed message becomes a retry button. A run of messages from one sender shares a single tail.
 * The sender, text, time and delivery state are read out as one sentence.
 */
export function ChatBubble({
  text,
  children,
  side = "them",
  name,
  time,
  status,
  tail = true,
  onRetry,
  animateIn = true,
  colors,
  style,
}: ChatBubbleProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const mine = side === "me";
  const enter = useRef(new Animated.Value(animateIn ? 0 : 1)).current;

  useEffect(() => {
    if (!animateIn || reduceMotion) {
      enter.setValue(1);
      return;
    }
    Animated.spring(enter, {
      toValue: 1,
      stiffness: 360,
      damping: 24,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
    // The entrance plays once, when the bubble mounts.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  const failed = status === "failed";
  const bubbleColor = mine ? palette.mine : palette.theirs;
  const textColor = mine ? palette.mineText : palette.theirsText;
  const spoken = [
    mine ? "You" : (name ?? "Them"),
    text ?? "attachment",
    time,
    mine && status ? STATUS_TEXT[status] : undefined,
  ]
    .filter(Boolean)
    .join(", ");

  const ticks =
    status === "sending"
      ? "…"
      : status === "sent"
        ? "✓"
        : status === "delivered" || status === "read"
          ? "✓✓"
          : "";

  const body = (
    <View
      accessible
      accessibilityLabel={spoken}
      aria-label={spoken}
      style={[
        styles.bubble,
        { backgroundColor: failed ? palette.failed : bubbleColor },
        mine ? styles.mineCorner : styles.theirCorner,
        !tail && styles.noTail,
      ]}
    >
      {!mine && name ? <Text style={[styles.name, { color: palette.meta }]}>{name}</Text> : null}
      {children ?? (
        <Text style={[styles.text, { color: failed ? "#ffffff" : textColor }]}>{text}</Text>
      )}
      {time || ticks ? (
        <View style={styles.meta}>
          {time ? (
            <Text style={[styles.time, { color: mine ? "rgba(255,255,255,0.75)" : palette.meta }]}>
              {time}
            </Text>
          ) : null}
          {mine && ticks ? (
            <Text
              style={[
                styles.ticks,
                { color: status === "read" ? palette.read : "rgba(255,255,255,0.75)" },
              ]}
            >
              {ticks}
            </Text>
          ) : null}
        </View>
      ) : null}
    </View>
  );

  return (
    <Animated.View
      style={[
        styles.row,
        mine ? styles.rowMine : styles.rowTheirs,
        {
          opacity: enter,
          transform: [
            { translateY: enter.interpolate({ inputRange: [0, 1], outputRange: [14, 0] }) },
            { scale: enter.interpolate({ inputRange: [0, 1], outputRange: [0.86, 1] }) },
          ],
        },
        style,
      ]}
    >
      {failed && onRetry ? (
        <Pressable
          accessibilityRole="button"
          accessibilityLabel="Message failed to send. Tap to retry"
          onPress={onRetry}
          style={styles.retry}
        >
          <Text style={[styles.retryGlyph, { color: palette.failed }]}>↻</Text>
        </Pressable>
      ) : null}
      {body}
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "flex-end", marginVertical: 2, paddingHorizontal: 12 },
  rowMine: { justifyContent: "flex-end", transformOrigin: "right bottom" },
  rowTheirs: { justifyContent: "flex-start", transformOrigin: "left bottom" },
  bubble: {
    maxWidth: "78%",
    paddingHorizontal: 12,
    paddingTop: 8,
    paddingBottom: 6,
    borderRadius: 18,
  },
  mineCorner: { borderBottomRightRadius: 5 },
  theirCorner: { borderBottomLeftRadius: 5 },
  noTail: { borderBottomRightRadius: 18, borderBottomLeftRadius: 18 },
  name: { fontSize: 12, fontWeight: "700", marginBottom: 2 },
  text: { fontSize: 16, lineHeight: 22 },
  meta: { flexDirection: "row", alignSelf: "flex-end", alignItems: "center", gap: 4, marginTop: 2 },
  time: { fontSize: 11 },
  ticks: { fontSize: 11, fontWeight: "700", letterSpacing: -1 },
  retry: { width: 44, height: 44, alignItems: "center", justifyContent: "center", marginRight: 2 },
  retryGlyph: { fontSize: 24, fontWeight: "700" },
});
```

---

# Live Dot

> A React Native presence and broadcast indicator whose live or online dot sends a soft ring outward on a loop, and whose status is always spoken as well as coloured.

Install: `npx @modus-ui/cli add live-dot`

A presence or broadcast indicator. A live or online dot sends a soft ring outward on a loop, and the colour changes between statuses. Away, busy and offline stay still. The status is read out as words, so it never relies on colour alone, and with reduced motion the ring doesn't pulse. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add live-dot
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/live-dot.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { LiveDot } from "@/components/ui/live-dot";

export default function Example() {
  return <LiveDot status="live" showLabel />;
}
```

## Props

| Prop        | Type                                                  | Default | Description                                                        |
| :---------- | :---------------------------------------------------- | :------ | :----------------------------------------------------------------- |
| `status`    | `"live" \| "online" \| "away" \| "busy" \| "offline"` | -       | Which state the dot shows.                                         |
| `size`      | `number`                                              | `10`    | Diameter of the dot.                                               |
| `pulse`     | `boolean`                                             | `true`  | Sends a soft ring outward from the dot while it is live or online. |
| `showLabel` | `boolean`                                             | `false` | Shows the status word beside the dot.                              |
| `label`     | `string`                                              | -       | Replaces the status word, for example "Recording".                 |
| `colors`    | `Partial<LiveDotColors>`                              | -       | Overrides `live`, `online`, `away`, `busy`, `offline` and `text`.  |
| `style`     | `StyleProp<ViewStyle>`                                | -       | Style for the row.                                                 |

## Source

`components/ui/live-dot.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export type LiveStatus = "live" | "online" | "away" | "busy" | "offline";

export interface LiveDotColors {
  live: string;
  online: string;
  away: string;
  busy: string;
  offline: string;
  text: string;
}

const DEFAULT_COLORS: LiveDotColors = {
  live: "#ef4444",
  online: "#22c55e",
  away: "#f59e0b",
  busy: "#dc2626",
  offline: "#9ca3af",
  text: "#111827",
};

const WORDS: Record<LiveStatus, string> = {
  live: "Live",
  online: "Online",
  away: "Away",
  busy: "Busy",
  offline: "Offline",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface LiveDotProps {
  status: LiveStatus;
  /** Diameter of the dot. */
  size?: number;
  /** Sends a soft ring outward from the dot while it is live or online. */
  pulse?: boolean;
  /** Shows the status word beside the dot. */
  showLabel?: boolean;
  /** Replaces the status word, for example "Recording". */
  label?: string;
  colors?: Partial<LiveDotColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A presence or broadcast indicator. A live or online dot sends a soft ring outward on a loop, and
 * the colour change between statuses blends. Away, busy and offline stay still. The status is read
 * out, so it never relies on colour alone.
 */
export function LiveDot({
  status,
  size = 10,
  pulse = true,
  showLabel = false,
  label,
  colors,
  style,
}: LiveDotProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const ring = useRef(new Animated.Value(0)).current;
  const active = pulse && !reduceMotion && (status === "live" || status === "online");
  const word = label ?? WORDS[status];

  useEffect(() => {
    if (!active) {
      ring.setValue(0);
      return;
    }
    const loop = Animated.loop(
      Animated.timing(ring, {
        toValue: 1,
        duration: status === "live" ? 1100 : 1900,
        easing: Easing.out(Easing.quad),
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [active, status, ring]);

  const color = palette[status];
  const spread = size * 2.6;

  return (
    <View
      accessible
      accessibilityRole="text"
      accessibilityLabel={word}
      aria-label={word}
      style={[styles.row, style]}
    >
      <View style={{ width: size, height: size }}>
        <Animated.View
          pointerEvents="none"
          style={[
            styles.ring,
            {
              width: size,
              height: size,
              borderRadius: size / 2,
              backgroundColor: color,
              // Always mounted, so the loop is never rebuilt; it is simply invisible when idle.
              opacity: active
                ? ring.interpolate({ inputRange: [0, 1], outputRange: [0.45, 0] })
                : 0,
              transform: [
                {
                  scale: ring.interpolate({ inputRange: [0, 1], outputRange: [1, spread / size] }),
                },
              ],
            },
          ]}
        />
        <View
          style={{ width: size, height: size, borderRadius: size / 2, backgroundColor: color }}
        />
      </View>
      {showLabel ? (
        <Text style={[styles.label, { color: status === "live" ? palette.live : palette.text }]}>
          {status === "live" ? word.toUpperCase() : word}
        </Text>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 6 },
  ring: { position: "absolute", top: 0, left: 0 },
  label: { fontSize: 13, fontWeight: "700", letterSpacing: 0.3 },
});
```

---

# Composer Bar

> A React Native message composer whose field grows line by line, whose microphone turns into a send arrow as you type, and which sends on Enter on the web.

Install: `npx @modus-ui/cli add composer-bar`

A message composer. The field grows line by line up to a limit, and the button on the right turns from a microphone into a send arrow as soon as there is text, with the two glyphs swapping on a spring. On the web Enter sends and Shift+Enter starts a new line. It clears itself after sending and keeps focus, so you can keep typing. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add composer-bar
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/composer-bar.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { ComposerBar } from "@/components/ui/composer-bar";

export default function Example() {
  const [text, setText] = useState("");

  return (
    <ComposerBar
      value={text}
      onChangeText={setText}
      onSend={(message) => console.log("send", message)}
      onAttach={() => console.log("attach")}
      onRecord={() => console.log("record")}
    />
  );
}
```

## Props

| Prop           | Type                         | Default     | Description                                                                                          |
| :------------- | :--------------------------- | :---------- | :--------------------------------------------------------------------------------------------------- |
| `value`        | `string`                     | -           | The text in the field.                                                                               |
| `onChangeText` | `(text: string) => void`     | -           | Called as the text changes, and with an empty string after sending.                                  |
| `onSend`       | `(text: string) => void`     | -           | Called with the trimmed text when the send button or Enter (on the web) is pressed.                  |
| `placeholder`  | `string`                     | `"Message"` | Hint shown in the empty field, also its spoken label.                                                |
| `maxLines`     | `number`                     | `5`         | How many lines the field grows to before it scrolls.                                                 |
| `onAttach`     | `() => void`                 | -           | Shows a plus button on the left when given.                                                          |
| `onRecord`     | `() => void`                 | -           | Shows a microphone in place of the send button while the field is empty, when given.                 |
| `disabled`     | `boolean`                    | `false`     | Stops editing and sending.                                                                           |
| `colors`       | `Partial<ComposerBarColors>` | -           | Overrides `background`, `field`, `border`, `text`, `placeholder`, `accent`, `accentText` and `icon`. |
| `style`        | `StyleProp<ViewStyle>`       | -           | Style for the bar.                                                                                   |

## Source

`components/ui/composer-bar.tsx`

```tsx
import { useEffect, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type LayoutChangeEvent,
  type TextInputKeyPressEvent,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const LINE = 22;
const MIN_HEIGHT = 40;

export interface ComposerBarColors {
  background: string;
  field: string;
  border: string;
  text: string;
  placeholder: string;
  accent: string;
  accentText: string;
  icon: string;
}

const DEFAULT_COLORS: ComposerBarColors = {
  background: "#ffffff",
  field: "#f3f4f6",
  border: "#e5e7eb",
  text: "#111827",
  placeholder: "#9ca3af",
  accent: "#4f46e5",
  accentText: "#ffffff",
  icon: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ComposerBarProps {
  value: string;
  onChangeText: (text: string) => void;
  /** Called with the trimmed text when the send button or Enter (on the web) is pressed. */
  onSend: (text: string) => void;
  placeholder?: string;
  /** How many lines the field grows to before it scrolls. */
  maxLines?: number;
  /** Shows a plus button on the left when given. */
  onAttach?: () => void;
  /** Shows a microphone in place of the send button while the field is empty, when given. */
  onRecord?: () => void;
  disabled?: boolean;
  colors?: Partial<ComposerBarColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A message composer. The field grows line by line up to a limit, and the button on the right turns
 * from a microphone into a send arrow as soon as there is text, with the two glyphs swapping on a
 * spring. On the web Enter sends and Shift+Enter starts a new line. It clears itself after sending.
 */
export function ComposerBar({
  value,
  onChangeText,
  onSend,
  placeholder = "Message",
  maxLines = 5,
  onAttach,
  onRecord,
  disabled = false,
  colors,
  style,
}: ComposerBarProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const input = useRef<ElementRef<typeof TextInput>>(null);
  const [height, setHeight] = useState(MIN_HEIGHT);
  const text = value.trim();
  const ready = text.length > 0;
  const mode = useRef(new Animated.Value(ready ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      mode.setValue(ready ? 1 : 0);
      return;
    }
    Animated.spring(mode, {
      toValue: ready ? 1 : 0,
      stiffness: 420,
      damping: 24,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [ready, reduceMotion, mode]);

  const send = () => {
    if (!ready || disabled) return;
    onSend(text);
    onChangeText("");
    setHeight(MIN_HEIGHT);
    input.current?.focus();
  };

  const onMirrorLayout = (event: LayoutChangeEvent) => {
    const next = event.nativeEvent.layout.height + 14;
    setHeight(Math.max(MIN_HEIGHT, Math.min(LINE * maxLines + 14, next)));
  };

  const onKeyPress = (event: TextInputKeyPressEvent) => {
    const native = event.nativeEvent as typeof event.nativeEvent & { shiftKey?: boolean };
    if (Platform.OS === "web" && native.key === "Enter" && !native.shiftKey) {
      (event as unknown as { preventDefault?: () => void }).preventDefault?.();
      send();
    }
  };

  const showAction = ready || !!onRecord;
  const micOpacity = mode.interpolate({ inputRange: [0, 1], outputRange: [1, 0] });
  const sendOpacity = mode;

  return (
    <View
      style={[
        styles.bar,
        { backgroundColor: palette.background, borderTopColor: palette.border },
        style,
      ]}
    >
      {onAttach ? (
        <Pressable
          accessibilityRole="button"
          accessibilityLabel="Add attachment"
          disabled={disabled}
          onPress={onAttach}
          style={({ pressed }) => [styles.side, pressed && styles.dim]}
        >
          <Text style={[styles.plus, { color: palette.icon }]}>+</Text>
        </Pressable>
      ) : null}
      <View
        style={[styles.field, { backgroundColor: palette.field, minHeight: MIN_HEIGHT, height }]}
      >
        {/* A hidden copy of the text, wrapped like the field, whose height sets the field's. Measuring the
            field itself fails on the web: it reports a taller content size than it needs and never shrinks. */}
        <Text
          pointerEvents="none"
          accessibilityElementsHidden
          importantForAccessibility="no-hide-descendants"
          onLayout={onMirrorLayout}
          style={[styles.mirror, { fontSize: 16, lineHeight: LINE }]}
        >
          {value.endsWith("\n") || value === "" ? `${value} ` : value}
        </Text>
        <TextInput
          ref={input}
          value={value}
          onChangeText={onChangeText}
          onKeyPress={onKeyPress}
          editable={!disabled}
          multiline
          blurOnSubmit={false}
          placeholder={placeholder}
          placeholderTextColor={palette.placeholder}
          accessibilityLabel={placeholder}
          aria-label={placeholder}
          selectionColor={palette.accent}
          style={[styles.input, { color: palette.text, height: height - 2 }]}
        />
      </View>
      {showAction ? (
        <Pressable
          accessibilityRole="button"
          accessibilityLabel={ready ? "Send message" : "Record voice message"}
          disabled={disabled || (!ready && !onRecord)}
          onPress={ready ? send : onRecord}
          style={({ pressed }) => [styles.side, pressed && styles.dim]}
        >
          <Animated.View
            style={[
              styles.action,
              {
                backgroundColor: ready ? palette.accent : "transparent",
                transform: [
                  { scale: mode.interpolate({ inputRange: [0, 1], outputRange: [0.9, 1] }) },
                ],
              },
            ]}
          >
            <Animated.Text style={[styles.glyph, { color: palette.icon, opacity: micOpacity }]}>
              ●
            </Animated.Text>
            <Animated.Text
              style={[
                styles.glyph,
                styles.over,
                {
                  color: palette.accentText,
                  opacity: sendOpacity,
                  transform: [
                    {
                      rotate: mode.interpolate({
                        inputRange: [0, 1],
                        outputRange: ["-90deg", "0deg"],
                      }),
                    },
                  ],
                },
              ]}
            >
              ↑
            </Animated.Text>
          </Animated.View>
        </Pressable>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  bar: {
    flexDirection: "row",
    alignItems: "flex-end",
    gap: 6,
    paddingHorizontal: 8,
    paddingVertical: 8,
    borderTopWidth: StyleSheet.hairlineWidth,
  },
  side: {
    width: 44,
    height: 44,
    alignItems: "center",
    justifyContent: "center",
    userSelect: "none",
  },
  plus: { fontSize: 30, lineHeight: 32, fontWeight: "300" },
  field: { flex: 1, borderRadius: 20, paddingHorizontal: 14, justifyContent: "center" },
  input: { fontSize: 16, lineHeight: LINE, paddingVertical: 7, outlineStyle: "none" } as object,
  action: {
    width: 36,
    height: 36,
    borderRadius: 18,
    alignItems: "center",
    justifyContent: "center",
  },
  glyph: { fontSize: 18, fontWeight: "800" },
  over: { position: "absolute" },
  mirror: { position: "absolute", left: 14, right: 14, top: 0, opacity: 0, paddingVertical: 0 },
  dim: { opacity: 0.6 },
});
```

---

# Setting List

> A React Native grouped settings list with icon tiles, chevrons, values and animated switches, in the style of a phone's own settings screen.

Install: `npx @modus-ui/cli add setting-list`

A grouped settings list in the style of a phone's own settings screen. Rows are rounded and split by hairlines, each with an optional icon tile, a label and description, and a chevron, a value or a switch on the right. The switches slide on a spring and are real switches to screen readers, a pressed row highlights, and a row can be marked destructive or disabled. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add setting-list
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/setting-list.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { SettingList } from "@/components/ui/setting-list";

export default function Example() {
  const [push, setPush] = useState(true);

  return (
    <SettingList
      header="Preferences"
      items={[
        { id: "push", label: "Notifications", kind: "toggle", checked: push, onToggle: setPush },
        { id: "lang", label: "Language", kind: "value", value: "English", onPress: () => {} },
      ]}
    />
  );
}
```

## Props

| Prop     | Type                         | Default | Description                                                                                                                                                                                                    |
| :------- | :--------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items`  | `SettingItem[]`              | -       | The rows. Each has an `id` and a `label`, and optionally `icon`, `description`, `kind` (`"link"`, `"value"`, `"toggle"` or `"info"`), `value`, `checked`, `onPress`, `onToggle`, `destructive` and `disabled`. |
| `header` | `string`                     | -       | A small heading above the group.                                                                                                                                                                               |
| `footer` | `string`                     | -       | Explanatory text under the group.                                                                                                                                                                              |
| `colors` | `Partial<SettingListColors>` | -       | Overrides `surface`, `border`, `text`, `muted`, `accent`, `destructive`, `tile` and `track`.                                                                                                                   |
| `style`  | `StyleProp<ViewStyle>`       | -       | Style for the group and its heading.                                                                                                                                                                           |

## Source

`components/ui/setting-list.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const TRACK_W = 46;
const TRACK_H = 28;
const THUMB = 22;

export interface SettingItem {
  id: string;
  label: string;
  /** A glyph or small view shown in a tile at the start of the row. */
  icon?: ReactNode;
  /** A smaller line under the label. */
  description?: string;
  /** "link" shows a chevron, "value" shows `value`, "toggle" a switch, and "info" is not pressable. */
  kind?: "link" | "value" | "toggle" | "info";
  value?: string;
  checked?: boolean;
  onPress?: () => void;
  onToggle?: (next: boolean) => void;
  destructive?: boolean;
  disabled?: boolean;
}

export interface SettingListColors {
  surface: string;
  border: string;
  text: string;
  muted: string;
  accent: string;
  destructive: string;
  tile: string;
  track: string;
}

const DEFAULT_COLORS: SettingListColors = {
  surface: "#ffffff",
  border: "#e5e7eb",
  text: "#111827",
  muted: "#6b7280",
  accent: "#4f46e5",
  destructive: "#dc2626",
  tile: "#f3f4f6",
  track: "#d1d5db",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

function Switch({
  on,
  accent,
  track,
  reduceMotion,
}: {
  on: boolean;
  accent: string;
  track: string;
  reduceMotion: boolean;
}) {
  const t = useRef(new Animated.Value(on ? 1 : 0)).current;
  useEffect(() => {
    if (reduceMotion) {
      t.setValue(on ? 1 : 0);
      return;
    }
    Animated.spring(t, {
      toValue: on ? 1 : 0,
      stiffness: 420,
      damping: 26,
      mass: 1,
      useNativeDriver: false,
    }).start();
  }, [on, reduceMotion, t]);
  return (
    <Animated.View
      pointerEvents="none"
      style={{
        width: TRACK_W,
        height: TRACK_H,
        borderRadius: TRACK_H / 2,
        justifyContent: "center",
        backgroundColor: t.interpolate({ inputRange: [0, 1], outputRange: [track, accent] }),
      }}
    >
      <Animated.View
        style={{
          width: THUMB,
          height: THUMB,
          borderRadius: THUMB / 2,
          backgroundColor: "#ffffff",
          boxShadow: "0 1px 3px rgba(0, 0, 0, 0.3)",
          transform: [
            {
              translateX: t.interpolate({
                inputRange: [0, 1],
                outputRange: [3, TRACK_W - THUMB - 3],
              }),
            },
          ],
        }}
      />
    </Animated.View>
  );
}

export interface SettingListProps {
  items: SettingItem[];
  /** A small heading above the group. */
  header?: string;
  /** Explanatory text under the group. */
  footer?: string;
  colors?: Partial<SettingListColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A grouped settings list in the style of a phone's own settings screen: rounded rows split by
 * hairlines, with an icon tile, a label and a description, and a chevron, a value or a switch on the
 * right. Switches are real switches to screen readers, and a pressed row highlights.
 */
export function SettingList({ items, header, footer, colors, style }: SettingListProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  return (
    <View style={style}>
      {header ? (
        <Text style={[styles.header, { color: palette.muted }]}>{header.toUpperCase()}</Text>
      ) : null}
      <View
        style={[styles.group, { backgroundColor: palette.surface, borderColor: palette.border }]}
      >
        {items.map((item, i) => {
          const kind = item.kind ?? "link";
          const toggle = kind === "toggle";
          const pressable = kind !== "info" && !item.disabled;
          const color = item.destructive ? palette.destructive : palette.text;
          const spoken = [item.label, item.description, kind === "value" ? item.value : undefined]
            .filter(Boolean)
            .join(", ");
          return (
            <Pressable
              key={item.id}
              accessibilityRole={toggle ? "switch" : kind === "info" ? "text" : "button"}
              accessibilityLabel={spoken}
              accessibilityState={
                toggle
                  ? { checked: !!item.checked, disabled: !!item.disabled }
                  : { disabled: !!item.disabled }
              }
              aria-checked={toggle ? !!item.checked : undefined}
              aria-disabled={!!item.disabled}
              disabled={!pressable}
              onPress={() => (toggle ? item.onToggle?.(!item.checked) : item.onPress?.())}
              style={({ pressed }) => [
                styles.row,
                i > 0 && {
                  borderTopWidth: StyleSheet.hairlineWidth,
                  borderTopColor: palette.border,
                },
                pressed && { backgroundColor: palette.tile },
                item.disabled && styles.disabled,
              ]}
            >
              {item.icon ? (
                <View style={[styles.tile, { backgroundColor: palette.tile }]}>{item.icon}</View>
              ) : null}
              <View style={styles.text}>
                <Text style={[styles.label, { color }]}>{item.label}</Text>
                {item.description ? (
                  <Text style={[styles.description, { color: palette.muted }]}>
                    {item.description}
                  </Text>
                ) : null}
              </View>
              {toggle ? (
                <Switch
                  on={!!item.checked}
                  accent={palette.accent}
                  track={palette.track}
                  reduceMotion={reduceMotion}
                />
              ) : (
                <View style={styles.end}>
                  {item.value && (kind === "value" || kind === "link" || kind === "info") ? (
                    <Text style={[styles.value, { color: palette.muted }]}>{item.value}</Text>
                  ) : null}
                  {kind === "link" ? (
                    <Text style={[styles.chevron, { color: palette.muted }]}>›</Text>
                  ) : null}
                </View>
              )}
            </Pressable>
          );
        })}
      </View>
      {footer ? <Text style={[styles.footer, { color: palette.muted }]}>{footer}</Text> : null}
    </View>
  );
}

const styles = StyleSheet.create({
  header: { fontSize: 12, fontWeight: "700", letterSpacing: 0.6, marginBottom: 6, marginLeft: 14 },
  group: { borderRadius: 14, borderWidth: StyleSheet.hairlineWidth, overflow: "hidden" },
  row: {
    minHeight: 54,
    flexDirection: "row",
    alignItems: "center",
    gap: 12,
    paddingHorizontal: 14,
    paddingVertical: 8,
    userSelect: "none",
  },
  tile: { width: 32, height: 32, borderRadius: 8, alignItems: "center", justifyContent: "center" },
  text: { flex: 1, gap: 1 },
  label: { fontSize: 16, fontWeight: "500" },
  description: { fontSize: 13 },
  end: { flexDirection: "row", alignItems: "center", gap: 6 },
  value: { fontSize: 15 },
  chevron: { fontSize: 24, lineHeight: 26 },
  footer: { fontSize: 13, lineHeight: 18, marginTop: 6, marginHorizontal: 14 },
  disabled: { opacity: 0.45 },
});
```

---

# Pull Refresh

> A React Native scrolling list you refresh by pulling down from the top, with resistance, a turning arrow, a holding spinner, and a Refresh action for screen readers.

Install: `npx @modus-ui/cli add pull-refresh`

A scrolling list you refresh by pulling it down from the top. The content follows your finger with growing resistance, an arrow turns over as you reach the threshold, and on release a spinner holds the content open until you set `refreshing` back to false. It works with a mouse drag on the web, and screen reader users get a Refresh action instead of the gesture. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add pull-refresh
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/pull-refresh.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Text } from "react-native";
import { PullRefresh } from "@/components/ui/pull-refresh";

export default function Example() {
  const [refreshing, setRefreshing] = useState(false);

  const refresh = async () => {
    setRefreshing(true);
    await fetch("/api/feed");
    setRefreshing(false);
  };

  return (
    <PullRefresh refreshing={refreshing} onRefresh={refresh}>
      <Text style={{ padding: 20 }}>Feed items go here.</Text>
    </PullRefresh>
  );
}
```

The component fills its parent, so give the parent a height.

## Props

| Prop         | Type                         | Default | Description                                                                     |
| :----------- | :--------------------------- | :------ | :------------------------------------------------------------------------------ |
| `refreshing` | `boolean`                    | -       | Whether a refresh is under way. Set it true in `onRefresh` and false when done. |
| `onRefresh`  | `() => void`                 | -       | Called when the list is pulled past the threshold and let go.                   |
| `threshold`  | `number`                     | `72`    | How far, in pixels, the content must be pulled to trigger a refresh.            |
| `colors`     | `Partial<PullRefreshColors>` | -       | Overrides `indicator`, `arrow` and `background`.                                |
| `style`      | `StyleProp<ViewStyle>`       | -       | Style for the container.                                                        |

## Source

`components/ui/pull-refresh.tsx`

```tsx
import { useEffect, useRef, useState, type ElementRef, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  PanResponder,
  Platform,
  ScrollView,
  StyleSheet,
  Text,
  View,
  type NativeScrollEvent,
  type NativeSyntheticEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const INDICATOR = 40;

export interface PullRefreshColors {
  indicator: string;
  arrow: string;
  background: string;
}

const DEFAULT_COLORS: PullRefreshColors = {
  indicator: "#4f46e5",
  arrow: "#6b7280",
  background: "transparent",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface PullRefreshProps {
  /** Whether a refresh is under way. Set it true in `onRefresh` and false when the work is done. */
  refreshing: boolean;
  /** Called when the list is pulled past the threshold and let go. */
  onRefresh: () => void;
  /** The scrolling content. */
  children: ReactNode;
  /** How far, in pixels, the content must be pulled to trigger a refresh. */
  threshold?: number;
  colors?: Partial<PullRefreshColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A scrolling list you refresh by pulling it down from the top. The content follows your finger
 * with growing resistance, an arrow turns over as you reach the threshold, and on release a spinner
 * holds the content open until you set `refreshing` back to false. It works with a mouse drag on the
 * web, and screen readers get a Refresh action instead.
 */
export function PullRefresh({
  refreshing,
  onRefresh,
  children,
  threshold = 72,
  colors,
  style,
}: PullRefreshProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const pull = useRef(new Animated.Value(0)).current;
  const spin = useRef(new Animated.Value(0)).current;
  const atTop = useRef(true);
  const dragging = useRef(false);
  const hold = INDICATOR + 12;

  const live = useRef({ refreshing, onRefresh, threshold, reduceMotion });
  live.current = { refreshing, onRefresh, threshold, reduceMotion };

  const settleTo = (toValue: number) => {
    if (live.current.reduceMotion) {
      pull.setValue(toValue);
      return;
    }
    Animated.spring(pull, {
      toValue,
      stiffness: 300,
      damping: 28,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  // Hold the content open while refreshing, and close it when the work is done.
  useEffect(() => {
    if (dragging.current) return;
    settleTo(refreshing ? hold : 0);
    // settleTo reads everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [refreshing, reduceMotion]);

  useEffect(() => {
    if (!refreshing || reduceMotion) {
      spin.setValue(0);
      return;
    }
    const loop = Animated.loop(
      Animated.timing(spin, {
        toValue: 1,
        duration: 800,
        easing: Easing.linear,
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [refreshing, reduceMotion, spin]);

  const responder = useRef(
    PanResponder.create({
      onMoveShouldSetPanResponder: (_, g) =>
        atTop.current && !live.current.refreshing && g.dy > 6 && Math.abs(g.dy) > Math.abs(g.dx),
      onPanResponderGrant: () => {
        dragging.current = true;
        pull.stopAnimation();
      },
      // Growing resistance: the content moves less and less the further it is pulled.
      onPanResponderMove: (_, g) => {
        const limit = live.current.threshold * 1.8;
        pull.setValue(limit * (1 - Math.exp(-Math.max(0, g.dy) / (limit * 1.2))));
      },
      onPanResponderRelease: () => {
        dragging.current = false;
        pull.stopAnimation((value) => {
          if (value >= live.current.threshold * 0.8) {
            live.current.onRefresh();
            settleTo(hold);
          } else {
            settleTo(0);
          }
        });
      },
      onPanResponderTerminate: () => {
        dragging.current = false;
        settleTo(live.current.refreshing ? hold : 0);
      },
    }),
  ).current;

  const onScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
    atTop.current = event.nativeEvent.contentOffset.y <= 0;
  };

  const progress = pull.interpolate({
    inputRange: [0, threshold * 0.8],
    outputRange: [0, 1],
    extrapolate: "clamp",
  });
  const scroller = useRef<ElementRef<typeof ScrollView>>(null);

  return (
    <View
      accessibilityActions={[{ name: "refresh", label: "Refresh" }]}
      onAccessibilityAction={(event) => {
        if (event.nativeEvent.actionName === "refresh" && !refreshing) onRefresh();
      }}
      style={[styles.root, { backgroundColor: palette.background }, style]}
    >
      <Animated.View
        pointerEvents="none"
        accessibilityElementsHidden
        style={[
          styles.indicator,
          {
            opacity: progress,
            transform: [
              {
                translateY: pull.interpolate({
                  inputRange: [0, hold],
                  outputRange: [-INDICATOR, 6],
                  extrapolate: "extend",
                }),
              },
              { scale: progress.interpolate({ inputRange: [0, 1], outputRange: [0.6, 1] }) },
            ],
          },
        ]}
      >
        {refreshing ? (
          <Animated.View
            style={[
              styles.spinner,
              {
                borderTopColor: palette.indicator,
                transform: [
                  {
                    rotate: spin.interpolate({
                      inputRange: [0, 1],
                      outputRange: ["0deg", "360deg"],
                    }),
                  },
                ],
              },
            ]}
          />
        ) : (
          <Animated.Text
            style={[
              styles.arrow,
              {
                color: progress.interpolate({
                  inputRange: [0, 1],
                  outputRange: [palette.arrow, palette.indicator],
                }),
                transform: [
                  {
                    rotate: progress.interpolate({
                      inputRange: [0, 0.9, 1],
                      outputRange: ["0deg", "0deg", "180deg"],
                    }),
                  },
                ],
              },
            ]}
          >
            ↓
          </Animated.Text>
        )}
      </Animated.View>
      <Animated.View
        {...responder.panHandlers}
        style={[styles.content, { transform: [{ translateY: pull }] }]}
      >
        <ScrollView ref={scroller} bounces={false} scrollEventThrottle={16} onScroll={onScroll}>
          {children}
        </ScrollView>
      </Animated.View>
      {refreshing ? (
        <Text accessibilityLiveRegion="polite" style={styles.sr}>
          Refreshing
        </Text>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, overflow: "hidden", userSelect: "none" },
  indicator: {
    position: "absolute",
    top: 0,
    left: 0,
    right: 0,
    height: INDICATOR,
    alignItems: "center",
    justifyContent: "center",
  },
  spinner: {
    width: 26,
    height: 26,
    borderRadius: 13,
    borderWidth: 3,
    borderColor: "rgba(128,128,128,0.25)",
  },
  arrow: { fontSize: 22, fontWeight: "800" },
  content: { flex: 1 },
  sr: { position: "absolute", width: 1, height: 1, opacity: 0 },
});
```

---

# Story Bars

> The React Native row of segmented progress bars from a story viewer, which fills each story in turn, holds in place when paused, and announces its position.

Install: `npx @modus-ui/cli add story-bars`

The row of progress bars at the top of a story viewer. Finished stories are full, the current one fills over `duration` and then asks for the next, and the rest are empty. Pausing holds the fill in place and resuming carries on from where it stopped. The position is read out as "Story 2 of 5". The bars only keep time; you add the tap zones, so the viewer can also go back, skip ahead or pause while a finger is down. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add story-bars
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/story-bars.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { StoryBars } from "@/components/ui/story-bars";

export default function Example() {
  const [index, setIndex] = useState(0);

  return (
    <StoryBars
      count={5}
      index={index}
      onIndexChange={setIndex}
      onComplete={() => console.log("last story done")}
      duration={4000}
    />
  );
}
```

## Props

| Prop            | Type                       | Default | Description                                                          |
| :-------------- | :------------------------- | :------ | :------------------------------------------------------------------- |
| `count`         | `number`                   | -       | How many stories there are.                                          |
| `index`         | `number`                   | -       | The story showing now, from 0.                                       |
| `onIndexChange` | `(index: number) => void`  | -       | Called when the current story's time is up and the next should show. |
| `onComplete`    | `() => void`               | -       | Called when the last story's time is up.                             |
| `duration`      | `number`                   | `5000`  | How long each story shows, in milliseconds.                          |
| `paused`        | `boolean`                  | `false` | Holds the bar where it is, for example while a finger is down.       |
| `height`        | `number`                   | `3`     | Height of each bar.                                                  |
| `gap`           | `number`                   | `4`     | Space between the bars.                                              |
| `colors`        | `Partial<StoryBarsColors>` | -       | Overrides `track` and `fill`.                                        |
| `style`         | `StyleProp<ViewStyle>`     | -       | Style for the row.                                                   |

## Source

`components/ui/story-bars.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface StoryBarsColors {
  track: string;
  fill: string;
}

const DEFAULT_COLORS: StoryBarsColors = {
  track: "rgba(255, 255, 255, 0.35)",
  fill: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface StoryBarsProps {
  /** How many stories there are. */
  count: number;
  /** The story showing now, from 0. */
  index: number;
  /** Called when the current story's time is up and the next one should show. */
  onIndexChange: (index: number) => void;
  /** Called when the last story's time is up. */
  onComplete?: () => void;
  /** How long each story shows, in milliseconds. */
  duration?: number;
  /** Holds the bar where it is, for example while a finger is down. */
  paused?: boolean;
  /** Height of each bar. */
  height?: number;
  /** Space between the bars. */
  gap?: number;
  colors?: Partial<StoryBarsColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * The row of progress bars at the top of a story viewer. Finished stories are full, the current one
 * fills over `duration` and then asks for the next, and the rest are empty. Pausing holds the fill in
 * place and resuming carries on from there. The position is read out as "Story 2 of 5".
 */
export function StoryBars({
  count,
  index,
  onIndexChange,
  onComplete,
  duration = 5000,
  paused = false,
  height = 3,
  gap = 4,
  colors,
  style,
}: StoryBarsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  // One value per bar, and every bar stays mounted: an animated value stops itself when the view it
  // drives unmounts, so moving the fill to a different element between stories would freeze it.
  const bars = useMemo(
    () => Array.from({ length: count }, (_, i) => new Animated.Value(i < index ? 1 : 0)),
    // The starting fills only matter on mount; the effect below keeps them right from then on.
    // eslint-disable-next-line react-hooks/exhaustive-deps
    [count],
  );
  const value = useRef(0);
  const lastIndex = useRef(index);

  const live = useRef({ count, index, onIndexChange, onComplete, duration, reduceMotion });
  live.current = { count, index, onIndexChange, onComplete, duration, reduceMotion };

  useEffect(() => {
    // Finished stories are full and later ones empty; a new story starts from nothing, while a pause
    // and resume of the same story carries on from where it stopped.
    bars.forEach((bar, i) => {
      if (i < index) bar.setValue(1);
      else if (i > index) bar.setValue(0);
    });
    const current = bars[index];
    if (!current) return;
    if (lastIndex.current !== index) {
      lastIndex.current = index;
      current.setValue(0);
    }
    value.current = (current as unknown as { __getValue: () => number }).__getValue();
    const id = current.addListener(({ value: v }) => (value.current = v));
    if (paused) return () => current.removeListener(id);
    const remaining = Math.max(0, 1 - value.current) * live.current.duration;
    const animation = Animated.timing(current, {
      toValue: 1,
      duration: remaining,
      // With reduced motion the bar moves in ten steps instead of sliding.
      easing: live.current.reduceMotion ? (t: number) => Math.floor(t * 10) / 10 : Easing.linear,
      useNativeDriver: false,
    });
    animation.start(({ finished }) => {
      if (!finished) return;
      const { index: now, count: total } = live.current;
      if (now < total - 1) live.current.onIndexChange(now + 1);
      else live.current.onComplete?.();
    });
    return () => {
      animation.stop();
      current.removeListener(id);
    };
  }, [index, paused, bars, reduceMotion]);

  const label = `Story ${index + 1} of ${count}`;

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel={label}
      aria-label={label}
      accessibilityValue={{ min: 1, max: count, now: index + 1, text: label }}
      aria-valuemin={1}
      aria-valuemax={count}
      aria-valuenow={index + 1}
      aria-valuetext={label}
      style={[styles.row, { gap }, style]}
    >
      {bars.map((bar, i) => (
        <View
          key={i}
          style={[
            styles.track,
            { height, borderRadius: height / 2, backgroundColor: palette.track },
          ]}
        >
          <Animated.View
            style={[
              styles.fill,
              {
                backgroundColor: palette.fill,
                width: bar.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
              },
            ]}
          />
        </View>
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row" },
  track: { flex: 1, overflow: "hidden" },
  fill: { height: "100%" },
});
```

---

# Action Button

> A React Native button that carries its own progress, turning its label into a spinner, then a tick or a cross with a shake, without ever changing size.

Install: `npx @modus-ui/cli add action-button`

A button that carries its own progress. Press it and, if the action returns a promise, the label gives way to a spinner, then to a tick that pops in, or a cross and a shake if it fails, before it settles back to idle. The button never changes size, so nothing around it moves, the outcome is read out to screen readers, and pressing while it is busy does nothing. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add action-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/action-button.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { ActionButton } from "@/components/ui/action-button";

export default function Example() {
  return (
    <ActionButton
      label="Save changes"
      onPress={async () => {
        await fetch("/api/save", { method: "POST" });
      }}
    />
  );
}
```

## Props

| Prop           | Type                                          | Default    | Description                                                                         |
| :------------- | :-------------------------------------------- | :--------- | :---------------------------------------------------------------------------------- |
| `label`        | `string`                                      | -          | The button's text.                                                                  |
| `onPress`      | `() => void \| Promise<unknown>`              | -          | Called on press. If it returns a promise the button shows loading until it settles. |
| `status`       | `"idle" \| "loading" \| "success" \| "error"` | -          | Sets the state yourself instead of following the promise.                           |
| `variant`      | `"solid" \| "outline" \| "ghost"`             | `"solid"`  | How the button is drawn.                                                            |
| `size`         | `"md" \| "lg"`                                | `"md"`     | Height of the button.                                                               |
| `successLabel` | `string`                                      | `"Done"`   | Text announced in the success state.                                                |
| `errorLabel`   | `string`                                      | `"Failed"` | Text announced in the error state.                                                  |
| `resetAfter`   | `number`                                      | `1600`     | Milliseconds the success or error state stays before going back to idle.            |
| `disabled`     | `boolean`                                     | `false`    | Dims the button and ignores presses.                                                |
| `fullWidth`    | `boolean`                                     | `false`    | Stretches the button to the full width of its parent.                               |
| `colors`       | `Partial<ActionButtonColors>`                 | -          | Overrides `background`, `text`, `success` and `error`.                              |
| `style`        | `StyleProp<ViewStyle>`                        | -          | Style for the button's outer wrapper.                                               |

## Source

`components/ui/action-button.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export type ActionStatus = "idle" | "loading" | "success" | "error";

export interface ActionButtonColors {
  background: string;
  text: string;
  success: string;
  error: string;
}

const DEFAULT_COLORS: ActionButtonColors = {
  background: "#4f46e5",
  text: "#ffffff",
  success: "#16a34a",
  error: "#dc2626",
};

const INDEX: Record<ActionStatus, number> = { idle: 0, loading: 1, success: 2, error: 3 };

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ActionButtonProps {
  label: string;
  /** Called on press. If it returns a promise the button shows loading until it settles. */
  onPress: () => void | Promise<unknown>;
  /** Sets the state yourself instead of following the promise. */
  status?: ActionStatus;
  variant?: "solid" | "outline" | "ghost";
  size?: "md" | "lg";
  /** Text announced and shown in the success state. */
  successLabel?: string;
  /** Text announced and shown in the error state. */
  errorLabel?: string;
  /** Milliseconds the success or error state stays before the button goes back to idle. */
  resetAfter?: number;
  disabled?: boolean;
  /** Stretches the button to the full width of its parent. */
  fullWidth?: boolean;
  colors?: Partial<ActionButtonColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A button that carries its own progress. Press it and, if the action returns a promise, the label
 * gives way to a spinner, then to a tick that pops in, or a cross and a shake if it fails, before it
 * settles back. The button never changes size, so nothing around it moves, and the outcome is read
 * out. Pressing while busy does nothing.
 */
export function ActionButton({
  label,
  onPress,
  status,
  variant = "solid",
  size = "md",
  successLabel = "Done",
  errorLabel = "Failed",
  resetAfter = 1600,
  disabled = false,
  fullWidth = false,
  colors,
  style,
}: ActionButtonProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [inner, setInner] = useState<ActionStatus>("idle");
  const current = status ?? inner;
  const m = useRef(new Animated.Value(INDEX[current])).current;
  const spin = useRef(new Animated.Value(0)).current;
  const press = useRef(new Animated.Value(1)).current;
  const shake = useRef(new Animated.Value(0)).current;
  const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
  const mounted = useRef(true);

  useEffect(() => {
    mounted.current = true;
    return () => {
      mounted.current = false;
      timers.current.forEach(clearTimeout);
    };
  }, []);

  useEffect(() => {
    if (reduceMotion) m.setValue(INDEX[current]);
    else
      Animated.timing(m, {
        toValue: INDEX[current],
        duration: 220,
        useNativeDriver: false,
      }).start();
    if (current === "error" && !reduceMotion) {
      Animated.sequence(
        [-7, 7, -5, 5, -2, 0].map((toValue) =>
          Animated.timing(shake, { toValue, duration: 50, useNativeDriver: NATIVE_DRIVER }),
        ),
      ).start();
    }
  }, [current, reduceMotion, m, shake]);

  useEffect(() => {
    if (current !== "loading" || reduceMotion) {
      spin.setValue(0);
      return;
    }
    const loop = Animated.loop(
      Animated.timing(spin, {
        toValue: 1,
        duration: 750,
        easing: Easing.linear,
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [current, reduceMotion, spin]);

  const handlePress = () => {
    if (disabled || current !== "idle") return;
    const result = onPress();
    if (status !== undefined || !result || typeof (result as Promise<unknown>).then !== "function")
      return;
    setInner("loading");
    const finish = (next: ActionStatus) => {
      if (!mounted.current) return;
      setInner(next);
      timers.current.push(setTimeout(() => mounted.current && setInner("idle"), resetAfter));
    };
    (result as Promise<unknown>).then(
      () => finish("success"),
      () => finish("error"),
    );
  };

  const dip = (down: boolean) => {
    if (reduceMotion) return;
    Animated.spring(press, {
      toValue: down ? 0.97 : 1,
      stiffness: 500,
      damping: 26,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  const solid = variant === "solid";
  const ink = solid ? palette.text : palette.background;
  const idleFill = solid ? palette.background : "transparent";
  const fill = m.interpolate({
    inputRange: [0, 1, 2, 3],
    outputRange: [idleFill, idleFill, palette.success, palette.error],
  });
  const mark = (index: number) =>
    m.interpolate({
      inputRange: [index - 1, index, index + 1],
      outputRange: [0, 1, 0],
      extrapolate: "clamp",
    });
  const markInk = current === "success" || current === "error" ? palette.text : ink;
  const height = size === "lg" ? 56 : 48;
  const spoken =
    current === "loading"
      ? `${label}, working`
      : current === "success"
        ? successLabel
        : current === "error"
          ? errorLabel
          : label;

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={spoken}
      accessibilityState={{ busy: current === "loading", disabled }}
      aria-busy={current === "loading"}
      aria-disabled={disabled}
      disabled={disabled}
      onPress={handlePress}
      onPressIn={() => dip(true)}
      onPressOut={() => dip(false)}
      style={[fullWidth ? styles.full : styles.auto, style]}
    >
      <Animated.View
        style={[
          styles.button,
          {
            minHeight: height,
            borderRadius: height * 0.3,
            backgroundColor: fill,
            borderWidth: variant === "outline" ? 2 : 0,
            borderColor:
              current === "success"
                ? palette.success
                : current === "error"
                  ? palette.error
                  : palette.background,
            opacity: disabled ? 0.45 : 1,
            transform: [{ scale: press }, { translateX: shake }],
          },
        ]}
      >
        <Animated.Text
          style={[
            styles.label,
            { color: ink, opacity: mark(0), fontSize: size === "lg" ? 17 : 16 },
          ]}
          numberOfLines={1}
        >
          {label}
        </Animated.Text>
        <Animated.View pointerEvents="none" style={[styles.center, { opacity: mark(1) }]}>
          <Animated.View
            style={[
              styles.spinner,
              {
                borderColor: ink,
                borderTopColor: "transparent",
                transform: [
                  {
                    rotate: spin.interpolate({
                      inputRange: [0, 1],
                      outputRange: ["0deg", "360deg"],
                    }),
                  },
                ],
              },
            ]}
          />
        </Animated.View>
        <Animated.View
          pointerEvents="none"
          style={[
            styles.center,
            {
              opacity: mark(2),
              transform: [
                { scale: mark(2).interpolate({ inputRange: [0, 1], outputRange: [0.4, 1] }) },
              ],
            },
          ]}
        >
          <View style={[styles.tick, { borderColor: markInk }]} />
        </Animated.View>
        <Animated.View
          pointerEvents="none"
          style={[
            styles.center,
            {
              opacity: mark(3),
              transform: [
                { scale: mark(3).interpolate({ inputRange: [0, 1], outputRange: [0.4, 1] }) },
              ],
            },
          ]}
        >
          <Text style={[styles.cross, { color: markInk }]}>×</Text>
        </Animated.View>
      </Animated.View>
      <Text accessibilityLiveRegion="polite" style={styles.sr}>
        {current === "success" ? successLabel : current === "error" ? errorLabel : ""}
      </Text>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  auto: { alignSelf: "flex-start" },
  full: { alignSelf: "stretch" },
  button: {
    paddingHorizontal: 24,
    alignItems: "center",
    justifyContent: "center",
    userSelect: "none",
  },
  label: { fontWeight: "700" },
  center: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
  },
  spinner: { width: 22, height: 22, borderRadius: 11, borderWidth: 3 },
  tick: {
    width: 9,
    height: 17,
    marginTop: -3,
    borderRightWidth: 3,
    borderBottomWidth: 3,
    transform: [{ rotate: "45deg" }],
  },
  cross: { fontSize: 30, lineHeight: 32, fontWeight: "300" },
  sr: { position: "absolute", width: 1, height: 1, opacity: 0 },
});
```

---

# Spin Loader

> Four React Native loading spinners in one component, a ring, bouncing dots, rising bars and a spreading pulse, that stand still when motion is reduced.

Install: `npx @modus-ui/cli add spin-loader`

Four loading spinners in one component: a turning ring, three bouncing dots, a row of rising bars, and a pulse that spreads outward. They share one loop, mount their views once so the animation never restarts, and stand still when motion is reduced. Each reads out as a busy progress bar with your label. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add spin-loader
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/spin-loader.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { SpinLoader } from "@/components/ui/spin-loader";

export default function Example() {
  return <SpinLoader variant="dots" size={36} label="Loading messages" />;
}
```

## Props

| Prop       | Type                                    | Default     | Description                      |
| :--------- | :-------------------------------------- | :---------- | :------------------------------- |
| `variant`  | `"ring" \| "dots" \| "bars" \| "pulse"` | `"ring"`    | Which style of spinner to draw.  |
| `size`     | `number`                                | `32`        | Height and width of the spinner. |
| `duration` | `number`                                | `900`       | Milliseconds for one full cycle. |
| `label`    | `string`                                | `"Loading"` | Spoken name of the spinner.      |
| `colors`   | `Partial<SpinLoaderColors>`             | -           | Overrides `color` and `track`.   |
| `style`    | `StyleProp<ViewStyle>`                  | -           | Style for the spinner's box.     |

## Source

`components/ui/spin-loader.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export type SpinVariant = "ring" | "dots" | "bars" | "pulse";

export interface SpinLoaderColors {
  color: string;
  track: string;
}

const DEFAULT_COLORS: SpinLoaderColors = {
  color: "#4f46e5",
  track: "rgba(128, 128, 128, 0.25)",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SpinLoaderProps {
  /** Which style of spinner to draw. */
  variant?: SpinVariant;
  /** Height and width of the spinner. */
  size?: number;
  /** Milliseconds for one full cycle. */
  duration?: number;
  /** Spoken name of the spinner. */
  label?: string;
  colors?: Partial<SpinLoaderColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * Four loading spinners in one component: a turning ring, three bouncing dots, a row of rising bars,
 * and a pulse that spreads outward. They share one loop, mount their views once so the animation
 * never restarts, and stand still when motion is reduced. Each reads out as a busy progress bar.
 */
export function SpinLoader({
  variant = "ring",
  size = 32,
  duration = 900,
  label = "Loading",
  colors,
  style,
}: SpinLoaderProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const t = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    if (reduceMotion) {
      t.setValue(0);
      return;
    }
    const loop = Animated.loop(
      Animated.timing(t, {
        toValue: 1,
        duration,
        easing: variant === "ring" ? Easing.linear : Easing.inOut(Easing.quad),
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [reduceMotion, duration, variant, t]);

  // Offsets that stagger the dots and bars across the cycle.
  const phase = useMemo(() => (i: number) => i * 0.14, []);

  const body = (() => {
    if (variant === "ring") {
      return (
        <Animated.View
          style={{
            width: size,
            height: size,
            borderRadius: size / 2,
            borderWidth: Math.max(2, size / 9),
            borderColor: palette.track,
            borderTopColor: palette.color,
            transform: [
              { rotate: t.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] }) },
            ],
          }}
        />
      );
    }
    if (variant === "dots") {
      const dot = size / 4;
      return (
        <View style={[styles.row, { width: size, height: size, gap: dot * 0.6 }]}>
          {[0, 1, 2].map((i) => (
            <Animated.View
              key={i}
              style={{
                width: dot,
                height: dot,
                borderRadius: dot / 2,
                backgroundColor: palette.color,
                opacity: t.interpolate({
                  inputRange: [0, phase(i), phase(i) + 0.2, phase(i) + 0.4, 1],
                  outputRange: [0.3, 0.3, 1, 0.3, 0.3],
                }),
                transform: [
                  {
                    translateY: t.interpolate({
                      inputRange: [0, phase(i), phase(i) + 0.2, phase(i) + 0.4, 1],
                      outputRange: [0, 0, -dot * 0.7, 0, 0],
                    }),
                  },
                ],
              }}
            />
          ))}
        </View>
      );
    }
    if (variant === "bars") {
      const bar = size / 7;
      return (
        <View
          style={[styles.row, { width: size, height: size, gap: bar * 0.7, alignItems: "center" }]}
        >
          {[0, 1, 2, 3].map((i) => (
            <Animated.View
              key={i}
              style={{
                width: bar,
                height: size * 0.8,
                borderRadius: bar / 2,
                backgroundColor: palette.color,
                transform: [
                  {
                    scaleY: t.interpolate({
                      inputRange: [0, phase(i), phase(i) + 0.25, phase(i) + 0.5, 1],
                      outputRange: [0.3, 0.3, 1, 0.3, 0.3],
                    }),
                  },
                ],
              }}
            />
          ))}
        </View>
      );
    }
    return (
      <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
        <Animated.View
          style={{
            position: "absolute",
            width: size,
            height: size,
            borderRadius: size / 2,
            backgroundColor: palette.color,
            opacity: reduceMotion
              ? 0.25
              : t.interpolate({ inputRange: [0, 1], outputRange: [0.55, 0] }),
            transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.3, 1] }) }],
          }}
        />
        <View
          style={{
            width: size * 0.3,
            height: size * 0.3,
            borderRadius: size * 0.15,
            backgroundColor: palette.color,
          }}
        />
      </View>
    );
  })();

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel={label}
      aria-label={label}
      aria-busy
      accessibilityState={{ busy: true }}
      style={[{ width: size, height: size }, style]}
    >
      {body}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "flex-end", justifyContent: "center" },
});
```

---

# Radio Group

> A React Native radio group drawn as cards with a springing dot, a single tab stop and arrow-key navigation on the web.

Install: `npx @modus-ui/cli add radio-group`

A group of mutually exclusive choices drawn as cards. The selected card takes the accent colour and its dot springs in. Only the selected radio is a tab stop, and on the web the arrow keys move the selection, skipping disabled options and wrapping at the ends, as a native radio group does. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add radio-group
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/radio-group.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { RadioGroup } from "@/components/ui/radio-group";

export default function Example() {
  const [plan, setPlan] = useState("pro");

  return (
    <RadioGroup
      label="Plan"
      value={plan}
      onChange={setPlan}
      options={[
        { value: "free", label: "Free", description: "One project" },
        { value: "pro", label: "Pro", description: "Unlimited projects" },
      ]}
    />
  );
}
```

## Props

| Prop       | Type                        | Default     | Description                                                                                |
| :--------- | :-------------------------- | :---------- | :----------------------------------------------------------------------------------------- |
| `options`  | `RadioOption[]`             | -           | The choices, each with a `value`, a `label`, and an optional `description` and `disabled`. |
| `value`    | `string`                    | -           | The selected option's value.                                                               |
| `onChange` | `(value: string) => void`   | -           | Called with the new value when the selection changes.                                      |
| `label`    | `string`                    | `"Options"` | Spoken name of the group.                                                                  |
| `colors`   | `Partial<RadioGroupColors>` | -           | Overrides `accent`, `border`, `surface`, `selectedSurface`, `label` and `description`.     |
| `style`    | `StyleProp<ViewStyle>`      | -           | Style for the group's container.                                                           |

## Source

`components/ui/radio-group.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface RadioOption {
  value: string;
  label: string;
  description?: string;
  disabled?: boolean;
}

export interface RadioGroupColors {
  accent: string;
  border: string;
  surface: string;
  selectedSurface: string;
  label: string;
  description: string;
}

const DEFAULT_COLORS: RadioGroupColors = {
  accent: "#4f46e5",
  border: "#d1d5db",
  surface: "#ffffff",
  selectedSurface: "#eef2ff",
  label: "#111827",
  description: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface RadioGroupProps {
  options: RadioOption[];
  /** The selected option's value. */
  value: string;
  onChange: (value: string) => void;
  /** Spoken name of the group. */
  label?: string;
  colors?: Partial<RadioGroupColors>;
  style?: StyleProp<ViewStyle>;
}

interface RowProps {
  option: RadioOption;
  selected: boolean;
  index: number;
  count: number;
  palette: RadioGroupColors;
  reduceMotion: boolean;
  onSelect: () => void;
}

function Row({ option, selected, index, count, palette, reduceMotion, onSelect }: RowProps) {
  // Every dot stays mounted with its own value, so the spring is never cut short by an unmount.
  const dot = useRef(new Animated.Value(selected ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      dot.setValue(selected ? 1 : 0);
      return;
    }
    Animated.spring(dot, {
      toValue: selected ? 1 : 0,
      stiffness: 420,
      damping: 20,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [selected, reduceMotion, dot]);

  return (
    <Pressable
      accessibilityRole="radio"
      accessibilityLabel={option.label}
      accessibilityState={{ checked: selected, disabled: !!option.disabled }}
      accessibilityHint={option.description}
      aria-checked={selected}
      aria-disabled={!!option.disabled}
      aria-posinset={index + 1}
      aria-setsize={count}
      disabled={option.disabled}
      onPress={onSelect}
      tabIndex={selected ? 0 : -1}
      style={[
        styles.row,
        {
          borderColor: selected ? palette.accent : palette.border,
          backgroundColor: selected ? palette.selectedSurface : palette.surface,
          opacity: option.disabled ? 0.45 : 1,
        },
      ]}
    >
      <View style={[styles.ring, { borderColor: selected ? palette.accent : palette.border }]}>
        <Animated.View
          style={[
            styles.dot,
            { backgroundColor: palette.accent, opacity: dot, transform: [{ scale: dot }] },
          ]}
        />
      </View>
      <View style={styles.text}>
        <Text style={[styles.title, { color: palette.label }]}>{option.label}</Text>
        {option.description ? (
          <Text style={[styles.description, { color: palette.description }]}>
            {option.description}
          </Text>
        ) : null}
      </View>
    </Pressable>
  );
}

/**
 * A group of mutually exclusive choices drawn as cards. The selected card takes the accent colour
 * and its dot springs in. Only the selected radio is a tab stop, and on the web the arrow keys move
 * the selection, skipping disabled options and wrapping at the ends, as a native radio group does.
 */
export function RadioGroup({
  options,
  value,
  onChange,
  label = "Options",
  colors,
  style,
}: RadioGroupProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  const move = (direction: 1 | -1) => {
    const enabled = options.filter((option) => !option.disabled);
    if (enabled.length === 0) return;
    const at = enabled.findIndex((option) => option.value === value);
    const next = enabled[(at + direction + enabled.length) % enabled.length];
    onChange(next.value);
  };

  const onKeyDown = (event: { key: string; preventDefault: () => void }) => {
    if (event.key === "ArrowDown" || event.key === "ArrowRight") {
      event.preventDefault();
      move(1);
    } else if (event.key === "ArrowUp" || event.key === "ArrowLeft") {
      event.preventDefault();
      move(-1);
    }
  };

  const webKeys = { onKeyDown } as object;

  return (
    <View
      accessibilityRole="radiogroup"
      accessibilityLabel={label}
      aria-label={label}
      {...webKeys}
      style={[styles.group, style]}
    >
      {options.map((option, index) => (
        <Row
          key={option.value}
          option={option}
          index={index}
          count={options.length}
          selected={option.value === value}
          palette={palette}
          reduceMotion={reduceMotion}
          onSelect={() => onChange(option.value)}
        />
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  group: { gap: 10 },
  row: {
    flexDirection: "row",
    alignItems: "center",
    gap: 14,
    minHeight: 56,
    paddingVertical: 12,
    paddingHorizontal: 16,
    borderRadius: 16,
    borderWidth: 2,
    userSelect: "none",
  },
  ring: {
    width: 24,
    height: 24,
    borderRadius: 12,
    borderWidth: 2,
    alignItems: "center",
    justifyContent: "center",
  },
  dot: { width: 12, height: 12, borderRadius: 6 },
  text: { flex: 1, gap: 2 },
  title: { fontSize: 16, fontWeight: "600" },
  description: { fontSize: 13, lineHeight: 18 },
});
```

---

# Mode Toggle

> A React Native light and dark switch where the sun slides across, turns into a moon and the sky fills with stars.

Install: `npx @modus-ui/cli add mode-toggle`

A light and dark switch. The sun slides across the sky, its glow turns into a moon as a shadow crosses it, the day sky deepens to night and stars fade in. It reads as a switch that is on when the mode is dark, and with reduced motion it jumps between the two states. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add mode-toggle
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/mode-toggle.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { ModeToggle, type Mode } from "@/components/ui/mode-toggle";

export default function Example() {
  const [mode, setMode] = useState<Mode>("light");

  return <ModeToggle mode={mode} onChange={setMode} />;
}
```

## Props

| Prop       | Type                        | Default       | Description                                                   |
| :--------- | :-------------------------- | :------------ | :------------------------------------------------------------ |
| `mode`     | `"light" \| "dark"`         | -             | The current mode.                                             |
| `onChange` | `(mode: Mode) => void`      | -             | Called with the other mode when the switch is pressed.        |
| `size`     | `"md" \| "lg"`              | `"md"`        | Size of the switch.                                           |
| `label`    | `string`                    | `"Dark mode"` | Spoken name of the switch.                                    |
| `colors`   | `Partial<ModeToggleColors>` | -             | Overrides `dayTrack`, `nightTrack`, `sun`, `moon` and `star`. |
| `style`    | `StyleProp<ViewStyle>`      | -             | Style for the switch's outer wrapper.                         |

## Source

`components/ui/mode-toggle.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export type Mode = "light" | "dark";

export interface ModeToggleColors {
  dayTrack: string;
  nightTrack: string;
  sun: string;
  moon: string;
  star: string;
}

const DEFAULT_COLORS: ModeToggleColors = {
  dayTrack: "#7dd3fc",
  nightTrack: "#1e1b4b",
  sun: "#facc15",
  moon: "#e5e7eb",
  star: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ModeToggleProps {
  mode: Mode;
  onChange: (mode: Mode) => void;
  size?: "md" | "lg";
  /** Spoken name of the switch. */
  label?: string;
  colors?: Partial<ModeToggleColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A light and dark switch. The sun slides across the sky, its glow turns into a moon as a shadow
 * crosses it, the day sky deepens to night and stars fade in. It reads as a switch that is on when
 * the mode is dark. With reduced motion it jumps between the two states.
 */
export function ModeToggle({
  mode,
  onChange,
  size = "md",
  label = "Dark mode",
  colors,
  style,
}: ModeToggleProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const dark = mode === "dark";
  const m = useRef(new Animated.Value(dark ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) {
      m.setValue(dark ? 1 : 0);
      return;
    }
    // Colours cannot run on the native driver, so the whole toggle is driven from JS.
    Animated.timing(m, {
      toValue: dark ? 1 : 0,
      duration: 380,
      easing: Easing.inOut(Easing.cubic),
      useNativeDriver: false,
    }).start();
  }, [dark, reduceMotion, m]);

  const height = size === "lg" ? 44 : 36;
  const width = height * 2;
  const pad = 4;
  const thumb = height - pad * 2;

  const track = m.interpolate({
    inputRange: [0, 1],
    outputRange: [palette.dayTrack, palette.nightTrack],
  });
  const body = m.interpolate({ inputRange: [0, 1], outputRange: [palette.sun, palette.moon] });
  const x = m.interpolate({ inputRange: [0, 1], outputRange: [pad, width - thumb - pad] });
  const shadowX = m.interpolate({ inputRange: [0, 1], outputRange: [thumb, thumb * 0.35] });
  const stars = m.interpolate({ inputRange: [0, 0.6, 1], outputRange: [0, 0, 1] });

  const star = (left: number, top: number, s: number) => (
    <Animated.View
      key={`${left}-${top}`}
      style={{
        position: "absolute",
        left,
        top,
        width: s,
        height: s,
        borderRadius: s / 2,
        backgroundColor: palette.star,
        opacity: stars,
      }}
    />
  );

  return (
    <Pressable
      accessibilityRole="switch"
      accessibilityLabel={label}
      accessibilityState={{ checked: dark }}
      aria-checked={dark}
      onPress={() => onChange(dark ? "light" : "dark")}
      style={[styles.hit, style]}
    >
      <Animated.View
        style={[styles.track, { width, height, borderRadius: height / 2, backgroundColor: track }]}
      >
        {star(height * 0.3, height * 0.28, 3)}
        {star(height * 0.55, height * 0.6, 2)}
        {star(height * 0.8, height * 0.22, 2)}
        <Animated.View
          style={[
            styles.thumb,
            {
              width: thumb,
              height: thumb,
              borderRadius: thumb / 2,
              backgroundColor: body,
              transform: [{ translateX: x }],
            },
          ]}
        >
          <Animated.View
            style={{
              position: "absolute",
              top: -thumb * 0.1,
              width: thumb,
              height: thumb,
              borderRadius: thumb / 2,
              backgroundColor: track,
              transform: [{ translateX: shadowX }],
            }}
          />
        </Animated.View>
      </Animated.View>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  hit: { alignSelf: "flex-start", userSelect: "none" },
  track: { justifyContent: "center", overflow: "hidden" },
  thumb: { position: "absolute", top: 4, overflow: "hidden" },
});
```

---

# Tip Popover

> A React Native tip that points at its trigger, springs out from the arrow and closes on an outside tap or Escape.

Install: `npx @modus-ui/cli add tip-popover`

A small tip that points at its trigger. It is drawn inside its parent rather than in a Modal, so it stays within a screen, and it springs out from the arrow. Tapping anywhere else closes it, and on the web so does Escape. The tip is announced when it opens. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add tip-popover
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/tip-popover.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { Pressable, Text } from "react-native";
import { TipPopover } from "@/components/ui/tip-popover";

export default function Example() {
  const [open, setOpen] = useState(false);

  return (
    <TipPopover open={open} onClose={() => setOpen(false)} content="Anyone with the link can view.">
      <Pressable onPress={() => setOpen(!open)}>
        <Text>Share</Text>
      </Pressable>
    </TipPopover>
  );
}
```

## Props

| Prop        | Type                        | Default | Description                                 |
| :---------- | :-------------------------- | :------ | :------------------------------------------ |
| `open`      | `boolean`                   | -       | Whether the tip is showing.                 |
| `onClose`   | `() => void`                | -       | Called on an outside tap or Escape.         |
| `content`   | `string`                    | -       | The tip's text.                             |
| `placement` | `"top" \| "bottom"`         | `"top"` | Which side of the trigger the tip opens on. |
| `colors`    | `Partial<TipPopoverColors>` | -       | Overrides `background` and `text`.          |
| `style`     | `StyleProp<ViewStyle>`      | -       | Style for the wrapper around the trigger.   |

## Source

`components/ui/tip-popover.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const WIDTH = 220;
const GAP = 10;

export interface TipPopoverColors {
  background: string;
  text: string;
}

const DEFAULT_COLORS: TipPopoverColors = {
  background: "#111827",
  text: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface TipPopoverProps {
  open: boolean;
  onClose: () => void;
  /** The tip's text. */
  content: string;
  /** The element the tip points at. */
  children: ReactNode;
  /** Which side of the trigger the tip opens on. */
  placement?: "top" | "bottom";
  colors?: Partial<TipPopoverColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A small tip that points at its trigger. It is drawn inside its parent rather than in a Modal, so it
 * stays within a screen, and it springs out from the arrow. Tapping anywhere else closes it, and on
 * the web so does Escape. The tip is announced when it opens.
 */
export function TipPopover({
  open,
  onClose,
  content,
  children,
  placement = "top",
  colors,
  style,
}: TipPopoverProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const t = useRef(new Animated.Value(0)).current;
  const [mounted, setMounted] = useState(open);
  const [triggerWidth, setTriggerWidth] = useState(0);
  const top = placement === "top";

  const live = useRef({ onClose });
  live.current = { onClose };

  useEffect(() => {
    if (open) setMounted(true);
    if (reduceMotion) {
      t.setValue(open ? 1 : 0);
      if (!open) setMounted(false);
      return;
    }
    Animated.spring(t, {
      toValue: open ? 1 : 0,
      stiffness: 380,
      damping: 26,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start(({ finished }) => {
      if (finished && !open) setMounted(false);
    });
  }, [open, reduceMotion, t]);

  useEffect(() => {
    if (open) AccessibilityInfo.announceForAccessibility(content);
  }, [open, content]);

  useEffect(() => {
    if (!open || Platform.OS !== "web") return;
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape") live.current.onClose();
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [open]);

  return (
    <View style={[styles.root, style]}>
      <View
        onLayout={(event: LayoutChangeEvent) => setTriggerWidth(event.nativeEvent.layout.width)}
      >
        {children}
      </View>
      {mounted ? (
        <>
          {open ? <Pressable accessible={false} onPress={onClose} style={styles.backdrop} /> : null}
          <Animated.View
            role="tooltip"
            accessibilityLiveRegion="polite"
            pointerEvents="none"
            style={[
              styles.holder,
              top ? { bottom: "100%", marginBottom: GAP } : { top: "100%", marginTop: GAP },
              {
                left: (triggerWidth - WIDTH) / 2,
                opacity: t,
                transform: [
                  {
                    translateY: t.interpolate({
                      inputRange: [0, 1],
                      outputRange: [top ? 6 : -6, 0],
                    }),
                  },
                  { scale: t.interpolate({ inputRange: [0, 1], outputRange: [0.92, 1] }) },
                ],
              },
            ]}
          >
            {!top ? (
              <View
                style={[styles.arrow, styles.arrowTop, { backgroundColor: palette.background }]}
              />
            ) : null}
            <View style={[styles.bubble, { backgroundColor: palette.background }]}>
              <Text style={[styles.text, { color: palette.text }]}>{content}</Text>
            </View>
            {top ? (
              <View
                style={[styles.arrow, styles.arrowBottom, { backgroundColor: palette.background }]}
              />
            ) : null}
          </Animated.View>
        </>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  root: { alignSelf: "flex-start", position: "relative" },
  // Large enough to catch a tap anywhere on the screen around the trigger.
  backdrop: { position: "absolute", top: -2000, left: -2000, width: 4400, height: 4400 },
  holder: { position: "absolute", width: WIDTH, alignItems: "center", zIndex: 10 },
  bubble: { paddingVertical: 10, paddingHorizontal: 14, borderRadius: 12 },
  text: { fontSize: 14, lineHeight: 20, textAlign: "center" },
  arrow: { width: 12, height: 12, transform: [{ rotate: "45deg" }] },
  arrowBottom: { marginTop: -6 },
  arrowTop: { marginBottom: -6 },
});
```

---

# Data Table

> A React Native table with sortable columns, a header that stays put while rows scroll and sideways scrolling for wide columns.

Install: `npx @modus-ui/cli add data-table`

A table that scrolls sideways when its columns are wider than the screen and keeps its header visible while the rows scroll up and down. Tapping a sortable header sorts by it, then reverses, and the arrow turns to match. Headers report their sort order to screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add data-table
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/data-table.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { DataTable } from "@/components/ui/data-table";

const rows = [
  { id: "1", name: "Maya", score: 92 },
  { id: "2", name: "Jon", score: 78 },
];

export default function Example() {
  return (
    <DataTable
      rows={rows}
      rowKey={(row) => row.id}
      columns={[
        { key: "name", title: "Name", sortable: true },
        { key: "score", title: "Score", align: "right", sortable: true },
      ]}
    />
  );
}
```

## Props

| Prop          | Type                                          | Default | Description                                                                           |
| :------------ | :-------------------------------------------- | :------ | :------------------------------------------------------------------------------------ |
| `columns`     | `DataTableColumn<T>[]`                        | -       | Each column's `key`, `title`, and optional `width`, `align`, `sortable` and `render`. |
| `rows`        | `T[]`                                         | -       | The data to show.                                                                     |
| `rowKey`      | `(row: T) => string`                          | -       | Returns a unique key for a row.                                                       |
| `initialSort` | `{ key: string; direction: "asc" \| "desc" }` | -       | Column key and direction to sort by at first.                                         |
| `onRowPress`  | `(row: T) => void`                            | -       | Called when a row is pressed.                                                         |
| `striped`     | `boolean`                                     | `true`  | Shades every other row.                                                               |
| `maxHeight`   | `number`                                      | `280`   | Height of the rows area; the header stays above it.                                   |
| `colors`      | `Partial<DataTableColors>`                    | -       | Overrides `header`, `headerText`, `text`, `border`, `stripe` and `background`.        |
| `style`       | `StyleProp<ViewStyle>`                        | -       | Style for the table's frame.                                                          |

## Source

`components/ui/data-table.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  ScrollView,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const DEFAULT_WIDTH = 120;
const NATIVE_DRIVER = Platform.OS !== "web";

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

// The arrow stays mounted and turns between ascending and descending.
function SortArrow({ direction, color }: { direction: "asc" | "desc"; color: string }) {
  const reduceMotion = useReduceMotion();
  const turn = useRef(new Animated.Value(direction === "asc" ? 0 : 1)).current;
  useEffect(() => {
    const toValue = direction === "asc" ? 0 : 1;
    if (reduceMotion) turn.setValue(toValue);
    else Animated.timing(turn, { toValue, duration: 180, useNativeDriver: NATIVE_DRIVER }).start();
  }, [direction, reduceMotion, turn]);
  return (
    <Animated.Text
      style={{
        color,
        fontSize: 13,
        fontWeight: "700",
        transform: [
          { rotate: turn.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "180deg"] }) },
        ],
      }}
    >
      ↑
    </Animated.Text>
  );
}

export interface DataTableColumn<T> {
  key: keyof T & string;
  title: string;
  width?: number;
  align?: "left" | "right";
  sortable?: boolean;
  render?: (row: T) => ReactNode;
}

export interface DataTableColors {
  header: string;
  headerText: string;
  text: string;
  border: string;
  stripe: string;
  background: string;
}

const DEFAULT_COLORS: DataTableColors = {
  header: "#f3f4f6",
  headerText: "#374151",
  text: "#111827",
  border: "#e5e7eb",
  stripe: "#f9fafb",
  background: "#ffffff",
};

export interface DataTableProps<T> {
  columns: DataTableColumn<T>[];
  rows: T[];
  /** Returns a unique key for a row. */
  rowKey: (row: T) => string;
  /** Column key and direction to sort by at first. */
  initialSort?: { key: string; direction: "asc" | "desc" };
  onRowPress?: (row: T) => void;
  /** Shades every other row. */
  striped?: boolean;
  /** Height of the rows area; the header stays above it while the rows scroll. */
  maxHeight?: number;
  colors?: Partial<DataTableColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A table that scrolls sideways when its columns are wider than the screen and keeps its header
 * visible while the rows scroll up and down. Tapping a sortable header sorts by it, then reverses,
 * and the arrow turns to match. Headers report their sort order to screen readers.
 */
export function DataTable<T>({
  columns,
  rows,
  rowKey,
  initialSort,
  onRowPress,
  striped = true,
  maxHeight = 280,
  colors,
  style,
}: DataTableProps<T>) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const [sort, setSort] = useState(initialSort);

  const sorted = useMemo(() => {
    if (!sort) return rows;
    const key = sort.key as keyof T;
    const sign = sort.direction === "asc" ? 1 : -1;
    return [...rows].sort((a, b) => {
      const x = a[key];
      const y = b[key];
      if (typeof x === "number" && typeof y === "number") return (x - y) * sign;
      return String(x).localeCompare(String(y)) * sign;
    });
  }, [rows, sort]);

  const toggle = (key: string) =>
    setSort((now) =>
      now?.key === key
        ? { key, direction: now.direction === "asc" ? "desc" : "asc" }
        : { key, direction: "asc" },
    );

  const total = columns.reduce((sum, column) => sum + (column.width ?? DEFAULT_WIDTH), 0);

  return (
    <View
      style={[
        styles.root,
        { borderColor: palette.border, backgroundColor: palette.background },
        style,
      ]}
    >
      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
        <View style={{ minWidth: total }}>
          <View
            accessibilityRole="header"
            style={[styles.row, { backgroundColor: palette.header }]}
          >
            {columns.map((column) => {
              const active = sort?.key === column.key;
              const direction = active ? sort.direction : undefined;
              const cell = (
                <View style={[styles.head, column.align === "right" && styles.headRight]}>
                  <Text numberOfLines={1} style={[styles.headText, { color: palette.headerText }]}>
                    {column.title}
                  </Text>
                  {direction ? (
                    <SortArrow direction={direction} color={palette.headerText} />
                  ) : null}
                </View>
              );
              const box = { width: column.width ?? DEFAULT_WIDTH };
              return column.sortable ? (
                <Pressable
                  key={column.key}
                  accessibilityRole="button"
                  accessibilityLabel={`Sort by ${column.title}`}
                  aria-sort={
                    direction === "asc" ? "ascending" : direction === "desc" ? "descending" : "none"
                  }
                  onPress={() => toggle(column.key)}
                  style={[styles.cell, box]}
                >
                  {cell}
                </Pressable>
              ) : (
                <View key={column.key} style={[styles.cell, box]}>
                  {cell}
                </View>
              );
            })}
          </View>
          <ScrollView style={{ maxHeight }} nestedScrollEnabled>
            {sorted.map((row, index) => (
              <Pressable
                key={rowKey(row)}
                accessibilityRole={onRowPress ? "button" : undefined}
                disabled={!onRowPress}
                onPress={() => onRowPress?.(row)}
                style={[
                  styles.row,
                  { borderTopColor: palette.border, borderTopWidth: StyleSheet.hairlineWidth },
                  striped && index % 2 === 1 && { backgroundColor: palette.stripe },
                ]}
              >
                {columns.map((column) => (
                  <View
                    key={column.key}
                    style={[styles.cell, { width: column.width ?? DEFAULT_WIDTH }]}
                  >
                    {column.render ? (
                      column.render(row)
                    ) : (
                      <Text
                        numberOfLines={1}
                        style={[
                          styles.text,
                          { color: palette.text },
                          column.align === "right" && styles.right,
                        ]}
                      >
                        {String(row[column.key])}
                      </Text>
                    )}
                  </View>
                ))}
              </Pressable>
            ))}
          </ScrollView>
        </View>
      </ScrollView>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { borderWidth: 1, borderRadius: 14, overflow: "hidden" },
  row: { flexDirection: "row" },
  cell: { minHeight: 44, paddingHorizontal: 12, justifyContent: "center", userSelect: "none" },
  head: { flexDirection: "row", alignItems: "center", gap: 4 },
  headRight: { justifyContent: "flex-end" },
  headText: { fontSize: 13, fontWeight: "700" },
  text: { fontSize: 14 },
  right: { textAlign: "right" },
});
```

---

# Wave Bars

> A React Native audio waveform made of bars that swell out of step while playing and tint as they are played.

Install: `npx @modus-ui/cli add wave-bars`

A row of bars drawn like an audio waveform. At rest they keep their recorded shape. While `playing` each bar swells and settles out of step with its neighbours, and `progress` tints the bars already played. With reduced motion the bars hold still. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add wave-bars
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/wave-bars.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { WaveBars } from "@/components/ui/wave-bars";

export default function Example() {
  return <WaveBars playing progress={0.4} />;
}
```

## Props

| Prop       | Type                      | Default      | Description                                     |
| :--------- | :------------------------ | :----------- | :---------------------------------------------- |
| `playing`  | `boolean`                 | `false`      | Makes the bars dance.                           |
| `count`    | `number`                  | `24`         | How many bars to draw.                          |
| `height`   | `number`                  | `40`         | Height of the tallest bar.                      |
| `progress` | `number`                  | `0`          | Colours the bars up to this fraction as played. |
| `label`    | `string`                  | `"Waveform"` | Spoken name of the waveform.                    |
| `colors`   | `Partial<WaveBarsColors>` | -            | Overrides `bar` and `played`.                   |
| `style`    | `StyleProp<ViewStyle>`    | -            | Style for the row of bars.                      |

## Source

`components/ui/wave-bars.tsx`

```tsx
import { useEffect, useMemo, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface WaveBarsColors {
  bar: string;
  played: string;
}

const DEFAULT_COLORS: WaveBarsColors = {
  bar: "#c7d2fe",
  played: "#4f46e5",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface WaveBarsProps {
  /** Makes the bars dance. */
  playing?: boolean;
  /** How many bars to draw. */
  count?: number;
  /** Height of the tallest bar. */
  height?: number;
  /** Colours the bars up to this fraction, from 0 to 1, as already played. */
  progress?: number;
  /** Spoken name of the waveform. */
  label?: string;
  colors?: Partial<WaveBarsColors>;
  style?: StyleProp<ViewStyle>;
}

// A fixed, repeatable shape so the bars look like a recording rather than noise.
const shape = (i: number) => 0.35 + 0.65 * Math.abs(Math.sin(i * 1.7) * Math.cos(i * 0.6));

/**
 * A row of bars drawn like an audio waveform. At rest they keep their recorded shape. While
 * `playing` each bar swells and settles out of step with its neighbours, and `progress` tints the
 * bars already played. With reduced motion the bars hold still.
 */
export function WaveBars({
  playing = false,
  count = 24,
  height = 40,
  progress = 0,
  label = "Waveform",
  colors,
  style,
}: WaveBarsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const t = useRef(new Animated.Value(0)).current;
  const items = useMemo(() => Array.from({ length: count }, (_, i) => i), [count]);

  useEffect(() => {
    if (!playing || reduceMotion) {
      t.setValue(0);
      return;
    }
    const loop = Animated.loop(
      Animated.timing(t, {
        toValue: 1,
        duration: 900,
        easing: Easing.linear,
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [playing, reduceMotion, t]);

  return (
    <View
      accessible
      accessibilityRole="image"
      accessibilityLabel={label}
      aria-label={label}
      style={[styles.row, { height }, style]}
    >
      {items.map((i) => {
        const base = shape(i);
        const start = (i % 6) / 6;
        const scale = t.interpolate({
          inputRange: [0, start, Math.min(1, start + 0.3), 1],
          outputRange: [1, 1, 0.45, 1],
          extrapolate: "clamp",
        });
        return (
          <Animated.View
            key={i}
            style={{
              flex: 1,
              height: height * base,
              borderRadius: 3,
              backgroundColor: i / count < progress ? palette.played : palette.bar,
              transform: [{ scaleY: scale }],
            }}
          />
        );
      })}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 3 },
});
```

---

# Page Dots

> React Native pager dots where the current page stretches into a pill and every dot can be tapped to jump.

Install: `npx @modus-ui/cli add page-dots`

The row of dots under a pager. The current page's dot stretches into a pill and takes the accent colour while the others shrink back to circles. Give it `onIndexChange` and the dots become buttons. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add page-dots
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/page-dots.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { PageDots } from "@/components/ui/page-dots";

export default function Example() {
  const [index, setIndex] = useState(0);

  return <PageDots count={4} index={index} onIndexChange={setIndex} />;
}
```

## Props

| Prop            | Type                      | Default | Description                                           |
| :-------------- | :------------------------ | :------ | :---------------------------------------------------- |
| `count`         | `number`                  | -       | How many pages there are.                             |
| `index`         | `number`                  | -       | The page showing now, from 0.                         |
| `onIndexChange` | `(index: number) => void` | -       | Makes each dot tappable and calls this with its page. |
| `dotSize`       | `number`                  | `8`     | Diameter of a dot.                                    |
| `colors`        | `Partial<PageDotsColors>` | -       | Overrides `active` and `inactive`.                    |
| `style`         | `StyleProp<ViewStyle>`    | -       | Style for the row of dots.                            |

## Source

`components/ui/page-dots.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Pressable,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface PageDotsColors {
  active: string;
  inactive: string;
}

const DEFAULT_COLORS: PageDotsColors = {
  active: "#4f46e5",
  inactive: "#d1d5db",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface PageDotsProps {
  /** How many pages there are. */
  count: number;
  /** The page showing now, from 0. */
  index: number;
  /** Makes each dot tappable and calls this with the page it stands for. */
  onIndexChange?: (index: number) => void;
  /** Diameter of a dot. */
  dotSize?: number;
  colors?: Partial<PageDotsColors>;
  style?: StyleProp<ViewStyle>;
}

interface DotProps {
  active: boolean;
  size: number;
  page: number;
  count: number;
  palette: PageDotsColors;
  reduceMotion: boolean;
  onPress?: () => void;
}

function Dot({ active, size, page, count, palette, reduceMotion, onPress }: DotProps) {
  const grow = useRef(new Animated.Value(active ? 1 : 0)).current;

  useEffect(() => {
    if (reduceMotion) grow.setValue(active ? 1 : 0);
    else
      Animated.timing(grow, {
        toValue: active ? 1 : 0,
        duration: 220,
        useNativeDriver: false,
      }).start();
  }, [active, reduceMotion, grow]);

  return (
    <Pressable
      accessibilityRole={onPress ? "button" : undefined}
      accessibilityLabel={`Page ${page + 1} of ${count}`}
      accessibilityState={{ selected: active }}
      aria-current={active ? "step" : undefined}
      disabled={!onPress}
      hitSlop={6}
      onPress={onPress}
    >
      <Animated.View
        style={{
          height: size,
          borderRadius: size / 2,
          width: grow.interpolate({ inputRange: [0, 1], outputRange: [size, size * 3] }),
          backgroundColor: grow.interpolate({
            inputRange: [0, 1],
            outputRange: [palette.inactive, palette.active],
          }),
        }}
      />
    </Pressable>
  );
}

/**
 * The row of dots under a pager. The current page's dot stretches into a pill and takes the accent
 * colour while the others shrink back to circles. Give it `onIndexChange` and the dots become buttons.
 */
export function PageDots({
  count,
  index,
  onIndexChange,
  dotSize = 8,
  colors,
  style,
}: PageDotsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  return (
    <View
      accessible
      accessibilityLabel={`Page ${index + 1} of ${count}`}
      aria-label={`Page ${index + 1} of ${count}`}
      style={[styles.row, { gap: dotSize * 0.75 }, style]}
    >
      {Array.from({ length: count }, (_, i) => (
        <Dot
          key={i}
          page={i}
          count={count}
          active={i === index}
          size={dotSize}
          palette={palette}
          reduceMotion={reduceMotion}
          onPress={onIndexChange ? () => onIndexChange(i) : undefined}
        />
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", alignSelf: "center" },
});
```

---

# Password Meter

> A React Native strength meter whose four bars fill and change colour as a password gets stronger.

Install: `npx @modus-ui/cli add password-meter`

Four bars that fill and change colour as a password gets stronger, with the verdict beside them. The rating looks at length and how many kinds of character are mixed. It is a hint, not a guarantee, and the verdict is read out whenever it changes. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add password-meter
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/password-meter.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { TextInput } from "react-native";
import { PasswordMeter } from "@/components/ui/password-meter";

export default function Example() {
  const [password, setPassword] = useState("");

  return (
    <>
      <TextInput value={password} onChangeText={setPassword} secureTextEntry />
      <PasswordMeter value={password} />
    </>
  );
}
```

## Props

| Prop        | Type                           | Default | Description                                                     |
| :---------- | :----------------------------- | :------ | :-------------------------------------------------------------- |
| `value`     | `string`                       | -       | The password to rate.                                           |
| `showLabel` | `boolean`                      | `true`  | Shows the strength as a word beside the bars.                   |
| `colors`    | `Partial<PasswordMeterColors>` | -       | Overrides `track`, `weak`, `fair`, `good`, `strong` and `text`. |
| `style`     | `StyleProp<ViewStyle>`         | -       | Style for the meter's row.                                      |

## Source

`components/ui/password-meter.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface PasswordMeterColors {
  track: string;
  weak: string;
  fair: string;
  good: string;
  strong: string;
  text: string;
}

const DEFAULT_COLORS: PasswordMeterColors = {
  track: "#e5e7eb",
  weak: "#dc2626",
  fair: "#f59e0b",
  good: "#84cc16",
  strong: "#16a34a",
  text: "#374151",
};

const NAMES = ["Too short", "Weak", "Fair", "Good", "Strong"];

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

/** Scores a password from 0 to 4 on its length and the kinds of characters it mixes. */
export function scorePassword(value: string) {
  if (value.length < 6) return 0;
  const kinds = [/[a-z]/, /[A-Z]/, /\d/, /[^A-Za-z0-9]/].filter((re) => re.test(value)).length;
  const length = value.length >= 12 ? 2 : value.length >= 8 ? 1 : 0;
  return Math.max(1, Math.min(4, Math.floor((kinds + length) / 1.5)));
}

export interface PasswordMeterProps {
  /** The password to rate. */
  value: string;
  /** Shows the strength as a word beside the bars. */
  showLabel?: boolean;
  colors?: Partial<PasswordMeterColors>;
  style?: StyleProp<ViewStyle>;
}

function Segment({
  lit,
  color,
  track,
  reduceMotion,
}: {
  lit: boolean;
  color: string;
  track: string;
  reduceMotion: boolean;
}) {
  const fill = useRef(new Animated.Value(lit ? 1 : 0)).current;
  useEffect(() => {
    if (reduceMotion) fill.setValue(lit ? 1 : 0);
    else
      Animated.timing(fill, {
        toValue: lit ? 1 : 0,
        duration: 200,
        useNativeDriver: false,
      }).start();
  }, [lit, reduceMotion, fill]);
  return (
    <View style={[styles.segment, { backgroundColor: track }]}>
      <Animated.View
        style={[
          styles.fill,
          {
            backgroundColor: color,
            width: fill.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
          },
        ]}
      />
    </View>
  );
}

/**
 * Four bars that fill and change colour as a password gets stronger, with the verdict beside them.
 * The rating looks at length and how many kinds of character are mixed. It is a hint, not a guarantee,
 * and the verdict is read out whenever it changes.
 */
export function PasswordMeter({ value, showLabel = true, colors, style }: PasswordMeterProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const score = value ? scorePassword(value) : 0;
  const tint = [palette.weak, palette.weak, palette.fair, palette.good, palette.strong][score];
  const name = value ? NAMES[score] : "Enter a password";

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel="Password strength"
      accessibilityValue={{ min: 0, max: 4, now: score, text: name }}
      aria-label="Password strength"
      aria-valuemin={0}
      aria-valuemax={4}
      aria-valuenow={score}
      aria-valuetext={name}
      style={[styles.row, style]}
    >
      <View style={styles.bars}>
        {[1, 2, 3, 4].map((n) => (
          <Segment
            key={n}
            lit={n <= score}
            color={tint}
            track={palette.track}
            reduceMotion={reduceMotion}
          />
        ))}
      </View>
      {showLabel ? (
        <Text
          accessibilityLiveRegion="polite"
          style={[styles.label, { color: value ? tint : palette.text }]}
        >
          {name}
        </Text>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 12 },
  bars: { flex: 1, flexDirection: "row", gap: 4 },
  segment: { flex: 1, height: 6, borderRadius: 3, overflow: "hidden" },
  fill: { height: "100%" },
  label: { minWidth: 72, fontSize: 13, fontWeight: "700", textAlign: "right" },
});
```

---

# Timeline List

> A React Native vertical timeline with completed, current and upcoming steps and a pulsing dot on the step in progress.

Install: `npx @modus-ui/cli add timeline-list`

A vertical list of events joined by a line. Finished steps are green, the current step has a dot that pulses outward, and later steps are muted. Each row reads out its status, so progress does not depend on colour alone. With reduced motion the pulse stands still. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add timeline-list
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/timeline-list.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { TimelineList } from "@/components/ui/timeline-list";

export default function Example() {
  return (
    <TimelineList
      items={[
        { id: "1", title: "Order placed", time: "9:02", status: "done" },
        { id: "2", title: "Out for delivery", status: "current" },
        { id: "3", title: "Delivered", status: "upcoming" },
      ]}
    />
  );
}
```

## Props

| Prop     | Type                          | Default | Description                                                                            |
| :------- | :---------------------------- | :------ | :------------------------------------------------------------------------------------- |
| `items`  | `TimelineItem[]`              | -       | The steps, each with an `id`, `title`, `status` and optional `description` and `time`. |
| `colors` | `Partial<TimelineListColors>` | -       | Overrides `line`, `done`, `current`, `upcoming`, `title` and `description`.            |
| `style`  | `StyleProp<ViewStyle>`        | -       | Style for the list.                                                                    |

## Source

`components/ui/timeline-list.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const DOT = 16;

export interface TimelineItem {
  id: string;
  title: string;
  description?: string;
  /** Shown beside the title, such as a time or date. */
  time?: string;
  status: "done" | "current" | "upcoming";
}

export interface TimelineListColors {
  line: string;
  done: string;
  current: string;
  upcoming: string;
  title: string;
  description: string;
}

const DEFAULT_COLORS: TimelineListColors = {
  line: "#e5e7eb",
  done: "#16a34a",
  current: "#4f46e5",
  upcoming: "#d1d5db",
  title: "#111827",
  description: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface TimelineListProps {
  items: TimelineItem[];
  colors?: Partial<TimelineListColors>;
  style?: StyleProp<ViewStyle>;
}

function Pulse({ color, reduceMotion }: { color: string; reduceMotion: boolean }) {
  const t = useRef(new Animated.Value(0)).current;
  useEffect(() => {
    if (reduceMotion) {
      t.setValue(0);
      return;
    }
    const loop = Animated.loop(
      Animated.timing(t, {
        toValue: 1,
        duration: 1400,
        easing: Easing.out(Easing.quad),
        useNativeDriver: NATIVE_DRIVER,
      }),
    );
    loop.start();
    return () => loop.stop();
  }, [reduceMotion, t]);
  return (
    <Animated.View
      pointerEvents="none"
      style={{
        position: "absolute",
        width: DOT,
        height: DOT,
        borderRadius: DOT / 2,
        backgroundColor: color,
        opacity: t.interpolate({ inputRange: [0, 1], outputRange: [0.45, 0] }),
        transform: [{ scale: t.interpolate({ inputRange: [0, 1], outputRange: [1, 2.4] }) }],
      }}
    />
  );
}

/**
 * A vertical list of events joined by a line. Finished steps are green, the current step has a dot
 * that pulses outward, and later steps are muted. Each row reads out its status, so the progress does
 * not depend on colour alone. With reduced motion the pulse stands still.
 */
export function TimelineList({ items, colors, style }: TimelineListProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const status = { done: "Completed", current: "In progress", upcoming: "Upcoming" };

  return (
    <View accessibilityRole="list" style={style}>
      {items.map((item, index) => {
        const tint = palette[item.status];
        const last = index === items.length - 1;
        return (
          <View
            key={item.id}
            accessible
            accessibilityRole="text"
            accessibilityLabel={`${item.title}, ${status[item.status]}${item.time ? `, ${item.time}` : ""}`}
            style={styles.row}
          >
            <View style={styles.rail}>
              <View style={styles.dotBox}>
                {item.status === "current" ? (
                  <Pulse color={tint} reduceMotion={reduceMotion} />
                ) : null}
                <View
                  style={[
                    styles.dot,
                    item.status === "upcoming"
                      ? { borderWidth: 2, borderColor: tint, backgroundColor: "transparent" }
                      : { backgroundColor: tint },
                  ]}
                />
              </View>
              {last ? null : (
                <View
                  style={[
                    styles.line,
                    { backgroundColor: item.status === "done" ? palette.done : palette.line },
                  ]}
                />
              )}
            </View>
            <View style={[styles.body, last && styles.lastBody]}>
              <View style={styles.head}>
                <Text
                  style={[
                    styles.title,
                    { color: item.status === "upcoming" ? palette.description : palette.title },
                  ]}
                >
                  {item.title}
                </Text>
                {item.time ? (
                  <Text style={[styles.time, { color: palette.description }]}>{item.time}</Text>
                ) : null}
              </View>
              {item.description ? (
                <Text style={[styles.description, { color: palette.description }]}>
                  {item.description}
                </Text>
              ) : null}
            </View>
          </View>
        );
      })}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", gap: 14 },
  rail: { width: DOT, alignItems: "center" },
  dotBox: { width: DOT, height: DOT, marginTop: 3, alignItems: "center", justifyContent: "center" },
  dot: { width: DOT, height: DOT, borderRadius: DOT / 2 },
  line: { flex: 1, width: 2, marginVertical: 4 },
  body: { flex: 1, gap: 2, paddingBottom: 22 },
  lastBody: { paddingBottom: 0 },
  head: { flexDirection: "row", justifyContent: "space-between", gap: 8 },
  title: { flex: 1, fontSize: 16, fontWeight: "600" },
  time: { fontSize: 13 },
  description: { fontSize: 14, lineHeight: 20 },
});
```

---

# Empty State

> A React Native empty list placeholder with a floating badge, a message and an optional action button.

Install: `npx @modus-ui/cli add empty-state`

What to show when a list has nothing in it yet. A badge with a glyph floats gently above a title, a short message and an optional button, and the whole block rises into place when it appears. With reduced motion it appears already in place and the badge stays still. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add empty-state
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/empty-state.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { EmptyState } from "@/components/ui/empty-state";

export default function Example() {
  return (
    <EmptyState
      title="No messages yet"
      message="When someone writes to you, it will show up here."
      actionLabel="Send a message"
      onAction={() => {}}
    />
  );
}
```

## Props

| Prop          | Type                        | Default | Description                                                       |
| :------------ | :-------------------------- | :------ | :---------------------------------------------------------------- |
| `title`       | `string`                    | -       | The headline.                                                     |
| `message`     | `string`                    | -       | A short explanation under the title.                              |
| `icon`        | `string`                    | `"📭"`  | A single glyph or emoji drawn in the badge.                       |
| `actionLabel` | `string`                    | -       | Label of the button; leave it out for no button.                  |
| `onAction`    | `() => void`                | -       | Called when the button is pressed.                                |
| `colors`      | `Partial<EmptyStateColors>` | -       | Overrides `badge`, `title`, `message`, `button` and `buttonText`. |
| `style`       | `StyleProp<ViewStyle>`      | -       | Style for the block.                                              |

## Source

`components/ui/empty-state.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface EmptyStateColors {
  badge: string;
  title: string;
  message: string;
  button: string;
  buttonText: string;
}

const DEFAULT_COLORS: EmptyStateColors = {
  badge: "#eef2ff",
  title: "#111827",
  message: "#6b7280",
  button: "#4f46e5",
  buttonText: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface EmptyStateProps {
  title: string;
  message?: string;
  /** A single glyph or emoji drawn in the badge. */
  icon?: string;
  /** Label of the button under the message; leave it out for no button. */
  actionLabel?: string;
  onAction?: () => void;
  colors?: Partial<EmptyStateColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * What to show when a list has nothing in it yet. A badge with a glyph floats gently above a title,
 * a short message and an optional button, and the whole block rises into place when it appears.
 * With reduced motion it appears already in place and the badge stays still.
 */
export function EmptyState({
  title,
  message,
  icon = "📭",
  actionLabel,
  onAction,
  colors,
  style,
}: EmptyStateProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const enter = useRef(new Animated.Value(0)).current;
  const bob = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    if (reduceMotion) {
      enter.setValue(1);
      bob.setValue(0);
      return;
    }
    Animated.timing(enter, {
      toValue: 1,
      duration: 420,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: NATIVE_DRIVER,
    }).start();
    const loop = Animated.loop(
      Animated.sequence([
        Animated.timing(bob, {
          toValue: 1,
          duration: 1600,
          easing: Easing.inOut(Easing.sin),
          useNativeDriver: NATIVE_DRIVER,
        }),
        Animated.timing(bob, {
          toValue: 0,
          duration: 1600,
          easing: Easing.inOut(Easing.sin),
          useNativeDriver: NATIVE_DRIVER,
        }),
      ]),
    );
    loop.start();
    return () => loop.stop();
  }, [reduceMotion, enter, bob]);

  return (
    <Animated.View
      accessible
      accessibilityLabel={message ? `${title}. ${message}` : title}
      style={[
        styles.root,
        {
          opacity: enter,
          transform: [
            { translateY: enter.interpolate({ inputRange: [0, 1], outputRange: [16, 0] }) },
          ],
        },
        style,
      ]}
    >
      <Animated.View
        style={[
          styles.badge,
          {
            backgroundColor: palette.badge,
            transform: [
              { translateY: bob.interpolate({ inputRange: [0, 1], outputRange: [0, -8] }) },
            ],
          },
        ]}
      >
        <Text style={styles.icon}>{icon}</Text>
      </Animated.View>
      <Text style={[styles.title, { color: palette.title }]}>{title}</Text>
      {message ? <Text style={[styles.message, { color: palette.message }]}>{message}</Text> : null}
      {actionLabel && onAction ? (
        <Pressable
          accessibilityRole="button"
          accessibilityLabel={actionLabel}
          onPress={onAction}
          style={({ pressed }) => [
            styles.button,
            { backgroundColor: palette.button, opacity: pressed ? 0.8 : 1 },
          ]}
        >
          <Text style={[styles.buttonText, { color: palette.buttonText }]}>{actionLabel}</Text>
        </Pressable>
      ) : null}
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  root: { alignItems: "center", gap: 8, paddingHorizontal: 24 },
  badge: {
    width: 88,
    height: 88,
    borderRadius: 44,
    alignItems: "center",
    justifyContent: "center",
    marginBottom: 8,
  },
  icon: { fontSize: 40 },
  title: { fontSize: 20, fontWeight: "700", textAlign: "center" },
  message: { fontSize: 15, lineHeight: 22, textAlign: "center", maxWidth: 280 },
  button: {
    marginTop: 12,
    minHeight: 46,
    paddingHorizontal: 24,
    borderRadius: 14,
    justifyContent: "center",
    userSelect: "none",
  },
  buttonText: { fontSize: 15, fontWeight: "700" },
});
```

---

# Rating Histogram

> A React Native review breakdown with one animated bar per star level and the average beside them.

Install: `npx @modus-ui/cli add rating-histogram`

The breakdown of ratings you see on a product page: one bar per star level that grows to its share of all ratings, with the average beside them. Bars animate to new counts, and each row reads out as "4 stars: 12 ratings". Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add rating-histogram
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/rating-histogram.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { RatingHistogram } from "@/components/ui/rating-histogram";

export default function Example() {
  return <RatingHistogram counts={[2, 3, 8, 21, 46]} />;
}
```

## Props

| Prop          | Type                                       | Default | Description                                                  |
| :------------ | :----------------------------------------- | :------ | :----------------------------------------------------------- |
| `counts`      | `[number, number, number, number, number]` | -       | How many ratings each star level got, from one star to five. |
| `showAverage` | `boolean`                                  | `true`  | Shows the average and the total beside the bars.             |
| `colors`      | `Partial<RatingHistogramColors>`           | -       | Overrides `bar`, `track`, `text` and `average`.              |
| `style`       | `StyleProp<ViewStyle>`                     | -       | Style for the whole block.                                   |

## Source

`components/ui/rating-histogram.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface RatingHistogramColors {
  bar: string;
  track: string;
  text: string;
  average: string;
}

const DEFAULT_COLORS: RatingHistogramColors = {
  bar: "#f59e0b",
  track: "#e5e7eb",
  text: "#6b7280",
  average: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface RatingHistogramProps {
  /** How many ratings each star level got, from one star up to five. */
  counts: [number, number, number, number, number];
  /** Shows the average and the total beside the bars. */
  showAverage?: boolean;
  colors?: Partial<RatingHistogramColors>;
  style?: StyleProp<ViewStyle>;
}

function Row({
  stars,
  share,
  count,
  palette,
  reduceMotion,
}: {
  stars: number;
  share: number;
  count: number;
  palette: RatingHistogramColors;
  reduceMotion: boolean;
}) {
  const fill = useRef(new Animated.Value(share)).current;
  useEffect(() => {
    if (reduceMotion) fill.setValue(share);
    else
      Animated.timing(fill, {
        toValue: share,
        duration: 500,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [share, reduceMotion, fill]);
  return (
    <View
      accessible
      accessibilityLabel={`${stars} star${stars > 1 ? "s" : ""}: ${count} rating${count === 1 ? "" : "s"}`}
      style={styles.row}
    >
      <Text style={[styles.star, { color: palette.text }]}>{stars}★</Text>
      <View style={[styles.track, { backgroundColor: palette.track }]}>
        <Animated.View
          style={[
            styles.fill,
            {
              backgroundColor: palette.bar,
              width: fill.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
            },
          ]}
        />
      </View>
      <Text style={[styles.count, { color: palette.text }]}>{count}</Text>
    </View>
  );
}

/**
 * The breakdown of ratings you see on a product page: one bar per star level that grows to its share
 * of all ratings, with the average beside them. Bars animate to new counts, and each row reads out
 * as "4 stars: 12 ratings".
 */
export function RatingHistogram({
  counts,
  showAverage = true,
  colors,
  style,
}: RatingHistogramProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const total = counts.reduce((sum, n) => sum + n, 0);
  const average = total ? counts.reduce((sum, n, i) => sum + n * (i + 1), 0) / total : 0;

  return (
    <View style={[styles.root, style]}>
      {showAverage ? (
        <View
          accessible
          accessibilityLabel={`Average ${average.toFixed(1)} out of 5 from ${total} rating${total === 1 ? "" : "s"}`}
          style={styles.summary}
        >
          <Text style={[styles.average, { color: palette.average }]}>{average.toFixed(1)}</Text>
          <Text style={[styles.total, { color: palette.text }]}>{total} ratings</Text>
        </View>
      ) : null}
      <View style={styles.bars}>
        {[5, 4, 3, 2, 1].map((stars) => (
          <Row
            key={stars}
            stars={stars}
            count={counts[stars - 1]}
            share={total ? counts[stars - 1] / total : 0}
            palette={palette}
            reduceMotion={reduceMotion}
          />
        ))}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flexDirection: "row", alignItems: "center", gap: 20 },
  summary: { alignItems: "center", gap: 2 },
  average: { fontSize: 44, fontWeight: "800" },
  total: { fontSize: 12 },
  bars: { flex: 1, gap: 6 },
  row: { flexDirection: "row", alignItems: "center", gap: 8 },
  star: { width: 28, fontSize: 13 },
  track: { flex: 1, height: 8, borderRadius: 4, overflow: "hidden" },
  fill: { height: "100%", borderRadius: 4 },
  count: { width: 32, fontSize: 13, textAlign: "right" },
});
```

---

# Countdown Timer

> A React Native minutes and seconds countdown with a draining bar that pauses, resumes and fires once when time is up.

Install: `npx @modus-ui/cli add countdown-timer`

A minutes and seconds countdown with a bar that drains underneath. Pausing holds both the digits and the bar and resuming carries on from there. When the time is up the digits turn to the done colour and `onComplete` fires once. The remaining time is not announced every second, only "Time is up", so a screen reader is not flooded. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add countdown-timer
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/countdown-timer.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { CountdownTimer } from "@/components/ui/countdown-timer";

export default function Example() {
  return <CountdownTimer seconds={90} onComplete={() => console.log("done")} />;
}
```

## Props

| Prop         | Type                            | Default   | Description                                                  |
| :----------- | :------------------------------ | :-------- | :----------------------------------------------------------- |
| `seconds`    | `number`                        | -         | How long to count down from. Changing it restarts the timer. |
| `running`    | `boolean`                       | `true`    | Pauses the countdown when false.                             |
| `onComplete` | `() => void`                    | -         | Called once when the time runs out.                          |
| `label`      | `string`                        | `"Timer"` | Spoken name of the timer.                                    |
| `colors`     | `Partial<CountdownTimerColors>` | -         | Overrides `text`, `track`, `fill` and `done`.                |
| `style`      | `StyleProp<ViewStyle>`          | -         | Style for the timer's container.                             |

## Source

`components/ui/countdown-timer.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface CountdownTimerColors {
  text: string;
  track: string;
  fill: string;
  done: string;
}

const DEFAULT_COLORS: CountdownTimerColors = {
  text: "#111827",
  track: "#e5e7eb",
  fill: "#4f46e5",
  done: "#16a34a",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

const format = (ms: number) => {
  const total = Math.ceil(ms / 1000);
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
};

export interface CountdownTimerProps {
  /** How long to count down from, in seconds. Changing it restarts the timer. */
  seconds: number;
  /** Pauses the countdown when false. */
  running?: boolean;
  /** Called once when the time runs out. */
  onComplete?: () => void;
  /** Spoken name of the timer. */
  label?: string;
  colors?: Partial<CountdownTimerColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A minutes and seconds countdown with a bar that drains underneath. Pausing holds both the digits
 * and the bar and resuming carries on from there. When the time is up the digits turn to the done
 * colour and `onComplete` fires once. The remaining time is not announced every second; only
 * "Time is up" is, so a screen reader is not flooded.
 */
export function CountdownTimer({
  seconds,
  running = true,
  onComplete,
  label = "Timer",
  colors,
  style,
}: CountdownTimerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const total = seconds * 1000;
  const [remaining, setRemaining] = useState(total);
  const left = useRef(total);
  const bar = useRef(new Animated.Value(1)).current;
  const finished = useRef(false);
  const live = useRef({ onComplete });
  live.current = { onComplete };

  // A new duration starts over.
  useEffect(() => {
    left.current = total;
    finished.current = false;
    setRemaining(total);
    bar.setValue(1);
  }, [total, bar]);

  // The digits follow a wall clock, so they stay right when the tab is slow.
  useEffect(() => {
    if (!running || left.current <= 0) return;
    const end = Date.now() + left.current;
    const id = setInterval(() => {
      left.current = Math.max(0, end - Date.now());
      setRemaining(left.current);
      if (left.current === 0 && !finished.current) {
        finished.current = true;
        clearInterval(id);
        live.current.onComplete?.();
      }
    }, 200);
    return () => clearInterval(id);
  }, [running, total]);

  // The bar drains over the time that is left, or steps once a second with reduced motion.
  useEffect(() => {
    if (!running || left.current <= 0) return;
    if (reduceMotion) {
      bar.setValue(left.current / total);
      return;
    }
    const animation = Animated.timing(bar, {
      toValue: 0,
      duration: left.current,
      easing: Easing.linear,
      useNativeDriver: false,
    });
    animation.start();
    return () => animation.stop();
  }, [running, reduceMotion, total, bar]);

  useEffect(() => {
    if (reduceMotion) bar.setValue(remaining / total);
  }, [remaining, reduceMotion, total, bar]);

  const done = remaining <= 0;

  return (
    <View
      accessible
      accessibilityRole="timer"
      accessibilityLabel={`${label}, ${done ? "time is up" : format(remaining)}`}
      style={[styles.root, style]}
    >
      <Text style={[styles.digits, { color: done ? palette.done : palette.text }]}>
        {format(remaining)}
      </Text>
      <View style={[styles.track, { backgroundColor: palette.track }]}>
        <Animated.View
          style={[
            styles.fill,
            {
              backgroundColor: done ? palette.done : palette.fill,
              width: bar.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
            },
          ]}
        />
      </View>
      <Text accessibilityLiveRegion="polite" style={styles.sr}>
        {done ? "Time is up" : ""}
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { gap: 12, alignItems: "stretch" },
  digits: { fontSize: 56, fontWeight: "800", textAlign: "center", fontVariant: ["tabular-nums"] },
  track: { height: 8, borderRadius: 4, overflow: "hidden" },
  fill: { height: "100%", borderRadius: 4 },
  sr: { position: "absolute", width: 1, height: 1, opacity: 0 },
});
```

---

# Contact Index

> A React Native alphabetical list with a draggable letter rail that jumps between sections like a phone's contacts.

Install: `npx @modus-ui/cli add contact-index`

An alphabetical list with a letter rail down the right edge, like a phone's contacts. Names are grouped under letter headers. Tap or drag along the rail to jump to a letter and the list scrolls there; the letter you are on is highlighted and read out. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add contact-index
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/contact-index.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { ContactIndex } from "@/components/ui/contact-index";

export default function Example() {
  return (
    <ContactIndex
      items={[
        { id: "1", name: "Aaron" },
        { id: "2", name: "Maya" },
      ]}
      onSelect={(item) => console.log(item.name)}
    />
  );
}
```

## Props

| Prop       | Type                          | Default | Description                                                      |
| :--------- | :---------------------------- | :------ | :--------------------------------------------------------------- |
| `items`    | `ContactItem[]`               | -       | The people to list, each with an `id` and a `name`.              |
| `onSelect` | `(item: ContactItem) => void` | -       | Called when a name is pressed.                                   |
| `colors`   | `Partial<ContactIndexColors>` | -       | Overrides `header`, `headerText`, `text`, `accent` and `border`. |
| `style`    | `StyleProp<ViewStyle>`        | -       | Style for the list; give it a height.                            |

## Source

`components/ui/contact-index.tsx`

```tsx
import { useEffect, useMemo, useRef, useState, type ElementRef } from "react";
import {
  AccessibilityInfo,
  PanResponder,
  Pressable,
  ScrollView,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const LETTER = 18;

export interface ContactItem {
  id: string;
  name: string;
}

export interface ContactIndexColors {
  header: string;
  headerText: string;
  text: string;
  accent: string;
  border: string;
}

const DEFAULT_COLORS: ContactIndexColors = {
  header: "#f3f4f6",
  headerText: "#6b7280",
  text: "#111827",
  accent: "#4f46e5",
  border: "#e5e7eb",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ContactIndexProps {
  items: ContactItem[];
  onSelect?: (item: ContactItem) => void;
  colors?: Partial<ContactIndexColors>;
  /** Give it a height, for example flex: 1 or a number. */
  style?: StyleProp<ViewStyle>;
}

/**
 * An alphabetical list with a letter rail down the right edge, like a phone's contacts. Names are
 * grouped under letter headers. Tap or drag along the rail to jump to a letter and the list scrolls
 * there; the letter you are on is highlighted and its name is read out.
 */
export function ContactIndex({ items, onSelect, colors, style }: ContactIndexProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const list = useRef<ElementRef<typeof ScrollView>>(null);
  const tops = useRef<Record<string, number>>({});
  const [active, setActive] = useState<string | null>(null);

  const groups = useMemo(() => {
    const map = new Map<string, ContactItem[]>();
    [...items]
      .sort((a, b) => a.name.localeCompare(b.name))
      .forEach((item) => {
        const key = item.name.charAt(0).toUpperCase() || "#";
        map.set(key, [...(map.get(key) ?? []), item]);
      });
    return [...map.entries()];
  }, [items]);

  const live = useRef({ groups, reduceMotion });
  live.current = { groups, reduceMotion };

  const jump = (index: number) => {
    const { groups: all, reduceMotion: reduce } = live.current;
    const key = all[Math.max(0, Math.min(all.length - 1, index))]?.[0];
    if (!key) return;
    setActive(key);
    list.current?.scrollTo({ y: tops.current[key] ?? 0, animated: !reduce });
    AccessibilityInfo.announceForAccessibility(key);
  };

  const rail = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onMoveShouldSetPanResponder: () => true,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: (event) => jump(Math.floor(event.nativeEvent.locationY / LETTER)),
      onPanResponderMove: (event) => jump(Math.floor(event.nativeEvent.locationY / LETTER)),
    }),
  ).current;

  return (
    <View style={[styles.root, style]}>
      <ScrollView ref={list} showsVerticalScrollIndicator={false}>
        {groups.map(([letter, people]) => (
          <View
            key={letter}
            onLayout={(event) => (tops.current[letter] = event.nativeEvent.layout.y)}
          >
            <View style={[styles.header, { backgroundColor: palette.header }]}>
              <Text
                accessibilityRole="header"
                style={[styles.headerText, { color: palette.headerText }]}
              >
                {letter}
              </Text>
            </View>
            {people.map((person) => (
              <Pressable
                key={person.id}
                accessibilityRole="button"
                accessibilityLabel={person.name}
                onPress={() => onSelect?.(person)}
                style={[styles.row, { borderBottomColor: palette.border }]}
              >
                <Text style={[styles.name, { color: palette.text }]}>{person.name}</Text>
              </Pressable>
            ))}
          </View>
        ))}
      </ScrollView>
      <View
        {...rail.panHandlers}
        accessibilityLabel="Jump to letter"
        accessibilityRole="adjustable"
        style={styles.rail}
      >
        {groups.map(([letter]) => (
          <Text
            key={letter}
            pointerEvents="none"
            style={[
              styles.letter,
              { color: active === letter ? palette.accent : palette.headerText },
            ]}
          >
            {letter}
          </Text>
        ))}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { flex: 1, flexDirection: "row" },
  header: { paddingHorizontal: 16, paddingVertical: 4 },
  headerText: { fontSize: 13, fontWeight: "700" },
  row: {
    minHeight: 48,
    paddingHorizontal: 16,
    justifyContent: "center",
    borderBottomWidth: StyleSheet.hairlineWidth,
  },
  name: { fontSize: 16 },
  rail: {
    width: 26,
    alignItems: "center",
    justifyContent: "center",
    paddingVertical: 8,
    userSelect: "none",
  },
  letter: { height: LETTER, fontSize: 11, fontWeight: "700", lineHeight: LETTER },
});
```

---

# Select Grid

> A React Native multi-select grid of cards where a tick springs in, with an optional limit that dims the rest.

Install: `npx @modus-ui/cli add select-grid`

A grid of cards where any number can be picked, such as interests during onboarding. A picked card takes the accent border and a tick springs into its corner. Set `max` and the remaining cards dim once the limit is reached. Every card is a checkbox for screen readers. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add select-grid
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/select-grid.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { SelectGrid } from "@/components/ui/select-grid";

export default function Example() {
  const [picked, setPicked] = useState<string[]>([]);

  return (
    <SelectGrid
      options={[
        { id: "music", label: "Music", icon: "🎧" },
        { id: "food", label: "Food", icon: "🍜" },
      ]}
      value={picked}
      onChange={setPicked}
      max={3}
    />
  );
}
```

## Props

| Prop       | Type                        | Default | Description                                                                          |
| :--------- | :-------------------------- | :------ | :----------------------------------------------------------------------------------- |
| `options`  | `SelectOption[]`            | -       | The cards, each with an `id`, a `label` and an optional `icon`.                      |
| `value`    | `string[]`                  | -       | The ids of the selected options.                                                     |
| `onChange` | `(value: string[]) => void` | -       | Called with the new selection.                                                       |
| `columns`  | `number`                    | `2`     | Cards per row.                                                                       |
| `max`      | `number`                    | -       | The most cards that can be selected.                                                 |
| `colors`   | `Partial<SelectGridColors>` | -       | Overrides `accent`, `border`, `surface`, `selectedSurface`, `label` and `checkText`. |
| `style`    | `StyleProp<ViewStyle>`      | -       | Style for the grid.                                                                  |

## Source

`components/ui/select-grid.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface SelectOption {
  id: string;
  label: string;
  /** A glyph or emoji drawn above the label. */
  icon?: string;
}

export interface SelectGridColors {
  accent: string;
  border: string;
  surface: string;
  selectedSurface: string;
  label: string;
  checkText: string;
}

const DEFAULT_COLORS: SelectGridColors = {
  accent: "#4f46e5",
  border: "#e5e7eb",
  surface: "#ffffff",
  selectedSurface: "#eef2ff",
  label: "#111827",
  checkText: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SelectGridProps {
  options: SelectOption[];
  /** The ids of the selected options. */
  value: string[];
  onChange: (value: string[]) => void;
  /** Cards per row. */
  columns?: number;
  /** The most cards that can be selected; further taps are ignored until one is cleared. */
  max?: number;
  colors?: Partial<SelectGridColors>;
  style?: StyleProp<ViewStyle>;
}

interface CardProps {
  option: SelectOption;
  selected: boolean;
  blocked: boolean;
  palette: SelectGridColors;
  reduceMotion: boolean;
  onPress: () => void;
}

function Card({ option, selected, blocked, palette, reduceMotion, onPress }: CardProps) {
  const check = useRef(new Animated.Value(selected ? 1 : 0)).current;
  const press = useRef(new Animated.Value(1)).current;

  useEffect(() => {
    if (reduceMotion) check.setValue(selected ? 1 : 0);
    else
      Animated.spring(check, {
        toValue: selected ? 1 : 0,
        stiffness: 480,
        damping: 22,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
  }, [selected, reduceMotion, check]);

  const dip = (down: boolean) => {
    if (reduceMotion) return;
    Animated.spring(press, {
      toValue: down ? 0.96 : 1,
      stiffness: 500,
      damping: 26,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  };

  return (
    <Pressable
      accessibilityRole="checkbox"
      accessibilityLabel={option.label}
      accessibilityState={{ checked: selected, disabled: blocked }}
      aria-checked={selected}
      aria-disabled={blocked}
      onPress={onPress}
      onPressIn={() => dip(true)}
      onPressOut={() => dip(false)}
      style={styles.cell}
    >
      <Animated.View
        style={[
          styles.card,
          {
            borderColor: selected ? palette.accent : palette.border,
            backgroundColor: selected ? palette.selectedSurface : palette.surface,
            opacity: blocked ? 0.45 : 1,
            transform: [{ scale: press }],
          },
        ]}
      >
        {option.icon ? <Text style={styles.icon}>{option.icon}</Text> : null}
        <Text style={[styles.label, { color: palette.label }]}>{option.label}</Text>
        <Animated.View
          style={[
            styles.badge,
            { backgroundColor: palette.accent, opacity: check, transform: [{ scale: check }] },
          ]}
        >
          <Text style={[styles.tick, { color: palette.checkText }]}>✓</Text>
        </Animated.View>
      </Animated.View>
    </Pressable>
  );
}

/**
 * A grid of cards where any number can be picked, such as interests during onboarding. A picked card
 * takes the accent border and a tick springs into its corner. Set `max` and the remaining cards dim
 * once the limit is reached. Every card is a checkbox for screen readers.
 */
export function SelectGrid({
  options,
  value,
  onChange,
  columns = 2,
  max,
  colors,
  style,
}: SelectGridProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const full = max !== undefined && value.length >= max;

  const toggle = (id: string) => {
    if (value.includes(id)) onChange(value.filter((v) => v !== id));
    else if (!full) onChange([...value, id]);
  };

  return (
    <View accessibilityRole="list" style={[styles.grid, style]}>
      {options.map((option) => {
        const selected = value.includes(option.id);
        return (
          <View key={option.id} style={{ width: `${100 / columns}%` }}>
            <Card
              option={option}
              selected={selected}
              blocked={full && !selected}
              palette={palette}
              reduceMotion={reduceMotion}
              onPress={() => toggle(option.id)}
            />
          </View>
        );
      })}
    </View>
  );
}

const styles = StyleSheet.create({
  grid: { flexDirection: "row", flexWrap: "wrap", margin: -5 },
  cell: { padding: 5, userSelect: "none" },
  card: {
    minHeight: 88,
    borderRadius: 16,
    borderWidth: 2,
    alignItems: "center",
    justifyContent: "center",
    gap: 6,
    padding: 12,
  },
  icon: { fontSize: 28 },
  label: { fontSize: 15, fontWeight: "600" },
  badge: {
    position: "absolute",
    top: 8,
    right: 8,
    width: 20,
    height: 20,
    borderRadius: 10,
    alignItems: "center",
    justifyContent: "center",
  },
  tick: { fontSize: 12, fontWeight: "800" },
});
```

---

# Poll Bars

> A React Native poll whose options turn into animated result bars with percentages once a vote is cast.

Install: `npx @modus-ui/cli add poll-bars`

A poll. Before anyone has voted each option is a button. After a vote the options turn into bars that grow to each one's share of the votes, with percentages, and the chosen option is marked. Results are read out for each option, along with which one is yours. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add poll-bars
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/poll-bars.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { PollBars } from "@/components/ui/poll-bars";

export default function Example() {
  const [selected, setSelected] = useState<string>();

  return (
    <PollBars
      selected={selected}
      onVote={setSelected}
      options={[
        { id: "a", label: "Cats", votes: 12 },
        { id: "b", label: "Dogs", votes: 9 },
      ]}
    />
  );
}
```

## Props

| Prop       | Type                      | Default | Description                                                   |
| :--------- | :------------------------ | :------ | :------------------------------------------------------------ |
| `options`  | `PollOption[]`            | -       | The choices, each with an `id`, a `label` and its `votes`.    |
| `selected` | `string`                  | -       | The id voted for; once set, results show.                     |
| `onVote`   | `(id: string) => void`    | -       | Called with the id when an option is pressed.                 |
| `colors`   | `Partial<PollBarsColors>` | -       | Overrides `bar`, `chosenBar`, `surface`, `border` and `text`. |
| `style`    | `StyleProp<ViewStyle>`    | -       | Style for the poll.                                           |

## Source

`components/ui/poll-bars.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface PollOption {
  id: string;
  label: string;
  votes: number;
}

export interface PollBarsColors {
  bar: string;
  chosenBar: string;
  surface: string;
  border: string;
  text: string;
}

const DEFAULT_COLORS: PollBarsColors = {
  bar: "#e0e7ff",
  chosenBar: "#a5b4fc",
  surface: "#ffffff",
  border: "#e5e7eb",
  text: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface PollBarsProps {
  options: PollOption[];
  /** The id the person voted for; once set, results show. */
  selected?: string;
  onVote: (id: string) => void;
  colors?: Partial<PollBarsColors>;
  style?: StyleProp<ViewStyle>;
}

function Row({
  option,
  share,
  chosen,
  voted,
  palette,
  reduceMotion,
  onVote,
}: {
  option: PollOption;
  share: number;
  chosen: boolean;
  voted: boolean;
  palette: PollBarsColors;
  reduceMotion: boolean;
  onVote: () => void;
}) {
  const fill = useRef(new Animated.Value(0)).current;
  useEffect(() => {
    const toValue = voted ? share : 0;
    if (reduceMotion) fill.setValue(toValue);
    else
      Animated.timing(fill, {
        toValue,
        duration: 550,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [voted, share, reduceMotion, fill]);

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={
        voted
          ? `${option.label}, ${Math.round(share * 100)} percent${chosen ? ", your vote" : ""}`
          : option.label
      }
      accessibilityState={{ selected: chosen, disabled: voted }}
      disabled={voted}
      onPress={onVote}
      style={[
        styles.row,
        {
          borderColor: chosen ? palette.chosenBar : palette.border,
          backgroundColor: palette.surface,
        },
      ]}
    >
      <Animated.View
        pointerEvents="none"
        style={[
          styles.fill,
          {
            backgroundColor: chosen ? palette.chosenBar : palette.bar,
            width: fill.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
          },
        ]}
      />
      <Text style={[styles.label, { color: palette.text }]}>
        {option.label}
        {chosen ? " ✓" : ""}
      </Text>
      {voted ? (
        <Text style={[styles.percent, { color: palette.text }]}>{Math.round(share * 100)}%</Text>
      ) : null}
    </Pressable>
  );
}

/**
 * A poll. Before anyone has voted each option is a button. After a vote the options turn into bars
 * that grow to each one's share of the votes, with percentages, and the chosen option is marked.
 * Results are read out for each option, along with which one is yours.
 */
export function PollBars({ options, selected, onVote, colors, style }: PollBarsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const voted = selected !== undefined;
  const total = options.reduce((sum, option) => sum + option.votes, 0);

  return (
    <View style={[styles.root, style]}>
      {options.map((option) => (
        <Row
          key={option.id}
          option={option}
          share={total ? option.votes / total : 0}
          chosen={option.id === selected}
          voted={voted}
          palette={palette}
          reduceMotion={reduceMotion}
          onVote={() => onVote(option.id)}
        />
      ))}
      <Text accessibilityLiveRegion="polite" style={[styles.total, { color: palette.text }]}>
        {voted ? `${total} votes` : ""}
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { gap: 8 },
  row: {
    minHeight: 52,
    borderRadius: 14,
    borderWidth: 2,
    overflow: "hidden",
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    paddingHorizontal: 16,
    userSelect: "none",
  },
  fill: { position: "absolute", top: 0, bottom: 0, left: 0 },
  label: { fontSize: 16, fontWeight: "600" },
  percent: { fontSize: 15, fontWeight: "700" },
  total: { fontSize: 13, textAlign: "right", opacity: 0.7, minHeight: 18 },
});
```

---

# Card Field

> A React Native payment card input that groups the number, names the brand, adds the expiry slash and shakes on a failed check.

Install: `npx @modus-ui/cli add card-field`

A card entry field. The number groups itself as you type, in fours or in the 4-6-5 pattern of an Amex, the brand name appears from the first digits, the expiry adds its own slash, and a full number that fails the Luhn check shakes and turns red. Each input has its own spoken name and the numeric keyboard. It only formats and checks the shape of a card; never send raw card numbers to your own server, use your payment provider's fields for that. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add card-field
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/card-field.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { CardField, type CardValue } from "@/components/ui/card-field";

export default function Example() {
  const [card, setCard] = useState<CardValue>({ number: "", expiry: "", cvc: "" });

  return <CardField value={card} onChange={setCard} />;
}
```

## Props

| Prop       | Type                         | Default | Description                                                                |
| :--------- | :--------------------------- | :------ | :------------------------------------------------------------------------- |
| `value`    | `CardValue`                  | -       | The `number`, `expiry` and `cvc` as formatted strings.                     |
| `onChange` | `(value: CardValue) => void` | -       | Called with the updated, formatted value.                                  |
| `colors`   | `Partial<CardFieldColors>`   | -       | Overrides `surface`, `border`, `text`, `placeholder`, `error` and `valid`. |
| `style`    | `StyleProp<ViewStyle>`       | -       | Style for the field's frame.                                               |

## Source

`components/ui/card-field.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface CardValue {
  number: string;
  expiry: string;
  cvc: string;
}

export interface CardFieldColors {
  surface: string;
  border: string;
  text: string;
  placeholder: string;
  error: string;
  valid: string;
}

const DEFAULT_COLORS: CardFieldColors = {
  surface: "#ffffff",
  border: "#d1d5db",
  text: "#111827",
  placeholder: "#9ca3af",
  error: "#dc2626",
  valid: "#16a34a",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

const digits = (text: string) => text.replace(/\D/g, "");

function brandOf(number: string) {
  if (/^3[47]/.test(number)) return "Amex";
  if (/^4/.test(number)) return "Visa";
  if (/^(5[1-5]|2[2-7])/.test(number)) return "Mastercard";
  if (/^6/.test(number)) return "Discover";
  return "Card";
}

function formatNumber(text: string) {
  const raw = digits(text);
  if (brandOf(raw) === "Amex") {
    const n = raw.slice(0, 15);
    return [n.slice(0, 4), n.slice(4, 10), n.slice(10)].filter(Boolean).join(" ");
  }
  return (raw.slice(0, 16).match(/.{1,4}/g) ?? []).join(" ");
}

function formatExpiry(text: string) {
  const raw = digits(text).slice(0, 4);
  return raw.length > 2 ? `${raw.slice(0, 2)}/${raw.slice(2)}` : raw;
}

function luhn(number: string) {
  let sum = 0;
  [...number].reverse().forEach((char, i) => {
    let d = Number(char);
    if (i % 2 === 1) d = d * 2 > 9 ? d * 2 - 9 : d * 2;
    sum += d;
  });
  return sum % 10 === 0;
}

export interface CardFieldProps {
  value: CardValue;
  onChange: (value: CardValue) => void;
  colors?: Partial<CardFieldColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A card entry field. The number groups itself as you type, in fours or in the 4-6-5 pattern of an
 * Amex, the brand name appears from the first digits, the expiry adds its own slash, and a full
 * number that fails the Luhn check shakes and turns red. Each input has its own spoken name and the
 * numeric keyboard.
 */
export function CardField({ value, onChange, colors, style }: CardFieldProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const shake = useRef(new Animated.Value(0)).current;
  const raw = digits(value.number);
  const brand = brandOf(raw);
  const length = brand === "Amex" ? 15 : 16;
  const complete = raw.length === length;
  const valid = complete && luhn(raw);
  const bad = complete && !valid;
  const wasBad = useRef(false);

  useEffect(() => {
    if (bad && !wasBad.current && !reduceMotion) {
      Animated.sequence(
        [-6, 6, -4, 4, 0].map((toValue) =>
          Animated.timing(shake, { toValue, duration: 50, useNativeDriver: NATIVE_DRIVER }),
        ),
      ).start();
    }
    wasBad.current = bad;
  }, [bad, reduceMotion, shake]);

  const input = (props: React.ComponentProps<typeof TextInput>) => (
    <TextInput
      keyboardType="number-pad"
      placeholderTextColor={palette.placeholder}
      style={[styles.input, { color: palette.text }]}
      {...props}
    />
  );

  return (
    <Animated.View
      style={[
        styles.root,
        {
          backgroundColor: palette.surface,
          borderColor: bad ? palette.error : palette.border,
          transform: [{ translateX: shake }],
        },
        style,
      ]}
    >
      <View style={styles.top}>
        {input({
          accessibilityLabel: "Card number",
          autoComplete: "cc-number",
          placeholder: "1234 5678 9012 3456",
          value: value.number,
          onChangeText: (text) => onChange({ ...value, number: formatNumber(text) }),
          style: [styles.input, styles.number, { color: palette.text }],
        })}
        <Text
          style={[
            styles.brand,
            { color: valid ? palette.valid : bad ? palette.error : palette.placeholder },
          ]}
        >
          {valid ? `${brand} ✓` : brand}
        </Text>
      </View>
      <View style={[styles.bottom, { borderTopColor: palette.border }]}>
        {input({
          accessibilityLabel: "Expiry date",
          autoComplete: "cc-exp",
          placeholder: "MM/YY",
          value: value.expiry,
          onChangeText: (text) => onChange({ ...value, expiry: formatExpiry(text) }),
          style: [styles.input, styles.half, { color: palette.text }],
        })}
        {input({
          accessibilityLabel: "Security code",
          autoComplete: "cc-csc",
          placeholder: brand === "Amex" ? "CVC (4)" : "CVC",
          secureTextEntry: true,
          value: value.cvc,
          onChangeText: (text) =>
            onChange({ ...value, cvc: digits(text).slice(0, brand === "Amex" ? 4 : 3) }),
          style: [
            styles.input,
            styles.half,
            { color: palette.text, borderLeftColor: palette.border, borderLeftWidth: 1 },
          ],
        })}
      </View>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  root: { borderWidth: 1.5, borderRadius: 14, overflow: "hidden" },
  top: { flexDirection: "row", alignItems: "center", paddingRight: 14 },
  input: { height: 50, paddingHorizontal: 14, fontSize: 16 },
  number: { flex: 1 },
  half: { flex: 1 },
  brand: { fontSize: 13, fontWeight: "700" },
  bottom: { flexDirection: "row", borderTopWidth: 1 },
});
```

---

# Step Slider

> A React Native slider with fixed stops whose thumb follows the finger and springs onto the nearest label.

Install: `npx @modus-ui/cli add step-slider`

A slider with a fixed set of stops, such as a text size or a delivery speed. The thumb follows the finger and settles on the nearest stop with a spring; tapping the track jumps to the stop under it. It is an adjustable control for screen readers and reads out the label of the chosen stop. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add step-slider
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/step-slider.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { StepSlider } from "@/components/ui/step-slider";

export default function Example() {
  const [index, setIndex] = useState(1);

  return (
    <StepSlider
      steps={["Slow", "Normal", "Fast"]}
      value={index}
      onChange={setIndex}
      label="Speed"
    />
  );
}
```

## Props

| Prop       | Type                        | Default  | Description                                    |
| :--------- | :-------------------------- | :------- | :--------------------------------------------- |
| `steps`    | `string[]`                  | -        | The label under each stop.                     |
| `value`    | `number`                    | -        | The index of the chosen stop.                  |
| `onChange` | `(index: number) => void`   | -        | Called when the chosen stop changes.           |
| `label`    | `string`                    | `"Step"` | Spoken name of the slider.                     |
| `colors`   | `Partial<StepSliderColors>` | -        | Overrides `track`, `fill`, `thumb` and `text`. |
| `style`    | `StyleProp<ViewStyle>`      | -        | Style for the slider.                          |

## Source

`components/ui/step-slider.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  Platform,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const THUMB = 28;

export interface StepSliderColors {
  track: string;
  fill: string;
  thumb: string;
  text: string;
}

const DEFAULT_COLORS: StepSliderColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  thumb: "#ffffff",
  text: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface StepSliderProps {
  /** The label under each stop. */
  steps: string[];
  /** The index of the chosen stop. */
  value: number;
  onChange: (index: number) => void;
  /** Spoken name of the slider. */
  label?: string;
  colors?: Partial<StepSliderColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A slider with a fixed set of stops, such as a text size or a delivery speed. The thumb follows the
 * finger and settles on the nearest stop with a spring; tapping the track jumps to the stop under it.
 * It is an adjustable control for screen readers and reads out the label of the chosen stop.
 */
export function StepSlider({
  steps,
  value,
  onChange,
  label = "Step",
  colors,
  style,
}: StepSliderProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const x = useRef(new Animated.Value(0)).current;
  const dragging = useRef(false);
  const last = steps.length - 1;
  const travel = Math.max(1, width - THUMB);

  const live = useRef({ travel, last, value, onChange, reduceMotion });
  live.current = { travel, last, value, onChange, reduceMotion };

  const settle = (index: number) => {
    const target = (index / Math.max(1, live.current.last)) * live.current.travel;
    if (live.current.reduceMotion) x.setValue(target);
    else
      Animated.spring(x, {
        toValue: target,
        stiffness: 420,
        damping: 30,
        mass: 1,
        useNativeDriver: false,
      }).start();
  };

  useEffect(() => {
    if (!dragging.current && width > 0) settle(value);
    // settle reads everything through refs.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [value, width, reduceMotion]);

  const indexAt = (px: number) => {
    const { travel: t, last: l } = live.current;
    return Math.max(0, Math.min(l, Math.round(((px - THUMB / 2) / t) * l)));
  };

  const start = useRef(0);
  const responder = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: (event) => {
        dragging.current = true;
        const px = Math.max(
          0,
          Math.min(live.current.travel, event.nativeEvent.locationX - THUMB / 2),
        );
        start.current = px;
        x.stopAnimation();
        x.setValue(px);
        const next = indexAt(event.nativeEvent.locationX);
        if (next !== live.current.value) live.current.onChange(next);
      },
      onPanResponderMove: (_, g) => {
        const px = Math.max(0, Math.min(live.current.travel, start.current + g.dx));
        x.setValue(px);
        const next = indexAt(px + THUMB / 2);
        if (next !== live.current.value) live.current.onChange(next);
      },
      onPanResponderRelease: () => {
        dragging.current = false;
        settle(live.current.value);
      },
      onPanResponderTerminate: () => {
        dragging.current = false;
        settle(live.current.value);
      },
    }),
  ).current;

  const move = (direction: 1 | -1) => onChange(Math.max(0, Math.min(last, value + direction)));

  return (
    <View style={style}>
      <View
        {...responder.panHandlers}
        onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
        accessible
        accessibilityRole="adjustable"
        accessibilityLabel={label}
        aria-label={label}
        accessibilityValue={{ min: 0, max: last, now: value, text: steps[value] }}
        aria-valuemin={0}
        aria-valuemax={last}
        aria-valuenow={value}
        aria-valuetext={steps[value]}
        accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
        onAccessibilityAction={(event) =>
          move(event.nativeEvent.actionName === "increment" ? 1 : -1)
        }
        style={styles.hit}
      >
        <View style={[styles.track, { backgroundColor: palette.track }]} />
        <Animated.View
          pointerEvents="none"
          style={[
            styles.fill,
            { backgroundColor: palette.fill, width: Animated.add(x, THUMB / 2) },
          ]}
        />
        {steps.map((step, i) => (
          <View
            key={step}
            pointerEvents="none"
            style={[
              styles.tick,
              {
                left: THUMB / 2 - 3 + (i / Math.max(1, last)) * travel,
                backgroundColor: i <= value ? palette.thumb : palette.fill,
              },
            ]}
          />
        ))}
        <Animated.View
          pointerEvents="none"
          style={[styles.thumb, { backgroundColor: palette.thumb, transform: [{ translateX: x }] }]}
        />
      </View>
      <View style={styles.labels} pointerEvents="none">
        {steps.map((step, i) => (
          <Text
            key={step}
            style={[
              styles.label,
              {
                color: i === value ? palette.fill : palette.text,
                fontWeight: i === value ? "700" : "500",
              },
            ]}
          >
            {step}
          </Text>
        ))}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  hit: { height: 44, justifyContent: "center", userSelect: "none" },
  track: { height: 6, borderRadius: 3 },
  fill: { position: "absolute", left: 0, top: 19, height: 6, borderRadius: 3 },
  tick: { position: "absolute", top: 19, width: 6, height: 6, borderRadius: 3 },
  thumb: {
    position: "absolute",
    left: 0,
    top: 8,
    width: THUMB,
    height: THUMB,
    borderRadius: THUMB / 2,
    boxShadow: "0 2px 6px rgba(0, 0, 0, 0.3)",
  },
  labels: { flexDirection: "row", justifyContent: "space-between" },
  label: { fontSize: 12 },
});
```

---

# Cart Quantity

> A React Native quantity picker whose minus turns into a bin at one so the same tap removes the item.

Install: `npx @modus-ui/cli add cart-quantity`

A quantity picker for a cart line. At one, the minus becomes a bin so the same tap removes the item instead of going to zero. The number pops when it changes and the plus dims at the limit. Each button names the item it changes, and the new quantity is announced. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add cart-quantity
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/cart-quantity.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { CartQuantity } from "@/components/ui/cart-quantity";

export default function Example() {
  const [qty, setQty] = useState(1);

  return (
    <CartQuantity label="Linen shirt" value={qty} onChange={setQty} onRemove={() => setQty(0)} />
  );
}
```

## Props

| Prop       | Type                          | Default  | Description                                                    |
| :--------- | :---------------------------- | :------- | :------------------------------------------------------------- |
| `value`    | `number`                      | -        | The current quantity.                                          |
| `onChange` | `(value: number) => void`     | -        | Called with the new quantity.                                  |
| `onRemove` | `() => void`                  | -        | Called when minus is pressed at 1; the minus then shows a bin. |
| `max`      | `number`                      | `99`     | The most that can be ordered.                                  |
| `label`    | `string`                      | `"item"` | Spoken name of the item.                                       |
| `colors`   | `Partial<CartQuantityColors>` | -        | Overrides `surface`, `border`, `text`, `accent` and `remove`.  |
| `style`    | `StyleProp<ViewStyle>`        | -        | Style for the picker.                                          |

## Source

`components/ui/cart-quantity.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface CartQuantityColors {
  surface: string;
  border: string;
  text: string;
  accent: string;
  remove: string;
}

const DEFAULT_COLORS: CartQuantityColors = {
  surface: "#ffffff",
  border: "#e5e7eb",
  text: "#111827",
  accent: "#4f46e5",
  remove: "#dc2626",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface CartQuantityProps {
  value: number;
  onChange: (value: number) => void;
  /** Called when minus is pressed at 1; the minus then shows a bin. Leave it out to stop at 1. */
  onRemove?: () => void;
  /** The most that can be ordered. */
  max?: number;
  /** Spoken name of the item. */
  label?: string;
  colors?: Partial<CartQuantityColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A quantity picker for a cart line. At one, the minus becomes a bin so the same tap removes the item
 * instead of going to zero. The number pops when it changes and the plus dims at the limit. Each
 * button names the item it changes, and the new quantity is announced.
 */
export function CartQuantity({
  value,
  onChange,
  onRemove,
  max = 99,
  label = "item",
  colors,
  style,
}: CartQuantityProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const pop = useRef(new Animated.Value(1)).current;
  const first = useRef(true);
  const removing = value <= 1 && !!onRemove;

  useEffect(() => {
    if (first.current) {
      first.current = false;
      return;
    }
    if (reduceMotion) return;
    pop.setValue(1.3);
    Animated.spring(pop, {
      toValue: 1,
      stiffness: 400,
      damping: 16,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [value, reduceMotion, pop]);

  const decrease = () => (removing ? onRemove?.() : value > 1 && onChange(value - 1));
  const button = (
    text: string,
    name: string,
    onPress: () => void,
    disabled: boolean,
    tint: string,
  ) => (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={name}
      accessibilityState={{ disabled }}
      aria-disabled={disabled}
      disabled={disabled}
      onPress={onPress}
      style={({ pressed }) => [styles.button, { opacity: disabled ? 0.35 : pressed ? 0.6 : 1 }]}
    >
      <Text style={[styles.glyph, { color: tint }]}>{text}</Text>
    </Pressable>
  );

  return (
    <View
      style={[
        styles.root,
        { backgroundColor: palette.surface, borderColor: palette.border },
        style,
      ]}
    >
      {removing
        ? button("🗑", `Remove ${label}`, decrease, false, palette.remove)
        : button("−", `Decrease ${label} quantity`, decrease, value <= 1, palette.accent)}
      <Animated.Text
        accessibilityLiveRegion="polite"
        accessibilityLabel={`Quantity ${value}`}
        style={[styles.value, { color: palette.text, transform: [{ scale: pop }] }]}
      >
        {value}
      </Animated.Text>
      {button(
        "+",
        `Increase ${label} quantity`,
        () => onChange(Math.min(max, value + 1)),
        value >= max,
        palette.accent,
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  root: {
    flexDirection: "row",
    alignItems: "center",
    alignSelf: "flex-start",
    borderWidth: 1,
    borderRadius: 14,
  },
  button: {
    width: 44,
    height: 44,
    alignItems: "center",
    justifyContent: "center",
    userSelect: "none",
  },
  glyph: { fontSize: 22, fontWeight: "600" },
  value: { minWidth: 32, textAlign: "center", fontSize: 17, fontWeight: "700" },
});
```

---

# Password Field

> A React Native password input with a Show and Hide button and a border that eases to the accent colour on focus.

Install: `npx @modus-ui/cli add password-field`

A password input with a Show and Hide button at its end. The border eases to the accent colour while the field has focus. The button says what it will do, so a screen reader hears "Show password" and then "Hide password". Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add password-field
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/password-field.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { PasswordField } from "@/components/ui/password-field";

export default function Example() {
  const [password, setPassword] = useState("");

  return <PasswordField value={password} onChangeText={setPassword} />;
}
```

## Props

| Prop           | Type                           | Default      | Description                                                                 |
| :------------- | :----------------------------- | :----------- | :-------------------------------------------------------------------------- |
| `value`        | `string`                       | -            | The password text.                                                          |
| `onChangeText` | `(text: string) => void`       | -            | Called as the text changes.                                                 |
| `placeholder`  | `string`                       | `"Password"` | Hint shown while the field is empty.                                        |
| `label`        | `string`                       | `"Password"` | Spoken name of the field.                                                   |
| `colors`       | `Partial<PasswordFieldColors>` | -            | Overrides `surface`, `border`, `focus`, `text`, `placeholder` and `toggle`. |
| `style`        | `StyleProp<ViewStyle>`         | -            | Style for the field's frame.                                                |

## Source

`components/ui/password-field.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Pressable,
  StyleSheet,
  Text,
  TextInput,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface PasswordFieldColors {
  surface: string;
  border: string;
  focus: string;
  text: string;
  placeholder: string;
  toggle: string;
}

const DEFAULT_COLORS: PasswordFieldColors = {
  surface: "#ffffff",
  border: "#d1d5db",
  focus: "#4f46e5",
  text: "#111827",
  placeholder: "#9ca3af",
  toggle: "#4f46e5",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface PasswordFieldProps {
  value: string;
  onChangeText: (text: string) => void;
  placeholder?: string;
  /** Spoken name of the field. */
  label?: string;
  colors?: Partial<PasswordFieldColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A password input with a Show and Hide button at its end. The border eases to the accent colour
 * while the field has focus. The button says what it will do, and its pressed state is exposed, so a
 * screen reader hears "Show password" and then "Hide password".
 */
export function PasswordField({
  value,
  onChangeText,
  placeholder = "Password",
  label = "Password",
  colors,
  style,
}: PasswordFieldProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [shown, setShown] = useState(false);
  const focus = useRef(new Animated.Value(0)).current;

  const setFocus = (on: boolean) => {
    if (reduceMotion) focus.setValue(on ? 1 : 0);
    else
      Animated.timing(focus, {
        toValue: on ? 1 : 0,
        duration: 160,
        useNativeDriver: false,
      }).start();
  };

  return (
    <Animated.View
      style={[
        styles.root,
        {
          backgroundColor: palette.surface,
          borderColor: focus.interpolate({
            inputRange: [0, 1],
            outputRange: [palette.border, palette.focus],
          }),
        },
        style,
      ]}
    >
      <TextInput
        accessibilityLabel={label}
        value={value}
        onChangeText={onChangeText}
        placeholder={placeholder}
        placeholderTextColor={palette.placeholder}
        secureTextEntry={!shown}
        autoCapitalize="none"
        autoCorrect={false}
        autoComplete="password"
        onFocus={() => setFocus(true)}
        onBlur={() => setFocus(false)}
        style={[styles.input, { color: palette.text }]}
      />
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={shown ? "Hide password" : "Show password"}
        accessibilityState={{ selected: shown }}
        onPress={() => setShown(!shown)}
        hitSlop={8}
        style={styles.toggle}
      >
        <Text style={[styles.toggleText, { color: palette.toggle }]}>
          {shown ? "Hide" : "Show"}
        </Text>
      </Pressable>
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  root: { flexDirection: "row", alignItems: "center", borderWidth: 2, borderRadius: 14 },
  input: { flex: 1, minWidth: 0, height: 50, paddingHorizontal: 14, fontSize: 16 },
  toggle: { paddingHorizontal: 14, height: 50, justifyContent: "center", userSelect: "none" },
  toggleText: { fontSize: 14, fontWeight: "700" },
});
```

---

# Resend Button

> A React Native resend code link that waits out a countdown, pulses when ready and starts over after each press.

Install: `npx @modus-ui/cli add resend-button`

The "Resend code" link under a verification form. It starts out waiting, showing the seconds left, and becomes pressable when the wait is over, pulsing once to say so. Pressing it calls `onResend` and starts the wait again. The time is not announced each second, only "You can resend now". Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add resend-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/resend-button.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { ResendButton } from "@/components/ui/resend-button";

export default function Example() {
  return <ResendButton onResend={() => console.log("sent again")} />;
}
```

## Props

| Prop       | Type                          | Default         | Description                                                 |
| :--------- | :---------------------------- | :-------------- | :---------------------------------------------------------- |
| `onResend` | `() => void`                  | -               | Called when pressed after the wait; the wait then restarts. |
| `seconds`  | `number`                      | `30`            | How long to wait before it can be pressed, in seconds.      |
| `label`    | `string`                      | `"Resend code"` | The button's text.                                          |
| `colors`   | `Partial<ResendButtonColors>` | -               | Overrides `accent` and `disabled`.                          |
| `style`    | `StyleProp<ViewStyle>`        | -               | Style for the button.                                       |

## Source

`components/ui/resend-button.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface ResendButtonColors {
  accent: string;
  disabled: string;
}

const DEFAULT_COLORS: ResendButtonColors = {
  accent: "#4f46e5",
  disabled: "#9ca3af",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ResendButtonProps {
  /** Called when the button is pressed after the wait; the wait then starts over. */
  onResend: () => void;
  /** How long to wait before it can be pressed, in seconds. */
  seconds?: number;
  label?: string;
  colors?: Partial<ResendButtonColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * The "Resend code" link under a verification form. It starts out waiting, showing the seconds left,
 * and becomes pressable when the wait is over, pulsing once to say so. Pressing it calls
 * `onResend` and starts the wait again. The time is not announced each second; only "You can resend
 * now" is.
 */
export function ResendButton({
  onResend,
  seconds = 30,
  label = "Resend code",
  colors,
  style,
}: ResendButtonProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [left, setLeft] = useState(seconds);
  const pulse = useRef(new Animated.Value(1)).current;
  const ready = left <= 0;

  useEffect(() => {
    if (ready) return;
    const id = setInterval(() => setLeft((s) => Math.max(0, s - 1)), 1000);
    return () => clearInterval(id);
  }, [ready]);

  useEffect(() => {
    if (!ready || reduceMotion) return;
    Animated.sequence([
      Animated.timing(pulse, { toValue: 1.12, duration: 160, useNativeDriver: NATIVE_DRIVER }),
      Animated.spring(pulse, {
        toValue: 1,
        stiffness: 400,
        damping: 14,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }),
    ]).start();
  }, [ready, reduceMotion, pulse]);

  const text = ready
    ? label
    : `${label} in ${Math.floor(left / 60)}:${String(left % 60).padStart(2, "0")}`;

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={ready ? label : `${label}, available soon`}
      accessibilityState={{ disabled: !ready }}
      aria-disabled={!ready}
      disabled={!ready}
      onPress={() => {
        onResend();
        setLeft(seconds);
      }}
      hitSlop={8}
      style={[styles.root, style]}
    >
      <Animated.Text
        style={[
          styles.text,
          { color: ready ? palette.accent : palette.disabled, transform: [{ scale: pulse }] },
        ]}
      >
        {text}
      </Animated.Text>
      <Text accessibilityLiveRegion="polite" style={styles.sr}>
        {ready ? "You can resend now" : ""}
      </Text>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  root: { alignSelf: "center", minHeight: 44, justifyContent: "center", userSelect: "none" },
  text: { fontSize: 15, fontWeight: "700", fontVariant: ["tabular-nums"] },
  sr: { position: "absolute", width: 1, height: 1, opacity: 0 },
});
```

---

# Gauge Meter

> A React Native half-circle gauge whose arc springs round to the value, built from clipped Views with no SVG package.

Install: `npx @modus-ui/cli add gauge-meter`

A half-circle gauge. The arc sweeps round from the left to the value on a spring, with the percentage in the middle and an optional caption below it. The arc is built from clipped, rotated Views, so it needs no SVG package. It reads out as a progress bar. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add gauge-meter
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/gauge-meter.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { GaugeMeter } from "@/components/ui/gauge-meter";

export default function Example() {
  return <GaugeMeter value={0.62} caption="Storage used" />;
}
```

## Props

| Prop        | Type                        | Default   | Description                                      |
| :---------- | :-------------------------- | :-------- | :----------------------------------------------- |
| `value`     | `number`                    | -         | Progress from 0 to 1.                            |
| `size`      | `number`                    | `220`     | Width of the gauge; its height is half of this.  |
| `thickness` | `number`                    | `18`      | Width of the arc.                                |
| `caption`   | `string`                    | -         | Text under the number.                           |
| `label`     | `string`                    | `"Gauge"` | Spoken name of the gauge.                        |
| `colors`    | `Partial<GaugeMeterColors>` | -         | Overrides `track`, `fill`, `text` and `caption`. |
| `style`     | `StyleProp<ViewStyle>`      | -         | Style for the gauge's box.                       |

## Source

`components/ui/gauge-meter.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface GaugeMeterColors {
  track: string;
  fill: string;
  text: string;
  caption: string;
}

const DEFAULT_COLORS: GaugeMeterColors = {
  track: "#e5e7eb",
  fill: "#4f46e5",
  text: "#111827",
  caption: "#6b7280",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface GaugeMeterProps {
  /** Progress from 0 to 1. */
  value: number;
  /** Width of the gauge; its height is half of this. */
  size?: number;
  /** Width of the arc. */
  thickness?: number;
  /** Text under the number. */
  caption?: string;
  /** Spoken name of the gauge. */
  label?: string;
  colors?: Partial<GaugeMeterColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A half-circle gauge. The arc sweeps round from the left to the value on a spring, with the
 * percentage in the middle and an optional caption below it. The arc is built from clipped, rotated
 * Views, so it needs no SVG package. Reads out as a progress bar.
 */
export function GaugeMeter({
  value,
  size = 220,
  thickness = 18,
  caption,
  label = "Gauge",
  colors,
  style,
}: GaugeMeterProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const clamped = Math.max(0, Math.min(1, value));
  const sweep = useRef(new Animated.Value(clamped)).current;
  const percent = Math.round(clamped * 100);

  useEffect(() => {
    if (reduceMotion) {
      sweep.setValue(clamped);
      return;
    }
    Animated.spring(sweep, {
      toValue: clamped,
      stiffness: 120,
      damping: 18,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start();
  }, [clamped, reduceMotion, sweep]);

  const ring = {
    position: "absolute" as const,
    top: 0,
    left: 0,
    width: size,
    height: size,
    borderRadius: size / 2,
    borderWidth: thickness,
  };

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel={label}
      aria-label={label}
      accessibilityValue={{ min: 0, max: 100, now: percent }}
      aria-valuemin={0}
      aria-valuemax={100}
      aria-valuenow={percent}
      style={[{ width: size, height: size / 2 + 8 }, style]}
    >
      <View style={{ width: size, height: size / 2, overflow: "hidden" }}>
        <View style={[ring, { borderColor: palette.track }]} />
        <Animated.View
          style={[
            ring,
            {
              borderColor: "transparent",
              borderTopColor: palette.fill,
              borderLeftColor: palette.fill,
              transform: [
                {
                  rotate: sweep.interpolate({
                    inputRange: [0, 1],
                    outputRange: ["-135deg", "45deg"],
                  }),
                },
              ],
            },
          ]}
        />
      </View>
      <View style={[styles.center, { width: size }]}>
        <Text style={[styles.number, { color: palette.text, fontSize: size * 0.2 }]}>
          {percent}%
        </Text>
        {caption ? (
          <Text style={[styles.caption, { color: palette.caption }]}>{caption}</Text>
        ) : null}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  center: { position: "absolute", bottom: 0, alignItems: "center" },
  number: { fontWeight: "800", lineHeight: 44 },
  caption: { fontSize: 13 },
});
```

---

# Undo Snackbar

> A React Native snackbar with an Undo button that slides up, shows a draining timer line and closes itself.

Install: `npx @modus-ui/cli add undo-snackbar`

The bar that appears after a delete with an Undo button. It slides up from the bottom of its parent, a thin line along its edge shows how long is left, and it closes itself when that runs out. The message is announced when it opens, and the action is an ordinary button. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add undo-snackbar
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/undo-snackbar.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { UndoSnackbar } from "@/components/ui/undo-snackbar";

export default function Example() {
  const [open, setOpen] = useState(true);

  return (
    <UndoSnackbar
      open={open}
      message="Note deleted"
      onAction={() => {}}
      onClose={() => setOpen(false)}
    />
  );
}
```

## Props

| Prop          | Type                          | Default  | Description                                             |
| :------------ | :---------------------------- | :------- | :------------------------------------------------------ |
| `open`        | `boolean`                     | -        | Whether the snackbar is showing.                        |
| `onClose`     | `() => void`                  | -        | Called when the time runs out or the action is pressed. |
| `message`     | `string`                      | -        | What happened.                                          |
| `actionLabel` | `string`                      | `"Undo"` | The button's text.                                      |
| `onAction`    | `() => void`                  | -        | Called when the action is pressed, before it closes.    |
| `duration`    | `number`                      | `5000`   | How long it stays, in milliseconds.                     |
| `colors`      | `Partial<UndoSnackbarColors>` | -        | Overrides `background`, `text`, `action` and `timer`.   |
| `style`       | `StyleProp<ViewStyle>`        | -        | Style for the bar.                                      |

## Source

`components/ui/undo-snackbar.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface UndoSnackbarColors {
  background: string;
  text: string;
  action: string;
  timer: string;
}

const DEFAULT_COLORS: UndoSnackbarColors = {
  background: "#111827",
  text: "#ffffff",
  action: "#a5b4fc",
  timer: "rgba(255, 255, 255, 0.35)",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface UndoSnackbarProps {
  open: boolean;
  /** Called when the time runs out or the action is pressed. */
  onClose: () => void;
  message: string;
  actionLabel?: string;
  /** Called when the action is pressed, before the snackbar closes. */
  onAction?: () => void;
  /** How long it stays, in milliseconds. */
  duration?: number;
  colors?: Partial<UndoSnackbarColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * The bar that appears after a delete with an Undo button. It slides up from the bottom of its parent,
 * a thin line along its edge shows how long is left, and it closes itself when that runs out. The
 * message is announced when it opens, and the action is an ordinary button.
 */
export function UndoSnackbar({
  open,
  onClose,
  message,
  actionLabel = "Undo",
  onAction,
  duration = 5000,
  colors,
  style,
}: UndoSnackbarProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const t = useRef(new Animated.Value(0)).current;
  const timer = useRef(new Animated.Value(1)).current;
  const [mounted, setMounted] = useState(open);
  const live = useRef({ onClose });
  live.current = { onClose };

  useEffect(() => {
    if (open) setMounted(true);
    if (reduceMotion) {
      t.setValue(open ? 1 : 0);
      if (!open) setMounted(false);
      return;
    }
    Animated.spring(t, {
      toValue: open ? 1 : 0,
      stiffness: 380,
      damping: 30,
      mass: 1,
      useNativeDriver: NATIVE_DRIVER,
    }).start(({ finished }) => {
      if (finished && !open) setMounted(false);
    });
  }, [open, reduceMotion, t]);

  useEffect(() => {
    if (!open) return;
    AccessibilityInfo.announceForAccessibility(message);
    timer.setValue(1);
    const drain = Animated.timing(timer, {
      toValue: 0,
      duration,
      easing: Easing.linear,
      useNativeDriver: false,
    });
    if (!reduceMotion) drain.start();
    const id = setTimeout(() => live.current.onClose(), duration);
    return () => {
      drain.stop();
      clearTimeout(id);
    };
  }, [open, message, duration, reduceMotion, timer]);

  if (!mounted) return null;

  return (
    <Animated.View
      accessibilityLiveRegion="polite"
      style={[
        styles.root,
        {
          backgroundColor: palette.background,
          opacity: t,
          transform: [{ translateY: t.interpolate({ inputRange: [0, 1], outputRange: [40, 0] }) }],
        },
        style,
      ]}
    >
      <View style={styles.row}>
        <Text style={[styles.message, { color: palette.text }]}>{message}</Text>
        <Pressable
          accessibilityRole="button"
          accessibilityLabel={actionLabel}
          onPress={() => {
            onAction?.();
            onClose();
          }}
          hitSlop={8}
          style={styles.action}
        >
          <Text style={[styles.actionText, { color: palette.action }]}>{actionLabel}</Text>
        </Pressable>
      </View>
      <Animated.View
        pointerEvents="none"
        style={[
          styles.timer,
          {
            backgroundColor: palette.timer,
            width: timer.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
          },
        ]}
      />
    </Animated.View>
  );
}

const styles = StyleSheet.create({
  root: {
    position: "absolute",
    left: 16,
    right: 16,
    bottom: 16,
    borderRadius: 14,
    overflow: "hidden",
    boxShadow: "0 8px 24px rgba(0, 0, 0, 0.25)",
  },
  row: { flexDirection: "row", alignItems: "center", gap: 12, paddingLeft: 16, minHeight: 52 },
  message: { flex: 1, fontSize: 15 },
  action: { minHeight: 52, paddingHorizontal: 16, justifyContent: "center", userSelect: "none" },
  actionText: { fontSize: 15, fontWeight: "800" },
  timer: { height: 3 },
});
```

---

# Mood Picker

> A React Native row of faces for rating how something felt, where the chosen face swells with a bounce and shows its name.

Install: `npx @modus-ui/cli add mood-picker`

A row of faces for rating how something felt, from awful to great. The chosen face swells with a bounce and its name appears beneath it while the others dim. The faces form a radio group, so a screen reader reads each name and which one is chosen. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add mood-picker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/mood-picker.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { MoodPicker } from "@/components/ui/mood-picker";

export default function Example() {
  const [mood, setMood] = useState<number | null>(null);

  return <MoodPicker value={mood} onChange={setMood} />;
}
```

## Props

| Prop       | Type                        | Default                                     | Description                                |
| :--------- | :-------------------------- | :------------------------------------------ | :----------------------------------------- |
| `value`    | `number \| null`            | -                                           | The chosen index, or null for none.        |
| `onChange` | `(index: number) => void`   | -                                           | Called with the index of the pressed face. |
| `icons`    | `string[]`                  | `["😡", "🙁", "😐", "🙂", "😍"]`            | One glyph per level, worst first.          |
| `labels`   | `string[]`                  | `["Awful", "Bad", "Okay", "Good", "Great"]` | One spoken name per level.                 |
| `colors`   | `Partial<MoodPickerColors>` | -                                           | Overrides `accent`, `surface` and `text`.  |
| `style`    | `StyleProp<ViewStyle>`      | -                                           | Style for the row.                         |

## Source

`components/ui/mood-picker.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface MoodPickerColors {
  accent: string;
  surface: string;
  text: string;
}

const DEFAULT_COLORS: MoodPickerColors = {
  accent: "#eef2ff",
  surface: "#f3f4f6",
  text: "#374151",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface MoodPickerProps {
  /** The chosen index, or null for none. */
  value: number | null;
  onChange: (index: number) => void;
  /** One glyph per level, worst first. */
  icons?: string[];
  /** One spoken name per level, matching icons. */
  labels?: string[];
  colors?: Partial<MoodPickerColors>;
  style?: StyleProp<ViewStyle>;
}

const ICONS = ["😡", "🙁", "😐", "🙂", "😍"];
const LABELS = ["Awful", "Bad", "Okay", "Good", "Great"];

function Face({
  icon,
  label,
  selected,
  dimmed,
  palette,
  reduceMotion,
  onPress,
  index,
  count,
}: {
  icon: string;
  label: string;
  selected: boolean;
  dimmed: boolean;
  palette: MoodPickerColors;
  reduceMotion: boolean;
  onPress: () => void;
  index: number;
  count: number;
}) {
  const grow = useRef(new Animated.Value(selected ? 1 : 0)).current;
  useEffect(() => {
    if (reduceMotion) grow.setValue(selected ? 1 : 0);
    else
      Animated.spring(grow, {
        toValue: selected ? 1 : 0,
        stiffness: 420,
        damping: 15,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
  }, [selected, reduceMotion, grow]);

  return (
    <Pressable
      accessibilityRole="radio"
      accessibilityLabel={label}
      accessibilityState={{ checked: selected }}
      aria-checked={selected}
      aria-posinset={index + 1}
      aria-setsize={count}
      onPress={onPress}
      style={styles.face}
    >
      <Animated.View
        style={[
          styles.bubble,
          {
            backgroundColor: selected ? palette.accent : palette.surface,
            opacity: dimmed ? 0.45 : 1,
            transform: [
              { scale: grow.interpolate({ inputRange: [0, 1], outputRange: [1, 1.25] }) },
            ],
          },
        ]}
      >
        <Text style={styles.icon}>{icon}</Text>
      </Animated.View>
      <Text style={[styles.label, { color: palette.text, opacity: selected ? 1 : 0 }]}>
        {label}
      </Text>
    </Pressable>
  );
}

/**
 * A row of faces for rating how something felt, from awful to great. The chosen face swells with a
 * bounce and its name appears beneath it while the others dim. The faces form a radio group, so a
 * screen reader reads each name and which one is chosen.
 */
export function MoodPicker({
  value,
  onChange,
  icons = ICONS,
  labels = LABELS,
  colors,
  style,
}: MoodPickerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  return (
    <View
      accessibilityRole="radiogroup"
      accessibilityLabel="How was it?"
      style={[styles.row, style]}
    >
      {icons.map((icon, i) => (
        <Face
          key={i}
          icon={icon}
          label={labels[i] ?? String(i + 1)}
          index={i}
          count={icons.length}
          selected={value === i}
          dimmed={value !== null && value !== i}
          palette={palette}
          reduceMotion={reduceMotion}
          onPress={() => onChange(i)}
        />
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", justifyContent: "space-between" },
  face: { alignItems: "center", gap: 8, userSelect: "none" },
  bubble: {
    width: 52,
    height: 52,
    borderRadius: 26,
    alignItems: "center",
    justifyContent: "center",
  },
  icon: { fontSize: 28 },
  label: { fontSize: 12, fontWeight: "700" },
});
```

---

# Expandable Text

> A React Native paragraph that clamps to a few lines with a Read more link that grows the box to the full text.

Install: `npx @modus-ui/cli add expandable-text`

A paragraph that shows a few lines and a Read more link. Pressing the link grows the box to the full text, and it shrinks back on Show less. The link only appears when the text is long enough to be cut, and it reports whether it is expanded. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add expandable-text
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/expandable-text.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { ExpandableText } from "@/components/ui/expandable-text";

export default function Example() {
  return <ExpandableText text="A long paragraph of text goes here..." lines={3} />;
}
```

## Props

| Prop         | Type                            | Default       | Description                               |
| :----------- | :------------------------------ | :------------ | :---------------------------------------- |
| `text`       | `string`                        | -             | The paragraph.                            |
| `lines`      | `number`                        | `3`           | How many lines show before it is cut off. |
| `lineHeight` | `number`                        | `22`          | Height of one line.                       |
| `moreLabel`  | `string`                        | `"Read more"` | Text of the link while collapsed.         |
| `lessLabel`  | `string`                        | `"Show less"` | Text of the link while expanded.          |
| `colors`     | `Partial<ExpandableTextColors>` | -             | Overrides `text` and `link`.              |
| `style`      | `StyleProp<ViewStyle>`          | -             | Style for the whole block.                |

## Source

`components/ui/expandable-text.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface ExpandableTextColors {
  text: string;
  link: string;
}

const DEFAULT_COLORS: ExpandableTextColors = {
  text: "#374151",
  link: "#4f46e5",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ExpandableTextProps {
  text: string;
  /** How many lines show before it is cut off. */
  lines?: number;
  /** Height of one line. */
  lineHeight?: number;
  moreLabel?: string;
  lessLabel?: string;
  colors?: Partial<ExpandableTextColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A paragraph that shows a few lines and a Read more link. Pressing the link grows the box to the
 * full text, and it shrinks back on Show less; the link only appears when the text is long enough to
 * be cut. The link reports whether it is expanded.
 */
export function ExpandableText({
  text,
  lines = 3,
  lineHeight = 22,
  moreLabel = "Read more",
  lessLabel = "Show less",
  colors,
  style,
}: ExpandableTextProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [expanded, setExpanded] = useState(false);
  const [full, setFull] = useState(0);
  const collapsed = lines * lineHeight;
  const height = useRef(new Animated.Value(collapsed)).current;
  const long = full > collapsed + 1;

  useEffect(() => {
    if (full === 0) return;
    const toValue = expanded && long ? full : collapsed;
    if (reduceMotion) height.setValue(toValue);
    else
      Animated.timing(height, {
        toValue,
        duration: 260,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [expanded, full, long, collapsed, reduceMotion, height]);

  return (
    <View style={style}>
      <Animated.View style={{ height: long ? height : undefined, overflow: "hidden" }}>
        <Text
          onLayout={(event: LayoutChangeEvent) => setFull(event.nativeEvent.layout.height)}
          style={[styles.text, { color: palette.text, lineHeight }]}
        >
          {text}
        </Text>
      </Animated.View>
      {long ? (
        <Pressable
          accessibilityRole="button"
          accessibilityLabel={expanded ? lessLabel : moreLabel}
          accessibilityState={{ expanded }}
          aria-expanded={expanded}
          onPress={() => setExpanded(!expanded)}
          hitSlop={8}
          style={styles.link}
        >
          <Text style={[styles.linkText, { color: palette.link }]}>
            {expanded ? lessLabel : moreLabel}
          </Text>
        </Pressable>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  text: { fontSize: 15 },
  link: { alignSelf: "flex-start", minHeight: 40, justifyContent: "center", userSelect: "none" },
  linkText: { fontSize: 15, fontWeight: "700" },
});
```

---

# Extended FAB

> A React Native floating action button with a label that slides away to leave a circle when collapsed.

Install: `npx @modus-ui/cli add extended-fab`

A floating action button with a label. While `collapsed` is false it shows icon and label; when it turns true the label slides away and the button shrinks to a circle, the way the compose button folds up as a list scrolls. The label stays in the accessibility tree either way. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add extended-fab
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/extended-fab.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { ExtendedFab } from "@/components/ui/extended-fab";

export default function Example() {
  return <ExtendedFab label="Compose" icon="✎" collapsed={false} onPress={() => {}} />;
}
```

## Props

| Prop        | Type                         | Default | Description                          |
| :---------- | :--------------------------- | :------ | :----------------------------------- |
| `label`     | `string`                     | -       | The button's text.                   |
| `onPress`   | `() => void`                 | -       | Called when the button is pressed.   |
| `icon`      | `string`                     | `"+"`   | A glyph drawn before the label.      |
| `collapsed` | `boolean`                    | `false` | Shrinks the button to just its icon. |
| `colors`    | `Partial<ExtendedFabColors>` | -       | Overrides `background` and `text`.   |
| `style`     | `StyleProp<ViewStyle>`       | -       | Style for the button's wrapper.      |

## Source

`components/ui/extended-fab.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const SIZE = 56;

export interface ExtendedFabColors {
  background: string;
  text: string;
}

const DEFAULT_COLORS: ExtendedFabColors = {
  background: "#4f46e5",
  text: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface ExtendedFabProps {
  label: string;
  onPress: () => void;
  /** A glyph drawn before the label. */
  icon?: string;
  /** Shrinks the button to just its icon, for example while a list is scrolling down. */
  collapsed?: boolean;
  colors?: Partial<ExtendedFabColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A floating action button with a label. While `collapsed` is false it shows icon and label; when it
 * turns true the label slides away and the button shrinks to a circle, the way the compose button
 * folds up as a list scrolls. The label stays in the accessibility tree either way.
 */
export function ExtendedFab({
  label,
  onPress,
  icon = "+",
  collapsed = false,
  colors,
  style,
}: ExtendedFabProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [labelWidth, setLabelWidth] = useState(0);
  const t = useRef(new Animated.Value(collapsed ? 0 : 1)).current;

  useEffect(() => {
    const toValue = collapsed ? 0 : 1;
    if (reduceMotion) t.setValue(toValue);
    else
      Animated.timing(t, {
        toValue,
        duration: 240,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [collapsed, reduceMotion, t]);

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={label}
      onPress={onPress}
      style={[styles.hit, style]}
    >
      <Animated.View
        style={[
          styles.fab,
          {
            backgroundColor: palette.background,
            width: t.interpolate({
              inputRange: [0, 1],
              outputRange: [SIZE, SIZE + labelWidth + 8],
            }),
          },
        ]}
      >
        <Text style={[styles.icon, { color: palette.text }]}>{icon}</Text>
        <Animated.View style={{ opacity: t, width: labelWidth || undefined }}>
          <Text
            numberOfLines={1}
            onLayout={(event: LayoutChangeEvent) =>
              setLabelWidth(Math.ceil(event.nativeEvent.layout.width))
            }
            style={[styles.label, { color: palette.text }]}
          >
            {label}
          </Text>
        </Animated.View>
      </Animated.View>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  hit: { alignSelf: "flex-start", userSelect: "none" },
  fab: {
    height: SIZE,
    borderRadius: SIZE / 2,
    flexDirection: "row",
    alignItems: "center",
    overflow: "hidden",
    boxShadow: "0 6px 16px rgba(0, 0, 0, 0.25)",
  },
  icon: { width: SIZE, textAlign: "center", fontSize: 26, fontWeight: "500" },
  label: { fontSize: 15, fontWeight: "700", marginLeft: -4 },
});
```

---

# Swatch Picker

> A React Native colour picker of circles where the chosen one gets a ring that springs out and a tick inside.

Install: `npx @modus-ui/cli add swatch-picker`

A row of colour circles to choose from, such as a theme or a label colour. The chosen one gets a ring that springs out around it and a tick inside. The circles are a radio group and each is read out by the name you give it, not by its hex code. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add swatch-picker
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/swatch-picker.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { SwatchPicker } from "@/components/ui/swatch-picker";

export default function Example() {
  const [color, setColor] = useState("#3b82f6");

  return (
    <SwatchPicker
      value={color}
      onChange={setColor}
      options={[
        { value: "#ef4444", label: "Red" },
        { value: "#3b82f6", label: "Blue" },
      ]}
    />
  );
}
```

## Props

| Prop       | Type                          | Default | Description                                            |
| :--------- | :---------------------------- | :------ | :----------------------------------------------------- |
| `options`  | `Swatch[]`                    | -       | The colours, each with a `value` and a spoken `label`. |
| `value`    | `string`                      | -       | The chosen swatch's colour value.                      |
| `onChange` | `(value: string) => void`     | -       | Called with the pressed swatch's value.                |
| `size`     | `number`                      | `36`    | Diameter of a swatch.                                  |
| `colors`   | `Partial<SwatchPickerColors>` | -       | Overrides `ring` and `check`.                          |
| `style`    | `StyleProp<ViewStyle>`        | -       | Style for the row of swatches.                         |

## Source

`components/ui/swatch-picker.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface Swatch {
  /** A CSS colour such as "#ef4444". */
  value: string;
  /** Spoken name, such as "Red". */
  label: string;
}

export interface SwatchPickerColors {
  ring: string;
  check: string;
}

const DEFAULT_COLORS: SwatchPickerColors = {
  ring: "#111827",
  check: "#ffffff",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SwatchPickerProps {
  options: Swatch[];
  /** The chosen swatch's colour value. */
  value: string;
  onChange: (value: string) => void;
  /** Diameter of a swatch. */
  size?: number;
  colors?: Partial<SwatchPickerColors>;
  style?: StyleProp<ViewStyle>;
}

function Dot({
  swatch,
  selected,
  size,
  palette,
  reduceMotion,
  onPress,
  index,
  count,
}: {
  swatch: Swatch;
  selected: boolean;
  size: number;
  palette: SwatchPickerColors;
  reduceMotion: boolean;
  onPress: () => void;
  index: number;
  count: number;
}) {
  const pick = useRef(new Animated.Value(selected ? 1 : 0)).current;
  useEffect(() => {
    if (reduceMotion) pick.setValue(selected ? 1 : 0);
    else
      Animated.spring(pick, {
        toValue: selected ? 1 : 0,
        stiffness: 420,
        damping: 18,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
  }, [selected, reduceMotion, pick]);

  const outer = size + 12;
  return (
    <Pressable
      accessibilityRole="radio"
      accessibilityLabel={swatch.label}
      accessibilityState={{ checked: selected }}
      aria-checked={selected}
      aria-posinset={index + 1}
      aria-setsize={count}
      onPress={onPress}
      style={{ width: outer, height: outer, alignItems: "center", justifyContent: "center" }}
    >
      <Animated.View
        pointerEvents="none"
        style={{
          position: "absolute",
          width: outer,
          height: outer,
          borderRadius: outer / 2,
          borderWidth: 2,
          borderColor: palette.ring,
          opacity: pick,
          transform: [{ scale: pick.interpolate({ inputRange: [0, 1], outputRange: [0.7, 1] }) }],
        }}
      />
      <View
        style={{
          width: size,
          height: size,
          borderRadius: size / 2,
          backgroundColor: swatch.value,
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        <Animated.Text
          style={{
            color: palette.check,
            fontSize: size * 0.45,
            fontWeight: "800",
            opacity: pick,
            transform: [{ scale: pick }],
          }}
        >
          ✓
        </Animated.Text>
      </View>
    </Pressable>
  );
}

/**
 * A row of colour circles to choose from, such as a theme or a label colour. The chosen one gets a ring
 * that springs out around it and a tick inside. The circles are a radio group and each is read out by
 * the name you give it, not by its hex code.
 */
export function SwatchPicker({
  options,
  value,
  onChange,
  size = 36,
  colors,
  style,
}: SwatchPickerProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();

  return (
    <View accessibilityRole="radiogroup" accessibilityLabel="Colour" style={[styles.row, style]}>
      {options.map((swatch, i) => (
        <Dot
          key={swatch.value}
          swatch={swatch}
          index={i}
          count={options.length}
          selected={swatch.value === value}
          size={size}
          palette={palette}
          reduceMotion={reduceMotion}
          onPress={() => onChange(swatch.value)}
        />
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", flexWrap: "wrap", gap: 2, userSelect: "none" },
});
```

---

# Like Button

> A React Native heart button that pops on like with a ring of sparks flying outward, and shrinks quietly when unliked.

Install: `npx @modus-ui/cli add like-button`

A heart button. Liking pops the heart past full size and settles it back while a ring of sparks flies outward and fades; unliking just shrinks it quietly. The button reports whether it is pressed and the count is part of its spoken name. With reduced motion the colour changes and nothing else. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add like-button
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/like-button.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { LikeButton } from "@/components/ui/like-button";

export default function Example() {
  const [liked, setLiked] = useState(false);

  return <LikeButton liked={liked} onChange={setLiked} count={128} />;
}
```

## Props

| Prop       | Type                        | Default | Description                            |
| :--------- | :-------------------------- | :------ | :------------------------------------- |
| `liked`    | `boolean`                   | -       | Whether the heart is filled.           |
| `onChange` | `(liked: boolean) => void`  | -       | Called with the new state.             |
| `count`    | `number`                    | -       | Shows a number beside the heart.       |
| `size`     | `number`                    | `28`    | Size of the heart.                     |
| `colors`   | `Partial<LikeButtonColors>` | -       | Overrides `liked`, `idle` and `count`. |
| `style`    | `StyleProp<ViewStyle>`      | -       | Style for the button.                  |

## Source

`components/ui/like-button.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const SPARKS = 8;

export interface LikeButtonColors {
  liked: string;
  idle: string;
  count: string;
}

const DEFAULT_COLORS: LikeButtonColors = {
  liked: "#ef4444",
  idle: "#9ca3af",
  count: "#374151",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface LikeButtonProps {
  liked: boolean;
  onChange: (liked: boolean) => void;
  /** Shows a number beside the heart. */
  count?: number;
  /** Size of the heart. */
  size?: number;
  colors?: Partial<LikeButtonColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A heart button. Liking pops the heart past full size and settles it back while a ring of sparks
 * flies outward and fades; unliking just shrinks it quietly. The button reports whether it is pressed
 * and the count is part of its spoken name. With reduced motion the colour changes and nothing else.
 */
export function LikeButton({ liked, onChange, count, size = 28, colors, style }: LikeButtonProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const pop = useRef(new Animated.Value(1)).current;
  const burst = useRef(new Animated.Value(0)).current;
  const first = useRef(true);

  useEffect(() => {
    if (first.current) {
      first.current = false;
      return;
    }
    if (reduceMotion) return;
    if (liked) {
      pop.setValue(0.6);
      Animated.spring(pop, {
        toValue: 1,
        stiffness: 300,
        damping: 9,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
      burst.setValue(0);
      Animated.timing(burst, {
        toValue: 1,
        duration: 480,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    } else {
      pop.setValue(0.8);
      Animated.spring(pop, {
        toValue: 1,
        stiffness: 400,
        damping: 20,
        mass: 1,
        useNativeDriver: NATIVE_DRIVER,
      }).start();
    }
  }, [liked, reduceMotion, pop, burst]);

  const spark = size * 0.14;
  const reach = size * 0.95;

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={count === undefined ? "Like" : `Like, ${count} likes`}
      accessibilityState={{ selected: liked }}
      aria-pressed={liked}
      onPress={() => onChange(!liked)}
      hitSlop={8}
      style={[styles.root, style]}
    >
      <View
        style={{
          width: size + 8,
          height: size + 8,
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        {Array.from({ length: SPARKS }, (_, i) => {
          const angle = (i / SPARKS) * Math.PI * 2;
          return (
            <Animated.View
              key={i}
              pointerEvents="none"
              style={{
                position: "absolute",
                width: spark,
                height: spark,
                borderRadius: spark / 2,
                backgroundColor: palette.liked,
                opacity: burst.interpolate({ inputRange: [0, 0.2, 1], outputRange: [0, 1, 0] }),
                transform: [
                  {
                    translateX: burst.interpolate({
                      inputRange: [0, 1],
                      outputRange: [0, Math.cos(angle) * reach],
                    }),
                  },
                  {
                    translateY: burst.interpolate({
                      inputRange: [0, 1],
                      outputRange: [0, Math.sin(angle) * reach],
                    }),
                  },
                  { scale: burst.interpolate({ inputRange: [0, 1], outputRange: [1, 0.3] }) },
                ],
              }}
            />
          );
        })}
        <Animated.Text
          style={{
            fontSize: size,
            color: liked ? palette.liked : palette.idle,
            transform: [{ scale: pop }],
          }}
        >
          {liked ? "♥" : "♡"}
        </Animated.Text>
      </View>
      {count !== undefined ? (
        <Text style={[styles.count, { color: palette.count }]}>{count}</Text>
      ) : null}
    </Pressable>
  );
}

const styles = StyleSheet.create({
  root: {
    flexDirection: "row",
    alignItems: "center",
    gap: 4,
    alignSelf: "flex-start",
    userSelect: "none",
  },
  count: { fontSize: 15, fontWeight: "700", minWidth: 20 },
});
```

---

# Task Checklist

> A React Native to-do list with a progress bar, where ticking a task draws a strike-through line across its text.

Install: `npx @modus-ui/cli add task-checklist`

A to-do list with a progress bar above it. Ticking a task fills its box, greys its text and draws a line through it from left to right, and the bar grows to the share of tasks finished. Each task is a checkbox, and the progress is read out as "2 of 4 done". Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add task-checklist
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/task-checklist.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { TaskChecklist } from "@/components/ui/task-checklist";

export default function Example() {
  const [done, setDone] = useState<string[]>([]);

  return (
    <TaskChecklist
      items={[
        { id: "a", label: "Verify your email" },
        { id: "b", label: "Invite a teammate" },
      ]}
      value={done}
      onChange={setDone}
    />
  );
}
```

## Props

| Prop       | Type                           | Default | Description                                               |
| :--------- | :----------------------------- | :------ | :-------------------------------------------------------- |
| `items`    | `ChecklistItem[]`              | -       | The tasks, each with an `id` and a `label`.               |
| `value`    | `string[]`                     | -       | The ids of the finished tasks.                            |
| `onChange` | `(value: string[]) => void`    | -       | Called with the new list of finished ids.                 |
| `colors`   | `Partial<TaskChecklistColors>` | -       | Overrides `accent`, `text`, `done`, `track` and `border`. |
| `style`    | `StyleProp<ViewStyle>`         | -       | Style for the whole list.                                 |

## Source

`components/ui/task-checklist.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface ChecklistItem {
  id: string;
  label: string;
}

export interface TaskChecklistColors {
  accent: string;
  text: string;
  done: string;
  track: string;
  border: string;
}

const DEFAULT_COLORS: TaskChecklistColors = {
  accent: "#4f46e5",
  text: "#111827",
  done: "#9ca3af",
  track: "#e5e7eb",
  border: "#d1d5db",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface TaskChecklistProps {
  items: ChecklistItem[];
  /** The ids of the finished tasks. */
  value: string[];
  onChange: (value: string[]) => void;
  colors?: Partial<TaskChecklistColors>;
  style?: StyleProp<ViewStyle>;
}

function Row({
  item,
  done,
  palette,
  reduceMotion,
  onToggle,
}: {
  item: ChecklistItem;
  done: boolean;
  palette: TaskChecklistColors;
  reduceMotion: boolean;
  onToggle: () => void;
}) {
  const t = useRef(new Animated.Value(done ? 1 : 0)).current;
  useEffect(() => {
    if (reduceMotion) t.setValue(done ? 1 : 0);
    else
      Animated.timing(t, {
        toValue: done ? 1 : 0,
        duration: 260,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [done, reduceMotion, t]);

  return (
    <Pressable
      accessibilityRole="checkbox"
      accessibilityLabel={item.label}
      accessibilityState={{ checked: done }}
      aria-checked={done}
      onPress={onToggle}
      style={styles.row}
    >
      <Animated.View
        style={[
          styles.box,
          {
            borderColor: t.interpolate({
              inputRange: [0, 1],
              outputRange: [palette.border, palette.accent],
            }),
            backgroundColor: t.interpolate({
              inputRange: [0, 1],
              outputRange: ["rgba(0,0,0,0)", palette.accent],
            }),
          },
        ]}
      >
        <Animated.Text style={[styles.tick, { opacity: t }]}>✓</Animated.Text>
      </Animated.View>
      <View style={styles.labelBox}>
        <Animated.Text
          style={[
            styles.label,
            {
              color: t.interpolate({
                inputRange: [0, 1],
                outputRange: [palette.text, palette.done],
              }),
            },
          ]}
        >
          {item.label}
        </Animated.Text>
        <Animated.View
          pointerEvents="none"
          style={[
            styles.strike,
            {
              backgroundColor: palette.done,
              width: t.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
            },
          ]}
        />
      </View>
    </Pressable>
  );
}

/**
 * A to-do list with a progress bar above it. Ticking a task fills its box, greys its text and draws a
 * line through it from left to right, and the bar grows to the share of tasks finished. Each task is
 * a checkbox, and the progress is read out as "2 of 4 done".
 */
export function TaskChecklist({ items, value, onChange, colors, style }: TaskChecklistProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const share = items.length
    ? value.filter((id) => items.some((item) => item.id === id)).length / items.length
    : 0;
  const bar = useRef(new Animated.Value(share)).current;
  const finished = Math.round(share * items.length);

  useEffect(() => {
    if (reduceMotion) bar.setValue(share);
    else
      Animated.timing(bar, {
        toValue: share,
        duration: 320,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [share, reduceMotion, bar]);

  const toggle = (id: string) =>
    onChange(value.includes(id) ? value.filter((v) => v !== id) : [...value, id]);

  return (
    <View style={[styles.root, style]}>
      <View
        accessible
        accessibilityRole="progressbar"
        accessibilityLabel={`${finished} of ${items.length} done`}
        accessibilityValue={{ min: 0, max: items.length, now: finished }}
        aria-valuemin={0}
        aria-valuemax={items.length}
        aria-valuenow={finished}
        aria-valuetext={`${finished} of ${items.length} done`}
        style={styles.progress}
      >
        <View style={[styles.track, { backgroundColor: palette.track }]}>
          <Animated.View
            style={[
              styles.fill,
              {
                backgroundColor: palette.accent,
                width: bar.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
              },
            ]}
          />
        </View>
        <Text style={[styles.count, { color: palette.done }]}>
          {finished}/{items.length}
        </Text>
      </View>
      {items.map((item) => (
        <Row
          key={item.id}
          item={item}
          done={value.includes(item.id)}
          palette={palette}
          reduceMotion={reduceMotion}
          onToggle={() => toggle(item.id)}
        />
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  root: { gap: 4 },
  progress: { flexDirection: "row", alignItems: "center", gap: 12, marginBottom: 8 },
  track: { flex: 1, height: 8, borderRadius: 4, overflow: "hidden" },
  fill: { height: "100%", borderRadius: 4 },
  count: { fontSize: 13, fontWeight: "700", minWidth: 28, textAlign: "right" },
  row: { flexDirection: "row", alignItems: "center", gap: 12, minHeight: 48, userSelect: "none" },
  box: {
    width: 24,
    height: 24,
    borderRadius: 8,
    borderWidth: 2,
    alignItems: "center",
    justifyContent: "center",
  },
  tick: { color: "#ffffff", fontSize: 14, fontWeight: "800" },
  labelBox: { flexShrink: 1, justifyContent: "center" },
  label: { fontSize: 16 },
  strike: { position: "absolute", left: 0, top: "52%", height: 2 },
});
```

---

# Spark Bars

> A tiny React Native bar chart for trends inside a card, whose bars grow up one after another and resize on change.

Install: `npx @modus-ui/cli add spark-bars`

A tiny bar chart for showing a trend inside a card. The bars grow up from the baseline one after another, resize when the values change, and the active bar takes the accent colour. It reads out as an image with every value listed, since the bars carry no labels. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add spark-bars
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/spark-bars.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { SparkBars } from "@/components/ui/spark-bars";

export default function Example() {
  return <SparkBars values={[12, 18, 9, 22, 30, 26, 34]} label="Steps per day" />;
}
```

## Props

| Prop        | Type                       | Default   | Description                                    |
| :---------- | :------------------------- | :-------- | :--------------------------------------------- |
| `values`    | `number[]`                 | -         | One value per bar; the tallest sets the scale. |
| `height`    | `number`                   | `48`      | Height of the tallest bar.                     |
| `gap`       | `number`                   | `4`       | Space between bars.                            |
| `highlight` | `number`                   | -         | Index of the active bar; defaults to the last. |
| `label`     | `string`                   | `"Chart"` | Spoken name of the chart.                      |
| `colors`    | `Partial<SparkBarsColors>` | -         | Overrides `bar` and `active`.                  |
| `style`     | `StyleProp<ViewStyle>`     | -         | Style for the row of bars.                     |

## Source

`components/ui/spark-bars.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  StyleSheet,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface SparkBarsColors {
  bar: string;
  active: string;
}

const DEFAULT_COLORS: SparkBarsColors = {
  bar: "#c7d2fe",
  active: "#4f46e5",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SparkBarsProps {
  /** One value per bar; the tallest sets the scale. */
  values: number[];
  /** Height of the tallest bar. */
  height?: number;
  /** Space between bars. */
  gap?: number;
  /** Index of the bar drawn in the active colour; defaults to the last. */
  highlight?: number;
  /** Spoken name of the chart. */
  label?: string;
  colors?: Partial<SparkBarsColors>;
  style?: StyleProp<ViewStyle>;
}

function Bar({
  share,
  height,
  color,
  index,
  reduceMotion,
}: {
  share: number;
  height: number;
  color: string;
  index: number;
  reduceMotion: boolean;
}) {
  const grow = useRef(new Animated.Value(0)).current;
  useEffect(() => {
    if (reduceMotion) {
      grow.setValue(share);
      return;
    }
    Animated.timing(grow, {
      toValue: share,
      duration: 420,
      delay: index * 40,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: false,
    }).start();
  }, [share, index, reduceMotion, grow]);
  return (
    <Animated.View
      style={{
        flex: 1,
        borderRadius: 4,
        backgroundColor: color,
        height: grow.interpolate({ inputRange: [0, 1], outputRange: [3, height] }),
      }}
    />
  );
}

/**
 * A tiny bar chart for showing a trend inside a card. The bars grow up from the baseline one after
 * another, resize when the values change, and the active bar takes the accent colour. It reads out as
 * an image with every value listed, since the bars carry no labels.
 */
export function SparkBars({
  values,
  height = 48,
  gap = 4,
  highlight,
  label = "Chart",
  colors,
  style,
}: SparkBarsProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const top = Math.max(...values, 1);
  const active = highlight ?? values.length - 1;

  return (
    <View
      accessible
      accessibilityRole="image"
      accessibilityLabel={`${label}: ${values.join(", ")}`}
      aria-label={`${label}: ${values.join(", ")}`}
      style={[styles.row, { height, gap }, style]}
    >
      {values.map((value, i) => (
        <Bar
          key={i}
          index={i}
          share={Math.max(0, value) / top}
          height={height}
          color={i === active ? palette.active : palette.bar}
          reduceMotion={reduceMotion}
        />
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "flex-end" },
});
```

---

# Battery Meter

> A React Native battery gauge whose fill slides to the level, turns red when low and pulses a bolt while charging.

Install: `npx @modus-ui/cli add battery-meter`

A battery gauge. The fill slides to the charge level and turns red below 20 percent, amber while charging, and green otherwise. While charging a bolt pulses over the cell. The level is read out with whether it is charging. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add battery-meter
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/battery-meter.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { BatteryMeter } from "@/components/ui/battery-meter";

export default function Example() {
  return <BatteryMeter level={0.64} charging />;
}
```

## Props

| Prop          | Type                          | Default | Description                                              |
| :------------ | :---------------------------- | :------ | :------------------------------------------------------- |
| `level`       | `number`                      | -       | Charge from 0 to 1.                                      |
| `charging`    | `boolean`                     | `false` | Shows the charging colour and a pulsing bolt.            |
| `width`       | `number`                      | `64`    | Width of the battery.                                    |
| `showPercent` | `boolean`                     | `true`  | Shows the percentage beside it.                          |
| `colors`      | `Partial<BatteryMeterColors>` | -       | Overrides `outline`, `low`, `ok`, `charging` and `text`. |
| `style`       | `StyleProp<ViewStyle>`        | -       | Style for the row.                                       |

## Source

`components/ui/battery-meter.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";

export interface BatteryMeterColors {
  outline: string;
  low: string;
  ok: string;
  charging: string;
  text: string;
}

const DEFAULT_COLORS: BatteryMeterColors = {
  outline: "#9ca3af",
  low: "#dc2626",
  ok: "#16a34a",
  charging: "#f59e0b",
  text: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface BatteryMeterProps {
  /** Charge from 0 to 1. */
  level: number;
  /** Shows the charging colour and a bolt that pulses. */
  charging?: boolean;
  /** Width of the battery. */
  width?: number;
  /** Shows the percentage beside it. */
  showPercent?: boolean;
  colors?: Partial<BatteryMeterColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A battery gauge. The fill slides to the charge level and turns red below 20 percent, amber while
 * charging, and green otherwise. While charging a bolt pulses over the cell. The level is read out
 * with whether it is charging.
 */
export function BatteryMeter({
  level,
  charging = false,
  width = 64,
  showPercent = true,
  colors,
  style,
}: BatteryMeterProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const clamped = Math.max(0, Math.min(1, level));
  const percent = Math.round(clamped * 100);
  const fill = useRef(new Animated.Value(clamped)).current;
  const pulse = useRef(new Animated.Value(0)).current;
  const tint = charging ? palette.charging : clamped < 0.2 ? palette.low : palette.ok;
  const height = width * 0.5;

  useEffect(() => {
    if (reduceMotion) fill.setValue(clamped);
    else
      Animated.timing(fill, {
        toValue: clamped,
        duration: 400,
        easing: Easing.out(Easing.cubic),
        useNativeDriver: false,
      }).start();
  }, [clamped, reduceMotion, fill]);

  useEffect(() => {
    if (!charging || reduceMotion) {
      pulse.setValue(charging ? 1 : 0);
      return;
    }
    const loop = Animated.loop(
      Animated.sequence([
        Animated.timing(pulse, {
          toValue: 1,
          duration: 700,
          easing: Easing.inOut(Easing.sin),
          useNativeDriver: NATIVE_DRIVER,
        }),
        Animated.timing(pulse, {
          toValue: 0.3,
          duration: 700,
          easing: Easing.inOut(Easing.sin),
          useNativeDriver: NATIVE_DRIVER,
        }),
      ]),
    );
    loop.start();
    return () => loop.stop();
  }, [charging, reduceMotion, pulse]);

  return (
    <View
      accessible
      accessibilityRole="progressbar"
      accessibilityLabel={`Battery ${percent} percent${charging ? ", charging" : ""}`}
      accessibilityValue={{ min: 0, max: 100, now: percent }}
      aria-valuemin={0}
      aria-valuemax={100}
      aria-valuenow={percent}
      style={[styles.row, style]}
    >
      <View style={styles.body}>
        <View
          style={[
            styles.shell,
            { width, height, borderColor: palette.outline, borderRadius: height * 0.28 },
          ]}
        >
          <Animated.View
            style={{
              margin: 3,
              height: height - 6 - 4,
              borderRadius: height * 0.18,
              backgroundColor: tint,
              width: fill.interpolate({ inputRange: [0, 1], outputRange: [0, width - 6 - 4] }),
            }}
          />
          <Animated.View pointerEvents="none" style={[styles.bolt, { opacity: pulse }]}>
            <Text style={[styles.boltText, { fontSize: height * 0.6 }]}>⚡</Text>
          </Animated.View>
        </View>
        <View style={[styles.cap, { height: height * 0.4, backgroundColor: palette.outline }]} />
      </View>
      {showPercent ? (
        <Text style={[styles.percent, { color: palette.text }]}>{percent}%</Text>
      ) : null}
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 10, alignSelf: "flex-start" },
  body: { flexDirection: "row", alignItems: "center" },
  shell: { borderWidth: 2, justifyContent: "center", overflow: "hidden" },
  cap: { width: 4, borderTopRightRadius: 2, borderBottomRightRadius: 2 },
  bolt: {
    position: "absolute",
    top: 0,
    right: 0,
    bottom: 0,
    left: 0,
    alignItems: "center",
    justifyContent: "center",
  },
  boltText: { color: "#ffffff" },
  percent: { fontSize: 15, fontWeight: "700", minWidth: 40 },
});
```

---

# Compare Slider

> A React Native before and after slider where dragging a handle reveals more of one side, steppable by screen readers.

Install: `npx @modus-ui/cli add compare-slider`

A before and after comparison. Drag the handle, or touch anywhere, and the divider follows to reveal more of one side or the other. It is an adjustable control for screen readers, which can step it by ten percent, and the position is read out as a percentage. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add compare-slider
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/compare-slider.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { Image } from "react-native";
import { CompareSlider } from "@/components/ui/compare-slider";

export default function Example() {
  return (
    <CompareSlider
      before={<Image source={require("./before.jpg")} style={{ flex: 1 }} />}
      after={<Image source={require("./after.jpg")} style={{ flex: 1 }} />}
    />
  );
}
```

## Props

| Prop      | Type                           | Default        | Description                              |
| :-------- | :----------------------------- | :------------- | :--------------------------------------- |
| `before`  | `ReactNode`                    | -              | Shown on the left of the divider.        |
| `after`   | `ReactNode`                    | -              | Shown on the right of the divider.       |
| `initial` | `number`                       | `0.5`          | Where the divider starts, from 0 to 1.   |
| `height`  | `number`                       | `220`          | Height of the slider.                    |
| `label`   | `string`                       | `"Comparison"` | Spoken name of the slider.               |
| `colors`  | `Partial<CompareSliderColors>` | -              | Overrides `line`, `handle` and `arrows`. |
| `style`   | `StyleProp<ViewStyle>`         | -              | Style for the slider's frame.            |

## Source

`components/ui/compare-slider.tsx`

```tsx
import { useEffect, useRef, useState, type ReactNode } from "react";
import {
  AccessibilityInfo,
  Animated,
  PanResponder,
  StyleSheet,
  Text,
  View,
  type LayoutChangeEvent,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const HANDLE = 40;

export interface CompareSliderColors {
  line: string;
  handle: string;
  arrows: string;
}

const DEFAULT_COLORS: CompareSliderColors = {
  line: "#ffffff",
  handle: "#ffffff",
  arrows: "#111827",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface CompareSliderProps {
  /** Shown on the left of the divider. */
  before: ReactNode;
  /** Shown on the right of the divider. */
  after: ReactNode;
  /** Where the divider starts, from 0 to 1. */
  initial?: number;
  height?: number;
  /** Spoken name of the slider. */
  label?: string;
  colors?: Partial<CompareSliderColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A before and after comparison. Drag the handle, or touch anywhere, and the divider follows to reveal
 * more of one side or the other. It is an adjustable control for screen readers, which can step it by
 * ten percent, and the position is read out as a percentage.
 */
export function CompareSlider({
  before,
  after,
  initial = 0.5,
  height = 220,
  label = "Comparison",
  colors,
  style,
}: CompareSliderProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [width, setWidth] = useState(0);
  const [percent, setPercent] = useState(Math.round(initial * 100));
  const pos = useRef(new Animated.Value(initial)).current;
  const at = useRef(initial);
  const start = useRef(initial);
  const live = useRef({ width, reduceMotion });
  live.current = { width, reduceMotion };

  const set = (next: number, animate = false) => {
    const clamped = Math.max(0, Math.min(1, next));
    at.current = clamped;
    setPercent(Math.round(clamped * 100));
    if (animate && !live.current.reduceMotion) {
      Animated.timing(pos, { toValue: clamped, duration: 180, useNativeDriver: false }).start();
    } else {
      pos.setValue(clamped);
    }
  };

  const responder = useRef(
    PanResponder.create({
      onStartShouldSetPanResponder: () => true,
      onPanResponderTerminationRequest: () => false,
      onPanResponderGrant: (event) => {
        const w = Math.max(1, live.current.width);
        set(event.nativeEvent.locationX / w);
        start.current = at.current;
      },
      onPanResponderMove: (_, g) => set(start.current + g.dx / Math.max(1, live.current.width)),
    }),
  ).current;

  const x = pos.interpolate({ inputRange: [0, 1], outputRange: [0, width] });

  return (
    <View
      {...responder.panHandlers}
      onLayout={(event: LayoutChangeEvent) => setWidth(event.nativeEvent.layout.width)}
      accessible
      accessibilityRole="adjustable"
      accessibilityLabel={label}
      aria-label={label}
      accessibilityValue={{ min: 0, max: 100, now: percent, text: `${percent} percent` }}
      aria-valuemin={0}
      aria-valuemax={100}
      aria-valuenow={percent}
      accessibilityActions={[{ name: "increment" }, { name: "decrement" }]}
      onAccessibilityAction={(event) =>
        set(at.current + (event.nativeEvent.actionName === "increment" ? 0.1 : -0.1), true)
      }
      style={[styles.root, { height }, style]}
    >
      <View style={StyleSheet.flatten([styles.layer, { width }])} pointerEvents="none">
        {after}
      </View>
      <Animated.View style={[styles.clip, { width: x }]} pointerEvents="none">
        <View style={{ width, height }}>{before}</View>
      </Animated.View>
      <Animated.View
        pointerEvents="none"
        style={[styles.line, { backgroundColor: palette.line, transform: [{ translateX: x }] }]}
      />
      <Animated.View
        pointerEvents="none"
        style={[
          styles.handle,
          {
            backgroundColor: palette.handle,
            top: height / 2 - HANDLE / 2,
            transform: [{ translateX: Animated.subtract(x, HANDLE / 2) }],
          },
        ]}
      >
        <Text style={[styles.arrows, { color: palette.arrows }]}>◂▸</Text>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { overflow: "hidden", borderRadius: 16, userSelect: "none" },
  layer: { position: "absolute", top: 0, bottom: 0, left: 0 },
  clip: { position: "absolute", top: 0, bottom: 0, left: 0, overflow: "hidden" },
  line: { position: "absolute", top: 0, bottom: 0, left: -1, width: 2 },
  handle: {
    position: "absolute",
    left: 0,
    width: HANDLE,
    height: HANDLE,
    borderRadius: HANDLE / 2,
    alignItems: "center",
    justifyContent: "center",
    boxShadow: "0 2px 8px rgba(0, 0, 0, 0.35)",
  },
  arrows: { fontSize: 14, fontWeight: "800" },
});
```

---

# Hold Confirm

> A React Native press and hold button for risky actions that fills while held and drains back if released early.

Install: `npx @modus-ui/cli add hold-confirm`

A button for actions that should not happen by accident, such as deleting an account. A colour fills the button while it is held and the action runs when it is full; letting go early drains it back and nothing happens. Because holding is hard for some people, a screen reader's activate action and the Enter key on the web run the action straight away. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add hold-confirm
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/hold-confirm.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { HoldConfirm } from "@/components/ui/hold-confirm";

export default function Example() {
  return <HoldConfirm label="Delete project" onComplete={() => console.log("deleted")} />;
}
```

## Props

| Prop         | Type                         | Default  | Description                                     |
| :----------- | :--------------------------- | :------- | :---------------------------------------------- |
| `label`      | `string`                     | -        | The button's text.                              |
| `onComplete` | `() => void`                 | -        | Called once when held long enough or activated. |
| `duration`   | `number`                     | `1200`   | How long to hold, in milliseconds.              |
| `doneLabel`  | `string`                     | `"Done"` | Text shown after it completes.                  |
| `colors`     | `Partial<HoldConfirmColors>` | -        | Overrides `background`, `fill` and `text`.      |
| `style`      | `StyleProp<ViewStyle>`       | -        | Style for the button.                           |

## Source

`components/ui/hold-confirm.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

export interface HoldConfirmColors {
  background: string;
  fill: string;
  text: string;
}

const DEFAULT_COLORS: HoldConfirmColors = {
  background: "#fee2e2",
  fill: "#dc2626",
  text: "#7f1d1d",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface HoldConfirmProps {
  label: string;
  /** Called once when the button has been held long enough, or activated by a screen reader or Enter. */
  onComplete: () => void;
  /** How long to hold, in milliseconds. */
  duration?: number;
  /** Text shown after it completes. */
  doneLabel?: string;
  colors?: Partial<HoldConfirmColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A button for actions that should not happen by accident, such as deleting an account. A colour fills
 * the button while it is held and the action runs when it is full; letting go early drains it back and
 * nothing happens. Because holding is hard for some people, a screen reader's activate action and the
 * Enter key on the web run the action straight away.
 */
export function HoldConfirm({
  label,
  onComplete,
  duration = 1200,
  doneLabel = "Done",
  colors,
  style,
}: HoldConfirmProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const fill = useRef(new Animated.Value(0)).current;
  const [done, setDone] = useState(false);
  const live = useRef({ onComplete, reduceMotion, duration });
  live.current = { onComplete, reduceMotion, duration };
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);

  useEffect(
    () => () => {
      if (timer.current) clearTimeout(timer.current);
    },
    [],
  );

  const finish = () => {
    setDone(true);
    live.current.onComplete();
    timer.current = setTimeout(() => {
      setDone(false);
      fill.setValue(0);
    }, 1400);
  };

  const press = () => {
    if (done) return;
    fill.stopAnimation();
    if (live.current.reduceMotion) {
      // Without motion the hold is a plain timer, and the fill jumps to full when it ends.
      timer.current = setTimeout(() => {
        fill.setValue(1);
        finish();
      }, live.current.duration);
      return;
    }
    Animated.timing(fill, {
      toValue: 1,
      duration: live.current.duration,
      easing: Easing.linear,
      useNativeDriver: false,
    }).start(({ finished }) => {
      if (finished) finish();
    });
  };

  const release = () => {
    if (done) return;
    if (timer.current) clearTimeout(timer.current);
    fill.stopAnimation();
    if (live.current.reduceMotion) fill.setValue(0);
    else Animated.timing(fill, { toValue: 0, duration: 250, useNativeDriver: false }).start();
  };

  const keys = {
    onKeyDown: (event: { key: string }) => {
      if (event.key === "Enter" && !done) finish();
    },
  } as object;

  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={done ? doneLabel : `${label}, hold to confirm`}
      accessibilityHint="Press and hold, or activate to confirm"
      accessibilityActions={[{ name: "activate" }]}
      onAccessibilityAction={() => !done && finish()}
      onPressIn={press}
      onPressOut={release}
      {...keys}
      style={[styles.root, { backgroundColor: palette.background }, style]}
    >
      <Animated.View
        pointerEvents="none"
        style={[
          styles.fill,
          {
            backgroundColor: palette.fill,
            width: fill.interpolate({ inputRange: [0, 1], outputRange: ["0%", "100%"] }),
          },
        ]}
      />
      <View pointerEvents="none" style={styles.center}>
        <Text style={[styles.text, { color: palette.text }]}>{done ? doneLabel : label}</Text>
        {done ? null : <Text style={[styles.hint, { color: palette.text }]}>Hold</Text>}
      </View>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  root: {
    minHeight: 56,
    borderRadius: 16,
    overflow: "hidden",
    justifyContent: "center",
    userSelect: "none",
  },
  fill: { position: "absolute", top: 0, bottom: 0, left: 0, opacity: 0.85 },
  center: {
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "center",
    gap: 10,
    paddingHorizontal: 20,
  },
  text: { fontSize: 16, fontWeight: "800" },
  hint: { fontSize: 12, fontWeight: "700", opacity: 0.6 },
});
```

---

# Select Menu

> A React Native dropdown that opens in place, pushing content down instead of floating, with a turning chevron.

Install: `npx @modus-ui/cli add select-menu`

A dropdown that opens in place, pushing the content below it down instead of floating over it, which keeps it inside a scrolling screen. The chevron turns and the list grows open; choosing an option or pressing Escape on the web closes it. The trigger reports whether it is expanded. Built for React Native and Expo with `react-native` only; this page previews it in the browser through react-native-web.

## Installation

### CLI

```bash
npx @modus-ui/cli add select-menu
```

### Manual

1. Copy the code from the component tab.
2. Create a file at `components/ui/select-menu.tsx`.
3. Paste the code.

It needs no packages beyond `react-native`, which your Expo or React Native app already has.

## Usage

```tsx
import { useState } from "react";
import { SelectMenu } from "@/components/ui/select-menu";

export default function Example() {
  const [country, setCountry] = useState("");

  return (
    <SelectMenu
      label="Country"
      value={country}
      onChange={setCountry}
      options={[
        { value: "ca", label: "Canada" },
        { value: "us", label: "United States" },
      ]}
    />
  );
}
```

## Props

| Prop          | Type                        | Default              | Description                                                                    |
| :------------ | :-------------------------- | :------------------- | :----------------------------------------------------------------------------- |
| `options`     | `SelectOption[]`            | -                    | The choices, each with a `value` and a `label`.                                |
| `value`       | `string`                    | -                    | The chosen option's value, or an empty string.                                 |
| `onChange`    | `(value: string) => void`   | -                    | Called with the chosen value.                                                  |
| `placeholder` | `string`                    | `"Select an option"` | Shown while nothing is chosen.                                                 |
| `label`       | `string`                    | `"Select"`           | Spoken name of the menu.                                                       |
| `colors`      | `Partial<SelectMenuColors>` | -                    | Overrides `surface`, `border`, `text`, `placeholder`, `selected` and `accent`. |
| `style`       | `StyleProp<ViewStyle>`      | -                    | Style for the menu's frame.                                                    |

## Source

`components/ui/select-menu.tsx`

```tsx
import { useEffect, useRef, useState } from "react";
import {
  AccessibilityInfo,
  Animated,
  Easing,
  Platform,
  Pressable,
  StyleSheet,
  Text,
  View,
  type StyleProp,
  type ViewStyle,
} from "react-native";

const NATIVE_DRIVER = Platform.OS !== "web";
const ROW = 48;

export interface SelectOption {
  value: string;
  label: string;
}

export interface SelectMenuColors {
  surface: string;
  border: string;
  text: string;
  placeholder: string;
  selected: string;
  accent: string;
}

const DEFAULT_COLORS: SelectMenuColors = {
  surface: "#ffffff",
  border: "#d1d5db",
  text: "#111827",
  placeholder: "#9ca3af",
  selected: "#eef2ff",
  accent: "#4f46e5",
};

function useReduceMotion() {
  const [reduce, setReduce] = useState(false);
  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => sub.remove();
  }, []);
  return reduce;
}

export interface SelectMenuProps {
  options: SelectOption[];
  /** The chosen option's value, or an empty string for none. */
  value: string;
  onChange: (value: string) => void;
  placeholder?: string;
  /** Spoken name of the menu. */
  label?: string;
  colors?: Partial<SelectMenuColors>;
  style?: StyleProp<ViewStyle>;
}

/**
 * A dropdown that opens in place, pushing the content below it down instead of floating over it, which
 * keeps it inside a scrolling screen. The chevron turns and the list grows open; choosing an option or
 * pressing Escape on the web closes it. The trigger reports whether it is expanded.
 */
export function SelectMenu({
  options,
  value,
  onChange,
  placeholder = "Select an option",
  label = "Select",
  colors,
  style,
}: SelectMenuProps) {
  const palette = { ...DEFAULT_COLORS, ...colors };
  const reduceMotion = useReduceMotion();
  const [open, setOpen] = useState(false);
  const t = useRef(new Animated.Value(0)).current;
  const chosen = options.find((option) => option.value === value);
  const live = useRef({ setOpen });
  live.current = { setOpen };

  useEffect(() => {
    if (reduceMotion) {
      t.setValue(open ? 1 : 0);
      return;
    }
    Animated.timing(t, {
      toValue: open ? 1 : 0,
      duration: 220,
      easing: Easing.out(Easing.cubic),
      useNativeDriver: false,
    }).start();
  }, [open, reduceMotion, t]);

  useEffect(() => {
    if (!open || Platform.OS !== "web") return;
    const onKey = (event: KeyboardEvent) => {
      if (event.key === "Escape") live.current.setOpen(false);
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [open]);

  return (
    <View
      style={[
        styles.root,
        { backgroundColor: palette.surface, borderColor: open ? palette.accent : palette.border },
        style,
      ]}
    >
      <Pressable
        accessibilityRole="button"
        accessibilityLabel={`${label}, ${chosen ? chosen.label : placeholder}`}
        accessibilityState={{ expanded: open }}
        aria-haspopup="listbox"
        aria-expanded={open}
        onPress={() => setOpen(!open)}
        style={styles.trigger}
      >
        <Text style={[styles.value, { color: chosen ? palette.text : palette.placeholder }]}>
          {chosen ? chosen.label : placeholder}
        </Text>
        <Animated.Text
          style={[
            styles.chevron,
            {
              color: palette.placeholder,
              transform: [
                { rotate: t.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "180deg"] }) },
              ],
            },
          ]}
        >
          ⌄
        </Animated.Text>
      </Pressable>
      <Animated.View
        style={{
          overflow: "hidden",
          height: t.interpolate({ inputRange: [0, 1], outputRange: [0, options.length * ROW] }),
        }}
        pointerEvents={open ? "auto" : "none"}
      >
        {options.map((option) => {
          const selected = option.value === value;
          return (
            <Pressable
              key={option.value}
              accessibilityRole="button"
              accessibilityLabel={option.label}
              accessibilityState={{ selected }}
              aria-selected={selected}
              tabIndex={open ? 0 : -1}
              onPress={() => {
                onChange(option.value);
                setOpen(false);
              }}
              style={[
                styles.option,
                {
                  backgroundColor: selected ? palette.selected : "transparent",
                  borderTopColor: palette.border,
                },
              ]}
            >
              <Text
                style={[
                  styles.optionText,
                  { color: palette.text, fontWeight: selected ? "700" : "500" },
                ]}
              >
                {option.label}
              </Text>
              {selected ? (
                <Text style={{ color: palette.accent, fontWeight: "800" }}>✓</Text>
              ) : null}
            </Pressable>
          );
        })}
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  root: { borderWidth: 2, borderRadius: 14, overflow: "hidden" },
  trigger: {
    minHeight: ROW,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    paddingHorizontal: 14,
    userSelect: "none",
  },
  value: { fontSize: 16 },
  chevron: { fontSize: 22, fontWeight: "700" },
  option: {
    height: ROW,
    flexDirection: "row",
    alignItems: "center",
    justifyContent: "space-between",
    paddingHorizontal: 14,
    borderTopWidth: StyleSheet.hairlineWidth,
    userSelect: "none",
  },
  optionText: { fontSize: 16 },
});
```

---

# useColorScheme

> A React Native hook that returns the system colour scheme as light or dark, never null.

Install: `npx @modus-ui/cli add use-color-scheme`

The system colour scheme, always "light" or "dark". React Native's own hook can return null before the platform reports a value; this one falls back to light so styles never see a missing scheme. It re-renders when the person switches appearance. Works in React and in React Native with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add use-color-scheme
```

### Manual

1. Copy the code from the code tab, using the React or React Native switch for your project.
2. Create a file at `components/ui/use-color-scheme.ts`.
3. Paste the code.

The CLI installs the React Native version in an Expo or React Native app and the React version everywhere else. In a project that targets both, keep the React file `use-color-scheme.ts` and the React Native file `use-color-scheme.native.ts` side by side and import `./use-color-scheme`; Metro picks the `.native` file on its own.

## Usage

```tsx
import { View } from "react-native";
import { useColorScheme } from "@/components/ui/use-color-scheme";

export default function Screen() {
  const scheme = useColorScheme();

  return <View style={{ backgroundColor: scheme === "dark" ? "#0b0b0f" : "#ffffff" }} />;
}
```

## API

| Part    | Type                | Description                                   |
| :------ | :------------------ | :-------------------------------------------- |
| Returns | `"light" \| "dark"` | The scheme in effect, light when none is set. |

## Source (React)

`registry/use-color-scheme.ts`

```tsx
"use client";

import { useSyncExternalStore } from "react";

export type Scheme = "light" | "dark";

const QUERY = "(prefers-color-scheme: dark)";

function subscribe(onChange: () => void) {
  const media = window.matchMedia(QUERY);
  media.addEventListener("change", onChange);
  return () => media.removeEventListener("change", onChange);
}

/**
 * The system colour scheme, always "light" or "dark". It reads the prefers-color-scheme media query and
 * re-renders when the person switches appearance. On the server, and for the first render while
 * hydrating, it returns "light" so the markup matches.
 */
export function useColorScheme(): Scheme {
  return useSyncExternalStore(
    subscribe,
    () => (window.matchMedia(QUERY).matches ? "dark" : "light"),
    () => "light",
  );
}
```

## Source (React Native)

`registry/use-color-scheme.native.ts`

```tsx
import { useColorScheme as useSystemScheme } from "react-native";

export type Scheme = "light" | "dark";

/**
 * The system colour scheme, always "light" or "dark". React Native's own hook can return null before
 * the platform reports a value; this one falls back to light so styles never see a missing scheme.
 * It re-renders when the user switches appearance.
 */
export function useColorScheme(): Scheme {
  return useSystemScheme() === "dark" ? "dark" : "light";
}
```

---

# useKeyboardHeight

> A React Native hook that returns the on-screen keyboard height, or 0 while it is hidden.

Install: `npx @modus-ui/cli add use-keyboard-height`

The height of the on-screen keyboard, or 0 while it is hidden. On iOS it updates as the keyboard starts to move, so a view can slide up alongside it; on Android it updates once the keyboard has finished appearing. It is always 0 on the web, where there is no on-screen keyboard to measure. Works in React and in React Native with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add use-keyboard-height
```

### Manual

1. Copy the code from the code tab, using the React or React Native switch for your project.
2. Create a file at `components/ui/use-keyboard-height.ts`.
3. Paste the code.

The CLI installs the React Native version in an Expo or React Native app and the React version everywhere else. In a project that targets both, keep the React file `use-keyboard-height.ts` and the React Native file `use-keyboard-height.native.ts` side by side and import `./use-keyboard-height`; Metro picks the `.native` file on its own.

## Usage

```tsx
import { TextInput, View } from "react-native";
import { useKeyboardHeight } from "@/components/ui/use-keyboard-height";

export default function Composer() {
  const keyboard = useKeyboardHeight();

  return (
    <View style={{ marginBottom: keyboard }}>
      <TextInput placeholder="Message" />
    </View>
  );
}
```

## API

| Part    | Type     | Description                                  |
| :------ | :------- | :------------------------------------------- |
| Returns | `number` | Keyboard height in points, or 0 when hidden. |

## Source (React)

`registry/use-keyboard-height.ts`

```tsx
"use client";

import { useEffect, useState } from "react";

/**
 * The height of the on-screen keyboard on a phone's browser, or 0 while it is hidden. It measures how
 * much of the layout viewport the visual viewport has lost, which is what the keyboard covers. It is
 * always 0 on desktop, and while the page is pinch-zoomed, because a zoom also shrinks the visual
 * viewport and would be mistaken for a keyboard.
 */
export function useKeyboardHeight(): number {
  const [height, setHeight] = useState(0);

  useEffect(() => {
    const viewport = window.visualViewport;
    if (!viewport) return;
    const update = () =>
      setHeight(
        viewport.scale > 1
          ? 0
          : Math.max(0, Math.round(window.innerHeight - viewport.height - viewport.offsetTop)),
      );
    update();
    viewport.addEventListener("resize", update);
    viewport.addEventListener("scroll", update);
    return () => {
      viewport.removeEventListener("resize", update);
      viewport.removeEventListener("scroll", update);
    };
  }, []);

  return height;
}
```

## Source (React Native)

`registry/use-keyboard-height.native.ts`

```tsx
import { useEffect, useState } from "react";
import { Keyboard, Platform } from "react-native";

/**
 * The height of the on-screen keyboard, or 0 while it is hidden. On iOS it updates as the keyboard
 * starts to move, so a view can slide up alongside it; on Android it updates once the keyboard has
 * finished appearing. Always 0 on the web, where there is no on-screen keyboard to measure.
 */
export function useKeyboardHeight(): number {
  const [height, setHeight] = useState(0);

  useEffect(() => {
    const ios = Platform.OS === "ios";
    const show = Keyboard.addListener(ios ? "keyboardWillShow" : "keyboardDidShow", (event) =>
      setHeight(event.endCoordinates.height),
    );
    const hide = Keyboard.addListener(ios ? "keyboardWillHide" : "keyboardDidHide", () =>
      setHeight(0),
    );
    return () => {
      show.remove();
      hide.remove();
    };
  }, []);

  return height;
}
```

---

# useHaptics

> A React Native hook for touch feedback with tap, success, warning and error patterns that you can switch off.

Install: `npx @modus-ui/cli add use-haptics`

Touch feedback built on React Native's Vibration, so it needs no extra package. Pass `enabled` false, for example from a settings switch, and every call does nothing. Android follows the patterns exactly; iOS only offers a single fixed buzz for any pattern, so for finer iOS feedback swap the bodies for expo-haptics. Works in React and in React Native with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add use-haptics
```

### Manual

1. Copy the code from the code tab, using the React or React Native switch for your project.
2. Create a file at `components/ui/use-haptics.ts`.
3. Paste the code.

The CLI installs the React Native version in an Expo or React Native app and the React version everywhere else. In a project that targets both, keep the React file `use-haptics.ts` and the React Native file `use-haptics.native.ts` side by side and import `./use-haptics`; Metro picks the `.native` file on its own.

## Usage

```tsx
import { Pressable, Text } from "react-native";
import { useHaptics } from "@/components/ui/use-haptics";

export default function SaveButton() {
  const haptics = useHaptics();

  return (
    <Pressable onPress={() => haptics.success()}>
      <Text>Save</Text>
    </Pressable>
  );
}
```

## API

| Part      | Type      | Default | Description                                             |
| :-------- | :-------- | :------ | :------------------------------------------------------ |
| `enabled` | `boolean` | `true`  | Pass false to turn every call into a no-op.             |
| Returns   | `Haptics` | -       | An object with `tap`, `success`, `warning` and `error`. |

## Source (React)

`registry/use-haptics.ts`

```tsx
"use client";

import { useMemo } from "react";

export interface Haptics {
  /** A light tick, for a press or a selection. */
  tap: () => void;
  /** Two short pulses, for something that worked. */
  success: () => void;
  /** Two firmer pulses, for something that needs attention. */
  warning: () => void;
  /** Three pulses, for something that failed. */
  error: () => void;
}

/**
 * Touch feedback built on the browser's Vibration API, so it needs no extra package. Pass `enabled`
 * false, for example from a settings switch, and every call does nothing. Browsers that cannot vibrate,
 * which includes Safari and every desktop browser, ignore the calls without an error.
 */
export function useHaptics(enabled = true): Haptics {
  return useMemo(() => {
    const run = (pattern: number | number[]) => {
      if (enabled && typeof navigator !== "undefined") navigator.vibrate?.(pattern);
    };
    return {
      tap: () => run(10),
      success: () => run([0, 15, 60, 15]),
      warning: () => run([0, 30, 50, 30]),
      error: () => run([0, 50, 40, 50, 40, 50]),
    };
  }, [enabled]);
}
```

## Source (React Native)

`registry/use-haptics.native.ts`

```tsx
import { useMemo } from "react";
import { Vibration } from "react-native";

export interface Haptics {
  /** A light tick, for a press or a selection. */
  tap: () => void;
  /** Two short pulses, for something that worked. */
  success: () => void;
  /** Two firmer pulses, for something that needs attention. */
  warning: () => void;
  /** Three pulses, for something that failed. */
  error: () => void;
}

/**
 * Touch feedback built on React Native's Vibration, so it needs no extra package. Pass `enabled`
 * false, for example from a settings switch, and every call does nothing. Android follows the
 * patterns exactly; iOS only offers a single fixed buzz for any pattern, so for finer iOS feedback
 * swap the bodies for expo-haptics.
 */
export function useHaptics(enabled = true): Haptics {
  return useMemo(() => {
    const run = (pattern: number | number[]) => {
      if (enabled) Vibration.vibrate(pattern);
    };
    return {
      tap: () => run(10),
      success: () => run([0, 15, 60, 15]),
      warning: () => run([0, 30, 50, 30]),
      error: () => run([0, 50, 40, 50, 40, 50]),
    };
  }, [enabled]);
}
```

---

# useReduceMotion

> A React Native hook that reports whether the system asks to reduce motion and follows later changes.

Install: `npx @modus-ui/cli add use-reduce-motion`

Whether the person has asked the system to reduce motion. It reads the setting once on mount and follows later changes, so animated components can skip or shorten their motion. It starts as false until the platform answers. Works in React and in React Native with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add use-reduce-motion
```

### Manual

1. Copy the code from the code tab, using the React or React Native switch for your project.
2. Create a file at `components/ui/use-reduce-motion.ts`.
3. Paste the code.

The CLI installs the React Native version in an Expo or React Native app and the React version everywhere else. In a project that targets both, keep the React file `use-reduce-motion.ts` and the React Native file `use-reduce-motion.native.ts` side by side and import `./use-reduce-motion`; Metro picks the `.native` file on its own.

## Usage

```tsx
import { useEffect, useRef } from "react";
import { Animated } from "react-native";
import { useReduceMotion } from "@/components/ui/use-reduce-motion";

export default function Fade({ show }: { show: boolean }) {
  const reduce = useReduceMotion();
  const opacity = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    if (reduce) opacity.setValue(show ? 1 : 0);
    else
      Animated.timing(opacity, {
        toValue: show ? 1 : 0,
        duration: 200,
        useNativeDriver: true,
      }).start();
  }, [show, reduce, opacity]);

  return <Animated.View style={{ opacity }} />;
}
```

## API

| Part    | Type      | Description                                 |
| :------ | :-------- | :------------------------------------------ |
| Returns | `boolean` | True when the system asks to reduce motion. |

## Source (React)

`registry/use-reduce-motion.ts`

```tsx
"use client";

import { useSyncExternalStore } from "react";

const QUERY = "(prefers-reduced-motion: reduce)";

function subscribe(onChange: () => void) {
  const media = window.matchMedia(QUERY);
  media.addEventListener("change", onChange);
  return () => media.removeEventListener("change", onChange);
}

/**
 * Whether the person has asked the system to reduce motion. It reads the prefers-reduced-motion media
 * query and follows later changes, so animated components can skip or shorten their motion. On the
 * server, and for the first render while hydrating, it returns false so the markup matches.
 */
export function useReduceMotion(): boolean {
  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(QUERY).matches,
    () => false,
  );
}
```

## Source (React Native)

`registry/use-reduce-motion.native.ts`

```tsx
import { useEffect, useState } from "react";
import { AccessibilityInfo } from "react-native";

/**
 * Whether the person has asked the system to reduce motion. It reads the setting once on mount and
 * follows later changes, so animated components can skip or shorten their motion. It starts as false
 * until the platform answers.
 */
export function useReduceMotion(): boolean {
  const [reduce, setReduce] = useState(false);

  useEffect(() => {
    AccessibilityInfo.isReduceMotionEnabled().then(setReduce);
    const subscription = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduce);
    return () => subscription.remove();
  }, []);

  return reduce;
}
```

---

# useDebouncedValue

> A React Native hook that returns a copy of a value which only updates after it stops changing.

Install: `npx @modus-ui/cli add use-debounced-value`

A copy of `value` that only updates after it has stopped changing for `delay` milliseconds. Use it to wait out typing before searching: render with the live value, query with the debounced one. The first render returns the value straight away. One file that works unchanged in React and in React Native, with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add use-debounced-value
```

### Manual

1. Copy the code from the code tab.
2. Create a file at `components/ui/use-debounced-value.ts`.
3. Paste the code.

The same file serves React and React Native, so the CLI installs it unchanged in either.

## Usage

```tsx
import { useEffect, useState } from "react";
import { TextInput } from "react-native";
import { useDebouncedValue } from "@/components/ui/use-debounced-value";

export default function Search() {
  const [query, setQuery] = useState("");
  const debounced = useDebouncedValue(query, 400);

  useEffect(() => {
    if (debounced) console.log("search for", debounced);
  }, [debounced]);

  return <TextInput value={query} onChangeText={setQuery} />;
}
```

## API

| Part    | Type     | Default | Description                                      |
| :------ | :------- | :------ | :----------------------------------------------- |
| `value` | `T`      | -       | The value to debounce.                           |
| `delay` | `number` | `300`   | Milliseconds the value must stay still.          |
| Returns | `T`      | -       | The value as it was when the delay last ran out. |

## Source

`components/ui/use-debounced-value.tsx`

```tsx
"use client";

import { useEffect, useState } from "react";

/**
 * A copy of `value` that only updates after it has stopped changing for `delay` milliseconds. Use it
 * to wait out typing before searching: render with the live value, query with the debounced one. The
 * first render returns the value straight away.
 */
export function useDebouncedValue<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value);

  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);

  return debounced;
}
```

---

# ModeProvider

> A React Native provider that holds the light, dark or system choice and exposes it through a useMode hook.

Install: `npx @modus-ui/cli add mode-provider`

Holds the light, dark or system choice for the whole app. Read it anywhere below with `useMode()`. "system" follows the device and updates when the device changes. The provider keeps the choice in memory only; save it from `onModeChange` and pass it back as `initialMode` to remember it. Works in React and in React Native with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add mode-provider
```

### Manual

1. Copy the code from the code tab, using the React or React Native switch for your project.
2. Create a file at `components/ui/mode-provider.tsx`.
3. Paste the code.

The CLI installs the React Native version in an Expo or React Native app and the React version everywhere else. In a project that targets both, keep the React file `mode-provider.tsx` and the React Native file `mode-provider.native.tsx` side by side and import `./mode-provider`; Metro picks the `.native` file on its own.

## Usage

```tsx
import { Pressable, Text } from "react-native";
import { ModeProvider, useMode } from "@/components/ui/mode-provider";

function ToggleButton() {
  const { scheme, toggle } = useMode();

  return (
    <Pressable onPress={toggle}>
      <Text>Currently {scheme}</Text>
    </Pressable>
  );
}

export default function App() {
  return (
    <ModeProvider>
      <ToggleButton />
    </ModeProvider>
  );
}
```

## Props

| Prop           | Type                   | Default    | Description                                           |
| :------------- | :--------------------- | :--------- | :---------------------------------------------------- |
| `initialMode`  | `Mode`                 | `"system"` | The mode to start in.                                 |
| `onModeChange` | `(mode: Mode) => void` | -          | Called whenever the mode changes, so you can save it. |

`useMode()` returns `mode`, the resolved `scheme`, `setMode(mode)` and `toggle()`, and throws outside a `ModeProvider`.

## Source (React)

`registry/mode-provider.tsx`

```tsx
"use client";

import {
  createContext,
  useCallback,
  useSyncExternalStore,
  useContext,
  useMemo,
  useState,
  type ReactNode,
} from "react";

const QUERY = "(prefers-color-scheme: dark)";

/** The system scheme from the prefers-color-scheme media query; "light" on the server so hydration matches. */
function useSystemScheme(): "light" | "dark" {
  return useSyncExternalStore(
    (onChange) => {
      const media = window.matchMedia(QUERY);
      media.addEventListener("change", onChange);
      return () => media.removeEventListener("change", onChange);
    },
    () => (window.matchMedia(QUERY).matches ? "dark" : "light"),
    () => "light",
  );
}

export type Mode = "light" | "dark" | "system";

export interface ModeValue {
  /** What the person chose: light, dark, or follow the system. */
  mode: Mode;
  /** The scheme actually in effect, with "system" resolved to light or dark. */
  scheme: "light" | "dark";
  setMode: (mode: Mode) => void;
  /** Switches to the opposite of the scheme in effect. */
  toggle: () => void;
}

const ModeContext = createContext<ModeValue | null>(null);

export interface ModeProviderProps {
  children: ReactNode;
  /** The mode to start in. */
  initialMode?: Mode;
  /** Called whenever the mode changes, so you can save it. */
  onModeChange?: (mode: Mode) => void;
}

/**
 * Holds the light, dark or system choice for the whole app. Read it anywhere below with `useMode()`.
 * "system" follows the device and updates when the device changes. The provider keeps the choice in
 * memory only; save it from `onModeChange` and pass it back as `initialMode` to remember it.
 */
export function ModeProvider({
  children,
  initialMode = "system",
  onModeChange,
}: ModeProviderProps) {
  const system = useSystemScheme();
  const [mode, setModeState] = useState<Mode>(initialMode);
  const scheme = mode === "system" ? system : mode;

  const setMode = useCallback(
    (next: Mode) => {
      setModeState(next);
      onModeChange?.(next);
    },
    [onModeChange],
  );
  const toggle = useCallback(
    () => setMode(scheme === "dark" ? "light" : "dark"),
    [scheme, setMode],
  );

  const value = useMemo(() => ({ mode, scheme, setMode, toggle }), [mode, scheme, setMode, toggle]);
  return <ModeContext.Provider value={value}>{children}</ModeContext.Provider>;
}

/** The current mode and scheme. Throws when used outside a ModeProvider, so a missing one is caught early. */
export function useMode(): ModeValue {
  const value = useContext(ModeContext);
  if (!value) throw new Error("useMode must be used inside a ModeProvider");
  return value;
}
```

## Source (React Native)

`registry/mode-provider.native.tsx`

```tsx
import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from "react";
import { useColorScheme } from "react-native";

export type Mode = "light" | "dark" | "system";

export interface ModeValue {
  /** What the person chose: light, dark, or follow the system. */
  mode: Mode;
  /** The scheme actually in effect, with "system" resolved to light or dark. */
  scheme: "light" | "dark";
  setMode: (mode: Mode) => void;
  /** Switches to the opposite of the scheme in effect. */
  toggle: () => void;
}

const ModeContext = createContext<ModeValue | null>(null);

export interface ModeProviderProps {
  children: ReactNode;
  /** The mode to start in. */
  initialMode?: Mode;
  /** Called whenever the mode changes, so you can save it. */
  onModeChange?: (mode: Mode) => void;
}

/**
 * Holds the light, dark or system choice for the whole app. Read it anywhere below with `useMode()`.
 * "system" follows the device and updates when the device changes. The provider keeps the choice in
 * memory only; save it from `onModeChange` and pass it back as `initialMode` to remember it.
 */
export function ModeProvider({
  children,
  initialMode = "system",
  onModeChange,
}: ModeProviderProps) {
  const system = useColorScheme() === "dark" ? "dark" : "light";
  const [mode, setModeState] = useState<Mode>(initialMode);
  const scheme = mode === "system" ? system : mode;

  const setMode = useCallback(
    (next: Mode) => {
      setModeState(next);
      onModeChange?.(next);
    },
    [onModeChange],
  );
  const toggle = useCallback(
    () => setMode(scheme === "dark" ? "light" : "dark"),
    [scheme, setMode],
  );

  const value = useMemo(() => ({ mode, scheme, setMode, toggle }), [mode, scheme, setMode, toggle]);
  return <ModeContext.Provider value={value}>{children}</ModeContext.Provider>;
}

/** The current mode and scheme. Throws when used outside a ModeProvider, so a missing one is caught early. */
export function useMode(): ModeValue {
  const value = useContext(ModeContext);
  if (!value) throw new Error("useMode must be used inside a ModeProvider");
  return value;
}
```

---

# ThemeProvider

> A React Native provider that supplies one colour palette to the tree through a useTheme hook, with per-colour overrides.

Install: `npx @modus-ui/cli add theme-provider`

Supplies one palette to everything below it. Components call `useTheme()` and read colours by role, so switching between light and dark restyles the whole tree at once with no per-component logic. Override individual colours with `colors`; anything you leave out keeps its default. Works in React and in React Native with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add theme-provider
```

### Manual

1. Copy the code from the code tab, using the React or React Native switch for your project.
2. Create a file at `components/ui/theme-provider.tsx`.
3. Paste the code.

The CLI installs the React Native version in an Expo or React Native app and the React version everywhere else. In a project that targets both, keep the React file `theme-provider.tsx` and the React Native file `theme-provider.native.tsx` side by side and import `./theme-provider`; Metro picks the `.native` file on its own.

## Usage

```tsx
import { Text, View } from "react-native";
import { ModeProvider, useMode } from "@/components/ui/mode-provider";
import { ThemeProvider, useTheme } from "@/components/ui/theme-provider";

function Card() {
  const { colors } = useTheme();

  return (
    <View style={{ backgroundColor: colors.card }}>
      <Text style={{ color: colors.foreground }}>Hello</Text>
    </View>
  );
}

function Themed() {
  const { scheme } = useMode();

  return (
    <ThemeProvider scheme={scheme} colors={{ light: { primary: "#0d9488" } }}>
      <Card />
    </ThemeProvider>
  );
}

export default function App() {
  return (
    <ModeProvider>
      <Themed />
    </ModeProvider>
  );
}
```

## Props

| Prop     | Type                   | Default | Description                                                                         |
| :------- | :--------------------- | :------ | :---------------------------------------------------------------------------------- |
| `scheme` | `"light" \| "dark"`    | -       | Which palette to use. Leave it out to follow the system.                            |
| `colors` | `Partial<ThemeColors>` | -       | Overrides for single colours in either palette, as `{ light: {...}, dark: {...} }`. |

`useTheme()` returns the active `scheme` and its `colors`, and throws outside a `ThemeProvider`.

## Source (React)

`registry/theme-provider.tsx`

```tsx
"use client";

import { createContext, useSyncExternalStore, useContext, useMemo, type ReactNode } from "react";

const QUERY = "(prefers-color-scheme: dark)";

/** The system scheme from the prefers-color-scheme media query; "light" on the server so hydration matches. */
function useSystemScheme(): "light" | "dark" {
  return useSyncExternalStore(
    (onChange) => {
      const media = window.matchMedia(QUERY);
      media.addEventListener("change", onChange);
      return () => media.removeEventListener("change", onChange);
    },
    () => (window.matchMedia(QUERY).matches ? "dark" : "light"),
    () => "light",
  );
}

export interface ThemePalette {
  background: string;
  foreground: string;
  card: string;
  muted: string;
  mutedForeground: string;
  primary: string;
  primaryForeground: string;
  border: string;
  destructive: string;
}

export interface ThemeColors {
  light: Partial<ThemePalette>;
  dark: Partial<ThemePalette>;
}

const LIGHT: ThemePalette = {
  background: "#ffffff",
  foreground: "#111827",
  card: "#f9fafb",
  muted: "#f3f4f6",
  mutedForeground: "#6b7280",
  primary: "#4f46e5",
  primaryForeground: "#ffffff",
  border: "#e5e7eb",
  destructive: "#dc2626",
};

const DARK: ThemePalette = {
  background: "#0b0b0f",
  foreground: "#f9fafb",
  card: "#16161d",
  muted: "#1f1f29",
  mutedForeground: "#9ca3af",
  primary: "#818cf8",
  primaryForeground: "#0b0b0f",
  border: "#2a2a36",
  destructive: "#f87171",
};

export interface Theme {
  scheme: "light" | "dark";
  colors: ThemePalette;
}

const ThemeContext = createContext<Theme | null>(null);

export interface ThemeProviderProps {
  children: ReactNode;
  /** Which palette to use. Leave it out to follow the system; pass `useMode().scheme` to follow your own switch. */
  scheme?: "light" | "dark";
  /** Overrides for single colours in either palette. */
  colors?: Partial<ThemeColors>;
}

/**
 * Supplies one palette to everything below it. Components call `useTheme()` and read colours by role,
 * so switching between light and dark restyles the whole tree at once with no per-component logic.
 * Override individual colours with `colors`; anything you leave out keeps its default.
 */
export function ThemeProvider({ children, scheme, colors }: ThemeProviderProps) {
  const system = useSystemScheme();
  const active = scheme ?? system;

  const value = useMemo<Theme>(
    () => ({
      scheme: active,
      colors: active === "dark" ? { ...DARK, ...colors?.dark } : { ...LIGHT, ...colors?.light },
    }),
    [active, colors],
  );
  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

/** The active scheme and its colours. Throws when used outside a ThemeProvider. */
export function useTheme(): Theme {
  const value = useContext(ThemeContext);
  if (!value) throw new Error("useTheme must be used inside a ThemeProvider");
  return value;
}
```

## Source (React Native)

`registry/theme-provider.native.tsx`

```tsx
import { createContext, useContext, useMemo, type ReactNode } from "react";
import { useColorScheme } from "react-native";

export interface ThemePalette {
  background: string;
  foreground: string;
  card: string;
  muted: string;
  mutedForeground: string;
  primary: string;
  primaryForeground: string;
  border: string;
  destructive: string;
}

export interface ThemeColors {
  light: Partial<ThemePalette>;
  dark: Partial<ThemePalette>;
}

const LIGHT: ThemePalette = {
  background: "#ffffff",
  foreground: "#111827",
  card: "#f9fafb",
  muted: "#f3f4f6",
  mutedForeground: "#6b7280",
  primary: "#4f46e5",
  primaryForeground: "#ffffff",
  border: "#e5e7eb",
  destructive: "#dc2626",
};

const DARK: ThemePalette = {
  background: "#0b0b0f",
  foreground: "#f9fafb",
  card: "#16161d",
  muted: "#1f1f29",
  mutedForeground: "#9ca3af",
  primary: "#818cf8",
  primaryForeground: "#0b0b0f",
  border: "#2a2a36",
  destructive: "#f87171",
};

export interface Theme {
  scheme: "light" | "dark";
  colors: ThemePalette;
}

const ThemeContext = createContext<Theme | null>(null);

export interface ThemeProviderProps {
  children: ReactNode;
  /** Which palette to use. Leave it out to follow the system; pass `useMode().scheme` to follow your own switch. */
  scheme?: "light" | "dark";
  /** Overrides for single colours in either palette. */
  colors?: Partial<ThemeColors>;
}

/**
 * Supplies one palette to everything below it. Components call `useTheme()` and read colours by role,
 * so switching between light and dark restyles the whole tree at once with no per-component logic.
 * Override individual colours with `colors`; anything you leave out keeps its default.
 */
export function ThemeProvider({ children, scheme, colors }: ThemeProviderProps) {
  const system = useColorScheme() === "dark" ? "dark" : "light";
  const active = scheme ?? system;

  const value = useMemo<Theme>(
    () => ({
      scheme: active,
      colors: active === "dark" ? { ...DARK, ...colors?.dark } : { ...LIGHT, ...colors?.light },
    }),
    [active, colors],
  );
  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

/** The active scheme and its colours. Throws when used outside a ThemeProvider. */
export function useTheme(): Theme {
  const value = useContext(ThemeContext);
  if (!value) throw new Error("useTheme must be used inside a ThemeProvider");
  return value;
}
```

---

# Colors

> Light and dark colour palettes for React Native, named by role, with a helper that adds transparency to any colour.

Install: `npx @modus-ui/cli add theme-colors`

Every colour a screen needs, named by role rather than by shade, so light and dark can swap freely. `lightColors` and `darkColors` hold the same nine names, and `withAlpha` turns any #rrggbb colour into an rgba() string for overlays and pressed states. One file that works unchanged in React and in React Native, with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add theme-colors
```

### Manual

1. Copy the code from the code tab.
2. Create a file at `components/ui/theme-colors.ts`.
3. Paste the code.

The same file serves React and React Native, so the CLI installs it unchanged in either.

## Usage

```tsx
import { Text, View } from "react-native";
import { darkColors, lightColors, withAlpha } from "@/components/ui/theme-colors";

export default function Banner({ dark }: { dark: boolean }) {
  const colors = dark ? darkColors : lightColors;

  return (
    <View style={{ backgroundColor: withAlpha(colors.primary, 0.12) }}>
      <Text style={{ color: colors.primary }}>Heads up</Text>
    </View>
  );
}
```

## API

| Export        | Type                                     | Description                                                      |
| :------------ | :--------------------------------------- | :--------------------------------------------------------------- |
| `lightColors` | `ThemeColors`                            | The light palette.                                               |
| `darkColors`  | `ThemeColors`                            | The dark palette.                                                |
| `withAlpha`   | `(hex: string, alpha: number) => string` | Adds transparency to a #rrggbb colour; `alpha` runs from 0 to 1. |

The names are `background`, `foreground`, `card`, `muted`, `mutedForeground`, `primary`, `primaryForeground`, `border` and `destructive`.

## Source

`components/ui/theme-colors.tsx`

```tsx
/** Every colour a screen needs, by role rather than by shade, so light and dark can swap freely. */
export interface ThemeColors {
  background: string;
  foreground: string;
  card: string;
  muted: string;
  mutedForeground: string;
  primary: string;
  primaryForeground: string;
  border: string;
  destructive: string;
}

export const lightColors: ThemeColors = {
  background: "#ffffff",
  foreground: "#111827",
  card: "#f9fafb",
  muted: "#f3f4f6",
  mutedForeground: "#6b7280",
  primary: "#4f46e5",
  primaryForeground: "#ffffff",
  border: "#e5e7eb",
  destructive: "#dc2626",
};

export const darkColors: ThemeColors = {
  background: "#0b0b0f",
  foreground: "#f9fafb",
  card: "#16161d",
  muted: "#1f1f29",
  mutedForeground: "#9ca3af",
  primary: "#818cf8",
  primaryForeground: "#0b0b0f",
  border: "#2a2a36",
  destructive: "#f87171",
};

/**
 * Adds transparency to a #rrggbb colour and returns an rgba() string. `alpha` runs from 0 to 1. Use it
 * for overlays and pressed states so they stay tied to the palette instead of being hard-coded.
 */
export function withAlpha(hex: string, alpha: number): string {
  const value = hex.replace("#", "");
  const r = parseInt(value.slice(0, 2), 16);
  const g = parseInt(value.slice(2, 4), 16);
  const b = parseInt(value.slice(4, 6), 16);
  return `rgba(${r}, ${g}, ${b}, ${Math.max(0, Math.min(1, alpha))})`;
}
```

---

# Globals

> Shared React Native design tokens for spacing, corner radius, type sizes, font weights and shadows.

Install: `npx @modus-ui/cli add theme-globals`

The numbers every screen repeats, in one place. Pick spacing, radius, type size and shadow from a scale instead of typing a value, and the whole app stays consistent when you change one. One file that works unchanged in React and in React Native, with no extra packages.

## Installation

### CLI

```bash
npx @modus-ui/cli add theme-globals
```

### Manual

1. Copy the code from the code tab.
2. Create a file at `components/ui/theme-globals.ts`.
3. Paste the code.

The same file serves React and React Native, so the CLI installs it unchanged in either.

## Usage

```tsx
import { Text, View } from "react-native";
import { fontSize, radius, shadow, spacing } from "@/components/ui/theme-globals";

export default function Card() {
  return (
    <View style={{ padding: spacing.lg, borderRadius: radius.lg, boxShadow: shadow.md }}>
      <Text style={fontSize.title}>Title</Text>
    </View>
  );
}
```

## API

| Export       | Description                                                                  |
| :----------- | :--------------------------------------------------------------------------- |
| `spacing`    | `xs` 4, `sm` 8, `md` 12, `lg` 16, `xl` 24, `xxl` 32.                         |
| `radius`     | `sm` 8, `md` 12, `lg` 16, `xl` 24, `pill` 999.                               |
| `fontSize`   | `caption`, `body`, `title`, `heading`, `display`, each with its line height. |
| `fontWeight` | `regular`, `medium`, `semibold`, `bold` as string weights.                   |
| `shadow`     | `sm`, `md`, `lg` elevation levels as box shadows.                            |

## Source

`components/ui/theme-globals.tsx`

```tsx
/** Space between things, in points. Pick from the scale instead of typing a number. */
export const spacing = { xs: 4, sm: 8, md: 12, lg: 16, xl: 24, xxl: 32 } as const;

/** Corner radii, from slightly rounded to a full pill. */
export const radius = { sm: 8, md: 12, lg: 16, xl: 24, pill: 999 } as const;

/** Type sizes with matching line heights. */
export const fontSize = {
  caption: { fontSize: 12, lineHeight: 16 },
  body: { fontSize: 16, lineHeight: 24 },
  title: { fontSize: 20, lineHeight: 28 },
  heading: { fontSize: 28, lineHeight: 34 },
  display: { fontSize: 40, lineHeight: 46 },
} as const;

/** Font weights as the string values React Native expects. */
export const fontWeight = { regular: "400", medium: "500", semibold: "600", bold: "700" } as const;

/** Elevation levels as box shadows. */
export const shadow = {
  sm: "0 1px 3px rgba(0, 0, 0, 0.12)",
  md: "0 4px 12px rgba(0, 0, 0, 0.16)",
  lg: "0 12px 32px rgba(0, 0, 0, 0.22)",
} as const;
```