Trace waterfall

// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import {  useCallback,  useEffect,  useEffectEvent,  useId,  useLayoutEffect,  useMemo,  useRef,  useState,  type CSSProperties,  type Ref,} from 'react';import { GOAL, SPANS, type Span } from './data';import { DemoPointer, runDemo, type Point } from './demo-pointer';import { duration, money, spent, tick, tokens } from './format';import { Chevron, Cross, Sparkle, SpanGlyph, Warning } from './glyphs';import { useAutoplay } from './use-autoplay';import styles from './trace-waterfall.module.css';/*

/* Trace waterfall (trace-waterfall.tsx): a quiet grey stage with the card at its top, or at night   a near-black one with the card a step darker still. The card is laid out for 760 px: a header,   six totals, then the waterfall, a 256 px column of spans beside a timeline. Under 600 px of   card the column narrows to 152 px, the muted details go and the totals stack in two rows.   Time: the script writes --t (seconds into the run) and --range (the seconds the axis shows) on   .waterfall every frame while the run streams; each row carries its span's --s and --e. A bar   sits at s / range of the timeline and is (min(t, e) − s) / range wide, so it grows until its   end, and the label after it follows.   Colours are the tokens below, light-dark(light, dark) where the two differ: the component takes   the color-scheme it inherits from the page (light unless the page says otherwise), or the one   its colorScheme prop sets (data-color-scheme). */.root {  /* The stage, the card, its edge and the lines across it. */  --stage: #f7f7f7;  --card: #fdfdfd;  --edge: #e3e3e3;  --card-shadow: rgb(0 0 0 / 0.03);  --line: #ececec;  --divider: #e0e0e0;  --grid: #f0f0f0;  --guide: #e6e6e6;

// Copyright (c) 2026 Bruno Delorence. MIT License./* * The shapes the trace draws, and the run the lab shows: one agent launching a pricing page with * three sub-agents under it. Times are in seconds from the start of the run; a span shows once * the run's clock reaches its start, and runs until its end. *//** What a span is: an agent (with spans under it), a call to a model, or a call to a tool. */export type SpanKind = 'agent' | 'llm' | 'tool';/** The drawing on a span's tile, in glyphs.tsx: a model family's mark, or a tool's glyph. */export type SpanIcon =  | 'model-a'  | 'model-b'  | 'model-c'  | 'search'  | 'database'  | 'web'  | 'doc'  | 'design'  | 'repo'  | 'payments'  | 'crm'

// Copyright (c) 2026 Bruno Delorence. MIT License./* * How the trace writes its numbers: durations as a person reads them (637ms, 6.9s, 13s, 1m 22s), * money to the cent (or the tenth of a cent under one), tokens in thousands. *//** Seconds as 637ms, 6.9s, 13s or 1m 03s. Rounded down, so a live value never runs ahead. */export function duration(seconds: number) {  const s = Math.max(0, seconds);  if (s < 1) return `${Math.floor(s * 1000 + 1e-6)}ms`;  if (s < 10) return `${(Math.floor(s * 10 + 1e-6) / 10).toFixed(1)}s`;  if (s < 60) return `${Math.floor(s + 1e-6)}s`;  const whole = Math.floor(s + 1e-6);  return `${Math.floor(whole / 60)}m ${String(whole % 60).padStart(2, '0')}s`;}/** The axis's ticks: 0s, 20s, 1m, 1m 20s. */export function tick(seconds: number) {  if (seconds < 60) return `${seconds}s`;  const rest = seconds % 60;  return rest ? `${Math.floor(seconds / 60)}m ${rest}s` : `${seconds / 60}m`;}

// Copyright (c) 2026 Bruno Delorence. MIT License./* * The small drawings: a mark per model family and a glyph per tool, for the spans' tiles, plus * the header's sparkle, the chevron, the warning sign and the close cross. All on a 16-unit grid, * sized by the stylesheet. Ink-coloured strokes take --glyph-ink, so they turn light at night; * the coloured ones keep their colour on both schemes. */import type { SpanIcon } from './data';const INK = { stroke: 'var(--glyph-ink)' };function IconPath({ icon }: { icon: SpanIcon }) {  switch (icon) {    case 'model-a':      // Four rounded petals around a small open heart.      return (        <g fill="#d9614c">          <ellipse cx="8" cy="4" rx="2.1" ry="3.3" />          <ellipse cx="8" cy="12" rx="2.1" ry="3.3" />          <ellipse cx="4" cy="8" rx="3.3" ry="2.1" />          <ellipse cx="12" cy="8" rx="3.3" ry="2.1" />          <circle cx="8" cy="8" r="1.3" fill="var(--tile)" />

// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it. The arrow and the * hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {

// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and not while the reader is using it. `take()` hands it to the reader; it * takes back over `idle` ms after their last input. */export function useAutoplay<T extends HTMLElement>(idle = 6000) {  const ref = useRef<T>(null);  const [visible, setVisible] = useState(false);  const [reduced, setReduced] = useState(true);  const [taken, setTaken] = useState(false);  const timer = useRef(0);  useEffect(() => {    const element = ref.current;    if (!element) return;    let onScreen = false;    const update = () => setVisible(onScreen && !document.hidden);    const observer = new IntersectionObserver(