From 03a4dbff3d5735562cb9115dd2c8fdd4883b936e Mon Sep 17 00:00:00 2001
From: Kushagra Gour <chinchang457@gmail.com>
Date: Mon, 21 Jul 2025 19:34:44 +0530
Subject: [PATCH] add CLAUDE.md

---
 CLAUDE.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..cc9a84d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Web-Maker is a blazing fast offline web playground that supports multiple preprocessors and offers both a Chrome extension and web app. The codebase is built with Preact and includes a comprehensive build system for both web and extension distributions.
+
+## Development Commands
+
+### Build & Development
+
+- `npm run dev` - Start development server with hot reload
+- `npm run build` - Production build using Preact CLI
+- `npm start` - Start dev server with preview server (combines dev + gulp start-preview-server)
+
+### Testing & Quality
+
+- `npm test` - Run Jest tests
+- `npm run lint` - Run ESLint on src directory
+- `npm run cypress` - Run end-to-end tests with Cypress
+- `npm run cypress:open` - Open Cypress test runner
+
+### Build Distribution
+
+- `gulp release` - Full production release (web app + extension)
+- `gulp devRelease` - Development release
+- `gulp buildExtension` - Build Chrome extension only
+
+### Internationalization
+
+- `npm run extract` - Extract translatable strings
+- `npm run compile` - Compile translations
+- `npm run add-locale` - Add new locale
+
+## Architecture Overview
+
+### Core Structure
+
+- **src/components/app.jsx** - Main application component managing global state, modals, and user interactions
+- **src/components/ContentWrap.jsx** - 3-pane editor layout (HTML/CSS/JS)
+- **src/components/ContentWrapFiles.jsx** - File-based project mode with sidebar navigation
+- **src/components/MainHeader.jsx** - Top toolbar with actions and controls
+
+### Key Services
+
+- **src/itemService.js** - Handles creation storage/retrieval (local & cloud)
+- **src/firebaseInit.js** + **src/auth.js** - Firebase authentication and user management
+- **src/db.js** - Database abstraction layer for settings and local storage
+- **src/analytics.js** - Event tracking
+- **src/notifications.js** - Alert system service
+
+### Editor Infrastructure
+
+- **src/computes.js** - Code preprocessing (HTML/CSS/JS transformations)
+- **src/codeModes.js** - Defines supported preprocessors (Pug, SCSS, TypeScript, etc.)
+- **src/fileUtils.js** - File system operations for file-based projects
+- **src/utils.js** - Core utilities including HTML generation and preview handling
+
+### Build System
+
+- **gulpfile.js** - Complex build pipeline that packages for both web app and Chrome extension
+- **preact.config.js** - Preact CLI configuration with webpack customizations
+- Supports both traditional 3-pane mode and file-based project mode
+
+### Preview System
+
+Sophisticated preview system that:
+
+- Generates complete HTML documents from separated HTML/CSS/JS
+- Supports preprocessor compilation
+- Handles external library injection
+- Includes service worker for offline file serving in file mode
+
+### Extension Integration
+
+The Chrome extension shares the same codebase but includes additional files:
+
+- **src/manifest.json** - Extension manifest
+- **src/eventPage.js** - Background script
+- **src/options.js** - Extension options page
+
+## Development Notes
+
+### Running Tests
+
+- Jest tests are in `tests/` directory with mocks in `tests/__mocks__/`
+- Cypress e2e tests cover core user workflows
+- Tests use browser mocks for extension APIs
+
+### File Mode vs 3-Pane Mode
+
+The application supports two distinct modes:
+
+- **3-Pane Mode**: Traditional HTML/CSS/JS editors side-by-side
+- **File Mode**: Full file system with folder structure, currently limited to 2 projects for free users
+
+### Code Generation
+
+When working on the preview system or file handling, note that the app dynamically generates complete HTML documents and handles virtual file systems for the preview iframe.
+
+### State Management
+
+The main App component manages extensive global state including user authentication, current project, preferences, and modal states. Most state flows down through props rather than using a dedicated state management library.