From dbe2aeff2d627a71e43aba538ddb3845662e6a7d Mon Sep 17 00:00:00 2001
From: Kaosara18 <hallab419@gmail.com>
Date: Sun, 18 Oct 2026 17:24:59 +0100
Subject: [PATCH 1/4] feat(deliveries): create signature canvas component

---
 components/deliveries/SignatureCanvas.tsx     | 115 ++++++++++
 .../__tests__/SignatureCanvas.test.tsx        | 197 ++++++++++++++++++
 hooks/useSignatureCanvas.ts                   | 183 ++++++++++++++++
 .../__tests__/signatureCaptureService.test.ts |  28 +++
 services/signatureCaptureService.ts           |  23 ++
 5 files changed, 546 insertions(+)
 create mode 100644 components/deliveries/SignatureCanvas.tsx
 create mode 100644 components/deliveries/__tests__/SignatureCanvas.test.tsx
 create mode 100644 hooks/useSignatureCanvas.ts
 create mode 100644 services/__tests__/signatureCaptureService.test.ts
 create mode 100644 services/signatureCaptureService.ts

diff --git a/components/deliveries/SignatureCanvas.tsx b/components/deliveries/SignatureCanvas.tsx
new file mode 100644
index 00000000..3487329f
--- /dev/null
+++ b/components/deliveries/SignatureCanvas.tsx
@@ -0,0 +1,115 @@
+'use client';
+
+import { useRef } from 'react';
+import { Eraser, Save } from 'lucide-react';
+import { useSignatureCanvas } from '@/hooks/useSignatureCanvas';
+
+export interface SignatureCanvasProps {
+  onSave: (_dataUrl: string) => void;
+  width?: number;
+  height?: number;
+  disabled?: boolean;
+  className?: string;
+}
+
+/** Canvas signature capture with a keyboard-accessible typed fallback. */
+export function SignatureCanvas({
+  onSave,
+  width = 720,
+  height = 260,
+  disabled = false,
+  className = '',
+}: SignatureCanvasProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const {
+    beginStroke,
+    clear,
+    continueStroke,
+    endStroke,
+    hasSignature,
+    isTooLight,
+    save,
+    setTypedSignature,
+    typedSignature,
+  } = useSignatureCanvas({ canvasRef, onSave, disabled });
+
+  const cannotSave = disabled || !hasSignature || isTooLight;
+
+  return (
+    <section
+      className={`space-y-4 rounded-lg border border-slate-200 bg-white p-4 ${className}`.trim()}
+      aria-labelledby="recipient-signature-heading"
+    >
+      <div>
+        <h2 id="recipient-signature-heading" className="text-sm font-semibold text-slate-900">
+          Recipient signature
+        </h2>
+        <p className="mt-1 text-sm text-slate-600">
+          Sign inside the box using a mouse, stylus, or touch screen.
+        </p>
+      </div>
+
+      <canvas
+        ref={canvasRef}
+        width={width}
+        height={height}
+        aria-label="Recipient signature drawing area"
+        className="block aspect-[18/7] w-full touch-none rounded border border-slate-300 bg-white focus:outline-none focus:ring-2 focus:ring-blue-600 disabled:cursor-not-allowed"
+        onPointerDown={beginStroke}
+        onPointerMove={continueStroke}
+        onPointerUp={endStroke}
+        onPointerCancel={endStroke}
+        onPointerLeave={endStroke}
+        role="img"
+      />
+
+      {hasSignature && isTooLight && (
+        <p role="alert" className="text-sm font-medium text-amber-700">
+          Signature is too light. Add a longer stroke before saving.
+        </p>
+      )}
+
+      <div>
+        <label htmlFor="typed-signature" className="text-sm font-medium text-slate-800">
+          Keyboard signature fallback
+        </label>
+        <p id="typed-signature-help" className="mt-1 text-xs text-slate-500">
+          Type the recipient&apos;s name when drawing is not accessible.
+        </p>
+        <textarea
+          id="typed-signature"
+          value={typedSignature}
+          onChange={(event) => setTypedSignature(event.target.value)}
+          disabled={disabled}
+          aria-describedby="typed-signature-help"
+          rows={2}
+          className="mt-2 w-full resize-none rounded border border-slate-300 px-3 py-2 text-sm text-slate-900 focus:border-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-100 disabled:bg-slate-100"
+          placeholder="Type recipient name"
+        />
+      </div>
+
+      <div className="flex flex-wrap justify-end gap-2">
+        <button
+          type="button"
+          onClick={clear}
+          disabled={disabled || !hasSignature}
+          className="inline-flex min-h-10 items-center justify-center gap-2 rounded border border-slate-300 px-4 py-2 text-sm font-medium text-slate-700 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-50"
+        >
+          <Eraser aria-hidden="true" className="h-4 w-4" />
+          Clear
+        </button>
+        <button
+          type="button"
+          onClick={save}
+          disabled={cannotSave}
+          className="inline-flex min-h-10 items-center justify-center gap-2 rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:cursor-not-allowed disabled:bg-slate-300"
+        >
+          <Save aria-hidden="true" className="h-4 w-4" />
+          Save signature
+        </button>
+      </div>
+    </section>
+  );
+}
+
+export default SignatureCanvas;
diff --git a/components/deliveries/__tests__/SignatureCanvas.test.tsx b/components/deliveries/__tests__/SignatureCanvas.test.tsx
new file mode 100644
index 00000000..edbd785d
--- /dev/null
+++ b/components/deliveries/__tests__/SignatureCanvas.test.tsx
@@ -0,0 +1,197 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { SignatureCanvas } from '@/components/deliveries/SignatureCanvas';
+
+const context = {
+  beginPath: jest.fn(),
+  clearRect: jest.fn(),
+  fillText: jest.fn(),
+  lineTo: jest.fn(),
+  moveTo: jest.fn(),
+  stroke: jest.fn(),
+  fillStyle: '',
+  font: '',
+  lineCap: '',
+  lineJoin: '',
+  lineWidth: 0,
+  strokeStyle: '',
+  textBaseline: '',
+};
+
+function drawSignature(pointerType: 'mouse' | 'touch' = 'mouse') {
+  const canvas = screen.getByLabelText('Recipient signature drawing area');
+  fireEvent.pointerDown(canvas, {
+    button: 0,
+    clientX: 10,
+    clientY: 20,
+    pointerId: 1,
+    pointerType,
+  });
+  fireEvent.pointerMove(canvas, {
+    clientX: 90,
+    clientY: 40,
+    pointerId: 1,
+    pointerType,
+  });
+  fireEvent.pointerUp(canvas, { pointerId: 1, pointerType });
+}
+
+describe('SignatureCanvas', () => {
+  beforeAll(() => {
+    Object.defineProperty(window, 'PointerEvent', {
+      configurable: true,
+      value: MouseEvent,
+    });
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(
+      context as unknown as CanvasRenderingContext2D,
+    );
+    jest.spyOn(HTMLCanvasElement.prototype, 'toDataURL').mockReturnValue(
+      'data:image/png;base64,c2lnbmF0dXJl',
+    );
+    jest.spyOn(HTMLCanvasElement.prototype, 'getBoundingClientRect').mockReturnValue({
+      bottom: 260,
+      height: 260,
+      left: 0,
+      right: 720,
+      top: 0,
+      width: 720,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    });
+  });
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('renders the drawing area, fallback, and actions', () => {
+    render(<SignatureCanvas onSave={jest.fn()} />);
+
+    expect(screen.getByRole('heading', { name: 'Recipient signature' })).toBeInTheDocument();
+    expect(screen.getByLabelText('Recipient signature drawing area')).toBeInTheDocument();
+    expect(screen.getByLabelText('Keyboard signature fallback')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Clear' })).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeDisabled();
+  });
+
+  it('captures a mouse stroke on the canvas', () => {
+    render(<SignatureCanvas onSave={jest.fn()} />);
+    drawSignature('mouse');
+
+    expect(context.beginPath).toHaveBeenCalled();
+    expect(context.moveTo).toHaveBeenCalledWith(10, 20);
+    expect(context.lineTo).toHaveBeenCalledWith(90, 40);
+    expect(context.stroke).toHaveBeenCalled();
+  });
+
+  it('captures a touch pointer stroke on the canvas', () => {
+    render(<SignatureCanvas onSave={jest.fn()} />);
+    drawSignature('touch');
+
+    expect(context.lineTo).toHaveBeenCalledWith(90, 40);
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeEnabled();
+  });
+
+  it('shows a quality warning for a dot without a meaningful stroke', () => {
+    render(<SignatureCanvas onSave={jest.fn()} />);
+    const canvas = screen.getByLabelText('Recipient signature drawing area');
+
+    fireEvent.pointerDown(canvas, { button: 0, clientX: 10, clientY: 10, pointerId: 2 });
+    fireEvent.pointerUp(canvas, { pointerId: 2 });
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Signature is too light');
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeDisabled();
+  });
+
+  it('removes the quality warning after a meaningful stroke', () => {
+    render(<SignatureCanvas onSave={jest.fn()} />);
+    drawSignature();
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeEnabled();
+  });
+
+  it('accumulates ink quality across multiple strokes', () => {
+    render(<SignatureCanvas onSave={jest.fn()} />);
+    const canvas = screen.getByLabelText('Recipient signature drawing area');
+
+    fireEvent.pointerDown(canvas, { button: 0, clientX: 10, clientY: 10, pointerId: 1 });
+    fireEvent.pointerMove(canvas, { clientX: 40, clientY: 10, pointerId: 1 });
+    fireEvent.pointerUp(canvas, { pointerId: 1 });
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+
+    fireEvent.pointerDown(canvas, { button: 0, clientX: 40, clientY: 10, pointerId: 2 });
+    fireEvent.pointerMove(canvas, { clientX: 70, clientY: 10, pointerId: 2 });
+    fireEvent.pointerUp(canvas, { pointerId: 2 });
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeEnabled();
+  });
+
+  it('saves a drawn signature as a PNG data URL', async () => {
+    const onSave = jest.fn();
+    const user = userEvent.setup();
+    render(<SignatureCanvas onSave={onSave} />);
+    drawSignature();
+
+    await user.click(screen.getByRole('button', { name: 'Save signature' }));
+
+    expect(HTMLCanvasElement.prototype.toDataURL).toHaveBeenCalledWith('image/png');
+    expect(onSave).toHaveBeenCalledWith('data:image/png;base64,c2lnbmF0dXJl');
+  });
+
+  it('clears the canvas and resets both actions', async () => {
+    const user = userEvent.setup();
+    render(<SignatureCanvas onSave={jest.fn()} />);
+    drawSignature();
+
+    await user.click(screen.getByRole('button', { name: 'Clear' }));
+
+    expect(context.clearRect).toHaveBeenCalledWith(0, 0, 720, 260);
+    expect(screen.getByRole('button', { name: 'Clear' })).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeDisabled();
+  });
+
+  it('supports a keyboard-entered recipient signature', async () => {
+    const user = userEvent.setup();
+    render(<SignatureCanvas onSave={jest.fn()} />);
+
+    await user.type(screen.getByLabelText('Keyboard signature fallback'), 'Ada Lovelace');
+
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeEnabled();
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+
+  it('renders typed text onto the canvas before saving', async () => {
+    const onSave = jest.fn();
+    const user = userEvent.setup();
+    render(<SignatureCanvas onSave={onSave} />);
+    await user.type(screen.getByLabelText('Keyboard signature fallback'), 'Ada Lovelace');
+
+    await user.click(screen.getByRole('button', { name: 'Save signature' }));
+
+    expect(context.fillText).toHaveBeenCalledWith('Ada Lovelace', 24, 130);
+    expect(onSave).toHaveBeenCalledWith('data:image/png;base64,c2lnbmF0dXJl');
+  });
+
+  it('treats one typed character as too light', async () => {
+    const user = userEvent.setup();
+    render(<SignatureCanvas onSave={jest.fn()} />);
+
+    await user.type(screen.getByLabelText('Keyboard signature fallback'), 'A');
+
+    expect(screen.getByRole('alert')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeDisabled();
+  });
+
+  it('disables all interaction when disabled', () => {
+    render(<SignatureCanvas onSave={jest.fn()} disabled />);
+
+    expect(screen.getByLabelText('Keyboard signature fallback')).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Clear' })).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'Save signature' })).toBeDisabled();
+  });
+});
diff --git a/hooks/useSignatureCanvas.ts b/hooks/useSignatureCanvas.ts
new file mode 100644
index 00000000..e7b7e027
--- /dev/null
+++ b/hooks/useSignatureCanvas.ts
@@ -0,0 +1,183 @@
+'use client';
+
+import {
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+  useCallback,
+  useRef,
+  useState,
+} from 'react';
+import {
+  MIN_SIGNATURE_INK_LENGTH,
+  signatureCaptureService,
+} from '@/services/signatureCaptureService';
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+interface UseSignatureCanvasOptions {
+  canvasRef: RefObject<HTMLCanvasElement | null>;
+  onSave: (_dataUrl: string) => void;
+  disabled?: boolean;
+  minimumInkLength?: number;
+}
+
+function canvasPoint(canvas: HTMLCanvasElement, event: ReactPointerEvent<HTMLCanvasElement>): Point {
+  const rect = canvas.getBoundingClientRect();
+  const scaleX = rect.width > 0 ? canvas.width / rect.width : 1;
+  const scaleY = rect.height > 0 ? canvas.height / rect.height : 1;
+
+  return {
+    x: (event.clientX - rect.left) * scaleX,
+    y: (event.clientY - rect.top) * scaleY,
+  };
+}
+
+function drawingContext(canvas: HTMLCanvasElement): CanvasRenderingContext2D | null {
+  const context = canvas.getContext('2d');
+  if (!context) return null;
+
+  context.lineCap = 'round';
+  context.lineJoin = 'round';
+  context.lineWidth = 2.5;
+  context.strokeStyle = '#111827';
+  return context;
+}
+
+export function useSignatureCanvas({
+  canvasRef,
+  onSave,
+  disabled = false,
+  minimumInkLength = MIN_SIGNATURE_INK_LENGTH,
+}: UseSignatureCanvasOptions) {
+  const [hasSignature, setHasSignature] = useState(false);
+  const [isTooLight, setIsTooLight] = useState(false);
+  const [typedSignature, setTypedSignatureState] = useState('');
+  const drawingRef = useRef(false);
+  const lastPointRef = useRef<Point | null>(null);
+  const inkLengthRef = useRef(0);
+
+  const updateQuality = useCallback(
+    (inkLength: number, text: string) => {
+      const quality = signatureCaptureService.assessQuality(
+        inkLength,
+        text,
+        minimumInkLength,
+      );
+      setIsTooLight(quality.isTooLight);
+    },
+    [minimumInkLength],
+  );
+
+  const clear = useCallback(() => {
+    const canvas = canvasRef.current;
+    canvas?.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height);
+    drawingRef.current = false;
+    lastPointRef.current = null;
+    inkLengthRef.current = 0;
+    setTypedSignatureState('');
+    setHasSignature(false);
+    setIsTooLight(false);
+  }, [canvasRef]);
+
+  const beginStroke = useCallback(
+    (event: ReactPointerEvent<HTMLCanvasElement>) => {
+      if (disabled || event.button > 0) return;
+      const canvas = canvasRef.current;
+      const context = canvas && drawingContext(canvas);
+      if (!canvas || !context) return;
+
+      event.preventDefault();
+      canvas.setPointerCapture?.(event.pointerId);
+      if (typedSignature) {
+        context.clearRect(0, 0, canvas.width, canvas.height);
+        setTypedSignatureState('');
+        inkLengthRef.current = 0;
+      }
+      const point = canvasPoint(canvas, event);
+      context.beginPath();
+      context.moveTo(point.x, point.y);
+      drawingRef.current = true;
+      lastPointRef.current = point;
+      setHasSignature(true);
+      updateQuality(inkLengthRef.current, '');
+    },
+    [canvasRef, disabled, typedSignature, updateQuality],
+  );
+
+  const continueStroke = useCallback(
+    (event: ReactPointerEvent<HTMLCanvasElement>) => {
+      if (!drawingRef.current || disabled) return;
+      const canvas = canvasRef.current;
+      const context = canvas && drawingContext(canvas);
+      const previous = lastPointRef.current;
+      if (!canvas || !context || !previous) return;
+
+      event.preventDefault();
+      const point = canvasPoint(canvas, event);
+      context.lineTo(point.x, point.y);
+      context.stroke();
+      inkLengthRef.current += Math.hypot(point.x - previous.x, point.y - previous.y);
+      lastPointRef.current = point;
+      updateQuality(inkLengthRef.current, '');
+    },
+    [canvasRef, disabled, updateQuality],
+  );
+
+  const endStroke = useCallback(
+    (event: ReactPointerEvent<HTMLCanvasElement>) => {
+      if (!drawingRef.current) return;
+      canvasRef.current?.releasePointerCapture?.(event.pointerId);
+      drawingRef.current = false;
+      lastPointRef.current = null;
+      updateQuality(inkLengthRef.current, '');
+    },
+    [canvasRef, updateQuality],
+  );
+
+  const setTypedSignature = useCallback(
+    (value: string) => {
+      const canvas = canvasRef.current;
+      canvas?.getContext('2d')?.clearRect(0, 0, canvas.width, canvas.height);
+      drawingRef.current = false;
+      lastPointRef.current = null;
+      inkLengthRef.current = 0;
+      setTypedSignatureState(value);
+      setHasSignature(value.trim().length > 0);
+      updateQuality(0, value);
+    },
+    [canvasRef, updateQuality],
+  );
+
+  const save = useCallback(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || !hasSignature || isTooLight || disabled) return;
+
+    if (typedSignature.trim()) {
+      const context = drawingContext(canvas);
+      if (!context) return;
+      context.clearRect(0, 0, canvas.width, canvas.height);
+      context.fillStyle = '#111827';
+      context.font = 'italic 30px cursive';
+      context.textBaseline = 'middle';
+      context.fillText(typedSignature.trim(), 24, canvas.height / 2);
+    }
+
+    const dataUrl = canvas.toDataURL('image/png');
+    if (dataUrl && dataUrl !== 'data:,') onSave(dataUrl);
+  }, [canvasRef, disabled, hasSignature, isTooLight, onSave, typedSignature]);
+
+  return {
+    beginStroke,
+    clear,
+    continueStroke,
+    endStroke,
+    hasSignature,
+    isTooLight,
+    save,
+    setTypedSignature,
+    typedSignature,
+  };
+}
diff --git a/services/__tests__/signatureCaptureService.test.ts b/services/__tests__/signatureCaptureService.test.ts
new file mode 100644
index 00000000..931a44e7
--- /dev/null
+++ b/services/__tests__/signatureCaptureService.test.ts
@@ -0,0 +1,28 @@
+import {
+  MIN_SIGNATURE_INK_LENGTH,
+  signatureCaptureService,
+} from '@/services/signatureCaptureService';
+
+describe('signatureCaptureService', () => {
+  it('rejects ink below the configured quality threshold', () => {
+    expect(
+      signatureCaptureService.assessQuality(MIN_SIGNATURE_INK_LENGTH - 1, ''),
+    ).toEqual({
+      inkLength: MIN_SIGNATURE_INK_LENGTH - 1,
+      isTooLight: true,
+    });
+  });
+
+  it('accepts ink at the configured quality threshold', () => {
+    expect(
+      signatureCaptureService.assessQuality(MIN_SIGNATURE_INK_LENGTH, ''),
+    ).toEqual({
+      inkLength: MIN_SIGNATURE_INK_LENGTH,
+      isTooLight: false,
+    });
+  });
+
+  it('accepts a trimmed typed fallback with at least two characters', () => {
+    expect(signatureCaptureService.assessQuality(0, '  Ada  ').isTooLight).toBe(false);
+  });
+});
diff --git a/services/signatureCaptureService.ts b/services/signatureCaptureService.ts
new file mode 100644
index 00000000..1db2d824
--- /dev/null
+++ b/services/signatureCaptureService.ts
@@ -0,0 +1,23 @@
+export interface SignatureQuality {
+  isTooLight: boolean;
+  inkLength: number;
+}
+
+export const MIN_SIGNATURE_INK_LENGTH = 48;
+
+/** Pure signature rules shared by the canvas hook and its tests. */
+export const signatureCaptureService = {
+  assessQuality(
+    inkLength: number,
+    typedSignature: string,
+    minimumInkLength = MIN_SIGNATURE_INK_LENGTH,
+  ): SignatureQuality {
+    const normalizedText = typedSignature.trim();
+    const hasTypedSignature = normalizedText.length >= 2;
+
+    return {
+      inkLength,
+      isTooLight: !hasTypedSignature && inkLength < minimumInkLength,
+    };
+  },
+};

From a7ef4dc21801785ce3e5e49d063a5ae7a67287e1 Mon Sep 17 00:00:00 2001
From: Kaosara18 <hallab419@gmail.com>
Date: Sun, 18 Oct 2026 17:25:22 +0100
Subject: [PATCH 2/4] test(fleet): cover vehicle registration form and hook

---
 .../fleet/VehicleRegistration.test.tsx        | 214 ++++++++++++++++++
 components/fleet/VehicleRegistration.tsx      | 209 +++++++++++++++++
 .../__tests__/useVehicleRegistration.test.ts  | 164 ++++++++++++++
 hooks/useVehicleRegistration.ts               | 145 ++++++++++++
 services/fleetService.ts                      |  39 +++-
 types/fleet.ts                                |  25 ++
 6 files changed, 795 insertions(+), 1 deletion(-)
 create mode 100644 __tests__/components/fleet/VehicleRegistration.test.tsx
 create mode 100644 hooks/__tests__/useVehicleRegistration.test.ts
 create mode 100644 hooks/useVehicleRegistration.ts

diff --git a/__tests__/components/fleet/VehicleRegistration.test.tsx b/__tests__/components/fleet/VehicleRegistration.test.tsx
new file mode 100644
index 00000000..dc53621f
--- /dev/null
+++ b/__tests__/components/fleet/VehicleRegistration.test.tsx
@@ -0,0 +1,214 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { VehicleRegistration } from '@/components/fleet/VehicleRegistration';
+import { useVehicleRegistration } from '@/hooks/useVehicleRegistration';
+import type { VehicleRegistrationInput } from '@/types/fleet';
+
+jest.mock('@/hooks/useVehicleRegistration');
+
+const mockedUseVehicleRegistration = useVehicleRegistration as jest.MockedFunction<
+  typeof useVehicleRegistration
+>;
+
+const emptyValues: VehicleRegistrationInput = {
+  plateNumber: '',
+  make: '',
+  model: '',
+  year: '',
+  type: '',
+  capacityKg: '',
+  temperatureMin: '',
+  cargoBoxSize: '',
+  registrationDocument: null,
+  vehiclePhoto: null,
+};
+
+function mockHook(overrides: Partial<ReturnType<typeof useVehicleRegistration>> = {}) {
+  mockedUseVehicleRegistration.mockReturnValue({
+    values: emptyValues,
+    errors: {},
+    isValid: false,
+    isSubmitting: false,
+    isSubmitted: false,
+    photoPreview: null,
+    updateField: jest.fn(),
+    setVehiclePhoto: jest.fn(),
+    submit: jest.fn().mockResolvedValue(true),
+    reset: jest.fn(),
+    ...overrides,
+  });
+}
+
+describe('VehicleRegistration', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockHook();
+  });
+
+  it('renders every required vehicle field', () => {
+    render(<VehicleRegistration />);
+
+    expect(screen.getByLabelText('Plate number')).toBeRequired();
+    expect(screen.getByLabelText('Vehicle type')).toBeRequired();
+    expect(screen.getByLabelText('Make')).toBeRequired();
+    expect(screen.getByLabelText('Model')).toBeRequired();
+    expect(screen.getByLabelText('Year')).toBeRequired();
+    expect(screen.getByLabelText('Capacity (kg)')).toBeRequired();
+    expect(screen.getByLabelText('Registration document')).toBeRequired();
+    expect(screen.getByLabelText('Vehicle photo')).toBeRequired();
+  });
+
+  it('passes text input changes to the hook', async () => {
+    const updateField = jest.fn();
+    mockHook({ updateField });
+    const user = userEvent.setup();
+    render(<VehicleRegistration />);
+
+    await user.type(screen.getByLabelText('Plate number'), 'ABC-123');
+
+    expect(updateField).toHaveBeenCalledWith('plateNumber', 'A');
+  });
+
+  it('routes every standard field and document change through the hook', () => {
+    const updateField = jest.fn();
+    mockHook({ updateField });
+    render(<VehicleRegistration />);
+    const document = new File(['registration'], 'registration.pdf', {
+      type: 'application/pdf',
+    });
+
+    fireEvent.change(screen.getByLabelText('Vehicle type'), { target: { value: 'truck' } });
+    fireEvent.change(screen.getByLabelText('Make'), { target: { value: 'Ford' } });
+    fireEvent.change(screen.getByLabelText('Model'), { target: { value: 'Transit' } });
+    fireEvent.change(screen.getByLabelText('Year'), { target: { value: '2025' } });
+    fireEvent.change(screen.getByLabelText('Capacity (kg)'), { target: { value: '1200' } });
+    fireEvent.change(screen.getByLabelText('Registration document'), {
+      target: { files: [document] },
+    });
+
+    expect(updateField).toHaveBeenCalledWith('type', 'truck');
+    expect(updateField).toHaveBeenCalledWith('make', 'Ford');
+    expect(updateField).toHaveBeenCalledWith('model', 'Transit');
+    expect(updateField).toHaveBeenCalledWith('year', '2025');
+    expect(updateField).toHaveBeenCalledWith('capacityKg', '1200');
+    expect(updateField).toHaveBeenCalledWith('registrationDocument', document);
+  });
+
+  it('shows refrigerated fields only for refrigerated vehicles', () => {
+    const updateField = jest.fn();
+    mockHook({ values: { ...emptyValues, type: 'refrigerated' }, updateField });
+    render(<VehicleRegistration />);
+
+    expect(screen.getByLabelText('Minimum temperature (C)')).toBeInTheDocument();
+    expect(screen.queryByLabelText('Cargo box size')).not.toBeInTheDocument();
+    fireEvent.change(screen.getByLabelText('Minimum temperature (C)'), {
+      target: { value: '-10' },
+    });
+    expect(updateField).toHaveBeenCalledWith('temperatureMin', '-10');
+  });
+
+  it('shows cargo box fields only for motorcycles', () => {
+    const updateField = jest.fn();
+    mockHook({ values: { ...emptyValues, type: 'motorcycle' }, updateField });
+    render(<VehicleRegistration />);
+
+    expect(screen.getByLabelText('Cargo box size')).toBeInTheDocument();
+    expect(screen.queryByLabelText('Minimum temperature (C)')).not.toBeInTheDocument();
+    fireEvent.change(screen.getByLabelText('Cargo box size'), {
+      target: { value: '60 L' },
+    });
+    expect(updateField).toHaveBeenCalledWith('cargoBoxSize', '60 L');
+  });
+
+  it('hides dynamic fields for a standard van', () => {
+    mockHook({ values: { ...emptyValues, type: 'van' } });
+    render(<VehicleRegistration />);
+
+    expect(screen.queryByLabelText('Cargo box size')).not.toBeInTheDocument();
+    expect(screen.queryByLabelText('Minimum temperature (C)')).not.toBeInTheDocument();
+  });
+
+  it('renders validation messages returned by the hook', () => {
+    mockHook({
+      errors: {
+        plateNumber: 'Plate number is required',
+        make: 'Make is required',
+        model: 'Model is required',
+        year: 'Year is required',
+        type: 'Vehicle type is required',
+        capacityKg: 'Capacity is required',
+        registrationDocument: 'Registration document is required',
+        vehiclePhoto: 'Vehicle photo is required',
+      },
+    });
+    render(<VehicleRegistration />);
+
+    expect(screen.getByText('Plate number is required')).toHaveAttribute('role', 'alert');
+    expect(screen.getByText('Registration document is required')).toBeInTheDocument();
+    expect(screen.getByText('Vehicle photo is required')).toBeInTheDocument();
+  });
+
+  it('keeps submit disabled until the form is valid', () => {
+    render(<VehicleRegistration />);
+    expect(screen.getByRole('button', { name: 'Register vehicle' })).toBeDisabled();
+  });
+
+  it('enables submit for a valid form', () => {
+    mockHook({ isValid: true });
+    render(<VehicleRegistration />);
+    expect(screen.getByRole('button', { name: 'Register vehicle' })).toBeEnabled();
+  });
+
+  it('submits through the hook', async () => {
+    const submit = jest.fn().mockResolvedValue(true);
+    mockHook({ isValid: true, submit });
+    const user = userEvent.setup();
+    render(<VehicleRegistration />);
+
+    await user.click(screen.getByRole('button', { name: 'Register vehicle' }));
+
+    expect(submit).toHaveBeenCalledTimes(1);
+  });
+
+  it('sends an uploaded photo to the hook', () => {
+    const setVehiclePhoto = jest.fn();
+    mockHook({ setVehiclePhoto });
+    render(<VehicleRegistration />);
+    const photo = new File(['vehicle'], 'vehicle.png', { type: 'image/png' });
+
+    fireEvent.change(screen.getByLabelText('Vehicle photo'), {
+      target: { files: [photo] },
+    });
+
+    expect(setVehiclePhoto).toHaveBeenCalledWith(photo);
+  });
+
+  it('renders the vehicle photo preview', () => {
+    mockHook({ photoPreview: 'blob:vehicle-preview' });
+    render(<VehicleRegistration />);
+
+    expect(screen.getByAltText('Vehicle preview')).toHaveAttribute(
+      'src',
+      'blob:vehicle-preview',
+    );
+  });
+
+  it('clears every field through the reset action', async () => {
+    const reset = jest.fn();
+    mockHook({ reset });
+    const user = userEvent.setup();
+    render(<VehicleRegistration />);
+
+    await user.click(screen.getByRole('button', { name: 'Reset form' }));
+
+    expect(reset).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows submission progress and success feedback', () => {
+    mockHook({ isValid: true, isSubmitting: true, isSubmitted: true });
+    render(<VehicleRegistration />);
+
+    expect(screen.getByRole('button', { name: 'Registering...' })).toBeDisabled();
+    expect(screen.getByRole('status')).toHaveTextContent('Vehicle registered successfully.');
+  });
+});
diff --git a/components/fleet/VehicleRegistration.tsx b/components/fleet/VehicleRegistration.tsx
index e69de29b..5c813348 100644
--- a/components/fleet/VehicleRegistration.tsx
+++ b/components/fleet/VehicleRegistration.tsx
@@ -0,0 +1,209 @@
+'use client';
+
+import { RotateCcw, Truck, Upload } from 'lucide-react';
+import { useVehicleRegistration } from '@/hooks/useVehicleRegistration';
+import type { VehicleRegistrationInput } from '@/types/fleet';
+
+const inputClass =
+  'w-full rounded-md border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 focus:border-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-100';
+
+export function VehicleRegistration() {
+  const {
+    values,
+    errors,
+    isValid,
+    isSubmitting,
+    isSubmitted,
+    photoPreview,
+    updateField,
+    setVehiclePhoto,
+    submit,
+    reset,
+  } = useVehicleRegistration();
+
+  const renderError = (field: keyof VehicleRegistrationInput) =>
+    errors[field] ? (
+      <p className="mt-1 text-xs text-red-600" role="alert">
+        {errors[field]}
+      </p>
+    ) : null;
+
+  return (
+    <form
+      className="space-y-5"
+      noValidate
+      onSubmit={(event) => {
+        event.preventDefault();
+        void submit();
+      }}
+    >
+      <div className="grid gap-4 sm:grid-cols-2">
+        <label className="text-sm font-medium text-gray-800">
+          Plate number
+          <input
+            aria-label="Plate number"
+            className={inputClass}
+            value={values.plateNumber}
+            onChange={(event) => updateField('plateNumber', event.target.value)}
+            required
+          />
+          {renderError('plateNumber')}
+        </label>
+        <label className="text-sm font-medium text-gray-800">
+          Vehicle type
+          <select
+            aria-label="Vehicle type"
+            className={inputClass}
+            value={values.type}
+            onChange={(event) =>
+              updateField('type', event.target.value as VehicleRegistrationInput['type'])
+            }
+            required
+          >
+            <option value="">Select a type</option>
+            <option value="van">Van</option>
+            <option value="truck">Truck</option>
+            <option value="refrigerated">Refrigerated</option>
+            <option value="motorcycle">Motorcycle</option>
+          </select>
+          {renderError('type')}
+        </label>
+        <label className="text-sm font-medium text-gray-800">
+          Make
+          <input
+            aria-label="Make"
+            className={inputClass}
+            value={values.make}
+            onChange={(event) => updateField('make', event.target.value)}
+            required
+          />
+          {renderError('make')}
+        </label>
+        <label className="text-sm font-medium text-gray-800">
+          Model
+          <input
+            aria-label="Model"
+            className={inputClass}
+            value={values.model}
+            onChange={(event) => updateField('model', event.target.value)}
+            required
+          />
+          {renderError('model')}
+        </label>
+        <label className="text-sm font-medium text-gray-800">
+          Year
+          <input
+            aria-label="Year"
+            className={inputClass}
+            inputMode="numeric"
+            value={values.year}
+            onChange={(event) => updateField('year', event.target.value)}
+            required
+          />
+          {renderError('year')}
+        </label>
+        <label className="text-sm font-medium text-gray-800">
+          Capacity (kg)
+          <input
+            aria-label="Capacity (kg)"
+            className={inputClass}
+            inputMode="decimal"
+            value={values.capacityKg}
+            onChange={(event) => updateField('capacityKg', event.target.value)}
+            required
+          />
+          {renderError('capacityKg')}
+        </label>
+      </div>
+
+      {values.type === 'refrigerated' && (
+        <label className="block text-sm font-medium text-gray-800">
+          Minimum temperature (C)
+          <input
+            aria-label="Minimum temperature (C)"
+            className={inputClass}
+            inputMode="decimal"
+            value={values.temperatureMin}
+            onChange={(event) => updateField('temperatureMin', event.target.value)}
+            required
+          />
+          {renderError('temperatureMin')}
+        </label>
+      )}
+
+      {values.type === 'motorcycle' && (
+        <label className="block text-sm font-medium text-gray-800">
+          Cargo box size
+          <input
+            aria-label="Cargo box size"
+            className={inputClass}
+            value={values.cargoBoxSize}
+            onChange={(event) => updateField('cargoBoxSize', event.target.value)}
+            required
+          />
+          {renderError('cargoBoxSize')}
+        </label>
+      )}
+
+      <div className="grid gap-4 sm:grid-cols-2">
+        <label className="rounded-md border border-dashed border-gray-300 p-4 text-sm font-medium text-gray-800">
+          <span className="flex items-center gap-2"><Upload size={16} /> Registration document</span>
+          <input
+            aria-label="Registration document"
+            className="mt-3 block w-full text-sm"
+            type="file"
+            accept="application/pdf,image/*"
+            onChange={(event) =>
+              updateField('registrationDocument', event.target.files?.[0] ?? null)
+            }
+            required
+          />
+          {renderError('registrationDocument')}
+        </label>
+        <label className="rounded-md border border-dashed border-gray-300 p-4 text-sm font-medium text-gray-800">
+          <span className="flex items-center gap-2"><Truck size={16} /> Vehicle photo</span>
+          <input
+            aria-label="Vehicle photo"
+            className="mt-3 block w-full text-sm"
+            type="file"
+            accept="image/*"
+            onChange={(event) => setVehiclePhoto(event.target.files?.[0] ?? null)}
+            required
+          />
+          {renderError('vehiclePhoto')}
+        </label>
+      </div>
+
+      {photoPreview && (
+        <div>
+          <p className="mb-2 text-sm font-medium text-gray-800">Vehicle photo preview</p>
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img className="h-40 w-full rounded-md object-cover" src={photoPreview} alt="Vehicle preview" />
+        </div>
+      )}
+
+      {errors.submit && <p role="alert" className="text-sm text-red-600">{errors.submit}</p>}
+      {isSubmitted && <p role="status" className="text-sm text-green-700">Vehicle registered successfully.</p>}
+
+      <div className="flex gap-3">
+        <button
+          type="submit"
+          disabled={!isValid || isSubmitting}
+          className="flex-1 rounded-md bg-blue-600 px-4 py-2 text-sm font-semibold text-white disabled:cursor-not-allowed disabled:bg-gray-300"
+        >
+          {isSubmitting ? 'Registering...' : 'Register vehicle'}
+        </button>
+        <button
+          type="button"
+          aria-label="Reset form"
+          onClick={reset}
+          className="inline-flex items-center justify-center rounded-md border border-gray-300 p-2 text-gray-700"
+        >
+          <RotateCcw size={18} />
+        </button>
+      </div>
+    </form>
+  );
+}
+
+export default VehicleRegistration;
diff --git a/hooks/__tests__/useVehicleRegistration.test.ts b/hooks/__tests__/useVehicleRegistration.test.ts
new file mode 100644
index 00000000..e072b70f
--- /dev/null
+++ b/hooks/__tests__/useVehicleRegistration.test.ts
@@ -0,0 +1,164 @@
+import { act, renderHook } from '@testing-library/react';
+import {
+  useVehicleRegistration,
+  validateVehicleRegistration,
+} from '@/hooks/useVehicleRegistration';
+import { fleetService } from '@/services/fleetService';
+import type { VehicleRegistrationInput } from '@/types/fleet';
+
+jest.mock('@/services/fleetService', () => ({
+  fleetService: { registerVehicle: jest.fn() },
+}));
+
+const registerVehicle = fleetService.registerVehicle as jest.Mock;
+
+const validValues: VehicleRegistrationInput = {
+  plateNumber: 'ABC-123',
+  make: 'Ford',
+  model: 'Transit',
+  year: '2025',
+  type: 'van',
+  capacityKg: '1200',
+  temperatureMin: '',
+  cargoBoxSize: '',
+  registrationDocument: new File(['registration'], 'registration.pdf', {
+    type: 'application/pdf',
+  }),
+  vehiclePhoto: new File(['photo'], 'vehicle.png', { type: 'image/png' }),
+};
+
+describe('useVehicleRegistration', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('starts empty and invalid', () => {
+    const { result } = renderHook(() => useVehicleRegistration());
+    expect(result.current.values.plateNumber).toBe('');
+    expect(result.current.isValid).toBe(false);
+    expect(result.current.isSubmitting).toBe(false);
+  });
+
+  it('validates all empty required fields', () => {
+    const errors = validateVehicleRegistration({
+      ...validValues,
+      plateNumber: '',
+      make: '',
+      model: '',
+      year: '',
+      type: '',
+      capacityKg: '',
+      registrationDocument: null,
+      vehiclePhoto: null,
+    });
+
+    expect(errors).toEqual(
+      expect.objectContaining({
+        plateNumber: expect.any(String),
+        make: expect.any(String),
+        model: expect.any(String),
+        year: expect.any(String),
+        type: expect.any(String),
+        capacityKg: expect.any(String),
+        registrationDocument: expect.any(String),
+        vehiclePhoto: expect.any(String),
+      }),
+    );
+  });
+
+  it('requires the vehicle-specific refrigerated field', () => {
+    expect(
+      validateVehicleRegistration({ ...validValues, type: 'refrigerated' }),
+    ).toHaveProperty('temperatureMin');
+  });
+
+  it('rejects invalid numeric values and missing motorcycle cargo size', () => {
+    const errors = validateVehicleRegistration({
+      ...validValues,
+      type: 'motorcycle',
+      year: '1979',
+      capacityKg: '0',
+    });
+    expect(errors.year).toContain('1980');
+    expect(errors.capacityKg).toContain('greater than zero');
+    expect(errors.cargoBoxSize).toBe('Cargo box size is required');
+  });
+
+  it('clears stale dynamic values when vehicle type changes', () => {
+    const { result } = renderHook(() => useVehicleRegistration());
+    act(() => {
+      result.current.updateField('type', 'refrigerated');
+      result.current.updateField('temperatureMin', '-10');
+      result.current.updateField('type', 'van');
+    });
+    expect(result.current.values.temperatureMin).toBe('');
+  });
+
+  it('does not call the API for invalid data', async () => {
+    const { result } = renderHook(() => useVehicleRegistration());
+    await act(async () => {
+      expect(await result.current.submit()).toBe(false);
+    });
+    expect(registerVehicle).not.toHaveBeenCalled();
+    expect(result.current.errors.plateNumber).toBeDefined();
+  });
+
+  it('submits valid data through the fleet service', async () => {
+    registerVehicle.mockResolvedValue({ id: 'vehicle-1' });
+    const { result } = renderHook(() => useVehicleRegistration());
+    act(() => {
+      for (const [field, value] of Object.entries(validValues)) {
+        result.current.updateField(
+          field as keyof VehicleRegistrationInput,
+          value as never,
+        );
+      }
+    });
+
+    await act(async () => {
+      expect(await result.current.submit()).toBe(true);
+    });
+    expect(registerVehicle).toHaveBeenCalledWith(validValues);
+    expect(result.current.isSubmitted).toBe(true);
+  });
+
+  it('surfaces API failures without marking the form submitted', async () => {
+    registerVehicle.mockRejectedValue(new Error('Plate already registered'));
+    const { result } = renderHook(() => useVehicleRegistration());
+    act(() => {
+      for (const [field, value] of Object.entries(validValues)) {
+        result.current.updateField(
+          field as keyof VehicleRegistrationInput,
+          value as never,
+        );
+      }
+    });
+
+    await act(async () => {
+      expect(await result.current.submit()).toBe(false);
+    });
+    expect(result.current.errors.submit).toBe('Plate already registered');
+    expect(result.current.isSubmitted).toBe(false);
+  });
+
+  it('resets all fields after editing', () => {
+    const { result } = renderHook(() => useVehicleRegistration());
+    act(() => result.current.updateField('plateNumber', 'ABC-123'));
+    act(() => result.current.reset());
+    expect(result.current.values.plateNumber).toBe('');
+    expect(result.current.errors).toEqual({});
+  });
+
+  it('creates and clears the selected vehicle photo preview', () => {
+    const { result } = renderHook(() => useVehicleRegistration());
+    const photo = new File(['photo'], 'vehicle.png', { type: 'image/png' });
+
+    act(() => result.current.setVehiclePhoto(photo));
+    expect(result.current.values.vehiclePhoto).toBe(photo);
+    expect(result.current.photoPreview).toContain('blob://mock-');
+
+    act(() => result.current.setVehiclePhoto(null));
+    expect(result.current.values.vehiclePhoto).toBeNull();
+    expect(result.current.photoPreview).toBeNull();
+  });
+});
diff --git a/hooks/useVehicleRegistration.ts b/hooks/useVehicleRegistration.ts
new file mode 100644
index 00000000..9683efa0
--- /dev/null
+++ b/hooks/useVehicleRegistration.ts
@@ -0,0 +1,145 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { fleetService } from '@/services/fleetService';
+import type { VehicleRegistrationInput } from '@/types/fleet';
+
+const EMPTY_FORM: VehicleRegistrationInput = {
+  plateNumber: '',
+  make: '',
+  model: '',
+  year: '',
+  type: '',
+  capacityKg: '',
+  temperatureMin: '',
+  cargoBoxSize: '',
+  registrationDocument: null,
+  vehiclePhoto: null,
+};
+
+export type VehicleRegistrationErrors = Partial<
+  Record<keyof VehicleRegistrationInput | 'submit', string>
+>;
+
+export function validateVehicleRegistration(
+  values: VehicleRegistrationInput,
+): VehicleRegistrationErrors {
+  const errors: VehicleRegistrationErrors = {};
+  const currentYear = new Date().getFullYear() + 1;
+  const year = Number(values.year);
+  const capacity = Number(values.capacityKg);
+
+  if (!values.plateNumber.trim()) errors.plateNumber = 'Plate number is required';
+  if (!values.make.trim()) errors.make = 'Make is required';
+  if (!values.model.trim()) errors.model = 'Model is required';
+  if (!values.year) errors.year = 'Year is required';
+  else if (!Number.isInteger(year) || year < 1980 || year > currentYear) {
+    errors.year = `Year must be between 1980 and ${currentYear}`;
+  }
+  if (!values.type) errors.type = 'Vehicle type is required';
+  if (!values.capacityKg) errors.capacityKg = 'Capacity is required';
+  else if (!Number.isFinite(capacity) || capacity <= 0) {
+    errors.capacityKg = 'Capacity must be greater than zero';
+  }
+  if (!values.registrationDocument) {
+    errors.registrationDocument = 'Registration document is required';
+  }
+  if (!values.vehiclePhoto) errors.vehiclePhoto = 'Vehicle photo is required';
+  if (values.type === 'refrigerated' && !values.temperatureMin) {
+    errors.temperatureMin = 'Minimum temperature is required';
+  }
+  if (values.type === 'motorcycle' && !values.cargoBoxSize.trim()) {
+    errors.cargoBoxSize = 'Cargo box size is required';
+  }
+
+  return errors;
+}
+
+export function useVehicleRegistration() {
+  const [values, setValues] = useState<VehicleRegistrationInput>(EMPTY_FORM);
+  const [errors, setErrors] = useState<VehicleRegistrationErrors>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isSubmitted, setIsSubmitted] = useState(false);
+  const [photoPreview, setPhotoPreview] = useState<string | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (photoPreview) URL.revokeObjectURL(photoPreview);
+    };
+  }, [photoPreview]);
+
+  const validationErrors = useMemo(
+    () => validateVehicleRegistration(values),
+    [values],
+  );
+  const isValid = Object.keys(validationErrors).length === 0;
+
+  const updateField = useCallback(
+    <K extends keyof VehicleRegistrationInput>(
+      field: K,
+      value: VehicleRegistrationInput[K],
+    ) => {
+      setValues((current) => {
+        const next = { ...current, [field]: value };
+        if (field === 'type') {
+          if (value !== 'refrigerated') next.temperatureMin = '';
+          if (value !== 'motorcycle') next.cargoBoxSize = '';
+        }
+        return next;
+      });
+      setErrors((current) => ({ ...current, [field]: undefined, submit: undefined }));
+      setIsSubmitted(false);
+    },
+    [],
+  );
+
+  const setVehiclePhoto = useCallback(
+    (file: File | null) => {
+      if (photoPreview) URL.revokeObjectURL(photoPreview);
+      setPhotoPreview(file ? URL.createObjectURL(file) : null);
+      updateField('vehiclePhoto', file);
+    },
+    [photoPreview, updateField],
+  );
+
+  const reset = useCallback(() => {
+    if (photoPreview) URL.revokeObjectURL(photoPreview);
+    setValues(EMPTY_FORM);
+    setErrors({});
+    setPhotoPreview(null);
+    setIsSubmitted(false);
+  }, [photoPreview]);
+
+  const submit = useCallback(async () => {
+    const nextErrors = validateVehicleRegistration(values);
+    setErrors(nextErrors);
+    if (Object.keys(nextErrors).length > 0) return false;
+
+    setIsSubmitting(true);
+    try {
+      await fleetService.registerVehicle(values);
+      setIsSubmitted(true);
+      return true;
+    } catch (error) {
+      setErrors({
+        submit: error instanceof Error ? error.message : 'Vehicle registration failed',
+      });
+      return false;
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, [values]);
+
+  return {
+    values,
+    errors,
+    isValid,
+    isSubmitting,
+    isSubmitted,
+    photoPreview,
+    updateField,
+    setVehiclePhoto,
+    submit,
+    reset,
+  };
+}
diff --git a/services/fleetService.ts b/services/fleetService.ts
index 7fe20fe7..7f0253ce 100644
--- a/services/fleetService.ts
+++ b/services/fleetService.ts
@@ -1,5 +1,10 @@
 import axios from 'axios';
-import type { Driver, FleetResponse } from '@/types/fleet';
+import type {
+  Driver,
+  FleetResponse,
+  RegisteredVehicle,
+  VehicleRegistrationInput,
+} from '@/types/fleet';
 
 const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? '';
 
@@ -23,4 +28,36 @@ export const fleetService = {
     );
     return data;
   },
