Slosh Gauge

'use client';

import './slosh-gauge.css';

import { useEffect, useState } from 'react';

import {
  useCanvasScene,
  useReducedMotion,
  type SceneDrawContext,
  type SceneSetupContext,
} from '@/hooks/use-canvas-scene';

/**
 * A level gauge whose liquid obeys the shallow-water equations.
 *
 * Depth and along-tank velocity live on a staggered grid — depth at the cell
 * centres, velocity at the faces between them — and are advanced by the pair of
 * conservation laws a tide model uses: mass in equals mass out, and water
 * accelerates down the slope of its own surface. Nothing here is a sine wave with
 * a phase offset. The crest that runs across the tank when the level changes is
 * the gravity wave the pour actually launched, travelling at √(g·h), and it turns
 * around at the far side because the wall is a zero-velocity boundary rather than
 * a place the animation happens to stop.
 *
 * The flux at every face is upwinded and the two end faces are pinned shut, so
 * the sum of the depths only ever changes by what the inlet adds. That is why the
 * gauge comes to rest on the number it was asked for, exactly, with nothing
 * easing it there.
 *
 * Move the pointer across the card to tilt the tank: its offset from the centre
 * becomes the along-bed component of gravity, and the surface takes up the slope
 * that implies.
 */

/** Seconds per step. */
const STEP = 1 / 240;
/**
 * Target cell width in pixels, rather than a fixed cell count. An explicit scheme
 * is stable while a wave crosses less than one cell per step, and the wave speed
 * is √(g·h) — so it is dx that has to hold still as the card resizes. A fixed
 * count would halve dx on a narrow phone and put the solver over the limit.
 */
const CELL = 6;
/** Gravity, px/s². With the depth, this is what sets the wave speed. */
const G = 1400;
/** Bed friction, linearised. The only thing that finally flattens the surface. */
const FRICTION = 2.2;
/** Along-bed gravity at full pointer deflection — a tilt of about fifteen degrees. */
const TILT = 380;
/** How fast the inlet may change the mean depth, in pixels per second. */
const POUR = 300;
/** Depth a cell is never taken below, so a dry cell cannot go negative. */
const FLOOR = 0.75;
/** Fraction of the card the tank fills at 100%. The rest is room for crests. */
const HEAD = 0.8;
/** Cells the inlet spreads over. One cell would be a spike, not a stream. */
const MOUTH = 9;

const LEVELS = [18, 46, 72, 96];

interface SloshState {
  readonly cells: number;
  readonly dx: number;
  /** Depth at the cell centres. The volume of water, in one array. */
  readonly h: Float64Array;
  /** Along-tank velocity at the faces between cells. Both ends stay at zero. */
  readonly u: Float64Array;
  readonly flux: Float64Array;
  /** Inlet weights, one per cell, summing to one so a pour adds exactly its budget. */
  readonly mouth: Float64Array;
  readonly mouthX: number;
  readonly bedY: number;
  readonly maxDepth: number;
  /** Wanted mean depth in pixels, written from the component's value each frame. */
  target: number;
  /** Along-bed gravity from the tilt, px/s². */
  gx: number;
  /** How hard the inlet ran on the last step, −1…1. Only used to draw the stream. */
  pour: number;
  carry: number;
  clock: number;
  /**
   * Put the tank at rest on the target and skip the solver. Set under
   * `prefers-reduced-motion`, where the loop never runs and a gauge that advanced
   * one accumulator's worth per repaint would never arrive.
   */
  snap: boolean;
}

/** The tank flat at the target level, stationary. */
function flatten(state: SloshState) {
  state.h.fill(Math.max(FLOOR, state.target));
  state.u.fill(0);
  state.pour = 0;
}

