Fix spotlight effect behavior

Author: snwolak

README.md

@@ -1,6 +1,6 @@
 # Protohiro Effects
 
-Protohiro Effects is a zero-wrapper React library for hard CSS effects like gradient borders, glow rings, and noise overlays.
+Protohiro Effects is a zero-wrapper React library for hard CSS effects like gradient borders, glow rings, noise overlays, and spotlight overlays.
 
 ## Live demo
 
@@ -56,6 +56,24 @@ Options:
 - `intensity?: number`
 - `disabled?: boolean`
 
+### `useSpotlightEffect(options)`
+
+Options:
+- `mode?: 'glow' | 'reveal'`
+- `size?: string | number`
+- `intensity?: number`
+- `color?: string`
+- `softness?: number`
+- `coreIntensity?: number`
+- `x?: string | number`
+- `y?: string | number`
+- `followPointer?: boolean`
+- `revealColor?: string`
+- `revealImage?: string`
+- `revealSize?: string | number`
+- `revealOpacity?: number`
+- `disabled?: boolean`
+
 ## Safari notes
 
 `gradient-border` uses `mask-composite` for the preferred ring rendering path. Safari fallback uses a simplified border and layered background. The fallback keeps content readable and does not hide element content.

apps/demo/src/App.tsx

@@ -1,16 +1,23 @@
-import { useGlowEffect, useGradientBorderEffect, useNoiseEffect } from '@protohiro/effects';
+import {
+  useGlowEffect,
+  useGradientBorderEffect,
+  useNoiseEffect,
+  useSpotlightEffect,
+} from '@protohiro/effects';
 import { useMemo, useState, type CSSProperties, type RefCallback } from 'react';
+import revealImageAsset from './assets/reveal.jpeg';
 
 type DemoOption = string | number | boolean;
 type DemoOptions = Record<string, DemoOption>;
