Dock Magnify

'use client';

import './dock-magnify.css';

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

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

/*
 * A dock whose shelf is a BEAM ON A WINKLER ELASTIC FOUNDATION. The pointer is a
 * concentrated load P riding along it, and the shelf's shape is the solution of
 *
 *     EI * w'''' + k * w = p(x),        w(0) = w(W) = 0,  w'(0) = w'(W) = 0
 *
 * with the fourth derivative taken by the central five-point stencil
 * (w[i-2] - 4w[i-1] + 6w[i] - 4w[i+1] + w[i+2]) / h^4. That makes a symmetric
 * pentadiagonal positive-definite system in the 119 interior nodes, factorised
 * once per resize by banded Cholesky and back-substituted every frame — one
 * linear solve per painted frame, not a curve evaluated at eight points.
 *
 * It is NOT a Gaussian, NOT a cosine window, and NOT a distance-to-pointer
 * falloff with a radius. Every dock in every library reaches for one of those
 * three, and all three are positive everywhere. The elastic response is not:
 *
 *     w(x) = (P / 2kL) * e^(-|x|/L) * (cos(x/L) + sin(x/L)),   L = (4EI/k)^(1/4)
 *
 * crosses zero at 3*pi/4 * L and troughs at pi * L, where it sits at -e^(-pi),
 * i.e. 4.3% of the peak, BELOW the resting line. So the icon two places out from
 * the pointer does not merely fail to rise — it dips under the dock's rim, and
 * you can watch it pass behind the rim hairline. That undershoot is the whole
 * argument: it is unreachable by any positive kernel, and here it falls out of
 * the solve rather than being drawn in.
 *
 * Two more things come free with the equation and are visible on the shelf. The
 * bump's width is a material property, L, and not a radius: at L = 0.7 of the
 * icon pitch the zero crossing lands at 1.65 pitches and the trough at 2.20, so
 * which neighbour sinks is decided by EI/k. And the boundary is real — both ends
 * are built in, so an end icon lifts about 65% of what a mid-dock icon lifts,
 * the stiffening you feel in a real dock's corners and that no falloff produces.
 */

/** Icons on the dock. Eight, so aiming the middle keeps both undershoot slots on the shelf. */
const SLOTS = 8;
/** Interior nodes plus two ends. 121 puts h at 0.07 of L, where the stencil's error is under 0.1%. */
const NODES = 121;
/** Foundation modulus k. The unit of the whole system: EI and P are expressed in it. */
const BED = 1;
/** L in icon pitches. 0.7 puts the zero crossing at 1.65 pitches, so slot +-2 is the one that sinks. */
const L_CELLS = 0.7;
/** Built-in ends, 0.3 pitch outside the end icons: close enough to stiffen a corner, not to pin it. */
const PAD_CELLS = 0.3;
/** Peak rise at the pointer, in pitches. 1.05 lifts an icon clear of its neighbours' tops. */
const LIFT_CELLS = 1.05;
/** Icon side at rest, in pitches. 0.58 leaves the gap a dock needs to read as separate tiles. */
const TILE_CELLS = 0.58;
/** Scale at full lift. 1.7 is the macOS dock's magnification, and it fits inside a 0.7-pitch bump. */
const MAG = 1.7;
/** Load sign under a press. -0.26 dimples the aimed icon 14px into the shelf and inverts the lobes. */
const PRESS = -0.26;
/** Shelf thickness in px. 18 is deeper than the -2.1px trough, so a sunk icon stays inside the rim. */
const PLATE_H = 18;
/** Shelf inset from the card's edges in px, so the dock reads as a shelf with air at either end. */
const PLATE_INSET = 16;
/** Room below the resting line in px: 18 for the shelf, 16 so a press cannot clip its underside. */
const FOOT = 34;
/** Least room above the resting line in px, so the icons keep their headroom on a short card. */
const HEAD = 66;
/** Grab slack below the shelf in px, so a pointer just under the rim still counts as on the dock. */
const SLACK = 24;
/** Seconds per solver step. The load lag is first order with tau >= 45ms; dt/tau = 0.19 here, stable. */
const STEP = 1 / 120;
/** Steps per frame ceiling. 12 covers a 100ms hitch and refuses to chase a backgrounded tab. */
const MAX_STEPS = 12;
/** Time constant of the load's travel, in seconds. 0.045 trails a fast flick by about 3px. */
const MOVE_TAU = 0.045;
/** Time constant of the load's magnitude. 0.085 is slower than the travel, so the bump grows in place. */
const FADE_TAU = 0.085;
/** Which icon the load starts under. Slot 3 is off centre, so the response is visibly asymmetric. */
const START = 3;
/** Apps open at rest, one bit per slot: Finder, Terminal and Messages. */
const OPEN = 0b01001001;

const INK = '234, 243, 255';
const ACCENT = '158, 205, 255';
const TAU = Math.PI * 2;

