Cart-Pole Progress

'use client';

import './balance-progress.css';

import { useEffect, useState } from 'react';

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

/**
 * A five-stage release bar whose fill is carried by a cart balancing an inverted pole.
 *
 * The pair integrated here is the exact nonlinear cart-pole, not the small-angle version: the
 * shared 1 / (m_cart + m_pole) term couples the bodies both ways, the pole's angular acceleration
 * is subtracted back out of the cart, and the m_pole cos^2 term sits inside the effective inertia.
 * Linearising is easier and is also false at the angles this reaches — fourteen degrees on a stage
 * change, far more under a drag — where the reaction on the cart is most of what sells the mass.
 *
 * Steering is a cascade: a fast PD loop on pole angle (about 12 rad/s) inside a slow proportional
 * loop on cart position (about 4 rad/s). The outer loop cannot command travel, only lean, so
 * pressing a stage sends the cart the WRONG WAY first to topple the pole toward the target, then
 * chases it. That backwards step is the plant's right-half-plane zero, not a flourish. The clamp is
 * on force, never on angle: clamping the angle deletes the pole's mass and leaves a tween.
 */

const STEP = 1 / 150;
const STAGES = ['Draft', 'Review', 'Build', 'Canary', 'Live'];
const MASS_CART = 1;
const MASS_POLE = 0.14;
const POLE_HALF = 0.3; // half-length of a uniform rod, which is what the 4/3 inertia term assumes
const GRAVITY = 9.81;
const CART_DRAG = 0.6; // viscous, not Coulomb: sign(v) chatters at a fixed step and jams the cart
const POLE_DAMP = 0.006;
const GAIN_ANGLE = 70; // inner PD -> omega_n 11.9 rad/s, zeta 0.8, DC gain 1.19 on the lean ask
const GAIN_RATE = 7.9;
const GAIN_POS = 1.4; // outer P -> omega_n 4 rad/s, three times slower so the cascade holds
const GAIN_VEL = 0.7;
const MAX_TILT = 0.2; // radians of lean the outer loop may ask for
const MAX_FORCE = 24; // newtons at the wheels; the only clamp in the loop
const MAX_SPIN = 6; // a drag can never hand the pole more than this, so recovery always exists
const KICK = 9; // rad/s of tip spin per world unit of pointer travel
const WALL = 1.06;
const TRAIL = 26;
const WARM = 84; // 0.56 s of the real solver before the first paint
const ACCENT = '255, 196, 107';

interface State {
  clock: number;
  carry: number;
  snap: boolean;
  x: number; // cart position, world units; -1 and +1 are the ends of the bar
  xd: number;
  th: number; // pole angle from upright, positive leaning toward +x
  thd: number;
  force: number;
  target: number;
  kick: number; // pointer travel waiting to be handed to the pole as spin
  trail: Float64Array; // tip path in world units: x absolute, y measured down from the pivot line
  head: number;
}

const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v);

const worldOf = (stage: number) => -1 + stage * (2 / (STAGES.length - 1));

/**
 * theta'' = (g sin t - cos t * S - d theta') / (l (4/3 - m_p cos^2 t / M))
 *     x'' = S - m_p l theta'' cos t / M,  where S = (F - b x' + m_p l theta'^2 sin t) / M
 *
 * The denominator bottoms out at l (4/3 - m_p / M) = 0.363, so it can never reach zero and no
 * guard is needed there. Semi-implicit order — rate first, then position — because plain Euler
 * pumps energy into the pole at this stiffness and the pole slowly spins itself up.
 */
