Heat Grid

'use client';

import './heat-grid.css';

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

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

/**
 * A contribution calendar whose cells are a live temperature field.
 *
 * The glow under the cursor is the 2D heat equation dT/dt = alpha * lap(T) - k * T, integrated on the
 * cell lattice by explicit finite difference at a fixed step. Explicit FD is the honest cheap solver
 * for 182 cells, but it is only conditionally stable: with r = alpha * dt / dx^2 the discrete Fourier
 * factor is 1 + r * (2 cos kx + 2 cos ky - 4), which at the checkerboard mode kx = ky = pi is 1 - 8r.
 * The familiar 1D number r = 1/2 makes that -3, so every step multiplies alternating cells by minus
 * three and the grid tears into a flickering chequerboard inside half a second. R below is pinned to
 * 0.2, under the 2D ceiling of 1/4. Tweening each cell's opacity cannot stand in for this: a tween
 * never hands heat to the neighbour, and cell-to-cell transport is the entire picture.
 *
 * Boundaries are insulated (Neumann) by mirroring: the stencil reads a ghost cell equal to the edge
 * cell, so wall flux is exactly zero and interior fluxes cancel in pairs. Heat is conserved apart
 * from the one explicit sink, -k * T, radiating each cell back to its ambient — and ambient is the
 * recorded activity, which is why the grid reads as a plain, usable heatmap when left alone.
 */

const COLS = 26;
const ROWS = 7;
const CELLS = COLS * ROWS;

const STEP = 1 / 120;
const R = 0.2; // alpha * dt / dx^2, dx = 1 cell; 1/4 is the 2D explicit stability ceiling
const COOL = 3.4; // 1/s radiative pull back to ambient: a ~0.3 s decay, so the trail dies fast
const BRUSH = 6.2; // K/s injected under a moving pointer
const HOLD = 2.4; // multiplier while pressed, which is what makes a held source read as held
const SPREAD = 1.9; // squared brush radius, in cells
const KICK = 0.9; // impulse dropped by a keyboard step
const GAIN = 0.8; // temperature to ramp units
const WARM = 26; // setup pulse length in steps: 0.22 s, hot enough to see, short of saturation

const PAD = 18;
const HEAD = 78; // matches .heat-grid-content min-height; the calendar starts under the header
const MONTH_H = 15;
const LEGEND_H = 30;
const FOOT = 26;
const LABEL_W = 28;

// Six stops, flat so the lookup is a typed-array read. Ambient slate, then ember, then filament.
const STOPS = new Float64Array([
  22, 25, 32, 74, 44, 24, 138, 70, 22, 206, 112, 26, 244, 164, 74, 255, 226, 168,
]);
const SEGS = 5;

const ramp = (t: number): string => {
  const x = t > 0 ? (t < 1 ? t : 1) : 0; // the ternary order also turns a stray NaN into 0
  const f = x * SEGS;
  const s = Math.min(SEGS - 1, Math.floor(f));
  const k = f - s;
  const a = s * 3;
  const b = a + 3;
  const r = Math.round(STOPS[a] + (STOPS[b] - STOPS[a]) * k);
  const g = Math.round(STOPS[a + 1] + (STOPS[b + 1] - STOPS[a + 1]) * k);
  const l = Math.round(STOPS[a + 2] + (STOPS[b + 2] - STOPS[a + 2]) * k);
  return `rgb(${r}, ${g}, ${l})`;
};

const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
const WEEKDAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
const DAY_MS = 86400000;
const START = Date.UTC(2026, 2, 9); // a Monday, so row 0 is Monday for all 26 columns

// Sim index is row-major (r * COLS + c); the date runs down each week column, so day = c * 7 + r.
const dateOf = (i: number): Date =>
  new Date(START + ((i % COLS) * 7 + Math.floor(i / COLS)) * DAY_MS);

const mix = (n: number): number => {
  let x = Math.imul(n ^ 0x9e3779b9, 0x85ebca6b);
  x = Math.imul(x ^ (x >>> 13), 0xc2b2ae35);
  return ((x ^ (x >>> 16)) >>> 0) / 4294967296;
};

