Cline rules

1# Project Consistency Keeper - Auto-generated
2 
3**Last Updated**: 2025-01-17
4**Project Root**: `./`
5**Project Name**: WiseMapping Frontend
6**Version**: 6.0.1
7 
8## Technology Stack
9 
10### Languages & Runtimes
11- **Node.js**: >=18.0.0 (required)
12- **TypeScript**: ^5.9.3 (strict mode enforced)
13- **JavaScript**: ES2022 target, ES2020 modules
14- **JSX**: React JSX automatic runtime
15 
16### Frameworks & Core Libraries
17- **React**: ^19.0.0 (peer dependency)
18- **Material-UI (MUI)**: ^7.3.4
19  - `@mui/material`: ^7.3.4
20  - `@mui/icons-material`: ^7.3.4
21- **Emotion**: ^11.14.0+ (styled-components alternative)
22- **Styled Components**: ^6.1.19
23 
24### Core Architecture Packages
25- **@wisemapping/web2d**: SVG abstraction layer for chart rendering
26- **@wisemapping/mindplot**: Vanilla ES6 mind map engine
27- **@wisemapping/editor**: React component wrapper for mindplot
28- **webapp**: Complete React application (not in current scope)
29 
30### Key Dependencies
31- **html2canvas**: ^1.4.1 (for export functionality)
32- **jspdf**: ^3.0.3 (PDF generation)
33- **lodash**: ^4.17.21 (utility functions)
34- **xml-formatter**: ^3.6.7 (XML formatting)
35- **fflate**: Custom vendor version (compression)
36 
37## Toolchain Standards
38 
39### Package Management
40- **Primary**: Yarn with workspaces
41- **Monorepo Tool**: Lerna (independent versioning mode)
42- **Workspace Structure**: `packages/*`
43- **Dependency Linking**: `workspace:*` protocol
44 
45### Build System
46- **Bundler**: Webpack ^5.102.1
47- **Configuration**: `webpack.common.js` (shared), `webpack.prod.js`, `webpack.dev.js`
48- **TypeScript Loader**: ts-loader ^9.5.4 with transpile-only mode
49- **Babel**: @babel/preset-typescript ^7.28.5
50- **Optimization Features**:
51  - Persistent filesystem caching (`.webpack-cache`)
52  - Thread-loader for parallel builds
53  - Deterministic module IDs
54  - Dead code elimination (`usedExports: true`)
55 
56### Development Server
57- **Webpack Dev Server**: ^5.2.2
58- **Port**: Configurable via `$PORT` environment variable
59- **Default Ports**:
60  - Editor Storybook: 6008
61  - Mindplot/Storybook: 6006
62  - Playground: 8081
63 
64### Code Quality & Formatting
65 
66#### ESLint Configuration
67- **Version**: ^9.38.0 with flat config (`eslint.config.mjs`)
68- **Presets**: 
69  - `@eslint/js/recommended`
70  - `eslint-plugin-react`
71  - `eslint-plugin-react-hooks`
72  - `eslint-plugin-cypress`
73  - `eslint-plugin-storybook`
74  - `eslint-config-prettier`
75- **Globals**: browser, node, commonjs, jest
76- **Target**: ECMAScript 2022
77 
78#### Prettier Configuration
79- **Print Width**: 100
80- **Tab Width**: 2
81- **Single Quotes**: true
82- **Trailing Commas**: `all`
83- **Semicolons**: true
84 
85#### TypeScript Configuration
86- **Strict Mode**: Enabled (`strict: true`)
87- **Strict Null Checks**: Enabled
88- **Target**: ES2022
89- **Module**: ES2020
90- **JSX**: React automatic runtime
91- **Allow JS**: true (for mixed codebase)
92- **Source Maps**: Enabled
93- **Declaration**: true
94 
95### Testing Framework
96 
97#### Jest Configuration
98- **Version**: ^30.2.0
99- **Environment**: jsdom
100- **Preset**: ts-jest
101- **Transform**:
102  - JS/TS: babel-jest
103  - Assets: jest-transform-stub
104- **Module Extensions**: js, ts, tsx
105- **Verbose**: true
106 
107#### Cypress Configuration
108- **Version**: ^15.5.0
109- **Base URLs**: 
110  - Playground: `http://localhost:8081`
111  - Storybook: `http://localhost:6006`, `http://localhost:6008`
112- **Features**: 
113  - Visual regression testing with `cypress-image-snapshot`
114  - Screenshot/video capture
115 
116### Git Workflow
117- **Hooks**: Husky ^9.1.7
118- **Pre-commit**: lint-staged
119- **Pre-push**: `yarn lint && yarn test`
120- **Branch**: Main development flow
121 
122## Project Architecture
123 
124### Directory Structure
125```
126.
127├── packages/
128│   ├── editor/          # React-based mind map editor
129│   ├── mindplot/        # Core mind map engine (vanilla ES6)
130│   ├── web2d/           # SVG abstraction layer
131│   └── fastmind/        # Additional utilities (if present)
132├── api/                 # API-related code
133├── scripts/             # Build and utility scripts
134├── memory-bank/         # Project documentation
135└── .clinerules/         # Development guidelines
136```
137 
138### Module Organization
139- **Independent Versioning**: Each package uses independent versions
140- **Workspace Dependencies**: Internal packages use `workspace:*`
141- **Main Entry**: `src/index.ts` for all packages
142- **Files**: `src` directories published (not `dist`)
143 
144### File Naming Conventions
145- **TypeScript**: `.ts` for logic, `.tsx` for React components
146- **Tests**: `*.test.ts`, `*.test.tsx`, or `*.cy.ts`
147- **Configuration**: `*.config.js` or `*.config.ts`
148- **Webpack**: `webpack.*.js`
149 
150## Development Constraints
151 
152### Package Management Commands
153- **Install**: `yarn install` (not npm)
154- **Clean**: `yarn clean` (removes all build artifacts)
155- **Build**: `yarn build` (runs lerna build across packages)
156- **Test**: `yarn test` (unit + integration tests)
157- **Lint**: `yarn lint` (ESLint checks)
158- **Lint Fix**: `yarn lint:fix` (ESLint with auto-fix)
159 
160### Prohibited Patterns
161- **DO NOT** use npm commands (use yarn)
162- **DO NOT** commit build artifacts (dist/, build/, coverage/)
163- **DO NOT** use MUI without tree-shaking awareness (500KB+ impact)
164- **DO NOT** disable TypeScript strict mode
165- **DO NOT** skip pre-push hooks
166 
167### Required Patterns
168- **ALWAYS** run `yarn lint && yarn test` before pushing
169- **ALWAYS** use `workspace:*` for internal dependencies
170- **ALWAYS** enable source maps in development
171- **ALWAYS** write tests for new features (unit + integration)
172- **ALWAYS** use Prettier for code formatting
173- **ALWAYS** maintain TypeScript strict mode compliance
174 
175### Version Constraints
176- **React**: ^19.0.0 (peer dependency)
177- **MUI**: ^7.3.4 (critical for consistency)
178- **Node**: >=18.0.0 (required)
179- **TypeScript**: ^5.9.3 (latest stable)
180 
181### Bundle Optimization Requirements
182- **Critical**: Pay special attention to MUI imports (tree-shaking)
183- **Webpack**: Use persistent caching for rebuilds
184- **Threading**: Enable parallel builds with thread-loader
185- **Analyze**: Use `webpack-bundle-analyzer` for optimization
186 
187### Testing Requirements
188- **Unit Tests**: Jest for logic/components
189- **Integration Tests**: Cypress E2E tests
190- **Visual Tests**: Cypress image snapshot regression
191- **Coverage**: Maintain comprehensive test coverage
192- **CI**: All tests must pass before merge
193 
194## Reference Files
195 
196### Core Configuration
197- `package.json` - Root monorepo configuration
198- `lerna.json` - Lerna monorepo settings
199- `webpack.common.js` - Shared Webpack configuration
200- `eslint.config.mjs` - ESLint flat config
201- `.prettierrc.json` - Prettier formatting rules
202 
203### Package Configuration
204- `packages/editor/package.json` - React editor component
205- `packages/mindplot/package.json` - Core mind map engine
206- `packages/web2d/package.json` - SVG abstraction layer
207- `packages/*/tsconfig.json` - Package-specific TypeScript config
208- `packages/*/jest.config.js` - Package-specific Jest config
209- `packages/*/cypress.config.*` - Package-specific Cypress config
210 
211### Documentation
212- `README.md` - Project overview
213- `CONTRIBUTING.md` - Contribution guidelines
214- `memory-bank/` - Comprehensive project documentation
215  - `projectbrief.md` - Project overview and requirements
216  - `activeContext.md` - Current development focus
217  - `progress.md` - Implementation status
218  - `systemPatterns.md` - Architectural patterns
219  - `techContext.md` - Technology decisions
220 
221### Development Scripts
222- `.husky/pre-push` - Git pre-push hook
223- `scripts/check-mui-imports.sh` - MUI import validation
224 
225## Maintenance Notes
226 
227### Performance Monitoring
228- Webpack build times optimization with persistent caching
229- Bundle size monitoring (especially MUI impact)
230- Cypress test execution speed
231- TypeScript compilation performance
232 
233### Regular Updates
234- Keep TypeScript at latest stable version
235- Update MUI dependencies together (core + icons)
236- Maintain React peer dependency compatibility
237- Regular security updates for all dependencies
238