type AppKind = 'files' | 'mail' | 'calendar' | 'terminal' | 'music' | 'photos' | 'chat' | 'gear';

interface DockApp {
  readonly name: string;
  readonly kind: AppKind;
}

const APPS: readonly DockApp[] = [
  { name: 'Finder', kind: 'files' },
  { name: 'Mail', kind: 'mail' },
  { name: 'Calendar', kind: 'calendar' },
  { name: 'Terminal', kind: 'terminal' },
  { name: 'Music', kind: 'music' },
  { name: 'Photos', kind: 'photos' },
  { name: 'Messages', kind: 'chat' },
  { name: 'Settings', kind: 'gear' },
];

/** The banded Cholesky factor of the stiffness matrix: diagonal plus two sub-diagonals. */
interface Band {
  readonly size: number;
  readonly d: Float64Array;
  readonly l1: Float64Array;
  readonly l2: Float64Array;
}

/** What the DOM shows about the frame the solver just produced. */
interface Readout {
  aim: number;
}

interface DockState {
  /** Geometry, all of it derived from the stage at setup and never mutated after. */
  readonly plateX: number;
  readonly plateW: number;
  readonly restY: number;
  readonly cell: number;
  readonly pad: number;
  readonly tile: number;
  readonly lift: number;
  /** P, scaled so the infinite-beam peak P/(2kL) equals `lift`. */
  readonly load: number;
  readonly h: number;
  /** Vertical reach above the resting line that still counts as being on the dock. */
  readonly band: number;
  readonly centres: Float64Array;
  readonly system: Band;
  readonly rhs: Float64Array;
  readonly inner: Float64Array;
  readonly w: Float64Array;
  readonly wAt: Float64Array;
  readonly tileFill: CanvasGradient;

  /** Load position along the shelf, in px from its left end, and where it is headed. */
  lx: number;
  lxTarget: number;
  /** Load magnitude as a fraction of P, and its target. Negative under a press. */
  p: number;
  pTarget: number;
  clock: number;
  carry: number;
  snap: boolean;
  magnify: boolean;
  /** One bit per slot, set when that app is open. Read from React each frame. */
  running: number;
  /** Slot holding keyboard focus, or -1. The load follows it when nothing is hovering. */
  keyed: number;
  aim: number;
  engaged: boolean;
  /** Last transform written per slot: x, y, scale. NaN until the first placement. */
  posted: Float64Array;
}

/*
 * Banded Cholesky of the clamped stiffness matrix. Row i of the interior system is
 * beta * (w[i-2] - 4w[i-1] + 6w[i] - 4w[i+1] + w[i+2]) + k * w[i], with beta = EI/h^4.
 * The clamp enters as a ghost node, w[-1] = w[1]: reflecting it onto the first and last
 * rows turns their 6*beta into 7*beta, and that single changed entry is the entire
 * difference between a built-in end and a pinned one. Factorising here rather than per
 * frame is what makes a solve-per-frame cheap: 119 unknowns cost about 1.8 microseconds.
 */
function factorise(size: number, beta: number): Band {
  const d = new Float64Array(size);
  const l1 = new Float64Array(size);
  const l2 = new Float64Array(size);
  const at = (row: number, column: number): number => {
    const gap = Math.abs(row - column);
    if (gap === 2) return beta;
    if (gap === 1) return -4 * beta;
    if (gap > 2) return 0;
    const edge = row === 0 || row === size - 1;
    return (edge ? 7 : 6) * beta + BED;
  };

  for (let i = 0; i < size; i += 1) {
    d[i] = Math.sqrt(at(i, i) - l1[i] * l1[i] - l2[i] * l2[i]);
    if (i + 1 < size) l1[i + 1] = (at(i + 1, i) - l2[i + 1] * l1[i]) / d[i];
    if (i + 2 < size) l2[i + 2] = at(i + 2, i) / d[i];
  }

  return { size, d, l1, l2 };
}

/** Forward then back substitution through the factor. O(n), and the whole per-frame cost. */
function bandSolve(band: Band, rhs: Float64Array, out: Float64Array): void {
  const { size, d, l1, l2 } = band;
  for (let i = 0; i < size; i += 1) {
    const b1 = i >= 1 ? l1[i] * out[i - 1] : 0;
    const b2 = i >= 2 ? l2[i] * out[i - 2] : 0;
    out[i] = (rhs[i] - b1 - b2) / d[i];
  }
  for (let i = size - 1; i >= 0; i -= 1) {
    const u1 = i + 1 < size ? l1[i + 1] * out[i + 1] : 0;
    const u2 = i + 2 < size ? l2[i + 2] * out[i + 2] : 0;
    out[i] = (out[i] - u1 - u2) / d[i];
  }
}

