house-design/RESEARCH.md

# Interior Design Visualization - Tech Stack Research

**Task:** t-fb166
**Date:** 2026-02-07
**Researcher:** bohr

## Executive Summary

**Recommended approach: 2D-first with Konva.js (react-konva), Vite+React app, with optional 3D preview via React Three Fiber later.**

This is the simplest viable path to a working room planner prototype. Start with 2D canvas-based floor plan editing, add 3D viewing as a second phase.

---

## Options Evaluated

### Option A: Pure 3D with React Three Fiber (R3F)

**Stack:** Vite + React + @react-three/fiber + @react-three/drei

**How it works:** Everything rendered in a WebGL 3D scene. Room walls are 3D meshes, furniture are 3D models (GLTF/GLB), camera orbits around the scene.

**Pros:**
- Visually impressive - realistic lighting, shadows, materials
- R3F is mature (huge community, active maintenance, excellent docs)
- drei provides orbit controls, drag controls, environment maps out of the box
- Good ecosystem of 3D furniture models (Sketchfab, etc.)

**Cons:**
- **Hardest to build** - 3D drag-and-drop is complex (raycasting, plane projection)
- Precise measurement/placement is difficult in 3D
- Requires 3D model assets for all furniture (heavy, complex pipeline)
- Performance concerns with many objects + shadows
- Steep learning curve for 3D math (vectors, quaternions, raycasting)
- Drawing room outlines in 3D is unintuitive for users

**Complexity: HIGH** | **Time to prototype: 3-4 weeks**