function advance(s: State) {
  const lean = clamp(GAIN_POS * (s.target - s.x) - GAIN_VEL * s.xd, -MAX_TILT, MAX_TILT);
  s.force = clamp(GAIN_ANGLE * (s.th - lean) + GAIN_RATE * s.thd, -MAX_FORCE, MAX_FORCE);
  const c = Math.cos(s.th);
  const sn = Math.sin(s.th);
  const total = MASS_CART + MASS_POLE;
  const shared = (s.force - CART_DRAG * s.xd + MASS_POLE * POLE_HALF * s.thd * s.thd * sn) / total;
  const thAcc =
    (GRAVITY * sn - c * shared - POLE_DAMP * s.thd) /
    (POLE_HALF * (4 / 3 - (MASS_POLE * c * c) / total));
  const xAcc = shared - (MASS_POLE * POLE_HALF * thAcc * c) / total;
  s.thd += thAcc * STEP;
  s.th += s.thd * STEP;
  // Wrap into (-pi, pi]. The inner loop reads this angle raw, so an unwrapped one is fatal: once a
  // hard drag carries the pole over the top, the error keeps counting up past 2pi, the force pins
  // at +MAX_FORCE against the wall and the pole windmills for good. sin and cos do not care about
  // the wrap, so nothing drawn changes. One step moves at most MAX_SPIN * STEP = 0.04 rad, so a
  // single correction always lands inside the range.
  if (s.th > Math.PI) {
    s.th -= 2 * Math.PI;
  } else if (s.th < -Math.PI) {
    s.th += 2 * Math.PI;
  }
  s.xd += xAcc * STEP;
  s.x += s.xd * STEP;
  // Hard stops at the bar ends, so an overshoot can never draw the cart off its own track.
  if (s.x > WALL) {
    s.x = WALL;
    s.xd = Math.min(0, s.xd);
  } else if (s.x < -WALL) {
    s.x = -WALL;
    s.xd = Math.max(0, s.xd);
  }
}

function pushTip(s: State) {
  const len = 2 * POLE_HALF;
  s.trail[s.head * 2] = s.x + Math.sin(s.th) * len;
  s.trail[s.head * 2 + 1] = -Math.cos(s.th) * len;
  s.head = (s.head + 1) % TRAIL;
}

function capsule(context: CanvasRenderingContext2D, x0: number, x1: number, y: number, r: number) {
  // Ordered ends, because the force readout is drawn backwards half the time and an unordered
  // pair would collapse the left-pointing case to a dot — the very frames worth seeing.
  const a = Math.min(x0, x1);
  const b = Math.max(x0, x1);
  context.beginPath();
  context.arc(a, y, r, Math.PI / 2, -Math.PI / 2);
  context.arc(b, y, r, -Math.PI / 2, Math.PI / 2);
  context.closePath();
  context.fill();
}

/** `compact` is the 298x240 catalogue-card variant: presentation only, all of it CSS. */
export type BalanceProgressProps = { compact?: boolean };

