Cursor Rules - MDimension Project

You are working on the MDimension project, an n-dimensional visualization tool built with React, Three.js, and TypeScript. Follow these rules exactly to maintain code quality, test coverage, and system stability.

Critical Execution Protocol

Task Completion Standards

**MANDATORY:** Never simplify, skip steps, or leave tasks incomplete.

1. **Complete all tasks fully** - No shortcuts or simplified approaches

2. **Maintain 100% test coverage** - Keep tests up to date with all code changes

3. **All tests must pass** - Before any task is considered complete

4. **Fix bugs in code, never in tests** - If tests fail, fix the implementation, not the test

5. **Never use watch mode** - Always run `npm test` for automated execution

After Implementing New Functionality

You MUST create comprehensive tests in this order:

1. **Unit tests** - Logic and components using Vitest in `src/tests/`

2. **Integration tests** - Game flow and feature interactions

3. **Playwright tests** - Frontend functionality in `scripts/playwright/`

**All tests must pass before the task is complete.**

Code Style & Architecture

Mandatory Style Guide

Follow `docs/meta/styleguide.md` without exception. Read this file before making any code changes.

Shader Requirements (WebGL2/GLSL ES 3.00 ONLY)

All shaders MUST use modern WebGL2 syntax:

```glsl

// ✅ CORRECT - Use these

#version 300 es

in vec3 position;

out vec4 fragColor;

layout(location = 0) out vec4 outColor;

// ❌ FORBIDDEN - Never use these

attribute vec3 position; // deprecated

varying vec4 fragColor; // deprecated

gl_FragColor = vec4(...); // deprecated

```

Test Memory Management

Configuration Safeguards

**DO NOT MODIFY** these settings in `vitest.config.ts`:

Writing Memory-Safe Tests

**DO:**

**DON'T:**

Emergency Response

If the system becomes unresponsive during test execution:

```bash

killall -9 node

node scripts/cleanup-vitest.mjs

```

Folder Usage Rules

Follow this directory structure exactly:

| Activity | Required Directory |

|----------|-------------------|

| Browser automation (Playwright/Puppeteer) | `scripts/playwright/` |

| Physics, RNG, analytics utilities | `scripts/tools/` |

| Visual artifacts (screenshots, videos, GIFs) | `screenshots/` |

| Documentation, research notes | `docs/` |

| Temporary experiments / sandboxes | `src/dev-tools/` |

| **🚫 FORBIDDEN** | **Project root (keep pristine)** |

Never place temporary files, scripts, or experiments in the project root.

Tech Stack Reference

Core Framework

3D Graphics & Rendering

UI & Styling

State Management

Testing

Mandatory Document Reads

Before working on any feature, review these documents:

1. **`docs/architecture.md`** - Project architecture and folder structure

2. **`docs/testing.md`** - Testing setup and development environment

3. **`docs/frontend.md`** - Frontend setup

4. **`docs/meta/styleguide.md`** - Code style guide (MANDATORY)

5. **`docs/research/nd-dimensional-react-threejs-guide.md`** - Math for object creation/transformation/projection

6. **`docs/prd/ndimensional-visualizer.md`** - Product requirements

7. **`docs/prd/enhanced-visuals-rendering-pipeline.md`** - Rendering pipeline PRD

Task Management

For any task requiring 3 or more steps:

1. **Create a todo list** at the start

2. **Track progress** as you complete each step

3. **Maintain focus** on the current task

4. **Ensure systematic approach** by following the list

Step-by-Step Workflow

When starting any task:

1. **Read relevant documentation** from the mandatory list above

2. **Create a todo list** if the task has 3+ steps

3. **Implement the feature** following the style guide

4. **Write comprehensive tests** (unit → integration → E2E)

5. **Run all tests** with `npm test` (never watch mode)

6. **Verify all tests pass** before considering the task complete

7. **Clean up** any temporary files or experiments

Common Pitfalls to Avoid

Success Criteria

A task is only complete when:

✅ All functionality is fully implemented (no shortcuts)

✅ 100% test coverage for new code

✅ All tests pass (unit, integration, E2E)

✅ Code follows the style guide

✅ Shaders use WebGL2 syntax only

✅ Files are in correct directories

✅ Documentation is updated if needed