Letter Scramble

'use client';

import gsap from 'gsap';
import { Fragment, useEffect, useRef, useState } from 'react';
import { cn } from '@/lib/utils';
import { useInView } from '@/hooks/use-in-view';
import { createRng, randInt } from '@/lib/prng';
import { useReducedMotion } from '@/hooks/use-reduced-motion';

/* ==========================================================================
   Letter Scramble
   --------------------------------------------------------------------------
   The word assembles itself out of noise. Every character flips through a
   handful of wrong glyphs and then lands on the right one, each character
   starting 0.1 s after the one before it, so the resolution sweeps left to
   right across the word.

   The deceleration is what makes it read as *settling* rather than as a
   loading spinner: flip n holds for `0.08 + n * 0.025` seconds, so the first
   substitutions are a blur and the last is almost a beat. Constant-interval
   flipping reads as a slot machine that was switched off.

   Widths are frozen before the first substitution. Proportional type gives
   `i` and `W` wildly different advance widths, so a word scrambling through
   random glyphs visibly breathes — and every element after it on the line
   shudders in sympathy. Each character box is pinned to the width of its
   final glyph for the duration, then released.
   ========================================================================== */

export interface LetterScrambleProps {
  /** The resolved word. Rendered as-is for SSR, reduced motion, and AT. */
  text: string;
  /** Substitution pool. Keep it to glyphs of similar visual weight. */
  glyphs?: string;
  /** Wrong glyphs shown per character before it resolves. */
  flips?: number;
  /** Seconds between adjacent characters starting. */
  stagger?: number;
  /** Seconds the first wrong glyph is held. */
  baseFlip?: number;
  /** Seconds added to each successive hold. This is the deceleration. */
  flipGrowth?: number;
  /** Seconds of the fade that lands with the final glyph. */
  settle?: number;
  /** Re-run on pointer enter, on fine pointers only. */
  replayOnHover?: boolean;
  startOnView?: boolean;
  /** Any string or number. Same seed, same sequence, every render. */
  seed?: number | string;
  className?: string;
}

// #region critical
const GLYPHS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#%&@$*';
const FLIPS = 7;
const STAGGER = 0.1;
const BASE_FLIP = 0.08;
const FLIP_GROWTH = 0.025;
const SETTLE = 0.45;
const START_DELAY = 0.25;
const DIM = 0.35;
const VIEW_THRESHOLD = 0.4;

export function LetterScramble({
  text,
  glyphs = GLYPHS,
  flips = FLIPS,
  stagger = STAGGER,
  baseFlip = BASE_FLIP,
  flipGrowth = FLIP_GROWTH,
  settle = SETTLE,
  replayOnHover = true,
  startOnView = true,
  seed,
  className,
}: LetterScrambleProps) {
  const root = useRef<HTMLSpanElement>(null);
  const reduced = useReducedMotion();
  const { inView } = useInView(root, { threshold: VIEW_THRESHOLD, once: true });
  const [run, setRun] = useState(0);

  useEffect(() => {
    const el = root.current;
    if (!el || reduced) return;
    if (startOnView && !inView) return;

    const chars = Array.from(el.querySelectorAll<HTMLElement>('[data-char]'));
    if (chars.length === 0 || glyphs.length === 0) return;

    // Seeded, never Math.random: the glyph sequence decides what is painted
    // on the first client frame, and a server/client disagreement about that
    // is a hydration mismatch.
    const rng = createRng(seed ?? `${text}:${run}`);

    let cancelled = false;
    let tl: gsap.core.Timeline | null = null;

    const restore = () => {
      for (const c of chars) {
        c.textContent = c.dataset.final ?? '';
        c.style.width = '';
        c.style.opacity = '';
      }
    };

    const build = () => {
      if (cancelled) return;

      // Measured after fonts are ready, and measured from the *final* glyph,
      // which is what is in the DOM right now. Measuring a substituted glyph
      // would lock in the wrong box.
      for (const c of chars) {
        c.style.width = `${c.getBoundingClientRect().width}px`;
      }

      tl = gsap.timeline();

      chars.forEach((c, i) => {
        const final = c.dataset.final ?? '';
        let t = START_DELAY + i * stagger;

        for (let f = 0; f < flips; f += 1) {
          const g = glyphs.charAt(randInt(rng, 0, glyphs.length));
          tl?.call(
            () => {
              c.textContent = g;
            },
            undefined,
            t,
          );
          t += baseFlip + f * flipGrowth;
        }

        tl?.call(
          () => {
            c.textContent = final;
          },
          undefined,
          t,
        );
        // The fade is what separates "resolved" from "one more wrong glyph".
        tl?.fromTo(
          c,
          { opacity: DIM },
          { opacity: 1, duration: settle, ease: 'power3.out' },
          t,
        );
      });

      // Release the frozen widths once nothing is substituting any more, so
      // the word reflows normally if the viewport or the font changes later.
      tl?.call(
        () => {
          for (const c of chars) c.style.width = '';
        },
        undefined,
        '>',
      );
    };

    // Splitting or measuring before the webfont lands measures the fallback,
    // and every character box is then frozen to the wrong width.
    void document.fonts.ready.then(build);

    return () => {
      cancelled = true;
      tl?.kill();
      restore();
    };
  }, [
    text,
    glyphs,
    flips,
    stagger,
    baseFlip,
    flipGrowth,
    settle,
    seed,
    startOnView,
    inView,
    reduced,
    run,
  ]);
  // #endregion critical

  const replay = () => {
    if (!replayOnHover || reduced) return;
    if (!window.matchMedia('(pointer: fine)').matches) return;
    setRun((n) => n + 1);
  };

  const words = text.split(' ');

  return (
    <span
      ref={root}
      className={cn('inline-block', className)}
      onPointerEnter={replay}
    >
      {/* The visible characters are mutated to garbage mid-flight, so they are
          hidden from assistive tech and the real word is exposed once. */}
      <span className="sr-only">{text}</span>
      <span aria-hidden>
        {words.map((w, wi) => (
          <Fragment key={`${wi}-${w}`}>
            <span className="inline-block whitespace-nowrap">
              {Array.from(w).map((ch, ci) => (
                <span
                  key={ci}
                  data-char
                  data-final={ch}
                  className="inline-block text-center"
                >
                  {ch}
                </span>
              ))}
            </span>
            {wi < words.length - 1 ? ' ' : null}
          </Fragment>
        ))}
      </span>
    </span>
  );
}

