# Grid Snapping Improvements - More Forgiving Algorithm

## Problem
The snapping was too strict - it would only snap when the widget was almost perfectly positioned over a cell. Users had to be very precise, making it difficult to snap widgets into cells.

## Solution

### 1. Increased Snap Threshold
```typescript
// Before
threshold: 30  // Only 30 pixels - too strict

// After  
threshold: 500  // Much larger area - very forgiving
```

The threshold is now 500 pixels, which means the widget can be anywhere reasonably near a cell and it will consider snapping.

### 2. Overlap-Based Snapping
The algorithm now prioritizes **overlap** over distance:

**Old Algorithm:**
- Primary metric: Distance from widget center to cell center
- Secondary metric: Overlap as a tiebreaker
- Problem: Would snap to closest cell even with minimal overlap

**New Algorithm:**
- Primary metric: **Overlap ratio** (how much of the widget overlaps the cell)
- Secondary metric: Distance as a tiebreaker
- Minimum overlap required: 15% (`minOverlap: 0.15`)
- Result: Only snaps when widget is actually **ON** the cell

### 3. How It Works Now

```typescript
const SNAP_CONFIG = {
  threshold: 500,      // Consider cells within 500px
  minOverlap: 0.15,    // Widget must overlap cell by at least 15%
  magneticSnap: true,  // Real-time visual feedback
  resizeOnSnap: true,  // Auto-resize to fit cell
};
```

**Snap Selection Logic:**
1. Find all cells within 500px of widget center
2. Calculate overlap ratio for each cell (0.0 to 1.0)
3. Exclude cells with less than 15% overlap
4. Choose cell with **highest overlap**
5. If overlap is tied, choose the one with closer center

### 4. Visual Behavior

**Before:**
- Widget near cell → Snaps immediately (annoying)
- Widget partially on cell → Might snap to wrong cell
- Hard to position freely

**After:**
- Widget near cell but not overlapping → No snap, free movement ✅
- Widget partially on cell (15%+) → Highlights that cell ✅
- Widget mostly on cell → Snaps to that cell ✅
- Widget overlapping multiple cells → Snaps to cell with most overlap ✅

## Configuration

You can tune the behavior by adjusting these values in `WidgetRenderer.tsx`:

```typescript
const SNAP_CONFIG = {
  // Larger threshold = consider more cells (current: 500px is very forgiving)
  threshold: 500,
  
  // Higher minOverlap = need more widget on cell to snap
  // 0.15 = 15% overlap required
  // 0.25 = 25% overlap required (stricter)
  // 0.05 = 5% overlap required (more forgiving)
  minOverlap: 0.15,
  
  // Disable magnetic snapping for only-on-drop behavior
  magneticSnap: true,
  
  // Disable auto-resize if you want to preserve widget size
  resizeOnSnap: true,
};
```

## Examples

### Example 1: Small Overlap
```
Widget overlaps cell by 10%
→ No snap (below 15% threshold)
→ Widget moves freely
```

### Example 2: Good Overlap
```
Widget overlaps cell by 40%
→ Cell highlights
→ On release, snaps to cell
→ Widget resizes to fit cell
```

### Example 3: Multiple Cells
```
Widget overlaps cell-1 by 20%
Widget overlaps cell-2 by 60%
→ cell-2 highlights (higher overlap)
→ Snaps to cell-2
```

## Testing

1. **Free Movement**: Drag widget near (but not on) a cell
   - Expected: No highlighting, no snapping ✅

2. **Partial Overlap**: Drag widget so 20% overlaps a cell
   - Expected: Cell highlights, snaps on release ✅

3. **Multiple Cells**: Drag widget over corner between two cells
   - Expected: Only the cell with most overlap highlights ✅

4. **Full Overlap**: Drag widget completely over a cell
   - Expected: Strong highlight, definite snap ✅

## Console Debug Output

You'll now see more detailed logging:

```javascript
[Snap Debug] Checking cell: {
  cellId: "cell-1",
  distance: "245.3",
  overlap: "0.342",          // 34.2% overlap
  withinThreshold: true,
  meetsMinOverlap: true      // Above 15% minimum
}

[Snap Debug] Final best cell: {
  cellId: "cell-1",
  overlap: "0.342"           // Chosen due to highest overlap
}
```

## Files Modified
- `/src/components/WidgetRenderer.tsx`:
  - Increased `threshold` from 30 to 500
  - Added `minOverlap` config (0.15 = 15%)
  - Changed algorithm to prioritize overlap over distance
  - Improved debug logging

---

**Result**: Snapping now feels natural and forgiving. You have to actually position the widget **on** the cell for it to snap, rather than having it snap too eagerly when just passing nearby.