# L4D2 Blueprint Overlay Picker Design

**Goal:** Replace the checkbox + numeric-Order table on the blueprint detail page with a drag-to-reorder list and a single dropdown to add overlays. Drag-and-drop is the primary reorder mechanic; per-row Order text inputs are removed.

**Approval status:** User-approved. No companion implementation plan — small surface, implemented directly.

## Context

`templates/blueprint_detail.html:14-28` currently renders one HTML table for the blueprint's overlays. Each row carries a `Use` checkbox, a numeric `Order` text input, and the overlay name. To enable an overlay you check it; to reorder you type integers into per-row text fields. Adding a new overlay between existing ones means renumbering everything below it by hand.

This spec replaces that table with a single ordered list of *selected* overlays plus a `<select>` dropdown for adding more. Drag-to-reorder is the only reorder interaction. A ✕ button on each row removes it (returning it to the dropdown). Picking an entry from the dropdown appends it to the list (and removes it from the dropdown).

The change is intentionally scoped small: no two-panel layout, no filter widget, no touch / keyboard reorder support, no JS-disabled fallback. The native `<select>` element supplies typeahead-by-letter and keyboard navigation for free, which covers the no-drag path. The page is desktop-primary.

## Locked Decisions

1. **Single ordered list of selected overlays only.** No second pane. The "available" set lives in the `<select>`. Adding via dropdown is one click; removing via ✕ is one click; reordering is one drag.
2. **Native HTML5 drag-and-drop.** No vendored library, no polyfill. Touch-screen drag is unsupported on Android and rough on iOS — accepted because the page is desktop-primary. Add and remove still work on touch via the `<select>` and the `<button>`.
3. **JS-required UI.** If JS does not load, the page is unusable. No degradation to the old checkbox table.
4. **Server contract unchanged.** Each list row owns one `<input type="hidden" name="overlay_ids" value="{id}">`. Form-submission order = DOM order. The existing `ordered_overlay_ids_from_form` handler in `routes/blueprint_routes.py` already falls back to enumerate index when no `overlay_position_<id>` field is present, so it accepts the new shape with no Python edit.
5. **Dropdown re-sorted alphabetically on remove.** When ✕ removes a row, the corresponding `<option>` is sorted-inserted back into the `<select>` (case-insensitive name compare). The dropdown stays predictable.
6. **Drop-indicator visual.** A 2px focus-color bar drawn via `box-shadow … inset` on the row under the cursor: top-bar = "drop will land before this row", bottom-bar = "drop will land after this row". The hover side is computed by comparing `event.clientY` to the row's vertical midpoint.
7. **Drop on empty space inside the list = append.** Drop directly on the dragged row (or with no movement) = no-op. Escape during drag triggers `dragend`, which clears all visual classes.
8. **Out of scope:** keyboard reorder, ARIA live announcements, touch DnD polyfill, server-side cleanup of the now-unused `overlay_position_<id>` form-field path.

## Architecture

```
GET /blueprints/<id>
   page_routes.blueprint_page
       ├─▶ selected_overlays  (ordered by BlueprintOverlay.position)
       └─▶ available_overlays = all_overlays \ selected_overlays
                            (alphabetical)

   templates/blueprint_detail.html
       <ol data-overlay-list>                    ← drag target, hidden inputs
         <li data-overlay-id draggable> × ⋮⋮ name </li>
         …
       </ol>
       <select data-overlay-add>                 ← add path
         <option>Pick a name…</option>
         <option value=overlay.id>name</option>  ← available_overlays
         …
       </select>

   static/js/blueprint-overlay-picker.js
       ├─ dragstart/over/leave/drop/end → reorder DOM under [data-overlay-list]
       ├─ click [data-action="remove"]  → remove row + sorted-insert <option>
       ├─ change [data-overlay-add]     → append <li>, remove <option>
       └─ refreshEmpty()                → toggle [data-overlay-empty][hidden]

POST /blueprints/<id>
   form-encoded body: overlay_ids=<id>&overlay_ids=<id>&… (in DOM order)
   blueprint_routes.update_blueprint_form
     → ordered_overlay_ids_from_form (existing; fallback_position branch)
     → replace_blueprint_overlays    (existing)
```