/* ==========================================================================
   Seeded randomness.
   --------------------------------------------------------------------------
   `Math.random()` in a particle field means the server and the client
   disagree, which React reports as a hydration mismatch, and it means the
   layout is different on every reload so a visual regression is invisible.
   Every component that scatters something uses a seeded generator instead.
   ========================================================================== */

export type Rng = () => number;

/**
 * mulberry32 — 32-bit, fast, and good enough for visual scatter. Returns a
 * function yielding floats in [0, 1).
 */
export function mulberry32(seed: number): Rng {
  let a = seed >>> 0;
  return function next() {
    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;
  };
}

/** Turn any string into a 32-bit seed, so `seed="hero"` is reproducible. */
export function hashSeed(input: string): number {
  let h = 2166136261 >>> 0;
  for (let i = 0; i < input.length; i++) {
    h ^= input.charCodeAt(i);
    h = Math.imul(h, 16777619);
  }
  return h >>> 0;
}

export function createRng(seed: number | string): Rng {
  return mulberry32(typeof seed === 'string' ? hashSeed(seed) : seed);
}

export function randRange(rng: Rng, min: number, max: number): number {
  return min + rng() * (max - min);
}

export function randInt(rng: Rng, min: number, maxExclusive: number): number {
  return Math.floor(randRange(rng, min, maxExclusive));
}

/**
 * Uniform point on a unit sphere. Naive angle-pairing clusters at the poles;
 * this inverts the cosine so density is even.
 */
export function randOnSphere(rng: Rng): [number, number, number] {
  const u = rng() * 2 - 1;
  const theta = rng() * Math.PI * 2;
  const r = Math.sqrt(1 - u * u);
  return [r * Math.cos(theta), r * Math.sin(theta), u];
}

/** Uniform point in a unit disc — `sqrt` prevents crowding at the centre. */
export function randInDisc(rng: Rng): [number, number] {
  const r = Math.sqrt(rng());
  const theta = rng() * Math.PI * 2;
  return [r * Math.cos(theta), r * Math.sin(theta)];
}

/** In-place Fisher-Yates using the supplied generator. */
export function shuffle<T>(rng: Rng, arr: T[]): T[] {
  for (let i = arr.length - 1; i > 0; i--) {
    const j = randInt(rng, 0, i + 1);
    const a = arr[i] as T;
    const b = arr[j] as T;
    arr[i] = b;
    arr[j] = a;
  }
  return arr;
}

