(null)
+
+ const { networkSpeed, deviceMemory } = useDeviceCapabilities()
+
+ // Check if component should load based on conditions
+ useEffect(() => {
+ if (loadCondition && !loadCondition()) {
+ return undefined
+ }
+
+ switch (loadOn) {
+ case 'immediate':
+ setShouldLoad(true)
+ break
+
+ case 'idle':
+ if ('requestIdleCallback' in window) {
+ const id = requestIdleCallback(() => setShouldLoad(true))
+ return () => cancelIdleCallback(id)
+ } else {
+ // Fallback for browsers without requestIdleCallback
+ const timeout = setTimeout(() => setShouldLoad(true), 1)
+ return () => clearTimeout(timeout)
+ }
+ break
+
+ case 'interaction': {
+ const handleInteraction = () => {
+ setShouldLoad(true)
+ cleanup()
+ }
+
+ const events = ['click', 'touchstart', 'mouseenter', 'focus']
+ const cleanup = () => {
+ events.forEach(event => {
+ document.removeEventListener(event, handleInteraction)
+ })
+ }
+
+ events.forEach(event => {
+ document.addEventListener(event, handleInteraction, { once: true })
+ })
+
+ return cleanup
+ }
+
+ case 'visible': {
+ if (!elementRef.current) return
+
+ const observer = new IntersectionObserver(
+ ([entry]) => {
+ if (entry?.isIntersecting) {
+ setShouldLoad(true)
+ observer.disconnect()
+ }
+ },
+ { threshold, rootMargin }
+ )
+
+ observer.observe(elementRef.current)
+ return () => observer.disconnect()
+ }
+
+ default:
+ break
+ }
+
+ return undefined
+ }, [loadOn, loadCondition, threshold, rootMargin])
+
+ // Show fallback for low-end devices or slow networks
+ if (networkSpeed === 'slow' || deviceMemory < 4) {
+ return fallback ? <>{fallback} : null
+ }
+
+ if (!shouldLoad) {
+ return (
+
+ {loadingComponent}
+
+ )
+ }
+
+ return (
+
+ {children}
+
+ )
+ }
+)
+
+AdaptiveLoader.displayName = 'AdaptiveLoader'
+
+/**
+ * Component for dynamically importing heavy components
+ */
+interface DynamicComponentProps> {
+ loader: () => Promise<{ default: React.ComponentType
}>
+ props?: P
+ fallback?: React.ReactNode
+ loadOn?: 'immediate' | 'interaction' | 'idle' | 'visible'
+ ssr?: boolean
+}
+
+export function DynamicComponent
= Record>({
+ loader,
+ props = {} as P,
+ fallback = ,
+ loadOn = 'visible',
+ ssr = false,
+}: DynamicComponentProps) {
+ const Component = dynamic(loader, {
+ loading: () => <>{fallback},
+ ssr,
+ })
+
+ return (
+
+
+
+ )
+}
+
+/**
+ * Progressive enhancement wrapper
+ */
+interface ProgressiveEnhancementProps {
+ basic: React.ReactNode
+ enhanced: React.ReactNode
+ enhanceOn?: 'immediate' | 'interaction' | 'idle'
+ className?: string
+}
+
+export const ProgressiveEnhancement: React.FC = ({
+ basic,
+ enhanced,
+ enhanceOn = 'idle',
+ className,
+}) => {
+ const [isEnhanced, setIsEnhanced] = useState(false)
+ const { isTouch, networkSpeed } = useDeviceCapabilities()
+
+ useEffect(() => {
+ // Don't enhance on slow networks or low-end devices
+ if (networkSpeed === 'slow') {
+ return undefined
+ }
+
+ switch (enhanceOn) {
+ case 'immediate':
+ setIsEnhanced(true)
+ break
+
+ case 'idle': {
+ if ('requestIdleCallback' in window) {
+ const id = requestIdleCallback(() => setIsEnhanced(true))
+ return () => cancelIdleCallback(id)
+ } else {
+ const timeout = setTimeout(() => setIsEnhanced(true), 1)
+ return () => clearTimeout(timeout)
+ }
+ }
+
+ case 'interaction': {
+ const handleInteraction = () => setIsEnhanced(true)
+ const event = isTouch ? 'touchstart' : 'mouseenter'
+
+ document.addEventListener(event, handleInteraction, { once: true })
+ return () => document.removeEventListener(event, handleInteraction)
+ }
+
+ default:
+ break
+ }
+
+ return undefined
+ }, [enhanceOn, networkSpeed, isTouch])
+
+ return {isEnhanced ? enhanced : basic}
+}
+
+/**
+ * Resource hint component for preloading/prefetching
+ */
+interface ResourceHintProps {
+ href: string
+ as?: 'script' | 'style' | 'image' | 'font' | 'document'
+ type?: string
+ crossOrigin?: 'anonymous' | 'use-credentials'
+ rel?: 'preload' | 'prefetch' | 'preconnect' | 'dns-prefetch'
+}
+
+export const ResourceHint: React.FC = ({
+ href,
+ as,
+ type,
+ crossOrigin,
+ rel = 'preload',
+}) => {
+ useEffect(() => {
+ const link = document.createElement('link')
+ link.rel = rel
+ link.href = href
+
+ if (as) link.as = as
+ if (type) link.type = type
+ if (crossOrigin) link.crossOrigin = crossOrigin
+
+ document.head.appendChild(link)
+
+ return () => {
+ document.head.removeChild(link)
+ }
+ }, [href, as, type, crossOrigin, rel])
+
+ return null
+}
diff --git a/src/components/layout/LayoutDebugger.tsx b/src/components/layout/LayoutDebugger.tsx
new file mode 100644
index 0000000..2516571
--- /dev/null
+++ b/src/components/layout/LayoutDebugger.tsx
@@ -0,0 +1,366 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+import { useViewport } from './ResponsiveUtils'
+
+interface LayoutDebuggerProps {
+ showGrid?: boolean
+ showBreakpoints?: boolean
+ showContainerQueries?: boolean
+ showTouchTargets?: boolean
+ showViewportInfo?: boolean
+ showPerformance?: boolean
+ className?: string
+}
+
+export const LayoutDebugger: React.FC = ({
+ showGrid = true,
+ showBreakpoints = true,
+ showContainerQueries = true,
+ showTouchTargets = true,
+ showViewportInfo = true,
+ showPerformance = true,
+ className,
+}) => {
+ const [isVisible, setIsVisible] = useState(false)
+ const [gridEnabled, setShowGrid] = useState(showGrid)
+ const [touchTargetsEnabled, setShowTouchTargets] = useState(showTouchTargets)
+ const [containerQueriesEnabled, setShowContainerQueries] = useState(showContainerQueries)
+ const [performanceMetrics, setPerformanceMetrics] = useState({
+ fps: 0,
+ memory: 0,
+ layoutShifts: 0,
+ })
+ const viewport = useViewport()
+
+ // Toggle debugger visibility with keyboard shortcut
+ useEffect(() => {
+ const handleKeyPress = (e: KeyboardEvent) => {
+ if (e.ctrlKey && e.shiftKey && e.key === 'D') {
+ setIsVisible(prev => !prev)
+ }
+ }
+
+ window.addEventListener('keydown', handleKeyPress)
+ return () => window.removeEventListener('keydown', handleKeyPress)
+ }, [])
+
+ // Monitor performance metrics
+ useEffect(() => {
+ if (!showPerformance || !isVisible) return
+
+ let frameCount = 0
+ let lastTime = performance.now()
+ let rafId: number
+
+ const measureFPS = () => {
+ frameCount++
+ const currentTime = performance.now()
+
+ if (currentTime >= lastTime + 1000) {
+ setPerformanceMetrics(prev => ({
+ ...prev,
+ fps: Math.round((frameCount * 1000) / (currentTime - lastTime)),
+ }))
+ frameCount = 0
+ lastTime = currentTime
+ }
+
+ rafId = requestAnimationFrame(measureFPS)
+ }
+
+ rafId = requestAnimationFrame(measureFPS)
+
+ // Monitor memory usage
+ const memoryInterval = setInterval(() => {
+ if ('memory' in performance) {
+ const memory = (performance as any).memory
+ setPerformanceMetrics(prev => ({
+ ...prev,
+ memory: Math.round(memory.usedJSHeapSize / 1048576), // Convert to MB
+ }))
+ }
+ }, 1000)
+
+ // Monitor layout shifts
+ let layoutShiftCount = 0
+ const observer = new PerformanceObserver(list => {
+ for (const entry of list.getEntries()) {
+ if (entry.entryType === 'layout-shift') {
+ layoutShiftCount++
+ setPerformanceMetrics(prev => ({
+ ...prev,
+ layoutShifts: layoutShiftCount,
+ }))
+ }
+ }
+ })
+
+ observer.observe({ entryTypes: ['layout-shift'] })
+
+ return () => {
+ cancelAnimationFrame(rafId)
+ clearInterval(memoryInterval)
+ observer.disconnect()
+ }
+ }, [showPerformance, isVisible])
+
+ // Handle debug styles
+ useEffect(() => {
+ const styleId = 'layout-debugger-styles'
+ let styleElement = document.getElementById(styleId) as HTMLStyleElement
+
+ if (!isVisible) {
+ if (styleElement) {
+ styleElement.remove()
+ }
+ return
+ }
+
+ if (!styleElement) {
+ styleElement = document.createElement('style')
+ styleElement.id = styleId
+ document.head.appendChild(styleElement)
+ }
+
+ const styles: string[] = []
+
+ if (touchTargetsEnabled) {
+ styles.push(`
+ button, a, input, textarea, select, [role="button"], [tabindex]:not([tabindex="-1"]) {
+ position: relative;
+ }
+ button::after, a::after, input::after, textarea::after, select::after, [role="button"]::after, [tabindex]:not([tabindex="-1"])::after {
+ content: '';
+ position: absolute;
+ inset: 0;
+ min-width: 44px;
+ min-height: 44px;
+ border: 2px dashed rgba(255, 0, 255, 0.5);
+ pointer-events: none;
+ transform: translate(-50%, -50%);
+ left: 50%;
+ top: 50%;
+ }
+ `)
+ }
+
+ if (containerQueriesEnabled) {
+ styles.push(`
+ [class*="@container"], .container-queries {
+ outline: 2px dashed rgba(0, 255, 0, 0.5) !important;
+ outline-offset: -2px;
+ }
+ `)
+ }
+
+ styleElement.textContent = styles.join('\n')
+
+ return () => {
+ if (styleElement) {
+ styleElement.remove()
+ }
+ }
+ }, [isVisible, touchTargetsEnabled, containerQueriesEnabled])
+
+ if (!isVisible) {
+ return (
+
+ )
+ }
+
+ return (
+ <>
+ {/* Grid overlay */}
+ {gridEnabled && (
+
+ )}
+
+ {/* Touch target indicators are handled via useEffect */}
+
+ {/* Container query indicators are handled via useEffect */}
+
+ {/* Debug panel */}
+
+
+
Layout Debugger
+
+
+
+ {/* Viewport info */}
+ {showViewportInfo && (
+
+
+ Viewport: {viewport.width} × {viewport.height}
+
+
+ Device: {viewport.isMobile ? 'Mobile' : viewport.isTablet ? 'Tablet' : 'Desktop'}
+
+
+ )}
+
+ {/* Breakpoint indicator */}
+ {showBreakpoints && (
+
+
Active Breakpoint:
+
+
+ base
+
+ = 475 &&
+ viewport.width < 640 &&
+ 'bg-primary text-primary-foreground'
+ )}
+ >
+ xs
+
+ = 640 &&
+ viewport.width < 768 &&
+ 'bg-primary text-primary-foreground'
+ )}
+ >
+ sm
+
+ = 768 &&
+ viewport.width < 1024 &&
+ 'bg-primary text-primary-foreground'
+ )}
+ >
+ md
+
+ = 1024 &&
+ viewport.width < 1280 &&
+ 'bg-primary text-primary-foreground'
+ )}
+ >
+ lg
+
+ = 1280 &&
+ viewport.width < 1536 &&
+ 'bg-primary text-primary-foreground'
+ )}
+ >
+ xl
+
+ = 1536 && 'bg-primary text-primary-foreground'
+ )}
+ >
+ 2xl
+
+
+
+ )}
+
+ {/* Performance metrics */}
+ {showPerformance && (
+
+
FPS: {performanceMetrics.fps}
+ {performanceMetrics.memory > 0 &&
Memory: {performanceMetrics.memory} MB
}
+
Layout Shifts: {performanceMetrics.layoutShifts}
+
+ )}
+
+ {/* Toggle options */}
+
+
+
+
+
+
+
Press Ctrl+Shift+D to toggle
+
+ {children}
+
+ {/* Install prompt for PWA - Mobile-first responsive design */}
+ {showInstallPrompt && deferredPrompt && !isPWAInstalled && (
+
+
+
Install App
+
+ Install this app on your device for a better experience
+
+
+
+
+
+
+
+ )}
+
Content
+
+
+// With size variants
+Small container (max-w-2xl)
+Large container (max-w-6xl)
+
+// Disable container queries
+
+ Static container
+
+```
+
+### 2. Grid Component
+
+Intelligent grid system with automatic responsive behavior:
+
+```tsx
+import { Grid, GridItem } from '@/components/layout/Grid'
+
+// Responsive grid with container queries
+
+ Item 1
+ Item 2
+ Item 3
+
+
+// Auto-fit grid
+
+ Auto-sized item
+ Auto-sized item
+
+
+// Grid with custom items
+
+ Main content
+ Sidebar
+
+```
+
+### 3. Stack Component
+
+Flexible layout component for vertical/horizontal stacking:
+
+```tsx
+import { Stack, Spacer } from '@/components/layout/Stack'
+
+// Vertical stack (default)
+
+ Item 1
+ Item 2
+ Item 3
+
+
+// Horizontal stack with spacer
+
+ Left
+
+ Right
+
+
+// Responsive stack
+
+ Adapts to viewport
+ Changes direction
+
+```
+
+### 4. Typography Component
+
+Fluid typography with responsive scaling:
+
+```tsx
+import { Typography, Heading, Text } from '@/components/layout/Typography'
+
+// Responsive headings
+
+ Fluid Heading
+
+
+// Custom styling
+
+ Styled text
+
+
+// Convenience components
+Section Title
+Description text
+```
+
+### 5. ResponsiveImage Component
+
+Performance-optimized image loading with adaptive strategies:
+
+```tsx
+import { ResponsiveImage } from '@/components/layout/ResponsiveImage'
+
+// Basic responsive image
+
+
+// With adaptive loading
+
+
+// Art-directed images
+
+```
+
+## Utility Hooks
+
+### useViewport()
+
+Detect current viewport size and device type:
+
+```tsx
+const { width, height, isMobile, isTablet, isDesktop } = useViewport()
+
+if (isMobile) {
+ return
+}
+```
+
+### useDeviceCapabilities()
+
+Detect device capabilities for adaptive features:
+
+```tsx
+const { isTouch, networkSpeed, deviceMemory } = useDeviceCapabilities()
+
+if (networkSpeed === 'slow') {
+ return
+}
+```
+
+### useResponsiveValue()
+
+Get viewport-aware values:
+
+```tsx
+const columns = useResponsiveValue({
+ base: 1,
+ sm: 2,
+ lg: 3,
+ xl: 4,
+})
+```
+
+## Adaptive Loading
+
+### AdaptiveLoader Component
+
+Load components based on conditions:
+
+```tsx
+import { AdaptiveLoader } from '@/components/layout/AdaptiveLoader'
+
+// Load on viewport visibility
+
+
+
+
+// Load on user interaction
+
+
+
+
+// Load when idle
+
+
+
+```
+
+### DynamicComponent
+
+Dynamic imports with loading strategies:
+
+```tsx
+import { DynamicComponent } from '@/components/layout/AdaptiveLoader'
+; import('./Chart')}
+ loadOn='visible'
+ fallback={}
+/>
+```
+
+## Core Web Vitals Optimization
+
+### WebVitals Component
+
+Monitor performance metrics:
+
+```tsx
+import { WebVitals } from '@/components/layout/WebVitals'
+
+// Development monitoring
+
+
+// Production monitoring
+ {
+ // Send to analytics
+ analytics.track('web-vitals', metrics)
+ }}
+/>
+```
+
+### Layout Shift Prevention
+
+Prevent cumulative layout shift:
+
+```tsx
+import { LayoutStable } from '@/components/layout/WebVitals'
+
+// Fixed dimensions
+
+
+
+
+// Aspect ratio
+
+
+
+```
+
+## PWA Features
+
+### PWALayout Component
+
+PWA-optimized layout with safe areas:
+
+```tsx
+import { PWALayout } from '@/components/layout/PWALayout'
+;
+
+
+```
+
+### usePWAFeatures Hook
+
+Detect PWA capabilities:
+
+```tsx
+const { isInstalled, canInstall, hasShareSupport } = usePWAFeatures()
+
+if (hasShareSupport) {
+ navigator.share({ title, text, url })
+}
+```
+
+## Layout Debugging
+
+### LayoutDebugger Component
+
+Visual debugging tools for development:
+
+```tsx
+import { LayoutDebugger } from '@/components/layout/LayoutDebugger'
+
+// Add to app during development
+;
+```
+
+Press `Ctrl+Shift+D` to toggle the debugger.
+
+## CSS Utilities
+
+### Viewport-Aware Spacing
+
+```css
+/* Fluid padding/margin */
+.p-fluid /* Responsive padding */
+.px-fluid /* Horizontal padding */
+.py-fluid /* Vertical padding */
+.m-fluid /* Responsive margin */
+.gap-fluid /* Responsive gap */
+
+/* Safe area utilities */
+.safe-area-container /* All safe areas */
+.px-viewport /* Viewport-aware horizontal padding */
+.py-viewport /* Viewport-aware vertical padding */
+
+/* Touch targets */
+.touch-responsive /* Responsive touch target sizes */
+.touch-target /* Minimum 44px touch target */
+```
+
+### Container Queries
+
+Enable container queries on any element:
+
+```tsx
+
+
+ Responsive to container size
+
+
+ {shouldRenderImage && (
+
0 ? { blurDataURL } : {})}
+ onLoad={handleLoad}
+ onError={handleError}
+ className={cn(
+ 'transition-opacity duration-300',
+ isLoading ? 'opacity-0' : 'opacity-100',
+ hasError && 'opacity-50',
+ className
+ )}
+ />
+ )}
+
+ {/* Loading skeleton */}
+ {isLoading && placeholder === 'skeleton' && (
+
+ )}
+
+ {/* Error state */}
+ {hasError && fallback == null && (
+
+ )}
+
+
+ {sources.map((source, index) => (
+
+ ))}
+
+
+
} {...elementProps} />
+ case 'section':
+ return
} {...elementProps} />
+ case 'article':
+ return } {...elementProps} />
+ case 'main':
+ return } {...elementProps} />
+ case 'aside':
+ return