mattercontrol/TODO.md

# MatterControl Web Port - Development Checklist

A step-by-step checklist for porting MatterControl's design features to a Vue + TypeScript + three.js web application.

---

## Phase 1: Project Foundation

### Development Environment
- [x] Create `flake.nix` with Node.js and pnpm
- [x] Add Rust toolchain to `flake.nix` (for later WASM work)
- [x] Add `flake.lock` and verify `nix develop` works
- [x] Create `Justfile` with `dev`, `build`, `test`, `lint`, `format` recipes

### Vue Project Scaffold
- [x] Initialize Vue 3 project with Vite and TypeScript
- [x] Add ESLint and Prettier configuration
- [x] Create folder structure (`components/`, `composables/`, `stores/`, `types/`)
- [x] Add Pinia for state management

### Testing Infrastructure
- [x] Add Vitest for unit testing
- [x] Create first placeholder test
- [x] Add test script to `Justfile`

---

## Phase 2: 3D Viewport Foundation

### three.js Setup
- [x] Install three.js and `@types/three`
- [x] Create `Viewport.vue` component with canvas element
- [x] Initialize three.js Scene, Camera, and Renderer
- [x] Add resize observer for responsive canvas
- [x] Implement render loop with `requestAnimationFrame`
- [x] Add basic lighting (ambient + two directional)

### Scene Helpers
- [x] Add ground grid helper (XZ plane)
- [x] Add axis helper (RGB arrows for X/Y/Z)
- [x] Add option to toggle grid visibility
- [x] Add option to toggle axis visibility

### Camera Controls
- [x] Install and configure OrbitControls (zoom, pan, orbit)
- [x] Add "fit to selection" camera function
- [x] Add "reset view" function (home position)
- [x] Add view presets (front, back, top, bottom, left, right)
- [x] Add orthographic/perspective toggle

### Scene State Management
- [x] Create `useScene` composable for scene state
- [x] Define `SceneObject` interface (id, name, mesh, visible, locked)
- [x] Implement `addObject()` function
- [x] Implement `removeObject()` function
- [x] Implement `clearScene()` function
- [x] Add scene object list to Pinia store

---

## Phase 3: Core UI Layout

### Application Shell
- [x] Create `AppLayout.vue` with CSS Grid layout
- [x] Add header area with app title
- [x] Add left sidebar container (tools panel)
- [x] Add right sidebar container (properties panel)
- [x] Add center viewport area
- [x] Add bottom status bar

### Theme System
- [x] Define CSS custom properties for colors
- [x] Define CSS custom properties for spacing
- [x] Define CSS custom properties for typography
- [x] Create dark theme color palette
- [x] Apply theme to all components

### Sidebar Behavior
- [x] Create collapsible sidebar component
- [x] Add toggle buttons for left/right sidebars
- [x] Persist sidebar state to localStorage
- [x] Handle responsive layout for narrow screens

---

## Phase 4: Selection System

### Object Picking
- [x] Add Raycaster for mouse picking
- [x] Implement click-to-select single object
- [x] Implement click-on-empty to deselect
- [x] Add `selectedObjects` array to Pinia store
- [x] Implement Shift+click for multi-select
- [x] Implement Ctrl+click to toggle selection
- [x] Add "Select All" (Ctrl+A) shortcut

### Selection Visualization
- [x] Add selection outline effect (OutlinePass or custom)
- [x] Add hover highlight on mouseover
- [x] Distinguish single vs multi-selection visually

### Context Menu
- [x] Create right-click context menu component
- [x] Show context menu on object right-click
- [x] Add "Delete" option to context menu
- [x] Add "Duplicate" option to context menu
- [x] Add "Group" option to context menu
- [x] Close menu on click outside

---

## Phase 5: Transform Tools

### Translate Mode (Default with Selection)
- [ ] Create custom translate gizmo with 3 axis arrows (colored by axis)
- [ ] Attach gizmo to selected object(s)
- [ ] Left-drag handle: free translate along axis
- [ ] Right-drag handle: grid-aligned translate along axis
- [ ] Mouse wheel on handle: change grid granularity
- [ ] Hide gizmo when nothing selected

