Checkpoint

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

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

"use client";

import * as React from "react";

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

/**
 * Keep:
 * - One async runner owns every move: WAAPI keyframes on the `data-part` hooks, each end state
 *   written inline as it finishes. React only decides which row's Approve / Deny can be reached.
 * - Only transform and opacity move. A barrier swings down about its pivot, the way the token
 *   travels, so its tip stays clear of the token, and closes only once the token is past its reach.
 * - Approve / Deny float over the row's right end and stay `inert` unless that row holds, so a hold
 *   never moves the row or focus; a decision made from the keyboard leaves focus on the checkpoint.
 * - Off screen and on a hidden tab the runner waits between steps (`gate()`), and the approval
 *   timer and the waiting dot pause where they are.
 * - Under reduced motion there's no token, travel, lifting or knocking: each rule resolves with an
 *   opacity change and the barriers only change color.
 */
const TIMING = {
  /** How fast each request plays, as a multiple of the pace below (the `speed` prop). */
  speed: 1,
  // At the default pace; `speed` divides everything from here down to `log`.
  /** The token's leg from one barrier to the next, in ms. */
  travel: 300,
  /** A rule being read, row tinted, before its verdict, in ms. */
  read: 160,
  /** A barrier swinging open about its pivot, in ms. */
  lift: 200,
  /**
   * A barrier closing, in ms, and ms into the token's next leg before it starts: by then the token
   * is past the arm's 26px reach.
   */
  drop: { duration: 240, delay: 200 },
  /** A status box filling, in ms. */
  tick: 180,
  /** The row's tint fading as its barrier lifts, in ms. */
  untint: 200,
  /** A held token easing up against the barrier, in ms. */
  settle: 160,
  /**
   * A blocked token's two knocks, in ms. Linear overall, so each keyframe's own curve plays out on
   * the clock.
   */
  knock: { duration: 260, easing: "linear" },
  /** A turned-away token sliding out of the lane, in ms. */
  away: 200,
  /** The tag and the Approve / Deny buttons cross-fading, in ms. The status swaps on it unpaced. */
  swap: 180,
  /** The token fading into the log, in ms. */
  tokenOut: 120,
  /** Per box fading back, and between rows, last row first, in ms. */
  reset: { duration: 120, stagger: 25 },
  /** A new request sliding in from the left, and the old one fading, in ms. */
  enter: { duration: 280, out: 120 },
  /** A log line fading in while the older ones step down, in ms. */
  log: 280,
  // Not paced.
  /**
   * A hold waiting before it approves itself, with autoplay, in ms (the `approveAfter` prop), and
   * the curve of the hairline that fills meanwhile.
   */
  approveAfter: 2400,
  timer: "linear",
  /** An outcome staying up before the next request, in ms (the `dwell` prop). */
  dwell: 1600,
  /** One cycle of a waiting box's dot, in ms, and its curve. */
  breathe: { duration: 1400, easing: "ease-in-out" },
  /** Between rules under reduced motion, in ms. */
  reduced: 120,
  /** Curves, as CSS easings. */
  outEase: "cubic-bezier(0.23, 1, 0.32, 1)", // arrivals and lifts: all the speed up front
  inOut: "cubic-bezier(0.65, 0, 0.35, 1)", // the token's legs: pulls away and pulls up
  inEase: "cubic-bezier(0.55, 0, 1, 0.45)", // leaving, and a knock's run-up: the speed at the end
  fade: "linear", // cross-fades, and every fade under reduced motion
  /** A barrier and a row changing color, as a Tailwind class. */
  colors: "duration-150",
  /** Approve and Deny on hover, as a Tailwind class. */
  hover: "duration-150",
} as const;

/* ─────────────────────────────────────────────────────────
 * CHECKPOINT STORYBOARD
 *
 *  rest     the request sits in a card at the top: its icon, its name
 *           in mono, who sent it and what it carries, and a status on
 *           the right. Under it, one row per rule, each with a boom
 *           barrier down across a narrow lane on its left. The
 *           request's icon, every barrier, the token and the log's
 *           icons all sit on that lane's center line
 *  view     once 30% of it is in view, the token drops out from under
 *           the request card and the first rule is read
 *  travel   the token glides down the lane to just above the next
 *           barrier, 300ms, in-out, like a car pulling up
 *  read     the row tints with the accent for 160ms and its barrier
 *           turns accent: the rule is being checked
 *  pass     the barrier swings 84° down about its pivot, the way the
 *           token is heading, like a door pushed open (200ms,
 *           ease-out), clear of the token's path, while the row's box
 *           fills with a check (180ms, from 0.7), and the token drives
 *           through. The barrier swings back up behind it once the
 *           token is past its reach, 200ms into its next leg (240ms)
 *  hold     a rule that needs sign-off keeps its barrier down. The
 *           token settles 2px closer to it, Approve / Deny fade in
 *           over the row's right end (180ms) and the status reads
 *           "Waiting on approval". With autoplay a hairline fills
 *           under Approve over `approveAfter` and it approves itself
 *           as `approver`; pointing at the buttons holds the timer.
 *           Approve swings the barrier open; Deny keeps it shut and sends
 *           the token away without a knock
 *  block    a rule it breaks stays shut. The token knocks into the
 *           barrier twice (4px, then 2px, 260ms), the barrier and the
 *           row's box go ink with a cross, the status reads "Blocked ·
 *           <rule>" and the token slides out of the lane, 14px, 200ms
 *  clear    past the last rule the token drives into the top line of
 *           the log and becomes its check: the new line fades in as
 *           the older lines step down one line (280ms), the oldest
 *           dropping out under the edge. The status reads "Cleared"
 *  next     1.6s later the boxes clear, last row first (120ms each,
 *           25ms apart), the old request fades and the next one slides
 *           in from 12px left (280ms). Requests loop with autoplay
 *  sleep    off screen and on a hidden tab it stops between steps, and
 *           an approval timer stops where it is
 *  keys     Approve and Deny are buttons, reachable only while a rule
 *           waits; a hold never moves focus. A decision made from the
 *           keyboard leaves focus on the checkpoint
 *  narrow   under 26rem the value tags hide, so the details keep
 *           their room, and the status shortens to one word
 *  reduced  no token, no travel, no lifting or knocking: each rule
 *           resolves 120ms after the last with an opacity change, the
 *           barriers stay down and only change color, and holds wait
 *           the same way
 * ───────────────────────────────────────────────────────── */

