Shadow Caster

'use client';

import './shadow-caster.css';

import { useCallback, useEffect, useRef } from 'react';

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

/**
 * Soft shadows cast by the real cards in the real layout, from a light that has a
 * size.
 *
 * A point light gives a hard edge. Every real shadow has a penumbra because the
 * source is an area, and every point in the penumbra can see *part* of that area —
 * so the darkness there is the fraction of the source the occluder hides, and the
 * band widens the further the shadow is thrown. That is the whole effect, and the
 * only way to get it is to have an area to sample. This samples the disc at
 * fourteen points on a Vogel spiral, builds the exact shadow volume of every card
 * from each of them, and accumulates the occluded fraction.
 *
 * The accumulation is additive, in a mask, and then subtracted from the light in one
 * pass. Painting fourteen semi-transparent shadows on top of each other instead
 * would compound as (1 − 1/n)ⁿ, which leaves a third of the light standing in the
 * middle of a full umbra; darkness has to be linear in the occluded fraction, and
 * the only way to get that out of a canvas is to add the occlusion up somewhere
 * else first.
 *
 * The occluders are the cards. Their boxes come from `getBoundingClientRect`, so
 * the shadows follow whatever the grid does at whatever breakpoint, and the copy
 * inside them is ordinary selectable text.
 */

/** Points sampled on the source. Fourteen is where the penumbra stops banding. */
const SAMPLES = 14;
/** Radius of the light, in pixels. This single number is the softness. */
const LIGHT_R = 26;
/** The golden angle. Successive samples land in each other's gaps, at every count. */
const GOLDEN = Math.PI * (3 - Math.sqrt(5));
/**
 * Distance at which the light has fallen to a quarter, from 1/(1 + r/R)². Real
 * inverse-square, softened at the origin so standing on the source is finite.
 */
const REFERENCE = 190;
/** Brightest the floor is allowed to get. Full white would clip the card borders. */
const PEAK = 0.85;
/** Stops used to sample the falloff curve into the gradient. */
const STOPS = 9;
/** How fast the light follows the pointer, per second. */
const LAG = 9;
/** Where the light rests with the pointer away, as a fraction of the height. */
const PARK = 0.13;
/**
 * Shadow volumes are extruded to five diagonals rather than to a guessed edge. The
 * far side of the volume is a chord across the arc it should be, and at five
 * diagonals that chord is outside the stage for anything up to a card subtending
 * 168° — which needs the light inside the card, where there is no shadow to draw.
 */
const REACH = 5;

interface Box {
  readonly left: number;
  readonly top: number;
  readonly width: number;
  readonly height: number;
}

interface ShadowState {
  /** Sample offsets on the source disc, as x, y pairs. Fixed for the lifetime. */
  readonly disc: Float64Array;
  /** The occluders, republished by the measure pass rather than copied into here. */
  readonly boxes: { current: readonly Box[] };
  /**
   * Where the occlusion is added up. A separate surface because canvas has no
   * subtractive blend: the mask is built with additive alpha, then taken out of the
   * light with one `destination-out`, which is a subtraction and is linear.
   */
  readonly mask: HTMLCanvasElement;
  readonly maskContext: CanvasRenderingContext2D;
  lightX: number;
  lightY: number;
  clock: number;
}

/*
 * Corner scratch, at module scope. `volume` runs once per card per sample — fifty-six
 * times a frame at four cards — and allocating a pair of arrays each time would hand
 * the collector a few thousand of them a second for no reason.
 */
const cornerX = new Float64Array(4);
const cornerY = new Float64Array(4);

/**
 * Add one card's shadow volume, seen from one point, to the current path.
 *
 * The volume is bounded by the two rays that graze the card — its silhouette from
 * that point. A corner is on the silhouette when every other corner lies on one
 * side of the ray to it, which is four cross products, and the two that qualify are
 * the two extremes. Ordering them so that `a` is the one with everything to its
 * left makes every quad wind the same way, which is what lets one path hold all of
 * them: a nonzero fill of same-wound polygons is their union, so two cards' umbras
 * overlapping does not darken twice.
 */