function step(state: SloshState) {
  const { cells, dx, h, u, flux, mouth } = state;

  /*
   * The inlet, rate-limited. Depth is added over a cosine bump rather than into
   * one cell: a point source at this rate is a spike a hundred pixels tall that
   * the solver then has to survive, and the wave it launches is nothing like the
   * one a stream of water launches.
   */
  let total = 0;
  for (let i = 0; i < cells; i++) total += h[i];
  const limit = POUR * cells * STEP;
  const move = Math.max(-limit, Math.min(limit, state.target * cells - total));
  state.pour = move / limit;
  if (move !== 0) {
    for (let i = 0; i < cells; i++) h[i] = Math.max(FLOOR, h[i] + move * mouth[i]);
  }
  /*
   * Momentum at the faces: water accelerates down the surface slope, is carried by
   * its own flow, leans with the tilt, and loses speed to the bed. The advection
   * term is upwinded — differencing it centrally is unstable at this Courant
   * number and shows up as a checkerboard along the surface inside a second.
   */
  for (let j = 1; j < cells; j++) {
    const speed = u[j];
    const slope = (h[j] - h[j - 1]) / dx;
    const shear = speed > 0 ? (speed - u[j - 1]) / dx : (u[j + 1] - speed) / dx;
    u[j] = speed + (-G * slope - speed * shear + state.gx - FRICTION * speed) * STEP;
  }

  /*
   * Continuity, in flux form. `flux[0]` and `flux[cells]` are never written, so no
   * water crosses the walls and the total is conserved to the last pixel — which
   * is the whole reason the settled level is the requested one and not near it.
   * The floor below is the one leak, and at these levels it never triggers.
   */
  for (let j = 1; j < cells; j++) flux[j] = u[j] * (u[j] > 0 ? h[j - 1] : h[j]);
  for (let i = 0; i < cells; i++) {
    h[i] = Math.max(FLOOR, h[i] - (flux[i + 1] - flux[i]) * (STEP / dx));
  }
}

function build({ width, height }: SceneSetupContext, value: number): SloshState {
  const cells = Math.max(24, Math.round(width / CELL));
  const dx = width / cells;
  const maxDepth = height * HEAD;

  // A raised-cosine inlet, normalised. Inset from the wall by its own width so the
  // bump is not half-clipped and the pour does not lean on the boundary.
  const mouth = new Float64Array(cells);
  const centre = Math.min(cells - 1, MOUTH);
  let weight = 0;
  for (let i = 0; i < cells; i++) {
    const away = Math.abs(i - centre) / MOUTH;
    if (away >= 1) continue;
    mouth[i] = 0.5 + 0.5 * Math.cos(Math.PI * away);
    weight += mouth[i];
  }
  for (let i = 0; i < cells; i++) mouth[i] /= weight;

  const state: SloshState = {
    cells,
    dx,
    h: new Float64Array(cells),
    u: new Float64Array(cells + 1),
    flux: new Float64Array(cells + 1),
    mouth,
    mouthX: (centre + 0.5) * dx,
    bedY: height,
    maxDepth,
    target: (maxDepth * value) / 100,
    gx: 0,
    pour: 0,
    carry: 0,
    clock: 0,
    snap: false,
  };

  // Starting flat and full is the honest initial condition: the tank was already
  // at this level before the component mounted.
  flatten(state);

  return state;
}
function paint({ context, width, height, state, pointer }: SceneDrawContext<SloshState>) {
  const now = performance.now();
  const elapsed = state.clock ? Math.min(0.05, (now - state.clock) / 1000) : STEP;
  state.clock = now;

  // The pointer's offset from the centre is the tilt. Leaving the card levels the
  // tank rather than freezing it at whatever angle the cursor left on.
  state.gx = pointer.inside ? TILT * ((pointer.x / width) * 2 - 1) : 0;

  state.carry += elapsed;
  let steps = 0;
  while (state.carry >= STEP && steps < 8) {
    step(state);
    state.carry -= STEP;
    steps += 1;
  }
  if (state.carry > STEP * 8) state.carry = 0;
  if (state.snap) flatten(state);

  const { cells, dx, h, bedY, maxDepth } = state;

  context.clearRect(0, 0, width, height);

  // Quarter marks, so the level reads as a measurement and not as decoration.
  context.strokeStyle = 'rgba(226,240,255,0.07)';
  context.lineWidth = 1;
  for (let mark = 1; mark <= 4; mark++) {
    const y = Math.round(bedY - (maxDepth * mark) / 4) + 0.5;
    context.beginPath();
    context.moveTo(0, y);
    context.lineTo(width, y);
    context.stroke();
  }

  // The surface polyline, walked twice: once as the lid of the body and once on its
  // own as the lit edge. Cell centres, with the two half-cells at the walls carried
  // out flat — the wall is where the velocity is zero, not where the depth is.
  const trace = () => {
    context.moveTo(0, bedY - h[0]);
    for (let i = 0; i < cells; i++) context.lineTo((i + 0.5) * dx, bedY - h[i]);
    context.lineTo(width, bedY - h[cells - 1]);
  };

  context.beginPath();
  trace();
  context.lineTo(width, bedY);
  context.lineTo(0, bedY);
  context.closePath();
  const body = context.createLinearGradient(0, bedY - maxDepth, 0, bedY);
  body.addColorStop(0, 'rgba(90,200,218,0.58)');
  body.addColorStop(1, 'rgba(22,84,124,0.9)');
  context.fillStyle = body;
  context.fill();

  context.beginPath();
  trace();
  context.strokeStyle = 'rgba(186,246,255,0.85)';
  context.lineWidth = 1.5;
  context.stroke();

  /*
   * The stream is drawn from the inlet's actual flux, so it appears when the gauge
   * is filling, thickens with the rate, and stops the instant the level is reached.
   * Draining is silent because the outlet is under the water.
   */
  if (state.pour > 0.02) {
    const cell = Math.min(cells - 1, Math.max(0, Math.round(state.mouthX / dx - 0.5)));
    const surface = Math.max(0, bedY - h[cell]);
    const stream = context.createLinearGradient(0, 0, 0, surface);
    stream.addColorStop(0, 'rgba(186,246,255,0.04)');
    stream.addColorStop(1, `rgba(186,246,255,${0.3 * state.pour})`);
    context.fillStyle = stream;
    const half = 1.5 + state.pour * 2.5;
    context.fillRect(state.mouthX - half, 0, half * 2, surface);
  }
}