const GATE = {
  view: 0.3, // share of the box in view before the first request runs
  lane: 40, // px, the lane column; the icons, barriers and token sit on its center line
  token: 12, // px, the token's side
  gap: 4, // px between a waiting token and the barrier under it
  lift: { angle: 84 }, // deg: a barrier swinging open about its pivot, downward, the way the token travels (84° keeps its tip ~3px clear of the token)
  settle: { distance: 2 }, // px: a held token easing up against the barrier
  knock: { distance: 4 }, // px: a blocked token's first knock (the second is half as far)
  away: { distance: 14 }, // px: a turned-away token sliding out of the lane
  enter: { distance: 12 }, // px a new request slides in from the left
} as const;

const REDUCED = "(prefers-reduced-motion: reduce)";
const LOG_LINES = 3;

const subscribeReduced = (onChange: () => void) => {
  const query = window.matchMedia(REDUCED);
  query.addEventListener("change", onChange);
  return () => query.removeEventListener("change", onChange);
};

/** prefers-reduced-motion, false on the server and in the hydration render. */
function usePrefersReducedMotion() {
  return React.useSyncExternalStore(
    subscribeReduced,
    () => window.matchMedia(REDUCED).matches,
    () => false,
  );
}

const clock = () => new Date().toLocaleTimeString("en-GB", { hour12: false });

export type CheckpointVerdict = "pass" | "hold" | "block";

export interface CheckpointRule {
  /** Stable key, used by each request's `verdicts`. */
  id: string;
  /** The rule's name, e.g. "Amount". */
  label: string;
  /** One line under the name, e.g. "Refunds over $500 need finance". */
  detail?: string;
  /** A short value in a mono tag on the right, e.g. "≤ $500". */
  value?: string;
  /** A small glyph before the name, drawn in currentColor. */
  icon?: React.ReactNode;
}

export interface CheckpointRequest {
  /** Stable key. */
  id: string;
  /** What's asking, in mono, e.g. "refund_order". */
  label: string;
  /** Who sent it and what it carries, e.g. "$1,240 · support-bot". */
  meta?: string;
  /** A glyph for the request card, drawn in the accent. */
  icon?: React.ReactNode;
  /** How each rule judges it, by rule id. A rule left out passes. */
  verdicts?: Partial<Record<string, CheckpointVerdict>>;
  /** Why it was blocked, shown in the status instead of the rule's name. */
  reason?: string;
}

export type CheckpointOutcome = "cleared" | "blocked" | "denied";

export interface CheckpointProps extends React.HTMLAttributes<HTMLDivElement> {
  /** The rules, top to bottom, each with a barrier in the lane. */
  rules: CheckpointRule[];
  /** The requests that come through, in order. */
  requests: CheckpointRequest[];
  /** The id of the request to run. Set it to drive the checkpoint yourself: each change runs that request once. Leave it out and `autoplay` runs them in turn. */
  current?: string;
  /** Run the requests one after another and start over after the last. With `false` the first one runs once. Defaults to true. */
  autoplay?: boolean;
  /** Ms a rule that needs sign-off waits before it approves itself, or `false` to wait for the visitor. Only with autoplay. Defaults to 2400. */
  approveAfter?: number | false;
  /** Who signs off when a hold approves itself, as written in the log. Defaults to "a reviewer". */
  approver?: string;
  /** Show the last three outcomes under the rules. Defaults to true. */
  log?: boolean;
  /** Called when a request is settled, with the rule that stopped it. */
  onDecision?: (requestId: string, outcome: CheckpointOutcome, ruleId?: string) => void;
  /** How fast each request plays, as a multiple of the default pace: the token's legs, the barriers swinging, the rows ticking, a knock, the log line and the next request sliding in. `2` is twice as fast. Defaults to 1. */
  speed?: number;
  /** Ms an outcome stays up before the next request comes in, with autoplay. Defaults to 1600. */
  dwell?: number;
}

type Phase =
  | { kind: "queued" }
  | { kind: "checking" }
  | { kind: "hold"; rule: string }
  | { kind: "cleared" }
  | { kind: "blocked"; rule: string }
  | { kind: "denied"; rule: string };

type LogEntry = {
  key: number;
  ok: boolean;
  label: string;
  note: string;
  time: string;
};

/* ── Glyphs ───────────────────────────────────────────────── */

function Check({ className }: { className?: string }) {
  return (
    <svg viewBox="0 0 12 12" aria-hidden className={className}>
      <path
        d="M2.6 6.3l2.2 2.2 4.6-4.9"
        fill="none"
        stroke="currentColor"
        strokeWidth="1.7"
        strokeLinecap="round"
        strokeLinejoin="round"
      />
    </svg>
  );
}

function Cross({ className }: { className?: string }) {
  return (
    <svg viewBox="0 0 12 12" aria-hidden className={className}>
      <path
        d="M3.4 3.4l5.2 5.2M8.6 3.4l-5.2 5.2"
        fill="none"
        stroke="currentColor"
        strokeWidth="1.7"
        strokeLinecap="round"
      />
    </svg>
  );
}

/* ── Swap ─────────────────────────────────────────────────── */
// Swaps a short line of text when its key changes: the old one lifts 4px out,
// then the new one rises 4px in, so two lines never sit on top of each other.

