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.

If a given step is more complex than anticipated, consider breaking it down into additional steps and adding those checklist items below. If a given step is no longer appropriate or you discern it needs adjusted or re-scoping, raise it in discussion.

When a given step is completed, check it off.

---

## Phase 1: Project Foundation

### Development Environment
- [x] Create `flake.nix` with Node.js and pnpm
- [ ] Add Rust toolchain to `flake.nix` (for later WASM work)
- [ ] Add `flake.lock` and verify `nix develop` works
- [ ] Create `justfile` with `dev`, `build`, `test`, `lint` recipes
- [ ] Add `just fmt` recipe for code formatting
- [ ] Add `just wasm` recipe placeholder for Rust builds

### Vue Project Scaffold
- [ ] Initialize Vue 3 project with Vite and TypeScript
- [ ] Configure TypeScript with strict mode
- [ ] Add ESLint and Prettier configuration
- [ ] Create `.gitignore` for node_modules, dist, .env
- [ ] Set up path aliases (`@/` for `src/`)
- [ ] Create folder structure (`components/`, `composables/`, `stores/`, `types/`)
- [ ] Add Pinia for state management
- [ ] Verify hot module replacement works

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

---

## Phase 2: 3D Viewport Foundation

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

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

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

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

---

## Phase 3: Core UI Layout

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

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

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

---

## Phase 4: Selection System

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

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

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

---

## Phase 5: Transform Tools

### Transform Gizmos
- [ ] Install three.js `TransformControls`
- [ ] Attach gizmo to selected object(s)
- [ ] Implement translate mode
- [ ] Implement rotate mode
- [ ] Implement scale mode
- [ ] Hide gizmo when nothing selected

### Tool Switching
- [ ] Create toolbar with tool buttons (Select, Move, Rotate, Scale)
- [ ] Add keyboard shortcuts (Q=Select, W=Move, E=Rotate, R=Scale)
- [ ] Show active tool indicator
- [ ] Add Escape to switch to Select tool

### Transform Options
- [ ] Add snap-to-grid toggle for translate
- [ ] Add grid size input (1, 0.5, 0.1, etc.)
- [ ] Add angle snap toggle for rotate
- [ ] Add angle snap size (15°, 45°, 90°)

---

## 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: Persistence (IndexedDB)

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

### Project Storage
- [ ] Define `Project` interface (id, name, created, modified)
- [ ] Implement `saveProject()` - serialize scene
- [ ] Implement `loadProject()` - deserialize scene
- [ ] Implement `listProjects()` - get all projects
- [ ] Implement `deleteProject()`

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

### Unsaved Changes
- [ ] Track "dirty" state when scene modified
- [ ] Show unsaved indicator in header
- [ ] Warn before closing with unsaved changes
- [ ] Warn before "New Project" with unsaved changes

### Auto-Save
- [ ] Add debounced auto-save on scene changes
- [ ] Store current project ID in localStorage
- [ ] Load last project on app start

---

## 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