export function BalanceProgress({ compact = false }: BalanceProgressProps) {
  const reduced = useReducedMotion();
  const [stage, setStage] = useState(2);

  // Typed without binding the argument: the warm-up is pure physics in world units and needs no
  // geometry, and an unused parameter fails the build.
  const setup: (c: SceneSetupContext) => State = () => {
    const s: State = {
      clock: 0,
      carry: 0,
      snap: reduced,
      x: worldOf(0),
      xd: 0,
      th: 0,
      thd: 0,
      force: 0,
      target: worldOf(stage),
      kick: 0,
      trail: new Float64Array(TRAIL * 2),
      head: 0,
    };
    if (reduced) {
      s.x = s.target;
      return s;
    }
    // Warm the real solver so the first painted frame is already mid-transit and leaning, and seed
    // the tip streak from it — nothing here is a shortcut around the loop, it IS the loop.
    for (let i = 0; i < WARM; i += 1) {
      advance(s);
      if (i % 3 === 0) pushTip(s);
    }
    return s;
  };

  const draw = ({ context, width, height, state, pointer }: SceneDrawContext<State>) => {
    const now = performance.now() / 1000;
    const dt = state.clock === 0 ? 0 : Math.min(0.05, now - state.clock);
    state.clock = now;
    state.target = worldOf(stage);

    const mid = width / 2;
    const trackY = Math.round(Math.min(height - 92, height * 0.7));
    // Width sets the scale and height caps it. The pole is 0.6 world units long, so on a wide,
    // short card an uncapped scale swings the tip out through the top of the stage, where
    // overflow: hidden eats it. The floor keeps the pointer-to-world division finite.
    const scale = Math.max(48, Math.min((width - 92) / 2, (trackY - 46) / (2 * POLE_HALF)));
    const px = (wx: number) => mid + wx * scale;

    if (state.snap) {
      state.x = state.target;
      state.xd = 0;
      state.th = 0;
      state.thd = 0;
      state.force = 0;
    } else {
      if (pointer.down && pointer.inside) {
        state.kick += ((pointer.x - pointer.lastX) / scale) * KICK;
      }
      if (state.kick !== 0) {
        // Spend the whole frame's drag as one impulse on the tip. Capping the resulting spin is
        // what keeps a furious drag inside the envelope the clamped force can still recover from.
        state.thd = clamp(state.thd + clamp(state.kick, -1.6, 1.6), -MAX_SPIN, MAX_SPIN);
        state.kick = 0;
      }
      state.carry += dt;
      let n = 0;
      while (state.carry >= STEP && n < 8) {
        advance(state);
        state.carry -= STEP;
        n += 1;
      }
      if (n === 8) {
        state.carry = 0;
      }
      pushTip(state);
    }

    context.clearRect(0, 0, width, height);
    const cartX = px(state.x);

    context.fillStyle = 'rgba(255, 255, 255, 0.075)';
    capsule(context, px(-1), px(1), trackY, 4.5);
    context.fillStyle = `rgba(${ACCENT}, 0.82)`;
    capsule(context, px(-1), Math.max(px(-1), cartX), trackY, 4.5);

    for (let i = 0; i < STAGES.length; i += 1) {
      const wx = worldOf(i);
      const passed = state.x >= wx - 0.012;
      context.fillStyle = passed ? 'rgba(10, 14, 23, 0.85)' : 'rgba(255, 255, 255, 0.24)';
      context.beginPath();
      context.arc(px(wx), trackY, 2.6, 0, Math.PI * 2);
      context.fill();
    }

    context.strokeStyle = `rgba(${ACCENT}, 0.4)`;
    context.lineWidth = 1;
    context.setLineDash([3, 4]);
    context.beginPath();
    context.moveTo(px(state.target), trackY - 44);
    context.lineTo(px(state.target), trackY + 30);
    context.stroke();
    context.setLineDash([]);

    // The force the inner loop is actually asking for, drawn from the cart it acts on. On a stage
    // change it points away from the dashed target for the first third of a second; that is the
    // whole mechanism, so it is on screen rather than in the console.
    const clipped = Math.abs(state.force) > MAX_FORCE - 0.05;
    context.fillStyle = clipped ? 'rgba(255, 255, 255, 0.6)' : `rgba(${ACCENT}, 0.5)`;
    capsule(context, cartX, cartX + state.force * 1.4, trackY + 20, 1.5);

    const wheelR = 5.5;
    const wheelY = trackY - 10;
    const spin = (state.x * scale) / wheelR; // kinematic: no rolling constraint is solved, it reads
    for (let i = -1; i <= 1; i += 2) {
      const wx = cartX + i * 8;
      context.fillStyle = 'rgba(12, 17, 27, 0.95)';
      context.strokeStyle = 'rgba(255, 255, 255, 0.32)';
      context.lineWidth = 1.4;
      context.beginPath();
      context.arc(wx, wheelY, wheelR, 0, Math.PI * 2);
      context.fill();
      context.stroke();
      context.beginPath();
      context.moveTo(wx - Math.cos(spin) * 3.6, wheelY - Math.sin(spin) * 3.6);
      context.lineTo(wx + Math.cos(spin) * 3.6, wheelY + Math.sin(spin) * 3.6);
      context.stroke();
    }

    context.fillStyle = '#e8edf7';
    capsule(context, cartX - 13, cartX + 13, trackY - 22, 8);

    const pivotY = trackY - 30;
    const poleLen = 2 * POLE_HALF * scale;

    // Tip history is absolute, so the streak is the path the mass took across the bar rather than
    // a decoration stuck to the cart. It is the clearest tell that the lean leads the travel.
    if (!state.snap) {
      context.lineWidth = 1.6;
      for (let i = 1; i < TRAIL; i += 1) {
        const a = (state.head + i) % TRAIL;
        const b = (state.head + i - 1) % TRAIL;
        context.strokeStyle = `rgba(${ACCENT}, ${((i / TRAIL) * 0.34).toFixed(3)})`;
        context.beginPath();
        context.moveTo(px(state.trail[b * 2]), pivotY + state.trail[b * 2 + 1] * scale);
        context.lineTo(px(state.trail[a * 2]), pivotY + state.trail[a * 2 + 1] * scale);
        context.stroke();
      }
    }

    const tipX = cartX + Math.sin(state.th) * poleLen;
    const tipY = pivotY - Math.cos(state.th) * poleLen;
    context.strokeStyle = 'rgba(232, 237, 247, 0.88)';
    context.lineWidth = 3;
    context.lineCap = 'round';
    context.beginPath();
    context.moveTo(cartX, pivotY);
    context.lineTo(tipX, tipY);
    context.stroke();
    context.lineCap = 'butt';

    context.fillStyle = `rgb(${ACCENT})`;
    context.beginPath();
    context.arc(tipX, tipY, 6.5, 0, Math.PI * 2);
    context.fill();

    context.fillStyle = 'rgba(10, 14, 23, 0.9)';
    context.beginPath();
    context.arc(cartX, pivotY, 2.4, 0, Math.PI * 2);
    context.fill();
  };

  const { stageRef, canvasRef, requestRender } = useCanvasScene<State>({ setup, draw });
  useEffect(() => requestRender(), [reduced, stage, requestRender]);

  return (
    <div className="balance-progress-stage" data-compact={compact ? 'true' : undefined}>
      <div ref={stageRef} className="balance-progress-surface">
        <canvas ref={canvasRef} aria-hidden="true" />
      </div>
      <div className="balance-progress-content">
        <div>
          <p className="balance-progress-eyebrow">Release pipeline</p>
          <div className="balance-progress-head">
            <h3 className="balance-progress-title">{STAGES[stage]}</h3>
            <span className="balance-progress-percent">
              {Math.round(stage * (100 / (STAGES.length - 1)))}%
            </span>
          </div>
          <p className="balance-progress-sub">
            The cart carries the fill and balances the pole while it moves. It has to lean toward the
            stage you pick before it can travel there, so the first step is always backwards.
          </p>
        </div>
        <nav className="balance-progress-steps" aria-label="Release stage">
          {STAGES.map((name, i) => (
            /* Still clickable in a card — only the tab order changes, because the card
               frame is aria-hidden and a focusable node under that is a real bug. */
            <button
              key={name}
              type="button"
              className="balance-progress-step"
              aria-current={i === stage ? 'step' : undefined}
              tabIndex={compact ? -1 : undefined}
              onClick={() => setStage(i)}
            >
              {name}
            </button>
          ))}
        </nav>
      </div>
      <p className="balance-progress-hint">drag to disturb</p>
    </div>
  );
}