function volume(path: CanvasRenderingContext2D, box: Box, sx: number, sy: number, far: number) {
  const right = box.left + box.width;
  const bottom = box.top + box.height;
  cornerX[0] = box.left;
  cornerY[0] = box.top;
  cornerX[1] = right;
  cornerY[1] = box.top;
  cornerX[2] = right;
  cornerY[2] = bottom;
  cornerX[3] = box.left;
  cornerY[3] = bottom;

  let a = -1;
  let b = -1;
  for (let i = 0; i < 4; i++) {
    const dx = cornerX[i] - sx;
    const dy = cornerY[i] - sy;
    let ccw = false;
    let cw = false;
    for (let j = 0; j < 4; j++) {
      if (j === i) continue;
      const cross = dx * (cornerY[j] - sy) - dy * (cornerX[j] - sx);
      if (cross > 1e-9) cw = true;
      else if (cross < -1e-9) ccw = true;
    }
    if (!ccw) a = i;
    else if (!cw) b = i;
  }

  // No corner qualifies when the point is inside the card. A light inside an
  // occluder casts no shadow anything outside it could be standing in.
  if (a < 0 || b < 0) return;

  const ax = cornerX[a];
  const ay = cornerY[a];
  const bx = cornerX[b];
  const by = cornerY[b];
  const aScale = far / (Math.hypot(ax - sx, ay - sy) || 1e-6);
  const bScale = far / (Math.hypot(bx - sx, by - sy) || 1e-6);

  path.moveTo(ax, ay);
  path.lineTo(bx, by);
  path.lineTo(sx + (bx - sx) * bScale, sy + (by - sy) * bScale);
  path.lineTo(sx + (ax - sx) * aScale, sy + (ay - sy) * aScale);
  path.closePath();
}

function build(
  { width, height, dpr }: SceneSetupContext,
  boxes: { current: readonly Box[] },
): ShadowState {
  /*
   * The Vogel disc: radius as √(i/n) so the samples are spread by equal area rather
   * than equal radius, turned by the golden angle so each one lands in the gap the
   * others left. It is even at every count, which matters because fourteen is chosen
   * by eye and any other number has to look the same.
   */
  const disc = new Float64Array(SAMPLES * 2);
  for (let i = 0; i < SAMPLES; i++) {
    const radius = LIGHT_R * Math.sqrt((i + 0.5) / SAMPLES);
    const angle = i * GOLDEN;
    disc[i * 2] = Math.cos(angle) * radius;
    disc[i * 2 + 1] = Math.sin(angle) * radius;
  }

  const mask = document.createElement('canvas');
  mask.width = Math.max(1, Math.round(width * dpr));
  mask.height = Math.max(1, Math.round(height * dpr));
  const maskContext = mask.getContext('2d')!;
  // Same transform as the stage, so both are drawn in CSS pixels and the mask lines
  // up with the light without a scale factor anywhere in the drawing code.
  maskContext.setTransform(dpr, 0, 0, dpr, 0, 0);

  return {
    disc,
    boxes,
    mask,
    maskContext,
    lightX: width * 0.5,
    lightY: height * PARK,
    clock: 0,
  };
}

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

  /*
   * Everything geometric is derived from the live size rather than kept on the state,
   * so a resize needs nothing kept in step: the extrusion length and the falloff
   * range are recomputed per frame, which is two square roots.
   */
  const span = Math.hypot(width, height);
  const far = span * REACH;

  /*
   * The light follows the pointer through a first-order lag, and returns to its park
   * when the pointer leaves rather than staying where the cursor last was. The
   * coefficient is 1 − e^(−k·dt) rather than k·dt, so the approach is identical at
   * any frame rate instead of merely close at sixty.
   */
  const wantX = pointer.inside ? pointer.x : width * 0.5;
  const wantY = pointer.inside ? pointer.y : height * PARK;
  const follow = 1 - Math.exp(-elapsed * LAG);
  state.lightX += (wantX - state.lightX) * follow;
  state.lightY += (wantY - state.lightY) * follow;

  const lx = state.lightX;
  const ly = state.lightY;
  const boxes = state.boxes.current;

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

  /*
   * The light on the floor, at full strength. One gradient for the whole frame: the
   * samples all sit inside a twenty-six pixel disc, so they share their distance to
   * any point on the stage to well under a percent and only their *geometry*
   * differs. The penumbra is the exact thing being computed here; the 1/r² weight is
   * the thing being shared.
   */
  const glow = context.createRadialGradient(lx, ly, 0, lx, ly, span);
  for (let s = 0; s <= STOPS; s++) {
    const at = s / STOPS;
    const fall = 1 + (at * span) / REFERENCE;
    glow.addColorStop(at, `rgba(255,246,232,${(PEAK / (fall * fall)).toFixed(4)})`);
  }
  context.fillStyle = glow;
  context.fillRect(0, 0, width, height);

  if (boxes.length) {
    const mask = state.maskContext;
    // Setting either dimension resets the transform, so the scale goes back on.
    const wide = Math.max(1, Math.round(width * dpr));
    const tall = Math.max(1, Math.round(height * dpr));
    if (state.mask.width !== wide || state.mask.height !== tall) {
      state.mask.width = wide;
      state.mask.height = tall;
      mask.setTransform(dpr, 0, 0, dpr, 0, 0);
    }

    /*
     * The occluded fraction, added up. `lighter` adds alpha, so fourteen fills at
     * 1/14 reach exactly 1 where all fourteen samples are hidden and exactly k/14
     * where k are — which is the definition of the penumbra, not an approximation of
     * one. Each sample is a single path holding every card's volume, filled once, so
     * the nonzero winding unions them and no card's umbra is counted twice.
     */
    mask.globalCompositeOperation = 'source-over';
    mask.clearRect(0, 0, width, height);
    mask.globalCompositeOperation = 'lighter';
    mask.fillStyle = `rgba(0,0,0,${(1 / SAMPLES).toFixed(5)})`;
    for (let i = 0; i < SAMPLES; i++) {
      const sx = lx + state.disc[i * 2];
      const sy = ly + state.disc[i * 2 + 1];
      mask.beginPath();
      for (const box of boxes) volume(mask, box, sx, sy, far);
      mask.fill();
    }

    // Subtract it. `destination-out` scales the light by 1 − occluded, and the dark
    // page behind the canvas is what shows through: the ambient term, unlit.
    context.globalCompositeOperation = 'destination-out';
    context.drawImage(state.mask, 0, 0, width, height);
    context.globalCompositeOperation = 'source-over';
  }

  // The source itself, which nothing occludes. Drawn after the subtraction so the
  // lamp is not standing in its own shadow when it passes behind a card.
  context.globalCompositeOperation = 'lighter';
  const size = LIGHT_R * 2.8;
  const core = context.createRadialGradient(lx, ly, 0, lx, ly, size);
  core.addColorStop(0, 'rgba(255,248,235,0.85)');
  core.addColorStop(0.3, 'rgba(255,232,192,0.22)');
  core.addColorStop(1, 'rgba(255,232,192,0)');
  context.fillStyle = core;
  context.fillRect(lx - size, ly - size, size * 2, size * 2);
  context.globalCompositeOperation = 'source-over';
}

