vue-fft-visualizer Development

Development guidelines for the vue-fft-visualizer project - a standalone Vue 3 component library providing WebGL-based FFT spectrum visualization.

Project Context

This is a Vue 3 component library that provides a GPU-accelerated WebGL FFT spectrum visualizer. It receives pre-computed FFT data via WebSocket and renders it using WebGL for high-performance visualization.

Git Workflow Rules

**CRITICAL:** Never commit automatically. Always let the user create commits themselves. You may prepare changes and stage files if needed, but NEVER run `git commit`.

Build System

The project uses Vite and pnpm. Available commands:

Project Structure

```

src/

├── components/

│ └── FFTVisualizer.vue # Main WebGL FFT visualizer component

└── index.ts # Package exports

backend-examples/

├── python/ # Python WebSocket server reference

├── nodejs/ # Node.js WebSocket server reference

└── rust/ # Rust WebSocket server reference

```

WebSocket Protocol

The FFTVisualizer component expects a specific WebSocket protocol:

1. **Configuration message (JSON):**

```json

{

"type": "config",

"mode": "fft",

"bins": 80,

"fps": 120

}

```

2. **Binary data frames:**

- N bytes of uint8 values (0-255)

- Each byte represents a frequency magnitude

- Number of bytes should match the `bins` value from config

Development Guidelines

1. **Type Safety:** Always run `pnpm typecheck` before building to catch TypeScript errors early

2. **Component API:** The main component exports are in `src/index.ts` - ensure any new components or utilities are properly exported

3. **WebGL Performance:** The visualizer uses GPU acceleration - be mindful of shader performance and draw call optimization

4. **WebSocket Connection:** Handle connection states gracefully (connecting, connected, disconnected, error)

5. **Backend Examples:** When modifying the protocol, update all three backend examples (Python, Node.js, Rust) to maintain consistency

Code Modification Steps

When making changes to this project:

1. Read the relevant source files first to understand existing patterns

2. For component changes, check `src/components/FFTVisualizer.vue`

3. For API changes, update `src/index.ts`

4. Run `pnpm typecheck` to verify TypeScript correctness

5. Test with `pnpm dev` to verify visual behavior

6. Build with `pnpm build` to ensure production bundle compiles

7. Stage files with git if requested, but never commit automatically

Common Tasks

**Adding a new visualization mode:**

1. Update FFTVisualizer.vue component logic

2. Update WebSocket protocol config type if needed

3. Update all backend examples to support new mode

4. Update type definitions in index.ts

**Performance optimization:**

1. Profile WebGL rendering with browser DevTools

2. Optimize shaders if needed

3. Adjust FPS/bins balance for target performance

4. Test with various data rates

**Protocol changes:**

1. Update component to handle new protocol

2. Update all three backend example implementations

3. Update documentation in README

4. Consider backward compatibility