bsmnt 0.2.9 → 0.2.10

package/src/templates/next-webgl/README.md

@@ -1,221 +1,51 @@
-# Basement Next Starter
+# Basement Next WebGL Starter
 
-A production-ready Next.js starter with React 19, Tailwind CSS v4, TypeScript strict mode, and everything you need to build modern web applications.
-
-## Tech Stack
-
-| Technology | Version | Description |
-|------------|---------|-------------|
-| Next.js | 16.1 | App Router, Turbopack |
-| React | 19 | React Compiler enabled |
-| TypeScript | 5.9 | Strict mode, `noUncheckedIndexedAccess` |
-| Tailwind CSS | 4 | CSS-first configuration |
-| Biome | 2.3 | Linting and formatting |
-| Bun | 1.3 | Package manager and runtime |
-| Zustand | 5.0 | State management |
+Minimal Next.js starter with Tailwind CSS, WebGL helpers, TypeScript, and Basement defaults.
 
 ## Quick Start
 
 ```bash
-# Clone the template
-bunx degit basementstudio/next-starter my-project
-
-# Install dependencies
-cd my-project && bun install
-
-# Start development
+bun install
 bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) to see the result.
-
 ## Scripts
 
 | Command | Description |
 |---------|-------------|
-| `bun dev` | Start development server with Turbopack |
-| `bun dev:https` | Start with HTTPS (for secure contexts) |
+| `bun dev` | Start the development server |
+| `bun dev:https` | Start the development server with HTTPS |
 | `bun build` | Build for production |
-| `bun start` | Start production server |
-| `bun generate` | Scaffold new components/hooks |
-| `bun lint` | Run Biome linter |
-| `bun lint:fix` | Fix lint issues |
-| `bun format` | Format code with Biome |
-| `bun typecheck` | Type check with tsgo |
-| `bun test` | Run tests with Bun |
-| `bun analyze` | Analyze bundle size |
+| `bun start` | Start the production server |
+| `bun lint` | Run Biome |
+| `bun lint:fix` | Run Biome with fixes |
+| `bun format` | Format the codebase |
+| `bun typecheck` | Run TypeScript |
+| `bun analyze` | Analyze the Next.js bundle |
 
 ## Project Structure
 
-```
-app/                     # Next.js App Router pages and routes
-  ├── api/               # API routes (draft-mode, revalidate)
-  ├── layout.tsx         # Root layout with metadata, fonts
-  ├── page.tsx           # Homepage
-  ├── sitemap.ts         # Dynamic sitemap generation
-  └── robots.ts          # SEO robots.txt
-
+```txt
+app/
 components/
-  ├── layout/
-  │   ├── header/        # Navigation header
-  │   ├── footer/        # Page footer
-  │   ├── wrapper/       # Page wrapper with theme
-  │   └── theme/         # Theme context provider
-  └── ui/
-      ├── image/         # Enhanced Next.js Image wrapper
-      └── link/          # Smart Link component
-
+  webgl/
 lib/
-  ├── hooks/                      # Custom React hooks
-  │   ├── use-device-detection/   # Device/capability detection
-  │   ├── use-media-breakpoint/   # Responsive breakpoint hook
-  │   └── use-prefetch/           # Prefetch utilities
-  ├── integrations/               # Third-party integrations
-  ├── scripts/                    # Build and dev scripts
-  ├── store/                      # Zustand global state
-  ├── styles/                     # Design tokens, CSS config
-  │   ├── colors.ts               # Theme colors
-  │   ├── layout.mjs              # Breakpoints, grid, spacing
-  │   ├── easings.ts              # CSS easing variables
-  │   └── fonts.ts                # Font loading (Geist Mono)
-  └── utils/                      # Utility functions
-      ├── easings.ts              # 30+ animation easing functions
-      ├── math.ts                 # Math utilities
-      ├── strings.ts              # String utilities
-      └── fetch.ts                # Fetch utilities
-```
-
-## Features
-
-### Design System
-
-Pre-configured design tokens ready to use:
-
-**Breakpoints:**
-- `mobile`: 375px
-- `tablet`: 620px
-- `tablet-lg`: 1024px
-- `desktop`: 1440px
-- `desktop-large`: 1920px
-
-**Grid:**
-- Mobile: 4 columns
-- Desktop: 12 columns
-- Gap: 16px
-
-**Colors:**
-- Theme colors: `primary`, `secondary`, `contrast`
-- Accent colors: `red`, `blue`, `green`, `violet`, `pink`
-- Light/dark mode support
-
-**Easings:**
-30+ easing functions (quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce)
-
-### Smart Components
-
-**`<Image>`** - Enhanced Next.js Image wrapper:
-- Automatic responsive sizes based on breakpoints
-- Blur placeholder with shimmer effect
-- Preload support for LCP images
-- SVG handling
-
-**`<Link>`** - Intelligent link component:
-- Auto-detects external links (opens in new tab)
-- Connection-aware prefetching (4G only, respects data saver)
-- Falls back to button/div when no href
-- Active state detection
-
-**`<Wrapper>`** - Page layout component:
-- Includes Header and Footer
-- Theme provider integration
-- Flexible content area
-
-### Theme Support
-
-Light/dark theme with CSS custom properties:
-
-```tsx
-import { Wrapper } from "@/components/layout/wrapper"
-
-export default function Page() {
-  return (
-    <Wrapper theme="dark">
-      <section>Your content</section>
-    </Wrapper>
-  )
-}
+  hooks/
+  integrations/
+  scripts/
+  store/
+  styles/
+    index.css
+    tokens.css
+    global.css
+    fonts.ts
+    cn.ts
+  utils/
 ```
 