/**
 * Build the right-hand side for the load where it currently is, solve, and read the shelf
 * height at each icon. The load lands between two nodes and is split between them by
 * distance — consistent lumping. Rounding it to the nearest node instead would make the
 * bump jump the 3.7px node spacing, which is plainly visible on a slow drag.
 */
function deflect(state: DockState): void {
  const { rhs, inner, w, h, system } = state;
  rhs.fill(0);
  const g = Math.max(0, Math.min(state.plateW, state.lx)) / h;
  const node = Math.floor(g);
  const frac = g - node;
  const scale = (state.p * state.load) / h;
  for (let k = 0; k < 2; k += 1) {
    const i = node + k - 1;
    if (i >= 0 && i < rhs.length) rhs[i] += scale * (k === 0 ? 1 - frac : frac);
  }
  bandSolve(system, rhs, inner);
  for (let i = 0; i < inner.length; i += 1) w[i + 1] = inner[i];
  for (let i = 0; i < SLOTS; i += 1) state.wAt[i] = sampleW(state, state.centres[i]);
}

/** Shelf height between nodes, linearly. The stencil's own error is larger than this one's. */
function sampleW(state: DockState, x: number): number {
  const g = Math.max(0, Math.min(state.plateW, x)) / state.h;
  const i = Math.min(NODES - 2, Math.floor(g));
  return state.w[i] + (state.w[i + 1] - state.w[i]) * (g - i);
}

const slotAt = (state: DockState, x: number): number =>
  Math.max(0, Math.min(SLOTS - 1, Math.round((x - state.pad) / state.cell - 0.5)));

/** Icon side at a given shelf height. Linear in w, so the scale is the solve, not a curve of its own. */
const sizeOf = (state: DockState, w: number): number => state.tile * (1 + (MAG - 1) * (w / state.lift));

/**
 * Size the shelf to the stage and factorise its stiffness matrix. Everything geometric is
 * derived from one number, the icon pitch, so a 390px card and a 1340px one are the same
 * dock at two scales; and EI is not a free parameter — the characteristic length is chosen
 * in pitches and EI = k * L^4 / 4 follows, which is why the bump keeps its shape.
 */
function build({ context, width, height }: SceneSetupContext, snap: boolean, magnify: boolean): DockState {
  const plateX = PLATE_INSET;
  const plateW = Math.max(SLOTS * 12, width - PLATE_INSET * 2);
  const restY = Math.max(HEAD, height - FOOT);
  const cell = plateW / (SLOTS + 2 * PAD_CELLS);
  const pad = PAD_CELLS * cell;
  const charLen = L_CELLS * cell;
  const lift = LIFT_CELLS * cell;
  const tile = TILE_CELLS * cell;
  const h = plateW / (NODES - 1);
  const size = NODES - 2;

  const centres = new Float64Array(SLOTS);
  for (let i = 0; i < SLOTS; i += 1) centres[i] = pad + (i + 0.5) * cell;

  // Made once and drawn under a unit-space transform, so one gradient serves eight icons
  // at eight different scales.
  const tileFill = context.createLinearGradient(0, -0.5, 0, 0.5);
  tileFill.addColorStop(0, `rgba(${ACCENT}, 0.22)`);
  tileFill.addColorStop(1, 'rgba(8, 14, 23, 0.92)');

  const start = pad + (START + 0.5) * cell;

  return {
    plateX,
    plateW,
    restY,
    cell,
    pad,
    tile,
    lift,
    load: 2 * BED * charLen * lift,
    h,
    band: lift + tile * MAG,
    centres,
    system: factorise(size, (BED * charLen ** 4) / 4 / h ** 4),
    rhs: new Float64Array(size),
    inner: new Float64Array(size),
    w: new Float64Array(NODES),
    wAt: new Float64Array(SLOTS),
    tileFill,
    lx: start,
    lxTarget: start,
    p: 0,
    pTarget: 0,
    clock: 0,
    carry: 0,
    snap,
    magnify,
    running: OPEN,
    keyed: -1,
    aim: START,
    engaged: false,
    posted: new Float64Array(SLOTS * 3).fill(Number.NaN),
  };
}

/** The deflected surface, node by node. `lineTo` opens the subpath, so no separate `moveTo`. */
function surfacePath(context: CanvasRenderingContext2D, state: DockState): void {
  context.beginPath();
  for (let i = 0; i < NODES; i += 1) {
    context.lineTo(state.plateX + i * state.h, state.restY - state.w[i]);
  }
}

/** The shelf as a solid of constant thickness: the surface out, the underside back. */
function ribbonPath(context: CanvasRenderingContext2D, state: DockState): void {
  context.beginPath();
  for (let i = 0; i < NODES; i += 1) {
    context.lineTo(state.plateX + i * state.h, state.restY - state.w[i]);
  }
  for (let i = NODES - 1; i >= 0; i -= 1) {
    context.lineTo(state.plateX + i * state.h, state.restY - state.w[i] + PLATE_H);
  }
  context.closePath();
}