**Key repos:**
- [threejs-3d-room-designer](https://github.com/CodeHole7/threejs-3d-room-designer) - React + Three.js room planner
- [threejs-room-planner](https://github.com/nickorzha/threejs-room-planner) - Similar approach

---

### Option B: Hybrid 2D Editor + 3D Preview (react-planner style)

**Stack:** Vite + React + SVG (2D) + Three.js (3D preview)

**How it works:** Users draw/edit floor plans in a 2D SVG view, then toggle to a 3D preview. The same data model drives both views.

**Pros:**
- Best UX - 2D for precise editing, 3D for visualization
- Proven concept (react-planner has 1.4k GitHub stars)
- 2D editing is simpler and more intuitive for users
- 3D adds wow factor for presentations

**Cons:**
- Must maintain two rendering paths (SVG + Three.js)
- react-planner itself is **outdated** (React 16, Redux, Immutable.js - needs modernization)
- More code to maintain than either pure approach
- SVG can become slow with very complex plans

**Complexity: MEDIUM-HIGH** | **Time to prototype: 2-3 weeks**

**Key repos:**
- [react-planner](https://github.com/cvdlab/react-planner) - 1.4k stars, SVG 2D + Three.js 3D, but old React stack
- [arcada](https://github.com/mehanix/arcada) - React + Pixi.js, 196 stars, includes backend

---

### Option C: 2D Canvas with Konva.js (RECOMMENDED)

**Stack:** Vite + React + react-konva

**How it works:** Room plans rendered on HTML5 Canvas via Konva.js. Rooms are drawn as polygons/rectangles, furniture items are draggable shapes/images. Top-down 2D view.

**Pros:**
- **Simplest to build** - Konva handles drag-drop, transforms, snapping natively
- react-konva integrates cleanly with React component model
- Canvas performs well with hundreds of objects
- Built-in: drag-and-drop, resize handles, rotation, snapping, grouping, layers
- Easy to add grid snapping, measurements, labels
- Export to PNG/PDF straightforward
- Familiar 2D interaction model for users (like Google Slides)
- Can add 3D preview later using same data model

**Cons:**
- No 3D visualization (initially)
- Less visually impressive than 3D
- Canvas text rendering less crisp than SVG (mitigated by high-DPI)

**Complexity: LOW-MEDIUM** | **Time to prototype: 1-2 weeks**

**Alternative: Fabric.js** - Similar capabilities, also canvas-based, slightly different API. Konva has better React integration via react-konva.

---

### Option D: 2D SVG with React

**Stack:** Vite + React + raw SVG (or svg.js)

**How it works:** Floor plans rendered as SVG elements directly in React. Furniture items are SVG groups with drag behavior.

**Pros:**
- SVG is resolution-independent (crisp at all zoom levels)
- React manages SVG elements naturally (they're just DOM nodes)
- Good for precise measurements and labels
- Easy to style with CSS

**Cons:**
- Performance degrades with many elements (SVG is DOM-based)
- Custom drag-and-drop implementation needed (no built-in like Konva)
- Transform handles, snapping, rotation all manual work
- More boilerplate than Konva for interactive features

**Complexity: MEDIUM** | **Time to prototype: 2 weeks**

---

## Comparison Matrix

| Criteria              | A: Pure 3D (R3F) | B: Hybrid 2D+3D | C: 2D Konva (rec) | D: 2D SVG |
|-----------------------|-------------------|------------------|---------------------|-----------|
| Time to prototype     | 3-4 weeks         | 2-3 weeks        | **1-2 weeks**       | 2 weeks   |
| Visual impact         | **Highest**       | High             | Medium              | Medium    |
| Ease of furniture add | Hard (3D models)  | Medium           | **Easy (images)**   | Easy      |
| Drag-and-drop         | Complex           | Medium           | **Built-in**        | Manual    |
| Precise placement     | Hard              | Good             | **Good**            | Good      |
| Performance           | Medium            | Medium           | **Good**            | Medium    |
| Upgrade path to 3D    | N/A               | Built-in         | **Add later**       | Add later |
| Learning curve        | Steep             | Medium           | **Low**             | Low       |
| Mobile support        | Limited           | Limited          | **Good (touch)**    | Good      |

---

## Recommended Architecture

### Phase 1: 2D Room Planner (MVP)

```
Tech Stack:
- Vite + React + TypeScript
- react-konva (2D canvas rendering)
- Zustand (lightweight state management)
- Tailwind CSS (UI styling)
- shadcn/ui (UI components)

Features:
- Draw room outlines (rectangles, L-shapes)
- Grid-based canvas with snap-to-grid
- Furniture catalog sidebar (chair, table, bed, sofa, etc.)
- Drag furniture from catalog onto room
- Move, rotate, resize placed furniture
- Room dimensions and measurements
- Export as PNG image
- Save/load room plans (JSON)
```

### Phase 2: Enhanced Features

```
- Upload room image as background trace layer
- More furniture with realistic top-down SVG/PNG icons
- Multiple rooms / full floor plans
- Wall thickness and door/window placement
- Measurement labels and area calculation
- Color/material swatches for floors and walls
```

### Phase 3: 3D Preview (Optional)

```
Add-on stack:
- @react-three/fiber + @react-three/drei
- Same room data model → 3D scene generation
- Orbit camera view of the room
- Basic lighting and materials
```

---

## Key Libraries

| Library | Purpose | npm Weekly Downloads | Maturity |
|---------|---------|---------------------|----------|
| react-konva | React bindings for Konva canvas | ~100k+ | Stable, active |
| konva | 2D canvas framework | ~200k+ | Stable, v9+ |
| zustand | State management | ~3M+ | Very active |
| @react-three/fiber | React Three.js (Phase 3) | ~500k+ | Very active |
| @react-three/drei | R3F helpers (Phase 3) | ~500k+ | Very active |

---

## Existing Projects Worth Studying

1. **[react-planner](https://github.com/cvdlab/react-planner)** - Best reference for hybrid 2D/3D architecture. Study its data model even if not using the code directly (it's outdated React 16).

2. **[arcada](https://github.com/mehanix/arcada)** - React + Pixi.js floor planner. Good reference for feature set and UX patterns. Has a [bachelor's thesis document](https://github.com/mehanix/arcada/blob/master/docs/) explaining the architecture.

3. **[Floorplan.js](https://floorplanjs.org/)** - Commercial-ish but has good UX patterns to study.

4. **Sweet Home 3D** - Java desktop app, but gold standard for feature set reference. Shows what users expect from a room planner.

---

## Data Model Sketch

```typescript
interface RoomPlan {
  id: string;
  name: string;
  rooms: Room[];
  furniture: FurnitureItem[];
}

interface Room {
  id: string;
  points: Point[];  // polygon vertices
  label: string;
  floorColor: string;
}

interface FurnitureItem {
  id: string;
  catalogId: string;  // reference to catalog
  x: number;
  y: number;
  rotation: number;   // degrees
  scaleX: number;
  scaleY: number;
}

interface CatalogEntry {
  id: string;
  name: string;
  category: string;
  width: number;      // real-world cm
  height: number;
  icon: string;       // SVG/PNG path for 2D view
  model3d?: string;   // GLTF path for future 3D view
}
```

This data model works for both 2D rendering (Konva) and future 3D rendering (R3F), enabling a clean upgrade path.

---

## Conclusion

**Start with Option C (2D Konva.js)** because:
1. Fastest path to a working prototype
2. Konva handles 90% of the interactive features we need out of the box
3. Clean data model that separates room geometry from rendering
4. 3D can be added as a second view of the same data later
5. Modern stack (Vite + React + TS + Zustand) with excellent DX
6. Low risk - all well-maintained, well-documented libraries