bsmnt 0.0.2 → 0.1.0

package/packages/create-basement-app/templates/webgpu/lib/utils/viewport.ts

@@ -0,0 +1,193 @@
+/**
+ * Viewport Utilities
+ *
+ * Convert pixel values to viewport-relative sizes and relative units.
+ * Mirrors the SASS functions for consistent responsive scaling.
+ *
+ * @example
+ * ```ts
+ * import { tovw, torem, toem } from '@/utils/viewport'
+ *
+ * // Convert to viewport width units
+ * const paddingX = tovw(16, 24) // "1.5625vw" with a minimum of 24px
+ * const fontSize = tovw(16, 'mobile') // "4.27vw" (no undefined needed!)
+ * const width = tovw(100, 50, 'desktop') // "max(50px, 6.94vw)"
+ *
+ * // Convert to rem/em
+ * const spacing = torem(24) // "1.5rem"
+ * const padding = toem(16, 14) // "1.14em"
+ * ```
+ *
+ * ## When to Use
+ *
+ * - **CSS**: Prefer the PostCSS functions `tovw()`, `torem()`, and `toem()`
+ * - **JavaScript/TypeScript**: Use these for dynamic calculations or inline styles
+ * - **Runtime calculations**: Use for canvas, WebGL, or dynamic sizing
+ */
+
+import { breakpoints } from "@/lib/styles/config"
+
+type ContextSize = keyof typeof breakpoints | number
+
+/**
+ * Resolves a context size to a pixel value.
+ *
+ * @param context - Context identifier or pixel value
+ * @returns Pixel value
+ */
+function resolveContext(context: ContextSize): number {
+  if (typeof context === "number") {
+    return context
+  }
+  return breakpoints[context] ?? breakpoints.desktop
+}
+
+/**
+ * Checks if a value is a context identifier (breakpoint key).
+ *
+ * @param value - Value to check
+ * @returns True if value is a breakpoint key
+ */
+function isContextIdentifier(
+  value: unknown
+): value is keyof typeof breakpoints {
+  return typeof value === "string" && value in breakpoints
+}
+
+/**
+ * Rounds a number to a maximum of 4 decimal places, removing trailing zeros.
+ *
+ * @param value - Number to round
+ * @returns Rounded number as string without trailing zeros
+ */
+function roundToMaxDecimals(value: number): string {
+  // Round to 4 decimal places
+  const rounded = Math.round(value * 10000) / 10000
+  // Convert to string and remove trailing zeros only after decimal point
+  return rounded
+    .toString()
+    .replace(/\.0+$/, "")
+    .replace(/(\.\d*?)0+$/, "$1")
+}
+
+// Function overloads for tovw
+export function tovw(target: number): string
+export function tovw(target: number, min: number): string
+export function tovw(target: number, context: ContextSize): string
+export function tovw(target: number, min: number, context: ContextSize): string
+/**
+ * Converts a pixel value to viewport width units (vw).
+ * Optionally applies a minimum value using CSS max().
+ *
+ * Supports flexible parameter patterns:
+ * - `tovw(target)` - Uses default desktop context
+ * - `tovw(target, min)` - Sets minimum value
+ * - `tovw(target, context)` - Sets context (auto-detected if string identifier)
+ * - `tovw(target, min, context)` - Sets both min and context
+ *
+ * @param target - Target pixel value to convert
+ * @param minOrContext - Optional minimum pixel value OR context identifier
+ * @param context - Context size identifier (if min was provided)
+ * @returns CSS string with vw units (e.g., "6.94vw" or "max(50px, 6.94vw)")
+ *
+ * @example
+ * ```ts
+ * // Basic conversion
+ * tovw(100) // "6.94vw"
+ * tovw(16, 'mobile') // "4.27vw" (no undefined needed!)
+ *
+ * // With minimum value
+ * tovw(100, 50) // "max(50px, 6.94vw)"
+ * tovw(100, 50, 'mobile') // "max(50px, 6.94vw)" with mobile context
+ *
+ * // Custom context
+ * tovw(100, 1920) // "5.21vw"
+ *
+ * // Handles zero
+ * tovw(0) // "0"
+ * ```
+ */
+export function tovw(
+  target: number,
+  minOrContext?: number | ContextSize,
+  context?: ContextSize
+): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  let min: number | undefined
+  let resolvedContext: ContextSize = "desktop"
+
+  if (minOrContext !== undefined) {
+    if (isContextIdentifier(minOrContext)) {
+      // Second param is context
+      resolvedContext = minOrContext
+      if (context !== undefined) {
+        resolvedContext = context
+      }
+    } else if (typeof minOrContext === "number") {
+      // Second param is min value
+      min = minOrContext
+      if (context !== undefined) {
+        resolvedContext = context
+      }
+    }
+  } else if (context !== undefined) {
+    // Only context provided as third param (legacy support)
+    resolvedContext = context
+  }
+
+  const contextSize = resolveContext(resolvedContext)
+  const vwValue = (target / contextSize) * 100
+
+  if (min !== undefined) {
+    return `max(${min}px, ${roundToMaxDecimals(vwValue)}vw)`
+  }
+
+  return `${roundToMaxDecimals(vwValue)}vw`
+}
+
+/**
+ * Converts a pixel value to rem units.
+ *
+ * @param target - Target pixel value to convert
+ * @param context - Base font size in pixels (default: 16)
+ * @returns CSS string with rem units (e.g., "1.5rem")
+ *
+ * @example
+ * ```ts
+ * torem(24) // "1.5rem" (24 / 16)
+ * torem(18, 14) // "1.29rem" (18 / 14)
+ * torem(0) // "0"
+ * ```
+ */
+export function torem(target: number, context = 16): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  return `${roundToMaxDecimals(target / context)}rem`
+}
+
+/**
+ * Converts a pixel value to em units.
+ *
+ * @param target - Target pixel value to convert
+ * @param context - Context size in pixels (required)
+ * @returns CSS string with em units (e.g., "1.5em")
+ *
+ * @example
+ * ```ts
+ * toem(24, 16) // "1.5em" (24 / 16)
+ * toem(18, 14) // "1.29em" (18 / 14)
+ * toem(0, 16) // "0"
+ * ```
+ */
+export function toem(target: number, context: number): string {
+  if (target === 0) {
+    return "0"
+  }
+
+  return `${roundToMaxDecimals(target / context)}em`
+}