/** A rounded square on the unit box, so one path serves every icon at every scale. */
function roundedUnit(context: CanvasRenderingContext2D, radius: number): void {
  context.beginPath();
  context.moveTo(-0.5 + radius, -0.5);
  context.arcTo(0.5, -0.5, 0.5, 0.5, radius);
  context.arcTo(0.5, 0.5, -0.5, 0.5, radius);
  context.arcTo(-0.5, 0.5, -0.5, -0.5, radius);
  context.arcTo(-0.5, -0.5, 0.5, -0.5, radius);
  context.closePath();
}

/**
 * The mark on an icon, in unit space, stroked at whatever width the caller set. Painted on
 * the canvas rather than left to the DOM because it rides a surface the DOM cannot bend;
 * the button over it carries the name, so nothing here is load-bearing for a screen reader.
 */
function glyph(context: CanvasRenderingContext2D, kind: AppKind): void {
  context.beginPath();
  switch (kind) {
    case 'files':
      context.moveTo(-0.19, -0.06);
      context.lineTo(-0.19, -0.14);
      context.lineTo(-0.02, -0.14);
      context.lineTo(0.03, -0.06);
      context.lineTo(0.19, -0.06);
      context.lineTo(0.19, 0.15);
      context.lineTo(-0.19, 0.15);
      context.closePath();
      break;
    case 'mail':
      context.rect(-0.2, -0.13, 0.4, 0.26);
      context.moveTo(-0.2, -0.13);
      context.lineTo(0, 0.02);
      context.lineTo(0.2, -0.13);
      break;
    case 'calendar':
      context.rect(-0.19, -0.12, 0.38, 0.27);
      context.moveTo(-0.19, -0.03);
      context.lineTo(0.19, -0.03);
      context.moveTo(-0.09, -0.19);
      context.lineTo(-0.09, -0.07);
      context.moveTo(0.09, -0.19);
      context.lineTo(0.09, -0.07);
      break;
    case 'terminal':
      context.moveTo(-0.16, -0.09);
      context.lineTo(-0.05, 0.01);
      context.lineTo(-0.16, 0.11);
      context.moveTo(0.01, 0.13);
      context.lineTo(0.17, 0.13);
      break;
    case 'music':
      context.moveTo(0.035, 0.09);
      context.arc(-0.04, 0.09, 0.075, 0, TAU);
      context.moveTo(0.035, 0.09);
      context.lineTo(0.035, -0.15);
      context.lineTo(0.15, -0.09);
      break;
    case 'photos':
      context.rect(-0.2, -0.13, 0.4, 0.26);
      context.moveTo(-0.035, -0.045);
      context.arc(-0.08, -0.045, 0.045, 0, TAU);
      context.moveTo(-0.2, 0.13);
      context.lineTo(-0.02, 0);
      context.lineTo(0.07, 0.07);
      context.lineTo(0.13, 0.02);
      context.lineTo(0.2, 0.13);
      break;
    case 'chat':
      context.rect(-0.19, -0.14, 0.38, 0.23);
      context.moveTo(-0.12, 0.09);
      context.lineTo(-0.12, 0.19);
      context.lineTo(-0.02, 0.09);
      break;
    case 'gear':
      context.moveTo(0.085, 0);
      context.arc(0, 0, 0.085, 0, TAU);
      for (let i = 0; i < 8; i += 1) {
        const angle = (i / 8) * TAU;
        context.moveTo(Math.cos(angle) * 0.125, Math.sin(angle) * 0.125);
        context.lineTo(Math.cos(angle) * 0.195, Math.sin(angle) * 0.195);
      }
      break;
  }
  context.stroke();
}

/*
 * One frame: aim the load, walk the lag to it at a fixed step, solve the beam, draw.
 *
 * The beam itself is solved statically — for a shelf this stiff the elastic transient is
 * over inside a frame, so pretending otherwise would be fiction. What has a time constant
 * is the load: a hand does not teleport, and neither does the pressure it puts on the
 * shelf. Those two lags are integrated at a fixed 1/120s because they are explicit and
 * first order: at a 60ms frame, dt/tau would be 1.33 and the bump would ring on arrival.
 */
