webgl-card-effects

name	webgl-card-effects
promoted_to	distinctive-frontend-design
description	Standalone WebGL fragment shaders for card visual effects: holographic foil, shimmer, rarity glow.
agent	typescript-frontend-engineer
user-invocable	false
command	/card-effects
allowed-tools	["Read","Write","Bash","Grep","Glob","Edit"]
routing	{"triggers":["card effects","holographic","foil effect","card shimmer","card glow","shader card","WebGL card","rarity effects","Balatro effect","card visual effects"],"pairs_with":["typescript-frontend-engineer","ui-design-engineer"],"complexity":"Medium","category":"frontend"}

WebGL Card Effects Skill

Overview

This skill adds GPU-accelerated visual effects to React card components using standalone WebGL2 fragment shaders — no Three.js, no R3F, no external library required. It targets deckbuilder games and card UIs where rarity tiers should feel visually distinct, not just differentiated by a CSS box-shadow value.

Scope: Holographic foil overlays, metallic shimmer bands, rarity-driven energy pulses, and interactive tilt-shine effects mounted directly on React card components. The canonical target is FramedCard.tsx in a React 19 / Vite / Tailwind project with a rarity system (starter → common → uncommon → rare → legendary).

Not in scope: 3D transformations, texture loading, post-processing pipelines, or any Three.js scene management. For those, use threejs-builder.

Key constraint: Browsers cap WebGL contexts at roughly 8–16 total per page. This skill uses a single shared WebGL2 context with blit-to-2D-canvas output per card, avoiding the per-card context problem entirely. See references/shader-integration-react.md for the full singleton pattern.

---

Instructions

Phase 1: ASSESS

Goal: Understand which effects are needed and confirm the card component structure before writing any code.

Step 1: Read the card component

Read these files before writing anything:

• src/components/cards/FramedCard.tsx — component structure, hover state, rarity prop flow
• src/components/cards/cardStyles.ts — CARD_SIZE_CONFIG for pixel dimensions, rarity string values

Confirm:

• How rarity reaches the component (prop name, TypeScript type, exact string values)
• Whether isHovered state already exists in the component
• Which sizes are rendered in contexts that justify shader cost (xl/lg only — xs/sm are too small)
• Whether showShine / card-shine CSS exists and needs coordination

Step 2: Select effect tier per rarity

Rarity	WebGL?	Effect
starter / common	No	CSS shimmer only — no WebGL overhead
uncommon	Yes (subtle)	Metallic band shimmer, very low opacity
rare	Yes (medium)	Moving shimmer + blue hue shift + edge pulse
legendary	Yes (full)	Rainbow holographic foil, mouse-reactive tilt

Step 3: Confirm React version

Check package.json for the React version. This skill assumes React 19 (ref as prop, no forwardRef). If the project uses React 18, canvas refs require useRef + standard ref passing.

Gate: Rarity values confirmed, CARD_SIZE_CONFIG read, effect tiers decided. Proceed only when this gate passes.

---

Phase 2: BUILD

Goal: Write working GLSL shaders and the WebGL initialization harness.

Load references/card-shader-patterns.md now.

Step 1: Create the shader strings module

Create src/components/cards/effects/cardShaders.ts. This file holds:

• The shared vertex shader (passthrough UV coordinates)
• Three fragment shader strings: SHIMMER_FRAG, RARE_FRAG, LEGENDARY_FRAG
• A rarityToUniform(rarity: string): number mapping function

Every shader must expose this exact uniform interface:

uniform float u_time;        // seconds elapsed, JS wraps at 1000.0
uniform float u_rarity;      // 0.0=starter/common, 0.25=uncommon, 0.5=rare, 1.0=legendary
uniform float u_hover;       // 0.0 to 1.0, lerped by JavaScript each frame
uniform vec2  u_mouse;       // normalized card-space [0,1] mouse position
uniform vec2  u_resolution;  // canvas pixel dimensions (width, height)
uniform float u_upgraded;    // 0.0 or 1.0 — upgraded cards get slightly more intense effect

Step 2: Create the WebGL harness hook

Create src/components/cards/effects/useCardShader.ts.

Load references/shader-integration-react.md for the full hook source. The hook must:

• Use the shared WebGL2 context singleton (not create a new context per card)
• Accept { rarity, isHovered, isUpgraded, enabled } as input
• Return a RefObject<HTMLCanvasElement> that the component attaches to the canvas element
• Pause the animation loop when the card is off-screen (IntersectionObserver)
• Run at 30fps maximum via delta-time throttle
• Clean up the RAF loop and observer on unmount

Step 3: Shader construction for each tier

Load references/balatro-shader-breakdown.md for the legendary holographic shader GLSL source.

For rare: use the shimmer band + hue shift layer from the breakdown, omit the rainbow foil layer.

For uncommon: use only the metallic band pass (single moving highlight), opacity 0.3 maximum.

Gate: Run npx tsc --noEmit. Zero TypeScript errors. Open browser console and verify gl.getShaderInfoLog() returns empty string for all shaders.

---

Phase 3: INTEGRATE

Goal: Mount the canvas overlay on FramedCard.tsx and wire rarity/hover state into the shader uniforms.

Step 1: Derive render decision

Inside FramedCard, after the existing const shouldShine line:

