Migrate from Node.js to Bun runtime for improved performance

- Update GitHub Actions to use Bun setup and bun install commands
- Replace package-lock.json with bun.lockb
- Update Next.js config from .ts to .js for compatibility
- Change font from Geist to Inter for Next.js 14 compatibility
- Add client-side checks for SSR compatibility
- Remove unnecessary dependencies (@types/node, tone, recharts)
- Update gitignore to include bun.lockb and debug logs
- Add version display to footer component

Author: g

.github/workflows/nextjs.yml

@@ -31,28 +31,10 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      - name: Detect package manager
-        id: detect-package-manager
-        run: |
-          if [ -f "${{ github.workspace }}/yarn.lock" ]; then
-            echo "manager=yarn" >> $GITHUB_OUTPUT
-            echo "command=install" >> $GITHUB_OUTPUT
-            echo "runner=yarn" >> $GITHUB_OUTPUT
-            exit 0
-          elif [ -f "${{ github.workspace }}/package.json" ]; then
-            echo "manager=npm" >> $GITHUB_OUTPUT
-            echo "command=ci" >> $GITHUB_OUTPUT
-            echo "runner=npx --no-install" >> $GITHUB_OUTPUT
-            exit 0
-          else
-            echo "Unable to determine package manager"
-            exit 1
-          fi
-      - name: Setup Node
-        uses: actions/setup-node@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          node-version: "20"
-          cache: ${{ steps.detect-package-manager.outputs.manager }}
+          bun-version: latest
       - name: Setup Pages
         uses: actions/configure-pages@v5
         with:
@@ -67,14 +49,14 @@ jobs:
           path: |
             .next/cache
           # Generate a new cache whenever packages or source files change.
-          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
+          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/bun.lockb') }}-${{ hashFiles('**.[jt]s', '**.[jt]sx') }}
           # If source files changed but packages didn't, rebuild from a prior cache.
           restore-keys: |
-            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json', '**/yarn.lock') }}-
+            ${{ runner.os }}-nextjs-${{ hashFiles('**/bun.lockb') }}-
       - name: Install dependencies
-        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
+        run: bun install --frozen-lockfile
       - name: Build with Next.js
-        run: ${{ steps.detect-package-manager.outputs.runner }} next build
+        run: bun run build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -10,6 +10,9 @@
 !.yarn/releases
 !.yarn/versions
 
+# bun
+/bun.lockb
+
 # testing
 /coverage
 
@@ -29,6 +32,7 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
+bun-debug.log*
 
 # env files (can opt-in for committing if needed)
 .env*

AGENTS.md

@@ -0,0 +1,157 @@
+# Binaural Beat Player - Development Guide
+
+## Project Overview
+A Next.js-based binaural beat player with Web Audio API integration, migrated from Node.js to Bun runtime for improved performance and reduced bundle size.
+
+## Technology Stack
+- **Runtime**: Bun (>=1.0.0)
+ - **Framework**: Next.js 14.2.15 with React 18.3.1
+- **Styling**: Tailwind CSS v4
+ - **Audio**: Web Audio API
+ - **Icons**: Lucide React & React Icons
+- **Deployment**: GitHub Pages (static export)
+
+## Development Commands
+
+### Core Commands
+```bash
+# Install dependencies
+bun install
+
+# Start development server with Turbopack
+bun run dev
+
+# Build for production
+bun run build
+
+# Start production server
+bun run start
+
+# Run linting
+bun run lint
+
+# Deploy to GitHub Pages
+bun run deploy
+```
+
+## Key Features
+- **Binaural Beat Generation**: Real-time audio synthesis using Web Audio API
+- **Pattern Mode**: JSON-based frequency sequences with timing control
+- **Manual Mode**: Direct frequency control with range sliders (1-600 Hz)
+- **Visualizer**: Real-time waveform visualization using Canvas API
+- **Volume Control**: Frequency-aware volume adjustment
+- **Responsive Design**: Mobile-first approach with Tailwind CSS
+
+## Project Structure
+```
+├── app/                    # Next.js App Router
+│   ├── page.tsx           # Main binaural player component
+│   ├── layout.tsx         # Root layout
+│   └── globals.css        # Global styles
+├── components/            # Reusable components
+│   └── Footer.tsx         # Footer with donate links
+├── bineural-songs/        # Predefined patterns
+│   ├── ai-gemini.json     # AI-focused pattern
+│   ├── creative.json      # Creativity enhancement
+│   ├── intro.json         # Introduction pattern
+│   ├── relaxing.json      # Relaxation pattern
+│   └── scala.json         # Scala tuning pattern
+└── public/               # Static assets
+```
+
+## Audio Implementation Details
+
+### Web Audio API Architecture
+- **AudioContext**: Main audio processing context
+- **OscillatorNodes**: Generate left/right channel frequencies
+- **StereoPannerNodes**: Channel separation (-1 left, +1 right)
+- **GainNode**: Volume control with frequency-based scaling
+
+### Frequency Scaling
+Volume automatically adjusts based on average frequency:
+- 1 Hz: 100% volume
+- 600 Hz: 30% volume
+- Linear interpolation between endpoints
+
+### Pattern Format
+```json
+{
+  "pattern": [
+    [left_frequency, right_frequency, duration_ms],
+    // ... more steps
+  ]
+}
+```
+
+## Migration Notes (Node.js → Bun)
+
+### Removed Dependencies
+- `@types/node`: No longer needed with Bun's built-in Node.js compatibility
+- `tone`: Removed to prevent localStorage SSR issues
+- `recharts`: Removed to prevent localStorage SSR issues
+- `package-lock.json`: Replaced with `bun.lockb`
+
+### Configuration Changes
+- **next.config.js**: Renamed from .ts for compatibility, static export for production
+- **package.json**: Added Bun engine requirement
+- **.gitignore**: Added `bun.lockb` and `bun-debug.log*`
+
+### Version Compatibility
+- Downgraded Next.js from 15.3.1 to 14.2.15 for stability
+- Downgraded React from 19 to 18.3.1 for better SSR compatibility
+- Changed font from Geist to Inter for Next.js 14 compatibility
+
+### Performance Benefits
+- Faster installation times
+- Reduced bundle size
+- Improved runtime performance
+- Built-in TypeScript support
+
+## Development Guidelines
+
+### Code Style
+- Use TypeScript with strict mode
+- Follow React functional component patterns
+- Implement proper cleanup in useEffect hooks
+- Use semantic HTML with ARIA labels
+
+### Audio Best Practices
+- Always handle AudioContext state changes (suspended/resumed)
+- Implement proper oscillator cleanup
+- Use smooth transitions (linearRampToValueAtTime)
+- Handle browser compatibility gracefully
+
+### State Management
+- Keep audio state separate from UI state
+- Use refs for persistent audio objects
+- Implement proper error boundaries
+
+## Deployment
+The app builds as a static site for GitHub Pages:
+- Output directory: `out/`
+- Base path: `/binaural-beat-player` (production only)
+- Automatic .nojekyll file generation
+
+## Browser Compatibility
+- Modern browsers with Web Audio API support
+- Chrome/Edge: Full support
+- Firefox: Full support
+- Safari: Partial support (may require user interaction)
+
+## Deployment
+The app builds as a static site for GitHub Pages:
+- Output directory: `out/`
+- Base path: `/binaural-beat-player` (production only)
+- Automatic .nojekyll file generation
+
+## Browser Compatibility
+- Modern browsers with Web Audio API support
+- Chrome/Edge: Full support
+- Firefox: Full support
+- Safari: Partial support (may require user interaction)
+
+## Troubleshooting
+- **Audio not playing**: Check browser autoplay policies
+- **Context suspended**: Call `audioContext.resume()` after user interaction
+- **Performance issues**: Monitor oscillator cleanup and gain node connections
+- **SSR Issues**: Use `typeof window === 'undefined'` checks for browser APIs