+
+  async registerVehicle(
+    input: VehicleRegistrationInput,
+  ): Promise<RegisteredVehicle> {
+    const payload = new FormData();
+    payload.append('plateNumber', input.plateNumber.trim());
+    payload.append('make', input.make.trim());
+    payload.append('model', input.model.trim());
+    payload.append('year', input.year);
+    payload.append('type', input.type);
+    payload.append('capacityKg', input.capacityKg);
+
+    if (input.type === 'refrigerated') {
+      payload.append('temperatureMin', input.temperatureMin);
+    }
+    if (input.type === 'motorcycle') {
+      payload.append('cargoBoxSize', input.cargoBoxSize.trim());
+    }
+    if (input.registrationDocument) {
+      payload.append('registrationDocument', input.registrationDocument);
+    }
+    if (input.vehiclePhoto) {
+      payload.append('vehiclePhoto', input.vehiclePhoto);
+    }
+
+    const { data } = await axios.post<RegisteredVehicle>(
+      `${API_BASE_URL}/fleet/vehicles`,
+      payload,
+      { headers: { 'Content-Type': 'multipart/form-data' } },
+    );
+    return data;
+  },
 };
diff --git a/types/fleet.ts b/types/fleet.ts
index 70d661b6..ea590cb5 100644
--- a/types/fleet.ts
+++ b/types/fleet.ts
@@ -74,3 +74,28 @@ export interface AssignmentResult {
   success: boolean;
   error?: string;
 }