const COUNTS = new Int16Array(CELLS);
const AMBIENT = new Float64Array(CELLS);
let total = 0;
for (let i = 0; i < CELLS; i += 1) {
  const row = Math.floor(i / COLS);
  const q = mix((i % COLS) * 7 + row);
  const n = Math.floor(q * q * (row > 4 ? 6 : 19)) + (q > 0.87 ? 11 : 0);
  COUNTS[i] = n;
  AMBIENT[i] = Math.min(1, n / 14) * 0.62; // the data owns the lower ramp; heat owns the top
  total += n;
}
const TOTAL = total.toLocaleString('en-US');
const TODAY = 4 * COLS + (COLS - 1); // Friday of the newest week

interface State {
  clock: number;
  carry: number;
  u: Float64Array; // excess temperature over ambient, in ramp units
  next: Float64Array;
  src: Float64Array; // injection rate per cell, rebuilt every frame
  x0: number;
  y0: number;
  pitch: number;
  size: number;
  wasDown: boolean;
  snap: boolean;
}

const advance = (s: State): void => {
  const u = s.u;
  const n = s.next;
  for (let r = 0; r < ROWS; r += 1) {
    // The mirrored ghost cell: at a wall the offset collapses to 0, so the stencil reads this cell
    // in place of the missing neighbour and the wall flux is identically zero. Without the mirror the
    // four edges leak into nothing and the top row would read colder than the middle for no reason.
    const up = r > 0 ? -COLS : 0;
    const dn = r < ROWS - 1 ? COLS : 0;
    for (let c = 0; c < COLS; c += 1) {
      const i = r * COLS + c;
      const lf = c > 0 ? -1 : 0;
      const rt = c < COLS - 1 ? 1 : 0;
      const lap = u[i + lf] + u[i + rt] + u[i + up] + u[i + dn] - 4 * u[i];
      const v = u[i] + R * lap - STEP * COOL * u[i] + STEP * s.src[i];
      // Every source is positive, so u >= 0 holds analytically; the clamp is only here so a single
      // bad float can never take up permanent residence in the field.
      n[i] = v > 0 ? Math.min(v, 4) : 0;
    }
  }
  s.u = n;
  s.next = u;
};

const paint = (s: State, cx: number, cy: number, rate: number): void => {
  const c1 = Math.max(0, Math.ceil(cx - 2));
  const c2 = Math.min(COLS - 1, Math.floor(cx + 2));
  const r1 = Math.max(0, Math.ceil(cy - 2));
  const r2 = Math.min(ROWS - 1, Math.floor(cy + 2));
  for (let r = r1; r <= r2; r += 1) {
    const dy = r - cy;
    for (let c = c1; c <= c2; c += 1) {
      const dx = c - cx;
      s.src[r * COLS + c] += rate * Math.exp(-(dx * dx + dy * dy) / SPREAD);
    }
  }
};

/** A held source at one cell for `steps` steps, then released. Shared by setup and reduced motion. */
const pulse = (s: State, i: number, steps: number): void => {
  paint(s, i % COLS, Math.floor(i / COLS), BRUSH * HOLD);
  for (let k = 0; k < steps; k += 1) {
    advance(s);
  }
  s.src.fill(0);
};

const MONO = 'ui-monospace, SFMono-Regular, Menlo, monospace';
const MUTED = '#6d7382';

const render = (
  ctx: CanvasRenderingContext2D,
  width: number,
  height: number,
  s: State,
  sel: number,
): void => {
  ctx.fillStyle = '#0b0d12';
  ctx.fillRect(0, 0, width, height);

  const { x0, y0, pitch, size } = s;

  // Squares, never ctx.roundRect: its typing moves between DOM library versions.
  for (let i = 0; i < CELLS; i += 1) {
    ctx.fillStyle = ramp(AMBIENT[i] + s.u[i] * GAIN);
    ctx.fillRect(x0 + (i % COLS) * pitch, y0 + Math.floor(i / COLS) * pitch, size, size);
  }

  ctx.lineWidth = 1.5;
  ctx.strokeStyle = 'rgba(236, 238, 243, 0.86)';
  const sx = x0 + (sel % COLS) * pitch;
  const sy = y0 + Math.floor(sel / COLS) * pitch;
  ctx.strokeRect(sx - 1.5, sy - 1.5, size + 3, size + 3);

  ctx.font = `500 10px ${MONO}`;
  ctx.fillStyle = MUTED;
  ctx.textBaseline = 'middle';
  ctx.textAlign = 'right';
  for (let r = 0; r < ROWS; r += 2) {
    ctx.fillText(WEEKDAYS[r], x0 - 8, y0 + r * pitch + size / 2);
  }

  ctx.textAlign = 'left';
  let seen = dateOf(0).getUTCMonth();
  let mark = -9;
  for (let c = 1; c < COLS; c += 1) {
    const m = dateOf(c).getUTCMonth();
    if (m !== seen) {
      seen = m;
      if (c - mark >= 3) {
        ctx.fillText(MONTHS[m], x0 + c * pitch, y0 - MONTH_H / 2);
        mark = c;
      }
    }
  }

  // The legend is the cells' own ramp function sampled across its whole range, so a hot cell can be
  // read off it instead of being an unexplained bright square.
  const ly = y0 + ROWS * pitch + LEGEND_H / 2;
  const sw = Math.max(7, Math.min(12, size * 0.55));
  ctx.font = `500 9px ${MONO}`;
  ctx.fillText('AMBIENT', x0, ly);
  let lx = x0 + ctx.measureText('AMBIENT').width + 9;
  for (let k = 0; k < 6; k += 1) {
    ctx.fillStyle = ramp(k / SEGS);
    ctx.fillRect(lx, ly - sw / 2, sw, sw);
    lx += sw + 3;
  }
  ctx.fillStyle = MUTED;
  ctx.fillText('HOT', lx + 5, ly);
};

