docs/refractor-visual-spec.md

@@ -0,0 +1,243 @@
+# Refractor Tier Visual Spec — Cherry-Pick Reference
+
+Approved effects from `wip/refractor-card-art` mockup (`docs/refractor-tier-mockup.html`).
+This document is the handoff reference for applying these visuals to the production card renderer.
+
+---
+
+## 1. Tier Diamond Indicator
+
+A 4-quadrant diamond icon centered at the intersection of the left/right column headers.
+Replaces all per-tier emoji badges.
+
+### Positioning & Structure
+
+- **Position**: `left: 600px; top: 78.5px` (centered between column header top/bottom borders)
+- **Size**: `19px × 19px` (tips fit within header row bounds)
+- **Rotation**: `transform: translate(-50%, -50%) rotate(45deg)`
+- **Layout**: CSS Grid `2×2`, `gap: 2px`
+- **Background (gap color)**: `rgba(0,0,0,0.75)` with `border-radius: 2px`
+- **Base shadow**: `0 0 0 1.5px rgba(0,0,0,0.7), 0 2px 5px rgba(0,0,0,0.5)`
+- **z-index**: 20
+
+### Fill Order (Baseball Base Path)
+
+Quadrants fill progressively following the base path: **1st → 2nd → 3rd → Home**.
+
+| Tier | Quadrants Filled | Visual |
+|------|-----------------|--------|
+| T0 (Base) | 0 — no diamond shown | — |
+| T1 | 1st base (right) | ◇ with right quadrant filled |
+| T2 | 1st + 2nd (right + top) | ◇ with two quadrants |
+| T3 | 1st + 2nd + 3rd (right + top + left) | ◇ with three quadrants |
+| T4 | All 4 (full diamond) | ◆ fully filled |
+
+### Grid-to-Visual Mapping (after 45° rotation)
+
+The CSS grid positions map to visual positions as follows:
+
+| Grid Slot | Visual Position | Base |
+|-----------|----------------|------|
+| div 1 (top-left) | TOP | 2nd base |
+| div 2 (top-right) | RIGHT | 1st base |
+| div 3 (bottom-left) | LEFT | 3rd base |
+| div 4 (bottom-right) | BOTTOM | Home plate |
+
+**Render order in HTML**: `[2nd, 1st, 3rd, home]` (matches grid slot order above).
+
+### Quadrant Fill Styling
+
+Unfilled quads: `background: rgba(0,0,0,0.3)` (dark placeholder).
+
+Filled quads use a gradient + inset shadow for depth:
+
+```css
+/* Standard filled quad */
+.diamond-quad.filled {
+  background: linear-gradient(135deg, {highlight} 0%, {color} 50%, {color-darkened-75%} 100%);
+  box-shadow:
+    inset 0 1px 2px rgba(255,255,255,0.45),
+    inset 0 -1px 2px rgba(0,0,0,0.35),
+    inset 1px 0 2px rgba(255,255,255,0.15);
+}
+```
+
+### Approved Effect: Metallic Sheen + Pulse Glow
+
+The approved diamond effect combines metallic inset highlights with an animated glow pulse.
+
+**Metallic gradient** (replaces standard gradient on filled quads):
+```css
+background: linear-gradient(135deg,
+  rgba(255,255,255,0.9) 0%,
+  {highlight} 20%,
+  {color} 50%,
+  {color-darkened-60%} 80%,
+  {highlight} 100%);
+```
+
+**Metallic inset shadows** (boosted highlights):
+```css
+.diamond-quad.metallic.filled {
+  box-shadow:
+    inset 0 1px 3px rgba(255,255,255,0.7),
+    inset 0 -1px 2px rgba(0,0,0,0.5),
+    inset 1px 0 3px rgba(255,255,255,0.3),
+    inset -1px 0 2px rgba(0,0,0,0.2);
+}
+```
+
+**Glow pulse animation** (tight diameter, applied to `.tier-diamond` container):
+```css
+@keyframes diamond-glow-pulse {
+  0%   { box-shadow:
+    0 0 0 1.5px rgba(0,0,0,0.7),
+    0 2px 5px rgba(0,0,0,0.5),
+    0 0 5px 1px var(--diamond-glow-color);
+  }
+  50%  { box-shadow:
+    0 0 0 1.5px rgba(0,0,0,0.5),
+    0 2px 4px rgba(0,0,0,0.3),
+    0 0 8px 3px var(--diamond-glow-color),
+    0 0 14px 5px color-mix(in srgb, var(--diamond-glow-color) 25%, transparent);
+  }
+  100% { /* same as 0% */ }
+}
+
+.tier-diamond.diamond-glow {
+  animation: diamond-glow-pulse 2s ease-in-out infinite;
+}
+```
+
+Metallic effect **automatically** enables the glow pulse (no separate toggle needed in production).
+
+---
+
+## 2. Tier Diamond Colors
+
+| Tier | Color (body) | Highlight (bright edge) | Glow Color | Intent |
+|------|-------------|------------------------|------------|--------|
+| T1 | `#d46a1a` | `#f0a050` | `#d46a1a` | Orange |
+| T2 | `#b82020` | `#e85050` | `#b82020` | Red |
+| T3 | `#7b2d8e` | `#b860d0` | `#7b2d8e` | Purple |
+| T4 | `#1a6af0` | `#60b0ff` | `#1a6af0` | Blue flame |
+
+Progression: warm → hot → regal → transcendent.
+
+---
+
+## 3. T3 Gold Shimmer Sweep (Header Animation)
+
+A single narrow gold stripe sweeps left-to-right across the card header.
+
+- **Duration**: 2.5s loop, ease-in-out
+- **Gradient**: 105° diagonal, peak opacity 0.38
+- **Key colors**: `rgba(255,240,140,0.18)` → `rgba(255,220,80,0.38)` → `rgba(255,200,60,0.30)`
+- **Scope**: Header only (`.card-header` has `overflow: hidden`)
+- **z-index**: 5
+
+```css
+@keyframes t3-shimmer {
+  0%   { transform: translateX(-130%); }
+  100% { transform: translateX(230%); }
+}
+```
+
+### Playwright APNG Capture
+
+For static card rendering, the shimmer position is driven by `--anim-progress` (0.0–1.0) instead of CSS animation. Playwright captures 8 frames to produce an APNG.
+
+---
+
+## 4. T4 Superfractor — Layered Animation System
+
+T4 stacks four independent effect layers for a premium look qualitatively different from T3.
+
+### Layer 1: Prismatic Rainbow Header Sweep
+
+- Seamless loop using a 200%-wide element with two mirrored rainbow bands
+- `translateX(-50%)` over 6s linear = continuous wrap
+- Colors: red → gold → green → blue → violet → pink, all at ~0.28 opacity
+- z-index: 1 (behind header text at z-index: 2)
+- Header children get `position: relative; z-index: 2` to sit above rainbow
+
+### Layer 2+3: Gold/Teal Dual Glow Pulse
+
+- Applied via `::before` on the card element
+- Gold and teal in opposition: when gold brightens, teal dims and vice versa
+- 2s ease-in-out loop
+- Inset box-shadows (`45px 12px` gold, `80px 5px` teal)
+- z-index: 4
+
+```css
+@keyframes t4-dual-pulse {
+  0%   { box-shadow: inset 0 0 45px 12px rgba(201,169,78,0.40),
+                      inset 0 0 80px 5px rgba(45,212,191,0.08); }
+  50%  { box-shadow: inset 0 0 45px 12px rgba(201,169,78,0.08),
+                      inset 0 0 80px 5px rgba(45,212,191,0.38); }
+  100% { /* same as 0% */ }
+}
+```
+
+### Layer 4: Column Bar Shimmer
+
+- White highlight (`rgba(255,255,255,0.28)`) sweeps across each column header bar
+- 1.6s ease-in-out loop, staggered by -0.25s per bar for a ripple effect
+- 6 bars total (3 left group, 3 right group)
+
+---
+
+## 5. T4b Variant — Full-Card Rainbow
+
+Same as T4 but the prismatic rainbow covers the entire card height (not just header).
+
+- Applied via `::after` on `.pd-card` instead of `.card-header::after`
+- Slightly reduced opacity (0.18–0.22 vs 0.28–0.32)
+- z-index: 6 (above content)
+- Dual glow pulse uses a separate `.dual-pulse-overlay` div at 2.8s (slightly slower)
+- Column bar shimmer identical to T4
+
+**Status**: Experimental variant. May or may not ship — kept as an option.
+
+---
+
+## 6. Corner Accents (T4 Only)
+
+L-shaped corner brackets on all four card corners.
+
+- **Color**: `#c9a94e` (gold)
+- **Size**: 35px arms, 3px thick
+- **Implementation**: Four absolutely-positioned divs with two-sided borders each
+- **z-index**: 6
+
+---
+
+## 7. Implementation Notes for Production
+
+### What to port
+
+1. **Diamond indicator CSS** (`.tier-diamond`, `.diamond-quad`, keyframes) → add to card template stylesheet
+2. **Diamond HTML generation** → add to Playwright card renderer (4 divs in a grid)
+3. **Metallic + glow effect** → always apply metallic class + glow animation to filled diamonds
+4. **T3 shimmer** → APNG capture with `--anim-progress` variable (8 frames)
+5. **T4 layered effects** → APNG capture with `--anim-progress` driving all 4 layers
+6. **Diamond colors** → store in tier config or derive from tier level
+7. **Corner accents** → T4 only, simple border divs
+
+### What NOT to port
+
+- The mockup control panel UI (sliders, dropdowns, color pickers)
+- The `diamondEffect` dropdown with 5 options (we chose metallic — hardcode it)
+- The separate `diamondGlow` toggle (metallic always includes glow)
+- Border preset / header type controls (these are already in production tier configs)
+- T4b full-card rainbow (unless explicitly promoted later)
+
+### Database/API considerations
+
+The diamond fill count is already derivable from the tier level — no new database fields needed:
+- `refractor_tier = 1` → `diamondFill = 1`, color = orange
+- `refractor_tier = 2` → `diamondFill = 2`, color = red
+- `refractor_tier = 3` → `diamondFill = 3`, color = purple
+- `refractor_tier = 4` → `diamondFill = 4`, color = blue-flame
+
+Diamond colors are purely visual (CSS) — they don't need to be stored.