bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/webgl/next.config.ts

@@ -0,0 +1,142 @@
+import withBundleAnalyzer from "@next/bundle-analyzer"
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  reactCompiler: true,
+  typedRoutes: true,
+  turbopack: {
+    rules: {
+      "*.svg": {
+        loaders: [
+          {
+            loader: "@svgr/webpack",
+            options: {
+              memo: true,
+              dimensions: false,
+              svgoConfig: {
+                multipass: true,
+                plugins: [
+                  "removeDimensions",
+                  "removeOffCanvasPaths",
+                  "reusePaths",
+                  "removeElementsByAttr",
+                  "removeStyleElement",
+                  "removeScriptElement",
+                  "prefixIds",
+                  "cleanupIds",
+                  {
+                    name: "cleanupNumericValues",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                  {
+                    name: "convertPathData",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                  {
+                    name: "convertTransform",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                  {
+                    name: "cleanupListOfValues",
+                    params: {
+                      floatPrecision: 1,
+                    },
+                  },
+                ],
+              },
+            },
+          },
+        ],
+        as: "*.js",
+      },
+    },
+  },
+  cacheComponents: true,
+  experimental: {
+    browserDebugInfoInTerminal: true,
+    optimizePackageImports: [
+      "@react-three/drei",
+      "@react-three/fiber",
+      "gsap",
+      "three",
+      "postprocessing",
+      "lenis",
+      "zustand",
+    ],
+  },
+  images: {
+    dangerouslyAllowSVG: true,
+    remotePatterns: [],
+    minimumCacheTTL: 60 * 60 * 24 * 30, // 30 days
+    qualities: [90],
+    formats: ["image/avif", "image/webp"],
+    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+  },
+  headers: async () => [
+    {
+      source: "/(.*)",
+      headers: [
+        {
+          key: "X-Content-Type-Options",
+          value: "nosniff",
+        },
+        {
+          key: "Content-Security-Policy",
+          value: "frame-ancestors 'self';",
+        },
+        {
+          key: "X-Frame-Options",
+          value: "SAMEORIGIN",
+        },
+        {
+          key: "X-XSS-Protection",
+          value: "1; mode=block",
+        },
+        {
+          key: "X-DNS-Prefetch-Control",
+          value: "on",
+        },
+        {
+          key: "Strict-Transport-Security",
+          value: "max-age=63072000; includeSubDomains; preload",
+        },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
+      ],
+    },
+  ],
+  redirects: async () => [
+    {
+      source: "/home",
+      destination: "/",
+      permanent: true,
+    },
+  ],
+  rewrites: async () => [
+    {
+      source: "/",
+      destination: "/home",
+    },
+  ],
+}
+
+const bundleAnalyzerPlugin = withBundleAnalyzer({
+  enabled: process.env.ANALYZE === "true",
+})
+
+const NextApp = () => {
+  const plugins = [bundleAnalyzerPlugin]
+  return plugins.reduce((config, plugin) => plugin(config), nextConfig)
+}
+
+export default NextApp

package/packages/create-basement-app/templates/webgl/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "basement-next-starter",
+  "description": "Basement Next.js starter template",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "bun@1.3.5",
+  "scripts": {
+    "analyze": "cross-env ANALYZE=true bun run build",
+    "analyze:experimental": "next experimental-analyze",
+    "build": "bun run setup:styles && next build",
+    "dev": "bun ./lib/scripts/dev.ts",
+    "dev:https": "bun ./lib/scripts/dev.ts --https",
+    "dev:inspect": "bun ./lib/scripts/dev.ts --inspect",
+    "format": "biome format --write .",
+    "generate": "bun ./lib/scripts/generate.ts",
+    "lighthouse": "bunx @unlighthouse/cli --site http://localhost:3000",
+    "lint": "biome lint --max-diagnostics=200",
+    "lint:fix": "biome lint --write --unsafe --max-diagnostics=200",
+    "setup:styles": "bun ./lib/styles/scripts/setup-styles.ts",
+    "start": "next start",
+    "test": "bun test",
+    "test:setup": "bun test lib/scripts/setup-project.test.ts",
+    "typecheck": "tsgo --noEmit",
+    "typecheck:compare": "bun run typecheck:tsc && bun run typecheck",
+    "typecheck:tsc": "tsc --noEmit --incremental false"
+  },
+  "dependencies": {
+    "@radix-ui/react-navigation-menu": "^1.2.5",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "class-variance-authority": "^0.7.1",
+    "leva": "^0.9.35",
+    "next": "16.1.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-use": "^17.6.0",
+    "tailwind-merge": "^3.4.0",
+    "three": "^0.182.0",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.10"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@clack/prompts": "^0.11.0",
+    "@csstools/postcss-global-data": "^3.1.0",
+    "@next/bundle-analyzer": "16.1.1",
+    "@svgr/webpack": "^8.1.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@types/bun": "^1.3.6",
+    "@types/node": "^20.19.30",
+    "@types/react": "^19.2.9",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.182.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260122.3",
+    "babel-plugin-react-compiler": "1.0.0",
+    "cross-env": "^10.1.0",
+    "postcss-functions": "^4.0.2",
+    "postcss-preset-env": "^10.6.1",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3"
+  },
+  "trustedDependencies": [
+    "@biomejs/biome",
+    "@tailwindcss/oxide",
+    "esbuild",
+    "sharp"
+  ]
+}

package/packages/create-basement-app/templates/webgl/postcss.config.mjs

@@ -0,0 +1,42 @@
+import { functions } from "./lib/styles/scripts/postcss-functions.mjs"
+
+/**
+ * PostCSS preset-env config
+ * @see Docs {@link https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/README.md#options}
+ * @see Features Flags {@link https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/FEATURES.md}
+ * @type {import('postcss-preset-env').pluginOptions}
+ */
+const presetEnvConfig = {
+  autoprefixer: {
+    flexbox: "no-2009",
+  },
+  stage: 3,
+  features: {
+    "custom-properties": false,
+    "custom-media-queries": true,
+    "nesting-rules": true,
+  },
+}
+
+/**
+ * PostCSS global data config
+ * Makes sure the css module files have access to these context files
+ * @see {@link https://github.com/csstools/postcss-global-data?tab=readme-ov-file#options}
+ * @type {import('@csstools/postcss-global-data').pluginOptions}
+ */
+const globalDataConfig = {
+  files: ["./lib/styles/css/root.css"],
+}
+
+const postcssConfig = {
+  // NOTE: Order is important
+  plugins: {
+    "@tailwindcss/postcss": {},
+    "@csstools/postcss-global-data": globalDataConfig,
+    "postcss-functions": { functions },
+    // NOTE: This has to be last config
+    "postcss-preset-env": presetEnvConfig,
+  },
+}
+
+export default postcssConfig

package/packages/create-basement-app/templates/webgl/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "noUncheckedSideEffectImports": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noUncheckedIndexedAccess": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/packages/create-basement-app/templates/webgpu/.biome/plugins/README.md

@@ -0,0 +1,21 @@
+## Plugins
+
+### 1. `no-anchor-element.grit`
+Enforces using Next.js `<Link>` component instead of HTML `<a>` elements.
+
+### 2. `no-unnecessary-forwardref.grit`
+Checks for unnecessary `forwardRef` usage in React 19 with the compiler.
+
+### 3. `no-relative-parent-imports.grit`
+Forbids relative parent imports (`../`) and encourages alias imports (`@/`).
+
+## Plugin Configuration
+
+The plugins are configured in `biome.json`:
+```json
+"plugins": [
+  "./biome-plugins/no-anchor-element.grit",
+  "./biome-plugins/no-unnecessary-forwardref.grit",
+  "./biome-plugins/no-relative-parent-imports.grit"
+]
+``` 

package/packages/create-basement-app/templates/webgpu/.biome/plugins/no-anchor-element.grit

@@ -0,0 +1,12 @@
+language js;
+
+`<a $attrs>$content</a>` as $anchor where {
+    !$anchor <: within `if ($condition) { return ($jsx) }` where {
+        $condition <: contains or { `isExternal`, `isExternalSSR` }
+    },
+    register_diagnostic(
+        span = $anchor,
+        message = "Use custom Link component instead of <a> element. The Link component handles both internal and external links automatically.",
+        severity = "error"
+    )
+} 

package/packages/create-basement-app/templates/webgpu/.biome/plugins/no-relative-parent-imports.grit

@@ -0,0 +1,10 @@
+language js;
+
+`import $imports from $source` as $import where {
+    $source <: r"['\"]\.\.\/\.\.\/.*['\"]",
+    register_diagnostic(
+        span = $import,
+        message = "Use alias imports (~/dir/) instead of deep relative imports (../../). Single level imports (../) are allowed for colocated files.",
+        severity = "error"
+    )
+} 

package/packages/create-basement-app/templates/webgpu/.biome/plugins/no-unnecessary-forwardref.grit

@@ -0,0 +1,9 @@
+language js;
+
+`forwardRef($func)` as $ref where {
+    register_diagnostic(
+        span = $ref,
+        message = "forwardRef is unnecessary in React 19 with the compiler",
+        severity = "warning"
+    )
+} 

package/packages/create-basement-app/templates/webgpu/.cursor/rules/README.md

@@ -0,0 +1,184 @@
+# Cursor Rules Documentation
+
+This directory contains consolidated Cursor AI rules for the Satus project. The rules are organized into 5 focused files for easy maintenance and efficient AI context loading.
+
+## 📁 File Structure
+
+### 1. `main.mdc` - Project Overview & Cross-Cutting Concerns
+**Purpose**: High-level overview and concerns that apply across the entire project
+
+**Contents**:
+- Technology stack (Next.js 16+, React 19+, Tailwind v4, Biome, Bun)
+- React 19+ new features (`<Activity />`, `useEffectEvent`, `cacheSignal`)
+- Next.js 16 Cache Components gotchas and best practices
+- File organization
+- React Compiler & memoization guidelines (single source of truth)
+- Image optimization guidelines (single source of truth)
+- Development vs production guidelines (single source of truth)
+- Core utility libraries (`@/utils`)
+
+**When to reference**: Starting a new project, understanding the tech stack, cross-cutting concerns
+
+---
+
+### 2. `components.mdc` - React Component Patterns & WebGL
+**Purpose**: All React component patterns including standard components and WebGL/Three.js
+
+**Contents**:
+- Component structure and imports
+- Props interfaces and React 19 ref handling
+- Forms and responsive design
+- Performance best practices (code splitting)
+- Error handling
+- WebGL/Three.js setup and patterns
+- React Three Fiber
+- Drei components
+- Custom shaders
+- Animation and interaction
+- Post-processing
+
+**When to reference**: Building React components, creating WebGL experiences, working with Three.js
+
+---
+
+### 3. `styling.mdc` - CSS Modules & Tailwind CSS v4
+**Purpose**: All styling approaches including CSS Modules and Tailwind CSS v4
+
+**Contents**:
+- CSS Modules (file naming, class naming, imports)
+- Responsive design (viewport functions, breakpoints, grid system)
+- Typography and colors
+- Animations and transitions
+- Tailwind CSS v4 (CSS-first configuration, theme variables, new features)
+- 3D transforms, gradients, shadows
+- New variants (composable, `starting`, `not-*`, `nth-*`)
+- Custom extensions (`@utility`, `@variant`, `@plugin`)
+- Breaking changes and migration
+- Project-specific custom utilities (`b-*` classes)
+- PostCSS functions
+
+**When to reference**: Styling components, using Tailwind, creating responsive designs
+
+---
+
+### 4. `integrations.mdc` - Third-Party Integrations
+**Purpose**: Guidelines for all third-party service integrations
+
+**Contents**:
+- **Sanity CMS**: Configuration, schema management, GROQ queries, visual editing, TypeScript generation, cacheSignal integration
+- **Shopify**: API configuration, product management, cart operations, cacheSignal integration
+- General best practices (environment variables, API resilience, error handling)
+- Cache Components gotchas for integrations (user-specific data, real-time data)
+- Type safety and performance
+- Security and integration management
+- Webhook handling
+
+**When to reference**: Integrating with Sanity, Shopify, or other third-party services
+
+---
+
+### 5. `architecture.mdc` - Architecture Patterns & Best Practices
+**Purpose**: Architectural patterns, state management, routing, and code quality guidelines
+
+**Contents**:
+- Type safety (TypeScript configuration)
+- State management (React state, Zustand)
+- Routing & navigation (Next.js App Router, Link component)
+- Metadata & SEO
+- Performance (server components, code splitting, caching)
+- Cache Components (Next.js 16) - Suspense, invalidation, gotchas
+- Security (environment variables, input validation, authentication)
+- Testing & debugging (unit tests, debugging tools, error boundaries)
+- Code quality (linting, formatting, code organization)
+- Development workflow (package manager, git workflow, client/server boundaries)
+
+**When to reference**: Architectural decisions, state management, routing patterns, code quality
+
+---
+
+## 🎯 Quick Reference Guide
+
+### I want to...
+
+- **Start a new feature** → Read `main.mdc` for overview, then `architecture.mdc` for patterns
+- **Build a React component** → `components.mdc`
+- **Add WebGL/Three.js** → `components.mdc` § WebGL Components & Activity Integration
+- **Style with CSS Modules** → `styling.mdc` § CSS Modules
+- **Style with Tailwind** → `styling.mdc` § Tailwind CSS v4
+- **Use custom utilities** → `styling.mdc` § Project-Specific Custom Utilities
+- **Integrate Sanity CMS** → `integrations.mdc` § Sanity CMS Integration
+- **Integrate Shopify** → `integrations.mdc` § Shopify Integration
+- **Manage state** → `architecture.mdc` § State Management
+- **Add routing** → `architecture.mdc` § Routing & Navigation
+- **Optimize performance** → `architecture.mdc` § Performance
+- **Handle security** → `architecture.mdc` § Security
+- **Debug issues** → `architecture.mdc` § Testing & Debugging
+- **Understand React Compiler** → `main.mdc` § React Compiler & Memoization
+- **Handle images** → `main.mdc` § Image Optimization (`@/components/ui/image`)
+- **Dev vs prod differences** → `main.mdc` § Development vs Production
+- **Use utility functions** → `main.mdc` § Core Utility Libraries (`@/utils`)
+
+---
+
+## 📝 Maintenance Guidelines
+
+### When Editing Rules
+
+1. **Avoid Duplication**: If content applies to multiple areas, put it in `main.mdc` and reference it
+2. **Use Cross-References**: Link to other sections instead of duplicating content
+3. **Keep It Focused**: Each file should maintain its specific purpose
+4. **Update Dates**: Update the "Last updated" date when making changes
+5. **Check Dependencies**: When updating one file, check if related files need updates
+
+### Example Cross-Reference Pattern
+
+```markdown
+<!-- In components.mdc -->
+## Performance Optimization
+See main.mdc § React Compiler & Memoization for optimization guidelines.
+```
+
+### Adding New Content
+
+**Ask yourself**:
+- Is this component-specific? → `components.mdc`
+- Is this styling-related? → `styling.mdc`
+- Is this an integration? → `integrations.mdc`
+- Is this architectural? → `architecture.mdc`
+- Is this cross-cutting? → `main.mdc`
+
+---
+
+## 🚀 For Developers
+
+### Quick Setup
+1. These rules are automatically loaded by Cursor AI
+2. All files have `alwaysApply: true` in frontmatter
+3. Files apply to: `*.tsx, *.jsx, *.css, *.js, *.ts`
+
+### Contributing
+When adding new guidelines:
+1. Choose the appropriate file
+2. Follow existing formatting patterns
+3. Add clear examples
+4. Update this README if needed
+5. Keep content focused and actionable
+
+---
+
+## 📊 File Statistics
+
+| File | Purpose | Key Topics |
+|------|---------|------------|
+| `main.mdc` | Overview & Cross-cutting | Tech stack, React 19+ features, Cache Components, React Compiler, Images, Dev/Prod |
+| `components.mdc` | React & WebGL | Components, Forms, WebGL, Three.js, Shaders, Activity |
+| `styling.mdc` | All Styling | CSS Modules, Tailwind v4, Responsive, Custom utilities |
+| `integrations.mdc` | Third-party Services | Sanity, Shopify, Cache Components, cacheSignal |
+| `architecture.mdc` | Patterns & Quality | State, Routing, Performance, Cache Components, Security, Testing |
+
+---
+
+Last updated: 2026-01-26
+
+For questions or suggestions about these rules, contact the development team.
+