New 3D tensor mode

Author: diegochine

CLAUDE.md

@@ -4,7 +4,11 @@ This file provides guidance to Claude Code when working with code in this reposi
 
 ## Project Overview
 
-This is **Interactive Linear Algebra** - an educational web application for teaching vector operations through visual experimentation. Students can draw vectors on a 2D Cartesian plane and perform operations (addition, subtraction, scalar multiplication, dot products, projections) with smooth animated visualizations.
+This is **Interactive Linear Algebra** - an educational web application for teaching linear algebra concepts through visual experimentation. The application supports three interaction modes:
+
+- **Vector Mode**: Draw vectors on a 2D Cartesian plane and perform operations (addition, subtraction, scalar multiplication, dot products, projections) with smooth animated visualizations
+- **Matrix Mode**: Visualize 2×2 matrix transformations and their effects on basis vectors
+- **Tensor Mode**: Explore tensors of different ranks (0-3) in an interactive 3D space with drag-to-rotate and scroll-to-zoom controls
 
 This application also serves as a reference implementation of the **Bespoke framework** - a reusable set of generalized CSS and JavaScript components designed for building embedded educational applications.
 
@@ -38,22 +42,30 @@ No build step required - this is pure HTML/CSS/JavaScript with no frameworks or
 
 ### Core Components
 
-1. **Vector Class** (`client/linear-algebra.js`)
+1. **Vector Class** (`client/core/vector.js`)
    - Encapsulates mathematical vector operations
    - Methods: add, subtract, scale, dot, normalize, project, reflect
 
-2. **LinearAlgebraApp Class** (`client/linear-algebra.js`)
-   - Main application controller
-   - Manages canvas rendering, user interactions, and animations
-   - Configuration-driven design via CONFIG object
+2. **Mode System** (`client/core/mode-manager.js`, `client/modes/`)
+   - Three modes: VectorMode, MatrixMode, TensorMode
+   - Each mode is a controller managing its own UI, canvas rendering, and interactions
+   - Modes subscribe to theme changes and clean up properly on destroy
+   - See `client/modes/AGENTS.md` for detailed implementation contracts
+
+3. **TensorMode** (`client/modes/tensor-mode.js`, `client/modes/tensor-canvas-3d.js`)
+   - Visualizes tensors of ranks 0-3 in interactive 3D space
+   - Uses `TensorCanvas3D` for 3D rendering with mouse drag rotation and scroll zoom
+   - Supports scalar, vector, matrix, and 3D tensor inputs
+   - See `client/modes/AGENTS.md` for lifecycle and teardown requirements
 
-3. **HelpModal** (`client/help-modal.js`)
+4. **HelpModal** (`client/help-modal.js`)
    - Reusable modal component with theme support
    - Singleton pattern with event handling
+   - Mode-specific help content loaded from `help-content-*.html` files
 
-4. **Status Management** (`client/app.js`)
-   - WebSocket client for real-time updates
+5. **Status Management** (`client/core/status.js`, `client/app.js`)
    - Standardized status messaging system
+   - WebSocket client for real-time updates (optional)
 
 ### File Loading Order
 
@@ -116,10 +128,21 @@ client/
 ├── help-modal.js            # Reusable help modal
 ├── app.js                   # WebSocket & status handling
 ├── linear-algebra.js        # Main app logic
-├── linear-algebra.css       # App-specific styles
+├── config.json              # Application configuration (modes, operations)
+├── core/                    # Shared services
+│   ├── mode-manager.js      # Mode switching system
+│   ├── theme-service.js     # Theme management
+│   ├── coordinate-system.js # Coordinate system
+│   └── ...                  # Other core services
+├── modes/                   # Mode controllers
+│   ├── vector-mode.js       # Vector mode controller
+│   ├── matrix-mode.js       # Matrix mode controller
+│   ├── tensor-mode.js       # Tensor mode controller
+│   └── tensor-canvas-3d.js  # 3D canvas renderer for tensor mode
+├── help-content-*.html      # Mode-specific help content
 └── index.html               # Main HTML structure
 
 server.js                    # Development server
-test-integration.html        # Component testing page
 AGENTS.md                    # Bespoke framework implementation guide
