# Spotlight Grid — Technical Details Deep-dive into the grid-level pointer architecture, the inset-shadow glow, the corner-gap behaviour, and the SSR-safe data generator. --- ## 1. Overview A 3 × 3 grid of dark "ticker" cards on a near-black, deep-navy stage. At rest they're faint dark-blue rounded squares. As the cursor moves over the grid, every card lights up based on its proximity to the cursor: - The card under the cursor lights up its **inner edge nearest the cursor**, with light pooling inward from that edge through the card body. - Neighbouring cards glow more softly along the *same* edge — whichever is closest to the cursor — and quickly fade out further away. - **When the cursor sits in the gap between four cards, all four light up the corner that meets at that gap.** Each card's "nearest edge" becomes its corner, so the four glowing corners pool together in the gap. The architecture is the interesting part: - **A single `pointermove` listener** lives on the grid container — not on each card. (See *§ 3* for why per-card listeners can't do this.) - **Three CSS variables per card (`--sx`, `--sy`, `--glow`)** carry an inset box-shadow offset (in px) and a proximity-derived opacity. They're written straight to each card's DOM node — no React state, no re-renders. - A single child span uses those variables in a layered `inset box-shadow` plus `opacity: var(--glow, 0)`, so the compositor repaints; React doesn't. ``` SpotlightGrid (forced-dark stage) └── grid container — single pointer listener (the crux) └── GlowCard × 9 ├── ref handed back to the grid for measuring + writing vars ├── span.glow (inset box-shadow with offsets var(--sx, --sy); │ opacity: var(--glow)) └── span.labels ($X.XB vol vertical + ▲/▼ TICKER) ``` --- ## 2. File map | File | Role | | --- | --- | | `spotlight-grid.tsx` | Forced-dark stage + grid container. Owns the pointer handlers and the mount fade. | | `glow-card.tsx` | One card. Resting surface + inset-shadow glow span + labels. Listens to nothing. | | `use-grid-glow.ts` | The crux. One listener, iterates 9 cards per move, writes CSS variables. | | `config.ts` | Grid size, colors, proximity radius, shadow reach, transition timing. | | `data.ts` | `SpotlightCell` type, ticker pool, seeded 9-cell generator. | | `index.ts` | `export { SpotlightGrid }`. | --- ## 3. Why grid-level, not per-card The naïve approach is "give each card its own `onPointerMove`." It fails in a very visible way: `pointermove` fires only on the element under the cursor. If the cursor is **between** four cards — over the gap — none of those four cards receive the event, so none of their inner edges light up. The cursor effectively "disappears" until it moves back onto a card. A single listener on the grid container catches every move, including ones over the gaps. Per move, the hook iterates the 9 cards and, for each one, writes: - `--sx`, `--sy` → inset-shadow offset in **pixels**, computed as `(cardCentre − cursor) × SHADOW_REACH`. An inset shadow paints colour on the inner edge *opposite* its offset direction — so a positive `--sy` (cursor above card centre) shifts the shadow downward and exposes the *top* inner edge to the glow colour. Whichever side the cursor is on, that side lights up. - `--glow` → `0…1` opacity, derived from the cursor's distance to that card's bounding box. `1` inside the card, falling off with `1 − (distance / GLOW_PROXIMITY_PX)²` outside. ```ts const cx = (rect.left + rect.right) / 2; // card centre x const cy = (rect.top + rect.bottom) / 2; // card centre y const sx = (cx - cursorX) * SHADOW_REACH; // shadow offset (px) const sy = (cy - cursorY) * SHADOW_REACH; const dx = Math.max(0, rect.left - cursorX, cursorX - rect.right); const dy = Math.max(0, rect.top - cursorY, cursorY - rect.bottom); const d2 = dx*dx + dy*dy; const glow = d2 >= prox2 ? 0 : 1 - d2 / prox2; ``` The `dx = Math.max(0, rect.left - x, x - rect.right)` form is the distance from the cursor to the card's bounding box along the X axis: `0` when the cursor is between `rect.left` and `rect.right`, otherwise the positive distance to whichever side is closer. Same logic on Y. The square of the Euclidean distance feeds the quadratic falloff — quadratic because a concave-down curve keeps the glow strong until the cursor is well clear of an edge (so cards across a small gap stay bright together) and only drops sharply past that. --- ## 4. Why this is still cheap - One `pointermove` listener, fired only when the pointer is over the grid. Per move we do 9 × (one arithmetic block + three `setProperty` calls). At a worst-case 120Hz that's ~3,240 `setProperty` calls per second — negligible. - Zero React renders. The hook reads / writes refs and DOM attributes only. - Per-card rect caching: `getBoundingClientRect()` is read once on `pointerenter` and on `window` resize. Reading it on every move would trigger layout flushes — instead we cache once per enter. - An inset box-shadow is GPU-friendly to repaint as its offset changes (the browser invalidates a single bitmap of the shadow); the only thing transitioning is `opacity` on `--glow`, which is one of the cheapest property transitions. Net effect: dragging the cursor across the grid costs roughly one struct update + 27 `setProperty` calls per frame, with no layout reads and no React tree walk. --- ## 5. The hook (`use-grid-glow.ts`) ### Public surface ```ts type GridGlow = { setNodes: ((node: HTMLElement | null) => void)[]; // stable, per index onPointerEnter: (e: ReactPointerEvent) => void; onPointerMove: (e: ReactPointerEvent) => void; onPointerLeave: () => void; }; function useGridGlow(cellCount: number): GridGlow; ``` `setNodes[i]` is a **stable callback ref** for card index `i`, computed once via `useMemo` so re-renders don't detach and re-attach the ref. The card just spreads it as `ref={setNode}`. ### Lifecycle ```ts const cardsRef = useRef<(HTMLElement | null)[]>([]); // populated by setNodes[i] const rectsRef = useRef<(DOMRect | null)[]>([]); // cached on enter / resize const cleanupRef = useRef(null); // deferred-removal timer onPointerEnter(e) → cancelCleanup(); measureAll(); update(e.clientX, e.clientY); onPointerMove(e) → update(e.clientX, e.clientY); onPointerLeave() → setGlow0OnEveryCard(); cleanupRef = setTimeout(removeInlineSxSyGlow, 320); ``` `measureAll` iterates the cards array and stores each `getBoundingClientRect()`. We measure on `pointerenter` (covers initial entry and re-entries) and on `window` resize (covers viewport changes while the pointer is parked over the grid). `update` does the per-card arithmetic from *§ 3* and three `setProperty` calls per card. `onPointerLeave` is **two-phase** and that's the whole point — see *§ 5a*. ### 5a. Smoothing the glow (CSS `@property`, not JS) `setProperty('--sx', '40px')` on every `pointermove` *snaps* the inset-shadow offset to each new value — the lit edge jumps on fast cursor moves and looks distinctly mechanical even on slow ones. We don't want to add a JS rAF lerp (constant frame work for 9 cards × 2 dimensions), so the fix lives in the stylesheet. **Step 1: register the variables as typed custom properties** in `app/globals.css`: ```css @property --sx { syntax: ""; inherits: true; initial-value: 0px; } @property --sy { syntax: ""; inherits: true; initial-value: 0px; } ``` A typed `syntax` is what makes the property *interpolatable* — without it, CSS treats the value as an opaque string and snaps. `inherits: true` is mandatory: the hook writes the variables on the card (the only element it has a ref to), and the glow span (child of the card) reads `var(--sx)`/`var(--sy)` via inheritance. **Step 2: transition the property on the card** in `glow-card.tsx`: ```ts restingStyle.transition = ` --sx ${POINTER_FOLLOW_MS}ms linear, --sy ${POINTER_FOLLOW_MS}ms linear, box-shadow 300ms cubic-bezier(0.4, 0, 0.2, 1) `; ``` `POINTER_FOLLOW_MS = 110` is the sweet spot: short enough to feel responsive (~7 frames at 60fps), long enough to perceive as smooth. Successive `setProperty` writes stack — each new target restarts the transition from wherever the previous one left off — so continuous moves read as one trailing follow rather than discrete jumps. The browser stops re-rendering once the value converges (no perpetual rAF cost). Net effect: every `pointermove` does the same three `setProperty` calls as before, but the visible glow now glides between them. The `box-shadow 300ms` slot is kept here too (replacing what Tailwind's `transition-shadow` did) so the hover ring brightening still eases in. Note that the *glow* span's box-shadow re-renders every frame as `--sx`/`--sy` interpolate — but that's free, because that's the inset shadow itself transitioning via the cascading `@property` value, not a separate `transition: box-shadow` on the span. ### 5b. Two-phase leave (the "no janky reset" trick) CSS custom properties don't transition between values by default — so a naïve `onPointerLeave` that does `removeProperty('--sx' | '--sy' | '--glow')` snaps the shadow offset back to `(0px, 0px)` *instantly* while `opacity` is still mid-transition. You see the lit edge teleport from wherever the cursor was to a centred glow at all edges, then fade out. Janky. Fix: 1. **Phase 1 — immediate:** set `--glow` to `0` on every card. `--sx` / `--sy` are left alone, so the inset shadow stays put. The CSS `transition: opacity 320ms` on the glow span fades it out in place from wherever the cursor last was. 2. **Phase 2 — deferred (`GLOW_TRANSITION_MS` later):** the span is now fully transparent. `removeProperty` for all three variables. The removal is invisible because nothing is showing, and any CSS fallback (`focus-visible:[--glow:1]`) can take over with the default centred (zero-offset) glow from this point on. `pointerenter` cancels the pending cleanup timer (`cancelCleanup`) before it fires `update`, so a quick out-and-back inside 320ms doesn't reset the just-written inline values out from under us. Both the on-unmount cleanup (`useEffect(() => cancelCleanup, ...)`) and the re-enter path share the same cancellation, so there's no zombie timer to leak. ### Tuning ```ts GLOW_PROXIMITY_PX = 140; // how far past a card's edge the cursor can sit // and still light it up. ~70% of card width is // a good range for our 3 × 3. ``` The quadratic falloff `1 − (d / prox)²` has these inflection points: | distance / proximity | glow | | --- | --- | | 0 | 1.00 | | 0.25 | 0.94 | | 0.50 | 0.75 | | 0.71 | 0.50 | | 1.00 | 0.00 | So at half the proximity radius the glow is still 0.75 — cards across a small gap stay bright together. Past the proximity radius the value clamps to 0. --- ## 6. The card (`glow-card.tsx`) ### Stacking order 1. The card itself — `relative aspect-square overflow-hidden`, dark gradient background, 1px ring, `borderRadius: 36px` (≈12% of card width). Listens to nothing. 2. `span.glow` — `absolute inset-0`, `pointer-events-none`, the layered `inset box-shadow`, `opacity: var(--glow, 0)`. 3. `span.labels` — `pointer-events-none`, vertical volume and ticker. `overflow-hidden` is load-bearing: it clips the shadow inside the rounded square. Without it the inset shadow would still render inside the span, but the rounded corners of the parent wouldn't mask the shadow into the same shape. ### Glow span — layered `inset box-shadow` Each card carries its own `palette: { core, mid, outer, rim }` from `SPOTLIGHT_PALETTES`. The glow uses two of those (`mid` for the wide halo, `core` for the bright edge highlight): ```ts boxShadow: ` inset var(--sx, 0px) var(--sy, 0px) 110px -15px ${mid}, inset calc(var(--sx, 0px) * 0.35) calc(var(--sy, 0px) * 0.35) 32px -10px ${core} `, borderRadius: 'inherit', opacity: 'var(--glow, 0)', transition: 'opacity 320ms cubic-bezier(0.16, 1, 0.3, 1)'; ``` **How the offset lights the cursor-side edge.** For an `inset` box-shadow, the shadow colour paints the part of the inside that *isn't* covered by the offset shadow rectangle. So a positive `--sy` (shadow shifted *down*) leaves the *top* uncovered → top edge glows. The hook computes `--sx`, `--sy` as `(cardCentre − cursor) × SHADOW_REACH`: cursor above the centre → positive `--sy` → top lights up. Cursor to the right of the centre → negative `--sx` → right side lights up. And so on. The math falls out naturally. **Why two layers, not one.** A single inset shadow can give you either a wide soft halo *or* a tight bright edge, but not both — the `blur` / `spread` knobs trade between those looks. Stacking a wide saturated `mid`-coloured shadow under a tight near-white `core`-coloured shadow gives the reference's two-tone look: a luminous edge plus a deeper halo that pools inward. The tight shadow uses the same `--sx` / `--sy` scaled down to `~0.35×` so its bright peak sits closer to the cursor-side edge than the wide halo does, which is what produces the "luminous wire then bloom" gradient you see in the reference. **Why box-shadow, not a radial gradient.** A `radial-gradient` centred on the cursor reads as "a bright dot painted on the card" — fine for some looks but it pulls the eye to a *point* rather than to an *edge*. The reference clearly shows light emanating from an edge (specifically the inner edge nearest the cursor) and fading inward across the card body. `inset` box-shadow is the CSS feature designed for "light coming from an inner edge" — the offset chooses the edge, the blur softens the falloff into the body, the spread controls how far the light reaches. It maps directly to the visual we want, with no rim layer or `mask-composite` ring needed on top. **Why `overflow-hidden` on the parent.** The inset shadow paints inside the rounded card, but the *span* it lives on is rectangular. Without `overflow-hidden` on the card, the span's box-shadow would poke out beyond the card's rounded corners. `borderRadius: 'inherit'` on the span picks up the parent's curve, and the parent's `overflow-hidden` does the final clip. The 9-entry palette array assigns one hue per card (blue, violet, fuchsia, cyan, emerald, amber, rose, indigo, teal) — so the 3 × 3 reads as a multi-coloured rainbow rather than nine clones of the same blue. The shadow shape, blur, and spread stay identical across hues — only the colours change. When the cursor sits in a neighbouring gap, the hook writes large `--sx`/`--sy` values (the cursor is far from the card centre), so the shadow is offset deep beyond the far side of the card — only a thin slice of the cursor-side edge is exposed, which paints as a soft luminous strip on that edge. ### Focus `focus-visible:[--glow:1]` on the card body keeps keyboard navigation working: when the pointer isn't over the grid (no inline `--glow` overriding it), focusing a card sets `--glow: 1` from CSS, the inline `--sx`/`--sy` are absent so they fall back to their `0px` initial values, and the shadow renders with zero offset — a uniform soft glow at all inner edges. Once the pointer re-enters the grid, the hook's inline values win until the next `pointerleave` removes them. ### Labels Always visible (the 3 × 3 leaves enough room at every breakpoint). The vertical volume label uses `rotate-90` around `origin-top-left` so it sits along the left edge exactly like the screenshot. Two positioning gotchas: 1. Rotation around the top-left corner pushes the element's original height into leftward overflow. To keep the visible strip inside the card, the pivot is offset inward via `left-7` (28px) — roughly the line-height of the rotated text. 2. Tailwind composes `translate` *before* `rotate` in the `transform` shorthand, so adding `translate-x-full` to "shift the rotated text right" does the wrong thing. Use the inward offset on `left` instead. Ticker direction is a `▲` / `▼` glyph (Unicode `\u25B2` / `\u25BC`) — no icon library needed. --- ## 7. The grid (`spotlight-grid.tsx`) The inner grid `

