# POS Frontend AI Agent Instructions (`apps/pos`)

> **Tech Stack:** Vue 3, Vite, Tailwind CSS, Pinia, zxing-wasm  
> **Role:** Cashier POS Register SPA (Fast Scanning, Offline-First, Shift & Drawer Tracking)

---

## 1. High-Performance Cashier Principles

1. **Sub-Second Response**: Cashier scanning and item lookups must remain responsive. Heavy computations or unnecessary re-renders must be avoided.
2. **Barcode Scanning**: Barcode detection uses `zxing-wasm`. Always import `zxing-wasm` from direct dependencies; never rely on global hoisting.
3. **Idempotent Checkout**: Every checkout submission must send an idempotency key generated via `@keluargamart/utils` (`newIdempotencyKey()`) to prevent double-charging on network retries.
4. **Shift & Cash Drawer Integrity**: A cashier shift must be opened before processing sales transactions. Do not bypass shift validations.

---

## 2. Shared Packages Integration

- Import rute endpoints from `@keluargamart/contracts/routes`.
- Import permissions from `@keluargamart/permissions`.
- Import formatters from `@keluargamart/utils` (`formatIDR`, `formatRupiah`, `newIdempotencyKey`).
- Do NOT maintain localized copy-pasted route files.

---

## 3. Testing & Validation

- Run POS tests: `pnpm --filter @keluargamart/pos test`.
- Verify POS production build: `pnpm --filter @keluargamart/pos build`.
- Check all 20 test files and 111+ tests pass before committing changes.