const FEATURES = [
  {
    title: 'Edge functions',
    body: 'Deployed to thirty-one regions. Cold start under a millisecond, because there is no cold.',
  },
  {
    title: 'Instant rollback',
    body: 'Every deploy keeps its own immutable URL. Reverting is choosing an older one.',
  },
  {
    title: 'Typed queries',
    body: 'The schema generates the client. A column you renamed fails at compile time, not at 3am.',
  },
  {
    title: 'Usage that adds up',
    body: 'Metered per request and per gigabyte, invoiced to the cent, with the maths shown.',
  },
];

export type ShadowCasterProps = {
  /**
   * The 298x240 catalogue-card variant: the copy dropped, the row of occluders and the
   * light given the whole box. Presentation only, and all of it CSS. Nothing this
   * component renders is focusable — the stage is a canvas and four articles of copy —
   * so there is no control in here that needs `tabIndex={-1}` under the card's
   * `aria-hidden`.
   */
  compact?: boolean;
};

/**
 * The canvas is the floor and the cards stand on it.
 *
 * The stage is first in the DOM and absolutely filled, so it takes every pointer
 * event; the grid is a later sibling and paints over it. The cards are
 * `pointer-events: none` — they are copy, not controls — which is what lets the
 * light keep following the pointer while it is over one of them.
 */
