bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/webgl/components/ui/README.md

@@ -0,0 +1,77 @@
+# Components
+
+UI components organized by purpose.
+
+```
+components/
+├── ui/        → Primitives (reusable across projects)
+├── layout/    → Site chrome (customize per project)
+└── magic/   → Animation & visual enhancements
+```
+
+## Direct Imports (Recommended)
+
+```tsx
+// UI Components - import directly for better clarity
+import { Image } from '@/components/ui/image'
+import { Link } from '@/components/ui/link'
+
+// Layout Components
+import { Wrapper } from '@/components/layout/wrapper'
+import { Header } from '@/components/layout/header' 
+import { Footer } from '@/components/layout/footer'
+
+// Magic Components
+import { Marquee } from '@/components/magic/marquee'
+```
+
+## UI Components
+
+| Component | Purpose |
+|-----------|---------|
+| `image/` | Optimized images (always use this, never `next/image`) |
+| `link/` | Smart navigation (auto-detects external) |
+
+## Layout Components
+
+| Component | Purpose |
+|-----------|---------|
+| `wrapper/` | Page wrapper (theme, WebGL, Lenis) |
+| `header/` | Site header/navigation |
+| `footer/` | Site footer |
+| `lenis/` | Smooth scrolling |
+
+```tsx
+<Wrapper theme="dark" webgl lenis>
+  <section>Your content</section>
+</Wrapper>
+```
+
+## Effects Components
+
+| Component | Purpose |
+|-----------|---------|
+| `marquee/` | Infinite scrolling text |
+
+## Best Practices
+
+```tsx
+// ✅ Always use custom Image
+import { Image } from '@/components/ui/image'
+<Image src="/photo.jpg" alt="Photo" aspectRatio={16/9} />
+
+// ✅ Always use custom Link
+import { Link } from '@/components/ui/link'
+<Link href="/about">Internal</Link>
+<Link href="https://example.com">External</Link>
+
+// ✅ CSS Modules + Tailwind
+import s from './component.module.css'
+<div className={cn(s.wrapper, 'flex items-center')} />
+```
+
+## Related
+
+- [Image docs](ui/image/README.md)
+- [Real Viewport docs](ui/real-viewport/README.md)
+- [WebGL Components](../lib/webgl/README.md)

package/packages/create-basement-app/templates/webgl/components/ui/image/README.md

@@ -0,0 +1,37 @@
+# Image Component
+
+Optimized images with smart loading, blur placeholders, and responsive sizing.
+
+## Usage
+
+```tsx
+import { Image } from '@/components/ui/image'
+
+// Basic
+<Image src="/hero.jpg" alt="Hero" aspectRatio={16/9} />
+
+// Priority (LCP images)
+<Image src="/hero.jpg" alt="Hero" aspectRatio={16/9} priority />
+
+// Responsive
+<Image 
+  src="/product.jpg" 
+  alt="Product" 
+  mobileSize="100vw" 
+  desktopSize="33vw" 
+/>
+```
+
+## Props
+
+| Prop | Description |
+|------|-------------|
+| `aspectRatio` | Prevents layout shift, enables blur placeholder |
+| `priority` | Eager loading for above-the-fold images |
+| `mobileSize` / `desktopSize` | Responsive sizing |
+
+## Best Practices
+
+- Always provide `aspectRatio` (prevents CLS)
+- Use `priority` for LCP images
+- Never use `next/image` directly

package/packages/create-basement-app/templates/webgl/components/ui/image/index.tsx

