Effects Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/effects/crt-overlay.tsx
• src/effects/neural-cursor.tsx
• src/provider/index.tsx
• src/index.ts
• src/theme/colors.ts
• src/components/buttons/Button.tsx

Effects Integration within the @pcstyle/ui library refers to the specialized visual layer designed to enhance the user interface, specifically when the "cyber" theme is active. These effects are managed through a centralized provider system that synchronizes the visual state of the application with specific thematic requirements.

The system primary consists of standalone React components that hook into the global UI state to determine their visibility and behavior. By leveraging CSS variables and Framer Motion, these effects provide an immersive "cyberpunk" aesthetic without interfering with the functional components of the design system.
Sources: src/provider/index.tsx, src/index.ts:11-13, package.json:20-23

Architecture and State Management

The effects system is tightly coupled with the UIProvider. The provider manages the ThemeMode (either "cyber" or "minimal") and exposes this state via the useUI hook. Effects components use this state to conditionally render, ensuring that performance-heavy or visually aggressive effects are only present when the "cyber" theme is selected.

The diagram above illustrates the conditional rendering logic used by effects to maintain theme consistency.
Sources: src/provider/index.tsx:13-35, src/effects/crt-overlay.tsx:8-10, src/effects/neural-cursor.tsx:32

Thematic Synchronization

The system synchronizes thematic colors from src/theme/colors.ts to the effects using the following mechanism:

1. State Change: setTheme or toggleTheme updates the context.
2. CSS Variable Injection: An useEffect in the provider maps color tokens to CSS variables prefixed with --pc-.
3. Component Reactivity: Effects components re-render or update their internal color logic based on the new theme state.
   Sources: src/provider/index.tsx:25-33, src/theme/colors.ts:7-35

Core Effect Components

CRT Overlay

The CRTOverlay component provides a retro-futuristic screen effect. It utilizes absolute positioning and high z-index to overlay the entire viewport. The visual is achieved through two primary layers defined in CSS linear and radial gradients.

Feature	Implementation Detail	Purpose
Scanlines	linear-gradient with 4px/6px length	Mimics analog monitor lines and RGB subpixels
Vignette	radial-gradient	Darkens screen edges for a curved tube appearance
Interactivity	pointer-events-none	Ensures the overlay does not block user clicks
Z-Index	z-[9999]	Places effect above standard UI components

Sources: src/effects/crt-overlay.tsx:12-18

Neural Cursor

The NeuralCursor is an advanced interactive effect that replaces or augments the standard mouse pointer with a multi-part tracking system. It utilizes a custom useMousePosition hook to track client coordinates.

The sequence diagram shows the data flow from hardware input to the rendered delayed-tracking effect.
Sources: src/effects/neural-cursor.tsx:6-30

Key Technical Details:

• Tracking Logic: Uses a 30ms timeout to create a "trailing" effect via the delayedMouse state.
• Visual Elements:
  • A main 16x16 border ring following the immediate cursor position.
  • An inner 8x8 blurred dot following the delayed position.
  • An SVG <line> connecting the immediate and delayed positions with low opacity.
    Sources: src/effects/neural-cursor.tsx:35-56

Component-Level Effects

Beyond global overlays, standard components include "hooks" for specific effects. For instance, the Button component includes a reserved area for cyber-specific hover effects like scanlines, which are activated via the isCyber flag derived from the UI context.
Sources: src/components/buttons/Button.tsx:61-65

Implementation Summary

Component	File Path	Theme Dependency	Z-Index
UIProvider	src/provider/index.tsx	N/A (Manager)	N/A
CRTOverlay	src/effects/crt-overlay.tsx	Cyber only	9999
NeuralCursor	src/effects/neural-cursor.tsx	Cyber only	10000

The effects system is designed to be modular, exported via the @pcstyle/ui/effects entry point. This allows developers to opt-in to specific visual enhancements or include them globally within a UIProvider wrapper.
Sources: src/index.ts:11-13, package.json:18-24