function paint(scene: SceneDrawContext<DockState>): void {
  const { context, width, height, state, pointer } = scene;
  const now = performance.now();
  const elapsed = state.clock ? Math.min(0.05, (now - state.clock) / 1000) : STEP;
  state.clock = now;

  // On the dock means anywhere the dock reaches: a magnified icon stands a full pitch
  // above the shelf, so the band has to include the space it occupies or the bump would
  // collapse the moment the pointer followed the icon it just raised.
  const localX = pointer.x - state.plateX;
  const onDock =
    pointer.inside &&
    pointer.y > state.restY - state.band &&
    pointer.y < state.restY + PLATE_H + SLACK &&
    localX > -state.cell &&
    localX < state.plateW + state.cell;

  if (onDock) {
    state.lxTarget = Math.max(0, Math.min(state.plateW, localX));
    state.pTarget = state.magnify ? (pointer.down ? PRESS : 1) : 0;
  } else if (state.keyed >= 0) {
    // Nothing is hovering but a dock button holds focus, so the arrows drive the same
    // load the pointer does and the bump travels to whatever Tab reached.
    state.lxTarget = state.centres[state.keyed];
    state.pTarget = state.magnify ? 1 : 0;
  } else {
    state.pTarget = 0;
  }
  state.engaged = onDock;

  if (state.snap) {
    // With the loop stopped nothing can be walked anywhere, so the load is placed at its
    // target and the beam is solved there in one step. The whole response is on screen,
    // undershoot and end stiffening included; what is gone is the travel to it.
    state.lx = state.lxTarget;
    state.p = state.pTarget;
    state.carry = 0;
  } else {
    state.carry += elapsed;
    const steps = Math.min(MAX_STEPS, Math.floor(state.carry / STEP));
    for (let i = 0; i < steps; i += 1) {
      state.lx += (state.lxTarget - state.lx) * (STEP / MOVE_TAU);
      state.p += (state.pTarget - state.p) * (STEP / FADE_TAU);
    }
    state.carry -= steps * STEP;
    // A tab that was backgrounded owes nothing on return.
    if (state.carry > STEP * MAX_STEPS) state.carry = 0;
  }

  state.aim = slotAt(state, state.lx);
  deflect(state);

  const { plateX, plateW, restY } = state;
  context.clearRect(0, 0, width, height);
  context.lineJoin = 'round';
  context.lineCap = 'round';

  ribbonPath(context, state);
  context.fillStyle = `rgba(${INK}, 0.055)`;
  context.fill();
  context.lineWidth = 1;
  context.strokeStyle = `rgba(${INK}, 0.13)`;
  context.stroke();

  for (let i = 0; i < SLOTS; i += 1) {
    const w = state.wAt[i];
    const size = sizeOf(state, w);
    const cx = plateX + state.centres[i];
    const lit = Math.max(0, Math.min(1, w / state.lift));
    context.save();
    // Icons ride the surface: the foot of the tile is the shelf's height at its own x, so
    // the lift and the magnification are two readings of one solve.
    context.translate(cx, restY - w - size / 2);
    context.scale(size, size);
    roundedUnit(context, 0.22);
    context.fillStyle = state.tileFill;
    context.fill();
    context.lineWidth = 1.1 / size;
    context.strokeStyle = `rgba(${ACCENT}, ${(0.18 + 0.5 * lit).toFixed(3)})`;
    context.stroke();
    context.lineWidth = 1.6 / size;
    context.strokeStyle = `rgba(${INK}, ${(0.42 + 0.42 * lit).toFixed(3)})`;
    glyph(context, APPS[i].kind);
    context.restore();

    if ((state.running & (1 << i)) !== 0) {
      context.beginPath();
      context.arc(cx, restY - w + 7, 1.6, 0, TAU);
      context.fillStyle = `rgba(${ACCENT}, 0.8)`;
      context.fill();
    }
  }

  surfacePath(context, state);
  context.lineWidth = 1.4;
  context.strokeStyle = `rgba(${ACCENT}, 0.55)`;
  context.stroke();

  // The rim, at the undeflected line, drawn in front of the icons so a sunk one visibly
  // passes behind it. This is the reference the eye compares against.
  context.fillStyle = `rgba(${INK}, 0.26)`;
  context.fillRect(plateX, restY - 0.5, plateW, 1);
}

/*
 * Move the real buttons onto the tiles the solver just drew, so the focus ring rides the
 * bump instead of sitting where the icon used to be. The transform is written from the same
 * two numbers the canvas used; CSS owns only the centring translate, never a hand-matched
 * `left`. Writes are skipped when nothing moved, which is most frames once the load settles.
 */
function place(state: DockState, buttons: (HTMLButtonElement | null)[], tip: HTMLElement | null): void {
  for (let i = 0; i < SLOTS; i += 1) {
    const node = buttons[i];
    if (!node) continue;
    const w = state.wAt[i];
    const size = sizeOf(state, w);
    const x = state.plateX + state.centres[i];
    const y = state.restY - w - size / 2;
    const scale = size / state.tile;
    const slot = i * 3;
    const first = Number.isNaN(state.posted[slot]);
    if (
      !first &&
      Math.abs(state.posted[slot + 1] - y) < 0.3 &&
      Math.abs(state.posted[slot + 2] - scale) < 0.004
    ) {
      continue;
    }
    if (first) {
      // The rest size is set once per rebuild; every frame after that is a scale, which is
      // one composited property rather than a relayout eight times a frame.
      node.style.width = `${state.tile.toFixed(1)}px`;
      node.style.height = `${state.tile.toFixed(1)}px`;
      node.style.opacity = '1';
    }
    state.posted[slot] = x;
    state.posted[slot + 1] = y;
    state.posted[slot + 2] = scale;
    node.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px) translate(-50%, -50%) scale(${scale.toFixed(3)})`;
  }

  if (!tip) return;
  const w = state.wAt[state.aim];
  const x = state.plateX + state.centres[state.aim];
  const y = state.restY - w - sizeOf(state, w) - 10;
  // The label is faded by the load itself, so it arrives with the bump rather than on a
  // timer of its own, and it leaves when the hand does.
  tip.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px) translate(-50%, -100%)`;
  tip.style.opacity = Math.max(0, Math.min(1, Math.abs(state.p) / 0.5)).toFixed(2);
}