@@ -0,0 +1,224 @@
+/**
+ * Enhanced Image Component
+ *
+ * Next.js Image wrapper with optimized defaults and error handling.
+ * Always use this component instead of next/image directly.
+ */
+"use client"
+
+import cn from "clsx"
+import NextImage, { type ImageProps as NextImageProps } from "next/image"
+import type { CSSProperties, Ref } from "react"
+import { breakpoints } from "@/lib/styles/config"
+import s from "./image.module.css"
+
+/**
+ * Enhanced Image component props extending Next.js Image.
+ *
+ * Adds responsive sizing, aspect ratio support, and automatic blur placeholders.
+ * Always use this component instead of next/image directly.
+ */
+export type ImageProps = Omit<NextImageProps, "objectFit" | "alt"> & {
+  /** CSS object-fit property for image positioning */
+  objectFit?: CSSProperties["objectFit"]
+  /** Display as block element (adds display: block) */
+  block?: boolean
+  /** Size on mobile devices (e.g., "100vw", "50vw") */
+  mobileSize?: `${number}vw`
+  /** Size on desktop devices (e.g., "33vw", "25vw") */
+  desktopSize?: `${number}vw`
+  /** Ref for accessing the underlying img element */
+  ref?: Ref<HTMLImageElement>
+  /** Alt text for accessibility (required for meaningful images) */
+  alt?: string
+  /** Aspect ratio for automatic placeholder and layout stability */
+  aspectRatio?: number
+}
+
+// Memoize helper functions to avoid recreation
+const toBase64 = (str: string) =>
+  typeof window === "undefined"
+    ? Buffer.from(str).toString("base64")
+    : window.btoa(str)
+
+// Helper to generate blur placeholder with transparent background by default
+const generateShimmer = (w: number, h: number) => `
+  <svg width="${w}" height="${h}" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <defs>
+      <linearGradient id="g">
+        <stop stop-color="rgba(255,255,255,0.1)" offset="20%" />
+        <stop stop-color="rgba(255,255,255,0.2)" offset="50%" />
+        <stop stop-color="rgba(255,255,255,0.1)" offset="70%" />
+      </linearGradient>
+    </defs>
+    <rect width="${w}" height="${h}" fill="rgba(0,0,0,0)" />
+    <rect id="r" width="${w}" height="${h}" fill="url(#g)" />
+    <animate xlink:href="#r" attributeName="x" from="-${w}" to="${w}" dur="1s" repeatCount="indefinite"  />
+  </svg>`
+
+// Helper to determine if blur placeholder should be used
+const shouldUseBlurPlaceholder = (
+  src: NextImageProps["src"],
+  placeholder: string,
+  blurDataURL: string | undefined
+): boolean => {
+  if (!src) return false
+  const isSvg = typeof src === "string" && src.includes(".svg")
+  return !isSvg && placeholder === "blur" && !blurDataURL
+}
+
+// Helper to generate blur data URL
+const generateBlurDataURL = (
+  shouldUse: boolean,
+  aspectRatio: number | undefined,
+  existingBlurDataURL: string | undefined
+): string | undefined => {
+  if (!(shouldUse && aspectRatio)) return existingBlurDataURL
+
+  const shimmerSvg = generateShimmer(700, Math.round(700 / aspectRatio))
+  return `data:image/svg+xml;base64,${toBase64(shimmerSvg)}`
+}
+
+// Helper to determine final placeholder value
+const getFinalPlaceholder = (
+  shouldUse: boolean,
+  aspectRatio: number | undefined,
+  blurDataURL: string | undefined,
+  originalPlaceholder: NextImageProps["placeholder"]
+): NextImageProps["placeholder"] => {
+  if (!shouldUse) {
+    return originalPlaceholder === "blur" && !blurDataURL
+      ? "empty"
+      : originalPlaceholder
+  }
+
+  return aspectRatio || blurDataURL ? "blur" : "empty"
+}
+
+/**
+ * Enhanced Image component with responsive sizing and automatic optimizations.
+ *
+ * Always use this component instead of next/image directly. Provides:
+ * - Automatic responsive sizes generation
+ * - Smart blur placeholders with aspect ratio support
+ * - Performance optimizations (lazy loading by default)
+ * - Preload for LCP images
+ *
+ * @param props - Image props extending Next.js Image
+ * @param props.aspectRatio - Aspect ratio for layout stability and blur placeholder
+ * @param props.mobileSize - Size on mobile (e.g., "100vw")
+ * @param props.desktopSize - Size on desktop (e.g., "50vw")
+ * @param props.block - Display as block element
+ * @param props.preload - Enable preloading for LCP images
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with aspect ratio
+ * <Image
+ *   src="/hero.jpg"
+ *   alt="Hero image"
+ *   aspectRatio={16/9}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // LCP image with preload
+ * <Image
+ *   src="/hero.jpg"
+ *   alt="Hero image"
+ *   aspectRatio={16/9}
+ *   preload // Preloads image for LCP
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Responsive grid image
+ * <Image
+ *   src="/product.jpg"
+ *   alt="Product"
+ *   aspectRatio={1}
+ *   mobileSize="100vw"
+ *   desktopSize="33vw"
+ * />
+ * ```
+ */
+export function Image({
+  style,
+  className,
+  loading,
+  objectFit = "cover",
+  quality = 90,
+  alt = "",
+  fill,
+  block = !fill,
+  width = block ? 1 : undefined,
+  height = block ? 1 : undefined,
+  mobileSize = "100vw",
+  desktopSize = "100vw",
+  sizes,
+  src,
+  unoptimized,
+  ref,
+  aspectRatio,
+  placeholder = "blur",
+  preload = false,
+  ...props
+}: ImageProps) {
+  // Determine loading strategy
+  const finalLoading = loading ?? (preload ? "eager" : "lazy")
+
+  // Generate responsive sizes if not provided
+  const finalSizes =
+    sizes ||
+    `(max-width: ${breakpoints.desktop}px) ${mobileSize}, ${desktopSize}`
+
+  // Early return after hooks
+  if (!src) return null
+
+  // Determine SVG status and placeholder logic
+  const isSvg = typeof src === "string" && src.includes(".svg")
+  const shouldUsePlaceholder = shouldUseBlurPlaceholder(
+    src,
+    placeholder,
+    props.blurDataURL
+  )
+  const blurDataURL = generateBlurDataURL(
+    shouldUsePlaceholder,
+    aspectRatio,
+    props.blurDataURL
+  )
+  const finalPlaceholder = getFinalPlaceholder(
+    shouldUsePlaceholder,
+    aspectRatio,
+    props.blurDataURL,
+    placeholder
+  )
+
+  return (
+    <NextImage
+      ref={ref}
+      fill={!block}
+      {...(width !== undefined && { width })}
+      {...(height !== undefined && { height })}
+      loading={finalLoading}
+      quality={quality}
+      alt={alt}
+      style={{
+        objectFit,
+        ...style,
+      }}
+      className={cn(className, block && s.block)}
+      sizes={finalSizes}
+      src={src}
+      unoptimized={unoptimized || isSvg}
+      draggable={false}
+      onDragStart={(e) => e.preventDefault()}
+      {...(finalPlaceholder && { placeholder: finalPlaceholder })}
+      {...(blurDataURL && { blurDataURL })}
+      preload={preload}
+      {...props}
+    />
+  )
+}

