Morphogen Wordmark

'use client';

import './morphogen-wordmark.css';

import { useEffect, useRef } from 'react';

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

/**
 * A product hero whose ornament is grown, not drawn: the wordmark is nucleated into a
 * Gray-Scott reaction-diffusion field and the pattern spreads out of the letters.
 *
 *   du/dt = Du*lap(u) - u*v^2 + F*(1 - u)
 *   dv/dt = Dv*lap(v) + u*v^2 - (F + k)*v
 *
 * Integrated explicitly on a five-point Laplacian at unit grid spacing, which is stable
 * while TAU*4*DU < 1 - here 0.576, comfortably inside it. The easy version of this
 * picture is a blurred PNG of the letters with an opacity keyframe, and it cannot do the
 * one thing that matters: the front is autocatalytic, so v eats the u it finds outside
 * the glyphs and keeps going, splitting and merging in a way no curve encodes. Delete the
 * solver and the letters stop growing anything.
 *
 * F 0.037 / k 0.060 is the labyrinth window: stripes one wavelength wide that advance
 * into fresh u and braid around each other. Raise k to ~0.065 and the fronts pin into
 * isolated spots that never leave the letters; drop it to ~0.055 and there is no window
 * at all, v floods the whole field and the wordmark dissolves into a flat wash.
 */

const LABEL = 'ARTBLOOM';
const FONT_STACK = 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
const TRACKING = 0.055;

const STEP = 1 / 60;
const SUBSTEPS = 3;
const TAU = 0.9;
const DU = 0.16;
const DV = 0.08;
const FEED = 0.037;
const KILL = 0.06;

const CELL_MIN = 3;
const GRID_MAX_X = 260;
const GRID_MAX_Y = 168;
const WARM_BUDGET = 1.8e7;
const WARM_MAX = 900;
const RESEED_WARM = 210;

const V_PEAK = 0.32;
const SPILL_DIM = 0.7;
const MARK_FLOOR = 0.05;
const SEED_GAP = 5;

interface State {
  clock: number;
  carry: number;
  snap: boolean;
  gw: number;
  gh: number;
  cell: number;
  u: Float64Array;
  v: Float64Array;
  un: Float64Array;
  vn: Float64Array;
  mask: Uint8Array;
  field: ImageData;
  off: HTMLCanvasElement;
  offContext: CanvasRenderingContext2D;
  markSize: number;
  markX: number;
  markY: number;
  seedX: number;
  seedY: number;
  hasSeed: boolean;
  warm: number;
}

/**
 * Zero-flux walls rather than a wrapping grid: with periodic edges the spill off the top
 * of the wordmark reappears under the copy, which reads as a bug rather than as growth.
 */
const advance = (s: State) => {
  const { u, v, un, vn, gw, gh } = s;
  for (let y = 0; y < gh; y += 1) {
    const row = y * gw;
    const up = (y > 0 ? y - 1 : 0) * gw;
    const down = (y < gh - 1 ? y + 1 : gh - 1) * gw;
    for (let x = 0; x < gw; x += 1) {
      const i = row + x;
      const cu = u[i];
      const cv = v[i];
      const lapU = u[row + (x > 0 ? x - 1 : 0)] + u[row + (x < gw - 1 ? x + 1 : gw - 1)] + u[up + x] + u[down + x] - 4 * cu;
      const lapV = v[row + (x > 0 ? x - 1 : 0)] + v[row + (x < gw - 1 ? x + 1 : gw - 1)] + v[up + x] + v[down + x] - 4 * cv;
      const react = cu * cv * cv;
      const nu = cu + TAU * (DU * lapU - react + FEED * (1 - cu));
      const nv = cv + TAU * (DV * lapV + react - (FEED + KILL) * cv);
      // A seed stamp can leave a cell momentarily outside [0,1]; unclamped, the cubic
      // term there runs away in two or three steps and the NaN never washes out.
      un[i] = nu < 0 ? 0 : nu > 1 ? 1 : nu;
      vn[i] = nv < 0 ? 0 : nv > 1 ? 1 : nv;
    }
  }
  s.u = un;
  s.un = u;
  s.v = vn;
  s.vn = v;
};

const warmUp = (s: State, steps: number) => {
  for (let n = 0; n < steps; n += 1) {
    advance(s);
  }
};