## Form-contract details

The new template emits one hidden input per selected row, colocated as a child of the `<li>`:

```html
<li data-overlay-id="3" draggable="true">
  <span class="overlay-picker-handle">⋮⋮</span>
  <span class="overlay-picker-name">workshop_maps</span>
  <button type="button" data-action="remove">×</button>
  <input type="hidden" name="overlay_ids" value="3">
</li>
```

Browser form serialization preserves DOM order across multiple inputs that share a `name`. Werkzeug's `request.form.getlist("overlay_ids")` returns them in submission order. `ordered_overlay_ids_from_form` then assigns each id its enumerate-index position via the `fallback_position` branch (lines 19-31 of `routes/blueprint_routes.py`) and feeds the result to `replace_blueprint_overlays`.

The JSON path (`POST /blueprints` with `application/json`) already takes `overlay_ids` list order at line 64 of the same file — this spec does not affect it.

## UI / UX details

- **Empty state.** When no overlays are selected, a `[data-overlay-empty]` paragraph reads "No overlays selected. Pick one below to add." JS toggles its `hidden` attribute on every list mutation.
- **Drag handle.** Visual only (`⋮⋮` glyph). The whole row is `draggable="true"`; the user does not have to grab the handle specifically.
- **Drop indicator math.** During `dragover`, compute `event.clientY < rect.top + rect.height/2`; that boolean picks `drop-before` (bar at top) vs `drop-after` (bar at bottom). On `drop`, read which class is set and `insertBefore` or `insertBefore(…, target.nextSibling)` accordingly.
- **Sorted insert on remove.** Walk `<select>` children comparing `option.dataset.overlayName` (lowercased) against the removed name; `insertBefore` the new option ahead of the first option whose name sorts later, or append if none.
- **Reset select after add.** Set `select.value = ""` so the placeholder reappears after each add.

## Files

| Path | Change |
|---|---|
| `l4d2web/routes/page_routes.py` | Compute `available_overlays`; pass to template. |
| `l4d2web/templates/blueprint_detail.html` | Replace overlay table with `<ol>` + `<select>`; add `<script defer>`. |
| `l4d2web/static/css/components.css` | Append `.overlay-picker-*` rules. Reuse existing tokens. |
| `l4d2web/static/js/blueprint-overlay-picker.js` | New IIFE. ~150 LOC. |
| `l4d2web/tests/test_blueprints.py` | Two new GET-page assertions. |
| `l4d2web/tests/test_pages.py` | Update `test_blueprint_detail_has_ordered_overlay_form` to match new shape. |

## Verification

Manual browser flow (`/blueprints/<id>`):

1. Initial render shows the saved selection in saved order; dropdown holds the rest. No console errors.
2. Drag a row up/down. Focus-colored bar appears at the top or bottom of the hover-target row (depending on which half is hovered). On drop, the row moves; hidden inputs reflect the new order.
3. Click ✕ on a row. Row vanishes; the same name appears in the dropdown in alphabetical position.
4. Pick from the dropdown. New row appears at the end of the list; the option leaves the dropdown; the placeholder is reselected.
5. Save the blueprint, reload. Order survives the round-trip.
6. Press Escape mid-drag. Drop indicators clear; source row regains opacity; nothing moved.

Test commands:

```
pytest l4d2web/tests/test_blueprints.py -q
pytest l4d2web/tests -q
```

## Out of scope / future follow-ups

- **Drop the `overlay_position_<id>` server-side path.** Once no client emits those fields, `ordered_overlay_ids_from_form` collapses to `[int(v) for v in request.form.getlist("overlay_ids")]`. Test `test_form_update_preserves_ordered_overlays_and_multiline_fields` (`l4d2web/tests/test_blueprints.py:220`) gets simplified accordingly.
- **Touch-friendly DnD.** Vendor a polyfill (`drag-drop-touch`) or rewrite the picker on pointer events if mobile editing becomes a real use case.
- **Keyboard reorder.** Space-to-grab + arrow-keys + ARIA live announcements. Currently only add/remove are keyboard-accessible.
- **Filter on the selected list.** Not needed at v1's overlay counts; revisit if blueprints commonly carry 20+ overlays.