+
+export type VehicleType = 'van' | 'truck' | 'refrigerated' | 'motorcycle';
+
+export interface VehicleRegistrationInput {
+  plateNumber: string;
+  make: string;
+  model: string;
+  year: string;
+  type: VehicleType | '';
+  capacityKg: string;
+  temperatureMin: string;
+  cargoBoxSize: string;
+  registrationDocument: File | null;
+  vehiclePhoto: File | null;
+}
+
+export interface RegisteredVehicle {
+  id: string;
+  plateNumber: string;
+  make: string;
+  model: string;
+  year: number;
+  type: VehicleType;
+  capacityKg: number;
+}

From 8d127c73a9964eb99aaf0b898a820443493e8abe Mon Sep 17 00:00:00 2001
From: Kaosara18 <hallab419@gmail.com>
Date: Sun, 18 Oct 2026 17:25:46 +0100
Subject: [PATCH 3/4] enhance(deliveries): integrate signature proof bundles

---
 .../deliveries/components/ProofUpload.tsx     | 100 ++++++++++-
 .../__tests__/ProofUploadSignature.test.tsx   | 112 ++++++++++++
 hooks/__tests__/useProofBundle.test.ts        |  79 +++++++++
 hooks/useProofUpload.ts                       | 160 +++++++++++++++---
 hooks/useToast.ts                             |  25 ++-
 services/proofService.ts                      |  25 ++-
 6 files changed, 458 insertions(+), 43 deletions(-)
 create mode 100644 features/deliveries/components/__tests__/ProofUploadSignature.test.tsx
 create mode 100644 hooks/__tests__/useProofBundle.test.ts