-Access theme in components:
-
-```tsx
-import { useTheme } from "@/components/layout/theme"
-
-function Component() {
-  const { name, setThemeName } = useTheme()
-  // ...
-}
-```
-
-### Performance Optimizations
-
-- **React Compiler** - Automatic memoization (no manual `useMemo`/`useCallback`)
-- **Turbopack** - Fast development builds
-- **Bundle Analyzer** - `bun analyze` to inspect bundle size
-- **Optimized Imports** - Auto-optimization for GSAP, Three.js, Lenis, Zustand
-- **Security Headers** - CSP, HSTS, XSS protection pre-configured
-- **Image Optimization** - AVIF, WebP with custom quality settings
-
-### Developer Experience
-
-- **Component Scaffolding** - `bun generate` to create components/hooks
-- **HTTPS Dev Server** - `bun dev:https` for secure contexts
-- **Strict TypeScript** - `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
-- **Biome** - Fast linting and formatting with custom rules
-- **Tests** - Bun test runner with utilities
-
-## Configuration
-
-### Styles
-
-Edit design tokens in `lib/styles/`:
-
-- `colors.ts` - Theme and accent colors
-- `layout.mjs` - Breakpoints, grid, spacing
-- `typography.ts` - Font definitions
-- `easings.ts` - CSS easing variables
-
-After editing, regenerate CSS:
-
-```bash
-bun setup:styles
-```
-
-### Next.js
-
-Configuration in `next.config.ts`:
-
-- React Compiler enabled
-- Typed routes
-- SVG loader (@svgr/webpack)
-- Security headers
-- Image optimization settings
-
-## Deployment
-
-### Vercel (Recommended)
-
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/basementstudio/next-starter)
-
-### Other Platforms
-
-```bash
-bun build
-bun start
-```
-
-The app runs on port 3000 by default.
-
-## License
+## Styling
 
-MIT
+- Import `@/lib/styles/index.css` once in `app/layout.tsx`.
+- Edit `lib/styles/tokens.css` for theme variables, breakpoints, and custom Tailwind utilities.
+- Edit `lib/styles/global.css` for reset rules and app-wide global styles.
+- `lib/styles/fonts.ts` handles font variables.

package/src/templates/next-webgl/app/layout.tsx

@@ -2,10 +2,9 @@ import type { Metadata, Viewport } from "next";
 import { Geist } from "next/font/google";
 import { type PropsWithChildren, Suspense } from "react";
 import { Link } from "@/components/ui/link";
-import { themes } from "@/lib/styles/colors";
 import { fontsVariable } from "@/lib/styles/fonts";
 import AppData from "@/package.json";
-import "@/lib/styles/css/index.css";
+import "@/lib/styles/index.css";
 import { cn } from "@/lib/styles/cn";
 
 const APP_NAME = AppData.name;
@@ -74,7 +73,7 @@ export const metadata: Metadata = {
 
 export const viewport: Viewport = {
   colorScheme: "normal",
-  themeColor: themes.dark.primary,
+  themeColor: "#000000",
 };
 
 export default async function Layout({ children }: PropsWithChildren) {

package/src/templates/next-webgl/biome.json

@@ -214,20 +214,7 @@
       }
     },
     {
-      "includes": ["**/*.module.css"],
-      "linter": {
-        "rules": {
-          "correctness": {
-            "noUnknownProperty": "off"
-          },
-          "style": {
-            "noDescendingSpecificity": "off"
-          }
-        }
-      }
-    },
-    {
-      "includes": ["lib/styles/css/root.css"],
+      "includes": ["lib/styles/tokens.css"],
       "linter": {
         "rules": {
           "suspicious": {

package/src/templates/next-webgl/components/layout/theme/index.tsx

@@ -2,16 +2,14 @@
 
 import { usePathname } from "next/navigation"
 import { createContext, useContext, useEffect, useState } from "react"
-import type { Themes } from "@/lib/styles/colors"
-import { type ThemeName, themes } from "@/lib/styles/config"
+
+export type ThemeName = "light" | "dark"
 
 export const ThemeContext = createContext<{
   name: ThemeName
-  theme: Themes[ThemeName]
   setThemeName: (theme: ThemeName) => void
 }>({
   name: "light",
-  theme: themes.light,
   setThemeName: () => {
     void 0
   },
@@ -55,7 +53,6 @@ export function Theme({
       <ThemeContext.Provider
         value={{
           name: currentTheme,
-          theme: themes[currentTheme],
           setThemeName: setCurrentTheme,
         }}
       >

package/src/templates/next-webgl/components/layout/wrapper/index.tsx

@@ -6,8 +6,7 @@
 import cn from "clsx"
 import { Footer } from "@/components/layout/footer"
 import { Header } from "@/components/layout/header"
-import { Theme } from "@/components/layout/theme"
-import type { ThemeName } from "@/lib/styles/config"
+import { Theme, type ThemeName } from "@/components/layout/theme"
 
 /**
  * Props for the Wrapper component.

package/src/templates/next-webgl/components/ui/README.md

@@ -65,9 +65,8 @@ 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')} />
+// ✅ Tailwind only
+<div className="flex items-center" />
 ```
 
 ## Related

