bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/default/.cursor/rules/components.mdc

@@ -0,0 +1,436 @@
+---
+alwaysApply: true
+---
+---
+description: React component patterns and WebGL integration
+globs: *.tsx, *.jsx, *.js, *.ts
+---
+
+# Component Guidelines
+
+## Imports and Dependencies
+
+### Utility Functions
+Always use `cn` from `@/styles/cn` for className conditionals
+
+```tsx
+import { cn } from '@/styles/cn'
+
+function MyComponent({ className }) {
+  return <div className={cn(s.component, className)} />
+}
+```
+
+### Animation Libraries
+- Use `motion` for animations
+- Use `react-use` for DOM utilities
+
+## Component Structure
+
+### CSS Modules
+Use CSS modules for component styling. Import styles as `s`
+
+```tsx
+import s from './component-name.module.css'
+```
+
+### Client Components
+Add 'use client' directive for client components
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+```
+
+### Props Interface
+Define props interface at the top of the file. Extend HTML attributes when appropriate.
+
+```tsx
+import type { ComponentProps } from 'react'
+
+interface ButtonProps extends ComponentProps<'button'> {
+  variant?: 'primary' | 'secondary'
+  size?: 'sm' | 'md' | 'lg'
+}
+```
+
+### React 19 Ref Handling
+In React 19, ref is passed as a regular prop (no forwardRef needed)
+
+```tsx
+// Old pattern (React 18)
+// const Button = forwardRef<HTMLButtonElement, ButtonProps>(...)
+
+// New pattern (React 19)
+function Button({ ref, variant = 'primary', ...props }: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
+  return <button ref={ref} {...props} />
+}
+```
+
+### Default Exports
+Use named function declarations for components. Export the component as default.
+
+```tsx
+function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
+  // component logic
+}
+
+export default Button
+```
+
+## Form Components
+
+-- TODO: Add form handling rules
+
+### Server Actions
+Use Server Actions for form submissions when possible. Implement proper error handling.
+
+```tsx
+async function submitForm(formData: FormData) {
+  'use server'
+  // server-side logic
+}
+```
+
+## Responsive Design
+
+### Device Detection
+Use `useDeviceDetection` hook from `@/hooks/use-device-detection` for device specific logic
+
+```tsx
+import { useDeviceDetection } from '@/hooks/use-device-detection'
+
+function ResponsiveComponent() {
+  const { isMobile } = useDeviceDetection()
+  return isMobile ? <MobileVersion /> : <DesktopVersion />
+}
+```
+
+### Media Breakpoints
+Use `useMediaBreakpoint` hook from `@/hooks/use-media-breakpoint` for media breakpoints detection
+
+```tsx
+import { useMediaBreakpoint } from '@/hooks/use-media-breakpoint'
+
+function ResponsiveComponent() {
+  const isDesktop = useMediaBreakpoint('desktop')
+  return isDesktop ? <DesktopVersion /> : <MobileVersion />
+}
+```
+
+### Viewport Units
+Use custom viewport units for responsive values (see styling.mdc for details)
+
+```css
+.element {
+  width: tovw(150);
+  margin-top: torem(100);
+}
+```
+
+## Performance Best Practices
+
+### Code Splitting
+Use `next/dynamic` for heavy components
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
+  loading: () => <div>Loading...</div>,
+  ssr: false // if needed
+})
+```
+
+### Memoization
+See main.mdc for React Compiler guidance - manual memoization is rarely needed.
+
+## Error Handling
+
+### Error Boundaries
+Implement error boundaries for critical sections. Provide meaningful fallback UI.
+
+### Loading States
+Always handle loading states. Use Suspense boundaries where appropriate.
+
+---
+
+# WebGL Components
+
+## React Three Fiber Setup
+
+### Canvas Component
+-- TODO: Add Canvas component rules
+
+## WebGL File Organization
+
+Separate WebGL logic into `webgl.tsx` files. Keep React logic in main component files.
+
+```
+components/
+  scene/
+    index.tsx         # React component
+    webgl.tsx         # Three.js logic
+    scene.module.css  # Styles
+```
+
+### WebGL Component Pattern
+
+```tsx
+// scene/webgl.tsx
+import { useFrame } from '@react-three/fiber'
+import { useRef } from 'react'
+import type { Mesh } from 'three'
+
+export default function SceneWebGL() {
+  const meshRef = useRef<Mesh>(null)
+
+  useFrame((state, delta) => {
+    if (meshRef.current) {
+      meshRef.current.rotation.y += delta
+    }
+  })
+
+  // Simple logs are auto-stripped in production by Next.js
+  console.log('SceneWebGL rendered')
+
+  return (
+    <mesh ref={meshRef}>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshStandardMaterial color="hotpink" />
+    </mesh>
+  )
+}
+```
+
+## Drei Components
+
+### Common Helpers
+Use Drei components for common functionality
+
+```tsx
+import {
+  OrbitControls,
+  PerspectiveCamera,
+  Environment,
+  useGLTF,
+  useTexture
+} from '@react-three/drei'
+```
+
+### Loading Assets
+Preload assets using Drei hooks. Implement proper loading states.
+
+```tsx
+// Preload in separate component
+function Preload() {
+  const start = performance.now()
+  useGLTF.preload('/models/model.glb')
+  useTexture.preload('/textures/texture.jpg')
+  // Console logs auto-stripped in production by Next.js
+  console.log(`Preload took ${performance.now() - start}ms`)
+  return null
+}
+```
+
+## Custom Shaders
+
+### Shader Materials
+Use template literals for GLSL. Implement proper uniforms.
+
+```tsx
+import { shaderMaterial } from '@react-three/drei'
+import { extend } from '@react-three/fiber'
+
+const CustomMaterial = shaderMaterial(
+  { uTime: 0, uColor: new THREE.Color(0.0, 0.0, 0.0) },
+  vertexShader,
+  fragmentShader
+)
+
+extend({ CustomMaterial })
+```
+
+### GLSL Best Practices
+- Keep shaders in separate files when complex
+- Use proper precision qualifiers
+- Comment complex calculations
+
+```glsl
+precision mediump float;
+
+uniform float uTime;
+varying vec2 vUv;
+
+void main() {
+  // Shader logic
+}
+```
+
+## Animation & Interaction
+
+### Animation Loops
+Use `useFrame` for frame-based animations. Consider performance impact.
+
+```tsx
+useFrame((state, delta) => {
+  // Animation logic
+}, priority) // Lower priority = runs first
+```
+
+### Interaction
+Use Drei's interaction helpers. Implement proper hover/click states.
+
+```tsx
+import { useCursor } from '@react-three/drei'
+
+function InteractiveObject() {
+  const [hovered, setHovered] = useState(false)
+  useCursor(hovered)
+
+  return (
+    <mesh
+      onPointerOver={() => setHovered(true)}
+      onPointerOut={() => setHovered(false)}
+    >
+      {/* geometry and material */}
+    </mesh>
+  )
+}
+```
+
+## Post-Processing
+
+### Effect Composer
+Use postprocessing library for effects. Chain effects efficiently.
+
+```tsx
+import { EffectComposer, Bloom, ChromaticAberration } from '@react-three/postprocessing'
+
+function Effects() {
+  return (
+    <EffectComposer>
+      <Bloom intensity={1.5} />
+      <ChromaticAberration offset={[0.002, 0.002]} />
+    </EffectComposer>
+  )
+}
+```
+
+### Performance Considerations
+- Limit number of passes
+- Use lower resolution for effects when possible
+- Profile performance impact
+
+## WebGL Best Practices
+
+### Memory Management
+Dispose of geometries and materials when components unmount. Clean up in useEffect return for complex resources. React Compiler handles most cleanup automatically.
+
+```tsx
+useEffect(() => {
+  // Only for complex resources that need explicit disposal
+  return () => {
+    geometry.dispose()
+    material.dispose()
+    texture.dispose()
+  }
+}, [geometry, material, texture])
+```
+
+### Performance Optimization
+See main.mdc for React Compiler guidance. For WebGL-specific object instantiation, always use `useRef`:
+
+```tsx
+// ⚠️ EXCEPTION: Object instantiation MUST use useRef to prevent infinite loops
+// Creating new objects on every render creates new references that trigger effects
+
+// ❌ DON'T: This causes infinite re-renders
+const flowmap = new Flowmap()
+
+// ✅ DO: Use useRef for object instantiation
+const flowmapRef = useRef<Flowmap | null>(null)
+if (!flowmapRef.current) {
+  flowmapRef.current = new Flowmap(gl, { size: 128 })
+}
+const flowmap = flowmapRef.current
+```
+
+### Responsive Design
+Handle window resizing. Adjust quality based on device capabilities.
+
+```tsx
+const { viewport } = useThree()
+// Use viewport.width, viewport.height for responsive sizing
+```
+
+## React 19.2 Activity Integration
+
+Use `<Activity />` to optimize WebGL performance by deferring off-screen scenes:
+
+```tsx
+import { Activity, useEffect, useRef, useState } from 'react'
+import { useRect } from 'hamo'
+import { WebGLTunnel } from '@/lib/webgl/components/tunnel'
+
+export function WebGLScene({ className }) {
+  const [setRectRef, rect] = useRect()
+  const [isVisible, setIsVisible] = useState(true)
+  const elementRef = useRef<HTMLDivElement | null>(null)
+
+  // Intersection Observer with 200px margin for pre-activation
+  useEffect(() => {
+    const element = elementRef.current
+    if (!element) return
+
+    const observer = new IntersectionObserver(
+      ([entry]) => setIsVisible(entry.isIntersecting),
+      { rootMargin: '200px' }
+    )
+
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [])
+
+  return (
+    // Wrap DOM container - defers rect tracking when off-screen
+    <Activity mode={isVisible ? 'visible' : 'hidden'}>
+      <div ref={(el) => { setRectRef(el); elementRef.current = el }} className={className}>
+        {/* WebGL content goes in WebGLTunnel (no Activity wrapper needed) */}
+        <WebGLTunnel>
+          <WebGLComponent rect={rect} />
+        </WebGLTunnel>
+      </div>
+    </Activity>
+  )
+}
+```
+
+**Pattern**: `<Activity />` → DOM container → `WebGLTunnel` → WebGL content
+
+### Debugging
+- Use Theatre.js for animation debugging
+- Enable WebGL inspector in development
+- **Always gate debug UI components** - these are NOT auto-removed
+- Simple console logs are auto-stripped in production by Next.js
+
+```tsx
+// Simple logs: Auto-stripped in production
+console.log('WebGL state:', { fps, drawCalls, triangles })
+
+// Debug components: MUST be gated (not auto-removed)
+{process.env.NODE_ENV === 'development' && <Stats />}
+{process.env.NODE_ENV === 'development' && <Perf />}
+```
+
+### Mobile Optimization
+- Reduce polygon count for mobile
+- Use simpler shaders
+- Implement touch controls
+
+```tsx
+const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent)
+```
+
+Last updated: 2026-01-26