export default BalanceProgress;

.balance-progress-stage {
  position: relative;
  display: grid;
  width: 100%;
  min-height: 20rem;
  padding: 1.75rem 1.75rem 1.5rem;
  overflow: hidden;
  border-radius: 0.75rem;
  background: radial-gradient(120% 120% at 50% 0%, #111a29 0%, #0a0e17 58%, #06080e 100%);
  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.07);
  font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
  color: #eef1f7;
  isolation: isolate;
}

/* The measured element carries no border: `inset: 0` resolves against the padding
   box, so one pixel of border would shift the canvas origin and the cart would ride
   beside the track instead of on it. The hairline lives on the stage as a shadow. */
.balance-progress-surface {
  position: absolute;
  inset: 0;
  touch-action: none;
}

.balance-progress-surface canvas {
  display: block;
  width: 100%;
  height: 100%;
}

/* Transparent to the pointer so a drag anywhere over the card still reaches the
   pole. Only the stage buttons take events back, and they can because they are a
   later sibling of the capture surface rather than a child of it. */
.balance-progress-content {
  position: relative;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
  pointer-events: none;
}

.balance-progress-eyebrow {
  margin: 0 0 0.625rem;
  font: 500 0.6875rem/1 ui-monospace, 'SFMono-Regular', Menlo, monospace;
  letter-spacing: 0.14em;
  text-transform: uppercase;
  color: rgba(238, 241, 247, 0.48);
}

.balance-progress-head {
  display: flex;
  align-items: baseline;
  justify-content: space-between;
  gap: 1rem;
}

.balance-progress-title {
  margin: 0;
  font-size: 1.5rem;
  font-weight: 500;
  line-height: 1.1;
  letter-spacing: -0.02em;
  text-shadow: 0 1px 16px rgba(6, 8, 14, 0.75);
}

.balance-progress-percent {
  font-size: 0.875rem;
  font-weight: 500;
  font-variant-numeric: tabular-nums;
  letter-spacing: 0.02em;
  color: #ffc46b;
  text-shadow: 0 1px 16px rgba(6, 8, 14, 0.8);
}

.balance-progress-sub {
  max-width: 24rem;
  margin: 0.5rem 0 0;
  font-size: 0.8125rem;
  line-height: 1.45;
  color: rgba(238, 241, 247, 0.55);
  text-shadow: 0 1px 14px rgba(6, 8, 14, 0.85);
}

.balance-progress-steps {
  display: flex;
  gap: 0.3125rem;
}