/** `compact` is the 298x240 catalogue card: the same tank, given the whole frame,
 *  with the copy cut to one line along the bottom. Presentation only — the CSS. */
export type SloshGaugeProps = { compact?: boolean };

/**
 * The card is the component; the tank is its background. The canvas layer sits
 * underneath and the readout sits on top with `pointer-events: none`, so a move
 * anywhere over the card tilts the tank while the level keys keep their clicks —
 * the stage takes pointer capture as it tracks, and a real button inside it would
 * have its click swallowed by that capture.
 */
export function SloshGauge({ compact = false }: SloshGaugeProps) {
  const [value, setValue] = useState(46);
  const reduced = useReducedMotion();

  const { stageRef, canvasRef, requestRender } = useCanvasScene<SloshState>({
    setup: (scene) => build(scene, value),
    draw: (scene) => {
      scene.state.target = (scene.state.maxDepth * value) / 100;
      scene.state.snap = reduced;
      paint(scene);
    },
  });

  // The level has to repaint on its own account: with the loop stopped under
  // reduced motion nothing else would, and the water would stay at the old mark.
  useEffect(() => {
    requestRender();
  }, [value, requestRender]);

  return (
    <div className="slosh-gauge-stage" data-compact={compact ? 'true' : undefined}>
      <div className="slosh-gauge-card">
        <div ref={stageRef} className="slosh-gauge-tank" aria-hidden="true">
          <canvas ref={canvasRef} />
        </div>

        <div className="slosh-gauge-face">
          <div>
            <p className="slosh-gauge-label">Object storage</p>
            <p
              className="slosh-gauge-read"
              role="meter"
              aria-label="Object storage used"
              aria-valuemin={0}
              aria-valuemax={100}
              aria-valuenow={value}
              aria-valuetext={`${value} percent of 2 TB`}
            >
              {value}
              <span className="slosh-gauge-unit">%</span>
            </p>
            <p className="slosh-gauge-sub">of 2 TB provisioned</p>
          </div>

          <div className="slosh-gauge-keys" role="group" aria-label="Set level">
            {LEVELS.map((level) => (
              <button
                key={level}
                type="button"
                className="slosh-gauge-key"
                aria-pressed={level === value}
                // The card frame is aria-hidden, so inside it the keys leave the tab
                // order. They stay clickable — only the keyboard path is withdrawn.
                tabIndex={compact ? -1 : undefined}
                onClick={() => setValue(level)}
              >
                {level}%
              </button>
            ))}
          </div>
        </div>
      </div>

      <p className="slosh-gauge-hint">Move across to tilt</p>
    </div>
  );
}

export default SloshGauge;