### Rotation Mode (Ctrl Modifier)
- [ ] Create custom rotation gizmo with flat ring handles per axis
- [ ] Show rotation rings when Ctrl held with selection
- [ ] Hover effect: ring thickens and brightens
- [ ] Left-drag ring: free (by-pixel) rotation
- [ ] Right-drag ring: constrained rotation (15°, 30°, 45° based on mouse distance from control)
- [ ] Display angle wheel during constrained rotation (world-oriented)
- [ ] Track object rotation state for world-oriented snapping

### Scale Mode (Ctrl+Shift Modifier)
- [ ] Create bounding box visualization for selection
- [ ] Show scale handles when Ctrl+Shift held with selection
- [ ] Corner handles: white cubes for uniform scaling
  - [ ] Left-drag: free scale
  - [ ] Right-drag: symmetrical proportional scale from center
- [ ] Face center handles: colored cubes (by axis) for stretch
  - [ ] Left-drag: one-directional stretch along axis
  - [ ] Right-drag: symmetrical stretch from center along axis
- [ ] Hover effect: handles grow subtly and brighten

### Camera Mode (Alt Modifier)
- [ ] Left-drag: orbit camera
- [ ] Right-drag: pan camera
- [ ] Left-click object: center/zoom camera on object

### Shift Modifier Behaviors
- [ ] Click with Shift: add to selection (already in Phase 4)
- [ ] Drag translate handle with Shift: duplicate selection along axis

---

## Phase 6: Properties Panel

### Panel Structure
- [ ] Create `PropertiesPanel.vue` component
- [ ] Show "No selection" state when empty
- [ ] Show "Multiple objects" state for multi-select
- [ ] Add collapsible sections

### Object Properties
- [ ] Display and edit object name
- [ ] Display and edit position (X, Y, Z)
- [ ] Display and edit rotation (X, Y, Z in degrees)
- [ ] Display and edit scale (X, Y, Z)
- [ ] Add uniform scale toggle (lock aspect ratio)

### Object State
- [ ] Add visibility toggle (eye icon)
- [ ] Add lock toggle (lock icon)
- [ ] Reflect visibility in viewport
- [ ] Prevent selection/transform of locked objects

### Mesh Info
- [ ] Display vertex count
- [ ] Display face count
- [ ] Display bounding box dimensions

---

## Phase 7: Undo/Redo System

### Command Infrastructure
- [ ] Define `Command` interface (execute, undo)
- [ ] Create `useHistory` composable
- [ ] Implement undo stack with max depth (50)
- [ ] Implement redo stack
- [ ] Clear redo stack on new action

### Core Commands
- [ ] Implement `AddObjectCommand`
- [ ] Implement `RemoveObjectCommand`
- [ ] Implement `TransformCommand`
- [ ] Implement `RenameCommand`
- [ ] Implement `GroupCommand`

### Integration
- [ ] Wrap all scene modifications in commands
- [ ] Wire Ctrl+Z to undo
- [ ] Wire Ctrl+Y / Ctrl+Shift+Z to redo
- [ ] Add undo/redo buttons to toolbar
- [ ] Disable buttons when stack empty

---

## Phase 8: File Import/Export

### STL Support
- [ ] Add three.js `STLLoader`
- [ ] Create file input component for import
- [ ] Parse STL and add mesh to scene
- [ ] Add three.js `STLExporter`
- [ ] Implement "Export as STL" function
- [ ] Add binary/ASCII export option

### OBJ Support
- [ ] Add three.js `OBJLoader`
- [ ] Parse OBJ and add mesh to scene
- [ ] Add three.js `OBJExporter`
- [ ] Implement "Export as OBJ" function

### Export Options
- [ ] Create export dialog component
- [ ] Add "Export Selected" option
- [ ] Add "Export All" option
- [ ] Remember last export settings