package/src/templates/next-webgl/components/ui/image/index.tsx

@@ -9,7 +9,8 @@
 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"
+
+const DESKTOP_BREAKPOINT = 1440
 
 /**
  * Enhanced Image component props extending Next.js Image.
@@ -166,8 +167,7 @@ export function Image({
 }: ImageProps) {
   // Generate responsive sizes if not provided
   const finalSizes =
-    sizes ||
-    `(max-width: ${breakpoints.desktop}px) ${mobileSize}, ${desktopSize}`
+    sizes || `(max-width: ${DESKTOP_BREAKPOINT}px) ${mobileSize}, ${desktopSize}`
 
   // Early return after hooks
   if (!src) return null

package/src/templates/next-webgl/lib/README.md

@@ -27,7 +27,7 @@ import { colors, themes, breakpoints } from '@/lib/styles/config'
 
 ```bash
 bun dev              # Start dev server
-bun run generate     # Generate pages/components
-bun run setup:project  # Configure integrations
-bun setup:styles     # Regenerate CSS
+bun build            # Create production build
+bun lint:fix         # Fix lint issues
+bun typecheck        # Run type checks
 ```

package/src/templates/next-webgl/lib/hooks/use-device-detection.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react"
 import { useMedia } from "react-use"
-import { breakpoints } from "@/lib/styles/config"
+
+const MOBILE_BREAKPOINT = 640
 
 /**
  * Hook for detecting device capabilities and characteristics.
@@ -58,7 +59,7 @@ import { breakpoints } from "@/lib/styles/config"
  * ```
  */
 export function useDeviceDetection() {
-  const isMobile = useMedia(`(max-width: ${breakpoints.mobile - 1}px)`, true)
+  const isMobile = useMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`, true)
   const isReducedMotion = useMedia("(prefers-reduced-motion: reduce)")
   const [dpr, setDpr] = useState<number | undefined>(undefined)
   const [isSafari, setIsSafari] = useState<boolean | undefined>(undefined)

package/src/templates/next-webgl/lib/hooks/use-media-breakpoint.ts

@@ -1,5 +1,12 @@
 import { useMedia } from "react-use"
-import { breakpoints } from "@/lib/styles/config"
+
+const BREAKPOINTS = {
+  "desktop-large": 1920,
+  desktop: 1440,
+  "tablet-lg": 1024,
+  tablet: 768,
+  mobile: 640,
+} as const
 
 /**
  * Hook for detecting if the viewport is at a specific breakpoint.
@@ -8,8 +15,8 @@ import { breakpoints } from "@/lib/styles/config"
  * @returns True if the viewport is at the breakpoint
  */
 export function useMediaBreakpoint(
-  breakpoint: keyof typeof breakpoints,
+  breakpoint: keyof typeof BREAKPOINTS,
   defaultState = false
 ) {
-  return useMedia(`(min-width: ${breakpoints[breakpoint]}px)`, defaultState)
+  return useMedia(`(min-width: ${BREAKPOINTS[breakpoint]}px)`, defaultState)
 }

package/src/templates/next-webgl/lib/scripts/dev.ts

@@ -1,7 +1,5 @@
 /**
- * Cross-platform parallel dev script
- * Replaces npm-run-all for running multiple processes simultaneously
- * Works on Windows, macOS, and Linux using Bun's native APIs
+ * Cross-platform Next.js dev launcher.
  */
 
 import { bunExecutable, colorEnv } from "./utils"
@@ -14,39 +12,21 @@ const nextDevArgs = [bunExecutable, "next", "dev"]
 if (isHttps) nextDevArgs.push("--experimental-https")
 if (isInspect) nextDevArgs.push("--inspect")
 
-// Build environment with FORCE_COLOR
 const devEnv = colorEnv()
 
-const processes = [
-  // Style watcher
-  Bun.spawn(
-    [bunExecutable, "--watch", "./lib/styles/scripts/setup-styles.ts"],
-    {
-      stdout: "inherit",
-      stderr: "inherit",
-      env: devEnv,
-    }
-  ),
-
-  // Next.js dev server
-  Bun.spawn(nextDevArgs, {
-    stdout: "inherit",
-    stderr: "inherit",
-    env: devEnv,
-  }),
-]
-
-// Handle graceful shutdown
+const nextDevProcess = Bun.spawn(nextDevArgs, {
+  stdout: "inherit",
+  stderr: "inherit",
+  env: devEnv,
+})
+
 const cleanup = () => {
-  for (const proc of processes) {
-    proc.kill()
-  }
+  nextDevProcess.kill()
   process.exit(0)
 }
 
 process.on("SIGINT", cleanup)
 process.on("SIGTERM", cleanup)
 
-// Wait for any process to exit (if one crashes, we want to know)
-await Promise.race(processes.map((p) => p.exited))
+await nextDevProcess.exited
 cleanup()

package/src/templates/next-webgl/lib/styles/README.md

@@ -1,64 +1,13 @@
 # Styles
 
-Hybrid styling with Tailwind CSS v4 and custom PostCSS functions.
+Minimal Tailwind setup for the starter.
 
-## PostCSS Functions
-
-```css
-/* Viewport-relative sizing */
-.element {
-  width: tovw(100);                    /* 6.94vw (100px at 1440px) */
-  width: tovw(100, 50);                 /* max(50px, 6.94vw) */
-  width: tovw(16, undefined, 'mobile'); /* 4.27vw (16px at 375px) */
-}
-
-/* Relative units */
-.text {
-  font-size: torem(24);    /* 1.5rem (24px / 16px) */
-  padding: toem(16, 14);   /* 1.14em (16px / 14px) */
-}
-
-/* Grid columns */
-.sidebar {
-  width: columns(3);       /* Spans 3 columns + gaps */
-}
-```
-
-## Custom Utilities (`dr-*`)
-
-```tsx
-// Responsive sizing (scales with viewport)
-<div className="dr-w-150 dr-h-100" />
-
-// Column-based sizing
-<div className="dr-w-col-4" />  {/* 4 columns wide */}
-
-// Grid layout
-<div className="dr-grid" />     {/* 4 cols mobile, 12 cols desktop */}
-```
-
-## Breakpoints
-
-```css
-@media (--mobile) { /* <= 799px */ }
-@media (--desktop) { /* >= 800px */ }
-```
-
-## Configuration
+## Files
 
 | File | Purpose |
 |------|---------|
-| `colors.ts` | Color palette & themes |
-| `typography.ts` | Font sizes & weights |
-| `layout.mjs` | Grid, breakpoints, spacing |
-| `easings.ts` | Animation curves |
-| `fonts.ts` | Font loading |
-
-After changing config: `bun setup:styles`
-
-## Generated Files (Don't Edit)
-
-- `css/root.css` — CSS custom properties
-- `css/tailwind.css` — Tailwind utilities
-
-See [scripts/README.md](scripts/README.md) for generation details.
+| `index.css` | Single stylesheet entrypoint imported by `app/layout.tsx` |
+| `tokens.css` | Theme variables, breakpoints, and custom Tailwind utilities |
+| `global.css` | Reset and global app styles |
+| `fonts.ts` | Font variable setup |
+| `cn.ts` | Tailwind class merging helper |

package/src/templates/next-webgl/lib/styles/fonts.ts

@@ -1,17 +1,9 @@
-import localFont from "next/font/local"
+import { Geist_Mono } from "next/font/google";
 
-const mono = localFont({
-  src: [
-    {
-      path: "../../public/fonts/geist/Geist-Mono.woff2",
-      weight: "400",
-      style: "normal",
-    },
-  ],
+const mono = Geist_Mono({
+  subsets: ["latin"],
   display: "swap",
   variable: "--geist-mono",
-  preload: true,
-  adjustFontFallback: "Arial",
   fallback: [
     "ui-monospace",
     "SFMono-Regular",
@@ -20,9 +12,9 @@ const mono = localFont({
     "Menlo",
     "monospace",
   ],
-})
+});
 
-const fonts = [mono]
-const fontsVariable = fonts.map((font) => font.variable).join(" ")
+const fonts = [mono];
+const fontsVariable = fonts.map((font) => font.variable).join(" ");
 
-export { fontsVariable }
+export { fontsVariable };