-type ControlType = 'text' | 'number' | 'range' | 'checkbox' | 'color';
+type ControlType = 'text' | 'number' | 'range' | 'checkbox' | 'color' | 'select';
 type PreviewElement = 'button' | 'div' | 'article';
 type EffectHook = (options: DemoOptions) => RefCallback<HTMLElement>;
 
 type DemoControl = {
   key: string;
   label: string;
   type: ControlType;
+  selectOptions?: string[];
   min?: number;
   max?: number;
   step?: number;
@@ -42,6 +49,10 @@ function useNoiseStoryHook(options: DemoOptions): RefCallback<HTMLElement> {
   return useNoiseEffect(options);
 }
 
+function useSpotlightStoryHook(options: DemoOptions): RefCallback<HTMLElement> {
+  return useSpotlightEffect(options);
+}
+
 const STORIES: EffectStory[] = [
   {
     id: 'gradient-border',
@@ -116,6 +127,52 @@ const STORIES: EffectStory[] = [
       { key: 'disabled', label: 'Disabled', type: 'checkbox' },
     ],
   },
+  {
+    id: 'spotlight',
+    title: 'Spotlight',
+    description: 'Interactive light cone with cinematic falloff and pointer tracking.',
+    hookName: 'useSpotlightEffect',
+    componentName: 'SpotlightCard',
+    previewText: 'Move pointer across the card',
+    previewElement: 'article',
+    previewStyle: {
+      background:
+        'radial-gradient(circle at 8% 12%, rgba(99, 102, 241, 0.26), transparent 34%), radial-gradient(circle at 90% 82%, rgba(45, 212, 191, 0.12), transparent 42%), linear-gradient(150deg, #090617 0%, #0a1023 48%, #070b1a 100%)',
+      color: '#f5f3ff',
+      border: '1px solid rgba(129, 140, 248, 0.32)',
+      boxShadow:
+        'inset 0 1px 0 rgba(255, 255, 255, 0.1), inset 0 -24px 45px rgba(12, 8, 35, 0.42), 0 24px 70px rgba(3, 6, 19, 0.58)',
+    },
+    hook: useSpotlightStoryHook,
+    defaults: {
+      mode: 'reveal',
+      color: '#2a2079',
+      size: 50,
+      intensity: 0.3,
+      softness: 0.9,
+      coreIntensity: 0.35,
+      x: 36,
+      y: 32,
+      followPointer: true,
+      revealColor: '#38bdf8',
+      revealImage: revealImageAsset,
+      revealOpacity: 0.9,
+    },
+    controls: [
+      { key: 'mode', label: 'Mode', type: 'select', selectOptions: ['reveal', 'glow'] },
+      { key: 'color', label: 'Color', type: 'color' },
+      { key: 'size', label: 'Size', type: 'number', min: 0, max: 280, step: 1 },
+      { key: 'intensity', label: 'Intensity', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'softness', label: 'Softness', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'coreIntensity', label: 'Core intensity', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'revealColor', label: 'Reveal color', type: 'color' },
+      { key: 'revealOpacity', label: 'Reveal opacity', type: 'range', min: 0, max: 1, step: 0.01 },
+      { key: 'x', label: 'X', type: 'range', min: 0, max: 100, step: 1 },
+      { key: 'y', label: 'Y', type: 'range', min: 0, max: 100, step: 1 },
+      { key: 'followPointer', label: 'Follow pointer', type: 'checkbox' },
+      { key: 'disabled', label: 'Disabled', type: 'checkbox' },
+    ],
+  },
 ];
 
 function formatOptionValue(value: DemoOption): string {
@@ -150,6 +207,7 @@ function EffectPlayground({ story }: { story: EffectStory }) {
   const useEffectHook = story.hook;
   const ref = useEffectHook(options);
   const PreviewTag = story.previewElement;
+  const previewClassName = story.id === 'spotlight' ? 'demo-card demo-card-spotlight' : 'demo-card';
   const hookSnippet = useMemo(() => createHookSnippet(story, options), [options, story]);
 
   const controls = useMemo(
@@ -177,6 +235,30 @@ function EffectPlayground({ story }: { story: EffectStory }) {
           );
         }
 
+        if (control.type === 'select') {
+          return (
+            <label key={control.key} className="demo-control" htmlFor={inputId}>
+              <span>{control.label}</span>
+              <select
+                id={inputId}
+                value={String(value ?? '')}
+                onChange={(event) => {
+                  setOptions((current) => ({
+                    ...current,
+                    [control.key]: event.target.value,
+                  }));
+                }}
+              >
+                {(control.selectOptions ?? []).map((optionValue) => (
+                  <option key={optionValue} value={optionValue}>
+                    {optionValue}
+                  </option>
+                ))}
+              </select>
+            </label>
+          );
+        }
+
         return (
           <label key={control.key} className="demo-control" htmlFor={inputId}>
             <span>{control.label}</span>
@@ -216,7 +298,7 @@ function EffectPlayground({ story }: { story: EffectStory }) {
           <p>{story.description}</p>
         </header>
         <div className="demo-preview">
-          <PreviewTag ref={ref} className="demo-card" style={story.previewStyle}>
+          <PreviewTag ref={ref} className={previewClassName} style={story.previewStyle}>
             {story.previewText}
           </PreviewTag>
         </div>

apps/demo/src/assets/reveal.jpeg

@@ -147,6 +147,18 @@ h1 {
   font-weight: 600;
 }
 
+.demo-card-spotlight {
+  min-height: 136px;
+  display: flex;
+  align-items: flex-start;
+  justify-content: flex-start;
+  padding: 1.05rem 1.2rem;
+  font-size: 1rem;
+  font-weight: 700;
+  letter-spacing: 0.015em;
+  text-shadow: 0 3px 16px rgba(3, 6, 23, 0.85);
+}
+
 .demo-controls-pane {
   display: grid;
   align-content: start;
@@ -176,6 +188,15 @@ h1 {
   padding: 0.45rem 0.6rem;
 }
 
+.demo-control select {
+  width: 100%;
+  border-radius: 10px;
+  border: 1px solid rgba(148, 163, 184, 0.28);
+  background: rgba(10, 21, 42, 0.95);
+  color: #f8fafc;
+  padding: 0.45rem 0.6rem;
+}
+
 .demo-control input[type='color'] {
   min-height: 2.2rem;
   padding: 0.2rem 0.3rem;
@@ -186,6 +207,11 @@ h1 {
   outline-offset: 1px;
 }
 
+.demo-control select:focus-visible {
+  outline: 2px solid rgba(56, 189, 248, 0.6);
+  outline-offset: 1px;
+}
+
 .demo-control-toggle {
   display: flex;
   align-items: center;

apps/demo/src/styles.css

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

apps/demo/src/vite-env.d.ts

@@ -1,7 +1,7 @@
 {
   "name": "protohiro-effects-monorepo",
   "private": true,
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Zero-wrapper React CSS effects engine.",
   "packageManager": "pnpm@9.15.0",
   "scripts": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protohiro/effects-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Core runtime utilities for ProtoEffects CSS-first effects.",
   "license": "MIT",
   "type": "module",

packages/core/package.json

@@ -24,6 +24,7 @@ export function Button() {
 - `useGradientBorderEffect`
 - `useGlowEffect`
 - `useNoiseEffect`
+- `useSpotlightEffect`
 
 Live demo:
 https://libs.protohiro.com/effects/

packages/react/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@protohiro/effects",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Zero-wrapper React hooks for composable CSS effects.",
   "license": "MIT",
   "type": "module",