# Flutter Shape Builder - Full Documentation

This file contains the complete documentation for the Flutter Shape Builder project, consolidated for LLM context.

---

## 📂 Project Structure

```text
.
├── src/
│   ├── features/
│   │   ├── editor/             # Main editor functionality
│   │   │   ├── components/     # Canvas, Toolbar, Sidebar
│   │   │   ├── store/          # Zustand store (useStore.ts)
│   │   │   └── utils/          # Exporters, Path Parsers, Boolean Ops
│   │   └── landing/            # Marketing Landing Page
│   ├── components/             # Reusable UI components
│   ├── store/                  # Shared stores
│   ├── utils/                  # Analytics, Notifications
│   ├── types/                  # TypeScript definitions
│   └── main.tsx                # Entry point
├── public/                     # Static assets & videos
├── EMAIL_FEEDBACK_IMPLEMENTATION.md
├── CURVE_EDITING_GUIDE.md
├── DOCUMENTATION.md
├── README.md
└── llm.txt
```

---

## 🚀 Overview (llm.txt)

Flutter Shape Builder is a high-performance vector editing tool designed specifically for Flutter developers. It bridges the gap between manual drawing and `dart:ui` code generation, allowing for the creation of complex, high-performance UI elements without external SVG dependencies.

### Tech Stack
- **Framework**: React 19 (Vite)
- **Canvas Engine**: Konva.js (with react-konva) for efficient layer-based rendering and interaction.
- **Geometry Logic**: Paper.js for complex path algorithms and boolean operations.
- **State Management**: Zustand with `persist` middleware for local-first state and history tracking.
- **Styles**: Vanilla CSS with PostCSS (Tailwind for layout utilities).
- **Backend/Ops**: Firebase (Analytics, Performance Monitoring, and custom Error Tracking).

### Feature Deep Dive
- **Creative & Geometry Tools**: Parametric Rectangle and Circle tools. Regular Polygons with dynamic side count adjustment. Pen (Path) Tool with linear and cubic Bezier support. Boolean Operations (Unite, Subtract, Intersect, Exclude).
- **Editing & Transformation**: Multi-selection (Shift+Click), Context Menu (Right-click). Vertex Editing (Double-click anchors to toggle Sharp/Smooth). Precise Controls for X, Y, Width, Height, Rotation, and Corner Radii.
- **Export Options**: 
    - **Flutter (Dart)**: Runnable App, Widget, or Painter class.
    - **SVG**: Standards-compliant file download.
    - **JSON**: Raw configuration export.

---

## 🎨 Implementation Guide (DOCUMENTATION.md)

### Drawing System
The editor uses a layered canvas approach powered by **Konva.js**, enabling distinct interaction models for different shape types:

1. **Primitives (Rectangle, Circle)**: uses a "Drag-to-Create" model. Stored as parametric objects.
2. **Polygons**: Uses a "Click-to-Add" model. Each click adds a vertex. `Enter` closes the loop.
3. **Paths (Pen Tool)**: Supports sequential `Move` and `Line` commands. When selected, the "PathAnchors" system allows moving anchors, converting to curves (double-click), and inserting points.

### Export Engine
The code generation pipeline follows a strict normalization process:
1. **Normalization**: All shapes converted to SVG Path Data.
2. **Parsing**: Path string parsed into an AST of commands.
3. **Transpilation**: Commands mapped 1:1 to Flutter `Path` methods (`moveTo`, `lineTo`, `cubicTo`, `quadraticBezierTo`, `close`).
4. **Paint Generation**: Analysis of fill and stroke to generate the correct `Paint` object (including hex-to-Flutter color conversion).

---

## 📐 Anchor Points & Curve Editing (CURVE_EDITING_GUIDE.md)

### Visual Guide
- 🔵 **Blue circles**: Anchor points (path vertices)
- 🟢 **Green circles**: Control points (curve handles)

### Technical Details
- **Supported SVG Commands**: `M` (MoveTo), `L` (LineTo), `C` (Cubic Bezier), `Q` (Quadratic Bezier), `Z` (Close Path).
- **Mathematical Foundation**: USes De Casteljau's algorithm for curve subdivision.

---

## 🔨 Technical Constraints & Limitations

- **Circles**: Render correctly in-app but export as SVG Arc commands (`A`), which are currently placeholders in the Flutter exporter.
- **Gradients**: Not supported; only solid colors and transparency are implemented.
- **Coordinate Space**: All coordinates are absolute. Responsive behavior in Flutter requires wrapping the generated code in a `FittedBox` or using custom scaling logic.

---

## 🛠 For Developers & LLMs

- **Architecture**: Follows an MVC-inspired folder-wise architecture in `src/features`.
- **State**: `src/features/editor/store/useStore.ts` is the source of truth.
- **Code Generation**: Found in `src/features/editor/utils/flutterExporter.ts`.
- **Logic Verification**: The validator in `src/features/editor/utils/validator.ts` checks for unsupported features before code generation.

---

## 🎨 Design System & UI (UI_REDESIGN_SUMMARY.md)

### Color Palette
- **Primary**: #6366f1 (Indigo) - Active states
- **Success**: #10b981 (Emerald) - Union operations
- **Warning**: #f59e0b (Amber) - Exclude operations  
- **Danger**: #ef4444 (Red) - Subtract/Delete
- **Info**: #3b82f6 (Blue) - Intersect

### Interaction Model
- **Shortcuts**: V (Select), R (Rect), C (Circle), P (Polygon), Ctrl+P (Pen), Backspace (Delete), Ctrl+Z/Y (Undo/Redo).
- **Navigation**: Figma-style (Cmd/Ctrl + Scroll to zoom, Space + Drag to pan).
- **Context Menu**: Right-click shapes for Z-index and locking controls.

### UI Architecture
- **Toolbar**: Grouped by function (Tools, Style, Combine, History, Canvas, Theme, Export).
- **Sidebar Tabs**: **Properties** (Transform/Appearance), **Layers** (Ordered list with lock/delete), and **Code** (Flutter/JSON export with Highlight.js).
- **Canvas**: Konva.js stage with high-contrast alignment grid.

---

## 📈 Analytics & Monitoring (crashlytics.ts)
- **Firebase Integration**: Production-only initialization of Analytics and Performance monitoring.
- **Error Tracking**: Global listeners for `error` and `unhandledrejection` events to log exceptions with stack details.