.slosh-gauge-stage {
  position: relative;
  display: grid;
  place-content: center;
  width: 100%;
  min-height: 340px;
  padding: 2.5rem 1.5rem;
  overflow: hidden;
  border-radius: 0.75rem;
  background: radial-gradient(120% 110% at 50% 0%, #0c1620 0%, #070b12 60%, #05070c 100%);
  color: #eaf5ff;
}

.slosh-gauge-card {
  position: relative;
  width: min(23rem, 100%);
  height: 19rem;
  overflow: hidden;
  border: 1px solid rgba(255, 255, 255, 0.09);
  border-radius: 1rem;
  background: linear-gradient(180deg, rgba(255, 255, 255, 0.04), rgba(255, 255, 255, 0.015));
  isolation: isolate;
}

/* The tank, behind the readout. `overflow: hidden` on the card is what gives the
   water its rounded corners — the solver knows nothing about the border radius. */
.slosh-gauge-tank {
  position: absolute;
  inset: 0;
  touch-action: none;
}

.slosh-gauge-tank canvas {
  display: block;
  width: 100%;
  height: 100%;
}

/* Transparent to the pointer, so a move anywhere over the card still tilts the
   tank. Only the level keys take events back. */
.slosh-gauge-face {
  position: relative;
  display: flex;
  height: 100%;
  flex-direction: column;
  justify-content: space-between;
  padding: 1.25rem 1.375rem 1.125rem;
  pointer-events: none;
}

.slosh-gauge-label {
  margin: 0 0 0.5rem;
  font: 500 0.6875rem/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.14em;
  text-transform: uppercase;
  color: rgba(234, 245, 255, 0.5);
}

.slosh-gauge-read {
  margin: 0;
  font-size: 3.25rem;
  font-weight: 500;
  line-height: 0.92;
  letter-spacing: -0.035em;
  font-variant-numeric: tabular-nums;
  text-shadow: 0 1px 18px rgba(5, 12, 20, 0.55);
}

.slosh-gauge-unit {
  margin-left: 0.15em;
  font-size: 1.25rem;
  font-weight: 500;
  letter-spacing: -0.01em;
  color: rgba(234, 245, 255, 0.62);
}

.slosh-gauge-sub {
  margin: 0.5rem 0 0;
  font-size: 0.8125rem;
  color: rgba(234, 245, 255, 0.52);
  text-shadow: 0 1px 14px rgba(5, 12, 20, 0.5);
}

.slosh-gauge-keys {
  display: flex;
  gap: 0.3125rem;
}

.slosh-gauge-key {
  appearance: none;
  flex: 1;
  margin: 0;
  padding: 0.4375rem 0;
  border: 1px solid rgba(255, 255, 255, 0.14);
  border-radius: 999px;
  background: rgba(6, 14, 22, 0.42);
  font: inherit;
  font-size: 0.75rem;
  font-weight: 500;
  font-variant-numeric: tabular-nums;
  color: rgba(234, 245, 255, 0.72);
  cursor: pointer;
  pointer-events: auto;
  backdrop-filter: blur(6px);
  transition:
    border-color 160ms ease,
    background-color 160ms ease,
    color 160ms ease;
}

.slosh-gauge-key:hover {
  border-color: rgba(186, 246, 255, 0.4);
  color: #f2fbff;
}

.slosh-gauge-key[aria-pressed='true'] {
  border-color: rgba(186, 246, 255, 0.62);
  background: rgba(186, 246, 255, 0.16);
  color: #f5fdff;
}

.slosh-gauge-key:focus-visible {
  outline: 2px solid rgba(186, 246, 255, 0.75);
  outline-offset: 2px;
}

.slosh-gauge-hint {
  position: absolute;
  right: 0.875rem;
  bottom: 0.75rem;
  margin: 0;
  font: 500 0.6875rem/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  color: rgba(234, 245, 255, 0.28);
  pointer-events: none;
}

/*
 * With the loop stopped the tank is placed flat at the requested level and stays
 * there. Pressing a key still moves the water, because the component asks for one
 * repaint and the solver is skipped in favour of the settled state — what is gone
 * is the wave in between, which is the part that was asked to go.
 */
@media (prefers-reduced-motion: reduce) {
  .slosh-gauge-key {
    transition: none;
  }
}

/*
 * The card variant: the same tank authored for the 298x240 catalogue frame rather
 * than scaled into it. The section padding goes, the gauge becomes the frame — water
 * edge to edge — and the readout drops to a strip along the bottom with the level
 * keys beside it. No `vw` and no `clamp()` anywhere below: the card is 298px wide and
 * the viewport it sits in is not.
 */
.slosh-gauge-stage[data-compact='true'] {
  min-height: 0;
  height: 100%;
  padding: 0;
  /* The card frame rounds and clips already. */
  border-radius: 0;
}

/*
 * The gauge fills the frame instead of floating centred in it: 298 x 240 of tank,
 * which at 100% is 192px of water with 48px of headroom left for the crests. Absolute
 * rather than a stretched grid item, so the height is the frame's and not a track
 * sized from whatever is left once the copy has gone.
 */
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-card {
  position: absolute;
  inset: 0;
  width: auto;
  height: auto;
  border: 0;
  border-radius: 0;
}

/*
 * `pan-y`, not `none`. The tank is now the full bleed of the card, and a drag surface
 * that swallows vertical touches traps the page in a scrolling grid of cards, which is
 * the worse failure by a distance. Nothing is lost here: the tilt is read from the
 * pointer's x alone, so a sideways drag still tips the tank its full fifteen degrees.
 */
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-tank {
  touch-action: pan-y;
}

/*
 * The readout off the tank's back and onto the bottom edge, one row instead of a
 * column, so the water and its crests get the box rather than sharing it with a
 * column of type. Still deaf to the pointer, so a drag across it tilts the tank.
 */
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-face {
  position: absolute;
  inset: auto 0 0 0;
  height: auto;
  flex-direction: row;
  align-items: flex-end;
  gap: 0.5rem;
  padding: 0.75rem;
  pointer-events: none;
}

/* Everything but the level: the provisioned figure is a sentence, the section label is
   what the card's own title already says, and the hint asks for a hover a phone has
   not got. */
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-label,
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-sub,
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-hint {
  display: none;
}

/*
 * The one line that stays, at a fixed 22px. It is the readout because the readout is
 * the state — it is the number the water is asked for and settles on, so the card says
 * what the level means rather than only showing a coloured shape move. From 3.25rem,
 * which was sized for a 19rem card in a 340px section. The water is behind it at the
 * upper levels, which is what the text-shadow already on it is for.
 */
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-read {
  font-size: 1.375rem;
  line-height: 1;
  white-space: nowrap;
}

.slosh-gauge-stage[data-compact='true'] .slosh-gauge-unit {
  font-size: 0.6875rem;
}

/*
 * The keys stay, because pressing one is the pour — the crest that runs the length of
 * the tank is the half of this animation a hover cannot show. Sized to sit on the
 * strip beside the readout, and still the only thing here taking the pointer back.
 */
.slosh-gauge-stage[data-compact='true'] .slosh-gauge-keys {
  gap: 0.25rem;
}

.slosh-gauge-stage[data-compact='true'] .slosh-gauge-key {
  flex: 0 0 auto;
  padding: 0.25rem 0.4375rem;
  font-size: 0.625rem;
  pointer-events: auto;
}

"use client"

import { useCallback, useEffect, useRef, useState } from "react"

/**
 * The canvas preamble every 2D scene needs, in one place: a DPR-scaled backing
 * store, a rebuild on resize, a loop that stops when the stage scrolls out of
 * view, pointer tracking with per-frame deltas, and teardown.
 *
 * A scene supplies two functions. `setup` builds whatever mutable state the
 * animation owns and is re-run whenever the stage changes size, so the state can
 * be sized to the stage without ever being resized in place. `draw` paints one
 * frame from that state — it is called with the transform already scaled to
 * device pixels, so every coordinate in it is a CSS pixel.
 */

export type ScenePointer = {
  x: number
  y: number
  /** Position at the previous painted frame, so `x - lastX` is a frame delta. */
  lastX: number
  lastY: number
  down: boolean
  inside: boolean
}

export type SceneSetupContext = {
  context: CanvasRenderingContext2D
  width: number
  height: number
  dpr: number
}

export type SceneDrawContext<State> = SceneSetupContext & {
  state: State
  pointer: ScenePointer
  /** Painted frames since the last rebuild. Useful for every-Nth-frame work. */
  frame: number
}

export type CanvasSceneOptions<State> = {
  setup: (context: SceneSetupContext) => State
  draw: (context: SceneDrawContext<State>) => void
}

export type CanvasScene = {
  /** The sizing element. Owns the pointer listeners and is what is observed. */
  stageRef: (node: HTMLDivElement | null) => void
  canvasRef: (node: HTMLCanvasElement | null) => void
  /** Paint one frame now. The escape hatch for a paused or reduced-motion loop. */
  requestRender: () => void
}

/** Live `prefers-reduced-motion`. False during SSR and the first paint. */
export function useReducedMotion() {
  const [reduced, setReduced] = useState(false)

  useEffect(() => {
    const query = window.matchMedia("(prefers-reduced-motion: reduce)")
    setReduced(query.matches)
    const onChange = () => setReduced(query.matches)
    query.addEventListener("change", onChange)
    return () => query.removeEventListener("change", onChange)
  }, [])

  return reduced
}

export function useCanvasScene<State>(options: CanvasSceneOptions<State>): CanvasScene {
  const reduced = useReducedMotion()

  /*
   * `draw` is usually an inline closure, so it is a new function on every
   * render. Reading it through a ref keeps the loop from being torn down and
   * the scene from being rebuilt each time the component re-renders.
   */
  const optionsRef = useRef(options)
  optionsRef.current = options

  const stage = useRef<HTMLDivElement | null>(null)
  const canvas = useRef<HTMLCanvasElement | null>(null)

  /*
   * Plain ref assignment, with no state behind it. React attaches refs during
   * the commit phase, before passive effects run, so the effect below already
   * sees both nodes on the first mount — which is why these used to bump a
   * `mounted` counter for nothing: the two `setMounted` calls batched into one
   * re-render, the counter went 0 → 2, and the effect's dependency on it tore
   * the live scene down and rebuilt it. Every scene was constructed, measured
   * and warmed twice on every mount, four times under StrictMode in dev.
   *
   * The requirement this trades for that: a consumer must render the stage and
   * the canvas unconditionally, in the same commit as the component itself. All
   * thirteen do. Gating the canvas behind a flag would leave the effect bailing
   * on the null guard with nothing to re-run it.
   */
  const stageRef = useCallback((node: HTMLDivElement | null) => {
    stage.current = node
  }, [])
  const canvasRef = useCallback((node: HTMLCanvasElement | null) => {
    canvas.current = node
  }, [])

  /** Set once the scene is live, so `requestRender` before that is a no-op. */
  const render = useRef<(() => void) | null>(null)
  const requestRender = useCallback(() => render.current?.(), [])

  useEffect(() => {
    const stageNode = stage.current
    const canvasNode = canvas.current
    if (!stageNode || !canvasNode) return

    const context = canvasNode.getContext("2d")
    if (!context) return

    const pointer: ScenePointer = {
      x: 0,
      y: 0,
      lastX: 0,
      lastY: 0,
      down: false,
      inside: false,
    }

    let state: State | null = null
    let width = 0
    let height = 0
    let dpr = 1
    let frame = 0
    let loop = 0
    let pending = 0
    let visible = true

    /** Rebuild the backing store and the scene state for the current size. */
    const measure = () => {
      // `offsetWidth`/`offsetHeight`, not `getBoundingClientRect()`: the rect is
      // post-transform, so a scene sitting inside a scaled ancestor measured its
      // own frame at the scaled size, sized the backing store to that, and then
      // had CSS scale the result a second time — the scene ran at a fraction of
      // the box it was drawn into. The catalogue's scaled-poster branch is the
      // one place that happens, and it is reachable again the moment an
      // animation is registered without a card composition. These two properties
      // are the untransformed layout box; both are integers, which is what the
      // rounding below already reduced the rect to.
      const nextWidth = Math.max(1, stageNode.offsetWidth)
      const nextHeight = Math.max(1, stageNode.offsetHeight)
      const nextDpr = Math.min(2, window.devicePixelRatio || 1)
      if (nextWidth === width && nextHeight === height && nextDpr === dpr && state) return

      width = nextWidth
      height = nextHeight
      dpr = nextDpr
      canvasNode.width = Math.round(width * dpr)
      canvasNode.height = Math.round(height * dpr)
      canvasNode.style.width = `${width}px`
      canvasNode.style.height = `${height}px`
      frame = 0
      state = optionsRef.current.setup({ context, width, height, dpr })
    }

    const paint = () => {
      if (!state) return
      // Re-applied every frame: a scene is free to install its own transform
      // for a cell or a sprite, and most do.
      context.setTransform(dpr, 0, 0, dpr, 0, 0)
      optionsRef.current.draw({ context, width, height, dpr, state, pointer, frame })
      pointer.lastX = pointer.x
      pointer.lastY = pointer.y
      frame += 1
    }

    /** One frame on the next tick, coalescing however many were asked for. */
    const paintOnce = () => {
      if (pending) return
      pending = requestAnimationFrame(() => {
        pending = 0
        measure()
        paint()
      })
    }
    render.current = paintOnce

    const tick = () => {
      loop = requestAnimationFrame(tick)
      if (visible) paint()
    }

    const start = () => {
      if (loop || reduced) return
      loop = requestAnimationFrame(tick)
    }
    const stop = () => {
      if (!loop) return
      cancelAnimationFrame(loop)
      loop = 0
    }

    const at = (event: PointerEvent) => {
      const rect = stageNode.getBoundingClientRect()
      // The rect is the right thing to subtract here — `clientX` is viewport
      // space and so is the rect — but the difference comes back in *rendered*
      // pixels, and a scene reads `pointer` in the scene pixels `measure()` set
      // up from the untransformed box. Under a CSS scale those two disagree, so
      // divide the transform back out. `rect.width / offsetWidth` is the scale
      // actually in force, whatever produced it, and it is exactly 1 when there
      // is none.
      const scale = stageNode.offsetWidth > 0 ? rect.width / stageNode.offsetWidth : 1
      pointer.x = (event.clientX - rect.left) / (scale || 1)
      pointer.y = (event.clientY - rect.top) / (scale || 1)
      // A frozen loop still owes the user feedback for a drag.
      if (reduced) paintOnce()
    }

    const onEnter = (event: PointerEvent) => {
      pointer.inside = true
      at(event)
      pointer.lastX = pointer.x
      pointer.lastY = pointer.y
    }
    const onMove = (event: PointerEvent) => {
      pointer.inside = true
      at(event)
    }
    const onDown = (event: PointerEvent) => {
      pointer.down = true
      at(event)
      // Capture keeps a drag alive past the edge of the stage, which is where
      // a hard throw naturally ends up.
      stageNode.setPointerCapture(event.pointerId)
    }
    const onUp = (event: PointerEvent) => {
      pointer.down = false
      at(event)
      if (stageNode.hasPointerCapture(event.pointerId)) {
        stageNode.releasePointerCapture(event.pointerId)
      }
    }
    const onLeave = () => {
      pointer.inside = false
      pointer.down = false
      if (reduced) paintOnce()
    }

    stageNode.addEventListener("pointerenter", onEnter)
    stageNode.addEventListener("pointermove", onMove)
    stageNode.addEventListener("pointerdown", onDown)
    stageNode.addEventListener("pointerup", onUp)
    stageNode.addEventListener("pointercancel", onUp)
    stageNode.addEventListener("pointerleave", onLeave)

    const resizes = new ResizeObserver(() => paintOnce())
    resizes.observe(stageNode)

    /*
     * An animation nobody can see is heat. The observer both pauses the loop
     * and, on the way back in, repaints immediately rather than waiting a frame.
     */
    const views = new IntersectionObserver(
      (entries) => {
        visible = entries.some((entry) => entry.isIntersecting)
        if (visible) {
          start()
          paintOnce()
        } else {
          stop()
        }
      },
      { rootMargin: "120px" },
    )
    views.observe(stageNode)

    measure()
    paint()
    start()

    return () => {
      render.current = null
      stop()
      if (pending) cancelAnimationFrame(pending)
      resizes.disconnect()
      views.disconnect()
      stageNode.removeEventListener("pointerenter", onEnter)
      stageNode.removeEventListener("pointermove", onMove)
      stageNode.removeEventListener("pointerdown", onDown)
      stageNode.removeEventListener("pointerup", onUp)
      stageNode.removeEventListener("pointercancel", onUp)
      stageNode.removeEventListener("pointerleave", onLeave)
    }
  }, [reduced])

  return { stageRef, canvasRef, requestRender }
}