docs: spec for AOI click-to-place redesign

Single-click placement with preset sizes (100/250/500 km²),
replacing MapboxDraw two-tap rectangle and GeoJSON upload.

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/superpowers/specs/2026-04-06-aoi-click-to-place-design.md

@@ -0,0 +1,131 @@
+# AOI Click-to-Place Redesign
+
+**Date:** 2026-04-06
+**Status:** Approved
+
+## Summary
+
+Replace the current two-tap rectangle drawing + MapboxDraw interaction with a single-click placement model. User clicks the map → a fixed-size square AOI appears centered on that point. Three preset sizes (100, 250, 500 km²), 500 km² default. No resize handles, no corner dragging, no polygon draw mode. Geocoder search auto-places the AOI. GeoJSON upload removed.
+
+## Motivation
+
+The current AOI selection UX has unnecessary complexity for Aperture's use case. Users don't need arbitrary polygon shapes or resizable rectangles — they need to quickly define a square analysis area. The backend already constrains to 500 km² max and requires a bbox. A click-to-place model is faster, works better on mobile, and eliminates the MapboxDraw dependency.
+
+## Interaction Model
+
+### Click to Place
+
+- Map is always in click-to-place mode (no activation button needed)
+- Cursor shows as crosshair over the map
+- Single click places a square bbox centered on the click point
+- Clicking again replaces the previous AOI instantly (last click wins)
+- No explicit "clear" action required
+
+### Geocoder Search
+
+- Typing a location name and pressing Enter geocodes via Nominatim
+- On success: map flies to the location AND auto-places the AOI at the geocoded center
+- Replaces any existing AOI (same as clicking)
+
+### Size Presets
+
+- Three toggle buttons in the sidebar: `[100 km²] [250 km²] [500 km²]`
+- 500 km² selected by default
+- Changing the size while an AOI is placed immediately resizes it around the same center
+- All presets are within the backend's `MAX_AOI_KM2 = 500` limit
+
+## UI Changes
+
+### Sidebar Layout (Define Area page)
+
+```
+[Area name input]
+[Search location input]
+
+AOI size:  [100 km²] [250 km²] [●500 km²]
+
+[Area display: "487 km² — centered at 2.35°N, 36.82°E"]
+
+[Analysis period inputs...]
+[Season inputs...]
+[Continue button]
+```
+
+### Removed Elements
+
+- "Tap two corners" button (`#draw-rect-btn`)
+- GeoJSON upload section (`#geojson-upload`, `#upload-label`)
+- All MapboxDraw-related UI
+
+## Technical Design
+
+### Size Calculation
+
+For a target area at a given latitude, compute the bbox as a square:
+
+```javascript
+function computeBbox(centerLng, centerLat, targetKm2) {
+  const sideKm = Math.sqrt(targetKm2);
+  const dLat = sideKm / 111.32;
+  const dLon = sideKm / (111.32 * Math.cos(centerLat * Math.PI / 180));
+  return [
+    centerLng - dLon / 2,
+    centerLat - dLat / 2,
+    centerLng + dLon / 2,
+    centerLat + dLat / 2,
+  ];
+}
+```
+
+### Map Rendering
+
+Replace MapboxDraw with a plain GeoJSON source + layers:
+
+- Add a `aoi-draw` GeoJSON source to the map
+- Render with two layers: fill (semi-transparent) + outline (solid stroke)
+- On click or geocode: update the source data with the new bbox polygon
+- No vertex handles, no edit mode
+
+### Dependencies Removed
+
+- `@mapbox/mapbox-gl-draw` JS library (CDN link in index.html)
+- `mapbox-gl-draw.css` (CDN link in index.html)
+- All Draw-related code in `map.js`: `_draw`, `drawStyles()`, `activateDrawRect()`, `_onRectClick()`, `activateDrawPolygon()`, `loadGeoJSON()`, Draw event listeners
+
+### Files Modified
+
+| File | Changes |
+|------|---------|
+| `frontend/index.html` | Remove MapboxDraw CDN links. Remove GeoJSON upload section. Remove "Tap two corners" button. Add size toggle buttons. |
+| `frontend/js/map.js` | Remove all MapboxDraw code. Add `computeBbox()`. Add click handler that places AOI. Add `setAoiSize()` for preset changes. Render AOI as plain GeoJSON source/layer. Update `geocode()` to auto-place AOI. |
+| `frontend/js/app.js` | Remove GeoJSON upload handler. Remove draw button handler. Wire size toggle buttons. Update `_bboxAreaKm2` validation (presets are always valid, but still display area). Remove 10,000 km² limit logic. |
+| `frontend/css/` | Remove Draw-related styles. Add size toggle button styles. |
+
+### Geocode + Auto-Place Flow
+
+```
+User types "Turkana County" + Enter
+  → geocode() calls Nominatim API
+  → On success: extract center [lon, lat] from result
+  → computeBbox(lon, lat, selectedSize)
+  → Update map source with new bbox polygon
+  → Fire onAoiChange(bbox) callback
+  → Map flies to fit the bbox bounds
+```
+
+### Results Map
+
+The results map (`initResultsMap`, `renderSpatialOverlay`, etc.) does NOT use MapboxDraw — it uses plain GeoJSON sources already. No changes needed there.
+
+## Edge Cases
+
+- **Click near East Africa bounds**: The computed bbox may extend outside the backend's valid region. The backend already validates this and returns an error. The frontend does not need to clamp.
+- **Geocoder returns no results**: Show error message as today. No AOI placed.
+- **Size change with no AOI placed**: Store the selected size, apply it on next click/geocode.
+
+## What This Does NOT Change
+
+- Backend AOI validation (bbox bounds, max area)
+- Results map rendering
+- API payload structure (`aoi.bbox` remains `[minLon, minLat, maxLon, maxLat]`)
+- Analysis period, season, or indicator selection flows