/** `compact` is the 298x240 catalogue card: the same shelf, the same eight icons and the
 *  same solve, with the hint below the card dropped and the head tightened. The shelf is
 *  sized from the canvas box — `restY` is `height − FOOT` under a clamp and every other
 *  length is in icon pitches — so a shorter card is the same dock at a smaller scale. See
 *  `dock-magnify.css`. */
export type DockMagnifyProps = { compact?: boolean };

export function DockMagnify({ compact = false }: DockMagnifyProps) {
  const reduced = useReducedMotion();
  const [magnify, setMagnify] = useState(true);
  const [running, setRunning] = useState(OPEN);
  const [roving, setRoving] = useState(START);
  const [readout, setReadout] = useState<Readout>({ aim: START });

  const buttonsRef = useRef<(HTMLButtonElement | null)[]>([]);
  const tipRef = useRef<HTMLParagraphElement>(null);
  /** Which slot holds focus, or -1. Kept out of state: the solver reads it every frame. */
  const keyedRef = useRef(-1);
  /** Written by the solver so a press on the shelf knows which icon it landed under. */
  const hitRef = useRef({ slot: START, engaged: false });
  /** Last published readout, so an unchanged frame does not re-render the DOM. */
  const postedRef = useRef<Readout>({ aim: START });

  const { stageRef, canvasRef, requestRender } = useCanvasScene<DockState>({
    setup: (scene: SceneSetupContext) => build(scene, reduced, magnify),
    draw: (scene: SceneDrawContext<DockState>) => {
      const { state } = scene;
      state.snap = reduced;
      state.magnify = magnify;
      state.running = running;
      state.keyed = keyedRef.current;

      paint(scene);
      place(state, buttonsRef.current, tipRef.current);
      hitRef.current.slot = state.aim;
      hitRef.current.engaged = state.engaged;

      const posted = postedRef.current;
      if (posted.aim !== state.aim) {
        postedRef.current = { aim: state.aim };
        setReadout(postedRef.current);
      }
    },
  });

  // Every React value the scene reads needs one of these, or a stopped loop keeps showing
  // the old frame: under reduced motion nothing repaints unless something asks it to. The
  // readout is deliberately absent — it is published *by* the scene, and feeding it back
  // would schedule a second paint for every frame of a drag.
  useEffect(() => {
    requestRender();
  }, [magnify, running, reduced, requestRender]);

  const toggleApp = (index: number) => {
    setRunning((mask) => mask ^ (1 << index));
  };

  const onSlotFocus = (index: number) => {
    keyedRef.current = index;
    setRoving(index);
    requestRender();
  };

  const onSlotBlur = () => {
    keyedRef.current = -1;
    requestRender();
  };

  const onSlotKey = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
    let next = index;
    if (event.key === 'ArrowRight' || event.key === 'ArrowDown') next = index + 1;
    else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') next = index - 1;
    else if (event.key === 'Home') next = 0;
    else if (event.key === 'End') next = SLOTS - 1;
    else return;
    event.preventDefault();
    buttonsRef.current[Math.max(0, Math.min(SLOTS - 1, next))]?.focus({ preventScroll: true });
  };

  /*
   * The shelf owns the pointer capture, which is why the eight icon buttons are laid over it
   * with `pointer-events: none` and their clicks are routed from here instead. Edge-detecting
   * `pointer.down` inside the solver would have done it too, but it drops a click that opens
   * and closes between two frames; the DOM's own click never misses one.
   */
  const onStagePointerDown = (event: PointerEvent<HTMLDivElement>) => {
    if (!hitRef.current.engaged) return;
    if ((event.target as HTMLElement).closest('button')) return;
    // In a card there is nothing to hand focus to — the frame is aria-hidden and its buttons
    // are out of the tab order — so the press is left to the shelf, and the click below still
    // opens the app under it.
    if (compact) return;
    buttonsRef.current[hitRef.current.slot]?.focus({ preventScroll: true });
    // The focus came from the pointer, so the pointer keeps the load: clicking an icon must
    // not leave the dock magnified after the hand has gone.
    keyedRef.current = -1;
  };

  const onStageClick = (event: MouseEvent<HTMLDivElement>) => {
    if ((event.target as HTMLElement).closest('button')) return;
    if (hitRef.current.engaged) toggleApp(hitRef.current.slot);
  };

  const app = APPS[readout.aim];
  const open = (running & (1 << readout.aim)) !== 0;

  return (
    <div
      className="dock-magnify-stage"
      data-compact={compact ? 'true' : undefined}
      onPointerDown={onStagePointerDown}
      onClick={onStageClick}
    >
      <div className="dock-magnify-card">
        <div ref={stageRef} className="dock-magnify-well" aria-hidden="true">
          <canvas ref={canvasRef} />
        </div>

        <div className="dock-magnify-head">
          <p className="dock-magnify-label">Dock</p>
          <p className="dock-magnify-read">
            {app.name}
            <span className="dock-magnify-unit">{open ? 'open' : 'not running'}</span>
          </p>
        </div>

        <button
          type="button"
          className="dock-magnify-toggle"
          aria-pressed={magnify}
          /* Still pressable in a card, but out of the tab order: the card frame is
             aria-hidden, and a focusable node inside one is a trap with no label. */
          tabIndex={compact ? -1 : undefined}
          onClick={() => setMagnify((on) => !on)}
        >
          Magnification
        </button>

        <div className="dock-magnify-apps" role="toolbar" aria-label="Dock" aria-orientation="horizontal">
          {APPS.map((each, index) => (
            <button
              key={each.name}
              ref={(node) => {
                buttonsRef.current[index] = node;
              }}
              type="button"
              className="dock-magnify-app"
              aria-pressed={(running & (1 << index)) !== 0}
              /* The roving index is the toolbar's whole keyboard contract, so it stays —
                 except in a card, where the entire frame is out of the tab order. */
              tabIndex={compact ? -1 : index === roving ? 0 : -1}
              onFocus={() => onSlotFocus(index)}
              onBlur={onSlotBlur}
              onKeyDown={(event) => onSlotKey(event, index)}
              onClick={() => toggleApp(index)}
            >
              <span className="dock-magnify-app-name">{each.name}</span>
            </button>
          ))}
        </div>

        <p ref={tipRef} className="dock-magnify-tip" aria-hidden="true">
          {app.name}
        </p>
      </div>

      <p className="dock-magnify-hint">Hover the dock, or Tab into it</p>
    </div>
  );
}