diff --git a/features/deliveries/components/ProofUpload.tsx b/features/deliveries/components/ProofUpload.tsx
index 1f43a1d1..f55f08b0 100644
--- a/features/deliveries/components/ProofUpload.tsx
+++ b/features/deliveries/components/ProofUpload.tsx
@@ -2,7 +2,8 @@
 
 import React, { useRef, useState, useEffect } from 'react';
 import { useProofUpload } from '@/hooks/useProofUpload';
-import { Camera, Upload, CheckCircle, AlertCircle, Loader } from 'lucide-react';
+import { Camera, Upload, CheckCircle, AlertCircle, Loader, PenLine } from 'lucide-react';
+import { SignatureCanvas } from '@/components/deliveries/SignatureCanvas';
 import clsx from 'clsx';
 
 interface ProofUploadProps {
@@ -23,10 +24,17 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
     isCompressing,
     uploadedProofs,
     errors,
-    handleFileCapture,
-    handleCameraCapture,
     clearUploadedProofs,
     removeProof,
+    stagedPhoto,
+    photoPreviewUrl,
+    signatureDataUrl,
+    canSubmitBundle,
+    stagePhoto,
+    stageCameraCapture,
+    setSignature,
+    submitProofBundle,
+    resetBundle,
   } = useProofUpload({ deliveryId, maxSizeMB });
 
   const videoRef = useRef<HTMLVideoElement>(null);
