Neural Cursor

Relevant source files

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

• src/effects/neural-cursor.tsx
• src/provider/index.tsx
• src/theme/colors.ts
• src/index.ts
• package.json

The Neural Cursor is a specialized visual effect component within the @pcstyle/ui library designed to enhance user interaction through a reactive, multi-layered tracking system. It primarily serves the "cyber" theme, providing a high-tech, aesthetic cursor replacement that consists of a primary ring, a delayed trailing dot, and a connective neural line.

The component is part of the library's "Effects" module and integrates deeply with the global UIProvider to determine visibility and color schemes based on the active system theme. It is optimized for large screens and utilizes React hooks for efficient mouse position tracking.

Sources: src/effects/neural-cursor.tsx:1-50, src/index.ts:15-16, package.json:1-15

Architecture and Core Logic

The Neural Cursor system architecture is built around three primary functional areas: state management of physical mouse coordinates, time-delayed state calculation for the "trail" effect, and conditional rendering based on the global theme context.

Mouse Tracking Hook

The system employs a custom hook, useMousePosition, to abstract the low-level window event listeners. It updates the state on every mousemove event using a passive listener to ensure scrolling performance is not impacted.

Tracking Mechanism

The component manages two distinct sets of coordinates:

1. Immediate Position: Represented by the mouse variable, used for the primary outer ring.
2. Delayed Position: Managed via a useEffect hook with a 30ms setTimeout. This creates the "neural lag" effect where a secondary element follows the primary cursor.

Sources: src/effects/neural-cursor.tsx:18-30

Component Structure and Visual Elements

The NeuralCursor component renders a fixed-position container that spans the entire viewport. It is visually composed of three distinct SVG and HTML elements.

Visual Layers

Layer	Element Type	Purpose	Styling Logic
Primary Ring	div (border)	Represents the actual mouse position.	16x16px, centered at mouse.x/y, transitions via duration-75.
Trailing Dot	div (solid)	Provides a "neural" trail effect.	8x8px, 40% opacity, blurred, follows delayedMouse.
Neural Line	line (SVG)	Connects the ring and the dot.	Stroke opacity 0.15, connects mouse to delayedMouse.

Sources: src/effects/neural-cursor.tsx:37-55

Theme Integration and Context

The Neural Cursor's behavior and appearance are strictly governed by the UIProvider. It consumes the theme value to decide if it should mount and what color it should adopt.

Theme Sensitivity

The component is designed to be exclusive to the cyber theme. If the current theme is set to minimal, the component returns null, rendering nothing to the DOM.

Color Resolution

Colors are resolved dynamically. If a specific color prop is not provided, the component falls back to theme-specific defaults defined in the design tokens.

• Cyber Theme Default: #ff00ff (Neon Pink)
• Fallback Default: #000000

Sources: src/effects/neural-cursor.tsx:22, src/theme/colors.ts:8-12

Implementation Details

Properties (Props)

Name	Type	Required	Description
color	string	No	Overrides the default theme-based color for the cursor elements.

Technical Constraints

• Visibility: Forced hidden on non-LG (large) screens using Tailwind CSS classes (hidden lg:block).
• Interactivity: Uses pointer-events-none to ensure the custom cursor does not interfere with clicking or hovering on underlying UI elements.
• Layering: Set to a high Z-index (z-[10000]) to remain above all other UI components, including overlays.

Sources: src/effects/neural-cursor.tsx:17, src/effects/neural-cursor.tsx:37-38

Integration within @pcstyle/ui

The Neural Cursor is exported as a named export from the library's root, allowing developers to include it at the top level of their application, typically inside the UIProvider.

Summary

The Neural Cursor is a thematic UI effect that implements a dual-coordinate tracking system. By utilizing React's state management and window event listeners, it creates a lag-behind visual effect that is both performant and aesthetically aligned with the project's "cyber" design language. It serves as a prime example of how the library integrates context-aware effects with design tokens.