/** `compact` is the 298x240 catalogue card: the same field, solved by the same explicit
 *  step, with the header cut to one line along the bottom so the calendar is the whole
 *  subject. Presentation only — see `heat-grid.css`. */
export type HeatGridProps = { compact?: boolean };

export function HeatGrid({ compact = false }: HeatGridProps) {
  const reduced = useReducedMotion();
  const [sel, setSel] = useState(TODAY);
  const kick = useRef<number | null>(null);

  const setup = ({ width, height }: SceneSetupContext): State => {
    const gw = Math.max(1, width - PAD * 2 - LABEL_W);
    const gh = Math.max(1, height - HEAD - MONTH_H - LEGEND_H - FOOT);
    const pitch = Math.max(4, Math.min(gw / COLS, gh / ROWS)); // square cells, never a zero divisor
    const s: State = {
      clock: 0,
      carry: 0,
      u: new Float64Array(CELLS),
      next: new Float64Array(CELLS),
      src: new Float64Array(CELLS),
      x0: PAD + LABEL_W + Math.max(0, (gw - pitch * COLS) / 2),
      y0: HEAD + MONTH_H + Math.max(0, (gh - pitch * ROWS) / 2),
      pitch,
      size: pitch - Math.max(1, Math.min(4, pitch * 0.17)),
      wasDown: false,
      snap: reduced,
    };
    // Warm the real solver before the first paint. A reader scrolling a gallery gets a pulse already
    // spreading and dying on the newest week, rather than a still grid waiting to be touched.
    pulse(s, sel, WARM);
    return s;
  };

  const draw = ({ context, width, height, state, pointer }: SceneDrawContext<State>) => {
    // Refreshed every frame, not just in setup: the preference can flip without a resize.
    state.snap = reduced;
    const now = performance.now() / 1000;
    const dt = state.clock === 0 ? 0 : Math.min(0.05, now - state.clock);
    state.clock = now;

    const cx = (pointer.x - state.x0 - state.size / 2) / state.pitch;
    const cy = (pointer.y - state.y0 - state.size / 2) / state.pitch;
    const over = pointer.inside && cx > -1.5 && cx < COLS + 0.5 && cy > -1.5 && cy < ROWS + 0.5;
    const hit = kick.current;
    kick.current = null;

    if (state.snap) {
      // No loop to spread anything over time, so a keyboard step resolves at once: clear the field
      // and run the same held source for the same number of steps setup used.
      if (hit !== null) {
        state.u.fill(0);
        pulse(state, hit, WARM);
      }
    } else {
      state.src.fill(0);
      if (over) {
        paint(state, cx, cy, pointer.down ? BRUSH * HOLD : BRUSH);
      }
      if (hit !== null) {
        state.u[hit] += KICK; // a keypress is a discrete impulse, not a rate held over a frame
      }
      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; // a backgrounded tab must not come back owing 400 steps
      }
    }

    if (pointer.down && !state.wasDown && over) {
      const c = Math.min(COLS - 1, Math.max(0, Math.round(cx)));
      const r = Math.min(ROWS - 1, Math.max(0, Math.round(cy)));
      if (r * COLS + c !== sel) {
        setSel(r * COLS + c);
      }
    }
    state.wasDown = pointer.down;

    render(context, width, height, state, sel);
  };

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

  const step = (dc: number, dr: number): void => {
    const c = Math.min(COLS - 1, Math.max(0, (sel % COLS) + dc));
    const r = Math.min(ROWS - 1, Math.max(0, Math.floor(sel / COLS) + dr));
    kick.current = r * COLS + c;
    setSel(r * COLS + c);
    requestRender();
  };

  const onKey = (event: KeyboardEvent<HTMLButtonElement>): void => {
    const dc = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
    const dr = event.key === 'ArrowDown' ? 1 : event.key === 'ArrowUp' ? -1 : 0;
    if (dc === 0 && dr === 0) {
      return;
    }
    event.preventDefault();
    step(dc, dr);
  };

  const day = dateOf(sel);
  const count = COUNTS[sel];
  const stamp = `${WEEKDAYS[Math.floor(sel / COLS)]} ${day.getUTCDate()} ${MONTHS[day.getUTCMonth()]}`;

  return (
    <div className="heat-grid-stage" data-compact={compact ? 'true' : undefined}>
      <div ref={stageRef} className="heat-grid-surface">
        <canvas ref={canvasRef} aria-hidden="true" />
      </div>
      <div className="heat-grid-content">
        <div className="heat-grid-titles">
          <h3 className="heat-grid-title">Deploy activity</h3>
          <p className="heat-grid-meta">{TOTAL} deploys in 26 weeks, diffusing at 24 cells²/s</p>
        </div>
        {/* Still clickable in a card, and clicking it still drops heat on the probed
            day, but out of the tab order: the card frame is aria-hidden, and a focusable
            node inside one is a trap with no label. */}
        <button
          type="button"
          className="heat-grid-probe"
          tabIndex={compact ? -1 : undefined}
          aria-keyshortcuts="ArrowUp ArrowDown ArrowLeft ArrowRight"
          aria-label={`Heat ${stamp}, ${count} deploys. Arrow keys move the probe.`}
          onClick={() => step(0, 0)}
          onKeyDown={onKey}
        >
          <span className="heat-grid-probe-day">{stamp}</span>
          <span className="heat-grid-probe-count">
            {count} {count === 1 ? 'deploy' : 'deploys'}
          </span>
        </button>
      </div>
      <p className="heat-grid-hint">drag to warm, hold to pin</p>
    </div>
  );
}