+client/modes/AGENTS.md       # Mode implementation contracts
 ```

README.md

@@ -11,6 +11,7 @@ An interactive educational tool for learning vector operations through visual ex
 - **Real-time Calculations**: View coordinates, magnitude, and angle for each vector
 - **Animated Operations**: Smooth transitions showing vector transformations
 - **Formula Display**: Mathematical formulas and calculations shown for each operation
+- **Tensor Visualization**: Interactive 3D visualization of tensors (scalars, vectors, matrices, 3D tensors)
 
 ### Supported Operations
 - ✅ **Vector Addition** (v₁ + v₂)
@@ -20,9 +21,19 @@ An interactive educational tool for learning vector operations through visual ex
 - ✅ **Magnitude Calculation** (||v||)
 - ✅ **Angle Measurement** (in degrees from positive x-axis)
 
+### Modes
+
+The application supports three interaction modes:
+
+1. **Vector Mode**: Draw and manipulate vectors on a 2D Cartesian plane with animated operations
+2. **Matrix Mode**: Visualize 2×2 matrix transformations and their effects on basis vectors
+3. **Tensor Mode**: Explore tensors of different ranks (0-3) in an interactive 3D space
+
+Modes can be enabled/disabled via the `enabledModes` array in `client/config.json`. The default mode is set via the `mode` property in the config file.
+
 ### User Interface
-- **Left Sidebar**: Control panel with vector information and operation buttons
-- **Main Canvas**: Full-screen 2D Cartesian plane with grid
+- **Left Sidebar**: Control panel with mode-specific information and operation buttons
+- **Main Canvas**: Full-screen coordinate plane (2D for vector/matrix modes, 3D for tensor mode)
 - **No Scrolling**: Fully responsive, single-page layout
 - **Help System**: Comprehensive help modal with instructions and FAQ
 
@@ -34,19 +45,31 @@ An interactive educational tool for learning vector operations through visual ex
    ```
    Server runs at `http://localhost:3000`
 
-2. **Create vectors**:
-   - Click and drag anywhere on the grid
-   - First vector (v₁) will be red
-   - Second vector (v₂) will be blue
-
-3. **Perform operations**:
-   - Use buttons in the left sidebar
-   - Watch animated results
-   - Read formulas in the Results section
-
-4. **Clear and experiment**:
-   - Clear individual vectors or all at once
-   - Try different vector configurations
+2. **Choose a mode**:
+   - Use the mode switcher buttons (if multiple modes are enabled)
+   - Default mode is set in `client/config.json` (`mode` property)
+   - Available modes: Vector, Matrix, Tensor
+
+3. **Vector Mode**:
+   - Click and drag anywhere on the grid to create vectors
+   - First vector (v₁) will be red, second vector (v₂) will be blue
+   - Use buttons in the left sidebar to perform operations
+   - Watch animated results and read formulas in the Results section
+
+4. **Matrix Mode**:
+   - Enter values in the 2×2 matrix input grid
+   - See how the matrix transforms basis vectors î and ĵ
+   - Toggle determinant visualization to see area scaling
+
+5. **Tensor Mode**:
+   - Select a tensor rank (0-3) using the rank buttons
+   - Rank 0: Scalar (single value)
+   - Rank 1: Vector (x, y components)
+   - Rank 2: Matrix (2×2 grid)
+   - Rank 3: 3D Tensor (2×2×2 cube)
+   - Enter values in the input fields to modify tensor components
+   - Drag to rotate the 3D visualization, scroll to zoom
+   - See detailed help in `help-content-tensor.html`
 
 ## Project Structure
 
@@ -58,8 +81,26 @@ learn-bespoke-linear-algebra/
 │   ├── linear-algebra.css            # App-specific styles
 │   ├── linear-algebra.js             # Main application logic
 │   ├── help-modal.js                 # Help modal component
-│   ├── help-content-template.html    # Help content
-│   └── app.js                        # WebSocket/status handling
+│   ├── help-content-template.html    # Help content template
+│   ├── help-content-vector.html      # Vector mode help content
+│   ├── help-content-matrix.html      # Matrix mode help content
+│   ├── help-content-tensor.html      # Tensor mode help content
+│   ├── app.js                        # WebSocket/status handling
+│   ├── config.json                   # Application configuration
+│   ├── core/                         # Shared services
+│   │   ├── config.js                 # Config service
+│   │   ├── mode-manager.js           # Mode switching
+│   │   ├── theme-service.js          # Theme management
+│   │   ├── coordinate-system.js      # Coordinate system
+│   │   └── ...                       # Other core services
+│   ├── modes/                        # Mode controllers
+│   │   ├── vector-mode.js            # Vector mode controller
+│   │   ├── matrix-mode.js            # Matrix mode controller
+│   │   ├── tensor-mode.js            # Tensor mode controller
+│   │   ├── tensor-canvas-3d.js       # 3D canvas renderer
+│   │   └── ...                       # Other mode files
+│   └── entities/                     # Data models
+│       └── matrix.js                 # Matrix class
 ├── server.js                         # Development server
 ├── package.json                      # Dependencies
 └── README.md                         # This file
@@ -125,6 +166,49 @@ Modern browsers with Canvas support:
 - Firefox (latest)
 - Safari (latest)
 
