Phase 4

Seed data extended with a second barber (different hours/services), a beard-trim service + category, breaks, time off, a guest customer, and appointments in all three key states — verified against a live throwaway Postgres.
14 new integration tests (38 total with Phase 3's) covering guest/authenticated booking, any-barber assignment, slot-conflict handling, ownership enforcement, guest-data isolation, and book-again repricing.
Playwright E2E suite for the 6 required customer journeys, with its own global-setup.ts that migrates and seeds a database automatically.
Full verification pass, which caught and fixed three real bugs along the way (not just test-workarounds):
A date off-by-one bug in the calendar picker that made real weekdays show as closed for anyone in a UTC+ timezone (including the business's own).
A dialog that could vanish mid-confirmation on cancellation, before the customer could read the late-cancellation notice.
A silent test-cleanup leak in the Phase 3 fixtures that had been leaking stray businesses since Phase 3.
Plus a baseline desktop-responsive fix (centered max-w-2xl columns) across Home/Appointments/Settings/booking flow, since desktop had been effectively unstyled.
Final state: 90 unit tests, 38 integration tests, and all 6 E2E journeys passing together on a fresh database; clean tsc, eslint, and next build. Full writeup with routes, security model, guest-matching rules, known limitations, and what to check before Phase 5 is in docs/phase-4-summary.md.

src/features/booking/error-messages.ts

@@ -0,0 +1,46 @@
+import type { BookingValidationErrorCode, ValidationResult } from "@/services/scheduling/types";
+
+/**
+ * Maps the typed error codes the Phase 3 services already return into
+ * customer-friendly copy. The only place raw codes get translated —
+ * every booking-flow page imports from here rather than inlining its own
+ * message strings, so the wording only needs to change in one place.
+ */
+const FRIENDLY_MESSAGES: Record<BookingValidationErrorCode, string> = {
+  INVALID_INPUT: "Something about that wasn't quite right. Please try again.",
+  NO_SERVICES_SELECTED: "Please select at least one service.",
+  SERVICES_SPAN_MULTIPLE_BUSINESSES: "One or more selected services aren't available here.",
+  STAFF_CANNOT_PERFORM_SERVICE: "This barber doesn't offer one of the selected services.",
+  BUSINESS_CLOSED: "The business is closed at this time — please choose another slot.",
+  STAFF_NOT_WORKING: "This barber isn't working at that time — please choose another slot or barber.",
+  STAFF_ON_BREAK: "This barber is on a break at that time — please choose another slot.",
+  STAFF_ON_LEAVE: "This barber is away on that date — please choose another barber or date.",
+  SLOT_UNAVAILABLE: "That time was just booked by someone else — please choose another.",
+  INSUFFICIENT_DURATION:
+    "There isn't enough time left that day for the selected services — try an earlier time or fewer services.",
+  BELOW_MIN_NOTICE: "This time is too soon — please choose a later time.",
+  BEYOND_MAX_ADVANCE: "This date is too far ahead to book yet — please choose a nearer date.",
+  BUSINESS_DAILY_LIMIT_REACHED: "This business is fully booked that day — please choose another date.",
+  STAFF_DAILY_LIMIT_REACHED: "This barber is fully booked that day — please choose another barber or date.",
+  APPOINTMENT_NOT_FOUND: "We couldn't find that appointment.",
+  INVALID_STATUS_TRANSITION: "This appointment can no longer be changed.",
+  STAFF_NOT_FOUND: "We couldn't find that barber.",
+  CUSTOMER_NOT_FOUND: "We couldn't find your customer details.",
+  BUSINESS_NOT_FOUND: "We couldn't find this business.",
+};
+
+const FALLBACK_MESSAGE = "Something went wrong with this booking. Please try again.";
+
+export function getFriendlyMessage(code: BookingValidationErrorCode): string {
+  return FRIENDLY_MESSAGES[code] ?? FALLBACK_MESSAGE;
+}
+
+export function getFriendlyValidationMessages(validation: ValidationResult): string[] {
+  if (validation.issues.length === 0) return [];
+  return validation.issues.map((issue) => getFriendlyMessage(issue.code));
+}
+
+export function getFirstFriendlyMessage(validation: ValidationResult): string {
+  const [first] = validation.issues;
+  return first ? getFriendlyMessage(first.code) : FALLBACK_MESSAGE;
+}