export function ShadowCaster({ compact = false }: ShadowCasterProps) {
  const frame = useRef<HTMLDivElement | null>(null);
  const grid = useRef<HTMLDivElement | null>(null);
  /*
   * The occluders live in a ref the scene holds rather than in scene state, because
   * the measure pass and the draw loop have different lifetimes: re-measuring must
   * not mean rebuilding the light.
   */
  const boxes = useRef<readonly Box[]>([]);

  const { stageRef, canvasRef, requestRender } = useCanvasScene<ShadowState>({
    setup: (scene) => build(scene, boxes),
    draw: paint,
  });

  /*
   * The cards' own boxes, relative to the stage. Read from the DOM rather than
   * computed from the grid definition, so the shadows are correct at any breakpoint,
   * at any font size, and after any reflow — including the one where the copy wraps
   * to a third line and the card grows. The stage carries no border, so its bounding
   * rect and the canvas's own origin are the same point.
   */
  const measure = useCallback(() => {
    const host = frame.current;
    const list = grid.current;
    if (!host || !list) return;
    const origin = host.getBoundingClientRect();
    boxes.current = Array.from(list.children).map((child) => {
      const rect = child.getBoundingClientRect();
      return {
        left: rect.left - origin.left,
        top: rect.top - origin.top,
        width: rect.width,
        height: rect.height,
      };
    });
    requestRender();
  }, [requestRender]);

  useEffect(() => {
    measure();

    // Watching each card as well as the stage: a card can change height on its own
    // when its text rewraps, at a stage width that never changed.
    const observer = new ResizeObserver(measure);
    if (frame.current) observer.observe(frame.current);
    if (grid.current) {
      for (const child of Array.from(grid.current.children)) observer.observe(child);
    }
    return () => observer.disconnect();
  }, [measure]);

  return (
    <div
      ref={frame}
      className="shadow-caster-stage"
      data-compact={compact ? 'true' : undefined}
    >
      <div ref={stageRef} className="shadow-caster-floor" aria-hidden="true">
        <canvas ref={canvasRef} />
      </div>

      <div className="shadow-caster-face">
        <p className="shadow-caster-eyebrow">Penumbra</p>
        <h2>Everything the platform does, and nothing it does not.</h2>

        <div ref={grid} className="shadow-caster-grid">
          {FEATURES.map((feature) => (
            <article key={feature.title} className="shadow-caster-card">
              <h3>{feature.title}</h3>
              <p>{feature.body}</p>
            </article>
          ))}
        </div>
      </div>

      <p className="shadow-caster-hint">Move the light</p>
    </div>
  );
}

export default ShadowCaster;

/*
 * No `border` on the stage, deliberately: the canvas is `inset: 0`, which positions
 * it against the padding box, so a border would offset the canvas from the box the
 * card rects are measured against and every shadow would sit a pixel off its card.
 * The hairline is an inset shadow instead, which takes no space.
 */
.shadow-caster-stage {
  position: relative;
  width: 100%;
  min-height: 30rem;
  overflow: hidden;
  border-radius: 0.75rem;
  background: #090b10;
  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.06);
  color: #f4efe6;
}

.shadow-caster-floor {
  position: absolute;
  inset: 0;
  touch-action: none;
}

.shadow-caster-floor canvas {
  display: block;
  width: 100%;
  height: 100%;
}

/* Transparent to the pointer all the way down: the cards are copy, not controls, and
   the light has to keep following the pointer while it passes over one. */
.shadow-caster-face {
  position: relative;
  padding: 2.75rem 2.5rem 3rem;
  pointer-events: none;
}

.shadow-caster-eyebrow {
  margin: 0 0 0.875rem;
  font: 500 0.6875rem/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.16em;
  text-transform: uppercase;
  color: rgba(255, 226, 178, 0.7);
}

.shadow-caster-face h2 {
  margin: 0 0 2.25rem;
  max-width: 30rem;
  font-size: clamp(1.5rem, 2.8vw, 2.125rem);
  font-weight: 500;
  line-height: 1.15;
  letter-spacing: -0.02em;
  text-wrap: balance;
  color: rgba(255, 250, 242, 0.9);
}

.shadow-caster-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
  gap: 1.125rem;
  max-width: 44rem;
}

/*
 * The card is the occluder. Opaque enough to read as a solid object standing off the
 * floor — a translucent one would show the light passing through the thing casting
 * the shadow, which is the one contradiction the effect cannot survive.
 */
.shadow-caster-card {
  padding: 1.125rem 1.25rem 1.25rem;
  border-radius: 0.625rem;
  background: linear-gradient(170deg, #1b1f28 0%, #14171e 100%);
  box-shadow: inset 0 1px 0 rgba(255, 245, 226, 0.08);
}

.shadow-caster-card h3 {
  margin: 0 0 0.4375rem;
  font-size: 0.9375rem;
  font-weight: 500;
  letter-spacing: -0.01em;
  color: #f7f2e8;
}

.shadow-caster-card p {
  margin: 0;
  font-size: 0.8125rem;
  line-height: 1.55;
  color: rgba(244, 239, 230, 0.52);
}

.shadow-caster-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(244, 239, 230, 0.26);
  pointer-events: none;
}