app/debug/page.tsx

@@ -0,0 +1,29 @@
+"use client"
+
+import { useEffect, useState } from 'react'
+
+export default function DebugPage() {
+  const [localStorageAvailable, setLocalStorageAvailable] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    try {
+      if (typeof window !== 'undefined' && 'localStorage' in window) {
+        setLocalStorageAvailable(true)
+        localStorage.getItem('test')
+      } else {
+        setError('localStorage not available')
+      }
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Unknown error')
+    }
+  }, [])
+
+  return (
+    <div className="min-h-screen bg-gray-900 text-white p-8">
+      <h1 className="text-2xl font-bold mb-6">Debug Page</h1>
+      <p>localStorage available: {localStorageAvailable ? 'Yes' : 'No'}</p>
+      {error && <p className="text-red-500">Error: {error}</p>}
+    </div>
+  )
+}

app/layout.tsx

@@ -1,16 +1,12 @@
 import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
+import { Inter } from "next/font/google";
 import "./globals.css";
 import Footer from "@/components/Footer"; // Import the Footer component
 
-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
+const inter = Inter({
+  variable: "--font-inter",
   subsets: ["latin"],
+  preload: false,
 });
 
 export const metadata: Metadata = {
@@ -27,7 +23,7 @@ export default function RootLayout({
     <html lang="en" suppressHydrationWarning>
       {/* Add flex styles to body for sticky footer */}
       <body
-        className={`${geistSans.variable} ${geistMono.variable} antialiased flex flex-col min-h-screen`}
+        className={`${inter.variable} antialiased flex flex-col min-h-screen`}
         suppressHydrationWarning
       >
         <main className="flex-grow">{children}</main> {/* Wrap children in main for better structure */}

app/page.tsx

@@ -47,6 +47,9 @@ const BinauralPlayer: React.FC = () => {
   const animationPhaseRef = useRef<number>(0);
 
   useEffect(() => {
+    // Only initialize audio on client side
+    if (typeof window === 'undefined') return;
+    
     const initAudio = () => {
       if (!audioContextRef.current) {
         audioContextRef.current = new (window.AudioContext || (window as any).webkitAudioContext)();
@@ -226,8 +229,8 @@ const BinauralPlayer: React.FC = () => {
   }, []);
 
   useEffect(() => {
-    // Ensure canvas logic runs only when mounted and playing
-    if (!isMounted || !isPlaying) return;
+    // Ensure canvas logic runs only when mounted and playing and on client side
+    if (!isMounted || !isPlaying || typeof window === 'undefined') return;
 
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -492,4 +495,4 @@ const BinauralPlayer: React.FC = () => {
   );
 };
 
-export default BinauralPlayer;
+export default BinauralPlayer;

app/simple-page.tsx

@@ -0,0 +1,10 @@
+"use client"
+
+export default function HomePage() {
+  return (
+    <div className="min-h-screen bg-gray-900 text-white p-8">
+      <h1 className="text-2xl font-bold mb-6">Simple Test Page</h1>
+      <p>This is a test to see if the localStorage error persists.</p>
+    </div>
+  )
+}

app/test/page.tsx

@@ -0,0 +1,5 @@
+"use client"
+
+export default function TestPage() {
+  return <div className="min-h-screen bg-gray-900 text-white p-8">Test Page</div>
+}