async

agent.md

@@ -132,7 +132,7 @@ On mobile (< 620 px): scan input goes full-width on its own row; user dropdown a
 
 ## Key behaviours
 - **On load**: cookie credentials restored → GET webhook fires → dropdown populated → scan input auto-focused
-- **Enter key**: trims input → **duplicate check** → POSTs to webhook, prepends result row, clears + re-focuses input
+- **Enter key**: trims input → duplicate check → clears input **immediately** → adds pending row → pushed onto FIFO queue → `drainQueue()` starts if idle
 - **Clear button**: empties the table, clears the scan input, resets the scan counter
 - **No user selected**: red toast + highlighted dropdown; does not submit
 - **401 on any request**: modal prompts for credentials (pre-filled from cookie), saves to cookie, retries original call
@@ -140,7 +140,28 @@ On mobile (< 620 px): scan input goes full-width on its own row; user dropdown a
 - **Network error**: dismissing error banner; input selected so user can retry
 - **Dropdown error state**: tapping/focusing the dropdown while it shows an error re-triggers `loadUsers()`
 - **NDJSON/array/object**: `parseJson()` normalises all response formats from n8n
-- **Duplicate scan**: `isDuplicate(code)` queries `.col-code` cells in the live table before every POST; if found, shows a warning toast and skips the webhook call entirely
+- **Duplicate scan**: `isDuplicate(code)` queries `.col-code` cells (present on pending, resolved, and error rows) before enqueuing
+- **Scan queue**: `scanQueue[]` is a FIFO array of `{ code, user, rowEl }`. `drainQueue()` runs sequentially in the background — one `processItem()` at a time. Scans can be added faster than the webhook responds; each gets its own pending row immediately
+- **Pending row**: shows a spinner + `Processing… <code>` while the item is in-flight; replaced in-place by the resolved row or an error row
+- **Error row**: red background, shows the error message and the raw code; code is still in `.col-code` so it cannot be re-scanned
+- **Queue pill**: teal badge next to the scan counter showing `N pending`; hidden when queue is empty
+- **Auth mid-queue**: if `processItem` gets 401, it returns `"auth"` to `drainQueue`, which pauses (`queueBusy = false`), shows the auth modal with `drainQueue` as the retry callback — queue resumes from the same item after login
+- **Clear**: also drains `scanQueue` and resets `queueBusy`
+
+## Scan flow (sequence)
+```
+Enter key
+  └─ enqueue(code)
+       ├─ validation (user selected? duplicate?)
+       ├─ scanInput.value = ""  ← immediate clear
+       ├─ addPendingRow(code)  ← spinner row in table
+       └─ scanQueue.push(...)  ← add to FIFO
+            └─ drainQueue() if idle
+                 └─ processItem() loop
+                      ├─ fetch POST webhook
+                      ├─ resolveRow()  ← replace spinner with result
+                      └─ rowError()    ← replace spinner with error
+```
 
 ## Table columns (DOM)
 | Visible | Header | CSS class | Content |