### Drag and Drop
- [ ] Add drag-and-drop zone overlay
- [ ] Detect file type from extension
- [ ] Route to appropriate loader
- [ ] Show loading indicator during import
- [ ] Handle import errors with toast message

---

## Phase 9: Primitives (MVP)

### Primitive Generation
- [ ] Create `usePrimitives` composable
- [ ] Implement Box primitive
- [ ] Implement Sphere primitive
- [ ] Implement Cylinder primitive
- [ ] Auto-select newly created primitives
- [ ] Place primitives at scene origin (or selection center)

### Primitives Panel
- [ ] Create primitives panel in left sidebar
- [ ] Add clickable primitive icons/buttons
- [ ] Show primitive name on hover

### Parametric Editing
- [ ] Store primitive parameters in object metadata
- [ ] Show parameters in properties panel for primitives
- [ ] Update mesh when parameters change
- [ ] Add "Convert to Mesh" to bake parameters

---

## Phase 10: Clipboard & Grouping

### Clipboard Operations
- [ ] Implement Copy (Ctrl+C) - serialize to clipboard
- [ ] Implement Cut (Ctrl+X) - copy then delete
- [ ] Implement Paste (Ctrl+V) - deserialize and add
- [ ] Offset pasted objects slightly to show difference
- [ ] Implement Duplicate (Ctrl+D) - copy + paste in one action

### Object Grouping
- [ ] Implement Group command (Ctrl+G)
- [ ] Create Group object that contains children
- [ ] Select group selects all children
- [ ] Transform group transforms all children
- [ ] Implement Ungroup command (Ctrl+Shift+G)
- [ ] Allow entering group to edit children

---

## Phase 11: Continuous Autosave

### Database Setup
- [ ] Install `idb` library (IndexedDB wrapper)
- [ ] Define database schema version 1
- [ ] Create `scene` object store for current scene state
- [ ] Create `settings` object store
- [ ] Implement database open/migration

### Scene Serialization
- [ ] Serialize mesh geometry (positions, normals, indices)
- [ ] Serialize object transforms and metadata
- [ ] Serialize group hierarchy
- [ ] Handle large meshes efficiently (binary format)

### Continuous Autosave
- [ ] Implement autosave on every scene change (debounced)
- [ ] Save immediately on significant actions (add/delete object, transform complete)
- [ ] Load saved scene automatically on app start
- [ ] Handle serialization errors gracefully
- [ ] Show subtle save indicator during autosave (optional)

---

## Phase 12: Project Management UI

### Toolbar Actions
- [ ] Add "New" button - create empty project
- [ ] Add "Open" button - show project browser
- [ ] Add "Save" button - save current project
- [ ] Add "Save As" button - save with new name
- [ ] Add "Export" button - open export dialog

### Project Browser
- [ ] Create project browser dialog
- [ ] Display projects as list with name and date
- [ ] Add delete button per project
- [ ] Add rename option per project
- [ ] Double-click to open project

### Recent Projects
- [ ] Track recently opened projects
- [ ] Add recent projects to File menu
- [ ] Limit to last 5-10 projects

---

## Phase 13: Extended Primitives

### Additional Shapes
- [ ] Implement Cone primitive
- [ ] Implement Torus primitive
- [ ] Implement Plane/Quad primitive
- [ ] Implement Wedge/Prism primitive
- [ ] Add parameter UI for each shape

### Text Primitive
- [ ] Add font loading (Google Fonts or bundled)
- [ ] Implement 3D extruded text
- [ ] Add text content input
- [ ] Add font size parameter
- [ ] Add extrusion depth parameter
- [ ] Add font family selector

---

## Phase 14: Basic Mesh Operations

### Transform Operations
- [ ] Implement "Center to Origin"
- [ ] Implement "Align to Ground" (bottom at Z=0)
- [ ] Implement "Mirror X"
- [ ] Implement "Mirror Y"
- [ ] Implement "Mirror Z"

### Array/Pattern
- [ ] Implement linear array (count + spacing)
- [ ] Implement grid array (X count × Y count)
- [ ] Create array objects as group