'use client';

import { useEffect, useRef, useState, type RefObject } from 'react';

/* ==========================================================================
   IntersectionObserver, sharing one observer per option set.
   --------------------------------------------------------------------------
   A hundred cards each constructing their own observer is a hundred observers
   the compositor has to service. Keying a shared observer by its options
   collapses that to one per distinct configuration — in practice, two or
   three for the whole site.
   ========================================================================== */

export interface InViewState {
  inView: boolean;
  /** 0-1. The preview slot allocator ranks candidates by this. */
  ratio: number;
}

export interface UseInViewOptions {
  root?: Element | null;
  rootMargin?: string;
  /** Single number or list, same meaning as the native option. */
  threshold?: number | number[];
  /** Stop observing after the first time it becomes visible. */
  once?: boolean;
}

type Entry = {
  observer: IntersectionObserver;
  handlers: Map<Element, (e: IntersectionObserverEntry) => void>;
};

const pools = new Map<string, Entry>();

function poolFor(options: UseInViewOptions): Entry {
  const key = JSON.stringify({
    rootMargin: options.rootMargin ?? '0px',
    threshold: options.threshold ?? 0,
  });
  const existing = pools.get(key);
  if (existing) return existing;

  const handlers = new Map<Element, (e: IntersectionObserverEntry) => void>();
  const observer = new IntersectionObserver(
    (entries) => {
      for (const entry of entries) handlers.get(entry.target)?.(entry);
    },
    {
      root: options.root ?? null,
      rootMargin: options.rootMargin ?? '0px',
      threshold: options.threshold ?? 0,
    },
  );
  const created: Entry = { observer, handlers };
  pools.set(key, created);
  return created;
}

export function useInView(
  ref: RefObject<Element | null>,
  options: UseInViewOptions = {},
): InViewState {
  const [state, setState] = useState<InViewState>({ inView: false, ratio: 0 });
  const { root = null, rootMargin = '0px', once = false } = options;
  const thresholdKey = JSON.stringify(options.threshold ?? 0);
  const done = useRef(false);

  useEffect(() => {
    const el = ref.current;
    if (!el || typeof IntersectionObserver === 'undefined') return;
    if (once && done.current) return;

    const pool = poolFor({
      root,
      rootMargin,
      threshold: JSON.parse(thresholdKey) as number | number[],
    });

    const handle = (entry: IntersectionObserverEntry) => {
      setState({ inView: entry.isIntersecting, ratio: entry.intersectionRatio });
      if (once && entry.isIntersecting) {
        done.current = true;
        pool.handlers.delete(el);
        pool.observer.unobserve(el);
      }
    };

    pool.handlers.set(el, handle);
    pool.observer.observe(el);

    return () => {
      pool.handlers.delete(el);
      pool.observer.unobserve(el);
    };
  }, [ref, root, rootMargin, thresholdKey, once]);

  return state;
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   prefers-reduced-motion, SSR-safe.
   --------------------------------------------------------------------------
   useSyncExternalStore rather than useState + useEffect: the server snapshot
   is an explicit `false`, so the markup React renders on the server and the
   markup it hydrates with agree, and the real value lands in the same commit
   as hydration instead of one frame later. A useEffect version flashes the
   animated variant before removing it — the exact thing the user asked not to
   see.

   Reduced motion is not "duration: 0". For most components here it means a
   different render: the final state, a static poster, or a paused frame.
   ========================================================================== */

const QUERY = '(prefers-reduced-motion: reduce)';

function subscribe(onChange: () => void) {
  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
  const mql = window.matchMedia(QUERY);
  mql.addEventListener('change', onChange);
  return () => mql.removeEventListener('change', onChange);
}

function getSnapshot() {
  if (typeof window === 'undefined' || !window.matchMedia) return false;
  return window.matchMedia(QUERY).matches;
}

function getServerSnapshot() {
  return false;
}

export function useReducedMotion(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

/** Generic media-query hook, same SSR guarantees. */
export function useMediaQuery(query: string): boolean {
  return useSyncExternalStore(
    (onChange) => {
      if (typeof window === 'undefined' || !window.matchMedia) return () => {};
      const mql = window.matchMedia(query);
      mql.addEventListener('change', onChange);
      return () => mql.removeEventListener('change', onChange);
    },
    () => {
      if (typeof window === 'undefined' || !window.matchMedia) return false;
      return window.matchMedia(query).matches;
    },
    () => false,
  );
}