pharmacy-erp 1.2.0 → 1.3.0

package/frontend/package.json

@@ -25,6 +25,7 @@
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
     "framer-motion": "^13.1.0",
+    "html5-qrcode": "^2.3.8",
     "jspdf": "^4.2.1",
     "jspdf-autotable": "^5.0.8",
     "lucide-react": "^0.468.0",

package/frontend/pnpm-lock.yaml

@@ -53,6 +53,9 @@ importers:
       framer-motion:
         specifier: ^13.1.0
         version: 13.1.0(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+      html5-qrcode:
+        specifier: ^2.3.8
+        version: 2.3.8
       jspdf:
         specifier: ^4.2.1
         version: 4.2.1
@@ -1633,6 +1636,7 @@ packages:
   eslint@9.39.5:
     resolution: {integrity: sha512-DgZS62aPLXKlnxILS/AYCoRvHaZeXceIzlXPkkGGzJWSow1aEk0lbTlxUSlyjC8jcaKxAdOnTDz+o1JFSBsyjw==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    deprecated: This version is no longer supported. Please see https://eslint.org/version-support for other options.
     hasBin: true
     peerDependencies:
       jiti: '*'
@@ -1837,6 +1841,9 @@ packages:
     resolution: {integrity: sha512-fPU6BHNpsyIhr8yyMpTLLxAbkaK8ArIBcmZIRiBLiDhjeqvXolaEmDGmELFuX9I4xDcaKKcJl+TKZLqruBbmWA==}
     engines: {node: '>=8.0.0'}
 
+  html5-qrcode@2.3.8:
+    resolution: {integrity: sha512-jsr4vafJhwoLVEDW3n1KvPnCCXWaQfRng0/EEYk1vNcQGcG/htAdhJX0be8YyqMoSz7+hZvOZSTAepsabiuhiQ==}
+
   ignore@5.3.2:
     resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
     engines: {node: '>= 4'}
@@ -4587,6 +4594,8 @@ snapshots:
       text-segmentation: 1.0.3
     optional: true
 
+  html5-qrcode@2.3.8: {}
+
   ignore@5.3.2: {}
 
   ignore@7.0.6: {}

package/frontend/src/app/[locale]/(app)/catalog/products/page.tsx

@@ -8,8 +8,10 @@ import { Select } from '@/components/ui/select';
 import { Switch } from '@/components/ui/switch';
 import { Badge } from '@/components/ui/badge';
 import { ConfirmDialog } from '@/components/ui/confirm-dialog';
+import { BarcodeScanner } from '@/components/ui/barcode-scanner';
+import { useScanFeedback } from '@/components/ui/scan-feedback';
 import { toast } from 'react-hot-toast';
-import { Search, Plus, Edit, Trash2, Package, Pill, Beaker, Tag, DollarSign, Archive, AlertCircle, ChevronDown, Upload } from 'lucide-react';
+import { Search, Plus, Edit, Trash2, Package, Pill, Beaker, Tag, DollarSign, Archive, AlertCircle, ChevronDown, Upload, Camera } from 'lucide-react';
 import { BulkImportModal } from '@/components/ui/bulk-import-modal';
 import { cn } from '@/lib/utils';
 import { useRouter, useParams, useSearchParams } from 'next/navigation';
@@ -32,10 +34,12 @@ export default function ProductsPage() {
 
   const [slideOpen, setSlideOpen] = useState(false);
   const [importModalOpen, setImportModalOpen] = useState(false);
+  const [scannerOpen, setScannerOpen] = useState(false);
   const [editingId, setEditingId] = useState<string | null>(null);
   
   const [deleteDialog, setDeleteDialog] = useState({ open: false, id: '', name: '' });
   const [isSaving, setIsSaving] = useState(false);
+  const { playSuccess, playError } = useScanFeedback();
   
   // Form State
   const defaultForm = {
@@ -521,13 +525,23 @@ export default function ProductsPage() {
                     className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm text-foreground font-mono focus:border-brand-500 focus:outline-none focus:ring-1 focus:ring-brand-500"
                   />
                 </div>
-                <div className="space-y-1.5">
+                <div className="space-y-1.5 relative">
                   <label className="text-sm text-muted-foreground">Barcode</label>
-                  <input 
-                    type="text" 
-                    value={formData.barcode} onChange={e => setFormData({...formData, barcode: e.target.value})}
-                    className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm text-foreground font-mono focus:border-brand-500 focus:outline-none focus:ring-1 focus:ring-brand-500"
-                  />
+                  <div className="flex gap-2">
+                    <input 
+                      type="text" 
+                      value={formData.barcode} onChange={e => setFormData({...formData, barcode: e.target.value})}
+                      className="w-full rounded-lg border border-border bg-background px-3 py-2 text-sm text-foreground font-mono focus:border-brand-500 focus:outline-none focus:ring-1 focus:ring-brand-500"
+                    />
+                    <button
+                      type="button"
+                      onClick={() => setScannerOpen(true)}
+                      className="shrink-0 p-2 border border-border rounded-lg hover:bg-surface text-brand-500 transition-colors"
+                      title="Scan Barcode"
+                    >
+                      <Camera size={20} />
+                    </button>
+                  </div>
                 </div>
               </div>
             </div>
@@ -748,6 +762,26 @@ export default function ProductsPage() {
         onOpenChange={setImportModalOpen}
         onImportComplete={fetchData}
       />
+
+      {/* Barcode Scanner Modal */}
+      <BarcodeScanner
+        isOpen={scannerOpen}
+        onClose={() => setScannerOpen(false)}
+        title="Scan Barcode / QR Code"
+        onScan={(code) => {
+          setScannerOpen(false);
+          // Check if barcode already exists in loaded medicines
+          const exists = medicines.find(m => m.barcode === code);
+          if (exists) {
+            playError();
+            toast.error(`Barcode belongs to existing medicine: ${exists.name_en}`);
+          } else {
+            playSuccess();
+            setFormData(prev => ({ ...prev, barcode: code }));
+            toast.success("Barcode filled!");
+          }
+        }}
+      />
     </div>
   );
 }

package/frontend/src/app/[locale]/(pos)/pos/page.tsx

@@ -12,11 +12,15 @@ import PaymentSettingsModal from '@/components/pos/PaymentSettingsModal';
 import { CashSessionGuard } from '@/components/pos/CashSessionGuard';
 import { CloseSessionModal } from '@/components/pos/CloseSessionModal';
 import { SaleReceipt } from '@/components/pos/SaleReceipt';
+import { BarcodeScanner } from '@/components/ui/barcode-scanner';
+import { useScanFeedback } from '@/components/ui/scan-feedback';
+import { useBarcodeScanner } from '@/hooks/use-barcode-scanner';
 import type { Product } from '@/components/pos/ProductCatalog';
 import {
   Menu,
   Search,
   ScanBarcode,
+  Camera,
   ChevronDown,
   User,
   X,
@@ -50,6 +54,9 @@ function PosContent({ session }: { session: { id: string; opening_amount: number
   const [receiptOpen, setReceiptOpen] = useState(false);
   const [saleReceiptData, setSaleReceiptData] = useState<any>(null);
 
+  // Camera Scanner State
+  const [cameraScannerOpen, setCameraScannerOpen] = useState(false);
+
   const searchInputRef = useRef<HTMLInputElement>(null);
   const dropdownRef = useRef<HTMLDivElement>(null);
   const userMenuRef = useRef<HTMLDivElement>(null);
@@ -154,82 +161,99 @@ function PosContent({ session }: { session: { id: string; opening_amount: number
     [addItem]
   );
 
-  // Barcode Scanner Listener (Detect hardware scanners fast-typing + enter)
-  useEffect(() => {
-    let barcodeBuffer = '';
-    let lastKeyTime = Date.now();
+  // Scan feedback (beep sounds + visual flash)
+  const { playSuccess, playError, flashElement } = useScanFeedback();
+
+  // Shared barcode scan handler (used by both USB scanner and camera scanner)
+  const handleBarcodeScan = useCallback(
+    (scannedCode: string) => {
+      // First, try local lookup by product ID or barcode
+      const found = products.find(
+        (p) =>
+          p.id === scannedCode ||
+          p.name.toLowerCase() === scannedCode.toLowerCase()
+      );
+
+      if (found) {
+        handleProductClick(found);
+        playSuccess();
+        flashElement('green', searchInputRef.current);
+        toast.success(`✅ Scanned: ${found.name}`);
+        return;
+      }
+
+      // Fallback: search via API (matches barcode field in database)
+      api
+        .searchMedicines(scannedCode)
+        .then((res: any) => {
+          if (Array.isArray(res) && res.length > 0) {
+            const match = products.find((p) => p.medicine_id === res[0].id);
+            if (match) {
+              handleProductClick(match);
+              playSuccess();
+              flashElement('green', searchInputRef.current);
+              toast.success(`✅ Scanned: ${match.name}`);
+            } else {
+              playError();
+              flashElement('red', searchInputRef.current);
+              toast.error(`Scanned item not in stock catalog`);
+            }
+          } else {
+            playError();
+            flashElement('red', searchInputRef.current);
+            toast.error(`Barcode not found: ${scannedCode}`);
+          }
+        })
+        .catch(() => {
+          playError();
+          flashElement('red', searchInputRef.current);
+          toast.error(`Product not found for code: ${scannedCode}`);
+        });
+    },
+    [products, handleProductClick, playSuccess, playError, flashElement]
+  );
 
+  // USB/Bluetooth hardware barcode scanner hook
+  useBarcodeScanner({
+    onScan: handleBarcodeScan,
+    enabled: !paymentMode && !cameraScannerOpen,
+  });
+
+  // Camera scanner callback
+  const handleCameraScan = useCallback(
+    (code: string) => {
+      setCameraScannerOpen(false);
+      handleBarcodeScan(code);
+    },
+    [handleBarcodeScan]
+  );
+
+  // Keyboard shortcuts (F2 = search, F4 = camera, F9 = payment, Escape)
+  useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
-      // Global keyboard shortcuts
       if (e.key === 'F2') {
         e.preventDefault();
         searchInputRef.current?.focus();
-        return;
+      }
+      if (e.key === 'F4') {
+        e.preventDefault();
+        setCameraScannerOpen(true);
       }
       if (e.key === 'F9' && cart.length > 0) {
         e.preventDefault();
         setPaymentMode(true);
-        return;
       }
       if (e.key === 'Escape') {
+        if (cameraScannerOpen) setCameraScannerOpen(false);
         if (paymentMode) setPaymentMode(false);
         if (showDropdown) setShowDropdown(false);
         if (userMenuOpen) setUserMenuOpen(false);
-        return;
-      }
-
-      // If user is focused on an input/textarea (not scanning outside), skip global barcode hook
-      const activeTag = document.activeElement?.tagName.toLowerCase();
-      const isInputActive = activeTag === 'input' || activeTag === 'textarea';
-
-      const currentTime = Date.now();
-      const timeDiff = currentTime - lastKeyTime;
-      lastKeyTime = currentTime;
-
-      // Barcode scanners usually send characters within 30-50ms of each other
-      if (timeDiff > 80) {
-        barcodeBuffer = '';
-      }
-
-      if (e.key === 'Enter') {
-        if (barcodeBuffer.length >= 3) {
-          e.preventDefault();
-          const scannedCode = barcodeBuffer.trim();
-          barcodeBuffer = '';
-          
-          // Look up scanned barcode in products list or via API search
-          const found = products.find(p => p.id === scannedCode || p.name.toLowerCase() === scannedCode.toLowerCase());
-          if (found) {
-            handleProductClick(found);
-            toast.success(`Scanned: ${found.name}`);
-          } else {
-            api.searchMedicines(scannedCode)
-              .then((res: any) => {
-                if (Array.isArray(res) && res.length > 0) {
-                  const match = products.find(p => p.medicine_id === res[0].id);
-                  if (match) {
-                    handleProductClick(match);
-                    toast.success(`Scanned: ${match.name}`);
-                  } else {
-                    toast.error(`Scanned item not in stock catalog`);
-                  }
-                } else {
-                  toast.error(`Barcode not found: ${scannedCode}`);
-                }
-              })
-              .catch(() => {
-                toast.error(`Product not found for code: ${scannedCode}`);
-              });
-          }
-        }
-      } else if (e.key.length === 1 && !isInputActive) {
-        barcodeBuffer += e.key;
       }
     };
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [cart.length, paymentMode, showDropdown, userMenuOpen, products, handleProductClick]);
+  }, [cart.length, paymentMode, showDropdown, userMenuOpen, cameraScannerOpen]);
 
   // Click outside to close dropdowns
   useEffect(() => {
@@ -330,10 +354,18 @@ function PosContent({ session }: { session: { id: string; opening_amount: number
             {theme === 'dark' ? <Sun size={18} className="md:w-5 md:h-5" /> : <Moon size={18} className="md:w-5 md:h-5" />}
           </button>
 
+          <button 
+            onClick={() => setCameraScannerOpen(true)}
+            className="p-1.5 md:p-2 bg-transparent border border-border rounded-lg text-foreground hover:bg-surface transition-colors shrink-0"
+            title="Scan with Camera (F4)"
+          >
+            <Camera size={18} className="md:w-5 md:h-5 text-brand-500" />
+          </button>
+
           <button 
             onClick={() => searchInputRef.current?.focus()}
             className="p-1.5 md:p-2 bg-transparent border border-border rounded-lg text-foreground hover:bg-surface transition-colors shrink-0"
-            title="Scan Barcode (Focus Search)"
+            title="Focus Barcode Search (F2)"
           >
             <ScanBarcode size={18} className="md:w-5 md:h-5" />
           </button>
@@ -440,13 +472,24 @@ function PosContent({ session }: { session: { id: string; opening_amount: number
         onClose={() => setSettingsOpen(false)}
       />
 
-      {/* ===== SALE RECEIPT MODAL ===== */}
+      {/* Payment Success Receipt */}
       <SaleReceipt
         open={receiptOpen}
-        onClose={() => setReceiptOpen(false)}
+        onClose={() => {
+          setReceiptOpen(false);
+          setSaleReceiptData(null);
+        }}
         saleData={saleReceiptData}
       />
 
+      {/* Camera Barcode Scanner */}
+      <BarcodeScanner
+        isOpen={cameraScannerOpen}
+        onClose={() => setCameraScannerOpen(false)}
+        onScan={handleCameraScan}
+        title="Scan Product Barcode"
+      />
+
       {/* ===== CLOSE REGISTER MODAL ===== */}
       <CloseSessionModal
         open={closeSessionOpen}

package/frontend/src/components/ui/barcode-scanner.tsx

@@ -0,0 +1,222 @@
+'use client';
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { X, Camera, SwitchCamera, Flashlight, Loader2 } from 'lucide-react';
+
+interface BarcodeScannerProps {
+  /** Whether the scanner modal is open */
+  isOpen: boolean;
+  /** Called when the modal is closed */
+  onClose: () => void;
+  /** Called when a barcode/QR code is successfully scanned */
+  onScan: (code: string) => void;
+  /** Title shown at the top of the modal */
+  title?: string;
+}
+
+/**
+ * Camera-based barcode and QR code scanner modal.
+ * 
+ * Uses the `html5-qrcode` library to access the device camera and decode
+ * barcodes in real-time. Supports EAN-13, EAN-8, UPC-A, Code-128, QR Code,
+ * Data Matrix, and more.
+ * 
+ * Works on mobile (front/back camera), tablets, and desktop webcams.
+ * 
+ * @example
+ * ```tsx
+ * const [scannerOpen, setScannerOpen] = useState(false);
+ * 
+ * <BarcodeScanner
+ *   isOpen={scannerOpen}
+ *   onClose={() => setScannerOpen(false)}
+ *   onScan={(code) => {
+ *     console.log('Scanned:', code);
+ *     setScannerOpen(false);
+ *   }}
+ * />
+ * ```
+ */
+export function BarcodeScanner({ isOpen, onClose, onScan, title = 'Scan Barcode' }: BarcodeScannerProps) {
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [facingMode, setFacingMode] = useState<'environment' | 'user'>('environment');
+  const scannerRef = useRef<any>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const hasScannedRef = useRef(false);
+
+  const stopScanner = useCallback(async () => {
+    if (scannerRef.current) {
+      try {
+        const state = scannerRef.current.getState();
+        // State 2 = SCANNING
+        if (state === 2) {
+          await scannerRef.current.stop();
+        }
+        scannerRef.current.clear();
+      } catch {
+        // Ignore cleanup errors
+      }
+      scannerRef.current = null;
+    }
+  }, []);
+
+  const startScanner = useCallback(async () => {
+    if (!isOpen) return;
+    
+    setLoading(true);
+    setError(null);
+    hasScannedRef.current = false;
+
+    // Dynamic import to avoid SSR issues
+    const { Html5Qrcode } = await import('html5-qrcode');
+    
+    // Clean up any previous instance
+    await stopScanner();
+
+    // Wait for DOM to be ready
+    await new Promise(resolve => setTimeout(resolve, 100));
+    
+    const readerId = 'barcode-reader';
+    const readerElement = document.getElementById(readerId);
+    if (!readerElement) {
+      setError('Scanner container not found');
+      setLoading(false);
+      return;
+    }
+
+    try {
+      const scanner = new Html5Qrcode(readerId);
+      scannerRef.current = scanner;
+
+      await scanner.start(
+        { facingMode },
+        {
+          fps: 10,
+          qrbox: { width: 250, height: 250 },
+          aspectRatio: 1.0,
+        },
+        (decodedText: string) => {
+          // Prevent double scans
+          if (hasScannedRef.current) return;
+          hasScannedRef.current = true;
+
+          onScan(decodedText);
+        },
+        () => {
+          // QR decode failure — this fires continuously, ignore
+        }
+      );
+
+      setLoading(false);
+    } catch (err: any) {
+      setLoading(false);
+      if (err?.message?.includes('NotAllowedError') || err?.name === 'NotAllowedError') {
+        setError('Camera permission denied. Please allow camera access in your browser settings.');
+      } else if (err?.message?.includes('NotFoundError') || err?.name === 'NotFoundError') {
+        setError('No camera found on this device.');
+      } else {
+        setError(`Camera error: ${err?.message || 'Unknown error'}`);
+      }
+    }
+  }, [isOpen, facingMode, onScan, stopScanner]);
+
+  // Start scanner when modal opens
+  useEffect(() => {
+    if (isOpen) {
+      startScanner();
+    }
+    return () => {
+      stopScanner();
+    };
+  }, [isOpen, startScanner, stopScanner]);
+
+  // Toggle front/back camera
+  const toggleCamera = useCallback(async () => {
+    setFacingMode(prev => prev === 'environment' ? 'user' : 'environment');
+  }, []);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-[100] flex items-center justify-center bg-black/70 backdrop-blur-sm">
+      <div className="bg-background border border-border rounded-2xl shadow-2xl w-full max-w-md mx-4 overflow-hidden">
+        {/* Header */}
+        <div className="flex items-center justify-between px-4 py-3 border-b border-border">
+          <div className="flex items-center gap-2">
+            <Camera size={20} className="text-brand-500" />
+            <h3 className="font-semibold text-foreground">{title}</h3>
+          </div>
+          <button
+            onClick={() => { stopScanner(); onClose(); }}
+            className="p-1.5 rounded-lg hover:bg-surface transition-colors text-foreground/60 hover:text-foreground"
+          >
+            <X size={20} />
+          </button>
+        </div>
+
+        {/* Camera View */}
+        <div className="relative bg-black">
+          <div
+            id="barcode-reader"
+            ref={containerRef}
+            className="w-full aspect-square"
+          />
+
+          {/* Loading overlay */}
+          {loading && (
+            <div className="absolute inset-0 flex flex-col items-center justify-center bg-black/80 text-white gap-3">
+              <Loader2 size={32} className="animate-spin text-brand-500" />
+              <p className="text-sm text-white/80">Starting camera...</p>
+            </div>
+          )}
+
+          {/* Error overlay */}
+          {error && (
+            <div className="absolute inset-0 flex flex-col items-center justify-center bg-black/80 text-white gap-3 p-6">
+              <Camera size={48} className="text-red-400" />
+              <p className="text-sm text-center text-red-300">{error}</p>
+              <button
+                onClick={startScanner}
+                className="px-4 py-2 bg-brand-500 text-white rounded-lg text-sm hover:bg-brand-600 transition-colors"
+              >
+                Try Again
+              </button>
+            </div>
+          )}
+
+          {/* Scan overlay frame */}
+          {!loading && !error && (
+            <div className="absolute inset-0 pointer-events-none">
+              <div className="absolute inset-0 flex items-center justify-center">
+                <div className="w-[250px] h-[250px] border-2 border-brand-500/50 rounded-lg">
+                  {/* Corner accents */}
+                  <div className="absolute top-0 left-0 w-6 h-6 border-t-3 border-l-3 border-brand-400 rounded-tl-lg" />
+                  <div className="absolute top-0 right-0 w-6 h-6 border-t-3 border-r-3 border-brand-400 rounded-tr-lg" />
+                  <div className="absolute bottom-0 left-0 w-6 h-6 border-b-3 border-l-3 border-brand-400 rounded-bl-lg" />
+                  <div className="absolute bottom-0 right-0 w-6 h-6 border-b-3 border-r-3 border-brand-400 rounded-br-lg" />
+                </div>
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* Controls */}
+        <div className="flex items-center justify-between px-4 py-3 border-t border-border">
+          <p className="text-xs text-foreground/50">
+            Point camera at barcode or QR code
+          </p>
+          <div className="flex items-center gap-2">
+            <button
+              onClick={toggleCamera}
+              className="p-2 rounded-lg bg-surface hover:bg-border transition-colors text-foreground/70"
+              title="Switch Camera"
+            >
+              <SwitchCamera size={18} />
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/frontend/src/components/ui/scan-feedback.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useCallback, useRef } from 'react';
+
+const BEEP_DURATION = 150;
+const BEEP_VOLUME = 0.3;
+
+/**
+ * Creates a beep sound using the Web Audio API.
+ * No external audio files needed — works everywhere.
+ */
+function createBeep(frequency: number, duration: number, volume: number) {
+  try {
+    const audioCtx = new (window.AudioContext || (window as any).webkitAudioContext)();
+    const oscillator = audioCtx.createOscillator();
+    const gainNode = audioCtx.createGain();
+
+    oscillator.connect(gainNode);
+    gainNode.connect(audioCtx.destination);
+
+    oscillator.frequency.value = frequency;
+    oscillator.type = 'sine';
+    gainNode.gain.value = volume;
+
+    oscillator.start();
+    oscillator.stop(audioCtx.currentTime + duration / 1000);
+
+    // Clean up
+    oscillator.onended = () => audioCtx.close();
+  } catch {
+    // Audio not supported — fail silently
+  }
+}
+
+/**
+ * Hook that provides audio and visual feedback for barcode scanning.
+ * 
+ * @example
+ * ```tsx
+ * const { playSuccess, playError, flashElement } = useScanFeedback();
+ * 
+ * // On successful scan
+ * playSuccess();
+ * flashElement('green');
+ * 
+ * // On failed scan
+ * playError();
+ * flashElement('red');
+ * ```
+ */
+export function useScanFeedback() {
+  const flashTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const flashElementRef = useRef<HTMLElement | null>(null);
+
+  /** Play a success beep (high pitch) */
+  const playSuccess = useCallback(() => {
+    createBeep(1200, BEEP_DURATION, BEEP_VOLUME);
+    // Double beep for success
+    setTimeout(() => createBeep(1500, BEEP_DURATION, BEEP_VOLUME), 100);
+  }, []);
+
+  /** Play an error beep (low pitch) */
+  const playError = useCallback(() => {
+    createBeep(300, 300, BEEP_VOLUME);
+  }, []);
+
+  /**
+   * Flash the border of a target element green or red.
+   * Pass the element directly or use the ref returned by `getFlashRef`.
+   */
+  const flashElement = useCallback((color: 'green' | 'red', element?: HTMLElement | null) => {
+    const target = element || flashElementRef.current;
+    if (!target) return;
+
+    // Clear any existing flash
+    if (flashTimeoutRef.current) {
+      clearTimeout(flashTimeoutRef.current);
+    }
+
+    const borderColor = color === 'green' ? 'rgb(34, 197, 94)' : 'rgb(239, 68, 68)';
+    const shadowColor = color === 'green' ? 'rgba(34, 197, 94, 0.4)' : 'rgba(239, 68, 68, 0.4)';
+
+    target.style.transition = 'box-shadow 0.15s ease-in, border-color 0.15s ease-in';
+    target.style.borderColor = borderColor;
+    target.style.boxShadow = `0 0 0 3px ${shadowColor}`;
+
+    flashTimeoutRef.current = setTimeout(() => {
+      target.style.borderColor = '';
+      target.style.boxShadow = '';
+      target.style.transition = '';
+    }, 600);
+  }, []);
+
+  return {
+    playSuccess,
+    playError,
+    flashElement,
+    flashElementRef,
+  };
+}

package/frontend/src/hooks/use-barcode-scanner.ts

@@ -0,0 +1,84 @@
+'use client';
+
+import { useEffect, useRef, useCallback } from 'react';
+
+interface UseBarcodeOptions {
+  /** Callback when a barcode is scanned */
+  onScan: (code: string) => void;
+  /** Minimum barcode length (default: 3) */
+  minLength?: number;
+  /** Maximum time between keystrokes in ms (default: 80) */
+  maxDelay?: number;
+  /** Whether the scanner is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Custom hook that detects USB/Bluetooth barcode scanner input.
+ * 
+ * Hardware barcode scanners work like fast keyboards — they type characters
+ * very quickly (under 50ms between keystrokes) and end with Enter.
+ * This hook detects that pattern and fires `onScan` with the scanned code.
+ * 
+ * @example
+ * ```tsx
+ * useBarcodeScanner({
+ *   onScan: (code) => {
+ *     console.log('Scanned:', code);
+ *     // Look up product by barcode and add to cart
+ *   },
+ * });
+ * ```
+ */
+export function useBarcodeScanner({
+  onScan,
+  minLength = 3,
+  maxDelay = 80,
+  enabled = true,
+}: UseBarcodeOptions) {
+  const bufferRef = useRef('');
+  const lastKeyTimeRef = useRef(Date.now());
+  const onScanRef = useRef(onScan);
+
+  // Keep callback ref updated without re-registering the listener
+  useEffect(() => {
+    onScanRef.current = onScan;
+  }, [onScan]);
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      // Skip if focused on an input/textarea (let the input handle it)
+      const activeTag = document.activeElement?.tagName.toLowerCase();
+      const isInputActive = activeTag === 'input' || activeTag === 'textarea';
+
+      const now = Date.now();
+      const timeDiff = now - lastKeyTimeRef.current;
+      lastKeyTimeRef.current = now;
+
+      // Reset buffer if too much time has passed between keystrokes
+      if (timeDiff > maxDelay) {
+        bufferRef.current = '';
+      }
+
+      if (e.key === 'Enter') {
+        const code = bufferRef.current.trim();
+        if (code.length >= minLength) {
+          e.preventDefault();
+          e.stopPropagation();
+          bufferRef.current = '';
+          onScanRef.current(code);
+        }
+      } else if (e.key.length === 1 && !isInputActive) {
+        bufferRef.current += e.key;
+      }
+    },
+    [minLength, maxDelay]
+  );
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    window.addEventListener('keydown', handleKeyDown, { capture: true });
+    return () => window.removeEventListener('keydown', handleKeyDown, { capture: true });
+  }, [enabled, handleKeyDown]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pharmacy-erp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Pharmacy ERP & POS System — Enterprise-grade pharmacy management with full Arabic (RTL) and English support",
   "bin": {
     "pharmacy-erp": "./bin/cli.js"