package/packages/create-basement-app/templates/webgl/components/ui/link/index.tsx

@@ -0,0 +1,146 @@
+"use client"
+
+import NextLink from "next/link"
+import { usePathname } from "next/navigation"
+import {
+  type AnchorHTMLAttributes,
+  type ComponentProps,
+  type MouseEvent,
+  useEffect,
+  useState,
+} from "react"
+
+// Helper to extract props safe for button elements
+function getButtonProps(props: Record<string, unknown>) {
+  const {
+    href,
+    target,
+    rel,
+    "data-external": _dataExternal,
+    ...buttonProps
+  } = props
+  return buttonProps
+}
+
+// Helper to extract props safe for div elements
+function getDivProps(props: Record<string, unknown>) {
+  const {
+    href,
+    target,
+    rel,
+    onClick,
+    "data-external": _dataExternal,
+    ...divProps
+  } = props
+  return divProps
+}
+
+type CustomLinkProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  keyof ComponentProps<typeof NextLink> | "href"
+> &
+  Omit<ComponentProps<typeof NextLink>, "href"> & {
+    href?: string
+    onClick?: (e: MouseEvent<HTMLElement>) => void
+    scroll?: boolean
+  }
+
+export function Link({
+  href,
+  children,
+  onClick,
+  scroll = false, // Default to false to prevent scroll restoration warnings with fixed/sticky elements
+  ...props
+}: CustomLinkProps) {
+  const [shouldPrefetch, setShouldPrefetch] = useState(false)
+  const [isExternal, setIsExternal] = useState(false)
+  const [isActive, setIsActive] = useState(false)
+
+  // Get pathname - deferred to avoid blocking static generation
+  // usePathname is safe to call but we defer the active check to useEffect
+  const pathname = usePathname()
+
+  useEffect(() => {
+    // Check if this link is active (current page)
+    if (href && pathname) {
+      setIsActive(pathname === href)
+    }
+  }, [href, pathname])
+
+  useEffect(() => {
+    // Skip if no href
+    if (!href) return
+
+    // Check if external link
+    try {
+      const url = new URL(href, window.location.href)
+      setIsExternal(url.host !== window.location.host)
+    } catch {
+      setIsExternal(false)
+    }
+
+    // Only prefetch on good connections
+    const connection = (
+      navigator as Navigator & {
+        connection?: { effectiveType: string; saveData: boolean }
+      }
+    ).connection
+    if (connection) {
+      const { effectiveType, saveData } = connection
+      setShouldPrefetch(effectiveType === "4g" && !saveData)
+    } else {
+      // Default to prefetching if API not available
+      setShouldPrefetch(true)
+    }
+  }, [href])
+
+  // If no href is provided but there's an onClick, render a button
+  if (!href && onClick) {
+    return (
+      <button
+        onClick={(e: MouseEvent<HTMLButtonElement>) => onClick(e)}
+        type="button"
+        {...getButtonProps(props)}
+      >
+        {children}
+      </button>
+    )
+  }
+
+  // If no href and no onClick, render a div
+  if (!href) {
+    return <div {...getDivProps(props)}>{children}</div>
+  }
+
+  // For SSR, check if it's external based on the href pattern
+  const isExternalSSR =
+    href.startsWith("http://") || href.startsWith("https://")
+
+  if (isExternalSSR || isExternal) {
+    return (
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        data-external
+        onClick={onClick}
+        {...props}
+      >
+        {children}
+      </a>
+    )
+  }
+
+  return (
+    <NextLink
+      href={href as ComponentProps<typeof NextLink>["href"]}
+      prefetch={shouldPrefetch}
+      scroll={scroll}
+      data-active={isActive || undefined}
+      {...(onClick && { onClick })}
+      {...props}
+    >
+      {children}
+    </NextLink>
+  )
+}

