Barcode & Receipt Scanner → Auto-Create Items with Product Autofill

**Description**
Make item entry 10× faster: scan a **UPC/EAN** barcode to auto-fill name/type/photo, or snap a **receipt** to parse items, prices, and optional warranty dates. Suggest a box (“likely Kitchen” etc.), handle offline capture, and sync when back online.

**Summary**

* Camera barcode scan (UPC/EAN) → lookup product metadata → prefill item modal.
* Receipt OCR → extract line items → map to existing or new boxes → bulk add.
* Offline queue/cache so scans work without network; safe, conflict-free sync later.

**Goals**
✅ One-tap “Scan Barcode” in Add Item modal (mobile-first).
✅ Receipt capture → parse items + quantities + prices → bulk add wizard.
✅ Product autofill: name, category/type, optional photo/thumbnail.
✅ Box/type suggestions (rule-based + lightweight AI nudge via existing BoxedAI).
✅ Offline queue for scans; background sync + dedupe when online.

**Non-Goals (Initial)**
❌ Full price history tracking or budgeting.
❌ Returns management or e-commerce integrations.
❌ Perfect OCR for every receipt layout (good defaults + confirm UI is enough).

**High-Level Design**

1. **Barcode Scan**

* Route `/scan/barcode` using `@zxing/browser` (lazy-loaded).
* Parse UPC/EAN; adapter layer tries sources in order (e.g., local cache → public product DB → fallback heuristics).
* Cache successful lookups in IndexedDB (`productCache:{barcode→{name,type,thumb}}`).
* Prefill Add Item modal; let user confirm/edit and choose target box.

2. **Receipt OCR**

* Route `/scan/receipt` with camera/file input.
* On-device OCR first (e.g., Tesseract.js via Web Worker); optional server OCR fallback behind a feature flag.
* Line-item parser: normalize description → candidate `type` via keyword map; optional BoxedAI prompt for disambiguation (small payload).
* Bulk add wizard: per-line quantity, box, type; “Add all” commits in a single batch.

3. **Suggestions & Mapping**

* **Type**: keyword map + recent history; AI suggestion if low confidence.
* **Box**: recent boxes + text match (“mug”→ Kitchen), fall back to “Unsorted”.
* Show confidence chips; edits feed a local learning map.

4. **Offline & Sync**

* Use IndexedDB (`localforage/idb-keyval`) queues: `pendingScans`, `pendingItems`.
* If offline, store full payload; on reconnect, background submit and reconcile via item `client_id` to avoid dupes.

**Data Model (Supabase/Postgres)**

* `items`: add `barcode TEXT NULL`, `source TEXT DEFAULT 'manual'`, `purchase_price NUMERIC NULL`, `warranty_expires TIMESTAMPTZ NULL`.
* New table `receipts` (id, owner_profile_id, merchant?, total?, ts, blob_url?).
* New table `receipt_items` (receipt_id, name, quantity, price, matched_item_id?).
* Indexes: `items(barcode)`, `items(name text_pattern_ops)`.

**API / Server**

* Minimal Next.js API routes or Supabase RPC:

* `GET /api/product?barcode=...` → normalized `{name,type,thumb}` (with server-side caching).
* `POST /api/receipt` → optional server OCR & structured lines (feature-flag).
* Respect RLS; all reads/writes scoped to owner_profile_id.

**UI/UX**

* **Add Item**: “Scan Barcode” button; loading skeleton; prefilled modal with photo preview.
* **Receipt Wizard**: grid of parsed lines (name/qty/price/type/box); “Apply to all” helpers.
* **Scanner**: torch toggle (where supported), haptic feedback on detect, clear error states.
* Badges: “From barcode” / “From receipt”; toast “Synced” after background upload.

**Security & Privacy**

* Never log raw receipt images or full OCR text in client console or server logs.
* Barcodes resolve to metadata only; no PII stored.
* Explicit user opt-in for server OCR (if enabled); default is on-device OCR.

**Performance**

* Lazy-load ZXing/Tesseract; run OCR in Web Worker.
* Cache product results; LRU cap (e.g., 500 entries).
* Debounce AI disambiguation; cap tokens with truncated context.

**Acceptance Criteria**
✅ Scanning a supported UPC/EAN pre-fills item name & type within 1–2s online.
✅ Receipt photo produces >80% correct item rows on common US receipts, with quick manual fix-ups.
✅ Works offline: queued scans are visible and sync correctly when online.
✅ No unauthorized access across accounts; RLS respected.
✅ Usable on mobile Safari/Chrome; torch toggle where supported.

**Tasks**
*Frontend*

* [ ] `/scan/barcode` page with `@zxing/browser` (lazy-load).
* [ ] Add Item modal → “Scan Barcode” → prefill flow + confirm.
* [ ] `/scan/receipt` page with camera/upload, worker-based OCR, parser, wizard.
* [ ] IndexedDB cache/queues (`productCache`, `pendingScans`, `pendingItems`).
* [ ] Suggestion chips for type/box; integrate BoxedAI only when low confidence.
* [ ] Toasts, badges, empty/offline states.

*Server / API (optional OCR server step behind flag)*

* [ ] `/api/product?barcode=` with pluggable provider adapters + caching.
* [ ] `/api/receipt` endpoint (if server OCR enabled).
* [ ] Rate-limit product lookups; add simple telemetry.

*DB / Supabase*

* [ ] Migrations for `items` new columns; create `receipts` & `receipt_items`.
* [ ] Indexes + RLS policies; least-privileged service role where needed.

*QA*

* [ ] Real-device tests (iOS/Android) for camera + torch + permissions.
* [ ] OCR accuracy on a sample set (grocery, electronics, home goods).
* [ ] Offline: airplane mode → scan → add → reconnect → auto-sync.
* [ ] Accessibility: focus order, ARIA for scanner controls.

**Nice-to-Have (Future)**

* Warranty reminders & returns windows from receipt dates.
* Barcode print for items (micro-labels).
* Vendor price suggestions and product images via richer catalogs.
* Multi-merchant parsers & localization.