function Swap({
  id,
  children,
  reduced,
  className,
}: {
  id: string;
  children: React.ReactNode;
  reduced: boolean;
  className?: string;
}) {
  const [shown, setShown] = React.useState<{
    id: string;
    node: React.ReactNode;
  }>({ id, node: children });
  const [leaving, setLeaving] = React.useState<{
    id: string;
    node: React.ReactNode;
  } | null>(null);
  if (shown.id !== id) {
    setLeaving(shown);
    setShown({ id, node: children });
  }

  const nextRef = React.useRef<HTMLSpanElement>(null);
  const oldRef = React.useRef<HTMLSpanElement>(null);
  const leavingId = leaving?.id;
  React.useLayoutEffect(() => {
    if (!leavingId) return;
    const out = TIMING.swap * 0.5;
    nextRef.current?.animate(
      reduced
        ? [{ opacity: 0 }, { opacity: 1 }]
        : [
            { opacity: 0, transform: "translateY(4px)" },
            { opacity: 1, transform: "none" },
          ],
      {
        duration: TIMING.swap,
        delay: reduced ? out : out * 0.6,
        easing: TIMING.outEase,
        fill: "backwards",
      },
    );
    const a = oldRef.current?.animate(
      reduced
        ? [{ opacity: 1 }, { opacity: 0 }]
        : [
            { opacity: 1, transform: "none" },
            { opacity: 0, transform: "translateY(-4px)" },
          ],
      {
        duration: out,
        easing: TIMING.inEase,
        fill: "forwards",
      },
    );
    if (!a) return;
    a.finished.then(
      () => setLeaving((l) => (l?.id === leavingId ? null : l)),
      () => {},
    );
    return () => a.cancel();
  }, [leavingId, id, reduced]);

  const cell = "col-start-1 row-start-1 inline-flex items-center gap-1.5 whitespace-nowrap";
  return (
    <span className={cn("relative inline-grid justify-items-end overflow-hidden py-0.5", className)}>
      {leaving ? (
        <span key={leaving.id} ref={oldRef} aria-hidden className={cell}>
          {leaving.node}
        </span>
      ) : null}
      <span key={id} ref={nextRef} className={cell}>
        {children}
      </span>
    </span>
  );
}

/* ── RuleRow ──────────────────────────────────────────────── */
// One rule: its barrier in the lane, then the card. Everything that moves is
// driven from Checkpoint's runner through the data-part hooks; React only
// decides whether the Approve / Deny pair can be reached.

interface RuleRowProps {
  rule: CheckpointRule;
  holding: boolean;
  onDecide: (choice: "approve" | "deny") => void;
  onHoverActions: (over: boolean) => void;
}

const RuleRow = React.memo(function RuleRow({ rule, holding, onDecide, onHoverActions }: RuleRowProps) {
  return (
    <li data-checkpoint-row className="grid grid-cols-[2.5rem_minmax(0,1fr)] items-center">
      {/* The barrier: a pivot on the left, an arm across the lane, a rest on the right. */}
      <div aria-hidden className="relative h-full">
        <span className="absolute top-1/2 left-[31px] size-[5px] -translate-y-1/2 rounded-full border border-zinc-950/15 bg-white dark:border-white/20 dark:bg-zinc-950" />
        <span
          data-part="arm"
          className={`absolute top-1/2 left-[7px] -mt-[1.5px] h-[3px] w-[26px] origin-[1.5px_50%] rounded-full bg-zinc-950/20 transition-colors ${TIMING.colors} will-change-transform data-[state=active]:bg-[var(--checkpoint-accent)] data-[state=block]:bg-zinc-950 dark:bg-white/25 dark:data-[state=active]:bg-[var(--checkpoint-accent)] dark:data-[state=block]:bg-white`}
        />
        <span className="absolute top-1/2 left-[5px] size-[7px] -translate-y-1/2 rounded-full bg-zinc-950 ring-2 ring-white dark:bg-zinc-200 dark:ring-zinc-950" />
      </div>

      <div
        data-part="card"
        className={`relative flex min-h-14 items-center gap-3 rounded-xl border [--checkpoint-hold:color-mix(in_srgb,var(--checkpoint-accent)_6%,white)] dark:[--checkpoint-hold:color-mix(in_srgb,var(--checkpoint-accent)_10%,#18181b)] border-zinc-950/[0.08] bg-white px-3 py-2.5 shadow-[0_1px_2px_rgba(0,0,0,0.04)] transition-colors ${TIMING.colors} data-[state=block]:border-zinc-950/25 data-[state=hold]:border-[color-mix(in_oklab,var(--checkpoint-accent)_40%,transparent)] dark:border-white/10 dark:bg-zinc-900 dark:data-[state=block]:border-white/30 dark:data-[state=hold]:border-[color-mix(in_oklab,var(--checkpoint-accent)_45%,transparent)]`}
      >
        <span
          data-part="tint"
          aria-hidden
          className="pointer-events-none absolute inset-0 rounded-[inherit] bg-[color-mix(in_oklab,var(--checkpoint-accent)_6%,transparent)] opacity-0 dark:bg-[color-mix(in_oklab,var(--checkpoint-accent)_10%,transparent)]"
        />
        <span
          data-part="ink"
          aria-hidden
          className="pointer-events-none absolute inset-0 rounded-[inherit] bg-zinc-950/[0.035] opacity-0 dark:bg-white/[0.05]"
        />
        {rule.icon ? (
          <span
            aria-hidden
            className="relative grid size-4 shrink-0 place-items-center text-zinc-400 dark:text-zinc-500 [&_svg]:size-4"
          >
            {rule.icon}
          </span>
        ) : null}
        <span className="relative min-w-0 flex-1">
          <span className="block truncate text-[13px] leading-[18px] font-medium tracking-tight text-zinc-950 dark:text-zinc-100">
            {rule.label}
          </span>
          {rule.detail ? (
            <span className="block truncate text-[12px] leading-4 text-zinc-500 dark:text-zinc-400">{rule.detail}</span>
          ) : null}
        </span>

        {rule.value ? (
          <span
            data-part="tag"
            className="relative hidden shrink-0 rounded-md border border-zinc-950/10 px-1.5 py-0.5 font-mono text-[11px] leading-4 tracking-wide text-zinc-600 uppercase @[26rem]/checkpoint:block dark:border-white/15 dark:text-zinc-300"
          >
            {rule.value}
          </span>
        ) : null}

        {/* Approve / Deny float over the row's right end, on the hold color, so a hold never moves the row. */}
        <span
          data-part="actions"
          inert={!holding}
          onPointerEnter={(e) => e.pointerType === "mouse" && onHoverActions(true)}
          onPointerLeave={(e) => e.pointerType === "mouse" && onHoverActions(false)}
          className="absolute inset-y-0 right-[41px] z-[1] flex items-center gap-1 rounded-r-[inherit] bg-[linear-gradient(to_right,transparent,var(--checkpoint-hold)_1.25rem)] pl-6 opacity-0"
        >
          <button
            type="button"
            onClick={() => onDecide("deny")}
            className={`grid h-7 min-w-7 place-items-center rounded-full border border-zinc-950/10 px-1.5 text-[12px] font-medium text-zinc-700 transition-[background-color] ${TIMING.hover} hover:bg-zinc-950/[0.04] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--checkpoint-accent)] @[26rem]/checkpoint:px-2.5 dark:border-white/15 dark:text-zinc-200 dark:hover:bg-white/[0.06]`}
          >
            <Cross className="size-3 @[26rem]/checkpoint:hidden" />
            <span className="sr-only @[26rem]/checkpoint:not-sr-only">Deny</span>
          </button>
          <button
            type="button"
            onClick={() => onDecide("approve")}
            className={`relative h-7 overflow-hidden rounded-full bg-[var(--checkpoint-button)] px-3 text-[12px] font-medium text-white transition-[background-color] ${TIMING.hover} hover:bg-[color-mix(in_oklab,var(--checkpoint-button)_88%,black)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[color:var(--checkpoint-accent)]`}
          >
            Approve
            <span
              data-part="timer"
              aria-hidden
              className="absolute inset-x-0 bottom-0 h-[2px] origin-left bg-white/55 [transform:scaleX(0)] will-change-transform"
            />
          </button>
        </span>

        <span
          aria-hidden
          className="relative size-[18px] shrink-0 rounded-[5px] border border-zinc-950/15 dark:border-white/20"
        >
          <span
            data-part="pass"
            className="absolute -inset-px grid place-items-center rounded-[5px] bg-[var(--checkpoint-accent)] text-white opacity-0"
          >
            <Check className="size-3" />
          </span>
          <span
            data-part="block"
            className="absolute -inset-px grid place-items-center rounded-[5px] bg-zinc-950 text-white opacity-0 dark:bg-white dark:text-zinc-950"
          >
            <Cross className="size-3" />
          </span>
          <span
            data-part="hold"
            className="absolute -inset-px grid place-items-center rounded-[5px] border-[1.5px] border-[var(--checkpoint-accent)] opacity-0"
          >
            <span data-part="dot" className="size-1.5 rounded-full bg-[var(--checkpoint-accent)]" />
          </span>
        </span>
      </div>
    </li>
  );
});

