bsmnt 0.1.3 → 0.2.4

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

@@ -1,436 +0,0 @@
----
-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