+## Manual Testing Checklist
+
+Use this checklist to verify all modes work correctly after changes:
+
+### Mode Switching
+- [ ] Mode switcher buttons appear/disappear based on `enabledModes` config
+- [ ] Switching between modes updates the UI correctly
+- [ ] Each mode displays its own sidebar content
+- [ ] Canvas renders correctly for each mode
+
+### Vector Mode
+- [ ] Click and drag creates vectors on the canvas
+- [ ] Vector operations (add, subtract, scalar multiply, dot product) work
+- [ ] Animations play smoothly
+- [ ] Results panel displays calculation formulas
+- [ ] Status remains "Ready" after operations
+
+### Matrix Mode
+- [ ] Matrix input grid accepts numeric values
+- [ ] Basis vectors update when matrix changes
+- [ ] Determinant visualization toggles correctly (if enabled)
+- [ ] Reset button restores identity matrix
+- [ ] Status remains "Ready" after operations
+
+### Tensor Mode
+- [ ] Rank buttons (0-3) update UI inputs correctly
+- [ ] Rank toggle updates 3D render visualization
+- [ ] Scalar input (rank 0) updates single cube visualization
+- [ ] Vector inputs (rank 1) update two-cube visualization
+- [ ] Matrix inputs (rank 2) update 2×2 grid visualization
+- [ ] Tensor3D inputs (rank 3) update 2×2×2 cube visualization
+- [ ] Drag interaction rotates 3D view smoothly
+- [ ] Scroll/zoom interaction works correctly
+- [ ] Reset button restores default tensor values
+- [ ] Help button shows tensor help content when tensor mode is active
+- [ ] Status remains "Ready" after all interactions
+
+### Theme and Cleanup
+- [ ] Theme changes update all mode visualizations correctly
+- [ ] Switching away from a mode cleans up properly (no memory leaks)
+- [ ] Event listeners are removed when modes are destroyed
+- [ ] Canvas interaction handlers are cleaned up (especially tensor mode 3D canvas)
+
 ---
 
 ## Template Components (Bespoke Framework)

client/config.json

@@ -1,5 +1,6 @@
 {
-  "mode": "matrix",
+  "mode": "tensor",
+  "enabledModes": ["vector", "matrix", "tensor"],
   "vectorMode": {
     "maxVectors": 2,
     "operationGroups": {

client/core/config.js

@@ -10,6 +10,7 @@
   // Default configuration
   const DEFAULT_CONFIG = {
     mode: 'vector',
+    enabledModes: ['vector', 'matrix', 'tensor'],
     vectorMode: {
       maxVectors: 2,
       operationGroups: {
@@ -56,7 +57,10 @@
 
         if (!response.ok) {
           console.warn('config.json not found, using default configuration');
-          const config = { ...DEFAULT_CONFIG };
+          const config = {
+            ...DEFAULT_CONFIG,
+            enabledModes: [...DEFAULT_CONFIG.enabledModes]
+          };
           configCache = config;
 
           if (window.StatusService) {
@@ -71,6 +75,9 @@
         // Merge with defaults
         const config = {
           mode: userConfig.mode || DEFAULT_CONFIG.mode,
+          enabledModes: Array.isArray(userConfig.enabledModes) && userConfig.enabledModes.length > 0
+            ? userConfig.enabledModes
+            : DEFAULT_CONFIG.enabledModes,
           vectorMode: {
             ...DEFAULT_CONFIG.vectorMode,
             ...(userConfig.vectorMode || userConfig), // Backward compatible
@@ -99,7 +106,10 @@
         return config;
       } catch (error) {
         console.warn('Failed to load config.json, using default configuration:', error);
-        const config = { ...DEFAULT_CONFIG };
+        const config = {
+          ...DEFAULT_CONFIG,
+          enabledModes: [...DEFAULT_CONFIG.enabledModes]
+        };
         configCache = config;
 
         if (window.StatusService) {

client/core/help.js

@@ -9,12 +9,17 @@
 
   /**
    * Load help content from template file
-   * @param {string} mode - Mode name ('vector' or 'matrix')
+   * @param {string} mode - Mode name ('vector', 'matrix', or 'tensor')
    * @returns {Promise<string>} Promise that resolves to help content HTML
    */
   async function loadHelpContent(mode = 'vector') {
     // Determine filename based on mode
-    const filename = mode === 'matrix' ? 'help-content-matrix.html' : 'help-content-vector.html';
+    let filename = 'help-content-vector.html';
+    if (mode === 'matrix') {
+      filename = 'help-content-matrix.html';
+    } else if (mode === 'tensor') {
+      filename = 'help-content-tensor.html';
+    }
 
     // Return cached promise if it exists
     if (helpContentCache[mode]) {
@@ -43,7 +48,7 @@
    * Modes can append additional content using appendHelpContent()
    * @param {Object} options - Initialization options
    * @param {string} options.triggerSelector - CSS selector for help button
-   * @param {string} [options.mode] - Mode name ('vector' or 'matrix'), defaults to 'vector'
+   * @param {string} [options.mode] - Mode name ('vector', 'matrix', or 'tensor'), defaults to 'vector'
    * @param {string} [options.additionalContent] - Additional HTML content to append
    * @param {string} [options.theme] - Theme mode ('auto', 'light', 'dark')
    * @returns {Promise<void>}
@@ -98,7 +103,7 @@
    * Append additional content to the help modal
    * Useful for mode-specific help sections
    * @param {string} content - HTML content to append
-   * @param {string} [mode] - Mode name ('vector' or 'matrix'), defaults to 'vector'
+   * @param {string} [mode] - Mode name ('vector', 'matrix', or 'tensor'), defaults to 'vector'
    * @returns {Promise<void>}
    */
   async function appendHelpContent(content, mode = 'vector') {