` is the pointer target. It owns `onPointerEnter` / `onPointerMove` / `onPointerLeave` from `useGridGlow`, plus `role="presentation"` because the cards themselves are `aria-hidden`. Its bounding box covers cards + gaps (no padding on the inner div), so the pointer handlers see every move including ones over the gaps. ```tsx const { setNodes, onPointerEnter, onPointerMove, onPointerLeave } = useGridGlow(CELL_COUNT);

{spotlightCells.map((cell, index) => ( ))}

``` The stage background is a deep-navy radial: ``` radial-gradient(120% 120% at 50% 0%, #0d1530 0%, #05080f 55%, #03060c 100%) ``` A second, very faint highlight at the top hints at an off-screen light source — sells the "trading floor at night" feel from the screenshot. **Forced dark stage** is intentional. The blue bloom only reads on a near-black backdrop; a theme-adaptive light version would either look flat or require a completely different palette. This is the only experiment in the lab that doesn't track the page theme. --- ## 8. SSR-safe data (`data.ts`) The 9 cells need a deterministic generator: `Math.random()` would produce different markup on the server and the client and trip a React 19 hydration warning. The fix is a tiny `mulberry32` PRNG with a fixed seed: ```ts function mulberry32(seed: number) { let t = seed >>> 0; return () => { t = (t + 0x6d2b79f5) >>> 0; let r = t; r = Math.imul(r ^ (r >>> 15), r | 1); r ^= r + Math.imul(r ^ (r >>> 7), r | 61); return ((r ^ (r >>> 14)) >>> 0) / 4294967296; }; } ``` Used once at module scope to compute the `spotlightCells` array — both server and client read the same constant. Tickers come from a fixed 16-element pool; volume is `$X.XB vol` with one decimal; direction is `up` if `rand() > 0.45` so the grid skews slightly up (matches the screenshot's mix). --- ## 9. Accessibility - The grid is decorative — the inner grid is `role="presentation"`, and each card carries `aria-hidden="true"`. - Cards are `tabIndex={0}` so the bloom is reachable by keyboard (`focus-visible:[--glow:1]`); the hotspot defaults to centre, so a focused card looks like the screenshot's centred hover. Once the pointer re-enters, the hook's inline values override the CSS rule until the next `pointerleave`. - The hook only writes CSS variables — there's no animation that needs a reduced-motion gate. The 320ms opacity transition on the glow span stays. --- ## 10. Tuning knobs | Want to… | Change | | --- | --- | | Tighter / looser grid | `GRID_COLS` / `GRID_ROWS` (then `CELL_COUNT` recomputes) | | Smaller / bigger cards | the stage `max-w-…` at the route, or `gap-…` in the grid | | Overall subtler / more vivid glow | `GLOW_INTENSITY` (0.5 default; 0.3 = barely-there, 1 = full palette alpha — cards turn into tiles of colour) | | Brighter / dimmer edge highlight | `core` alpha in each palette (used by the tight shadow layer) | | Brighter / dimmer halo | `mid` alpha in each palette (used by the wide shadow layer) | | Wider / softer halo | first inset shadow's `blur` (30px default) | | Tighter / broader bright edge | second inset shadow's `blur` (12px default) + its offset multiplier (`0.35`) | | More / less aggressive directional offset | `SHADOW_REACH` (0.4 default; 0.25 = very subtle, 0.7 = pronounced) | | Different per-card hues | the palette objects in `SPOTLIGHT_PALETTES` | | Shuffle hue order across the grid | rotate or permute `SPOTLIGHT_PALETTES` | | Faster / slower glow fade | `GLOW_TRANSITION_MS` | | Larger / smaller "halo" around cursor (proximity reach) | `GLOW_PROXIMITY_PX` (140 default) | | Snappier / floatier shadow follow | `POINTER_FOLLOW_MS` (110 default; 60–180 is the useful range) | | Different ticker mix | the `TICKERS` array and `rand()` threshold for direction | | Reproducible alternate layout | the seed passed to `mulberry32` (currently `0xa10c_b105`) | --- ## 11. Gotchas (the ones that cost real time) 1. **Per-card pointer listeners don't fire over the gaps.** Single listener on the grid container is the only way to light up cards the cursor isn't directly on. 2. **`overflow-hidden` on the card.** Without it, the inset shadow on the rectangular glow span pokes past the card's rounded corners. `borderRadius: 'inherit'` on the span + `overflow-hidden` on the parent does the final clip. 3. **Hydration mismatch.** Seed your PRNG — `Math.random()` will diverge between server and client and React 19 will warn (and re-render). 4. **Cache rects on `pointerenter`, not every move.** `getBoundingClientRect()` triggers a layout flush — reading it on every move kills the perf win of "no React renders." Cache once per enter, re-measure on resize. 5. **Two-phase leave or you get a janky reset.** Calling `removeProperty('--sx' | '--sy' | '--glow')` all at once on `pointerleave` snaps the shadow offset to `(0px, 0px)` *while* the opacity is still fading — so the lit edge visibly teleports to a centred uniform glow before disappearing. Set `--glow: 0` immediately, leave `--sx` / `--sy` parked, and `removeProperty` everything in a `setTimeout(GLOW_TRANSITION_MS)`. Cancel the timer on `pointerenter` so a fast in-out-in doesn't fight itself. 6. **Stable per-index ref callbacks.** Computing `(node) => { cards.current[i] = node; }` inline on every render detaches and re-attaches the ref every render — measure on enter and the rects array is stale. Pre-compute the array of callbacks once with `useMemo`. 7. **Don't put `--glow` on a Motion `style` prop.** Motion will treat it as an animated value and try to interpolate. Plain CSS transition on the variable is what you want. 8. **`@property` requires `inherits: true` here.** The hook writes the vars on the card, but the glow span is a child — it reads the value via inheritance. With `inherits: false` the descendant would resolve to the `initial-value` independent of the parent and the smoothness machinery would silently no-op. 9. **The inset shadow's offset direction is opposite to its lit edge.** Positive offset shifts the shadow *box* in that direction, exposing the *opposite* inner edge to the shadow colour. So to light up the side closest to the cursor, use `(centre − cursor)` as the offset, not `(cursor − centre)`. Easy sign mistake to make. 10. **Offsets must be lengths, not percentages.** `box-shadow` offset accepts `` but *not* ``. So `--sx` / `--sy` have to be registered as `` via `@property` and written in pixels (the hook computes them from the cached `getBoundingClientRect()`).