/** A disc of v with u locally spent, which is what a nucleation event physically is. */
const stampSeed = (s: State, gx: number, gy: number, radius: number) => {
  const { u, v, gw, gh } = s;
  const r2 = radius * radius;
  const x0 = Math.max(0, Math.floor(gx - radius));
  const x1 = Math.min(gw - 1, Math.ceil(gx + radius));
  const y0 = Math.max(0, Math.floor(gy - radius));
  const y1 = Math.min(gh - 1, Math.ceil(gy + radius));
  for (let y = y0; y <= y1; y += 1) {
    const dy = y - gy;
    for (let x = x0; x <= x1; x += 1) {
      const dx = x - gx;
      const d2 = dx * dx + dy * dy;
      if (d2 > r2) {
        continue;
      }
      const fall = 1 - d2 / r2;
      const i = y * gw + x;
      const load = 0.55 * fall;
      if (v[i] < load) {
        v[i] = load;
      }
      u[i] -= 0.5 * fall * u[i];
    }
  }
};

const seedFromMask = (s: State) => {
  const { u, v, mask } = s;
  u.fill(1);
  v.fill(0);
  let count = 0;
  for (let i = 0; i < mask.length; i += 1) {
    if (mask[i] === 0) {
      continue;
    }
    // Deliberately unequal nuclei. A perfectly uniform seed region breaks symmetry only
    // on floating-point dust, and then every mount braids the same way.
    v[i] = 0.16 + 0.24 * Math.random();
    u[i] = 0.42;
    count += 1;
  }
  if (count === 0) {
    stampSeed(s, s.gw / 2, s.gh / 2, Math.max(4, s.gw * 0.05));
  }
  s.hasSeed = false;
};

/* Tracked by hand, one glyph at a time: ctx.letterSpacing is not in every lib.dom we
   compile against, and a wordmark set solid looks like body copy. */
const markWidth = (ctx: CanvasRenderingContext2D, size: number) => {
  ctx.font = `800 ${size}px ${FONT_STACK}`;
  let total = 0;
  for (let i = 0; i < LABEL.length; i += 1) {
    total += ctx.measureText(LABEL.charAt(i)).width;
  }
  return total + size * TRACKING * (LABEL.length - 1);
};

const paintMark = (ctx: CanvasRenderingContext2D, size: number, x: number, y: number, stroke: boolean) => {
  ctx.font = `800 ${size}px ${FONT_STACK}`;
  ctx.textAlign = 'left';
  ctx.textBaseline = 'alphabetic';
  let cursor = x;
  for (let i = 0; i < LABEL.length; i += 1) {
    const glyph = LABEL.charAt(i);
    if (stroke) {
      ctx.strokeText(glyph, cursor, y);
    } else {
      ctx.fillText(glyph, cursor, y);
    }
    cursor += ctx.measureText(glyph).width + size * TRACKING;
  }
};

/** The mask is cut at grid resolution, not canvas resolution: one wavelength of the
    pattern is several cells wide, so a crisper mask would buy nothing and cost a
    full-size getImageData on every resize. */
const buildMask = (s: State) => {
  const sheet = document.createElement('canvas');
  sheet.width = s.gw;
  sheet.height = s.gh;
  const ctx = sheet.getContext('2d');
  if (!ctx) {
    return;
  }
  ctx.fillStyle = '#ffffff';
  paintMark(ctx, s.markSize / s.cell, s.markX / s.cell, s.markY / s.cell, false);
  const px = ctx.getImageData(0, 0, s.gw, s.gh).data;
  for (let i = 0; i < s.mask.length; i += 1) {
    s.mask[i] = px[i * 4 + 3] > 96 ? 1 : 0;
  }
};

/* The grid is blitted up with smoothing on, so the coarse field arrives as soft tissue
   instead of pixels, and the letters get a hairline on top to stay legible after the
   pattern has spilled over them. */
const renderField = (s: State, context: CanvasRenderingContext2D) => {
  const { v, mask, field } = s;
  const px = field.data;
  for (let i = 0; i < mask.length; i += 1) {
    const t = v[i] > V_PEAK ? 1 : v[i] / V_PEAK;
    const inside = mask[i] === 1;
    const lit = t * t * (3 - 2 * t) * (inside ? 1 : SPILL_DIM) + (inside ? MARK_FLOOR : 0);
    // The mark floor pushes a saturated cell past 1, and the quartic on the red channel
    // then lands over 255. Clamped here rather than left to Uint8Clamped, which would
    // flatten the brightest ridges to a single value and lose the crest.
    const g = lit > 1 ? 1 : lit;
    const g2 = g * g;
    const g3 = g2 * g;
    const o = i * 4;
    px[o] = 8 + 236 * g3 * g;
    px[o + 1] = 11 + 218 * (0.42 * g + 0.58 * g2);
    px[o + 2] = 15 + 176 * (0.55 * g2 + 0.45 * g3);
    px[o + 3] = 255;
  }
  s.offContext.putImageData(field, 0, 0);
  context.imageSmoothingEnabled = true;
  context.imageSmoothingQuality = 'high';
  // Exactly `cell` CSS pixels per cell, so grid space and canvas space are the same map
  // the mask was cut in. The last row and column hang off the edge and are clipped.
  context.drawImage(s.off, 0, 0, s.gw * s.cell, s.gh * s.cell);
  context.lineWidth = Math.max(1, s.markSize * 0.014);
  context.strokeStyle = 'rgba(158, 246, 218, 0.34)';
  paintMark(context, s.markSize, s.markX, s.markY, true);
};

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