@@ -34,6 +42,7 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [isCameraActive, setIsCameraActive] = useState(false);
   const [cameraError, setCameraError] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState<'photo' | 'signature'>('photo');
 
   // Initialize camera
   const startCamera = async () => {
@@ -76,7 +85,7 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
         canvasRef.current.width = videoRef.current.videoWidth;
         canvasRef.current.height = videoRef.current.videoHeight;
         context.drawImage(videoRef.current, 0, 0);
-        await handleCameraCapture(canvasRef.current);
+        await stageCameraCapture(canvasRef.current);
       }
     }
   };
@@ -87,7 +96,7 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
   ) => {
     const file = event.target.files?.[0];
     if (file) {
-      handleFileCapture(file);
+      stagePhoto(file);
     }
     // Reset input
     if (fileInputRef.current) {
@@ -106,7 +115,7 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
     event.stopPropagation();
     const file = event.dataTransfer.files?.[0];
     if (file && file.type.startsWith('image/')) {
-      handleFileCapture(file);
+      stagePhoto(file);
     }
   };
 
@@ -119,6 +128,34 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
 
   return (
     <div className="space-y-6">
+      <div className="grid grid-cols-2 border-b border-gray-200" role="tablist">
+        <button
+          type="button"
+          role="tab"
+          aria-selected={activeTab === 'photo'}
+          onClick={() => setActiveTab('photo')}
+          className={clsx('flex items-center justify-center gap-2 border-b-2 px-4 py-3 text-sm font-medium', {
+            'border-blue-600 text-blue-700': activeTab === 'photo',
+            'border-transparent text-gray-500': activeTab !== 'photo',
+          })}
+        >
+          <Camera className="h-4 w-4" /> Photo
+        </button>
+        <button
+          type="button"
+          role="tab"
+          aria-selected={activeTab === 'signature'}
+          onClick={() => setActiveTab('signature')}
+          className={clsx('flex items-center justify-center gap-2 border-b-2 px-4 py-3 text-sm font-medium', {
+            'border-blue-600 text-blue-700': activeTab === 'signature',
+            'border-transparent text-gray-500': activeTab !== 'signature',
+          })}
+        >
+          <PenLine className="h-4 w-4" /> Signature
+        </button>
+      </div>
+
+      <div hidden={activeTab !== 'photo'} className="space-y-6">
       {/* Camera Section */}
       <div className="border rounded-lg overflow-hidden bg-slate-50">
         {isCameraActive ? (
@@ -172,6 +209,7 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
       >
         <input
           ref={fileInputRef}
+          aria-label="Delivery photo file"
           type="file"
           accept="image/*"
           onChange={handleFileInputChange}
@@ -242,6 +280,56 @@ export function ProofUpload({ deliveryId, maxSizeMB = 5 }: ProofUploadProps) {
           )}
         </div>
       )}
+      </div>
+
+      <div hidden={activeTab !== 'signature'}>
+        <SignatureCanvas
+          onSave={(dataUrl) => setSignature(dataUrl)}
+          disabled={isUploading}
+        />
+      </div>
+
+      {(photoPreviewUrl || signatureDataUrl) && (
+        <div className="grid gap-4 sm:grid-cols-2" aria-label="Delivery proof preview">
+          <div className="rounded-lg border border-gray-200 p-3">
+            <p className="mb-2 text-sm font-medium text-gray-800">Delivery photo</p>
+            {photoPreviewUrl ? (
+              // eslint-disable-next-line @next/next/no-img-element
+              <img src={photoPreviewUrl} alt="Delivery proof preview" className="h-36 w-full rounded object-cover" />
+            ) : (
+              <p className="text-sm text-amber-700">Add a photo before submitting.</p>
+            )}
+          </div>
+          <div className="rounded-lg border border-gray-200 p-3">
+            <p className="mb-2 text-sm font-medium text-gray-800">Recipient signature</p>
+            {signatureDataUrl ? (
+              // eslint-disable-next-line @next/next/no-img-element
+              <img src={signatureDataUrl} alt="Recipient signature preview" className="h-36 w-full rounded object-contain" />
+            ) : (
+              <p className="text-sm text-gray-500">Signature not captured.</p>
+            )}
+          </div>
+        </div>
+      )}
+
+      <div className="flex gap-3">
+        <button
+          type="button"
+          onClick={() => void submitProofBundle()}
+          disabled={!canSubmitBundle}
+          className="flex-1 rounded-lg bg-green-600 px-4 py-2 font-medium text-white disabled:cursor-not-allowed disabled:bg-gray-300"
+        >
+          {isUploading ? 'Submitting proof...' : 'Submit delivery proof'}
+        </button>
+        <button
+          type="button"
+          onClick={resetBundle}
+          disabled={!stagedPhoto && !signatureDataUrl}
+          className="rounded-lg border border-gray-300 px-4 py-2 font-medium text-gray-700 disabled:cursor-not-allowed disabled:text-gray-300"
+        >
+          Reset
+        </button>
+      </div>
 
       {/* Uploaded Proofs */}
       {uploadedProofs.length > 0 && (
diff --git a/features/deliveries/components/__tests__/ProofUploadSignature.test.tsx b/features/deliveries/components/__tests__/ProofUploadSignature.test.tsx
new file mode 100644
index 00000000..16d075df
--- /dev/null
+++ b/features/deliveries/components/__tests__/ProofUploadSignature.test.tsx
@@ -0,0 +1,112 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ProofUpload } from '@/features/deliveries/components/ProofUpload';
+import { useProofUpload } from '@/hooks/useProofUpload';
+
+jest.mock('@/hooks/useProofUpload');
+jest.mock('@/components/deliveries/SignatureCanvas', () => ({
+  SignatureCanvas: ({ onSave }: { onSave: (_value: string) => void }) => (
+    <button type="button" onClick={() => onSave('data:image/png;base64,signature')}>
+      Save test signature
+    </button>
+  ),
+}));
+
+const mockedUseProofUpload = useProofUpload as jest.MockedFunction<typeof useProofUpload>;
+
+function mockHook(overrides: Partial<ReturnType<typeof useProofUpload>> = {}) {
+  mockedUseProofUpload.mockReturnValue({
+    uploadProgress: 0,
+    compressionProgress: 0,
+    isUploading: false,
+    isCompressing: false,
+    uploadedProofs: [],
+    errors: [],
+    stagedPhoto: null,
+    photoPreviewUrl: null,
+    signatureDataUrl: null,
+    canSubmitBundle: false,
+    handleFileCapture: jest.fn(),
+    handleCameraCapture: jest.fn(),
+    clearUploadedProofs: jest.fn(),
+    removeProof: jest.fn(),
+    stagePhoto: jest.fn(),
+    stageCameraCapture: jest.fn(),
+    setSignature: jest.fn(),
+    submitProofBundle: jest.fn().mockResolvedValue(true),
+    resetBundle: jest.fn(),
+    ...overrides,
+  });
+}
+
+describe('ProofUpload signature integration', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockHook();
+  });
+
+  it('provides photo and signature tabs', () => {
+    render(<ProofUpload deliveryId="delivery-1" />);
+    expect(screen.getByRole('tab', { name: 'Photo' })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('tab', { name: 'Signature' })).toBeInTheDocument();
+  });
+
+  it('saves a captured signature through the hook', async () => {
+    const setSignature = jest.fn();
+    mockHook({ setSignature });
+    const user = userEvent.setup();
+    render(<ProofUpload deliveryId="delivery-1" />);
+
+    await user.click(screen.getByRole('tab', { name: 'Signature' }));
+    await user.click(screen.getByRole('button', { name: 'Save test signature' }));
+
+    expect(setSignature).toHaveBeenCalledWith('data:image/png;base64,signature');
+  });
+
+  it('stages a selected delivery photo', () => {
+    const stagePhoto = jest.fn();
+    mockHook({ stagePhoto });
+    render(<ProofUpload deliveryId="delivery-1" />);
+    const photo = new File(['photo'], 'delivery.png', { type: 'image/png' });
+
+    fireEvent.change(screen.getByLabelText('Delivery photo file'), {
+      target: { files: [photo] },
+    });
+
+    expect(stagePhoto).toHaveBeenCalledWith(photo);
+  });
+
+  it('disables submission until photo and signature exist', () => {
+    render(<ProofUpload deliveryId="delivery-1" />);
+    expect(screen.getByRole('button', { name: 'Submit delivery proof' })).toBeDisabled();
+  });
+
+  it('renders both previews and submits the bundle', async () => {
+    const submitProofBundle = jest.fn().mockResolvedValue(true);
+    mockHook({
+      stagedPhoto: new File(['photo'], 'delivery.png', { type: 'image/png' }),
+      photoPreviewUrl: 'blob:delivery-photo',
+      signatureDataUrl: 'data:image/png;base64,signature',
+      canSubmitBundle: true,
+      submitProofBundle,
+    });
+    const user = userEvent.setup();
+    render(<ProofUpload deliveryId="delivery-1" />);
+
+    expect(screen.getByAltText('Delivery proof preview')).toHaveAttribute('src', 'blob:delivery-photo');
+    expect(screen.getByAltText('Recipient signature preview')).toHaveAttribute(
+      'src',
+      'data:image/png;base64,signature',
+    );
+    await user.click(screen.getByRole('button', { name: 'Submit delivery proof' }));
+    expect(submitProofBundle).toHaveBeenCalledTimes(1);
+  });
+
+  it('handles a signature-only draft with a clear photo prompt', () => {
+    mockHook({ signatureDataUrl: 'data:image/png;base64,signature' });
+    render(<ProofUpload deliveryId="delivery-1" />);
+
+    expect(screen.getByText('Add a photo before submitting.')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Submit delivery proof' })).toBeDisabled();
+  });
+});
diff --git a/hooks/__tests__/useProofBundle.test.ts b/hooks/__tests__/useProofBundle.test.ts
new file mode 100644
index 00000000..f08c9191
--- /dev/null
+++ b/hooks/__tests__/useProofBundle.test.ts
@@ -0,0 +1,79 @@
+import { act, renderHook } from '@testing-library/react';
+import { useProofUpload } from '@/hooks/useProofUpload';
+import { proofService } from '@/services/proofService';
+
+jest.mock('@/services/proofService', () => ({
+  proofService: {
+    uploadProofBundle: jest.fn(),
+    compressImage: jest.fn(),
+    uploadProof: jest.fn(),
+  },
+}));
+jest.mock('@/hooks/useToast', () => ({
+  useToast: () => ({
+    error: jest.fn(),
+    success: jest.fn(),
+    toast: jest.fn(),
+  }),
+}));
+
+const uploadProofBundle = proofService.uploadProofBundle as jest.Mock;
+
+describe('useProofUpload delivery bundle', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('keeps a signature-only proof disabled and explains the missing photo', async () => {
+    const { result } = renderHook(() => useProofUpload({ deliveryId: 'delivery-1' }));
+    act(() => result.current.setSignature('data:image/png;base64,signature'));
+
+    await act(async () => {
+      expect(await result.current.submitProofBundle()).toBe(false);
+    });
+
+    expect(result.current.canSubmitBundle).toBe(false);
+    expect(result.current.errors).toEqual(['Add a delivery photo to submit this signature.']);
+  });
+
+  it('uploads the photo and signature in one API payload', async () => {
+    uploadProofBundle.mockResolvedValue({
+      success: true,
+      message: 'Uploaded',
+      data: {
+        signatureDataUrl: 'data:image/png;base64,signature',
+        photo: {
+          id: 'proof-1',
+          deliveryId: 'delivery-1',
+          filename: 'delivery.png',
+          fileSize: 5,
+          originalSize: 5,
+          isCompressed: false,
+          uploadedAt: '2026-10-18T00:00:00.000Z',
+          status: 'pending',
+        },
+      },
+    });
+    const { result } = renderHook(() => useProofUpload({ deliveryId: 'delivery-1' }));
+    const photo = new File(['photo'], 'delivery.png', { type: 'image/png' });
+    act(() => {
+      result.current.stagePhoto(photo);
+      result.current.setSignature('data:image/png;base64,signature');
+    });
+
+    await act(async () => {
+      expect(await result.current.submitProofBundle()).toBe(true);
+    });
+
+    const formData = uploadProofBundle.mock.calls[0][0] as FormData;
+    expect(formData.get('photo')).toBe(photo);
+    expect(formData.get('signatureDataUrl')).toBe('data:image/png;base64,signature');
+    expect(uploadProofBundle).toHaveBeenCalledWith(
+      expect.any(FormData),
+      'delivery-1',
+      expect.any(Function),
+    );
+    expect(result.current.uploadedProofs[0].status).toBe('completed');
+    expect(result.current.signatureDataUrl).toBeNull();
+  });
+});
diff --git a/hooks/useProofUpload.ts b/hooks/useProofUpload.ts
index 6f122202..21d8bc11 100644
--- a/hooks/useProofUpload.ts
+++ b/hooks/useProofUpload.ts
@@ -1,6 +1,6 @@
 'use client';
 