package/packages/create-basement-app/templates/webgl/components/webgl/canvas/dynamic.tsx

@@ -0,0 +1,34 @@
+"use client"
+
+import dynamic from "next/dynamic"
+import { Suspense, useRef } from "react"
+import { cn } from "@/lib/styles/cn"
+
+const WebGLCanvas = dynamic(() => import("./index"), {
+  ssr: false,
+})
+
+export default function DynamicCanvas() {
+  const eventSourceRef = useRef<HTMLDivElement>(null)
+
+  return (
+    <div
+      ref={eventSourceRef}
+      className={cn(
+        "pointer-events-none fixed top-0 left-0 z-50 h-lvh w-full overflow-hidden"
+      )}
+    >
+      <Suspense
+        fallback={
+          <div className="flex h-full w-full items-center justify-center bg-black/10">
+            <span className="font-mono text-xs uppercase tracking-widest opacity-30">
+              Loading WebGL...
+            </span>
+          </div>
+        }
+      >
+        <WebGLCanvas eventSource={eventSourceRef} />
+      </Suspense>
+    </div>
+  )
+}

package/packages/create-basement-app/templates/webgl/components/webgl/canvas/index.tsx

@@ -0,0 +1,43 @@
+"use client"
+
+import { Preload } from "@react-three/drei"
+import { Canvas } from "@react-three/fiber"
+import dynamic from "next/dynamic"
+
+import { cn } from "@/lib/styles/cn"
+
+const Scene = dynamic(
+  () =>
+    import("@/components/webgl/components/scene").then((mod) => mod.default),
+  {
+    ssr: false,
+  }
+)
+
+export default function WebGLCanvas({ ...props }) {
+  return (
+    <Canvas
+      className={cn("pointer-events-none h-lvh! w-full")}
+      dpr={[1, 2]}
+      eventPrefix="client"
+      frameloop="always"
+      camera={{
+        far: 1000,
+        near: 0.01,
+        fov: 16,
+        position: [0, 17, 350],
+      }}
+      gl={{
+        alpha: true,
+        antialias: true,
+        logarithmicDepthBuffer: true,
+        powerPreference: "high-performance",
+        premultipliedAlpha: true,
+      }}
+      {...props}
+    >
+      <Scene />
+      <Preload all />
+    </Canvas>
+  )
+}

package/packages/create-basement-app/templates/webgl/components/webgl/components/scene/index.tsx

@@ -0,0 +1,21 @@
+import { useFrame } from "@react-three/fiber"
+import { useRef } from "react"
+import type { Mesh } from "three"
+
+const Scene = () => {
+  const meshRef = useRef<Mesh>(null)
+
+  useFrame((_state, delta) => {
+    meshRef.current.rotation.x += delta
+    meshRef.current.rotation.y += delta
+  })
+
+  return (
+    <mesh ref={meshRef} scale={10}>
+      <boxGeometry />
+      <meshBasicMaterial color="orange" />
+    </mesh>
+  )
+}
+
+export default Scene

package/packages/create-basement-app/templates/webgl/lib/README.md

@@ -0,0 +1,33 @@
+# Lib
+
+Non-UI code: hooks, integrations, styles, and utilities.
+
+> **Rule**: Renders UI → `components/` · Everything else → `lib/`
+
+## Quick Imports
+
+```tsx
+// Utilities - explicit imports for better tree-shaking
+import { clamp, lerp } from '@/lib/utils/math'
+import { slugify } from '@/lib/utils/strings'
+
+// Styles
+import { colors, themes, breakpoints } from '@/lib/styles/config'
+```
+
+## Directories
+
+| Directory | Purpose | Optional? |
+|-----------|---------|-----------|
+| [hooks/](hooks/README.md) | React hooks + Zustand store | ❌ Core |
+| [styles/](styles/README.md) | CSS & Tailwind config | ❌ Core |
+| [utils/](utils/README.md) | Pure utility functions | ❌ Core |
+
+## Scripts
+
+```bash
+bun dev              # Start dev server
+bun run generate     # Generate pages/components
+bun run setup:project  # Configure integrations
+bun setup:styles     # Regenerate CSS
+```

package/packages/create-basement-app/templates/webgl/lib/hooks/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Custom React Hooks
+ *
+ * Import individual hooks:
+ *   import { useDeviceDetection } from '@/hooks/use-device-detection'
+ *
+ * Or import from barrel:
+ *   import { useDeviceDetection, usePrefetch } from '@/hooks/use-device-detection'
+ */
+
+export { useDeviceDetection } from "./use-device-detection"
+export { usePrefetch } from "./use-prefetch"