export default HeatGrid;

.heat-grid-stage {
  position: relative;
  width: 100%;
  min-height: 20rem;
  overflow: hidden;
  border-radius: 0.875rem;
  background: #0b0d12;
  color: #eceef3;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
}

/* No border on the measured host: `inset: 0` resolves against the padding box, so a border would
   slide the canvas origin a pixel off the grid that the pointer-to-cell maths assumes. An inset
   shadow draws the same hairline without moving anything. */
.heat-grid-surface {
  position: absolute;
  inset: 0;
  border-radius: inherit;
  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.055);
  touch-action: none;
}

.heat-grid-surface canvas {
  display: block;
  width: 100%;
  height: 100%;
}

/* Transparent to the pointer so a drag started anywhere over the header still warms cells; the
   probe button takes events back. Height is in px, not rem, because the canvas reserves exactly
   78 device-independent pixels for this band before it lays out the calendar. */
.heat-grid-content {
  position: relative;
  display: flex;
  min-height: 78px;
  align-items: flex-start;
  justify-content: space-between;
  gap: 1rem;
  padding: 1.0625rem 1.125rem 0;
  pointer-events: none;
}

.heat-grid-titles {
  min-width: 0;
}

.heat-grid-title {
  margin: 0;
  font-size: 0.9375rem;
  font-weight: 600;
  letter-spacing: -0.01em;
}

.heat-grid-meta {
  margin: 0.3125rem 0 0;
  overflow: hidden;
  color: #99a0ad;
  font-size: 0.75rem;
  font-variant-numeric: tabular-nums;
  white-space: nowrap;
  text-overflow: ellipsis;
}

.heat-grid-probe {
  display: grid;
  flex: none;
  gap: 0.125rem;
  margin: 0;
  padding: 0.4375rem 0.6875rem;
  appearance: none;
  border: 0;
  border-radius: 0.5rem;
  background: rgba(255, 255, 255, 0.05);
  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.09);
  color: #eceef3;
  font: inherit;
  text-align: right;
  cursor: pointer;
  pointer-events: auto;
  transition:
    background-color 150ms ease,
    box-shadow 150ms ease;
}