/* ── Checkpoint ───────────────────────────────────────────── */

export function Checkpoint({
  rules,
  requests,
  current,
  autoplay = true,
  approveAfter = TIMING.approveAfter,
  approver = "a reviewer",
  log = true,
  onDecision,
  speed = TIMING.speed,
  dwell = TIMING.dwell,
  className,
  style,
  ...props
}: CheckpointProps) {
  const rootRef = React.useRef<HTMLDivElement>(null);
  const tokenRef = React.useRef<HTMLSpanElement>(null);
  const cardRef = React.useRef<HTMLDivElement>(null);
  const logRef = React.useRef<HTMLOListElement>(null);
  const reduced = usePrefersReducedMotion();

  const [active, setActive] = React.useState(() =>
    Math.max(
      0,
      requests.findIndex((r) => r.id === current),
    ),
  );
  const [generation, setGeneration] = React.useState(0);
  const [phase, setPhase] = React.useState<Phase>({ kind: "queued" });
  const [holding, setHolding] = React.useState(-1);
  const [entries, setEntries] = React.useState<LogEntry[]>([]);
  const [announcement, setAnnouncement] = React.useState("");

  // `speed`, read by the runner and the log as each move starts, so a new value never restarts a request.
  const pace = Math.max(0.05, speed);
  const paceRef = React.useRef(pace);
  React.useLayoutEffect(() => {
    paceRef.current = pace;
  }, [pace]);

  // A new log line: it fades in on top while the older lines step down one line,
  // the oldest dropping out under the edge. Runs after the commit, before paint.
  const newest = entries[0]?.key;
  const lines = entries.length;
  React.useLayoutEffect(() => {
    const list = logRef.current;
    const first = list?.firstElementChild as HTMLElement | null | undefined;
    if (!list || !first || newest === undefined) return;
    if (reduced) {
      first.animate([{ opacity: 0 }, { opacity: 1 }], { duration: TIMING.reduced, easing: TIMING.fade });
      return;
    }
    const roll = TIMING.log / paceRef.current;
    first.animate([{ opacity: 0 }, { opacity: 1 }], { duration: roll, easing: TIMING.outEase });
    if (lines > 1) {
      list.animate([{ transform: `translateY(${-first.offsetHeight}px)` }, { transform: "translateY(0px)" }], {
        duration: roll,
        easing: TIMING.outEase,
      });
    }
  }, [newest, lines, reduced]);

  // Handlers the runner installs and the buttons call.
  const decideRef = React.useRef<((choice: "approve" | "deny") => void) | null>(null);
  const hoverRef = React.useRef<(over: boolean) => void>(() => {});
  const onDecide = React.useCallback((choice: "approve" | "deny") => decideRef.current?.(choice), []);
  const onHoverActions = React.useCallback((over: boolean) => hoverRef.current(over), []);

  // The latest labels and callbacks, read by the runner without restarting it.
  const latest = React.useRef({ rules, requests, approver, onDecision, dwell });
  const ranRef = React.useRef(false); // a request has run, so the next one slides in
  React.useLayoutEffect(() => {
    latest.current = { rules, requests, approver, onDecision, dwell: Math.max(0, dwell) };
  });

  const ruleKey = rules.map((r) => r.id).join("\u0000");
  const requestKey = JSON.stringify(requests.map((r) => [r.id, r.verdicts ?? {}]));
  const wait = approveAfter === false ? 0 : approveAfter;

  React.useEffect(() => {
    const root = rootRef.current;
    const token = tokenRef.current;
    if (!root || !token) return;
    const reqs = latest.current.requests;
    if (reqs.length === 0) return;

    const CANCEL = Symbol("cancel");
    let cancelled = false;
    let visible = false;
    let waiters: (() => void)[] = [];
    let timer: Animation | null = null;
    let overActions = false;
    const timers = new Set<number>();
    const anims = new Set<Animation>();
    const loops = new Set<Animation>();

    const check = () => {
      if (cancelled) throw CANCEL;
    };
    /** A move's ms at the current `speed`. */
    const paced = (ms: number) => ms / paceRef.current;
    const sleep = (ms: number) =>
      new Promise<void>((resolve) => {
        const id = window.setTimeout(() => {
          timers.delete(id);
          resolve();
        }, ms);
        timers.add(id);
      }).then(check);
    const frame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve())).then(check);
    const gate = () =>
      (visible ? Promise.resolve() : new Promise<void>((resolve) => waiters.push(resolve))).then(check);

    type Frame = {
      transform?: string;
      opacity?: number | string;
      offset?: number;
      easing?: string;
    };
    /** WAAPI from explicit keyframes; on finish the end state is written inline and the animation dropped. */
    const play = (
      el: HTMLElement | null | undefined,
      frames: Frame[],
      duration: number,
      easing: string = TIMING.outEase,
      delay = 0,
    ) => {
      if (!el) return Promise.resolve().then(check);
      const a = el.animate(frames as Keyframe[], {
        duration,
        easing,
        delay,
        fill: "forwards",
      });
      anims.add(a);
      return a.finished
        .then(
          () => {
            const end = frames[frames.length - 1];
            if (end.transform !== undefined) el.style.transform = end.transform;
            if (end.opacity !== undefined) el.style.opacity = String(end.opacity);
            a.cancel();
          },
          () => {},
        )
        .finally(() => anims.delete(a))
        .then(check);
    };
    const set = (el: HTMLElement | null | undefined, transform?: string, opacity?: number) => {
      if (!el) return;
      if (transform !== undefined) el.style.transform = transform;
      if (opacity !== undefined) el.style.opacity = String(opacity);
    };
    const state = (el: Element | null | undefined, value?: string) => {
      if (!el) return;
      if (value) el.setAttribute("data-state", value);
      else el.removeAttribute("data-state");
    };

    const rows = () => Array.from(root.querySelectorAll<HTMLElement>("[data-checkpoint-row]"));
    const part = (row: HTMLElement | undefined, name: string) =>
      row?.querySelector<HTMLElement>(`[data-part="${name}"]`);
    const half = GATE.token / 2;
    /** y of an element's center, in the root's box. */
    const centerY = (el: Element) => {
      const r = el.getBoundingClientRect();
      return r.top + r.height / 2 - root.getBoundingClientRect().top;
    };
    const stopAbove = (row: HTMLElement) => centerY(part(row, "arm") ?? row) - 1.5 - GATE.gap - half;
    const at = (y: number, x = 0) => `translate3d(${x}px, ${y - half}px, 0)`;

    let tokenY = 0;
    const origin = () => {
      const icon = cardRef.current?.querySelector("[data-part='icon']");
      return icon ? centerY(icon) : 0;
    };

    /** Everything back to rest at once: barriers down, boxes empty, token under the request card. */
    const clearRows = () => {
      for (const row of rows()) {
        for (const name of ["pass", "block", "hold", "tint", "ink", "actions", "timer"]) {
          const el = part(row, name);
          if (el) {
            el.getAnimations().forEach((a) => a.cancel());
            el.style.removeProperty("opacity");
            el.style.removeProperty("transform");
          }
        }
        const arm = part(row, "arm");
        arm?.getAnimations().forEach((a) => a.cancel());
        arm?.style.removeProperty("transform");
        state(arm);
        state(part(row, "card"));
        set(part(row, "tag"), undefined, 1);
      }
    };
    const park = () => {
      token.getAnimations().forEach((a) => a.cancel());
      tokenY = origin();
      set(token, at(tokenY), 1);
    };

    const isReduced = reduced;
    const motion = !isReduced;

    /** The token's leg to `y`; the barrier it just passed closes behind it. */
    const drive = (y: number, behind?: HTMLElement | null) => {
      if (behind) {
        play(
          behind,
          [{ transform: `rotate(${GATE.lift.angle}deg)` }, { transform: "rotate(0deg)" }],
          paced(TIMING.drop.duration),
          TIMING.outEase,
          paced(TIMING.drop.delay),
        )
          .then(() => state(behind))
          .catch(() => {});
      }
      const from = tokenY;
      tokenY = y;
      return play(token, [{ transform: at(from) }, { transform: at(y) }], paced(TIMING.travel), TIMING.inOut);
    };

    const tick = (el: HTMLElement | null | undefined) =>
      motion
        ? play(
            el,
            [
              { opacity: 0, transform: "scale(0.7)" },
              { opacity: 1, transform: "scale(1)" },
            ],
            paced(TIMING.tick),
          )
        : play(el, [{ opacity: 0 }, { opacity: 1 }], TIMING.reduced, TIMING.fade);

    const breathe = (el: HTMLElement | null | undefined) => {
      if (!el || !motion) return;
      const a = el.animate([{ opacity: 1 }, { opacity: 0.3 }, { opacity: 1 }], {
        duration: TIMING.breathe.duration,
        iterations: Infinity,
        easing: TIMING.breathe.easing,
      });
      loops.add(a);
      if (!visible) a.pause();
    };
    const stopLoops = () => {
      loops.forEach((a) => a.cancel());
      loops.clear();
    };

    const addLog = async (entry: Omit<LogEntry, "key" | "time">) => {
      setEntries((list) =>
        [{ ...entry, key: Date.now() + Math.random(), time: clock() }, ...list].slice(0, LOG_LINES + 1),
      );
      // The roll-in itself runs in a layout effect once the line is committed.
      await sleep(motion ? paced(TIMING.log) : TIMING.reduced);
    };

    const decide = (row: HTMLElement) =>
      new Promise<"approve" | "deny" | "auto">((resolve) => {
        let done = false;
        const finish = (choice: "approve" | "deny" | "auto") => {
          if (done) return;
          done = true;
          decideRef.current = null;
          hoverRef.current = () => {};
          timer?.cancel();
          timer = null;
          // A decision made from the keyboard leaves focus on the checkpoint, not on a button that's going away.
          if (row.contains(document.activeElement)) root.focus({ preventScroll: true });
          resolve(choice);
        };
        decideRef.current = finish;
        const timerEl = part(row, "timer");
        if (autoplay && wait > 0 && timerEl) {
          const a = timerEl.animate([{ transform: "scaleX(0)" }, { transform: "scaleX(1)" }], {
            duration: wait,
            easing: TIMING.timer,
            fill: "forwards",
          });
          timer = a;
          overActions = false;
          if (!visible) a.pause();
          hoverRef.current = (over) => {
            overActions = over;
            if (over) a.pause();
            else if (visible) a.play();
          };
          a.finished.then(
            () => finish("auto"),
            () => {},
          );
        }
      }).then((choice) => {
        check();
        return choice;
      });

    /** One request, top to bottom. */
    const run = async (index: number, enter: boolean) => {
      const req = latest.current.requests[index];
      if (!req) return;
      if (enter) {
        await play(
          cardRef.current?.querySelector<HTMLElement>("[data-part='content']"),
          [{ opacity: 1 }, { opacity: 0 }],
          paced(TIMING.enter.out),
          TIMING.fade,
        );
        setActive(index);
        setGeneration((g) => g + 1);
        setPhase({ kind: "checking" });
        await frame();
        await frame();
        park();
        await sleep(motion ? paced(TIMING.enter.duration) * 0.6 : TIMING.reduced);
      } else {
        setActive(index);
        setPhase({ kind: "checking" });
        park();
      }

      const list = rows();
      const ruleList = latest.current.rules;
      let behind: HTMLElement | null = null;
      let outcome: CheckpointOutcome = "cleared";
      let stopped: CheckpointRule | undefined;
      let approvedBy = "";

      for (let i = 0; i < list.length; i++) {
        const row = list[i];
        const rule = ruleList[i];
        if (!rule) break;
        const verdict = req.verdicts?.[rule.id] ?? "pass";
        const arm = part(row, "arm");
        const card = part(row, "card");
        await gate();

        if (motion) await drive(stopAbove(row), behind);
        behind = null;

        // read
        state(arm, "active");
        if (motion) await play(part(row, "tint"), [{ opacity: 0 }, { opacity: 1 }], paced(TIMING.read), TIMING.outEase);
        else await sleep(TIMING.reduced);
        await gate();

        let lifted = verdict === "pass";
        if (verdict === "hold") {
          state(card, "hold");
          set(part(row, "tint"), undefined, 1);
          setHolding(i);
          setPhase({ kind: "hold", rule: rule.label });
          setAnnouncement(`${req.label} needs approval: ${rule.label}${rule.detail ? `. ${rule.detail}` : ""}.`);
          const hold = part(row, "hold");
          tick(hold).catch(() => {});
          breathe(part(row, "dot"));
          if (motion) {
            play(
              token,
              [{ transform: at(tokenY) }, { transform: at(tokenY + GATE.settle.distance) }],
              paced(TIMING.settle),
            ).catch(() => {});
            tokenY += GATE.settle.distance;
          }
          await frame();
          const fade = motion ? paced(TIMING.swap) : TIMING.reduced;
          play(part(row, "tag"), [{ opacity: 1 }, { opacity: 0 }], fade, TIMING.fade).catch(() => {});
          await play(part(row, "actions"), [{ opacity: 0 }, { opacity: 1 }], fade, TIMING.fade);

          const choice = await decide(row);
          setHolding(-1);
          stopLoops();
          play(part(row, "actions"), [{ opacity: 1 }, { opacity: 0 }], fade, TIMING.fade).catch(() => {});
          play(part(row, "tag"), [{ opacity: 0 }, { opacity: 1 }], fade, TIMING.fade).catch(() => {});
          play(hold, [{ opacity: 1 }, { opacity: 0 }], fade, TIMING.fade).catch(() => {});
          state(card);
          if (choice === "deny") {
            outcome = "denied";
          } else {
            approvedBy = choice === "auto" ? latest.current.approver : "you";
            lifted = true;
          }
          setPhase({ kind: "checking" });
        }

        if (lifted) {
          play(part(row, "tint"), [{ opacity: 1 }, { opacity: 0 }], paced(TIMING.untint), TIMING.fade).catch(() => {});
          tick(part(row, "pass")).catch(() => {});
          if (motion) {
            play(
              arm,
              [{ transform: "rotate(0deg)" }, { transform: `rotate(${GATE.lift.angle}deg)` }],
              paced(TIMING.lift),
              TIMING.outEase,
            ).catch(() => {});
            // the token pulls away halfway up; the barrier closes behind it on its next leg
            await sleep(paced(TIMING.lift) / 2);
            behind = arm ?? null;
          } else {
            state(arm);
            await sleep(TIMING.reduced);
          }
          continue;
        }

        // block, or a hold that was denied
        stopped = rule;
        if (outcome !== "denied") outcome = "blocked";
        state(arm, "block");
        state(card, "block");
        set(part(row, "tint"), undefined, 0);
        set(part(row, "ink"), undefined, 1);
        tick(part(row, "block")).catch(() => {});
        if (motion && outcome === "blocked") {
          const d = GATE.knock.distance;
          const y = tokenY;
          await play(
            token,
            [
              { transform: at(y), easing: TIMING.inEase },
              { transform: at(y + d), offset: 0.22, easing: TIMING.outEase },
              {
                transform: at(y),
                offset: 0.5,
                easing: TIMING.inEase,
              },
              { transform: at(y + d / 2), offset: 0.68, easing: TIMING.outEase },
              { transform: at(y) },
            ],
            paced(TIMING.knock.duration),
            TIMING.knock.easing,
          );
        }
        if (motion) {
          await play(
            token,
            [
              { transform: at(tokenY), opacity: 1 },
              { transform: at(tokenY, -GATE.away.distance), opacity: 0 },
            ],
            paced(TIMING.away),
            TIMING.outEase,
          );
        }
        break;
      }

      if (outcome === "cleared") {
        setPhase({ kind: "cleared" });
        setAnnouncement(`${req.label} cleared${approvedBy ? `, approved by ${approvedBy}` : ""}.`);
        const listEl = logRef.current;
        if (motion) {
          const end = log && listEl ? centerY(listEl) - listEl.getBoundingClientRect().height / 2 + 11 : tokenY + 40;
          await drive(end, behind);
          behind = null;
          play(token, [{ opacity: 1 }, { opacity: 0 }], paced(TIMING.tokenOut), TIMING.fade).catch(() => {});
        }
        if (log) {
          await addLog({
            ok: true,
            label: req.label,
            note: approvedBy ? `ran · approved by ${approvedBy}` : "ran",
          });
        }
      } else {
        const why = req.reason ?? stopped?.label ?? "";
        setPhase(outcome === "denied" ? { kind: "denied", rule: why } : { kind: "blocked", rule: why });
        setAnnouncement(`${req.label} ${outcome === "denied" ? "denied" : "blocked"}${why ? `: ${why}` : ""}.`);
        if (log)
          await addLog({
            ok: false,
            label: req.label,
            note: `${outcome}${why ? ` · ${why}` : ""}`,
          });
      }
      latest.current.onDecision?.(req.id, outcome, stopped?.id);
    };

    /** Boxes clear and barriers close, last row first. */
    const reset = async () => {
      const list = rows();
      const fades: Promise<void>[] = [];
      list
        .slice()
        .reverse()
        .forEach((row, k) => {
          const delay = motion ? k * paced(TIMING.reset.stagger) : 0;
          for (const name of ["pass", "block", "tint", "ink"]) {
            const el = part(row, name);
            if (el && el.style.opacity && el.style.opacity !== "0") {
              fades.push(play(el, [{ opacity: 1 }, { opacity: 0 }], paced(TIMING.reset.duration), TIMING.fade, delay));
            }
          }
          state(part(row, "card"));
        });
      await Promise.all(fades);
      clearRows();
    };

    const start = Math.max(
      0,
      reqs.findIndex((r) => r.id === current),
    );
    const loop = current === undefined && autoplay;
    const main = async () => {
      const again = ranRef.current;
      if (!again) {
        clearRows();
        park();
      }
      await gate();
      if (again) await reset();
      let index = start;
      let enter = again;
      for (;;) {
        ranRef.current = true;
        await run(index, enter);
        enter = true;
        if (!loop) break;
        await sleep(latest.current.dwell);
        await gate();
        await reset();
        index = (index + 1) % latest.current.requests.length;
      }
    };

    const setVisible = (v: boolean) => {
      visible = v;
      if (v) {
        const ready = waiters;
        waiters = [];
        ready.forEach((resolve) => resolve());
        if (timer && !overActions) timer.play();
        loops.forEach((a) => a.play());
      } else {
        timer?.pause();
        loops.forEach((a) => a.pause());
      }
    };
    let inView = false;
    const io = new IntersectionObserver(
      ([entry]) => {
        inView = entry.isIntersecting && entry.intersectionRatio >= GATE.view - 0.01;
        if (!entry.isIntersecting) inView = false;
        setVisible(inView && !document.hidden);
      },
      { threshold: [0, GATE.view] },
    );
    io.observe(root);
    const onVisibility = () => setVisible(inView && !document.hidden);
    document.addEventListener("visibilitychange", onVisibility);

    main().catch((error) => {
      if (error !== CANCEL) throw error;
    });

    return () => {
      cancelled = true;
      io.disconnect();
      document.removeEventListener("visibilitychange", onVisibility);
      timers.forEach((id) => window.clearTimeout(id));
      anims.forEach((a) => a.cancel());
      stopLoops();
      timer?.cancel();
      decideRef.current = null;
      hoverRef.current = () => {};
      setHolding(-1);
    };
  }, [ruleKey, requestKey, current, autoplay, wait, log, reduced]);

  const req = requests[active] ?? requests[0];

  const status = (() => {
    switch (phase.kind) {
      // `short` is what a narrow box shows, so the request's name keeps its room.
      case "queued":
        return { id: "queued", tone: "muted", text: "Queued", short: "Queued" };
      case "checking":
        return { id: "checking", tone: "muted", text: "Checking", short: "Checking" };
      case "hold":
        return { id: `hold-${phase.rule}`, tone: "accent", text: "Waiting on approval", short: "Waiting" };
      case "cleared":
        return { id: "cleared", tone: "accent", text: "Cleared", short: "Cleared" };
      case "blocked":
        return {
          id: `blocked-${phase.rule}`,
          tone: "ink",
          text: phase.rule ? `Blocked · ${phase.rule}` : "Blocked",
          short: "Blocked",
        };
      case "denied":
        return {
          id: `denied-${phase.rule}`,
          tone: "ink",
          text: phase.rule ? `Denied · ${phase.rule}` : "Denied",
          short: "Denied",
        };
    }
  })();

  return (
    <div
      ref={rootRef}
      tabIndex={-1}
      className={cn(
        "@container/checkpoint relative w-full text-zinc-950 outline-none [--checkpoint-accent:#ff3b1f] [--checkpoint-button:color-mix(in_oklab,var(--checkpoint-accent)_80%,black)] [--checkpoint-text:color-mix(in_oklab,var(--checkpoint-accent)_78%,black)] dark:text-zinc-100 dark:[--checkpoint-accent:#ff5a3c] dark:[--checkpoint-button:color-mix(in_oklab,var(--checkpoint-accent)_72%,black)] dark:[--checkpoint-text:var(--checkpoint-accent)]",
        className,
      )}
      style={style}
      {...props}
    >
      <span className="sr-only" aria-live="polite">
        {announcement}
      </span>

      {/* The lane's hairline, from under the request card to the log. */}
      <span
        aria-hidden
        className={cn(
          "pointer-events-none absolute top-6 left-[19.5px] w-px bg-zinc-950/10 dark:bg-white/10",
          log ? "bottom-[55px]" : "bottom-0",
        )}
      />

      {/* The request card: the token waits under it, so it drops out from beneath the icon. */}
      <div
        ref={cardRef}
        className="relative z-10 flex min-h-12 items-center gap-3 rounded-xl border border-zinc-950/[0.08] bg-white py-2 pr-3 pl-1.5 shadow-[0_1px_2px_rgba(0,0,0,0.04),0_4px_12px_-6px_rgba(0,0,0,0.08)] dark:border-white/10 dark:bg-zinc-900"
      >
        {req ? (
          <RequestContent key={generation} request={req} enter={generation > 0} reduced={reduced} speed={pace} />
        ) : null}
        <span className="ml-auto flex shrink-0 items-center text-[12px] leading-4 font-medium">
          <Swap id={status.id} reduced={reduced}>
            {/* Each status carries its own color, so the leaving one keeps its tone as it fades. */}
            <span
              className={cn(
                "inline-flex items-center gap-1.5",
                status.tone === "muted" && "text-zinc-500 dark:text-zinc-400",
                status.tone === "accent" && "text-[var(--checkpoint-text)]",
                status.tone === "ink" && "text-zinc-950 dark:text-zinc-100",
              )}
            >
              {status.id === "cleared" ? (
                <Check className="size-3" />
              ) : status.tone === "ink" ? (
                <Cross className="size-3" />
              ) : (
                <span
                  aria-hidden
                  className={cn(
                    "size-1.5 rounded-full",
                    status.tone === "accent" ? "bg-[var(--checkpoint-accent)]" : "bg-zinc-950/25 dark:bg-white/30",
                  )}
                />
              )}
              <span className="@[28rem]/checkpoint:hidden">{status.short}</span>
              <span className="hidden max-w-[30ch] truncate @[28rem]/checkpoint:block">{status.text}</span>
            </span>
          </Swap>
        </span>
      </div>

      <span
        ref={tokenRef}
        aria-hidden
        className="pointer-events-none absolute top-0 left-[14px] z-[5] size-3 rounded-[4px] bg-[var(--checkpoint-accent)] shadow-[0_0_0_3px_color-mix(in_oklab,var(--checkpoint-accent)_18%,transparent)] will-change-transform"
      />

      <ol className="relative mt-3 space-y-2">
        {rules.map((rule, i) => (
          <RuleRow
            key={rule.id}
            rule={rule}
            holding={holding === i}
            onDecide={onDecide}
            onHoverActions={onHoverActions}
          />
        ))}
      </ol>

      {log ? (
        <div className="relative mt-3 h-[66px] overflow-hidden [mask-image:linear-gradient(to_bottom,#000_70%,transparent)]">
          <ol ref={logRef} className="will-change-transform" aria-label="Recent decisions">
            {entries.map((entry) => (
              <li key={entry.key} className="grid h-[22px] grid-cols-[2.5rem_minmax(0,1fr)_auto] items-center">
                <span className="grid place-items-center">
                  <span
                    className={cn(
                      "grid size-3 place-items-center rounded-[4px]",
                      entry.ok
                        ? "bg-[var(--checkpoint-accent)] text-white"
                        : "bg-zinc-950 text-white dark:bg-white dark:text-zinc-950",
                    )}
                  >
                    {entry.ok ? <Check className="size-2.5" /> : <Cross className="size-2.5" />}
                  </span>
                </span>
                <span className="min-w-0 truncate text-[12px] text-zinc-500 dark:text-zinc-400">
                  <span className="font-mono text-[11.5px] text-zinc-800 dark:text-zinc-200">{entry.label}</span>{" "}
                  {entry.note}
                </span>
                <span className="pl-3 font-mono text-[11px] text-zinc-400 tabular-nums dark:text-zinc-500">
                  {entry.time}
                </span>
              </li>
            ))}
          </ol>
        </div>
      ) : null}
    </div>
  );
}