/*
 * Nothing to switch off here. With the loop stopped the light stays parked and the
 * frame that gets painted is the full fourteen-sample solution — the penumbrae are
 * present and correct, they simply do not move. That is the whole of the effect that
 * is not motion, and it is the part worth keeping.
 */
@media (prefers-reduced-motion: reduce) {
  .shadow-caster-floor {
    cursor: default;
  }
}

/*
 * The 298x240 catalogue card. The copy comes off and the mechanism takes the whole box:
 * the light parks 31px down at the top centre, the four occluders sit in one row across
 * the middle, and the bottom 90px is open floor for the penumbrae to fan across. No
 * `vw` anywhere below — the card is 298px wide and the viewport is 1340.
 */
.shadow-caster-stage[data-compact='true'] {
  min-height: 0;
  height: 100%;
  /* The card frame rounds and clips already. */
  border-radius: 0;
  /* And draws its own border: a square hairline inside a rounded clip loses its corners. */
  box-shadow: none;
}

/*
 * `pan-y`, not `none`. The floor is the full-bleed pointer surface, and one that eats
 * vertical touches traps the page in a scrolling grid of cards — the worse failure. The
 * light follows the pointer's position rather than a gesture axis, so a horizontal drag
 * still walks it the full width of the box and the shadows swing with it.
 */
.shadow-caster-stage[data-compact='true'] .shadow-caster-floor {
  touch-action: pan-y;
}

/*
 * The occluders are the mechanism here — there is no penumbra without something to cast
 * one — so the text layer is not moved off them, it is emptied and they stay. The
 * padding puts the row 110px down, which is 79px below the parked light: far enough that
 * each shadow starts crisp under its own card, close enough that the fan still has 90px
 * of floor to soften over. Much nearer and the whole floor is umbra; much further and
 * the shadows have nowhere to go.
 */
.shadow-caster-stage[data-compact='true'] .shadow-caster-face {
  padding: 6.875rem 0.875rem 0;
}

/* Four across at this width, explicitly: `auto-fit` with a 15rem minimum resolves to one
   270px column here, and four rows do not fit in 240px. */
.shadow-caster-stage[data-compact='true'] .shadow-caster-grid {
  grid-template-columns: repeat(4, 1fr);
  gap: 0.625rem;
  max-width: none;
}

/*
 * 60x40 tiles. An explicit height because the copy inside them is gone and there is
 * nothing left to give them one, and `padding: 0` so 40px is 40px under either
 * `box-sizing`. The radius comes down with the box for a reason beyond taste: the shadow
 * volume is built from the element's bounding rect, so a corner rounded much more than
 * this is a corner that visibly disagrees with its own shadow.
 */
.shadow-caster-stage[data-compact='true'] .shadow-caster-card {
  height: 2.5rem;
  padding: 0;
  border-radius: 0.375rem;
}

/* The heading is a `clamp()` with a `vw` term, which reads the viewport and not this box.
   The card titles would be four more lines of type at five pixels, and the bodies are the
   paragraph. What this card is showing is the light, and the card's own title link
   underneath already says which item it belongs to. */
.shadow-caster-stage[data-compact='true'] .shadow-caster-eyebrow,
.shadow-caster-stage[data-compact='true'] .shadow-caster-face h2,
.shadow-caster-stage[data-compact='true'] .shadow-caster-card h3,
.shadow-caster-stage[data-compact='true'] .shadow-caster-card p {
  display: none;
}

/*
 * The one line that stays, on the bottom edge and well clear of the tiles, which end at
 * 150px. It is the hint and not the eyebrow because this mechanism holds perfectly still
 * until a pointer arrives — the light parks and stays parked — so "move the light" is
 * what tells a visitor the card is not a photograph. Still at its own fixed 0.6875rem,
 * and still deaf to the pointer, so a drag across it takes hold of the floor underneath.
 */
.shadow-caster-stage[data-compact='true'] .shadow-caster-hint {
  inset: auto 0 0 0;
  padding: 0 0.75rem 0.75rem;
  text-align: right;
}

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