.heat-grid-probe:hover {
  background: rgba(244, 164, 74, 0.14);
  box-shadow: inset 0 0 0 1px rgba(244, 164, 74, 0.42);
}

.heat-grid-probe:focus-visible {
  outline: 2px solid rgba(244, 164, 74, 0.8);
  outline-offset: 2px;
}

.heat-grid-probe-day {
  font-size: 0.75rem;
  font-weight: 600;
  letter-spacing: -0.005em;
}

.heat-grid-probe-count {
  color: #f4a44a;
  font-size: 0.6875rem;
  font-variant-numeric: tabular-nums;
}

.heat-grid-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;
  pointer-events: none;
  color: rgba(236, 238, 243, 0.3);
}

/*
 * The animation frame loop never starts, so what is switched off is the diffusion in time: no warm
 * trail following the cursor, no glow decaying after you leave. The canvas still paints the recorded
 * grid and one already-spread pulse on the selected day, produced by running the same explicit
 * solver to that point inside setup — a still of the physics rather than a different picture.
 */
@media (prefers-reduced-motion: reduce) {
  .heat-grid-probe {
    transition: none;
  }
}

/*
 * The card variant: the 298x240 catalogue frame, at that real size and never scaled. The
 * calendar already lays itself out against the live canvas box, so nothing here resizes it
 * — all this does is crop the band the header used to occupy and cut the header itself down
 * to one strip along the bottom, which is the only part of the box the canvas keeps empty.
 */
.heat-grid-stage[data-compact='true'] {
  min-height: 0;
  height: 100%;
  /* The card frame rounds and clips already. */
  border-radius: 0;
}

/*
 * `HEAD` in the tsx reserves the top 78px of the canvas for the header that used to sit
 * there, and in a card the header no longer does. Lifting the measured host by exactly that
 * band crops it out of view, so the calendar centres in what is left instead of floating in
 * the lower half under 78px of nothing: at 298 wide the pitch is capped by the width, which
 * pins the grid at 234x63 however tall the host is, so the lift is the whole of the fix.
 * In pixels, because that constant is in pixels.
 *
 * `pan-y` because a full-bleed drag surface that claims every touch traps the page inside a
 * scrolling grid. The vertical gesture goes back to the document; a horizontal drag still
 * warms cells, which is the gesture this mechanism is about.
 */
.heat-grid-stage[data-compact='true'] .heat-grid-surface {
  inset: -78px 0 0 0;
  touch-action: pan-y;
}

/*
 * The strip lands in the gap under the legend: `FOOT` holds the legend 26px clear of the
 * canvas floor and the lift above leaves it around 150px down, so the two never meet.
 * `pointer-events: none` is inherited from the rule above and left alone, so a drag started
 * over the strip still warms cells; the probe goes on taking its own clicks back.
 */
.heat-grid-stage[data-compact='true'] .heat-grid-content {
  position: absolute;
  inset: auto 0 0 0;
  min-height: 0;
  align-items: center;
  gap: 0.5rem;
  padding: 0.75rem;
}

/* The one line of text that stays, at a fixed rem — never `vw`, which would read the
   viewport rather than the 298px card. Ellipsised rather than wrapped, so it cannot
   quietly become two lines next to a long date. */
.heat-grid-stage[data-compact='true'] .heat-grid-title {
  overflow: hidden;
  font-size: 0.8125rem;
  white-space: nowrap;
  text-overflow: ellipsis;
}

/* The paragraph would be the second line and the hint the third; the card's own title
   already says what this is, and the legend on the canvas explains the colour. */
.heat-grid-stage[data-compact='true'] .heat-grid-meta,
.heat-grid-stage[data-compact='true'] .heat-grid-hint {
  display: none;
}

/* Day and count side by side instead of stacked, so the probe is one line ~20px tall and
   reads as part of the strip rather than a block sitting on it. It stays because a click
   on it drops heat on the probed day, which is worth having in a card. */
.heat-grid-stage[data-compact='true'] .heat-grid-probe {
  grid-auto-flow: column;
  align-items: baseline;
  gap: 0.375rem;
  padding: 0.1875rem 0.5rem;
  border-radius: 0.375rem;
}

.heat-grid-stage[data-compact='true'] .heat-grid-probe-day {
  font-size: 0.6875rem;
}

.heat-grid-stage[data-compact='true'] .heat-grid-probe-count {
  font-size: 0.625rem;
}

"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 }
}