const shouldRenderShader =
  ['uncommon', 'rare', 'legendary'].includes(rarity) &&
  size !== 'xs' &&
  size !== 'sm';

Step 2: Call the hook

const shaderCanvasRef = useCardShader({
  rarity,
  isHovered,
  isUpgraded,
  enabled: shouldRenderShader,
});

Step 3: Add the canvas overlay to JSX

Inside the motion.div return, immediately after the frame <img> element (after z-10):

{shouldRenderShader && (
  <canvas
    ref={shaderCanvasRef}
    className="absolute inset-0 w-full h-full pointer-events-none rounded-lg"
    style={{ zIndex: 15, mixBlendMode: 'screen' }}
  />
)}

mix-blend-mode: screen makes the shader's black background transparent while letting bright holographic colors add onto the card surface.

Step 4: Coordinate with existing CSS shine

The existing card-shine CSS class creates a gradient sweep on hover. It will double-shimmer with the WebGL effect. Suppress it for rarities that have the WebGL shader:

const shineClass =
  showShine && shouldShine && !shouldRenderShader
    ? `card-shine ${...}`
    : '';

Step 5: Verify z-layer stack

From bottom to top inside the card:

• z-0 — artwork container
• z-10 — frame PNG image
• z-15 — shader canvas (new)
• z-20 — text elements (energy orb, name, description, type strip)
• Tooltip renders outside via AnimatePresence portal

Tailwind does not generate z-15 by default. Either add it to tailwind.config or use style={{ zIndex: 15 }} inline (already shown above).

Gate: Cards render correctly at all sizes. Shader canvas is visible on uncommon/rare/legendary. No z-fighting between shader layer and frame image. TypeScript clean.

---

Phase 4: POLISH

Goal: Performance verification, visual tuning, mobile fallback confirmation.

Step 1: Performance audit

Open Chrome DevTools → Performance tab. Record 5 seconds while hovering over a legendary card.

Targets:

• GPU usage: < 5% for a single legendary card
• Frame time: shader must not push game loop below 60fps
• No memory growth across multiple mount/unmount cycles (check Heap in Memory tab)

Step 2: Mobile fallback verification

// In useCardShader.ts — call this once at module load
function supportsWebGL2(): boolean {
  try {
    const canvas = document.createElement('canvas');
    return !!canvas.getContext('webgl2');
  } catch {
    return false;
  }
}

On devices where supportsWebGL2() returns false, the hook returns a null ref and shouldRenderShader must evaluate to false. The existing card-shine CSS handles the fallback. Verify this works by temporarily forcing the function to return false.

Step 3: Visual calibration

• Legendary: Rainbow visible but not garish. Effective opacity 0.65–0.75 over the card. Animation speed: u_time advances at 0.5× real-time (not 1:1 — too fast feels cheap).
• Rare: Blue hue shift + shimmer. Feels premium, not like a cursor glow effect.
• Uncommon: Barely perceptible silver shimmer. If you notice it immediately on a static card, the opacity is too high.
• Mouse tilt: The holographic angle shift should feel like physically tilting a card under light, not like a flashlight following the cursor. Limit the angular response to ±15 degrees of apparent rotation.

Step 4: Test across all rendered sizes

Size	Width	Shader?	Note
xs	80px	No	Too small — no overhead
sm	110px	No	Too small — no overhead
md	140px	Optional	Test legibility first
lg	170px	Yes	Minimum size for full effect
xl	200px	Yes	Primary target — should look best

Gate: All DevTools performance targets met. Mobile fallback verified. Visual quality approved at lg and xl sizes across all three shader tiers.

---

Error Handling

"WebGL: INVALID_OPERATION: useProgram: program not valid"

Shader compilation failed silently. Call gl.getShaderInfoLog(shader) immediately after gl.compileShader(shader). Common causes: GLSL syntax error, wrong #version 300 es directive missing, or a uniform declared but never referenced (GLSL compilers strip unused uniforms — reference them or remove the declaration).

Canvas present but effect invisible

Check mixBlendMode. On very dark card backgrounds, screen blend mode makes dark shader output invisible. For debugging, switch to normal blend mode to see the raw shader output. Also verify the canvas zIndex is above the frame PNG (15 > 10).

Browser console: "Too many active WebGL contexts"

The shared context singleton in useCardShader is not being used — individual hook calls are each creating a new context. Verify the module-level singleton is initialized once and reused. See the singleton pattern in references/shader-integration-react.md.

Canvas appears stretched or distorted on high-DPI displays

Canvas width / height attributes must match physical pixel dimensions, not CSS dimensions. CSS w-full h-full sets display size only. Use a ResizeObserver on the canvas element: canvas.width = entry.contentRect.width * devicePixelRatio.

TypeScript error: "Property 'ref' does not exist on 'HTMLCanvasElement'"

React 19 passes ref as a prop. The canvas element should be <canvas ref={shaderCanvasRef} ... /> — no forwardRef needed. Ensure the ref type matches: useRef<HTMLCanvasElement>(null).

---

Reference Loading Table

Task	Reference File
Fragment shader GLSL source	references/card-shader-patterns.md
React 19 WebGL hook + context pool	references/shader-integration-react.md
Balatro holographic foil breakdown	references/balatro-shader-breakdown.md

Load only the reference needed for the current phase. All three together is ~1,400 lines — only load all three if implementing everything in one pass.