-import { useState, useCallback } from 'react';
+import { useState, useCallback, useEffect } from 'react';
 import { proofService, CompressionOptions } from '@/services/proofService';
 import { useToast } from './useToast';
 
@@ -27,6 +27,10 @@ interface UseProofUploadReturn {
   isCompressing: boolean;
   uploadedProofs: UploadedProof[];
   errors: string[];
+  stagedPhoto: File | null;
+  photoPreviewUrl: string | null;
+  signatureDataUrl: string | null;
+  canSubmitBundle: boolean;
 
   handleFileCapture: (_file: File) => Promise<void>;
 
@@ -34,6 +38,11 @@ interface UseProofUploadReturn {
   clearUploadedProofs: () => void;
 
   removeProof: (_filename: string) => void;
+  stagePhoto: (_file: File) => void;
+  stageCameraCapture: (_canvas: HTMLCanvasElement) => Promise<void>;
+  setSignature: (_signatureDataUrl: string | null) => void;
+  submitProofBundle: () => Promise<boolean>;
+  resetBundle: () => void;
 }
 
 /**
@@ -51,21 +60,128 @@ export function useProofUpload({
   const [isCompressing, setIsCompressing] = useState(false);
   const [uploadedProofs, setUploadedProofs] = useState<UploadedProof[]>([]);
   const [errors, setErrors] = useState<string[]>([]);
+  const [stagedPhoto, setStagedPhoto] = useState<File | null>(null);
+  const [photoPreviewUrl, setPhotoPreviewUrl] = useState<string | null>(null);
+  const [signatureDataUrl, setSignatureDataUrl] = useState<string | null>(null);
   const {
     error: toastError,
     success: toastSuccess,
-    loading: toastLoading,
-    info: toastInfo,
-    toast,
   } = useToast();
 
+  useEffect(() => {
+    return () => {
+      if (photoPreviewUrl) URL.revokeObjectURL(photoPreviewUrl);
+    };
+  }, [photoPreviewUrl]);
+
+  const stagePhoto = useCallback(
+    (file: File) => {
+      if (!file.type.startsWith('image/')) {
+        const message = 'Please select an image file';
+        setErrors([message]);
+        toastError?.(message);
+        return;
+      }
+      if (photoPreviewUrl) URL.revokeObjectURL(photoPreviewUrl);
+      setStagedPhoto(file);
+      setPhotoPreviewUrl(URL.createObjectURL(file));
+      setErrors([]);
+    },
+    [photoPreviewUrl, toastError]
+  );
+
+  const stageCameraCapture = useCallback(
+    async (canvas: HTMLCanvasElement) => {
+      const blob = await new Promise<Blob | null>((resolve) => {
+        canvas.toBlob(resolve, 'image/jpeg', 0.95);
+      });
+      if (!blob) {
+        setErrors(['Failed to capture image from camera']);
+        return;
+      }
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      stagePhoto(
+        new File([blob], `proof-${timestamp}.jpg`, { type: 'image/jpeg' })
+      );
+    },
+    [stagePhoto]
+  );
+
+  const setSignature = useCallback((value: string | null) => {
+    setSignatureDataUrl(value);
+    setErrors([]);
+  }, []);
+
+  const resetBundle = useCallback(() => {
+    if (photoPreviewUrl) URL.revokeObjectURL(photoPreviewUrl);
+    setStagedPhoto(null);
+    setPhotoPreviewUrl(null);
+    setSignatureDataUrl(null);
+    setErrors([]);
+  }, [photoPreviewUrl]);
+
+  const submitProofBundle = useCallback(async () => {
+    if (!stagedPhoto && signatureDataUrl) {
+      setErrors(['Add a delivery photo to submit this signature.']);
+      return false;
+    }
+    if (!stagedPhoto || !signatureDataUrl) {
+      setErrors(['A delivery photo and recipient signature are required.']);
+      return false;
+    }
+
+    setIsUploading(true);
+    setUploadProgress(0);
+    setErrors([]);
+    try {
+      const formData = new FormData();
+      formData.append('photo', stagedPhoto);
+      formData.append('signatureDataUrl', signatureDataUrl);
+      const response = await proofService.uploadProofBundle(
+        formData,
+        deliveryId,
+        ({ loaded, total }) => {
+          if (total) setUploadProgress(Math.round((loaded / total) * 100));
+        }
+      );
+      if (!response.success || !response.data) {
+        throw new Error(response.message || 'Proof bundle upload failed');
+      }
+
+      setUploadedProofs((current) => [
+        ...current,
+        {
+          id: response.data?.photo.id,
+          filename: response.data?.photo.filename ?? stagedPhoto.name,
+          fileSize: response.data?.photo.fileSize ?? stagedPhoto.size,
+          originalSize: response.data?.photo.originalSize ?? stagedPhoto.size,
+          isCompressed: response.data?.photo.isCompressed ?? false,
+          status: 'completed',
+          uploadedAt: response.data?.photo.uploadedAt,
+          compressionProgress: 100,
+        },
+      ]);
+      resetBundle();
+      toastSuccess?.('Delivery proof submitted');
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Proof bundle upload failed';
+      setErrors([message]);
+      toastError?.(message);
+      return false;
+    } finally {
+      setIsUploading(false);
+      setUploadProgress(0);
+    }
+  }, [deliveryId, resetBundle, signatureDataUrl, stagedPhoto, toastError, toastSuccess]);
+
   const handleFileCapture = useCallback(
     async (file: File) => {
       // Validate file type
       if (!file.type.startsWith('image/')) {
         const errorMsg = 'Please select an image file';
         setErrors((prev) => [...prev, errorMsg]);
-        toastError(errorMsg);
+        toastError?.(errorMsg);
         return;
       }
 
@@ -148,11 +264,10 @@ export function useProofUpload({
             ? ` (compressed from ${(originalSize / (1024 * 1024)).toFixed(2)}MB to ${(compressedFile.size / (1024 * 1024)).toFixed(2)}MB)`
             : '';
 
-          toast({
-            title: 'Upload Successful',
-            description: `Proof uploaded successfully${compressionMsg}`,
-            variant: 'default',
-          });
+          toastSuccess?.(
+            'Upload Successful',
+            `Proof uploaded successfully${compressionMsg}`
+          );
         } else {
           throw new Error(response.message || 'Upload failed');
         }
@@ -169,11 +284,7 @@ export function useProofUpload({
           )
         );
 
-        toast({
-          title: 'Upload Failed',
-          description: errorMessage,
-          variant: 'destructive',
-        });
+        toastError?.('Upload Failed', errorMessage);
       } finally {
         setIsUploading(false);
         setIsCompressing(false);
@@ -181,7 +292,7 @@ export function useProofUpload({
         setCompressionProgress(0);
       }
     },
-    [deliveryId, maxSizeMB, toast]
+    [deliveryId, maxSizeMB, toastError, toastSuccess]
   );
 
   const handleCameraCapture = useCallback(
@@ -207,14 +318,10 @@ export function useProofUpload({
       } catch (error: any) {
         const errorMessage = error?.message || 'Failed to capture from camera';
         setErrors((prev) => [...prev, errorMessage]);
-        toast({
-          title: 'Camera Capture Failed',
-          description: errorMessage,
-          variant: 'destructive',
-        });
+        toastError?.('Camera Capture Failed', errorMessage);
       }
     },
-    [handleFileCapture, toast]
+    [handleFileCapture, toastError]
   );
 
   const clearUploadedProofs = useCallback(() => {
@@ -233,9 +340,18 @@ export function useProofUpload({
     isCompressing,
     uploadedProofs,
     errors,
+    stagedPhoto,
+    photoPreviewUrl,
+    signatureDataUrl,
+    canSubmitBundle: Boolean(stagedPhoto && signatureDataUrl) && !isUploading,
     handleFileCapture,
     handleCameraCapture,
     clearUploadedProofs,
     removeProof,
+    stagePhoto,
+    stageCameraCapture,
+    setSignature,
+    submitProofBundle,
+    resetBundle,
   };
 }
diff --git a/hooks/useToast.ts b/hooks/useToast.ts
index 0e57b985..a0b767ac 100644
--- a/hooks/useToast.ts
+++ b/hooks/useToast.ts
@@ -10,11 +10,11 @@ import { useCallback, useEffect, useState } from 'react';
 import { toastService, ToastConfig, ToastMessage } from '@/lib/toast';
 
 export interface UseToastReturn {
-  success: (message: string, description?: string, duration?: number) => void;
-  error: (message: string, description?: string, duration?: number) => void;
-  info: (message: string, description?: string, duration?: number) => void;
-  loading: (message: string, description?: string) => void;
-  toast: (config: ToastConfig) => void;
+  success: (_message: string, _description?: string, _duration?: number) => void;
+  error: (_message: string, _description?: string, _duration?: number) => void;
+  info: (_message: string, _description?: string, _duration?: number) => void;
+  loading: (_message: string, _description?: string) => void;
+  toast: (_config: ToastConfig) => void;
   isLoading: boolean;
   notifications: ToastMessage[];
   fetchNotifications: () => Promise<void>;
@@ -50,8 +50,8 @@ export function useToast(): UseToastReturn {
           }
         });
       }
-    } catch (err: any) {
-      console.error('Failed to fetch notifications:', err.message);
+    } catch {
+      setNotifications([]);
     } finally {
       setIsLoading(false);
     }
@@ -104,21 +104,20 @@ export function useToast(): UseToastReturn {
   }, []);
 
   const showToast = useCallback((config: ToastConfig) => {
-    const { title, description, variant = 'default', duration } = config;
+    const { message, description, variant, duration } = config;
     switch (variant) {
-      case 'destructive':
       case 'error':
-        toastService.error(title, description, duration);
+        toastService.error(message, description, duration);
         break;
       case 'loading':
-        toastService.loading(title, description);
+        toastService.loading(message, description);
         break;
       case 'success':
-        toastService.success(title, description, duration);
+        toastService.success(message, description, duration);
         break;
       case 'info':
       default:
-        toastService.info(title, description, duration);
+        toastService.info(message, description, duration);
         break;
     }
   }, []);
diff --git a/services/proofService.ts b/services/proofService.ts
index ac4d572a..ddea9184 100644
--- a/services/proofService.ts
+++ b/services/proofService.ts
@@ -14,6 +14,11 @@ export interface ProofDocument {
   status: 'pending' | 'verified' | 'rejected';
 }
 
+export interface DeliveryProofBundle {
+  photo: ProofDocument;
+  signatureDataUrl: string;
+}
+
 export interface ApiResponse<T> {
   success: boolean;
   message: string;
@@ -24,7 +29,7 @@ export interface CompressionOptions {
   maxSizeMB?: number;
   maxWidthOrHeight?: number;
   useWebWorker?: boolean;
-  onProgress?: (progress: number) => void;
+  onProgress?: (_progress: number) => void;
 }
 
 /**
@@ -100,7 +105,7 @@ export const proofService = {
   async uploadProof(
     formData: FormData,
     deliveryId: string,
-    onUploadProgress?: (progressEvent: any) => void
+    onUploadProgress?: (_progressEvent: any) => void
   ): Promise<ApiResponse<ProofDocument>> {
     try {
       const { data } = await axios.post<ApiResponse<ProofDocument>>(
@@ -119,6 +124,22 @@ export const proofService = {
     }
   },
 
+  async uploadProofBundle(
+    formData: FormData,
+    deliveryId: string,
+    onUploadProgress?: (_progressEvent: { loaded: number; total?: number }) => void
+  ): Promise<ApiResponse<DeliveryProofBundle>> {
+    const { data } = await axios.post<ApiResponse<DeliveryProofBundle>>(
+      `${API_BASE_URL}/api/deliveries/${deliveryId}/proof-bundle`,
+      formData,
+      {
+        headers: { 'Content-Type': 'multipart/form-data' },
+        onUploadProgress,
+      }
+    );
+    return data;
+  },
+
   /**
    * Retrieve proof documents for a delivery
    * @param deliveryId - ID of the delivery

From f8427cf567173fedd84ecf541576f62b5e88c83d Mon Sep 17 00:00:00 2001
From: Kaosara18 <hallab419@gmail.com>
Date: Sun, 18 Oct 2026 17:26:10 +0100
Subject: [PATCH 4/4] enhance(mobile): add offline QR handoff sync

---
 features/shipments/components/HandoffQR.tsx   |  79 +++++++++++-
 .../__tests__/HandoffQROffline.test.tsx       |  75 +++++++++++
 hooks/useHandoffQR.ts                         |  32 ++---
 hooks/useOfflineHandoffSync.ts                | 103 +++++++++++++++
 .../__tests__/offlineHandoffService.test.ts   |  65 ++++++++++
 services/offlineHandoffService.ts             | 117 ++++++++++++++++++
 6 files changed, 443 insertions(+), 28 deletions(-)
 create mode 100644 features/shipments/components/__tests__/HandoffQROffline.test.tsx
 create mode 100644 hooks/useOfflineHandoffSync.ts
 create mode 100644 services/__tests__/offlineHandoffService.test.ts
 create mode 100644 services/offlineHandoffService.ts

diff --git a/features/shipments/components/HandoffQR.tsx b/features/shipments/components/HandoffQR.tsx
index 49d5a707..062e8732 100644
--- a/features/shipments/components/HandoffQR.tsx
+++ b/features/shipments/components/HandoffQR.tsx
@@ -8,6 +8,8 @@ import {
 } from '../../../hooks/useHandoffQR';
 import { HandoffQRData } from '../../../types/shipment';
 import clsx from 'clsx';
+import { CloudOff, RefreshCw, ScanLine } from 'lucide-react';
+import { useOfflineHandoffSync } from '@/hooks/useOfflineHandoffSync';
 
 interface HandoffQRProps {
   deliveryId: string;
@@ -16,8 +18,10 @@ interface HandoffQRProps {
   size?: number;
   includeLabel?: boolean;
   autoGenerate?: boolean;
-  onQRGenerated?: (qrData: HandoffQRData) => void;
-  onError?: (error: Error) => void;
+  onQRGenerated?: (_qrData: HandoffQRData) => void;
+  onError?: (_error: Error) => void;
+  scannerMode?: boolean;
+  onScanProcessed?: (_state: 'synced' | 'pending' | 'failed') => void;
 }
 
 /**
@@ -43,19 +47,27 @@ export function HandoffQR({
   autoGenerate = false,
   onQRGenerated,
   onError,
+  scannerMode = false,
+  onScanProcessed,
 }: HandoffQRProps) {
   const [hasTriedGenerate, setHasTriedGenerate] = useState(false);
-  const qrQuery = useHandoffQR(deliveryId, !autoGenerate || hasTriedGenerate);
+  const [scanToken, setScanToken] = useState('');
+  const qrQuery = useHandoffQR(
+    deliveryId,
+    !scannerMode && (!autoGenerate || hasTriedGenerate),
+  );
   const generateMutation = useGenerateHandoffQR();
+  const { isOnline, syncState, pendingCount, processScan, retry } =
+    useOfflineHandoffSync(scannerMode);
 
   // Auto-generate QR on first load if requested
   useEffect(() => {
-    if (autoGenerate && !hasTriedGenerate && deliveryId && driverId) {
+    if (!scannerMode && autoGenerate && !hasTriedGenerate && deliveryId && driverId) {
       // eslint-disable-next-line react-hooks/set-state-in-effect
       setHasTriedGenerate(true);
       generateMutation.mutate(deliveryId);
     }
-  }, [autoGenerate, hasTriedGenerate, deliveryId, driverId, generateMutation]);
+  }, [scannerMode, autoGenerate, hasTriedGenerate, deliveryId, driverId, generateMutation]);
 
   // Call onQRGenerated callback when QR data is loaded
   useEffect(() => {
@@ -90,6 +102,63 @@ export function HandoffQR({
     return `${seconds}s`;
   };
 
+  if (scannerMode) {
+    const statusLabel = {
+      synced: 'All handoffs synced',
+      pending: `${pendingCount} handoff${pendingCount === 1 ? '' : 's'} pending sync`,
+      failed: 'Sync failed. A retry is scheduled.',
+    }[syncState];
+
+    return (
+      <div className={clsx('relative space-y-4 rounded-lg border border-gray-200 bg-white p-4', className)}>
+        {!isOnline && (
+          <div className="absolute inset-x-0 top-0 flex items-center justify-center gap-2 bg-gray-900/85 px-3 py-2 text-sm font-semibold text-white" data-testid="offline-watermark">
+            <CloudOff className="h-4 w-4" /> Offline mode
+          </div>
+        )}
+        <div className={clsx({ 'pt-10': !isOnline })}>
+          <label className="text-sm font-medium text-gray-800" htmlFor="handoff-scan-token">
+            Scanned handoff token
+          </label>
+          <input
+            id="handoff-scan-token"
+            value={scanToken}
+            onChange={(event) => setScanToken(event.target.value)}
+            className="mt-2 w-full rounded-md border border-gray-300 px-3 py-2 text-sm"
+            placeholder="Scan or enter token"
+          />
+        </div>
+        <button
+          type="button"
+          disabled={!scanToken.trim()}
+          onClick={async () => {
+            const state = await processScan(deliveryId, scanToken.trim());
+            setScanToken('');
+            onScanProcessed?.(state);
+          }}
+          className="inline-flex w-full items-center justify-center gap-2 rounded-md bg-blue-600 px-4 py-2 text-sm font-semibold text-white disabled:bg-gray-300"
+        >
+          <ScanLine className="h-4 w-4" /> Confirm handoff scan
+        </button>
+        <div
+          role="status"
+          className={clsx('flex items-center justify-between rounded-md px-3 py-2 text-sm', {
+            'bg-green-50 text-green-700': syncState === 'synced',
+            'bg-amber-50 text-amber-800': syncState === 'pending',
+            'bg-red-50 text-red-700': syncState === 'failed',
+          })}
+        >
+          <span>{statusLabel}</span>
+          {syncState !== 'synced' && isOnline && (
+            <button type="button" aria-label="Retry handoff sync" onClick={() => void retry()}>
+              <RefreshCw className="h-4 w-4" />
+            </button>
+          )}
+        </div>
+      </div>
+    );
+  }
+
   // Render loading state
   if (qrQuery.isLoading || generateMutation.isPending) {
     return (
diff --git a/features/shipments/components/__tests__/HandoffQROffline.test.tsx b/features/shipments/components/__tests__/HandoffQROffline.test.tsx
new file mode 100644
index 00000000..f59afb66
--- /dev/null
+++ b/features/shipments/components/__tests__/HandoffQROffline.test.tsx
@@ -0,0 +1,75 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { HandoffQR } from '@/features/shipments/components/HandoffQR';
+import { useOfflineHandoffSync } from '@/hooks/useOfflineHandoffSync';
+
+jest.mock('@/hooks/useOfflineHandoffSync');
+jest.mock('@/hooks/useHandoffQR', () => ({
+  useHandoffQR: () => ({ isLoading: false, data: null, error: null }),
+  useGenerateHandoffQR: () => ({
+    mutate: jest.fn(),
+    isPending: false,
+    isError: false,
+    error: null,
+  }),
+}));
+
+const mockedUseOfflineSync = useOfflineHandoffSync as jest.MockedFunction<
+  typeof useOfflineHandoffSync
+>;
+
+describe('HandoffQR offline scanner', () => {
+  const processScan = jest.fn();
+  const retry = jest.fn();
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockedUseOfflineSync.mockReturnValue({
+      isOnline: false,
+      syncState: 'pending',
+      pendingCount: 1,
+      processScan,
+      retry,
+    });
+  });
+
+  it('shows an offline watermark and pending sync banner', () => {
+    render(<HandoffQR deliveryId="delivery-1" scannerMode />);
+    expect(screen.getByTestId('offline-watermark')).toHaveTextContent('Offline mode');
+    expect(screen.getByRole('status')).toHaveTextContent('1 handoff pending sync');
+  });
+
+  it('queues the scanned token through the sync hook', async () => {
+    processScan.mockResolvedValue('pending');
+    const onScanProcessed = jest.fn();
+    const user = userEvent.setup();
+    render(
+      <HandoffQR
+        deliveryId="delivery-1"
+        scannerMode
+        onScanProcessed={onScanProcessed}
+      />,
+    );
+
+    await user.type(screen.getByLabelText('Scanned handoff token'), 'token-1');
+    await user.click(screen.getByRole('button', { name: 'Confirm handoff scan' }));
+
+    expect(processScan).toHaveBeenCalledWith('delivery-1', 'token-1');
+    expect(onScanProcessed).toHaveBeenCalledWith('pending');
+  });
+
+  it('offers a manual retry after a failed online sync', async () => {
+    mockedUseOfflineSync.mockReturnValue({
+      isOnline: true,
+      syncState: 'failed',
+      pendingCount: 1,
+      processScan,
+      retry,
+    });
+    const user = userEvent.setup();
+    render(<HandoffQR deliveryId="delivery-1" scannerMode />);
+
+    await user.click(screen.getByRole('button', { name: 'Retry handoff sync' }));
+    expect(retry).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/hooks/useHandoffQR.ts b/hooks/useHandoffQR.ts
index 5f2f3563..95626bba 100644
--- a/hooks/useHandoffQR.ts
+++ b/hooks/useHandoffQR.ts
@@ -1,6 +1,6 @@
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 import { shipmentHandoffService } from '../services/shipmentHandoffService';
-import { HandoffQRData, QRHandoffToken } from '../types/shipment';
+import { HandoffQRData } from '../types/shipment';
 import { useToast } from './useToast';
 
 export function useHandoffQR(deliveryId: string, enabled: boolean = true) {
@@ -16,7 +16,7 @@ export function useHandoffQR(deliveryId: string, enabled: boolean = true) {
 
 export function useGenerateHandoffQR() {
   const queryClient = useQueryClient();
-  const { showToast } = useToast();
+  const { success, error: showError } = useToast();
 
   return useMutation({
     mutationFn: (deliveryId: string) =>
@@ -26,24 +26,17 @@ export function useGenerateHandoffQR() {
       queryClient.invalidateQueries({
         queryKey: ['handoffQR', data.deliveryId],
       });
-      showToast({
-        type: 'success',
-        message: 'QR code generated successfully',
-      });
+      success?.('QR code generated successfully');
     },
-    onError: (error) => {
-      showToast({
-        type: 'error',
-        message: 'Failed to generate QR code',
-      });
-      console.error('QR generation error:', error);
+    onError: () => {
+      showError?.('Failed to generate QR code');
     },
   });
 }
 
 export function useVerifyHandoffQR() {
   const queryClient = useQueryClient();
-  const { showToast } = useToast();
+  const { success, error: showError } = useToast();
 
   return useMutation({
     mutationFn: ({ deliveryId, token }: { deliveryId: string; token: string }) =>
@@ -56,17 +49,10 @@ export function useVerifyHandoffQR() {
       queryClient.invalidateQueries({
         queryKey: ['delivery', data.id],
       });
-      showToast({
-        type: 'success',
-        message: 'Handoff verified successfully!',
-      });
+      success?.('Handoff verified successfully!');
     },
-    onError: (error) => {
-      showToast({
-        type: 'error',
-        message: 'Failed to verify handoff',
-      });
-      console.error('Handoff verification error:', error);
+    onError: () => {
+      showError?.('Failed to verify handoff');
     },
   });
 }
diff --git a/hooks/useOfflineHandoffSync.ts b/hooks/useOfflineHandoffSync.ts
new file mode 100644
index 00000000..79991037
--- /dev/null
+++ b/hooks/useOfflineHandoffSync.ts
@@ -0,0 +1,103 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  HandoffSyncState,
+  offlineHandoffService,
+} from '@/services/offlineHandoffService';
+import { shipmentHandoffService } from '@/services/shipmentHandoffService';
+
+export function useOfflineHandoffSync(enabled = true) {
+  const [isOnline, setIsOnline] = useState(
+    () => typeof navigator === 'undefined' || navigator.onLine,
+  );
+  const [syncState, setSyncState] = useState<HandoffSyncState>(
+    () => (offlineHandoffService.pendingCount() > 0 ? 'pending' : 'synced'),
+  );
+  const [pendingCount, setPendingCount] = useState(
+    () => offlineHandoffService.pendingCount(),
+  );
+  const retryTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const syncRef = useRef<() => Promise<void>>(async () => undefined);
+
+  const refreshCount = useCallback(() => {
+    const count = offlineHandoffService.pendingCount();
+    setPendingCount(count);
+    return count;
+  }, []);
+
+  const sync = useCallback(async () => {
+    if (!enabled || typeof navigator !== 'undefined' && !navigator.onLine) return;
+    const result = await offlineHandoffService.syncPending();
+    refreshCount();
+    setSyncState(result.failed > 0 ? 'failed' : result.pending > 0 ? 'pending' : 'synced');
+
+    if (retryTimer.current) clearTimeout(retryTimer.current);
+    if (result.nextRetryAt !== null) {
+      retryTimer.current = setTimeout(
+        () => void syncRef.current(),
+        Math.max(0, result.nextRetryAt - Date.now()),
+      );
+    }
+  }, [enabled, refreshCount]);
+
+  useEffect(() => {
+    syncRef.current = sync;
+  }, [sync]);
+
+  const processScan = useCallback(
+    async (deliveryId: string, token: string) => {
+      if (!enabled) return 'failed' as const;
+      if (typeof navigator !== 'undefined' && !navigator.onLine) {
+        offlineHandoffService.enqueue(deliveryId, token);
+        await offlineHandoffService.requestBackgroundSync();
+        refreshCount();
+        setSyncState('pending');
+        return 'pending' as const;
+      }
+
+      try {
+        await shipmentHandoffService.verifyHandoffQR(deliveryId, token);
+        setSyncState('synced');
+        return 'synced' as const;
+      } catch {
+        offlineHandoffService.enqueue(deliveryId, token);
+        await offlineHandoffService.requestBackgroundSync();
+        refreshCount();
+        setSyncState('failed');
+        if (retryTimer.current) clearTimeout(retryTimer.current);
+        retryTimer.current = setTimeout(() => void syncRef.current(), 1000);
+        return 'failed' as const;
+      }
+    },
+    [enabled, refreshCount],
+  );
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    const handleOnline = () => {
+      setIsOnline(true);
+      void sync();
+    };
+    const handleOffline = () => {
+      setIsOnline(false);
+      if (refreshCount() > 0) setSyncState('pending');
+    };
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+    const initialSyncTimer =
+      navigator.onLine && pendingCount > 0
+        ? setTimeout(() => void sync(), 0)
+        : null;
+
+    return () => {
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+      if (initialSyncTimer) clearTimeout(initialSyncTimer);
+      if (retryTimer.current) clearTimeout(retryTimer.current);
+    };
+  }, [enabled, pendingCount, refreshCount, sync]);
+
+  return { isOnline, syncState, pendingCount, processScan, retry: sync };
+}
diff --git a/services/__tests__/offlineHandoffService.test.ts b/services/__tests__/offlineHandoffService.test.ts
new file mode 100644
index 00000000..5af098b7
--- /dev/null
+++ b/services/__tests__/offlineHandoffService.test.ts
@@ -0,0 +1,65 @@
+import {
+  OFFLINE_HANDOFF_STORAGE_KEY,
+  offlineHandoffService,
+} from '@/services/offlineHandoffService';
+import { shipmentHandoffService } from '@/services/shipmentHandoffService';
+
+jest.mock('@/services/shipmentHandoffService', () => ({
+  shipmentHandoffService: { verifyHandoffQR: jest.fn() },
+}));
+
+const verifyHandoff = shipmentHandoffService.verifyHandoffQR as jest.Mock;
+
+describe('offlineHandoffService', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    jest.clearAllMocks();
+  });
+
+  it('persists an offline scan in localStorage', () => {
+    offlineHandoffService.enqueue('delivery-1', 'token-1');
+
+    const stored = JSON.parse(localStorage.getItem(OFFLINE_HANDOFF_STORAGE_KEY) ?? '[]');
+    expect(stored).toEqual([
+      expect.objectContaining({ deliveryId: 'delivery-1', token: 'token-1', attempts: 0 }),
+    ]);
+  });
+
+  it('removes scans after a successful reconnect sync', async () => {
+    offlineHandoffService.enqueue('delivery-1', 'token-1');
+    verifyHandoff.mockResolvedValue({ id: 'handoff-1' });
+
+    const result = await offlineHandoffService.syncPending(1000);
+
+    expect(result).toEqual({ synced: 1, failed: 0, pending: 0, nextRetryAt: null });
+    expect(offlineHandoffService.getQueue()).toEqual([]);
+  });
+
+  it('retains failed scans with exponential backoff metadata', async () => {
+    offlineHandoffService.enqueue('delivery-1', 'token-1');
+    verifyHandoff.mockRejectedValue(new Error('Temporary outage'));
+
+    const first = await offlineHandoffService.syncPending(1000);
+    expect(first.nextRetryAt).toBe(2000);
+    expect(offlineHandoffService.getQueue()[0]).toEqual(
+      expect.objectContaining({ attempts: 1, nextAttemptAt: 2000 }),
+    );
+
+    await offlineHandoffService.syncPending(2000);
+    expect(offlineHandoffService.getQueue()[0]).toEqual(
+      expect.objectContaining({ attempts: 2, nextAttemptAt: 4000 }),
+    );
+  });
+
+  it('does not retry an item before its next attempt time', async () => {
+    offlineHandoffService.enqueue('delivery-1', 'token-1');
+    verifyHandoff.mockRejectedValue(new Error('Temporary outage'));
+    await offlineHandoffService.syncPending(1000);
+    verifyHandoff.mockClear();
+
+    const result = await offlineHandoffService.syncPending(1500);
+
+    expect(verifyHandoff).not.toHaveBeenCalled();
+    expect(result.pending).toBe(1);
+  });
+});
diff --git a/services/offlineHandoffService.ts b/services/offlineHandoffService.ts
new file mode 100644
index 00000000..606a8ec1
--- /dev/null
+++ b/services/offlineHandoffService.ts
@@ -0,0 +1,117 @@
+import { shipmentHandoffService } from '@/services/shipmentHandoffService';
+
+export type HandoffSyncState = 'synced' | 'pending' | 'failed';
+
+export interface QueuedHandoffScan {
+  id: string;
+  deliveryId: string;
+  token: string;
+  scannedAt: string;
+  attempts: number;
+  nextAttemptAt: number;
+}
+
+export interface HandoffSyncResult {
+  synced: number;
+  failed: number;
+  pending: number;
+  nextRetryAt: number | null;
+}
+
+const STORAGE_KEY = 'swiftchain:handoff-scan-queue:v1';
+const MAX_BACKOFF_MS = 5 * 60 * 1000;
+
+function readQueue(): QueuedHandoffScan[] {
+  if (typeof window === 'undefined') return [];
+  try {
+    const value = window.localStorage.getItem(STORAGE_KEY);
+    if (!value) return [];
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed) ? (parsed as QueuedHandoffScan[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(queue: QueuedHandoffScan[]) {
+  if (typeof window === 'undefined') return;
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(queue));
+}
+
+function createId(deliveryId: string, scannedAt: string) {
+  return `${deliveryId}:${scannedAt}:${Math.random().toString(36).slice(2)}`;
+}
+
+export const offlineHandoffService = {
+  getQueue: readQueue,
+
+  enqueue(deliveryId: string, token: string): QueuedHandoffScan {
+    const scannedAt = new Date().toISOString();
+    const item: QueuedHandoffScan = {
+      id: createId(deliveryId, scannedAt),
+      deliveryId,
+      token,
+      scannedAt,
+      attempts: 0,
+      nextAttemptAt: 0,
+    };
+    writeQueue([...readQueue(), item]);
+    return item;
+  },
+
+  pendingCount() {
+    return readQueue().length;
+  },
+
+  clear() {
+    writeQueue([]);
+  },
+
+  async requestBackgroundSync() {
+    if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) return;
+    try {
+      const registration = await navigator.serviceWorker.ready;
+      const syncRegistration = registration as ServiceWorkerRegistration & {
+        sync?: { register: (_tag: string) => Promise<void> };
+      };
+      await syncRegistration.sync?.register('swiftchain-handoff-sync');
+    } catch {
+      // The online listener remains the fallback when background sync is unavailable.
+    }
+  },
+
+  async syncPending(now = Date.now()): Promise<HandoffSyncResult> {
+    const queue = readQueue();
+    const remaining: QueuedHandoffScan[] = [];
+    let synced = 0;
+    let failed = 0;
+
+    for (const item of queue) {
+      if (item.nextAttemptAt > now) {
+        remaining.push(item);
+        continue;
+      }
+      try {
+        await shipmentHandoffService.verifyHandoffQR(item.deliveryId, item.token);
+        synced += 1;
+      } catch {
+        const attempts = item.attempts + 1;
+        const delay = Math.min(1000 * 2 ** (attempts - 1), MAX_BACKOFF_MS);
+        remaining.push({ ...item, attempts, nextAttemptAt: now + delay });
+        failed += 1;
+      }
+    }
+
+    writeQueue(remaining);
+    const nextRetryAt = remaining.reduce<number | null>(
+      (earliest, item) =>
+        earliest === null || item.nextAttemptAt < earliest
+          ? item.nextAttemptAt
+          : earliest,
+      null,
+    );
+    return { synced, failed, pending: remaining.length, nextRetryAt };
+  },
+};
+
+export { STORAGE_KEY as OFFLINE_HANDOFF_STORAGE_KEY };