export default DockMagnify;

.dock-magnify-stage {
  position: relative;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  width: 100%;
  min-height: 23.5rem;
  padding: 2.25rem 1.5rem;
  overflow: hidden;
  border-radius: 0.75rem;
  background: radial-gradient(120% 110% at 50% 0%, #0c1620 0%, #070b12 60%, #05070c 100%);
  color: #eaf3ff;
}

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

/* The shelf, behind everything, and the layer that owns the pointer capture — so every
   other layer in the card is a sibling of it rather than a child, which would swallow the
   press. Its box is the card's padding box, which is why a transform written from a canvas
   pixel lands where the canvas drew. */
.dock-magnify-well {
  position: absolute;
  inset: 0;
  touch-action: none;
}

.dock-magnify-well canvas {
  display: block;
  width: 100%;
  height: 100%;
}

.dock-magnify-head {
  position: absolute;
  top: 1rem;
  left: 1.25rem;
  pointer-events: none;
}

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

.dock-magnify-read {
  margin: 0;
  font-size: 1.3125rem;
  font-weight: 500;
  line-height: 1;
  letter-spacing: -0.02em;
  text-shadow: 0 1px 18px rgba(5, 12, 20, 0.55);
}

/* Its own line, not a suffix: at 390px a long app name plus its state would have run under
   the Magnification switch in the opposite corner. */
.dock-magnify-unit {
  display: block;
  margin-top: 0.3125rem;
  font-size: 0.75rem;
  font-weight: 500;
  letter-spacing: 0;
  color: rgba(234, 243, 255, 0.55);
}

/* The one control that needs its own click, so it takes events back. Moving onto it leaves
   the shelf, which drops the load — correct: the pointer is no longer on the dock. */
.dock-magnify-toggle {
  position: absolute;
  top: 1rem;
  right: 1.125rem;
  display: inline-flex;
  align-items: center;
  gap: 0.4375rem;
  padding: 0.3125rem 0.625rem;
  border: 1px solid rgba(234, 243, 255, 0.16);
  border-radius: 999px;
  background: rgba(6, 12, 20, 0.5);
  font: 500 0.625rem/1 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.1em;
  text-transform: uppercase;
  color: rgba(234, 243, 255, 0.62);
  cursor: pointer;
  pointer-events: auto;
  transition: border-color 160ms ease, color 160ms ease;
}

.dock-magnify-toggle::before {
  content: "";
  width: 0.3125rem;
  height: 0.3125rem;
  border-radius: 50%;
  background: rgba(234, 243, 255, 0.25);
}

.dock-magnify-toggle[aria-pressed="true"] {
  border-color: rgba(158, 205, 255, 0.45);
  color: rgba(234, 243, 255, 0.88);
}

.dock-magnify-toggle[aria-pressed="true"]::before {
  background: #9ecdff;
  box-shadow: 0 0 8px rgba(158, 205, 255, 0.85);
}

.dock-magnify-toggle:focus-visible {
  outline: 2px solid rgba(158, 205, 255, 0.8);
  outline-offset: 3px;
}

/*
 * The real dock. One button per icon, laid over the tiles the canvas draws and moved by the
 * solver, so the focus ring rides the bump instead of sitting where the icon used to be.
 * `pointer-events: none` keeps the press on the shelf, which owns the capture; focus still
 * lands here, so Tab and the arrows reach the same eight buttons the pointer does, and a
 * click on the shelf is routed to whichever of them is under it.
 */
.dock-magnify-apps {
  position: absolute;
  inset: 0;
  pointer-events: none;
}

.dock-magnify-app {
  position: absolute;
  top: 0;
  left: 0;
  width: 2rem;
  height: 2rem;
  padding: 0;
  border: 0;
  border-radius: 0.5rem;
  background: none;
  pointer-events: none;
  opacity: 0;
  will-change: transform;
}

.dock-magnify-app:focus-visible {
  outline: 2px solid rgba(158, 205, 255, 0.85);
  outline-offset: 3px;
}

/* The name is the button's whole accessible content — the mark itself is painted on the
   canvas, because it rides a surface the DOM has no way to bend. */
.dock-magnify-app-name {
  position: absolute;
  width: 1px;
  height: 1px;
  margin: -1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}

/* The dock label, placed above the magnified icon by the solver and faded by the load
   itself, so it arrives with the bump rather than on a timer of its own. */
.dock-magnify-tip {
  position: absolute;
  top: 0;
  left: 0;
  margin: 0;
  padding: 0.25rem 0.5rem;
  border: 1px solid rgba(255, 255, 255, 0.1);
  border-radius: 0.375rem;
  background: rgba(7, 13, 21, 0.85);
  font-size: 0.75rem;
  font-weight: 500;
  line-height: 1;
  white-space: nowrap;
  pointer-events: none;
  opacity: 0;
  will-change: transform, opacity;
}

.dock-magnify-hint {
  margin: 0.9375rem 0 0;
  font: 500 0.6875rem/1.5 ui-monospace, "SFMono-Regular", Menlo, monospace;
  letter-spacing: 0.07em;
  text-transform: uppercase;
  text-align: center;
  color: rgba(234, 243, 255, 0.3);
  pointer-events: none;
}

/* With the loop stopped the load is placed at its target and the beam is solved there in one
   step, so the shape is the same shape — what is gone is the travel to it. Hovering, the
   arrow keys and Enter all still work, and the undershoot is still on screen. */
@media (prefers-reduced-motion: reduce) {
  .dock-magnify-toggle {
    transition: none;
  }
}

/*
 * The card variant: the 298x240 catalogue frame, at that real size and never scaled.
 * Nothing about the shelf is restated here. `restY` is `height − FOOT` under a clamp and
 * every other length — pitch, characteristic length, lift, tile — is a multiple of the icon
 * pitch, which is `plateW / 8.6`. So a 278x220 card is the same beam with the same L/pitch
 * ratio, the same zero crossing at 1.65 pitches and the same trough at 2.20. What changes
 * here is the room around it.
 */
.dock-magnify-stage[data-compact='true'] {
  min-height: 0;
  height: 100%;
  padding: 0.625rem;
  /* The card frame rounds and clips already. */
  border-radius: 0;
}

.dock-magnify-stage[data-compact='true'] .dock-magnify-card {
  width: 100%;
  height: 100%;
}

/* A full-bleed surface that claims every touch traps the page inside a scrolling grid.
   `pan-y` hands the vertical gesture back to the document; the load follows a hover, which
   arrives either way. */
.dock-magnify-stage[data-compact='true'] .dock-magnify-well {
  touch-action: pan-y;
}

/* In from the corners, so the head and the switch clear the shelf's headroom on a card
   that is 60px shorter. */
.dock-magnify-stage[data-compact='true'] .dock-magnify-head {
  top: 0.75rem;
  left: 0.875rem;
}

.dock-magnify-stage[data-compact='true'] .dock-magnify-read {
  font-size: 1.125rem;
}

.dock-magnify-stage[data-compact='true'] .dock-magnify-toggle {
  top: 0.75rem;
  right: 0.75rem;
  gap: 0.375rem;
  padding: 0.25rem 0.5rem;
}

/* It sits below the card, and the card's own title says the same thing. */
.dock-magnify-stage[data-compact='true'] .dock-magnify-hint {
  display: none;
}

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