### Mesh Utilities
- [ ] Implement "Flip Normals"
- [ ] Implement "Recompute Normals" (flat/smooth)
- [ ] Implement "Merge Vertices" (weld by distance)

---

## Phase 15: Boolean Operations (CSG)

### CSG Setup
- [ ] Research and select CSG library (manifold.js recommended)
- [ ] Install and test CSG library
- [ ] Create Web Worker for CSG operations
- [ ] Create `useBooleans` composable

### Boolean Operations
- [ ] Implement Union (combine meshes)
- [ ] Implement Subtract (cut mesh from mesh)
- [ ] Implement Intersect (keep overlap)
- [ ] Validate: require exactly 2 objects selected
- [ ] Handle CSG errors gracefully

### Boolean UI
- [ ] Add Boolean section to toolbar or menu
- [ ] Show progress indicator for slow operations
- [ ] Add operation to undo history

---

## Phase 16: Advanced Mesh Operations

### Mesh Modification
- [ ] Implement mesh simplification (decimate)
- [ ] Add target face count or ratio input
- [ ] Implement subdivision smooth
- [ ] Add subdivision level input

### Mesh Analysis
- [ ] Detect non-manifold edges
- [ ] Highlight non-manifold edges in red
- [ ] Detect holes (boundary edges)
- [ ] Implement "Fill Holes" repair

---

## Phase 17: Library Browser

### Library Panel
- [ ] Create `LibraryPanel.vue` in left sidebar
- [ ] Display saved projects as cards
- [ ] Show project name and modified date
- [ ] Add search/filter input

### Thumbnails
- [ ] Generate thumbnail on project save
- [ ] Render scene to off-screen canvas
- [ ] Store thumbnail as data URL in IndexedDB
- [ ] Display thumbnail in library card

---

## Phase 18: Polish & UX

### User Feedback
- [ ] Add toast notification system
- [ ] Show success toast on save
- [ ] Show error toast on failures
- [ ] Add loading spinner component
- [ ] Show loading during imports

### Confirmations
- [ ] Add confirmation dialog component
- [ ] Confirm before delete objects
- [ ] Confirm before delete project
- [ ] Confirm before clear scene

### Keyboard Shortcuts Help
- [ ] Create keyboard shortcuts modal
- [ ] Add "?" key to open shortcuts help
- [ ] List all available shortcuts

---

## Phase 19: Performance

### Render Optimization
- [ ] Profile render loop performance
- [ ] Implement frustum culling
- [ ] Add level-of-detail for distant objects
- [ ] Throttle property panel updates

### Large Scenes
- [ ] Test with 100+ objects
- [ ] Optimize scene tree rendering
- [ ] Lazy-render off-screen UI
- [ ] Profile memory usage

---

## Phase 20: Rust + WASM Migration

### Rust Project Setup
- [ ] Create `crates/mesh-ops/` directory
- [ ] Initialize Cargo workspace
- [ ] Add wasm-bindgen dependency
- [ ] Add nalgebra dependency
- [ ] Configure wasm-pack build
- [ ] Update `just wasm` recipe

### Mesh Data in Rust
- [ ] Define Mesh struct (vertices, indices, normals)
- [ ] Implement mesh creation from JS arrays
- [ ] Implement mesh export to JS arrays
- [ ] Add tests for mesh operations

### Port Operations to Rust
- [ ] Port "Merge Vertices" to Rust
- [ ] Port "Compute Normals" to Rust
- [ ] Port mesh simplification to Rust
- [ ] Port CSG operations to Rust (or wrap manifold)

### Integration
- [ ] Create TypeScript wrapper for WASM module
- [ ] Replace JS implementations with WASM calls
- [ ] Benchmark performance improvement
- [ ] Add WASM loading fallback for old browsers

---

## Future Considerations (Out of Scope)

- [ ] Additional file formats (3MF, AMF, STEP)
- [ ] Measurement tools (distance, angle)
- [ ] Section view / clipping planes
- [ ] Multi-user collaboration
- [ ] Plugin/extension system
- [ ] Mobile/touch support
- [ ] Offline PWA support