export function MorphogenWordmark({ compact = false }: MorphogenWordmarkProps) {
  const reduced = useReducedMotion();
  const reseed = useRef(false);

  const setup = ({ context, width, height }: SceneSetupContext): State => {
    const cell = Math.max(CELL_MIN, Math.ceil(Math.max(width / GRID_MAX_X, height / GRID_MAX_Y)));
    // Ceil, not floor: the grid must cover at least the canvas so the blit can go up by
    // exactly `cell` and overhang. Flooring left gw*cell short of width, the blit stretched
    // to close the gap, and the grown letters slid out from under their own hairline by a
    // few pixels at the right edge - the mask, the pointer and the paint disagreed.
    const gw = Math.max(8, Math.ceil(width / cell));
    const gh = Math.max(8, Math.ceil(height / cell));
    const cells = gw * gh;

    const off = document.createElement('canvas');
    off.width = gw;
    off.height = gh;
    // A detached 2D context only fails when the tab is out of memory. Falling back to the
    // scene's own context keeps the type honest and degrades to the hairline wordmark.
    const grid = off.getContext('2d') ?? context;

    const base = markWidth(context, 100);
    const pad = Math.max(20, Math.min(48, width * 0.05));
    const room = Math.min(width - pad * 2, 620);
    const unit = base > 0 ? base / 100 : 6;
    const markSize = Math.max(26, Math.min(room / unit, height * 0.2, 108));

    const state: State = {
      clock: 0,
      carry: 0,
      snap: reduced,
      gw,
      gh,
      cell,
      u: new Float64Array(cells).fill(1),
      v: new Float64Array(cells),
      un: new Float64Array(cells),
      vn: new Float64Array(cells),
      mask: new Uint8Array(cells),
      field: grid.createImageData(gw, gh),
      off,
      offContext: grid,
      markSize,
      markX: pad,
      markY: Math.round(height * 0.36),
      seedX: 0,
      seedY: 0,
      hasSeed: false,
      warm: 120,
    };

    // Fixed work rather than a fixed step count: a wide hero has four times the cells of a
    // narrow one, and mount latency is what a reader actually notices.
    state.warm = Math.max(120, Math.min(WARM_MAX, Math.round(WARM_BUDGET / cells)));
    buildMask(state);
    seedFromMask(state);
    warmUp(state, reduced ? Math.round(state.warm * 1.4) : state.warm);
    return state;
  };

  const draw = ({ context, state, pointer }: SceneDrawContext<State>) => {
    // Read fresh every frame: a copy taken at setup goes stale the moment the OS setting
    // flips, because setup only re-runs on resize.
    state.snap = reduced;

    if (reseed.current) {
      reseed.current = false;
      seedFromMask(state);
      warmUp(state, state.snap ? state.warm : RESEED_WARM);
    }

    const now = performance.now() / 1000;
    const dt = state.clock === 0 ? 0 : Math.min(0.05, now - state.clock);
    state.clock = now;

    if (pointer.inside) {
      const gx = pointer.x / state.cell;
      const gy = pointer.y / state.cell;
      if (!state.hasSeed) {
        state.seedX = gx;
        state.seedY = gy;
        state.hasSeed = true;
      }
      const dx = gx - state.seedX;
      const dy = gy - state.seedY;
      const dist = Math.sqrt(dx * dx + dy * dy);
      // Stamped by distance travelled, not per frame, and interpolated along the segment
      // so a fast sweep leaves a continuous front instead of beads.
      if (dist >= SEED_GAP) {
        const stamps = Math.min(6, Math.floor(dist / SEED_GAP));
        for (let n = 1; n <= stamps; n += 1) {
          const f = n / stamps;
          const radius = (pointer.down ? 3.4 : 2.1) + Math.random() * 1.6;
          stampSeed(state, state.seedX + dx * f, state.seedY + dy * f, radius);
        }
        state.seedX = gx;
        state.seedY = gy;
      }
    } else {
      state.hasSeed = false;
    }

    if (!state.snap) {
      state.carry += dt;
      let n = 0;
      while (state.carry >= STEP && n < 8) {
        for (let k = 0; k < SUBSTEPS; k += 1) {
          advance(state);
        }
        state.carry -= STEP;
        n += 1;
      }
      if (n === 8) {
        state.carry = 0;
      }
    }

    renderField(state, context);
  };

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

  // Block body on purpose: `() => requestRender()` hands the effect whatever that call
  // returns, and React reads a returned value as a cleanup function.
  useEffect(() => {
    requestRender();
  }, [reduced, requestRender]);

  const growAgain = () => {
    reseed.current = true;
    requestRender();
  };

  return (
    <div className="morphogen-wordmark-stage" data-compact={compact ? 'true' : undefined}>
      <div ref={stageRef} className="morphogen-wordmark-surface">
        <canvas ref={canvasRef} aria-hidden="true" />
      </div>
      <div className="morphogen-wordmark-content">
        <h1 className="morphogen-wordmark-mark">Artbloom</h1>
        <p className="morphogen-wordmark-eyebrow">Gray-Scott morphogenesis</p>
        <h2 className="morphogen-wordmark-headline">The mark grows the rest of the page.</h2>
        <p className="morphogen-wordmark-body">
          Two reagents and no keyframes. The wordmark is nucleated into the field, then the
          front feeds outward until the stripes have taken the space around it. Every load
          braids differently, and so does every pass of your pointer.
        </p>
        <div className="morphogen-wordmark-actions">
          {/* 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
            type="button"
            className="morphogen-wordmark-cta"
            tabIndex={compact ? -1 : undefined}
            onClick={growAgain}
          >
            Grow it again
          </button>
          <span className="morphogen-wordmark-meta">F 0.037 / k 0.060 / Du 0.16</span>
        </div>
      </div>
      <p className="morphogen-wordmark-hint">move to seed growth</p>
    </div>
  );
}

export default MorphogenWordmark;

.morphogen-wordmark-stage {
  position: relative;
  display: flex;
  width: 100%;
  min-height: 28rem;
  overflow: hidden;
  border-radius: 0.75rem;
  background: #06080b;
  color: #edf6f1;
}

/* A border here would push `inset: 0` in on the padding box and slide the canvas
   origin away from the grid the solver is stepping. Hairline as an inset shadow. */
.morphogen-wordmark-surface {
  position: absolute;
  inset: 0;
  touch-action: none;
  cursor: crosshair;
  box-shadow: inset 0 0 0 1px rgba(126, 231, 195, 0.14);
}

.morphogen-wordmark-surface canvas {
  display: block;
  width: 100%;
  height: 100%;
}

/* The field is at its densest exactly where the copy sits, so the copy gets its
   own floor of contrast rather than hoping the pattern stays polite down there. */
.morphogen-wordmark-surface::after {
  content: '';
  position: absolute;
  inset: 0;
  pointer-events: none;
  background:
    radial-gradient(115% 85% at 82% 6%, rgba(6, 8, 11, 0) 34%, rgba(4, 6, 8, 0.6) 100%),
    linear-gradient(180deg, rgba(4, 6, 8, 0.18) 0%, rgba(4, 6, 8, 0) 32%, rgba(4, 6, 8, 0.88) 88%);
}

/* Transparent to the pointer: a drag that starts anywhere over the hero still
   nucleates. The button takes events back, and works because it is a later
   sibling than the element the hook captures the pointer on. */
.morphogen-wordmark-content {
  position: relative;
  display: flex;
  width: 100%;
  flex-direction: column;
  justify-content: flex-end;
  gap: 0.875rem;
  padding: 1.75rem clamp(1.25rem, 5vw, 3rem) 3.5rem;
  pointer-events: none;
}

/* The wordmark itself is painted into the field, and the canvas is aria-hidden.
   This is the same word, kept in the accessibility tree and out of the picture. */
.morphogen-wordmark-mark {
  position: absolute;
  width: 1px;
  height: 1px;
  margin: -1px;
  padding: 0;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}

.morphogen-wordmark-eyebrow {
  margin: 0;
  font: 600 0.6875rem/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.16em;
  text-transform: uppercase;
  color: rgba(126, 231, 195, 0.82);
}

.morphogen-wordmark-headline {
  max-width: 20ch;
  margin: 0;
  font-size: clamp(1.5rem, 3.6vw, 2.25rem);
  font-weight: 600;
  line-height: 1.1;
  letter-spacing: -0.025em;
  text-shadow: 0 1px 20px rgba(4, 6, 8, 0.72);
}

.morphogen-wordmark-body {
  max-width: 44ch;
  margin: 0;
  font-size: 0.875rem;
  line-height: 1.5;
  color: rgba(237, 246, 241, 0.68);
  text-shadow: 0 1px 16px rgba(4, 6, 8, 0.7);
}

.morphogen-wordmark-actions {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 0.75rem 1.125rem;
  margin-top: 0.25rem;
}

.morphogen-wordmark-cta {
  appearance: none;
  margin: 0;
  padding: 0.625rem 1.125rem;
  border: 0;
  border-radius: 999px;
  background: #7ee7c3;
  font: inherit;
  font-size: 0.8125rem;
  font-weight: 600;
  color: #04231a;
  cursor: pointer;
  pointer-events: auto;
  transition:
    background-color 160ms ease,
    box-shadow 160ms ease;
}

.morphogen-wordmark-cta:hover {
  background: #9df3d6;
  box-shadow: 0 0 0 6px rgba(126, 231, 195, 0.12);
}

.morphogen-wordmark-cta:focus-visible {
  outline: 2px solid rgba(157, 243, 214, 0.9);
  outline-offset: 3px;
}

.morphogen-wordmark-meta {
  font: 500 0.6875rem/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.1em;
  color: rgba(237, 246, 241, 0.46);
}

.morphogen-wordmark-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(237, 246, 241, 0.3);
  pointer-events: none;
}

/*
 * What goes away is the ongoing growth: the hook never starts the loop, so the
 * pattern the component paints once is a field that was already stepped a few
 * hundred times inside setup — the letters are dense, the spill is out past them,
 * and it simply stops there. The button still reseeds and repaints on demand.
 */
@media (prefers-reduced-motion: reduce) {
  .morphogen-wordmark-cta {
    transition: none;
  }

  .morphogen-wordmark-cta:hover {
    box-shadow: none;
  }

  .morphogen-wordmark-surface {
    cursor: default;
  }
}

/*
 * Card variant: the 298x240 catalogue tile, at real pixels and with no scaling
 * anywhere. The hero copy is what has to go — a headline sized in `vw` reads the
 * 1340px viewport, not this box, and it landed under the growing pattern. Here the
 * field owns the whole frame and the copy is one line of eyebrow plus the reseed
 * chip, pinned along the bottom edge where the existing wash is already darkest.
 */
.morphogen-wordmark-stage[data-compact='true'] {
  min-height: 0;
  height: 100%;
  border-radius: 0;
}

/* `none` would eat a vertical swipe over a full-bleed card inside a scrolling
   grid and trap the page on a phone. Seeding wants both axes, but a stuck page is
   the worse failure: `pan-y` gives the scroll back and a sideways drag still
   nucleates, as does any pointer that is not a finger. */
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-surface {
  touch-action: pan-y;
}

/* Off the mechanism entirely rather than stacked in front of it: a bottom strip
   about 64px tall, while the wordmark is painted around y=86 and the spill has the
   rest. Still `pointer-events: none`, so a drag through the strip seeds. */
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-content {
  position: absolute;
  inset: auto 0 0 0;
  width: auto;
  align-items: flex-start;
  gap: 0.5rem;
  padding: 0.75rem;
}

.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-headline,
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-body,
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-meta,
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-hint {
  display: none;
}

/* The one line that stays, at a fixed 10px and held to a single line. */
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-eyebrow {
  font-size: 0.625rem;
  letter-spacing: 0.14em;
  white-space: nowrap;
  text-shadow: 0 1px 10px rgba(4, 6, 8, 0.85);
}

.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-actions {
  margin-top: 0;
}

/* Kept, and kept clickable: pressing it re-nucleates the field out of the letters,
   which is the whole trick in two seconds. `tabIndex={-1}` in the component keeps
   it out of the tab order under the card's `aria-hidden`. */
.morphogen-wordmark-stage[data-compact='true'] .morphogen-wordmark-cta {
  padding: 0.3125rem 0.625rem;
  font-size: 0.625rem;
  pointer-events: auto;
}

"use client"

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

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

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

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

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

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

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

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

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

  return reduced
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    measure()
    paint()
    start()

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

  return { stageRef, canvasRef, requestRender }
}