# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview LearnGitBranching is an interactive git visualization tool for teaching git concepts through a game-like interface. It's a 100% client-side JavaScript application that simulates git operations and renders them visually using Raphael.js for SVG graphics. ## Build & Development Commands ### Setup ```bash yarn install ``` ### Building ```bash yarn dev # Vite development server with live reload yarn build # Checked production build in ./build yarn generate # Regenerate level + locale manifests (also pre-hooked) ``` ### Testing & Linting ```bash yarn test # Run Jasmine test suite yarn test:coverage # Run tests with nyc coverage yarn lint # Run ESLint correctness checks yarn lint:fix # Apply safe automatic lint fixes yarn lint:strings # Validate internationalization strings ``` ### Development Server ```bash yarn dev # Start Vite dev server # After building, serve the build directory with a static file server ``` ### Single Test Execution ```bash # Run a specific test file yarn jasmine __tests__/git.spec.js ``` ## Architecture Overview ### Core Components **GitEngine** (`src/js/git/index.js`) - The heart of the application - simulates all git operations - Manages the commit graph, branches, tags, refs, and HEAD - Processes commands and updates the visualization - Supports both git and Mercurial (hg) modes via `mode` property - Uses EventBaton pattern for command dispatching **Visualization System** (`src/js/visuals/`) - `visualization.js`: Main visualization controller - `tree.js`: Renders the commit tree using Raphael.js - `visNode.js`, `visBranch.js`, `visTag.js`, `visEdge.js`: Individual visual components - `animation/`: Animation system using promise chains (Q library) **Command Processing** (`src/js/commands/index.js`, `src/js/git/commands.js`) - Commands are defined with regex patterns, options, and execute functions - Supports both git and Mercurial command sets - Command delegation system allows commands to internally invoke other commands - All git commands are simulated - they manipulate in-memory data structures **Levels System** (`src/levels/`) - Each level is a JavaScript module exporting level configuration - Organized into sequences: intro, rampup, move, mixed, advanced, remote, remoteAdvanced - Level definition includes: name, goal description, starting tree state, solution validation - See `src/levels/index.js` for all level sequences ### Flux Architecture The app uses a Flux-like architecture: **Dispatcher** (`src/js/dispatcher/AppDispatcher.js`) - Central event bus using Facebook's Flux Dispatcher - Handles VIEW_ACTION and URI_ACTION payload sources **Stores** (`src/js/stores/`) - `CommandLineStore.js`: Manages command line state - `LevelStore.js`: Tracks current level and progress - `LocaleStore.js`: Handles internationalization - `GlobalStateStore.js`: Global application state **Actions** (`src/js/actions/`) - Action creators for CommandLine, Level, Locale, and GlobalState ### UI Components **Backbone Views** (`src/js/views/`) - Legacy Backbone.js views for modals, dialogs, builders - `gitDemonstrationView.js`: Shows animated git command demonstrations **React Components** (`src/js/react_views/`) - Modern React components for command line, toolbar, helper bars - Command history view with syntax highlighting ### Key Patterns **EventBaton** (`src/js/util/eventBaton.js`) - Pattern for transferring event handling responsibility - Used extensively for command processing and level events **TreeCompare** (`src/js/graph/treeCompare.js`) - Compares two commit trees for level completion validation - Handles branch positions, commit structure, tags **Animation Chains** - All visual updates go through animation queue - Uses Q promises to chain animations - Can be disabled for testing (headless mode) ## Project Structure ``` src/ ├── js/ │ ├── app/ # Application bootstrapping │ ├── git/ # Git engine and commands │ ├── mercurial/ # Mercurial (hg) support │ ├── commands/ # Command parsing and execution │ ├── level/ # Level loading and validation │ ├── visuals/ # Visualization and animation │ ├── views/ # Backbone views │ ├── react_views/ # React components │ ├── stores/ # Flux stores │ ├── actions/ # Flux actions │ ├── models/ # Backbone models and collections │ ├── intl/ # Internationalization │ ├── graph/ # Tree comparison logic │ └── util/ # Utilities ├── levels/ # Level definitions organized by category └── style/ # CSS files __tests__/ # Jasmine test specs index.html # Vite entry point and HTML view templates ``` ## Build Process The Vite build process: 1. `scripts/generate.js` writes `src/levels/generated/manifest.js` and `src/js/intl/generated/.js` (hooked via `predev`/`prebuild`/`pretest`) 2. Tests run with Jasmine 3. Vite bundles CommonJS JavaScript and transforms JSX; the generated `load()` thunks code-split each level and each locale into its own chunk, and third-party code is kept in a stable `vendor` chunk for cacheability 4. CSS and JavaScript are minified and hashed for cache busting 5. Static assets and generated documentation are copied into `build/` ### Lazy levels and locales Level definitions (dialog copy, trees, solutions) and locale string tables are the two largest parts of the app and carry every locale, so neither is imported at startup: - `src/levels/index.js` exposes the declarative `levelFiles` map (source of truth). The generated manifest holds only `id`/`name` for the level map, and `LevelStore.loadLevel(id)` dynamically imports the full definition when a level is opened. `startLevel` and the builder's edit path await it; everything else uses the synchronous stub. - `src/js/intl/strings.js` stays the translation source of truth. `intl` synchronously loads `en_US` as a fallback and lazily imports the active locale via `intl.loadLocale()`. The app resolves the locale and awaits that load before the first render (see `app/index.js` `detectLocale`), so users never see a frame of English first. Resolution order is `?locale=` URL param → stored preference (`localStorage.locale`, with a 180-day TTL) → browser header; picks are persisted on change. Later runtime switches emit a change event and re-render. `LocaleStore` itself stays synchronous. A shared loading overlay (`#appLoading` in `index.html`, driven by `src/js/util/appLoading.js`) covers slow startup and on-demand level loads; it fades in only after 250 ms so fast loads never flash it, and `bootstrap()` clears it (with a 15 s safety timeout). Levels are also prefetched on intent (next level after solving, or hovering the level map) via `LevelStore.prefetchLevel()`. ## Key Technologies - **Backbone.js**: MVC framework (legacy parts) - **React 17**: UI components (modern parts) - **Flux**: Unidirectional data flow - **Raphael.js**: SVG graphics for visualization - **Q**: Promises for animation chains - **jQuery/jQuery UI**: DOM manipulation and dialogs - **Vite**: Module bundling, development server, and JSX transform - **ESLint**: Static correctness checks - **Jasmine**: Testing framework ## Testing Conventions - Tests in `__tests__/` directory - Headless git engine for testing (`src/js/git/headless.js`) - Use `create.js` helper to set up test git trees - Mock commands with `mock.js` utility - Tests cover git operations, remote operations, levels, tree comparison ## Remote Repository Simulation Remote operations (push/pull/fetch) are simulated by creating a separate GitEngine instance for the "origin" repository. The `o/` prefix denotes remote tracking branches. ## Internationalization String translations in `src/js/intl/strings.js`. Use `intl.str()` and `intl.getDialog()` to access localized strings. Locale validation via `checkStrings.js`.