.balance-progress-step {
  appearance: none;
  flex: 1;
  min-width: 0;
  margin: 0;
  padding: 0.5rem 0.25rem;
  overflow: hidden;
  border: 1px solid rgba(255, 255, 255, 0.13);
  border-radius: 999px;
  background: rgba(8, 12, 20, 0.5);
  font: inherit;
  font-size: 0.75rem;
  font-weight: 500;
  letter-spacing: 0.01em;
  white-space: nowrap;
  text-overflow: ellipsis;
  color: rgba(238, 241, 247, 0.7);
  cursor: pointer;
  pointer-events: auto;
  backdrop-filter: blur(6px);
  transition:
    border-color 160ms ease,
    background-color 160ms ease,
    color 160ms ease;
}

.balance-progress-step:hover {
  border-color: rgba(255, 196, 107, 0.45);
  color: #fff6e8;
}

.balance-progress-step[aria-current='step'] {
  border-color: rgba(255, 196, 107, 0.65);
  background: rgba(255, 196, 107, 0.16);
  color: #fff3e0;
}

.balance-progress-step:focus-visible {
  outline: 2px solid rgba(255, 196, 107, 0.8);
  outline-offset: 2px;
}

.balance-progress-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(238, 241, 247, 0.26);
  pointer-events: none;
}

@media (max-width: 26rem) {
  .balance-progress-stage {
    padding: 1.5rem 1rem 1.375rem;
  }

  .balance-progress-title {
    font-size: 1.25rem;
  }

  .balance-progress-step {
    padding: 0.5rem 0.125rem;
    font-size: 0.6875rem;
    letter-spacing: 0;
  }
}

/*
 * With the loop stopped the cart is placed at the selected stage, upright, and the
 * bar reads that stage exactly — the analytic rest state of the pair, which is the
 * one state the controller is trying to reach anyway. What is switched off is the
 * lean, the backwards step and the settling wobble, plus the button colour fades.
 * Pressing a stage still repaints, so the picture is never stale, and a drag no
 * longer does anything because there is no frame in which to recover from it.
 */
@media (prefers-reduced-motion: reduce) {
  .balance-progress-step {
    transition: none;
  }
}

/*
 * Card variant: the same component authored for the 298x240 catalogue frame, unscaled.
 * The stage stops being a section — the canvas takes the whole box, the copy collapses
 * to the eyebrow, and the stage buttons shrink into a strip pinned below the track, so
 * the cart, the pole and its tip streak are the only things with room.
 */
.balance-progress-stage[data-compact='true'] {
  min-height: 0;
  height: 100%;
  padding: 0;
  border-radius: 0;
}

/* The surface's `inset: 0` resolves against the padding box, so zeroing the padding
   above is what hands the canvas all 298x240: the track widens, and the pole and the
   streak grow with it. `pan-y` rather than `none` because a full-bleed drag surface in
   a scrolling grid traps a phone on this card, and the disturbance only ever reads
   horizontal pointer travel — a vertical swipe was never an input here. */
.balance-progress-stage[data-compact='true'] .balance-progress-surface {
  touch-action: pan-y;
}

/* One overlay strip along the bottom instead of a column the mechanism has to share.
   The base rule's `pointer-events: none` is left alone, so a drag started on the
   eyebrow still lands on the pole. */
.balance-progress-stage[data-compact='true'] .balance-progress-content {
  position: absolute;
  inset: auto 0 0 0;
  padding: 0.625rem 0.75rem;
}

.balance-progress-stage[data-compact='true'] .balance-progress-eyebrow {
  margin: 0 0 0.375rem;
}

/* The eyebrow is the one line of text left. The stage name is already the highlighted
   button, the percent means nothing without the title beside it, and the buttons say
   plainly enough that they can be pressed. */
.balance-progress-stage[data-compact='true'] .balance-progress-head,
.balance-progress-stage[data-compact='true'] .balance-progress-sub,
.balance-progress-stage[data-compact='true'] .balance-progress-hint {
  display: none;
}

.balance-progress-stage[data-compact='true'] .balance-progress-steps {
  gap: 0.25rem;
}

/* Pressing a stage is the demo — the wrong-way first step — so the buttons stay, small
   enough that five of them cross 298px without reaching for the ellipsis. */
.balance-progress-stage[data-compact='true'] .balance-progress-step {
  padding: 0.25rem 0.1875rem;
  font-size: 0.625rem;
  letter-spacing: 0;
  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 }
}