package/packages/create-basement-app/templates/webgpu/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/webgpu/package.json

@@ -0,0 +1,69 @@
+{
+  "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": "^11.0.0-alpha.4",
+    "@react-three/fiber": "10.0.0-alpha.2",
+    "class-variance-authority": "^0.7.1",
+    "leva": "^0.9.35",
+    "lucide-react": "^0.474.0",
+    "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/webgpu/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/webgpu/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/tasks/.last-branch

@@ -0,0 +1 @@
+BertovDev/project-restructure

package/tasks/CLAUDE.md

@@ -0,0 +1,104 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project.
+
+## Your Task
+
+1. Read the PRD at `prd.json` (in the same directory as this file)
+2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
+3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
+4. Pick the **highest priority** user story where `passes: false`
+5. Implement that single user story
+6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+7. Update CLAUDE.md files if you discover reusable patterns (see below)
+8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
+9. Update the PRD to set `passes: true` for the completed story
+10. Append your progress to `progress.txt`
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+```
+## [Date/Time] - [Story ID]
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
+
+```
+## Codebase Patterns
+- Example: Use `sql<number>` template for aggregations
+- Example: Always use `IF NOT EXISTS` for migrations
+- Example: Export types from actions.ts for UI components
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update CLAUDE.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby CLAUDE.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+2. **Check for existing CLAUDE.md** - Look for CLAUDE.md in those directories or parent directories
+3. **Add valuable learnings** - If you discovered something future developers/agents should know:
+   - API patterns or conventions specific to that module
+   - Gotchas or non-obvious requirements
+   - Dependencies between files
+   - Testing approaches for that area
+   - Configuration or environment requirements
+
+**Examples of good CLAUDE.md additions:**
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+
+Only update CLAUDE.md if you have **genuinely reusable knowledge** that would help future work in that directory.
+
+## Quality Requirements
+
+- ALL commits must pass your project's quality checks (typecheck, lint, test)
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Browser Testing (If Available)
+
+For any story that changes UI, verify it works in the browser if you have browser testing tools configured (e.g., via MCP):
+
+1. Navigate to the relevant page
+2. Verify the UI changes work as expected
+3. Take a screenshot if helpful for the progress log
+
+If no browser tools are available, note in your progress report that manual browser verification is needed.
+
+## Stop Condition
+
+After completing a user story, check if ALL stories have `passes: true`.
+
+If ALL stories are complete and passing, reply with:
+<promise>COMPLETE</promise>
+
+If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
+
+## Important
+
+- Work on ONE story per iteration
+- Commit frequently
+- Keep CI green
+- Read the Codebase Patterns section in progress.txt before starting