/* ── RequestContent ───────────────────────────────────────── */
// The request card's contents. A new request slides in from the left; the
// first one is already there when the page loads.

function RequestContent({
  request,
  enter,
  reduced,
  speed,
}: {
  request: CheckpointRequest;
  enter: boolean;
  reduced: boolean;
  speed: number;
}) {
  const ref = React.useRef<HTMLDivElement>(null);
  // Each request mounts fresh (keyed), so it slides in at the speed it arrived with.
  const [slide] = React.useState(() => TIMING.enter.duration / speed);
  React.useLayoutEffect(() => {
    if (!enter || !ref.current) return;
    const a = ref.current.animate(
      reduced
        ? [{ opacity: 0 }, { opacity: 1 }]
        : [
            { opacity: 0, transform: `translateX(${-GATE.enter.distance}px)` },
            { opacity: 1, transform: "none" },
          ],
      {
        duration: reduced ? TIMING.reduced : slide,
        easing: TIMING.outEase,
      },
    );
    return () => a.cancel();
  }, [enter, reduced, slide]);

  return (
    <div ref={ref} data-part="content" className="flex min-w-0 items-center gap-3">
      <span
        data-part="icon"
        aria-hidden
        className="grid size-[26px] shrink-0 place-items-center rounded-lg bg-[color-mix(in_oklab,var(--checkpoint-accent)_12%,transparent)] text-[var(--checkpoint-accent)] [&_svg]:size-3.5"
      >
        {request.icon ?? <span className="size-1.5 rounded-full bg-current" />}
      </span>
      <span className="min-w-0">
        <span className="block truncate font-mono text-[13px] leading-[18px] text-zinc-950 dark:text-zinc-100">
          {request.label}
        </span>
        {request.meta ? (
          <span className="block truncate text-[12px] leading-4 text-zinc-500 dark:text-zinc-400">{request.meta}</span>
        ) : null}
      </span>
    </div>
  );
}