import './PatientBookAppointment.css';
import {
  useCallback,
  useEffect,
  useState,
  useMemo,
  useRef,
} from "react";
import {
  PractitionerRole,
  Practitioner,
  Schedule,
  Slot,
  Reference,
  AppointmentParticipant,
  Appointment,
  CodeableConcept,
  Organization,
  // Coding,
} from "fhir/r4";
import {
  getScheduleSlotIncrement,
  slotStartTimes,
  windowEndOnDay,
} from "../../../../../config/scheduleSlotIncrement";
import { getServiceFutureAppointmentLimit } from "../../../../../config/serviceFutureAppointmentLimit";
import { SUGGESTION_CONFIDENCE_FLOOR } from "../../../../../config/suggestionFloor";
import type { ServiceClarifyingQuestion } from "../../../../../services/BookingMatchService";
import { useForm, FormProvider, type Resolver } from "react-hook-form";
import {
  useAppointmentServiceContext,
  useAuthServiceContext,
  useEncounterServiceContext,
  useFhirServiceContext,
  usePractitionerRoleServiceContext,
  usePractitionerServiceContext,
  useScheduleServiceContext,
  useWebSocketServiceContext,
  usePatientServiceContext,
} from "../../../../../services";
import {
  useFhirAppointments,
  useFhirLocations,
  useFhirPractitionerRoleBroadcast,
  useFhirPractitioners,
  useFhirScheduleBroadcast,
  useFhirSchedules,
  useRouteAuthorization,
} from "../../../../../hooks";
import { useServiceCatalogueBasis } from "../../../../../hooks/useServiceCatalogueBasis";
import { useAwayBookingCatalog } from "../../../../../hooks/useAwayBookingCatalog";
import { useKeyedRead } from "../../../../../hooks/useKeyedRead";
import { formatFhirHumanName } from "../../../../../utils/fhirHumanName.tsx";
import {
  getCampaignCtaAttribution,
  clearCampaignCtaAttribution,
} from "../../../../../utils/campaignCtaAttribution";
import PatientTimeWindowRequest from "./PatientTimeWindowRequest";
import SelfBookingAuthorization, {
  SelfBookingAuthorizationRefusal,
  selfBookingAuthorizationSatisfied,
  type SelfBookingAuthorizationGate,
  type SelfBookingAuthorizationHandle,
} from "./SelfBookingAuthorization.tsx";

// New UI components
import { Button } from "../../../../../components/ui/button";
import {
  Select,
  SelectContent,
  SelectGroup,
  SelectItem,
  SelectLabel,
  SelectTrigger,
  SelectValue,
} from "../../../../../components/ui/select";
import {
  ArrowBigLeftDash,
  CalendarDays,
  Check,
  Clock4,
  Phone,
} from "lucide-react";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
import { Skeleton } from "../../../../../components/ui/skeleton.tsx";
import { formatDateForDisplay } from "../../../../../lib/utils.ts";
import { toast } from "sonner";
import { getScheduleBookingFlags } from "../../../../../services/ScheduleService.tsx";
import { getScheduleLocationReferences } from "../../../../../utils/scheduleLocations";
import { scheduleSiteFor } from '../../../../../utils/booking/physicalSite';
import { offerableLocationOptions, videoVisitFirst } from "../../../../../utils/scheduleTelehealth";
import { resolveServiceTelehealthEligible } from "../../../../../config/serviceTelehealthEligible";
import { resolveOrgAppointmentPolicy } from "../../../../../config/appointmentPolicy";
import { resolveAppointmentDurationMinutes } from "../../../../../config/appointmentDuration";
import { getOrganizationPolicyFlags } from "../../../../../services/OrganizationService";
import { useBookingMatchService } from "../../../../../services/BookingMatchService";
import {
  mapSuggestionsToBookableServices,
  type BookableSuggestion,
  recommendedSuggestionId,
} from "../../../../../utils/booking/matchServiceSuggestions";
import { dateHasBookableWindow } from "../../../../../utils/booking/bookingDateAvailability";
import {
  qualifiesForRecommendation,
  mapPractitionerRankings,
  type ApiPractitionerRanking,
  type BookablePractitioner,
  type PractitionerRecommendation,
} from "../../../../../utils/booking/matchPractitionerSuggestions";
import { reasonNamesALocation } from "../../../../../utils/booking/reasonNames";
import {
  buildBookablePractitioners,
  type BookablePractitionerCandidate,
} from "../../../../../utils/booking/bookablePractitioners";
import { selfBookingGuardText } from "../../../../../utils/booking/selfBookingGuardMessage";
import { canBeBookedAsClinician } from "../../../../../utils/booking/clinicianSeatGate";
import { useSeatStanding } from '../../../../../utils/seatStanding';
import { schedulePractitionerName } from "../../../../../utils/booking/schedulePractitionerName";
import { schedulePractitionerId } from "../../../../../utils/booking/schedulePractitioner";
import { matchSchedules, evaluateScheduleMatch, offeredServices, type MatchContext } from "../../../../../utils/booking/matchSchedules";
import { softConstraints } from "../../../../../utils/booking/softConstraints";
import { deadEndText } from "../../../../../utils/booking/explainDeadEnd";
import { describeNothingToOffer, type NothingToOffer } from "../../../../../utils/booking/nothingToOffer";
import { availabilityWindowsFor } from "../../../../../utils/booking/scheduleYieldsTimes";
import { offerablePractitionerSchedules, opensFrom } from "../../../../../utils/booking/offerablePractitioners";
import { resolveScheduleSelfBookableServices } from "../../../../../utils/booking/scheduleSelfBookableServices";
import {
  resolveFlowState,
  clearFrom,
  isAnswered,
  lockedServiceFilter,
  STEP_ORDER,
  type BookingAnswers,
  type BookingStepId,
} from "../../../../../utils/booking/bookingFlowSteps";
import { readPatientTypeFromEncounters } from "../../../../../utils/booking/patientBookingHistory";
import PractitionerRecommendationCallout from "./PractitionerRecommendationCallout";
import AnsweredLine from "./AnsweredLine";
import {
  getPractitionerRolePrimaryCoding,
  getPractitionerRolePrimaryDisplay,
} from "../../../../../utils/staffRoleCatalog";
import { isVirtualLocation, onlySites, onlyVirtual } from "../../../../../utils/roomLocation";
import { resolveBookingLocationRef, withLocationDisplay } from "../../../../../utils/booking/bookingAppointmentLocation";
import { isOrgWideRole } from "../../../../../utils/locationAssignments";
import {
  intervalEndDate,
  resolveBookingTimeZone,
  viewerTimeZone,
} from "../../../../../utils/practiceTimezone";
import { slotReadWindow } from "../../../../../utils/booking/slotReadWindow";
import { heldRangesOnDate, pickedTimeInstant } from "../../../../../utils/booking/patientPickedTime";
import { heldAsBusy, nextSendStanding, pickedTimeStanding, readBusyTimes, type SendStanding } from "../../../../../utils/booking/busyTimes";
import { returnLostPickToTimeChoice } from "../../../../../utils/booking/lostPick";
import { withSelectedServiceRef } from "../../../../../utils/booking/selectedServiceRef";
import { visitZoneLabel } from "../../../../../utils/booking/visitZoneLabel";
import { asDenial, readAppointmentGuardOutcome, readSlotReservationCode } from "../../../../../utils/booking/appointmentGuardOutcome";
import { HttpError } from "../../../../../services/HttpService.tsx";
import { bookingFailure, bookingRefusal } from "./bookingFailure";
import { StepRefusal } from "./StepRefusal";
import { STEP_NAMES, useStepFocus } from "./useStepFocus";
import {
  CheckingYourBooking,
  isBookingRetired,
  isBookingUnconfirmed,
  useBookingOperation,
} from "../../../../../components/booking/CheckingYourBooking";
import type { BookingOperationEntry } from "../../../../../utils/booking/bookingOperation";
import { isNewPatientConsultationType } from "../../../../../config/newPatientExam";
import { reviewServiceLabel } from "../../../../../utils/booking/reviewServiceLabel";
import { withAppointmentLength } from "../../../../../utils/appointmentLength";
import {
  buildUnionAvailability,
  type AvailabilityWindow,
  type BookingBlock,
  type TaggedAvailabilityWindow,
  type UnionAvailability,
} from "../../../../../utils/bookingAvailabilityUnion";

// Shape of the calendar events getScheduleAvailabilityEvents returns (Date-based). We convert these into
// the string-typed AvailabilityWindow the union util consumes; typing them here avoids the untyped `any`
// the previous inline filter used.
interface RawScheduleAvailabilityEvent {
  start: Date;
  end: Date;
  extendedProps?: { type?: string };
}

interface FhirCloudEvent<T> {
  data: T;
  type: string;
}

const codeableConceptSchema = z.custom<CodeableConcept>();

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function getErrorMessage(error: unknown, fallback: string): string {
  if (error instanceof Error && error.message.trim()) {
    return error.message;
  }

  if (!isRecord(error)) {
    return fallback;
  }

  if (typeof error.message === "string" && error.message.trim()) {
    return error.message;
  }

  const response = isRecord(error.response) ? error.response : undefined;
  const responseData = response?.data;

  if (typeof responseData === "string" && responseData.trim()) {
    return responseData;
  }

  if (
    isRecord(responseData) &&
    typeof responseData.message === "string" &&
    responseData.message.trim()
  ) {
    return responseData.message;
  }

  return fallback;
}

// Schema for form validation
const appointmentSchema = z.object({
  practitionerId: z.string().min(1, "Please select a practitioner"),
  appointmentType: z.string().min(1, "Please select an appointment type"),
  date: z.string().min(1, "Please select a date"),
  startTime: z.string().min(1, "Please select a time slot"),
  endTime: z.string().min(1, "Please select a time slot"),
  description: z.string().optional(),
  comment: z.string().optional(),
  reasonForVisit: z
    .string()
    .trim()
    .min(1, "Please tell us the reason for your visit"),
  serviceCategory: z.array(codeableConceptSchema).optional(),
  serviceType: z.array(codeableConceptSchema).optional(),
  specialty: z.array(codeableConceptSchema).optional(),
  priority: z.number().optional(),
  patientInstruction: z.string().optional(),
});

// react-hook-form builds its field-path union by walking every nested property of the form type.
// CodeableConcept is deep enough that three such fields push tsc past its type-instantiation limit
// and crash the compiler outright (RangeError: Map maximum size exceeded) instead of reporting an
// error - which is why nothing in this repo type-checks. None of these three is bound to an input:
// they are set programmatically and read once at submit, so no path types are needed for them.
// Keeping them opaque here costs a cast at each read site and takes the file from a 3-minute crash
// to a 6-second check. The zod schema above still validates them as CodeableConcept at runtime.
type FormOpaqueCodings = unknown[];

type AppointmentFormData = Omit<
  z.infer<typeof appointmentSchema>,
  "serviceCategory" | "serviceType" | "specialty"
> & {
  serviceCategory?: FormOpaqueCodings;
  serviceType?: FormOpaqueCodings;
  specialty?: FormOpaqueCodings;
};

// THE HAND-TYPED HALF-HOUR LADDER USED TO LIVE HERE, and it is deleted rather than left unused.
// It was a 24-hour table from 06:00 to 05:30 that the patient's time picker filtered by availability,
// so every practice was offered thirty-minute slots whatever increment it had chosen, at hours it does
// not work. The grid is now generated from each schedule block's own hours and increment - see
// `config/scheduleSlotIncrement`. Left in the file it would be reached for again.

// Radix <SelectItem> throws on an empty-string value, so "Any location" - an explicit, active choice
// meaning "no location preference, show every site" - uses this sentinel instead of ''. '' is reserved
// for "nothing chosen yet" (the Select shows its placeholder); ANY_LOCATION is a real, distinct selection
// that schedulesMatching treats the same as "no location constraint" when narrowing schedules.
const ANY_LOCATION = "__all__";

function formatDateOnly(date: Date | null) {
  return date
    ? date.getFullYear() +
        "-" +
        String(date.getMonth() + 1).padStart(2, "0") +
        "-" +
        String(date.getDate()).padStart(2, "0")
    : "";
}

// Local-time ISO string ("YYYY-MM-DDTHH:mm:ss.SSS", NO trailing Z) for a Date. The whole availability
// pipeline is LOCAL-time: isTimeSlotAvailable and the union resolver both build the slot instant with
// `new Date(`${dateStr}T${HH:mm}:00`)` (local). Serializing the Date-based schedule windows with
// toISOString() would emit UTC and offset against that local slot instant - so we serialize the local
// components instead, and `new Date(localIso)` reproduces the exact same local instant.
function toLocalIso(date: Date): string {
  return (
    date.getFullYear() +
    "-" +
    String(date.getMonth() + 1).padStart(2, "0") +
    "-" +
    String(date.getDate()).padStart(2, "0") +
    "T" +
    String(date.getHours()).padStart(2, "0") +
    ":" +
    String(date.getMinutes()).padStart(2, "0") +
    ":" +
    String(date.getSeconds()).padStart(2, "0") +
    "." +
    String(date.getMilliseconds()).padStart(3, "0")
  );
}

// Helper function to check if a time slot is within availability events
function isTimeSlotAvailable(
  slotTime: string,
  dateStr: string,
  availabilityEvents: AvailabilityWindow[],
  durationMinutes: number = 30,
): boolean {
  if (!dateStr || availabilityEvents.length === 0) return false;

  const now = new Date();
  const slotDateTime = new Date(`${dateStr}T${slotTime}:00`);
  const slotEndDateTime = new Date(slotDateTime.getTime() + durationMinutes * 60000);

  return availabilityEvents.some((event) => {
    // Windows are local-ISO strings (see toLocalIso); parse them back to the same local instant the slot
    // is built in, so this comparison stays timezone-consistent (never mix a UTC basis in here).
    const eventStart = new Date(event.start);
    const eventEnd = new Date(event.end);

    // The whole appointment [start, start+duration) must fit inside a single availability window.
    return (
      slotDateTime >= eventStart &&
      slotEndDateTime <= eventEnd &&
      slotDateTime >= now
    );
  });
}

// Helper function to check if a time slot is booked
function isTimeSlotBooked(
  slotTime: string,
  busyRanges: { startMin: number; endMin: number }[],
  durationMinutes: number,
): boolean {
  if (busyRanges.length === 0) return false;

  // The candidate appointment [start, start+duration) must not overlap any busy range (minutes-of-day).
  const [h, m] = slotTime.split(":").map(Number);
  const candStart = h * 60 + m;
  const candEnd = candStart + durationMinutes;
  return busyRanges.some((r) => candStart < r.endMin && r.startMin < candEnd);
}

// Main Component
interface PatientBookAppointmentProps {
  onSuccess?: (message: string, appointment?: Appointment) => void;
  onClose?: () => void;
  /**
 * Rendered inside a dialog rather than as the `book-appointment` ROUTE.
 *
 * This exists for one reason: the route guard below. It answers "may this person be AT this URL",
 * and the answer for the patient self-booking route is patients only - but the same component is
 * also opened as a dialog from the patient's chart, where the viewer is STAFF by definition. The
 * guard therefore fired on the person legitimately using it and redirected them off the chart.
 *
 * DEFAULTS TO FALSE SO THE GUARD STAYS ON, deliberately. A future DIALOG site that forgets this
 * reproduces a visible redirect; a future ROUTE that forgot it would be an unguarded route. Of the
 * two ways to be wrong, only one is silent.
 */
  embedded?: boolean;
  /** Another practice the patient is booking with from this portal; absent means the portal's own. */
  bookingOrganization?: Organization;
}

const PatientBookAppointment = ({
  onSuccess,
  onClose,
  embedded = false,
  bookingOrganization,
}: PatientBookAppointmentProps) => {
  const { USER_ROLES, wpOrganization, userRole } = useAuthServiceContext();
  const viewerIsPatient = [USER_ROLES.PATIENT, USER_ROLES.RELATED_PERSON].includes(userRole as string);
  const { patientState } = usePatientServiceContext();
  // Booking with another practice reads and writes under that practice, so its own rules decide; the
  // portal's branding and shared lists are left as they are. The portal's own practice books as before.
  const awayOrganization = bookingOrganization?.id && bookingOrganization.id !== wpOrganization.current?.id
    ? bookingOrganization
    : undefined;
  const bookingOrg: Organization | undefined = awayOrganization ?? wpOrganization.current ?? undefined;
  const orgOverride = awayOrganization?.id;
  const away = useAwayBookingCatalog(awayOrganization, patientState ?? undefined);
  const { subscribe, unsubscribe } = useWebSocketServiceContext();
  const { transformFromFhirPractitionerRole } =
    usePractitionerRoleServiceContext();
  const {
    schedulesList: sharedSchedulesList,
    getScheduleAvailabilityEvents,
    fetchSlots,
    fetchHeldTimes,
    createSlot,
    transformToFhirSlot,
  } = useScheduleServiceContext();
  const schedulesList = away ? away.schedules : sharedSchedulesList;
  const { practitionersList: sharedPractitionersList } = usePractitionerServiceContext();
  const practitionersList = away ? away.practitioners : sharedPractitionersList;
  // Org locations - used to surface bookable sites for a practitioner whose role is scoped to
  // "All locations" (an empty PractitionerRole.location), which otherwise contributes no options.
  const { locationsList: sharedLocationsList } = useFhirLocations({ autoLoad: !awayOrganization });
  const locationsList = away ? away.locations : sharedLocationsList;
  // Only services a whole current catalogue verifies are offered: the away practice's own basis, or the portal's.
  // A practice whose services cannot be verified offers none and says so; it is never read as offering nothing.
  const primaryServicesBasis = useServiceCatalogueBasis();
  const servicesBasis = away ? away.servicesBasis : primaryServicesBasis;
  const retryServices = away ? away.retryServices : primaryServicesBasis.retry;
  const healthcareServicesList = servicesBasis.services;
  const healthcareServicesLoading = servicesBasis.state === 'checking';
  const servicesUnverified = servicesBasis.state !== 'complete';
  const {
    filterAndUnpackBundle,
    extractReferenceType,
    extractReferenceId,
    // unpackBundle,
    createReferenceObject,
  } = useFhirServiceContext();
  // const { getAdjustedHeight } = useConfigServiceContext();
  const { fetchEncounters } = useEncounterServiceContext();
  const {
    createAppointment,
    fetchAppointments,
    setAppointmentsList,
    getActiveFutureAppointmentForPractitioner: activeFutureFromCache,
  } = useAppointmentServiceContext();
  // The booking's operation outlives this dialog: a lost answer is checked here, not booked again.
  const booking = useBookingOperation({
    opening: "patient-booking",
    practice: bookingOrg?.id,
    patient: patientState?.id,
  });
  booking.onBooked((appointment) => {
    const pending = appointment.status === "proposed" || appointment.status === "pending";
    onSuccess?.(pending
      ? "Your appointment has been submitted and is pending confirmation by the practice."
      : "Appointment created successfully.", appointment);
  });
  const awayAppointments = away?.appointments;
  const refreshAwayAppointments = away?.refreshAppointments;
  const getActiveFutureAppointmentForPractitioner = useCallback(
    (practitionerId: string, roleIds?: string[], appointments?: Appointment[], limit?: number, codingKey?: string) =>
      activeFutureFromCache(practitionerId, roleIds, appointments ?? awayAppointments, limit, codingKey),
    [activeFutureFromCache, awayAppointments],
  );
  // Reason-for-visit -> suggested service ("Find my service") and -> ranked practitioners.
  // Both fail open to [] on any error, so they can only ever degrade to the existing manual pickers
  // below, never block booking.
  const { matchService, matchPractitioner, matchingAvailable = true } = useBookingMatchService();

  // const navigate = useNavigate();

  // State management
  const [submitting, setSubmitting] = useState(false);
  // const [success, setSuccessState] = useState<string | undefined>();
  // const [error, setError] = useState<string | undefined>();
  const [selectedSchedule, setSelectedSchedule] = useState<Schedule | null>(
    null,
  );
  const [practitionerRole, setPractitionerRole] =
    useState<PractitionerRole | null>(null);
  const [practitioner, setPractitioner] = useState<Practitioner | undefined>();
  // Availability is now the UNION of every location-scoped block the selected practitioner works that
  // matches the current filters, so each window is tagged with its source block for slot->block
  // resolution and site labels. String-typed (local-ISO) - see toLocalIso / buildUnionAvailability.
  const [availabilityEvents, setAvailabilityEvents] = useState<
    TaggedAvailabilityWindow[]
  >([]);
  const [reviewStep, setReviewStep] = useState(1); // 1: selection, 2: review, 3: confirmation
  const stepBodyRef = useStepFocus(reviewStep);

  /*
 * WHAT WAS BOOKED, KEPT SO THE CONFIRMATION CAN SAY IT.
 *
 * Step 3 existed as a number and had no screen: the code that would have reached it was commented out,
 * the render had no branch for it, and the button block returned an empty string. So a patient who
 * confirmed got a toast and a wiped form, and the last step of the first thing they ever do in the
 * product acknowledged nothing.
 *
 * This is a SNAPSHOT rather than a read of live state, because clearing the form is what has to happen
 * next - the practitioner, date, slot and service are all reset, and a confirmation rendered from them
 * would empty itself out from under the patient.
 */
  const [bookingConfirmation, setBookingConfirmation] = useState<{
    practitionerName?: string;
    dateLabel: string;
    timeLabel: string;
    locationLabel: string;
    serviceLabel: string;
    pendingPracticeConfirmation: boolean;
  } | null>(null);
  /**
 * Why the last Confirm Booking did not book, shown INSIDE the dialog.
 *
 * Not a duplicate of the toast beside it. A toast is position:fixed inside a provider tree mounted
 * into a practice's own WordPress page, so any transformed ancestor positions it against that ancestor
 * instead of the viewport - where it can land off-screen. That is what a browser run on 2026-08-20 saw:
 * a 403 from the authorization step, and no message of any kind on the screen.
 */
  const [confirmRefusal, setConfirmRefusal] = useState<string | undefined>();
  // Why a refusal sent the patient back to the first step; shown there, announced and focused.
  const [stepOneRefusal, setStepOneRefusal] = useState<string | undefined>();
  useEffect(() => {
    if (reviewStep !== 1) setStepOneRefusal(undefined);
  }, [reviewStep]);
  const [selectedPractitioner, setSelectedPractitioner] = useState<{
    name: string;
    role: string;
    image: string;
  } | null>(null);
  // const [encounter, setEncounter] = useState<Encounter>();
  // const [encounterLoading, setEncounterLoading] = useState(false);
  const [formDataForSubmission, setFormDataForSubmission] =
    useState<AppointmentFormData | null>(null);
  const [selectedDate, setSelectedDate] = useState<Date | null>(null);
  const [checkingSelfBookingGuard, setCheckingSelfBookingGuard] =
    useState(false);
  const selfBookingGuardRequestRef = useRef(0);
  // The union resolver (Task 1) for the currently selected practitioner: maps a picked (date, HH:mm) slot
  // back to the location-scoped block that owns it. Held in a ref because booking/loadSlots read it
  // imperatively and it must not trigger a re-render; rebuilt whenever a practitioner is (re)selected.
  const resolveBlockForSlotRef = useRef<
    UnionAvailability["resolveBlockForSlot"] | null
  >(null);
  // The clinical-authorization step rendered in review Step 2 below. handleCreateAppointment awaits
  // recordAnswer() first thing inside its try block, before anything is created - and that call
  // REJECTS unless the patient has actually answered, so a failure aborts the booking instead of
  // producing an appointment the patient believes they authorized.
  //
  // The ref is the gate; the state below is only the button's view of it. The ref reads the
  // component's own current state, so it is right even in the render between mounting and the first
  // gate callback - which is exactly the window a state-only gate would leave open.
  const selfBookingAuthorizationRef = useRef<SelfBookingAuthorizationHandle>(null);
  // Defaults to "not-required" on purpose: the step is mounted only in review Step 2, and on the
  // paths that never mount it (request-only / time-window bookings) nothing should be gated. The
  // component pushes "checking" the moment it mounts.
  const [selfBookingAuthorizationGate, setSelfBookingAuthorizationGate] =
    useState<SelfBookingAuthorizationGate>("not-required");
  const [selectedServiceFilter, setSelectedServiceFilter] = useState('');
  const [selectedLocationFilter, setSelectedLocationFilter] = useState('');
  // "Find my service" (reason -> suggested service) affordance state - additive to, never a
  // replacement for, the manual Care-type Select below.
  const [suggestions, setSuggestions] = useState<BookableSuggestion[]>([]);
  const [suggestLoading, setSuggestLoading] = useState(false);
  const [suggestTried, setSuggestTried] = useState(false);
  // One question the server offers when more than five services cleared the floor - a list too long to
  // choose from. Answering is OPTIONAL: the long list is worse, not forbidden, so nothing here gates
  // the booking and "See all services" stays reachable throughout.
  const [clarifyQuestion, setClarifyQuestion] = useState<ServiceClarifyingQuestion | undefined>();
  const [clarifyAnswer, setClarifyAnswer] = useState("");
  // How many services matched above the floor. Bigger than what is drawn whenever the list was
  // long, which is exactly when a reader needs to be told so before they start scrolling.
  const [matchedCount, setMatchedCount] = useState(0);
  // Undefined when the top two are too close to separate - the screen then marks nothing and
  // says nothing that implies a preference, which is the honest reading of a near tie.
  const recommendedId = useMemo(() => recommendedSuggestionId(suggestions), [suggestions]);
  // Escape hatch for the now-required "Find my service" assist (Task 7) - set true by either fallback
  // door (assist failed / assist succeeded but nothing fit), reveals the manual Care-type Select.
  const [showAllServices, setShowAllServices] = useState(false);
  // "Recommended for your reason" - reason + chosen service -> ranked practitioners. The RAW
  // server ranking depends only on (reason, serviceId); it is location-INVARIANT, so we cache it here and
  // derive the display recommendations (incl. the location-dependent crossLocation flag) with a pure memo
  // below - a location toggle then re-maps without re-invoking Bedrock. Empty = the fail-open default.
  const [practitionerRankings, setPractitionerRankings] = useState<ApiPractitionerRanking[]>([]);

  /*
   * DECLARED HERE BECAUSE THE MEMO BELOW READS IT, and a component body runs top to bottom.
   *
   * Both of these used to sit about a thousand lines further down, after
   * `activePractitionerAppointment`. Reading a `const` above its own declaration in the same scope
   * is a temporal dead zone, so choosing a service killed the whole booking screen with
   * `Cannot access '_t' before initialization` - the minified name - and took the error boundary
   * with it.
   *
   * IT HID BEHIND AN EARLY RETURN. `activePractitionerAppointment` returns before touching this
   * when no practitioner is resolved, which is every render until a service is picked. Picking one
   * resolves a practitioner, the guard stops stopping it, and the read happens for the first time -
   * so the crash landed on the step AFTER the change that caused it, on all three entry points that
   * mount this screen.
   */
  const serviceById = useMemo(
    () => new Map((healthcareServicesList ?? []).map((s) => [s.id, s])),
    [healthcareServicesList],
  );

  /**
   * THE PRACTICE'S CAP FOR THE SERVICE BEING BOOKED, and its coding.
   *
   * Ruled 2026-09-06: no cap by default, an optional per-service limit. Both are undefined until a
   * service is chosen, which is correct rather than incidental - there is no per-service rule to apply
   * before the patient has picked one, and refusing then is the defect this replaced.
   *
   * A MIRROR OF THE SERVER'S RULE, and it decides only whether the picker offers a booking the server
   * would refuse. The server counts the same thing again before it writes.
   */
  const chosenServiceCap = useMemo(() => {
    const service = selectedServiceFilter ? serviceById.get(selectedServiceFilter) : undefined;
    const coding = service?.type?.[0]?.coding?.[0];

    return {
      limit: getServiceFutureAppointmentLimit(service),
      codingKey: coding?.code ? `${coding.system ?? ''}|${coding.code}` : undefined,
    };
  }, [selectedServiceFilter, serviceById]);

  const activePractitionerAppointment = useMemo(() => {
    if (!practitioner?.id) {
      return undefined;
    }

    return getActiveFutureAppointmentForPractitioner(
      practitioner.id,
      practitionerRole?.id ? [practitionerRole.id] : [],
      undefined,
      chosenServiceCap.limit,
      chosenServiceCap.codingKey,
    );
  }, [
    getActiveFutureAppointmentForPractitioner,
    practitioner?.id,
    practitionerRole?.id,
  ]);

  // const visibleRangeRef = useRef<{ start: Date; end: Date } | null>(null);

  // // Check if user is patient
  // const isPatient = [USER_ROLES.PATIENT, USER_ROLES.RELATED_PERSON].includes(
  // userRole as string,
  // );

  // Form setup
  const methods = useForm<AppointmentFormData>({
    // The schema still describes the three coded fields as CodeableConcept; AppointmentFormData
    // deliberately hides that shape from react-hook-form (see FormOpaqueCodings). Same values,
    // two views of them, so the resolver is restated in the form's view at that boundary.
    resolver: zodResolver(appointmentSchema) as Resolver<AppointmentFormData>,
    defaultValues: {
      practitionerId: "",
      appointmentType: "ROUTINE",
      date: "",
      startTime: "",
      endTime: "",
      description: "",
      comment: "",
      reasonForVisit: "",
      serviceCategory: [],
      serviceType: [],
      specialty: [],
      priority: 0,
      patientInstruction: "",
    },
    mode: "onChange",
  });

  const {
    // handleSubmit,
    reset,
    watch,
    setValue,
    trigger,
    getValues,
    formState: { isValid, errors },
  } = methods;

  // Watched values
  const watchStartTime = watch("startTime");
  // const watchEndTime = watch("endTime");
  const watchDate = watch("date");
  const watchPractitionerId = watch("practitionerId");
  const watchAppointmentType = watch("appointmentType");
  const watchReasonForVisit = watch("reasonForVisit");
  const selectedPractitionerName =
    selectedPractitioner?.name || "this practitioner";
  const organizationName = bookingOrg?.name || "the organization";
  const organizationPhone = bookingOrg?.telecom?.find(
    (contact) => contact.system === "phone" && contact.value,
  )?.value;
  const orgPolicy = getOrganizationPolicyFlags(bookingOrg);
  /*
 * THE SERVICE'S OWN DURATION, resolved exactly as the front desk resolves it.
 *
 * This read the org default and nothing else, under a comment saying patient self-booking has "no
 * per-service picker in this flow". That was true when it was written and is not true now - the patient
 * picks a service, or the booking assist picks one for them. The comment is why it went unnoticed for
 * so long: it reads as considered, so a reader takes it as current instead of checking it.
 *
 * ONE VALUE FEEDS THREE READS, and that is what made the failure total. The date-has-a-window check,
 * the slot filter and the saved appointment all take this number. So a practice that set a 45-minute
 * new-patient exam was offered 30-minute slots AND had a 30-minute appointment written - the offer and
 * the write were wrong from one cause, which is also why one line fixes both.
 *
 * The last slot of the day comes out right for free: `isTimeSlotAvailable` bounds a slot by whether the
 * duration fits before close, so a 45-minute service stops being offered at 4:30 PM against a 5 PM
 * close once the number is correct.
 */
  const selectedServiceForDuration = useMemo(
    () =>
      selectedServiceFilter
        ? (healthcareServicesList ?? []).find((service) => service.id === selectedServiceFilter)
        : undefined,
    [healthcareServicesList, selectedServiceFilter],
  );
  const appointmentDurationMinutes = resolveAppointmentDurationMinutes(
    selectedServiceForDuration,
    orgPolicy.defaultAppointmentDurationMinutes,
  );
  // Request-only: a patient self-booking becomes a `proposed` request a receptionist confirms.
  const isRequestOnlyBooking = orgPolicy.bookingMode === "request-only";
  // Review: a direct self-booking is held as `pending` for staff approval (same booking UI as direct).
  const isReviewBooking = orgPolicy.bookingMode === "review";
  // The policy holds only a patient's own booking; the server books staff directly, so the chart says Book.
  const asksAsRequest = viewerIsPatient && isRequestOnlyBooking;
  const heldForReview = viewerIsPatient && (isReviewBooking || isRequestOnlyBooking);
  // Time-window request: a slot-less request (no practitioner/slot) - rendered as a dedicated form.
  const isTimeWindowRequest =
    isRequestOnlyBooking && orgPolicy.requestStyle === "time-window";
  // New-patient-exam gate applies only to DIRECT self-booking - in request-only the receptionist
  // handles the new-patient flow on confirm (mirroring the server, which skips the gate there).
  const requireNewPatientExamGate =
    orgPolicy.requireNewPatientExamFirst && !isRequestOnlyBooking;
  // HAS THIS PATIENT BEEN SEEN HERE? Spencer, 2026-09-09: "New patient should be enforced on 'seen'
  // meaning they've actually had an encounter, not just appointments." An appointment is an intention -
  // it can be for next week, cancelled or missed - so this reads Encounters, filtered to this
  // organization because "new" belongs to the patient-practice relationship rather than to the person.
  //
  // The server reads the same record and is the boundary; this only decides what the patient is
  // OFFERED. The two use the same statuses and the same organization test deliberately, so the list a
  // patient sees and the booking the server will accept cannot disagree.
  //
  // There is no third "unknown" answer any more, and so no question to ask the patient. The old read
  // could not tell established from unrecorded, so the flow asked; a patient's answer could never
  // override a record we hold, and now we hold it.
  const [derivedPatientType, setDerivedPatientType] = useState<
    "existing" | "new" | "loading"
  >("loading");

  useEffect(() => {
    if (!requireNewPatientExamGate || !patientState?.id) {
      setDerivedPatientType("existing");
      return;
    }
    let cancelled = false;
    void readPatientTypeFromEncounters(
      () => fetchEncounters({ patient: patientState, organizationId: orgOverride }),
      bookingOrg?.id,
    ).then((type) => { if (!cancelled) setDerivedPatientType(type); });
    return () => { cancelled = true; };
  }, [requireNewPatientExamGate, patientState, fetchEncounters, orgOverride, bookingOrg?.id]);

  // Single answers object for the guided flow (Tasks 7-9 render the remaining steps off this).
  const [flowAnswers, setFlowAnswers] = useState<BookingAnswers>({});

  // handleEditStep is defined further down (after clearSelectedPractitioner, which it now calls) - see
  // that definition for the full rationale. Kept out of this spot because it needs clearSelectedPractitioner
  // in its dependency array, and that callback isn't declared until later in this component.

  // THE RECORD DECIDES THIS, NOT THE PATIENT. It used to read flowAnswers.patientType - what the
  // patient said about themselves in step 0.
  const restrictToNewPatientExam =
    requireNewPatientExamGate && derivedPatientType === "new";

  // The patient no longer picks an appointment type (it's receptionist-owned). A self-booking online is
  // a scheduled/routine visit (the "how they came in" modality) - always ROUTINE; the receptionist can
  // refine to walk-in/emergency on confirm. serviceType is written from the chosen service's own type.
  useEffect(() => {
    setValue("appointmentType", "ROUTINE", { shouldValidate: true });
    setValue("serviceType", [], { shouldValidate: true });
  }, [setValue]);

  // HOW MANY OTHER PRACTITIONERS THE PATIENT COULD STILL BOOK IS AN ARGUMENT, NOT A CLOSURE.
  // The candidate list is derived several hundred lines below this, so closing over it here would put
  // a const in this dependency array before its own declaration has run - a temporal dead zone error
  // on every render, not a subtle one. Both call sites are below that list and pass it in.
  const buildSelfBookingGuardMessage = useCallback(
    (appointment: Appointment | undefined, otherPractitionersAvailable: number): string => {
      const appointmentStart = appointment?.start
        ? new Date(appointment.start)
        : undefined;
      const appointmentDate =
        appointmentStart && !Number.isNaN(appointmentStart.getTime())
          ? appointmentStart.toLocaleString(undefined, {
              weekday: "long",
              year: "numeric",
              month: "long",
              day: "numeric",
              hour: "numeric",
              minute: "2-digit",
            })
          : undefined;

      return selfBookingGuardText({
        practitionerName: selectedPractitionerName,
        existingStartLabel: appointmentDate,
        organizationName,
        organizationPhone,
        otherPractitionersAvailable,
      });
    },
    [organizationName, organizationPhone, selectedPractitionerName],
  );

  const showSelfBookingGuardMessage = useCallback(
    (appointment: Appointment | undefined, otherPractitionersAvailable: number) => {
      toast.error(buildSelfBookingGuardMessage(appointment, otherPractitionersAvailable), {
        position: "top-right",
        duration: 8000,
      });
    },
    [buildSelfBookingGuardMessage],
  );

  const refreshSelfBookingConflict = useCallback(
    async (
      practitionerId: string | undefined = practitioner?.id,
      practitionerRoleIds: string[] = practitionerRole?.id
        ? [practitionerRole.id]
        : [],
    ): Promise<Appointment | undefined> => {
      if (!patientState || !practitionerId) {
        return undefined;
      }

      const latestAppointments = refreshAwayAppointments
        ? await refreshAwayAppointments()
        : filterAndUnpackBundle(await fetchAppointments(patientState), "Appointment") as Appointment[];
      if (!refreshAwayAppointments) setAppointmentsList(latestAppointments);

      return getActiveFutureAppointmentForPractitioner(
        practitionerId,
        practitionerRoleIds,
        latestAppointments,
        chosenServiceCap.limit,
        chosenServiceCap.codingKey,
      );
    },
    [
      fetchAppointments,
      filterAndUnpackBundle,
      getActiveFutureAppointmentForPractitioner,
      patientState,
      practitioner?.id,
      practitionerRole?.id,
      setAppointmentsList,
      refreshAwayAppointments,
    ],
  );

  // A ROUTE guard, and it only makes sense on the route. Mounted as a dialog from a patient's chart
  // the caller is staff, no workspace of theirs is in this list, and the hook redirected to '/' - so
  // clicking "Book Appointment" inside a patient record threw the user out of the record entirely,
  // four pushes deep, landing on their own dashboard with no dialog and no explanation.
  useRouteAuthorization({
    allowedRoles: [USER_ROLES.PATIENT, USER_ROLES.RELATED_PERSON],
    enabled: !embedded,
  });

  const { loading: sharedSchedulesLoading } = useFhirSchedules({ autoLoad: !awayOrganization });
  useFhirScheduleBroadcast();
  const { loading: sharedPractitionersLoading } = useFhirPractitioners({ autoLoad: !awayOrganization });
  useFhirPractitionerRoleBroadcast();
  useFhirAppointments({ autoLoad: !awayOrganization });
  const schedulesLoading = away ? away.loading : sharedSchedulesLoading;
  const practitionersLoading = away ? away.loading : sharedPractitionersLoading;
  // Hold the selection cascade behind a single skeleton while the schedule + practitioner data loads, so the
  // fields appear together instead of Reason/Practitioner popping in a second before Care type/Location.
  const isBookingDataLoading = schedulesLoading || practitionersLoading;

  // useFhirAppointmentBroadcast({
  // onCreate: (createdAppointment) => {
  // setAppointmentsList((prev) => [...prev, createdAppointment]);
  // },
  // onUpdate: (updatedAppointment) => {
  // setAppointmentsList((prev) =>
  // prev.map((p) =>
  // p.id === updatedAppointment.id ? updatedAppointment: p,
  // ),
  // );
  // },
  // onDelete: (deletedAppointment) => {
  // setAppointmentsList((prev) =>
  // prev.filter((p) => p.id !== deletedAppointment.id),
  // );
  // },
  // });

  // The distinct booking Schedules whose union availability falls on a given date. A multi-location
  // practitioner booked under "Any location" can have a different location-scoped Schedule per date (or
  // even an AM/PM split across two sites on one date), so busy-Slot loading must target the block(s) that
  // OWN the selected date - not the single representative schedule. Derived from the tagged union events;
  // falls back to the representative schedule defensively if the tags didn't resolve.
  const getSchedulesForDate = useCallback(
    (dateStr: string): Schedule[] => {
      const scheduleIds = new Set<string>();
      for (const event of availabilityEvents) {
        if (formatDateOnly(new Date(event.start)) !== dateStr) continue;
        if (event.block.scheduleId) scheduleIds.add(event.block.scheduleId);
      }
      const result: Schedule[] = [];
      for (const id of scheduleIds) {
        const found = schedulesList.find((s) => s.id === id);
        if (found) result.push(found);
      }
      if (result.length === 0 && selectedSchedule) result.push(selectedSchedule);
      return result;
    },
    [availabilityEvents, schedulesList, selectedSchedule],
  );

  // Load busy Slots for the selected date across every block that owns that date (see getSchedulesForDate),
  // merging them - under the non-overlapping-block invariant the merged busy ranges are correct (an AM
  // site's busy slot only overlaps AM-available grid times, and vice versa).
  // Each block's busy Slots and the practitioner's held time anywhere, read together and keyed on the blocks, the
  // date, the patient's clock and the practice: an answer for an earlier choice is never this one's, and a failed
  // read offers nothing. A refresh reads the same key again.
  const [busyAttempt, setBusyAttempt] = useState(0);
  const busySchedules = useMemo(
    () => (watchDate ? getSchedulesForDate(watchDate) : []),
    [watchDate, getSchedulesForDate],
  );
  const busyKey = watchDate && selectedSchedule && busySchedules.length > 0
    ? `${busySchedules.map((schedule) => schedule.id).join(",")}|${watchDate}|${viewerTimeZone()}|${orgOverride ?? ""}`
    : undefined;
  const readBusy = useCallback(
    async (key: string) => {
      // The patient's list draws the date on their own clock, and heldRangesOnDate reads the holds on it, so
      // the read is that local day: a UTC day ended at 7 PM in Chicago and dropped the evening's holds.
      const [, date, clock] = key.split("|");
      const { start, end } = slotReadWindow(date, [clock]);
      try {
        return await readBusyTimes(busySchedules, start, end, {
          fetchSlots, fetchHeldTimes, unpack: (bundle) => filterAndUnpackBundle(bundle, "Slot") as Slot[],
        }, orgOverride);
      } catch (error) {
        console.error("Failed to load slots:", error);
        throw error;
      }
    },
    [busySchedules, fetchSlots, fetchHeldTimes, filterAndUnpackBundle, orgOverride],
  );
  const busyRead = useKeyedRead(busyKey, readBusy, busyAttempt);
  const slots = useMemo(() => (busyRead.status === "ready" ? busyRead.value.slots : []), [busyRead]);
  const heldTimes = useMemo(() => (busyRead.status === "ready" ? busyRead.value.held : []), [busyRead]);
  const loading = busyRead.status === "pending";
  const loadSlots = useCallback((_date?: string) => setBusyAttempt((attempt) => attempt + 1), []);

  // Handle schedule change (practitioner selection). `options.silent` skips the `flowAnswers.practitioner`
  // write - used only by the single-remaining-practitioner auto-select effect below, so an auto-locked step
  // stays locked (bookingFlowSteps.ts resolves `answered, editable: true` the moment `answers.practitioner`
  // is truthy, which would otherwise flip the lock off and drop its stated reason on the very next render).
  const handleScheduleChange = (
    scheduleId: string,
    options?: { silent?: boolean },
  ) => {
    const schedule = schedulesList.find((s) => s.id === scheduleId);
    if (!schedule) return;

    const practitionerRoleRef: Reference | undefined = schedule?.actor?.find(
      (ref: Reference) => extractReferenceType(ref) === "PractitionerRole",
    );

    if (!practitionerRoleRef?.reference) {
      toast.error("Practitioner role not found.", { position: "top-right" });
      return;
    }

    const practitionerRoleId = extractReferenceId(practitionerRoleRef);
    const practitionerWithRoles = practitionersList.find(
      (practitionerWithRoles) =>
        practitionerWithRoles.roles.some(
          (role) => role.id === practitionerRoleId,
        ),
    );

    if (!practitionerWithRoles) {
      toast.error("Practitioner role not found.", { position: "top-right" });
      return;
    }

    const selectedPractitionerRole = practitionerWithRoles.roles.find(
      (role) => role.id === practitionerRoleId,
    ) as PractitionerRole;
    const selectedPractitioner = practitionerWithRoles.practitioner;

    setSelectedSchedule(schedule);
    setPractitionerRole(selectedPractitionerRole);
    setPractitioner(selectedPractitioner);
    if (!options?.silent) {
      setFlowAnswers((prev) => ({ ...prev, practitioner: scheduleId }));
    }

    // A practitioner change invalidates any previously selected date/time and review state.
    setValue("practitionerId", scheduleId, { shouldValidate: true });
    setValue("date", "", { shouldValidate: true });
    setValue("startTime", "", { shouldValidate: true });
    setValue("endTime", "", { shouldValidate: true });
    setSelectedDate(null);
    setFormDataForSubmission(null);
    setReviewStep(1);

    // Update selected practitioner display
    const fullName = formatFhirHumanName(selectedPractitioner.name, { emptyText: '' });

    setSelectedPractitioner({
      name: fullName,
      role: practitionerRoleRef.display || "Practitioner",
      image: `https://i.pravatar.cc/100?u=${selectedPractitioner.id}`,
    });

    // Availability is the UNION of every location-scoped block this practitioner works that still matches
    // the current service/location filters (, Finding B). Under "Any location" a practitioner can
    // have one Schedule per site; pinning availability to the picked representative block hid the other
    // sites' dates/times. Gather all matching blocks (same service/location/new-patient-exam scope the
    // practitioner list itself uses), convert each block's Date availability windows to local-ISO, union
    // them, and tag each window with its block for slot->block resolution (Task 4) + site labels (Task 5).
    // Filter to 'availability' events only: getScheduleAvailabilityEvents also returns 'not-available'
    // (time-off) background events, which must NOT count as bookable. The representative
    // selectedSchedule/Role stay set above for the single-schedule scaffolding (display, loadSlots fallback).
    const practitionerId = selectedPractitioner.id;
    const matchingBlockSchedules = practitionerId
      ? schedulesMatching({
          service: selectedServiceFilter,
          location: selectedLocationFilter,
          practitionerId,
        })
      : [];
    // Defensive: always union at least the picked block, even if the match set somehow came back empty.
    const blockSchedules =
      matchingBlockSchedules.length > 0 ? matchingBlockSchedules : [schedule];

    const perBlock = blockSchedules
      .map((blockSchedule) => {
        const blockRole = getScheduleRole(blockSchedule);
        const events = blockWindowsFor(blockSchedule);
        if (!blockRole?.id || !events) return undefined;
        // Resolve the block's location ref ( review, Findings A+B). Today's model is one
        // location per block, so `[0]` and the filter-matched entry coincide in practice - but when a
        // specific site is selected, prefer the entry that actually matches it (hardens against a
        // legacy multi-location role with no Schedule Location actor) rather than blindly taking the
        // first. Then backfill a display the same way locationSiteOptions does (ref display -> org
        // location name by id -> bare id): downstream readers (isMultiSiteAnyLocation, availableDates,
        // availableTimeOptions, the review-step site row) all read `block.locationRef?.display` with no
        // fallback of their own, so an actor ref with no `display` would otherwise blank the site label
        // everywhere even though the booking's `reference` is still correct.
        const blockLocationRefs = getScheduleLocationRefs(blockSchedule, blockRole);
        const chosenLocationRef =
          selectedLocationFilter && selectedLocationFilter !== ANY_LOCATION
            ? (blockLocationRefs.find(
                (l) => l.reference?.split("/").pop() === selectedLocationFilter,
              ) ?? blockLocationRefs[0])
            : blockLocationRefs[0];
        const block: BookingBlock = {
          scheduleId: blockSchedule.id as string,
          practitionerRoleId: blockRole.id,
          locationRef: chosenLocationRef
            ? {
                reference: chosenLocationRef.reference,
                display:
                  chosenLocationRef.display ||
                  locationsList.find(
                    (loc) =>
                      loc.id === chosenLocationRef.reference?.split("/").pop(),
                  )?.name ||
                  chosenLocationRef.reference?.split("/").pop(),
              }
            : undefined,
          serviceRef: selectedServiceFilter
            ? getScheduleSelfBookableServices(blockSchedule).find(
                (svc) => svc.id === selectedServiceFilter,
              )
            : undefined,
        };
        return { block, events };
      })
      .filter(
        (
          entry,
        ): entry is { block: BookingBlock; events: AvailabilityWindow[] } =>
          entry !== undefined,
      );

    const union = buildUnionAvailability(perBlock);
    setAvailabilityEvents(union.events);
    resolveBlockForSlotRef.current = union.resolveBlockForSlot;

    // The self-booking guard must check EVERY location's role, not just the representative one, so an
    // existing appointment booked at another site is still caught. (findActiveFutureAppointmentForPractitioner
    // matches on Practitioner OR any of these role refs; the Practitioner id alone already catches
    // self-bookings, but passing all roles keeps the role-only match path complete too.)
    const matchingRoleIds = Array.from(
      new Set(
        blockSchedules
          .map((blockSchedule) => getScheduleRole(blockSchedule)?.id)
          .filter((id): id is string => Boolean(id)),
      ),
    );

    const guardRequestId = selfBookingGuardRequestRef.current + 1;
    selfBookingGuardRequestRef.current = guardRequestId;
    setCheckingSelfBookingGuard(true);

    void refreshSelfBookingConflict(
      selectedPractitioner.id,
      matchingRoleIds.length > 0
        ? matchingRoleIds
        : selectedPractitionerRole.id
          ? [selectedPractitionerRole.id]
          : [],
    )
      .catch((error) => {
        if (selfBookingGuardRequestRef.current !== guardRequestId) {
          return;
        }

        console.error("Failed to verify existing appointments:", error);
        toast.error(
          "Unable to verify your existing appointments. They will be checked again before booking.",
          { position: "top-right" },
        );
      })
      .finally(() => {
        if (selfBookingGuardRequestRef.current === guardRequestId) {
          setCheckingSelfBookingGuard(false);
        }
      });
  };

  // WebSocket subscriptions
  useEffect(() => {
    const handleScheduleEvent = (cloudEvent: FhirCloudEvent<Schedule>) => {
      const schedule: Schedule = cloudEvent.data;
      if (schedule.id === selectedSchedule?.id) {
        // Update schedule if needed
        const index = schedulesList.findIndex((s) => s.id === schedule.id);
        if (index !== -1) {
          // Schedule updated, you may want to refresh the list
        }
      }
    };

    subscribe(
      "com.akashichealthrecords.fhir.schedule.updated",
      handleScheduleEvent,
    );
    return () => {
      unsubscribe(
        "com.akashichealthrecords.fhir.schedule.updated",
        handleScheduleEvent,
      );
    };
  }, [subscribe, unsubscribe, selectedSchedule, schedulesList]);

  useEffect(() => {
    const handlePractitionerRoleEvent = (
      cloudEvent: FhirCloudEvent<PractitionerRole>,
    ) => {
      const practitionerRolePayload: PractitionerRole = cloudEvent.data;
      if (practitionerRolePayload.id === practitionerRole?.id) {
        setPractitionerRole(practitionerRolePayload);
        // Reload slots if date is selected
        if (watchDate) {
          loadSlots(watchDate);
        }
      }
    };

    subscribe(
      "com.akashichealthrecords.fhir.practitionerrole.updated",
      handlePractitionerRoleEvent,
    );
    return () => {
      unsubscribe(
        "com.akashichealthrecords.fhir.practitionerrole.updated",
        handlePractitionerRoleEvent,
      );
    };
  }, [subscribe, unsubscribe, practitionerRole, loadSlots, watchDate]);

  useEffect(() => {
    const handleSlotEvent = (cloudEvent: FhirCloudEvent<Slot>) => {
      const slot: Slot = cloudEvent.data;
      // const eventType = cloudEvent.type;
      const slotScheduleId = extractReferenceId(slot.schedule);

      // A multi-location practitioner's selected date can be owned by a non-representative block, so
      // refresh when the slot belongs to ANY block that owns the current date (not just selectedSchedule).
      if (
        watchDate &&
        getSchedulesForDate(watchDate).some((s) => s.id === slotScheduleId)
      ) {
        // Refresh slots for the current date
        loadSlots(watchDate);
      }
    };

    subscribe("com.akashichealthrecords.fhir.slot.created", handleSlotEvent);
    subscribe("com.akashichealthrecords.fhir.slot.updated", handleSlotEvent);
    subscribe("com.akashichealthrecords.fhir.slot.deleted", handleSlotEvent);

    return () => {
      unsubscribe(
        "com.akashichealthrecords.fhir.slot.created",
        handleSlotEvent,
      );
      unsubscribe(
        "com.akashichealthrecords.fhir.slot.updated",
        handleSlotEvent,
      );
      unsubscribe(
        "com.akashichealthrecords.fhir.slot.deleted",
        handleSlotEvent,
      );
    };
  }, [
    getSchedulesForDate,
    extractReferenceId,
    subscribe,
    unsubscribe,
    watchDate,
    loadSlots,
  ]);


  // Sync selectedDate with watchDate
  useEffect(() => {
    if (watchDate && !selectedDate) {
      // Parse the YYYY-MM-DD as a LOCAL date. `new Date("YYYY-MM-DD")` parses as UTC midnight, which in
      // US timezones lands on the PREVIOUS day - that made the first date pick compute times for the wrong
      // (non-working) day and show "no open times" until the date was re-picked.
      const [y, mo, d] = watchDate.split("-").map(Number);
      setSelectedDate(new Date(y, mo - 1, d));
    } else if (!watchDate && selectedDate) {
      // If watchDate is cleared but selectedDate exists, clear selectedDate
      setSelectedDate(null);
    }
  }, [watchDate, selectedDate]);

  // Busy [startMin, endMin) ranges (minutes-of-day) for the selected date. Interval-based, NOT start-keyed,
  // so a longer appointment (e.g. 60 min booked at 9:00) blocks every grid start it overlaps (9:15/9:30/9:45),
  // not just 9:00.
  const getBusyRangesForDate = useMemo(() => {
    if (!watchDate) return [] as { startMin: number; endMin: number }[];
    // On the patient's clock and the patient's day, the same as the list they are checked against. The
    // practitioner's held time anywhere counts as busy beside this practice's own Slots.
    return heldRangesOnDate([...slots, ...heldAsBusy(heldTimes)], watchDate);
  }, [slots, heldTimes, watchDate]);

  // Site labels in the date/time picker ( §3.3.1) are only meaningful when the patient chose "Any
  // location" AND the practitioner's union of blocks actually spans more than one distinct site - a
  // specific-location pick or a single-site practitioner would make every label redundant noise. Gate
  // once here (identity = block.locationRef.display, matching what the labels themselves show) and reuse
  // it in both availableDates and availableTimeOptions below.
  const isMultiSiteAnyLocation = useMemo(() => {
    if (selectedLocationFilter !== ANY_LOCATION) return false;
    const distinctSites = new Set<string>();
    for (const event of availabilityEvents) {
      const site = event.block.locationRef?.display;
      if (site) distinctSites.add(site);
    }
    return distinctSites.size > 1;
  }, [selectedLocationFilter, availabilityEvents]);

  // Review step (Step 3, §3.3.1): reconfirm the resolved site + service for the picked slot -
  // belt-and-suspenders for the picker labels above, and the only correct source under "Any location"
  // since block.locationRef is the SITE the slot actually belongs to (wpOrganization is the org, not a
  // site). Recomputed whenever the picked date/time changes. Undefined (falls through to the org name /
  // selected-service-filter display below) when no block resolves - the pre-Task-3 single-block path, or
  // before a date/time is chosen - so single-schedule bookings render exactly as before.
  const reviewResolvedBlock = useMemo(
    () =>
      watchDate && watchStartTime
        ? resolveBlockForSlotRef.current?.(watchDate, watchStartTime)
        : undefined,
    [watchDate, watchStartTime],
  );

  // Distinct future dates the practitioner is available (from the schedule's availability windows), for the
  // Date select. availabilityEvents are already filtered to real availability, so time-off days and
  // non-working weekdays never appear.
  const availableDates = useMemo(() => {
    if (availabilityEvents.length === 0) return [];
    const todayStart = new Date();
    todayStart.setHours(0, 0, 0, 0);
    const now = new Date();
    // Group by date value in a single pass so the site label below can look at EVERY event on a date, not
    // just the first one encountered for it.
    const dayByDate = new Map<string, Date>();
    const sitesByDate = new Map<string, Set<string>>();
    for (const event of availabilityEvents) {
      const day = new Date(event.start);
      day.setHours(0, 0, 0, 0);
      if (day < todayStart) continue;
      const value = formatDateOnly(day);
      // - A DAY WHOSE HOURS ARE OVER IS NOT AN AVAILABLE DATE.
      //
      // Observed at ~22:30: this list offered today as its FIRST selectable date, while the staff
      // picker had already ruled the same day out. The test above is the only one that used to run, and
      // it asks whether the date is in the PAST - nothing here ever consulted the clock WITHIN today, so
      // a 9-to-5 day stayed on offer all evening. A patient picked it and every time came back empty.
      //
      // THIS IS THE MOST HARMFUL OF THE THREE SURFACES, which is why it is the one that changed
      // behaviour rather than wording: the patient-facing list was the most permissive, so it is the one
      // that invites an appointment nobody can honour.
      //
      // It calls the SAME rule the staff picker calls, deliberately. Two date pickers deriving
      // "bookable" separately is the whole of this card, and `reassignFeasibility` already keeps that rule
      // identical on purpose.
      if (!dateHasBookableWindow(value, availabilityEvents, { now, durationMinutes: appointmentDurationMinutes })) {
        continue;
      }
      if (!dayByDate.has(value)) dayByDate.set(value, day);
      const site = event.block.locationRef?.display;
      if (site) {
        if (!sitesByDate.has(value)) sitesByDate.set(value, new Set());
        sitesByDate.get(value)!.add(site);
      }
    }
    const dates: { value: string; label: string }[] = [];
    for (const [value, day] of dayByDate) {
      let label = day.toLocaleDateString(undefined, {
        weekday: "short",
        month: "short",
        day: "numeric",
        year: "numeric",
      });
      // Only under "Any location" + a genuinely multi-site practitioner: single-site dates get the site
      // name, dates spanning more than one site defer to the per-time labels (Step 2 below).
      if (isMultiSiteAnyLocation) {
        const siteList = Array.from(sitesByDate.get(value) ?? []);
        if (siteList.length === 1) {
          label += ` · ${siteList[0]}`;
        } else if (siteList.length > 1) {
          label += " · multiple sites";
        }
      }
      dates.push({ value, label });
    }
    dates.sort((a, b) => a.value.localeCompare(b.value));
    return dates;
  }, [availabilityEvents, isMultiSiteAnyLocation]);

  // Bookable start times for the selected date, for the Time select: the 30-minute grid filtered to slots
  // that fit an availability window (duration-aware) and are not already busy - the same rule the old pill
  // grid used.
  // Is the patient on a different clock from the practice, and what is their clock called?
  //
  // WITHOUT THIS THE CONVERSION IS MORE DANGEROUS THAN THE BUG IT FIXES. Every time on this screen
  // is now shown in the PATIENT's timezone (option B, Spencer 2026-08-10). A Californian booking an
  // Iowa practice sees "7:00 AM" - correct, and indistinguishable from the practice's 7:00 AM unless
  // we say which clock it is on. A silent conversion just moves the misunderstanding.
  //
  // Only shown when the clocks actually DIFFER, compared by offset rather than zone name: a notice
  // that appears for everyone is a notice nobody reads, and America/Detroit vs America/New_York is not
  // a difference worth interrupting anyone about.
  // Decided per visit, after the slot zones below are known: see viewerZoneNotice there.

  const availableTimeOptions = useMemo(() => {
    if (!selectedDate) return [];
    // Nothing is offered until the busy times are known: pending or failed is not free.
    if (busyRead.status !== "ready") return [];
    const dateStr = formatDateOnly(selectedDate);
    const to12h = (t: string) => {
      const [h, m] = t.split(":").map(Number);
      const period = h >= 12 ? "PM" : "AM";
      const displayHours = h % 12 || 12;
      return `${displayHours}:${m.toString().padStart(2, "0")} ${period}`;
    };
    // Site labels on individual times ( §3.3.1) are only worth showing when THIS date itself spans
    // more than one site - a single-site date already carries the site on its date label (Step 1 above), so
    // repeating it per time would be redundant. Determine that once, up front, from the date's own tagged
    // events (a subset of the overall isMultiSiteAnyLocation gate).
    let dateSpansMultipleSites = false;
    if (isMultiSiteAnyLocation) {
      const sitesForDate = new Set<string>();
      for (const event of availabilityEvents) {
        if (formatDateOnly(new Date(event.start)) !== dateStr) continue;
        const site = event.block.locationRef?.display;
        if (site) sitesForDate.add(site);
      }
      dateSpansMultipleSites = sitesForDate.size > 1;
    }
    /*
 * THE GRID IS GENERATED FROM THE BLOCKS, NOT FILTERED OUT OF A FIXED LADDER.
 *
 * This used to walk `TIME_SLOTS` - a hand-typed 24-hour table of half-hours from 06:00 to 05:30 -
 * and keep the ones that survived the availability check. Two things followed from that, and both
 * were measured on journey C1: every practice was offered THIRTY whatever it had chosen (23 slots on
 * an empty day, all 22 gaps exactly 30 minutes, zero quarter-hours, and identical across two bundles
 * because nothing in it could vary), and the candidate times were the ladder's rather than the
 * practice's own hours.
 *
 * Ruled 2026-09-06: the increment is set on the practitioner's SCHEDULE BLOCK - 10, 15, 20 or 30 -
 * appointment length comes from the service, and the practice default is 15. So the candidates come
 * from each window at ITS OWN block's increment, which is also why this is per-window rather than one
 * increment for the day: an "Any location" date can span two blocks that made different choices.
 *
 * THE FILTERS BELOW ARE UNCHANGED AND STILL DO THE WORK THEY DID. Generating a start time says only
 * that the block offers it; whether the SERVICE fits before the window closes, and whether the slot
 * is already taken, are the same two questions asked the same way. Nothing here is duration-aware -
 * that would quietly make the grid service-specific in a memo that does not depend on the service.
 */
    const options: { value: string; label: string }[] = [];
    const seen = new Set<string>();

    for (const event of availabilityEvents) {
      if (formatDateOnly(new Date(event.start)) !== dateStr) continue;

      const block = schedulesList.find((schedule) => schedule.id === event.block?.scheduleId);
      const increment = getScheduleSlotIncrement(block);

      // Local-ISO strings by construction (see toLocalIso), so the wall-clock time is the substring -
      // parsing to a Date and back would reintroduce the timezone question this format exists to settle.
      const from = String(event.start).slice(11, 16);
      // Through windowEndOnDay so an all-day window, which closes at the NEXT midnight, is not
      // reduced to the same 00:00 it opened at and read as an inside-out range.
      const to = windowEndOnDay(
        dateStr,
        String(event.end).slice(0, 10),
        String(event.end).slice(11, 16),
      );

      for (const slot of slotStartTimes(from, to, increment)) {
        // Two windows on one day can overlap - the same start time offered by two blocks is one
        // choice to a patient, not two identical rows.
        if (seen.has(slot)) continue;
        if (isTimeSlotBooked(slot, getBusyRangesForDate, appointmentDurationMinutes)) continue;
        if (
          !isTimeSlotAvailable(
            slot,
            dateStr,
            availabilityEvents,
            appointmentDurationMinutes,
          )
        )
          continue;
        seen.add(slot);
        let label = to12h(slot);
        if (dateSpansMultipleSites) {
          const site = resolveBlockForSlotRef.current?.(dateStr, slot)?.locationRef?.display;
          if (site) label += ` · ${site}`;
        }
        options.push({ value: slot, label });
      }
    }

    // The ladder was already in order; generated windows are not, because a day's blocks arrive in
    // whatever order the search returned them.
    options.sort((left, right) => left.value.localeCompare(right.value));
    return options;
  }, [
    selectedDate,
    busyRead.status,
    getBusyRangesForDate,
    availabilityEvents,
    appointmentDurationMinutes,
    isMultiSiteAnyLocation,
    schedulesList,
  ]);

  // A picked time is actionable only while the current read is ready and still offers it. A newer read that no
  // longer offers it retires the pick; a failed read retires the plan reviewed from it. Never during or after the send.
  const pickStanding = pickedTimeStanding(busyRead.status, watchStartTime, availableTimeOptions.map((option) => option.value));
  const pickedTimeIsOffered = pickStanding === "actionable";
  // The read and pick as the page stands now, for a Confirm already past its awaits. A new object on every change of
  // read, standing or pick, so a Confirm holding the old one is retired even when the same day and time come back.
  const busyEpoch = `${busyKey ?? ""}|${busyAttempt}`;
  const sendStandingRef = useRef<SendStanding>({ epoch: busyEpoch, standing: pickStanding, picked: watchStartTime });
  sendStandingRef.current = nextSendStanding(sendStandingRef.current, { epoch: busyEpoch, standing: pickStanding, picked: watchStartTime });
  // The one way a pick is let go: the time, its end and the flow's time answer, keeping the date it was on.
  const clearPickedTime = useCallback(() => {
    setValue("startTime", "", { shouldValidate: true });
    setValue("endTime", "", { shouldValidate: true });
    setFlowAnswers((prev) => {
      const next = { ...prev };
      delete next.time;
      return next;
    });
  }, [setValue]);
  useEffect(() => {
    if (submitting || reviewStep === 3 || (pickStanding !== "retire-pick" && pickStanding !== "retire-plan")) return;
    if (pickStanding === "retire-pick") clearPickedTime();
    setFormDataForSubmission(null);
    setReviewStep(1);
  }, [pickStanding, submitting, reviewStep, clearPickedTime]);

  const livePractitioners = useMemo(
    () => practitionersList.map((item) => item.practitioner),
    [practitionersList],
  );

  const getScheduleRole = useCallback((schedule: Schedule): PractitionerRole | undefined => {
    const roleRef = schedule.actor?.find((a) => extractReferenceType(a) === "PractitionerRole");
    if (!roleRef) return undefined;
    const roleIdRaw = extractReferenceId(roleRef);
    const roleId = Array.isArray(roleIdRaw) ? roleIdRaw[0] : roleIdRaw;
    if (!roleId) return undefined;
    for (const item of practitionersList) {
      const role = item.roles.find((r) => r.id === roleId);
      if (role) return role;
    }
    return undefined;
  }, [extractReferenceId, extractReferenceType, practitionersList]);

  const seatStanding = useSeatStanding();
  const bookableSchedules = useMemo(
    () =>
      schedulesList.filter((s) => {
        const flags = getScheduleBookingFlags(s);
        if (!(Boolean(s.id) && flags.allowBooking && flags.allowPatientSelfBooking)) return false;
        // Exclude schedules owned by a deactivated practitioner (their PractitionerRole.active === false).
        // The schedule itself is preserved and reappears automatically once they're reactivated.
        const role = getScheduleRole(s);
        if (role && role.active === false) return false;
        // AND EXCLUDE ANYBODY WITHOUT A CLINICIAN SEAT - the same gate the front desk now applies, from
        // the same helper. The per-service self-booking flag decides which SERVICES a patient may book
        // and never which PEOPLE can perform them, so this hole was patient-facing too.
        return canBeBookedAsClinician(s, role, seatStanding);
      }),
    [schedulesList, getScheduleRole, seatStanding],
  );

  // The self-bookable services offered by a schedule's practitioner, read from the practitioner's
  // PractitionerRole.healthcareService (the Services Offered tab - where the org assigns services AND the
  // per-practitioner self-bookable override live). Self-bookable resolves from the ref-level override first
  // (always readable on the role the patient already has), falling back to the HealthcareService org default
  // ONLY when the catalog is loaded, else default-on - so the picker does NOT hard-depend on the patient being
  // able to fetch the HealthcareService catalog. Name comes from the catalog when loaded, else the ref display.
  // Delegates to the pure module (utils/booking/scheduleSelfBookableServices), which the staff-side
  // bookability context reads too - one implementation, so a staff surface can never resolve self-bookable
  // differently from what this screen offers a patient.
  const getScheduleSelfBookableServices = useCallback(
    (schedule: Schedule): { id: string; display: string }[] =>
      servicesUnverified ? [] : resolveScheduleSelfBookableServices(schedule, getScheduleRole(schedule), serviceById, { catalogueComplete: true }),
    [getScheduleRole, serviceById, servicesUnverified],
  );

  // Location a schedule is for: the Schedule's own Location actor (new model), falling back to the role's
  // location for schedules saved before location moved onto the Schedule.
  // - reads EVERY Location actor, not just the first. This used to be
  // `getScheduleLocationReference(schedule)` (a `.find`), wrapped in an array. A schedule can now carry
  // two locations - the physical site AND the org's virtual one when the block offers video - so taking
  // only the first meant a block that had explicitly opted into video reported just its physical site.
  // The telehealth gate then raised NO_VIRTUAL_LOCATION_ON_BLOCK against a block that HAD opted in, and
  // patient video booking was impossible. The staff context never had this bug: it already filtered all
  // Location actors, so the two halves of one contract disagreed.
  //
  // The role fallback is unchanged and still matters: blocks saved before location moved onto the
  // Schedule carry it on the PractitionerRole instead.
  const getScheduleLocationRefs = useCallback((schedule: Schedule, role?: PractitionerRole) => {
    const scheduleLocationRefs = getScheduleLocationReferences(schedule);
    return scheduleLocationRefs.length > 0 ? scheduleLocationRefs : (role?.location ?? []);
  }, []);

  // A service satisfies the new-patient gate by its SNOMED type, whatever the practice named it.
  const isConsultationService = useCallback(
    (serviceId: string): boolean => isNewPatientConsultationType(serviceById.get(serviceId)?.type),
    [serviceById],
  );

  // Shared filter over bookableSchedules - service/location/practitioner are each applied only when
  // provided, so every derived option list can drop its OWN axis and narrow by the other two. This is
  // what makes the three selects bidirectionally cross-filtered instead of a fixed
  // service -> location -> practitioner chain: picking any one of them narrows what the other two offer,
  // in any order. `location` treats both '' (nothing chosen) and ANY_LOCATION (explicitly "no
  // preference") as "no location constraint" - the sentinel only matters to the UI, never here.
  //
  // Delegates to the pure matchSchedules module (utils/booking/matchSchedules), which applies the
  // new-patient-exam gate INSIDE the match - not just to the practitioner list, as before, but to every
  // derived option list (service, location, practitioner, and the card-040 ranker candidates) - so a
  // location or service that leads to zero bookable practitioners is never offered in the first place.
  const scheduleMatchContext = useMemo<MatchContext>(() => ({
    anyLocation: ANY_LOCATION,
    examGate: {
      restrictToNewPatientExam,
      isConsultationService,
    },
    // - so the patient's option lists apply the SAME explicit-opt-in rule the resolver does:
    // the "all locations" wildcard must not cover the virtual location, or every org-wide block would
    // offer video without anyone opting in. Undefined when the org has no virtual Location, which makes
    // the whole thing inert.
    virtualLocationId: onlyVirtual(locationsList)[0]?.id,
    accessors: {
      selfBookableServices: getScheduleSelfBookableServices,
      roleId: (s) => getScheduleRole(s)?.id,
      locationIds: (s) => {
        const role = getScheduleRole(s);
        if (!role) return [];
        return getScheduleLocationRefs(s, role)
          .map((ref) => ref.reference?.split("/").pop())
          .filter((id): id is string => Boolean(id));
      },
      // Its Practitioner actor, else its role's practitioner: a schedule naming only the role is still that clinician's.
      practitionerId: (s) => schedulePractitionerId(s, getScheduleRole(s)),
      allowsNewPatientGeneralExam: (s) => Boolean(getScheduleBookingFlags(s).allowNewPatientGeneralExam),
    },
  }), [
    restrictToNewPatientExam, isConsultationService, getScheduleSelfBookableServices,
    getScheduleRole, getScheduleLocationRefs, extractReferenceType, getScheduleBookingFlags,
    locationsList,
  ]);

  const schedulesMatching = useCallback(
    (criteria: { service?: string; location?: string; practitionerId?: string }): Schedule[] =>
      matchSchedules(bookableSchedules, criteria, scheduleMatchContext),
    [bookableSchedules, scheduleMatchContext],
  );

  // The practitioner currently selected, if any - read from the FHIR Practitioner resource set alongside
  // selectedSchedule in handleScheduleChange (Task 3's territory; this only READS that selection so the
  // service/location option lists narrow to it once a practitioner is picked before a service/location).
  const currentPractitionerId = practitioner?.id;


  // Real, bookable sites - narrowed by the OTHER two active selections (service/practitioner). Kept
  // separate from locationFilterOptions (below) so the "how many real choices are there" branching in the
  // render doesn't count the synthetic "Any location" entry.
  const sitesOfferingService = useCallback((serviceId: string | undefined) => {
    const matches = schedulesMatching({ service: serviceId, practitionerId: currentPractitionerId });
    const seen = new Set<string>();
    const options: { id: string; display: string }[] = [];
    let hasAllLocationsRole = false;
    for (const schedule of matches) {
      const role = getScheduleRole(schedule);
      if (!role) continue;
      const roleLocations = getScheduleLocationRefs(schedule, role);
      // No explicit site refs anywhere (neither the schedule nor the role), so this practitioner is
      // bookable at the org's full location list below - but ONLY if the role actually says it covers
      // every site.: "nobody set this" and "covers everywhere" used to be the same value, and
      // offering a practitioner at every site because their record is incomplete is the booking-surface
      // form of that fail-open. `isOrgWideRole` still answers true for an empty array today, so this is
      // behaviour-identical until the backfill lands.
      if (roleLocations.length === 0) {
        if (isOrgWideRole(role)) hasAllLocationsRole = true;
        continue;
      }
      for (const locRef of roleLocations) {
        const locId = locRef.reference?.split("/").pop();
        if (!locId || seen.has(locId)) continue;
        seen.add(locId);
        options.push({ id: locId, display: locRef.display || locId });
      }
    }
    if (hasAllLocationsRole) {
      for (const loc of onlySites(locationsList)) {
        if (!loc.id || seen.has(loc.id)) continue;
        seen.add(loc.id);
        options.push({ id: loc.id, display: loc.name || loc.id });
      }
    }
    // - a practice that does not offer video should not be offered "Video visit" and then
    // refused. Shared with the receptionist picker so the two cannot drift.
    //
    // - and neither should a service that cannot be DELIVERED by video. Resolved per candidate
    // role rather than from the org default alone: lets a practitioner override eligibility for
    // a service their practice defaults off, so keying on the default would hide video from the one
    // practitioner who explicitly enabled it. Same rule, same helper, same quantifier as the
    // receptionist picker - this is the drift the shared module exists to prevent.
    const selectedService = serviceId ? serviceById.get(serviceId) : undefined;
    const serviceAllowsVideo =
      selectedService !== undefined &&
      matches.some((schedule) =>
        resolveServiceTelehealthEligible(selectedService, getScheduleRole(schedule)),
      );

    // Offered video reads as "Video visit", first, as the deck draws it - not as the virtual Location's own
    // name among the buildings, which is how a patient offered video concluded there was none.
    const virtualLocationId = onlyVirtual(locationsList)[0]?.id;
    const offerable = offerableLocationOptions(
      options,
      virtualLocationId,
      resolveOrgAppointmentPolicy(bookingOrg).telehealthEnabled,
      serviceAllowsVideo,
    );
    return videoVisitFirst(offerable, virtualLocationId);
  }, [schedulesMatching, getScheduleRole, getScheduleLocationRefs, currentPractitionerId, locationsList, bookingOrg, serviceById]);

  // "What type of care?" axis = the distinct self-bookable services offered across schedules matching the
  // OTHER two active selections (design §4) - narrowed by location/practitioner when either is already
  // chosen, so this list stays consistent with whatever the patient picked, in any order.
  const serviceFilterOptions = useMemo(() => {
    const options = offeredServices(
      schedulesMatching({ location: selectedLocationFilter, practitionerId: currentPractitionerId }),
      scheduleMatchContext,
    );
    /**
     * DOES THIS SERVICE REACH ANYWHERE IT CAN BE DELIVERED?
     *
     * A service whose only schedule block is the video block, and which cannot be done by video, narrows
     * to no site at all. The stripping is correct - a service that cannot be delivered by video must not
     * offer the virtual location - but until now the patient met the result of that correct rule three
     * steps later, as "Those options just changed. Please reselect.", with nothing on screen to reselect
     * and nothing having changed. Measured on the mount: two of this practice's six services did that.
     *
     * Answered HERE, where the patient chooses, and answered with the same function the location step
     * uses so the two steps cannot disagree.
     *
     * NOT FILTERED OUT. A patient who came to book an oral examination and cannot find it on the list
     * learns nothing and telephones to ask why - a screen that speaks by showing nothing cannot say which
     * of the reasons for nothing applies. It stays on the list, unpickable, saying why.
     */
    return options.map((option) => ({
      ...option,
      bookable: sitesOfferingService(option.id).length > 0,
    }));
  }, [schedulesMatching, selectedLocationFilter, currentPractitionerId, scheduleMatchContext, sitesOfferingService]);

  // One consult-typed service left for a patient not yet seen: the flow chooses it, under the practice's
  // own name, and books it as a real service so serviceType comes from that service's type.
  const pinnedConsultation =
    restrictToNewPatientExam && serviceFilterOptions.length === 1 ? serviceFilterOptions[0] : undefined;
  const pinnedServiceLabel = pinnedConsultation?.display;
  useEffect(() => {
    if (pinnedConsultation && selectedServiceFilter !== pinnedConsultation.id) {
      setSelectedServiceFilter(pinnedConsultation.id);
    }
  }, [pinnedConsultation, selectedServiceFilter]);

  /**
   * WHICH EMPTINESS THIS IS, when the service step has nothing on it.
   *
   * The screen used to answer all three with one sentence - "hasn't added any bookable services yet" -
   * and it was measured false at a practice whose catalogue was full: the first-visit gate had pinned
   * the choice to a new patient consultation that no open block offered. A patient was sent to
   * telephone a practice that had done nothing wrong, on the screen that exists to save that call.
   *
   * Read in the order the causes stack, so the patient is told the FIRST thing that is true rather than
   * the last: no block open to self-booking at all beats a block that lists no service, and the gate is
   * named ahead of both because when it binds it is the reason the other two look empty.
   *
   * The wording is in `nothingToOffer`, with the copy test that pins it out of office vocabulary.
   */
  const nothingToOffer = useMemo<NothingToOffer>(() => {
    if (restrictToNewPatientExam) return 'FIRST_VISIT_NOT_OFFERED';
    if (bookableSchedules.length === 0) return 'NO_SELF_BOOKABLE_SCHEDULE';
    return 'NO_SELF_BOOKABLE_SERVICE';
  }, [restrictToNewPatientExam, bookableSchedules]);

  /**
   * THE SITES FOR THE SERVICE THE PATIENT HAS ACTUALLY CHOSEN.
   *
   * Asked of the same function the service list asks, and that is the whole point of the extraction: a
   * service shown as bookable on one step and dead on the next is two answers to one question. This used
   * to be the only caller, computing the answer inline for the selected service alone, which is why
   * nothing upstream could tell a patient a service had nowhere to be delivered.
   */
  const locationSiteOptions = useMemo(
    () => sitesOfferingService(selectedServiceFilter),
    [sitesOfferingService, selectedServiceFilter],
  );

  // The Location select's actual item list: an explicit "Any location" choice first (an active pick that
  // means "no location preference", replacing the old passive "All Locations" default), then the real
  // sites.
  const locationFilterOptions = useMemo(
    () => [{ id: ANY_LOCATION, display: "Any location" }, ...locationSiteOptions],
    [locationSiteOptions],
  );

  /**
   * One block's bookable windows as local-ISO strings, or undefined when it names no role. The one reading
   * both the practitioner list and the chosen practitioner's availability use, so they cannot disagree.
   */
  const blockWindowsFor = useCallback((blockSchedule: Schedule): AvailabilityWindow[] | undefined => {
    const blockRole = getScheduleRole(blockSchedule);
    if (!blockRole?.id) return undefined;
    // THE CLOCK THIS BLOCK'S HOURS ARE WRITTEN IN - its own PHYSICAL site's. `onlySites`, never `[0]`: a
    // video-enabled block also carries the org's virtual Location, which has no clock. Undefined for an
    // "all locations" block with no site actor; ScheduleService then falls back to the organization.
    const blockSite = scheduleSiteFor(blockSchedule, blockRole, locationsList);
    // availabilityWindowsFor is the SHARED filter (utils/booking/scheduleYieldsTimes): it drops 'not-available'
    // (time-off) background events, so a staff "no open times" explanation agrees with what is offered here.
    return availabilityWindowsFor(
      getScheduleAvailabilityEvents(
        blockSchedule,
        transformFromFhirPractitionerRole(blockRole),
        blockSite,
        bookingOrg,
      ) as RawScheduleAvailabilityEvent[],
    ).map((event) => ({
      start: toLocalIso(event.start),
      end: toLocalIso(event.end),
    }));
  }, [getScheduleRole, locationsList, getScheduleAvailabilityEvents, transformFromFhirPractitionerRole, bookingOrg]);

  // For the practitioner dropdown, show each practitioner once even when they have multiple schedules
  // (a practitioner can now have one schedule per location). First schedule per practitioner is the
  // representative; a specific site is chosen via the Location filter above. Renamed from
  // dedupedPractitionerSchedules (Task 2, ); the multi-block availability union is Task 3.
  //
  // Derived from an explicit `schedulesMatching({ service, location })` with the PRACTITIONER axis dropped
  // (Task 3, resolving a Task-2 banked finding): its correctness no longer depends on the "this Select
  // only renders while no practitioner is selected" invariant. Once a practitioner IS picked, the union in
  // handleScheduleChange - not this list - drives availability, so pinning the option list to
  // service+location (not the selected practitioner) is exactly right.
  // A clinician is listed only when one of their matching blocks opens a window from today, the test the
  // "not currently available" notice applies once one is chosen; listing them first was a dead end.
  const practitionerOptions = useMemo(() => {
    const todayStart = new Date();
    todayStart.setHours(0, 0, 0, 0);
    const matching = schedulesMatching({
      service: selectedServiceFilter,
      location: selectedLocationFilter,
    });
    return offerablePractitionerSchedules(
      matching,
      (schedule) => schedulePractitionerId(schedule, getScheduleRole(schedule)),
      (practitionerId) => schedulesMatching({
        service: selectedServiceFilter,
        location: selectedLocationFilter,
        practitionerId,
      }).some((blockSchedule) => opensFrom(blockWindowsFor(blockSchedule) ?? [], todayStart)),
    );
  }, [
    schedulesMatching,
    selectedServiceFilter,
    selectedLocationFilter,
    extractReferenceType,
    blockWindowsFor,
    getScheduleRole,
  ]);

  /**
 * HOW MANY OTHER PRACTITIONERS OFFERING THIS VISIT THE PATIENT COULD STILL BOOK WITH.
 *
 * The refusal used to offer a telephone number and nothing else, in both of the two states it could
 * not tell apart: a colleague is free and the patient is one click away, or nobody is and the phone
 * really is the answer. It gave the second answer in both cases, which reads as a dead end in the
 * case that is not one.
 *
 * COUNTED FROM THE LIST THE PICKER ITSELF RENDERS, deliberately, so the sentence cannot promise a
 * choice the screen does not offer. Same guard, same patient appointments, so a colleague counted
 * here is a colleague who would actually be accepted.
 */
  const unblockedOtherPractitionerCount = useMemo(() => {
    const seen = new Set<string>();

    for (const schedule of practitionerOptions) {
      const candidateId = schedulePractitionerId(schedule, getScheduleRole(schedule));

      if (!candidateId || candidateId === practitioner?.id || seen.has(candidateId)) continue;
      if (getActiveFutureAppointmentForPractitioner(candidateId, [], undefined, chosenServiceCap.limit, chosenServiceCap.codingKey)) continue;

      seen.add(candidateId);
    }

    return seen.size;
  }, [
    practitionerOptions,
    extractReferenceType,
    getScheduleRole,
    practitioner?.id,
    getActiveFutureAppointmentForPractitioner,
  ]);

  // The guided flow's step machine (bookingFlowSteps.ts) - the single source of truth for which of the
  // seven questions is on screen, which are answered/locked-with-a-reason, and which haven't been reached
  // yet. Tasks 7-9 render the later steps off this same memo; the reason step is wired here.
  const flowState = useMemo(
    () =>
      resolveFlowState({
        answers: flowAnswers,
        options: {
          service: serviceFilterOptions,
          location: locationSiteOptions,
          practitioner: practitionerOptions.map((s) => ({
            id: s.id as string,
            display: schedulePractitionerName(s, livePractitioners, "Unknown Practitioner", getScheduleRole(s)),
          })),
        },
        servicePinnedTo: pinnedConsultation
          ? { id: pinnedConsultation.id, display: pinnedConsultation.display }
          : undefined,
      }),
    [
      flowAnswers,
      serviceFilterOptions,
      locationSiteOptions,
      practitionerOptions,
      livePractitioners,
      requireNewPatientExamGate,
      derivedPatientType,
      pinnedConsultation,
      extractReferenceType,
      getScheduleRole,
    ],
  );

  // The only service left is committed as the filter, so the location and practitioner steps narrow for it.
  const autoServiceRef = useRef<string>();
  useEffect(() => {
    const next = lockedServiceFilter({
      service: flowState.steps.service,
      options: serviceFilterOptions,
      selected: selectedServiceFilter,
      committed: flowAnswers.service,
      autoSet: autoServiceRef.current,
    });
    if (next === undefined) return;
    autoServiceRef.current = next || undefined;
    setSelectedServiceFilter(next);
  }, [flowState.steps.service, serviceFilterOptions, selectedServiceFilter, flowAnswers.service]);

  const clearSelectedPractitioner = useCallback(() => {
    selfBookingGuardRequestRef.current += 1;
    setCheckingSelfBookingGuard(false);
    setSelectedPractitioner(null);
    setSelectedSchedule(null);
    setPractitionerRole(null);
    setPractitioner(undefined);
    setFormDataForSubmission(null);
    setReviewStep(1);
    setSelectedDate(null);
    setAvailabilityEvents([]);
    resolveBlockForSlotRef.current = null;
    setValue("practitionerId", "", { shouldValidate: true });
    setValue("date", "", { shouldValidate: true });
    setValue("startTime", "", { shouldValidate: true });
    setValue("endTime", "", { shouldValidate: true });
  }, [setValue]);

  // Re-opens a step and clears every answer after it (clearFrom) - the edit affordance every
  // AnsweredLine's onEdit calls. Two things must cascade identically to clearFrom's STEP_ORDER slice, or
  // a re-opened step silently disagrees with what's on screen:
  // 1. showAllServices - reset whenever `service` itself, or anything AT OR BEFORE it, is reopened
  // (Task 7 review finding), otherwise the required-assist escape hatch never comes back.
  // 2. Every step's CONTROLLING value (the Select's `value` prop / the RHF field it reads). Radix's
  // controlled Select only fires `onValueChange` when the new pick differs from the current `value`
  // prop (@radix-ui/react-use-controllable-state). `clearFrom` clears the ANSWER, but if the
  // Select/field still shows the old pick, re-clicking that SAME option is a silent no-op - the step
  // never reflects as answered again, and because resolveFlowState hides everything after an
  // unanswered step (bookingFlowSteps.ts), every step downstream vanishes with it until the patient
  // happens to pick something different first. (Task 9 review finding: this reproduced the exact
  // "state active, UI disagrees" bug the whole redesign exists to remove, one level down - on Service
  // and Location, and, less severely since submission reads `watch()` directly, on Date and Time.)
  // `service`/`location` reset their own local filter state directly. `practitioner`, and everything
  // that cascades into it (date, time), route through `clearSelectedPractitioner` - the SAME reset
  // `handleScheduleChange` already uses for a live practitioner swap, not a second competing path;
  // its own onEdit no longer calls it separately (see that call site). `reason` needs no
  // controlling-value reset: it
  // commits on blur from the RHF field itself, which already re-fires on any focus-out regardless of
  // whether the text changed.
  const handleEditStep = useCallback((step: BookingStepId) => {
    setFlowAnswers((prev) => clearFrom(prev, step));
    const idx = STEP_ORDER.indexOf(step);
    if (idx <= STEP_ORDER.indexOf('reason')) {
      // "Find my service" results are keyed on the reason TEXT they were computed from, not on the step
      // machine's cursor position - nothing else expires them (runSuggest is the only writer). Reopening
      // Reason (or anything before it) invalidates any prior text, so both must clear here or the patient
      // sees the PREVIOUS reason's suggestion cards (or its "no match" notice) rendered against a reason
      // they've since changed or haven't re-typed. Keyed at 'reason', not 'service': reopening step 2 with
      // the SAME reason still intentionally shows its own results.
      setSuggestions([]);
      setSuggestTried(false);
    }
    if (idx <= STEP_ORDER.indexOf('service')) {
      setShowAllServices(false);
      setSelectedServiceFilter('');
    }
    if (idx <= STEP_ORDER.indexOf('location')) {
      setSelectedLocationFilter('');
    }
    if (idx <= STEP_ORDER.indexOf('practitioner')) {
      // Superset reset - also clears date/startTime/endTime/selectedDate, so the two branches below only
      // run when the cascade does NOT reach back this far (i.e. editing 'date' or 'time' alone).
      clearSelectedPractitioner();
    } else if (step === 'date') {
      // clearFrom clears BOTH 'date' and 'time' from flowAnswers here (time is after date in
      // STEP_ORDER), so both controlling fields must reset together or 'time' would re-render answered
      // from a flowAnswers.time that no longer exists.
      setValue('date', '', { shouldValidate: true });
      setValue('startTime', '', { shouldValidate: true });
      setValue('endTime', '', { shouldValidate: true });
      setSelectedDate(null);
    } else {
      // step === 'time': clearFrom clears ONLY 'time' here - flowAnswers.date is untouched, so the date
      // field must NOT be reset, or flowAnswers.date (still "answered") would desync from a blanked
      // `date` RHF field, exactly the bug this whole function exists to prevent.
      setValue('startTime', '', { shouldValidate: true });
      setValue('endTime', '', { shouldValidate: true });
    }
  }, [clearSelectedPractitioner, setValue]);

  // "Any location" is a real choice meaning "no preference" - but once the chosen date+time resolve to a
  // concrete block, the visit HAS a site: that block's locationRef is exactly what the booking submits as
  // its Location participant (see the submit path's `block?.locationRef`). Leaving the summary saying
  // "Any location" for a visit that is now at a named clinic tells the patient something untrue.
  // DERIVED FOR DISPLAY ONLY - deliberately NOT written into flowAnswers.location. Writing it would
  // narrow the option lists the patient chose to leave open, make a derived value indistinguishable from a
  // chosen one, and add a fourth place that has to stay mirrored - the exact class behind three separate
  // defects in this build. Deriving also means it reverts to "Any location" for free when the time is
  // edited, with no reset logic to keep in step.
  const anyLocationResolvedSite =
    selectedLocationFilter === ANY_LOCATION
      ? reviewResolvedBlock?.locationRef?.display
      : undefined;

  // Display-only, like the derivation above, and read from the Location the patient actually chose.
  // `isVirtualLocation` reads the resource's own physicalType coding, which is what makes this
  // independent of whatever the practice named the site.
  const answeredLocationIsRemote = (() => {
    const chosenId = flowAnswers.location;
    if (!chosenId) return false;
    const chosen = locationsList.find((location) => location.id === chosenId);
    return chosen ? isVirtualLocation(chosen) : false;
  })();

  // Every answered step, in STEP_ORDER, rendered as ONE responsive grid above the live question. Each
  // answered line used to be emitted inline at its own step's position, which made the summary a single
  // stacked column interleaved with the current question and left Practitioner in a half-width grid cell
  // while the others were full-width. Driving it from STEP_ORDER keeps the order right by construction.
  const answeredSteps = STEP_ORDER.flatMap((id) => {
    const step = flowState.steps[id];
    if (!isAnswered(step)) return [];
    const common = {
      key: id,
      onEdit: step.editable ? () => handleEditStep(id) : undefined,
      lockReason: step.editable ? undefined : step.reason,
    };
    switch (id) {
      case "reason":
        return [{ ...common, label: "Reason", value: step.value }];
      case "service":
        return [{ ...common, label: "Care type", value: step.value }];
      case "location":
        return [{
          ...common,
          label: "Location",
          value: anyLocationResolvedSite ?? step.value,
          // THE CONFIRMING STEP IS THE ONE THAT MATTERS. The patient was told the visit is remote in
          // the picker and told again once it was booked, and not at the moment they agreed to it -
          // the last screen before a commitment is where somebody checks what they are agreeing to.
          //
          // Asked of the LOCATION rather than of its name, through the same helper the dialog and the
          // intent check already use, so a practice that calls its virtual location "Room 3 Video" or
          // its own brand is still identified. A second definition of what counts as virtual is how
          // two screens come to disagree about the same visit.
          subtitle: answeredLocationIsRemote
            ? "No address - you join from here"
            : anyLocationResolvedSite
              ? "set from the time you selected"
              : undefined,
        }];
      case "practitioner":
        return [{
          ...common,
          label: asksAsRequest ? "Preferred practitioner" : "Practitioner",
          value: step.value,
          subtitle:
            selectedSchedule?.specialty?.[0]?.text ||
            selectedSchedule?.specialty?.[0]?.coding?.[0]?.display ||
            undefined,
        }];
      case "date":
        return [{ ...common, label: "Date", value: step.value }];
      case "time":
        // The length the booking writes as the appointment's minutesDuration, as the deck's review row shows it.
        return [{
          ...common,
          label: "Time",
          value: withAppointmentLength(step.value, { minutesDuration: appointmentDurationMinutes }),
        }];
      default:
        return [];
    }
  });

  // Free-order cross-filtering: picking a service no longer force-clears an already-made location choice
  // (Task 2, ) - the Location select's own items are always narrowed by the current service, so
  // anything the patient could have picked there stays valid. Only the already-selected PRACTITIONER can
  // go stale (they were locked in before this change), so that's the one thing reconciled here.
  //
  // Also the single funnel for BOTH ways a patient can pick a service (a suggestion tap or the manual
  // Select), so it is the one place that commits `flowAnswers.service` (Task 7) - the guided flow's step
  // machine only advances step 2 once this lands, never on option count.
  const handleServiceFilterChange = useCallback((serviceId: string) => {
    setSelectedServiceFilter(serviceId);
    if (serviceId) {
      setFlowAnswers((prev) => ({ ...prev, service: serviceId }));
    }
    if (serviceId && selectedSchedule && !getScheduleSelfBookableServices(selectedSchedule).some((svc) => svc.id === serviceId)) {
      clearSelectedPractitioner();
    }
  }, [clearSelectedPractitioner, getScheduleSelfBookableServices, selectedSchedule]);

  // "Find my service" - suggest-not-autobook: this only populates the suggestion cards below; a
  // tap on a suggestion routes through handleServiceFilterChange (same as the manual Select), so
  // the downstream practitioner/location/time funnel is completely untouched by this feature.
  // matchService already fails open to [] on any error, so no separate error branch is needed here.
  const runSuggest = useCallback(async () => {
    const reason = watch("reasonForVisit")?.trim();
    if (!reason) return;
    setSuggestLoading(true);
    setSuggestTried(true);
    const api = await matchService(reason, clarifyAnswer || undefined, orgOverride);
    setSuggestions(
      mapSuggestionsToBookableServices(api.suggestions, serviceFilterOptions, {
        minConfidence: SUGGESTION_CONFIDENCE_FLOOR,
        maxSuggestions: 4,
      }),
    );
    // Only offered when more than five services cleared the floor - a list too long to choose from.
    // Advisory throughout: undefined is by far the commonest answer and every failure produces it too.
    setClarifyQuestion(api.question);
    setMatchedCount(api.matchedCount);
    setSuggestLoading(false);
  }, [watch, matchService, serviceFilterOptions, clarifyAnswer]);

  // Answering the question re-runs the same assist with the answer attached. Deliberately an effect on
  // the answer rather than work inside the click: runSuggest already closes over clarifyAnswer, so
  // calling it from the handler would send the PREVIOUS answer - the state has not been applied yet at
  // that point. The guard keeps it from firing on first render, when there is no answer to send.
  useEffect(() => {
    if (!clarifyAnswer) return;
    void runSuggest();
    // runSuggest is intentionally the only other dependency; it is a useCallback keyed on the answer.
  }, [clarifyAnswer, runSuggest]);

  // Mirrors handleServiceFilterChange: only reconciles an already-selected practitioner. Choosing the
  // explicit ANY_LOCATION option only widens the constraint, so it can never invalidate the current
  // practitioner - only a concrete site can. Routed through schedulesMatching (rather than the old
  // ad-hoc roleLocations.some(...) check) so an "All locations" practitioner (empty role.location) is
  // correctly treated as matching any site, instead of always being cleared.
  const handleLocationFilterChange = useCallback((locationId: string) => {
    setSelectedLocationFilter(locationId);
    if (locationId) {
      // "Any location" is a real, deliberate answer (it means "no site preference", not "unset") but its
      // sentinel id has no entry in locationSiteOptions - options.location, by design (see that memo's own
      // comment above), so the single-remaining-site auto-lock never counts the synthetic entry. Store the
      // display text directly for that one case so resolveFlowState's raw-string fallback
      // (`match?.display ?? String(answer)`, bookingFlowSteps.ts) renders "Any location" instead of the raw
      // "__all__" sentinel.
      setFlowAnswers((prev) => ({
        ...prev,
        location: locationId === ANY_LOCATION ? "Any location" : locationId,
      }));
    }
    if (
      locationId &&
      locationId !== ANY_LOCATION &&
      selectedSchedule &&
      !schedulesMatching({ location: locationId }).some((schedule) => schedule.id === selectedSchedule.id)
    ) {
      clearSelectedPractitioner();
    }
  }, [clearSelectedPractitioner, schedulesMatching, selectedSchedule]);

  // Pre-answer the Location question when the reason names one of the sites that offer the chosen
  // service. Routed through handleLocationFilterChange, so a pre-answer behaves exactly like picking the
  // site from the dropdown - the flow answer, the practitioner reconciliation and the availability
  // narrowing all follow the one path. It runs only while nothing is selected, so it can put an answer
  // in front of the patient but can never overrule one, and locationSiteOptions is already narrowed to
  // the sites this service is offered at, so it can never name a site the manual picker would refuse.
  useEffect(() => {
    if (selectedLocationFilter) return;
    const named = reasonNamesALocation(locationSiteOptions, watchReasonForVisit ?? "");
    if (named) handleLocationFilterChange(named);
  }, [
    watchReasonForVisit,
    selectedLocationFilter,
    locationSiteOptions,
    handleLocationFilterChange,
  ]);

  // ORG-WIDE candidate set for the practitioner ranker (, Step 1): one BookablePractitioner per
  // distinct practitioner-role that offers the chosen service, across EVERY location. Service-filtered
  // ONLY on the LOCATION axis - selectedLocationFilter deliberately does NOT prune here (location frames
  // the manual list but must never narrow the specialty ranker); it is passed only as `preferLocationId` so
  // a role that serves the service at several sites displays the selected one (the same tie-break
  // handleScheduleChange uses), which keeps the mapper's crossLocation flag accurate.
  // It DOES apply the new-patient exam gate (now inside schedulesMatching -> matchSchedules) - the same
  // gate the manual `practitionerOptions` and handleScheduleChange's availability union apply - so a
  // self-attested new patient can never be recommended a practitioner the manual picker hides from them
  // (the exam gate is a no-op unless the org requires a new-patient exam first). Empty until a service is
  // chosen.
  const bookablePractitioners = useMemo<BookablePractitioner[]>(() => {
    if (!selectedServiceFilter) return [];
    const locationNameById = new Map<string, string>();
    for (const loc of locationsList) {
      if (loc.id) locationNameById.set(loc.id, loc.name || loc.id);
    }
    const matchingForRank = schedulesMatching({
      service: selectedServiceFilter,
    });
    const candidates: BookablePractitionerCandidate[] = matchingForRank.map((schedule) => {
      const role = getScheduleRole(schedule);
      return {
        practitionerRoleId: role?.id,
        // Same source the manual practitioner <Select> renders.
        display: schedulePractitionerName(schedule, livePractitioners, "Unknown Practitioner", getScheduleRole(schedule)),
        specialty: role?.specialty,
        locationRefs: getScheduleLocationRefs(schedule, role),
      };
    });
    return buildBookablePractitioners(candidates, {
      locationNameById,
      preferLocationId:
        selectedLocationFilter && selectedLocationFilter !== ANY_LOCATION
          ? selectedLocationFilter
          : undefined,
    });
  }, [
    selectedServiceFilter,
    selectedLocationFilter,
    schedulesMatching,
    getScheduleRole,
    getScheduleLocationRefs,
    extractReferenceType,
    locationsList,
    livePractitioners,
  ]);

  // Gate (, Step 2). Recommend ONLY when: a reason is typed, no practitioner is pinned, a service
  // is chosen, AND either the candidate set spans >=2 distinct specialties or the reason names one of the
  // bookable practitioners (qualifiesForRecommendation) - else there is nothing to disambiguate. The name
  // door is what makes a clinician with no specialty recorded reachable, since the specialty door cannot
  // open for one. Every input here is LOCATION-INVARIANT: the candidate SET of roles is
  // org-wide (location only reframes their DISPLAY site), so the server ranking never changes on a location
  // toggle. We reduce the gate to primitive keys the fetch effect can depend on, so a location change does
  // NOT re-invoke Bedrock - only the pure re-map below runs.
  const practitionerRankingInputs = useMemo(() => {
    const reason = watchReasonForVisit?.trim() ?? "";
    const gateMet =
      reason !== "" &&
      !watchPractitionerId &&
      !!selectedServiceFilter &&
      qualifiesForRecommendation(bookablePractitioners, reason);
    return {
      // null reason => gate unmet => the fetch effect clears rankings and skips the call.
      reason: gateMet ? reason : null,
      serviceId: gateMet ? selectedServiceFilter : "",
      // Signature of WHICH roles are candidates (location-invariant). A service/exam-gate change alters it
      // and re-fetches; a location toggle leaves it identical, so the effect does not re-fire.
      candidateSignature: gateMet
        ? bookablePractitioners.map((b) => b.practitionerRoleId).join(",")
        : "",
    };
  }, [
    watchReasonForVisit,
    watchPractitionerId,
    selectedServiceFilter,
    bookablePractitioners,
  ]);

  // Fetch (, Step 2). Keyed on the location-invariant ranking inputs above. Fail-open:
  // matchPractitioner already returns [] on any error. Race-guarded by the `cancelled` ignore-flag: an
  // input change re-runs the effect and the prior cleanup flips `cancelled`, discarding the stale response.
  useEffect(() => {
    const { reason, serviceId } = practitionerRankingInputs;
    if (reason === null) {
      setPractitionerRankings([]);
      return;
    }
    let cancelled = false;
    void (async () => {
      const rankings = await matchPractitioner(reason, serviceId, orgOverride);
      if (!cancelled) setPractitionerRankings(rankings);
    })();
    return () => {
      cancelled = true;
    };
  }, [
    practitionerRankingInputs.reason,
    practitionerRankingInputs.serviceId,
    practitionerRankingInputs.candidateSignature,
    matchPractitioner,
  ]);

  /**
   * THE ROLES THE SELF-BOOKING GUARD WILL REFUSE, so the assist does not point at one.
   *
   * Grounding a recommendation against `bookablePractitioners` was enough for every other reason a
   * practitioner cannot be booked, because those reasons are properties of the SCHEDULE and have
   * already removed them from the funnel. This one is a property of the PATIENT - they hold an
   * upcoming appointment with that practitioner - so the picker still lists them and the refusal
   * only arrives once they are selected.
   *
   * Left alone, the callout recommends somebody, the patient clicks the recommendation, and the
   * guard refuses it. That is the product walking them into the wall it then explains.
   *
   * Built from the SAME predicate the guard and the "how many colleagues are free" count both use,
   * over the SAME list the picker renders - so what is recommended, what is offered and what is
   * accepted cannot disagree.
   */
  /**
   * WHY THE PRACTITIONER LIST IS EMPTY, AND WHICH CHOICE TO CHANGE.
   *
   * Until now an empty combination said "No practitioners available" INSIDE the dropdown - so somebody
   * had to open a picker to be told it had nothing in it, and was then left to guess which of their
   * three choices to undo. That guess is the reason the assist exists.
   *
   * BOTH HALVES COME FROM THE MATCHER and neither is invented here. The blockers are what
   * `evaluateScheduleMatch` recorded for these exact criteria, and the remedy is one `softConstraints`
   * proved would open something - so this can never name a combination the picker would then refuse.
   *
   * ONLY WHEN THE LIST IS ACTUALLY EMPTY. Somebody with options is not asking what to give up, and a
   * panel explaining a dead end to a person who has not reached one is the noise this feature exists to
   * remove.
   */
  const deadEnd = useMemo(() => {
    if (practitionerOptions.length > 0) return undefined;

    const criteria = { service: selectedServiceFilter, location: selectedLocationFilter };
    // Every blocker these criteria produced, across every schedule. `explainDeadEnd` sorts them and
    // takes the leading one, so that decision stays in one place rather than being made twice.
    const blockers = Array.from(
      new Set(
        bookableSchedules.flatMap(
          (schedule) => evaluateScheduleMatch(schedule, criteria, scheduleMatchContext).blockers,
        ),
      ),
    );

    return deadEndText(blockers, softConstraints(bookableSchedules, criteria, scheduleMatchContext));
  }, [
    practitionerOptions,
    bookableSchedules,
    scheduleMatchContext,
    selectedServiceFilter,
    selectedLocationFilter,
  ]);

  const guardRefusedRoleIds = useMemo(() => {
    const refused = new Set<string>();

    for (const schedule of practitionerOptions) {
      const roleId = getScheduleRole(schedule)?.id;
      const candidateId = schedulePractitionerId(schedule, getScheduleRole(schedule));

      if (!roleId || !candidateId) continue;
      if (getActiveFutureAppointmentForPractitioner(candidateId, [], undefined, chosenServiceCap.limit, chosenServiceCap.codingKey)) refused.add(roleId);
    }

    return refused;
  }, [practitionerOptions, extractReferenceType, getScheduleRole, getActiveFutureAppointmentForPractitioner]);

  // Map raw rankings -> display recommendations (, Step 3). PURE + location-dependent: recomputes
  // on a location toggle WITHOUT a refetch, so crossLocation stays accurate as the patient changes the
  // filter. Display/specialty/location always come from bookablePractitioners, never the API.
  const recommendations = useMemo<PractitionerRecommendation[]>(
    () =>
      mapPractitionerRankings(practitionerRankings, bookablePractitioners, {
        selectedLocationId:
          selectedLocationFilter && selectedLocationFilter !== ANY_LOCATION
            ? selectedLocationFilter
            : undefined,
        unbookableRoleIds: guardRefusedRoleIds,
      }),
    [practitionerRankings, bookablePractitioners, selectedLocationFilter, guardRefusedRoleIds],
  );

  // Selecting a recommendation (, Step 4) - reuse the EXACT manual-Select path. If the pick is at
  // a different site than the one currently filtered, flip the location filter first so the funnel
  // re-narrows to it; then resolve the Schedule that owns this role (preferring its own site/service
  // block) and drive handleScheduleChange with it, identically to picking it from the manual dropdown
  // (sets practitionerId, resets date/time, rebuilds availability, runs the self-booking guard). A plain
  // function (like the other handlers here) so it always closes over the current, non-memoized
  // handleScheduleChange rather than a stale one.
  const handleRecommendationSelect = (rec: PractitionerRecommendation) => {
    if (rec.crossLocation && rec.locationId) {
      // Route through the mirroring handler (not the raw setter) so flowAnswers.location is kept in
      // sync with selectedLocationFilter - see the file-header note on the two-answers-must-agree class
      // of bug. handleLocationFilterChange's own clearSelectedPractitioner reconciliation is inert here:
      // reaching this branch requires flowState.steps.practitioner.kind === "current" (the callout only
      // renders then), which means no practitioner/schedule has been picked yet, so selectedSchedule is
      // still null and that check short-circuits. The actual schedule selection happens below via
      // handleScheduleChange, identically to before this change.
      handleLocationFilterChange(rec.locationId);
    }
    const scheduleForRec =
      schedulesMatching({
        service: selectedServiceFilter,
        location: rec.locationId || undefined,
      }).find((s) => getScheduleRole(s)?.id === rec.practitionerRoleId) ??
      bookableSchedules.find(
        (s) => getScheduleRole(s)?.id === rec.practitionerRoleId,
      );
    if (scheduleForRec?.id) {
      handleScheduleChange(scheduleForRec.id);
    }
  };

  // The practitioner step's single-remaining-option auto-lock (bookingFlowSteps.ts) is a real answer, but -
  // unlike service/location, where "no filter chosen" and "the one real option chosen" narrow to the
  // identical schedule set - nothing else drives the actual booking selection the way a manual pick does.
  // Date/Time (Task 9, untouched here) are gated on `watchPractitionerId`, which only `handleScheduleChange`
  // ever sets. Without this, a locked practitioner step would silently strand the patient with no way to
  // reach Date - the exact class of dead end this redesign exists to remove (design doc §2.2). Auto-invokes
  // the identical path a manual pick uses, `{ silent: true }` so it does not also commit
  // `flowAnswers.practitioner` (see handleScheduleChange's comment for why that write must stay skipped
  // here). `watchPractitionerId` in the guard prevents this from re-firing once a schedule is set.
  useEffect(() => {
    if (
      isAnswered(flowState.steps.practitioner) &&
      !flowState.steps.practitioner.editable &&
      !watchPractitionerId &&
      practitionerOptions.length === 1 &&
      practitionerOptions[0].id
    ) {
      handleScheduleChange(practitionerOptions[0].id as string, { silent: true });
    }
  }, [flowState.steps.practitioner, watchPractitionerId, practitionerOptions]);

  /**
   * THE CLOCK THE PRACTICE'S HOURS ARE WRITTEN IN, for the block that actually owns the picked slot.
   *
   * The block's hours are expanded in this zone into real instants, and those are then listed on the
   * PATIENT's clock (toLocalIso). So the picked label is a patient-clock time and is stored with
   * pickedTimeInstant. Reading it in this zone instead stores a patient's 2:00 PM in another zone as the
   * wrong hour. This zone is still required: without it the hours themselves
   * cannot be placed, so there is nothing true to offer or store.
   *
   * Resolved per slot rather than once for the screen, because under "Any location" a practitioner can
   * hold one block per site and those sites can be in different zones - the same reason the payload
   * already resolves the owning block here. `scheduleSiteFor`, never `location[0]`: a video-enabled
   * block also carries the org's virtual Location, which has no clock of its own.
   *
   * `null` is a real answer. Never paper over it with the viewer's zone - that fallback is the defect.
   */
  const practiceZoneForSlot = useCallback(
    (dateStr: string, timeStr: string): string | null => {
      const owning = resolveBlockForSlotRef.current?.(dateStr, timeStr);
      const owningSchedule = owning
        ? schedulesList.find((s) => s.id === owning.scheduleId)
        : undefined;
      const site = scheduleSiteFor(
        owningSchedule,
        owningSchedule ? getScheduleRole(owningSchedule) : practitionerRole ?? undefined,
        locationsList,
      );
      return resolveBookingTimeZone({
        site,
        organization: bookingOrg,
      });
    },
    [schedulesList, getScheduleRole, practitionerRole, locationsList, bookingOrg],
  );

  // Known before Confirm is pressed: a location without a time zone cannot hold a booked time.
  const reviewZoneMissing = Boolean(
    formDataForSubmission && !practiceZoneForSlot(formDataForSubmission.date, formDataForSubmission.startTime),
  );

  // The viewer zone label for one visit, judged against the site that owns that slot at that instant.
  const zoneLabelForVisit = useCallback(
    (dateStr: string, timeStr: string): string | null =>
      visitZoneLabel(dateStr, timeStr, dateStr && timeStr ? practiceZoneForSlot(dateStr, timeStr) : null),
    [practiceZoneForSlot],
  );

  // The chosen visit once there is one; before that, any open time on the day that would need a label.
  const viewerZoneNotice = useMemo(() => {
    if (!watchDate) return null;
    const times = watchStartTime ? [watchStartTime] : availableTimeOptions.map((option) => option.value);
    for (const time of times) {
      const viewerZoneLabel = zoneLabelForVisit(watchDate, time);
      if (viewerZoneLabel) return { viewerZoneLabel };
    }
    return null;
  }, [watchDate, watchStartTime, availableTimeOptions, zoneLabelForVisit]);

  // Appointment Type = how the patient came in (v2-0276 modality). Patient self-bookings default to
  // routine; "what is performed" lives on the separate Visit service (serviceType) axis.
  const appointmentTypes = [
    { code: "ROUTINE", display: "Routine" },
    { code: "WALKIN", display: "Walk-in" },
    { code: "EMERGENCY", display: "Emergency" },
  ];

  // Create proper FHIR appointment payload
  const createAppointmentPayload = (
    data: AppointmentFormData,
  ): Appointment => {
    // The label was picked on the patient's clock, the one the list is drawn in (see pickedTimeInstant).
    const start = pickedTimeInstant(data.date, data.startTime).toISOString();
    // A visit ending at midnight ends on the next day, as the receptionist dialog already reads it.
    const end = pickedTimeInstant(
      intervalEndDate(data.date, data.startTime, data.endTime),
      data.endTime,
    ).toISOString();

    // Resolve the location-scoped block that actually owns the picked slot (Task 3's union resolver).
    // Under "Any location" a practitioner can have multiple blocks (one per site); the picked slot may
    // belong to any of them, so the role/location/service recorded on the Appointment must reflect THAT
    // block, not the representative practitionerRole/selectedSchedule state used to drive the form. The
    // resolver is pure and cheap to call again in handleCreateAppointment for the Slot. Falls through to
    // undefined (and the pre-existing representative-based derivations below) when only one block exists
    // for this practitioner, or resolveBlockForSlotRef hasn't been populated - no behavior change there.
    const block = resolveBlockForSlotRef.current?.(data.date, data.startTime);
    const blockSchedule = block
      ? schedulesList.find((s) => s.id === block.scheduleId)
      : undefined;

    // Get selected appointment type display
    const selectedType = appointmentTypes.find((t) => t.code === data.appointmentType);
    const typeDisplay = selectedType?.display || data.appointmentType;

    // Create proper CodeableConcept structure
    const appointmentType: CodeableConcept = {
      coding: [
        {
          system: "http://terminology.hl7.org/CodeSystem/v2-0276",
          code: data.appointmentType,
          display: typeDisplay,
        },
      ],
      text: typeDisplay,
    };

    // Create participants
    const participants: AppointmentParticipant[] = [];

    if (practitioner) {
      participants.push({
        actor: createReferenceObject(
          "Practitioner",
          practitioner.id as string,
          formatFhirHumanName(practitioner.name),
        ),
        status: "accepted",
        required: "required",
      });
    }

    // Record the organization-scoped PractitionerRole alongside the Practitioner. This is the join
    // key the server uses to recognize established patients (Appointment?actor=PractitionerRole/...)
    // and to scope the booking to the org - a bare Practitioner participant is invisible to those
    // queries. The server tolerates the Practitioner + PractitionerRole pair. Prefer the resolved
    // block's role id (the role that actually owns the picked slot) over the representative
    // practitionerRole state; post schedule/role-separation there is one role per practitioner per org,
    // so in the common case they're the same id, but the block's id is correct by construction. The
    // display always comes from practitionerRole - it's the same role either way.
    const resolvedPractitionerRoleId = block?.practitionerRoleId ?? practitionerRole?.id;
    if (resolvedPractitionerRoleId) {
      participants.push({
        actor: createReferenceObject(
          "PractitionerRole",
          resolvedPractitionerRoleId,
          getPractitionerRolePrimaryDisplay(practitionerRole ?? undefined),
        ),
        status: "accepted",
        required: "required",
      });
    }

    // Record the Location (the picked slot's own site - from the resolved block - else the patient's
    // explicitly chosen site, else the role's primary location) so the appointment is queryable by site
    // and staff can see where it actually is. Under "Any location" a picked slot can belong to any of the
    // practitioner's location-scoped blocks; block?.locationRef is that specific block's site and takes
    // priority so the booking never lands on a different, merely-representative site. It is undefined for
    // an "All locations" block (no site on the role/schedule itself) - the existing
    // selectedLocationFilter-derived chain below still resolves the chosen org site for that case, and for
    // the pre-Task-3/no-resolver path (resolveBlockForSlotRef unpopulated, or only one block exists) this
    // falls through unchanged. When a specific location was explicitly chosen (not ANY_LOCATION), the
    // resolved block's site equals it, so there is no behavior change in that path either.
    const chosenOrgLocation = selectedLocationFilter
      ? locationsList.find((loc) => loc.id === selectedLocationFilter)
      : undefined;
    // The block's ref was fixed when the practitioner was chosen, which can be before the Location answer;
    // the answer as it stands now decides among the block's own actors (video or the site).
    const answeredBlockLocation = blockSchedule
      ? withLocationDisplay(
          resolveBookingLocationRef(
            getScheduleLocationRefs(blockSchedule, getScheduleRole(blockSchedule)),
            selectedLocationFilter && selectedLocationFilter !== ANY_LOCATION ? selectedLocationFilter : undefined,
          ),
          locationsList,
        )
      : undefined;
    const appointmentLocation =
      answeredBlockLocation ??
      block?.locationRef ??
      (selectedLocationFilter
        ? practitionerRole?.location?.find(
            (location) =>
              location.reference?.split("/").pop() === selectedLocationFilter,
          )
        : undefined) ??
      (chosenOrgLocation?.id
        ? {
            reference: `Location/${chosenOrgLocation.id}`,
            display: chosenOrgLocation.name || chosenOrgLocation.id,
          }
        : undefined) ??
      practitionerRole?.location?.[0];
    if (appointmentLocation?.reference) {
      participants.push({
        actor: appointmentLocation,
        status: "accepted",
      });
    }

    if (patientState) {
      participants.push({
        actor: createReferenceObject(
          "Patient",
          patientState.id as string,
          formatFhirHumanName(patientState.name),
        ),
        status: "accepted",
        required: "required",
      });
    }

    // Build the appointment payload
    const payload: Appointment = {
      resourceType: "Appointment",
      status: "booked",
      appointmentType: appointmentType,
      start: start,
      end: end,
      created: new Date().toISOString(),
      participant: participants,
      description: data.description || undefined,
      comment: data.comment || undefined,
      minutesDuration: appointmentDurationMinutes,
    };

    // Add priority if set
    if (data.priority && data.priority > 0) {
      payload.priority = data.priority;
    }

    // Add service category if available
    if (data.serviceCategory && data.serviceCategory.length > 0) {
      payload.serviceCategory = data.serviceCategory as CodeableConcept[];
    }

    // Add service type if available, in precedence order (, fixed per review): (1) an
    // explicit form value always wins; (2) otherwise, when a single service was chosen for this booking
    // (block.serviceRef), use THAT service's own coded type from the loaded catalog - NOT
    // blockSchedule.serviceType, which is the block's denormalized union of every service the schedule
    // offers and would mislabel the appointment with services the patient didn't book; (3) only when no
    // single service was chosen (e.g. "Any service") fall back to the block's schedule-level Visit
    // service as a last resort, so the appointment still carries a coded serviceType rather than none.
    const chosenServiceType = block?.serviceRef
      ? healthcareServicesList.find((s) => s.id === block.serviceRef!.id)?.type
      : undefined;
    const resolvedServiceType =
      data.serviceType && data.serviceType.length > 0
        ? (data.serviceType as CodeableConcept[])
        : chosenServiceType && chosenServiceType.length > 0
          ? chosenServiceType
          : blockSchedule?.serviceType;
    if (resolvedServiceType && resolvedServiceType.length > 0) {
      payload.serviceType = resolvedServiceType;
    }

    // The practitioner's organization-role coding, kept for TWO narrow uses below and no longer for a
    // third: it is the last fallback for `specialty` when neither the form nor the role states one, and
    // the last fallback for the reason's WORDS when the patient typed none. It is deliberately not the
    // reason's coding any more - see the note on reasonCode below for why, and for the consumers.
    const selectedServiceCoding = getPractitionerRolePrimaryCoding(practitionerRole ?? undefined);

    // specialty: an explicit form value wins; otherwise the role's own specialty, then the org-role.
    if (data.specialty && data.specialty.length > 0) {
      payload.specialty = data.specialty as CodeableConcept[];
    } else if (
      practitionerRole?.specialty &&
      practitionerRole.specialty.length > 0
    ) {
      payload.specialty = practitionerRole.specialty;
    } else if (selectedServiceCoding) {
      payload.specialty = [
        {
          coding: [selectedServiceCoding],
          text: selectedServiceCoding.display || selectedServiceCoding.code,
        },
      ];
    }

    // reasonCode: WHY the visit, in the patient's own words, and DELIBERATELY UNCODED.
    //
    // This used to carry the practitioner's organization-role as its coding, so a booking's coded
    // reason read "Physician". The note explaining it said the chosen service was "the best-available
    // coded reason" until symptom routing arrived - and that premise has expired twice over: the real
    // SNOMED service now resolves a few lines above, and it already travels on `serviceType`, which is
    // the field that answers WHAT is being done.
    //
    // Neither candidate is a reason. A practitioner role is a person's function, and a service is the
    // act being performed; the reason is why the patient wants it, and nothing in this flow codes that
    // until symptom routing exists. So the coding is omitted rather than filled with the nearest
    // available concept: an absent coding says "we hold no coded reason", which is true, while
    // "Physician" asserts something false into an interoperability field that other systems read.
    //
    // CONSUMERS CHECKED, all six, before removing it:
    //   sensitivityLabels.ts (api)      adolescent redaction reads BOTH reasonCode codings and
    //                                   serviceType. The role coding matches no sensitive concept, so
    //                                   it contributed nothing, and serviceType still carries the real
    //                                   service - the redaction is unchanged.
    //   useEncounterActions.ts          copies reasonCode onto the Encounter, guarded on .length
    //   arrivalEncounter.ts (api)       the same, on the check-in path
    //                                   -> `.text` keeps the array non-empty, so both still carry the
    //                                      patient's sentence onto the clinical record.
    //   assistantRecord.ts (api)        reads encounter.reasonCode[0].TEXT only. Unaffected.
    //   FhirAppointmentDisplay          renders the CodeableConcept; it stops printing "Physician" as
    //                                   the reason and shows the patient's words.
    //   Appointment/get.ts (api)        deliberately does not derive from reasonCode; its own comment
    //                                   says so.
    const reasonText =
      data.reasonForVisit?.trim() ||
      data.description?.trim() ||
      data.comment?.trim() ||
      selectedServiceCoding?.display ||
      selectedServiceCoding?.code;
    if (reasonText) {
      payload.reasonCode = [{ text: reasonText }];
    }

    // Add patient instruction if available
    if (data.patientInstruction) {
      payload.patientInstruction = data.patientInstruction;
    }

    // THE ATTESTATION IS RETIRED AND NO LONGER SENT. It told the server that the patient said they were
    // already established here, and the server trusted it. Both halves are gone: "seen" is now an
    // Encounter the server reads for itself, and a patient's answer about their own history could never
    // be allowed to override a record we hold. The migrating-practice case it existed for is answered
    // instead by the front desk being outside this gate entirely, so a practice can always book anyone.

    // The one catalogue service the patient chose travels with its coding, so the server can tell it from a namesake.
    return block?.serviceRef?.id ? withSelectedServiceRef(payload, block.serviceRef.id) : payload;
  };

  // Validate and move to review. A stale local conflict is refreshed before blocking.
  const handleReview = async () => {
    if (!pickedTimeIsOffered) {
      toast.error("That time is no longer available. Please pick another time.", { position: "top-right" });
      return;
    }
    if (activePractitionerAppointment) {
      try {
        const latestConflict = await refreshSelfBookingConflict();
        if (latestConflict) {
          showSelfBookingGuardMessage(latestConflict, unblockedOtherPractitionerCount);
          return;
        }
      } catch (error) {
        console.error("Failed to verify existing appointments:", error);
        toast.error(
          "Unable to verify your existing appointments. Please try again.",
          { position: "top-right" },
        );
        return;
      }
    }

    const isValid = await trigger();
    if (isValid) {
      // Store form data for later submission
      const formData = getValues();
      setFormDataForSubmission(formData);
      setReviewStep(2);
    }
  };

  // Handle actual appointment creation - called only on Confirm Booking
  const handleCreateAppointment = async () => {
    // The send itself is fenced: only a time the current read still offers is booked, checked again before the write.
    const startedFrom = sendStandingRef.current;
    if (!pickedTimeIsOffered) {
      toast.error("That time is no longer available. Please pick another time.", { position: "top-right" });
      setFormDataForSubmission(null);
      setReviewStep(1);
      return;
    }
    if (
      !formDataForSubmission ||
      !selectedSchedule ||
      !practitioner ||
      !patientState
    ) {
      toast.error(
        "Missing required information. Please go back and check your selections.",
        { position: "top-right" },
      );
      return;
    }

    if (activePractitionerAppointment) {
      showSelfBookingGuardMessage(activePractitionerAppointment, unblockedOtherPractitionerCount);
      setReviewStep(1);
      return;
    }

    // WITHOUT THE PRACTICE'S CLOCK ITS HOURS CANNOT BE PLACED, so this refuses rather than guessing -
    // the quiet-hours precedent. A patient cannot fix a practice's
    // settings, so the refusal names the practice as the next step rather than a screen they cannot reach.
    const practiceZone = practiceZoneForSlot(
      formDataForSubmission.date,
      formDataForSubmission.startTime,
    );
    if (!practiceZone) {
      const noClock =
        "We could not work out what time this appointment would be, because this practice has not set a time zone for that location. Please contact the practice to book.";
      toast.error(noClock, { position: "top-right" });
      setConfirmRefusal(noClock);
      setReviewStep(2);
      return;
    }

    setSubmitting(true);
    // Cleared at the START of each attempt rather than on success. A reason that outlives the attempt
    // it described is its own defect: the patient fixes the problem, confirms again, and is left reading
    // the old sentence while the booking succeeds behind it.
    setConfirmRefusal(undefined);
    // setSuccessState(undefined);
    // toast.error(undefined);

    let begun: BookingOperationEntry | undefined;
    try {
      // Take the patient's clinical-authorization answer BEFORE anything is created. This resolves
      // when the org is already authorized, or when their agreement reached the server. It REJECTS when
      // they DECLINED ( - without the authorization there is no lawful way to reach the record,
      // so there is no service to perform), when they have not answered, when the question could not be
      // shown to them, or when recording their agreement failed. See SelfBookingAuthorization.tsx.
      try {
        await selfBookingAuthorizationRef.current?.recordAnswer();
      } catch (authorizationError) {
        if (authorizationError instanceof SelfBookingAuthorizationRefusal) {
          // Deliberately NOT rethrown into the generic handler below: this is not a failed
          // booking, it is a booking that has not been asked for yet, and "Failed to create
          // appointment:..." would describe it wrongly. Nothing has been created at this point.
          toast.error(authorizationError.message, { position: "top-right" });
          // The same sentence, somewhere it cannot be missed - see `confirmRefusal`.
          setConfirmRefusal(authorizationError.message);
          setReviewStep(2);
          return;
        }
        throw authorizationError;
      }

      // Refresh immediately before creating a Slot. The API remains the final guard,
      // but this avoids leaving a temporary busy Slot when an existing booking is already known.
      const latestConflict = await refreshSelfBookingConflict();

      if (latestConflict) {
        showSelfBookingGuardMessage(latestConflict, unblockedOtherPractitionerCount);
        setFormDataForSubmission(null);
        setReviewStep(1);
        return;
      }

      // Create slot data. A preferred-slot request HOLDS the slot from creation (the server reserves
      // it; the receptionist confirms or moves it, which releases the old one), so it is `busy` like a
      // direct booking. Time-window requests never reach here - they create no slot.
      const slotData = {
        status: "busy" as "busy" | "free",
        start: pickedTimeInstant(
          formDataForSubmission.date,
          formDataForSubmission.startTime,
        ).toISOString(),
        end: pickedTimeInstant(
          intervalEndDate(
            formDataForSubmission.date,
            formDataForSubmission.startTime,
            formDataForSubmission.endTime,
          ),
          formDataForSubmission.endTime,
        ).toISOString(),
        comment:
          formDataForSubmission.comment || "Slot created for appointment",
        overbooked: false,
      };

      // Hold the Slot against the resolved block's own schedule - the picked slot may belong to any of
      // the practitioner's location-scoped blocks under "Any location" (, Finding B write side),
      // not just the representative selectedSchedule. Resolving again here (createAppointmentPayload
      // resolves it separately below) is cheap - the resolver is pure. Falls back to selectedSchedule when
      // no block resolves (specific-location booking, single-block practitioner, or the resolver hasn't
      // been populated) - no regression there.
      const submissionBlock = resolveBlockForSlotRef.current?.(
        formDataForSubmission.date,
        formDataForSubmission.startTime,
      );
      const slotSchedule =
        (submissionBlock
          ? schedulesList.find((s) => s.id === submissionBlock.scheduleId)
          : undefined) ?? selectedSchedule;

      // Kept before the Slot or the booking is sent; an earlier booking still unknown is checked instead.
      const operation = await booking.begin();
      begun = operation;

      // The first write, after the last wait. The read this Confirm started from must still be current and still
      // offer its pick; a refusal here leaves the begun operation unsent, and the finally closes it.
      const now = sendStandingRef.current;
      if (now !== startedFrom || now.standing !== "actionable" || now.picked !== formDataForSubmission.startTime) {
        toast.error("The available times changed while you were confirming. Check the time and confirm again.", { position: "top-right" });
        if (now.standing !== "actionable" || now.picked !== formDataForSubmission.startTime) {
          setFormDataForSubmission(null);
          setReviewStep(1);
        }
        return;
      }

      // Create slot first
      const newSlot: Slot = await createSlot(
        transformToFhirSlot(slotData, slotSchedule),
        orgOverride,
      );

      try {
        // Create appointment payload with slot reference
        const appointmentPayload = createAppointmentPayload(formDataForSubmission);
        appointmentPayload.slot = [
          {
            reference: `Slot/${newSlot.id}`,
          },
        ];

        // Create appointment. In request-only mode the server returns the appointment as
        // `proposed` (a request) rather than `booked` - branch the messaging on the real result.
        //
        // S4e-2, Task 12 - `getCampaignCtaAttribution()` is a non-destructive read (never
        // throws; returns null when nothing was stashed or storage is unavailable), so it is always
        // safe to pass inline here even though it never blocks or alters the booking itself. This is
        // the patient's OWN self-booking path only (this component, not ReceptionistBookAppointment.tsx,
        // which staff use and which is not touched by this change) - so a staff member's session never
        // carries a patient's stashed token along.
        const cta = getCampaignCtaAttribution();
        const sent = await booking.send(operation, (operationId) => createAppointment(
          appointmentPayload,
          cta,
          undefined,
          orgOverride,
          operationId,
        ));
        // Settled for a view no longer shown: it is not announced, attributed or confirmed here.
        if (sent.kind === "retired") return;
        const createdAppointment = sent.appointment;
        // Consume-once: clear the stashed token only NOW, after the booking POST has actually
        // succeeded - never earlier. A failed booking below (caught in the inner catch) leaves the
        // token in place so the patient's retry still attributes; clearing it here means it cannot
        // also attribute a later, unrelated appointment in the same session. Idempotent when nothing
        // was stashed (removes a key that was never set).
        clearCampaignCtaAttribution();

        // Held self-bookings come back `proposed` (request) or `pending` (review) - either way the
        // patient is told it is pending confirmation; a direct booking is confirmed immediately.
        const needsConfirmation =
          createdAppointment.status === "proposed" ||
          createdAppointment.status === "pending";
        const successMessage = needsConfirmation
          ? "Your appointment has been submitted and is pending confirmation by the practice."
          : "Appointment created successfully.";

        // Call success callback
        if (onSuccess) {
          onSuccess(successMessage, createdAppointment);
        }

        toast.success(successMessage, {
          position: "top-right",
        });

        /*
 * EVERY BOOKING LANDS ON THE CONFIRMATION, INCLUDING THE ONE MADE IN A DIALOG.
 *
 * This used to read "a dialog closes, a page has nowhere to go, so it says so" - the standalone
 * route got the confirmation and both dialog callers just closed on a toast. That reasoning held
 * only while a page existed. The booking PAGE is retired and the dialog is the sole booking
 * surface, so the old branch would have deleted the confirmation screen outright: booked from the
 * dialog, nothing on screen ever named the appointment that had just been created, and the toast
 * fades.
 *
 * So the dialog stays OPEN on success and shows what was booked. Closing it is the patient's
 * action, on the Done button below, which is the only control that screen carries.
 *
 * The snapshot is taken BEFORE the clear, which wipes every field it reads.
 */
        // The place this Appointment was booked with; the slot's block ref can predate the Location answer.
        const bookedLocationLabel = appointmentPayload.participant?.find(
          (participant) => participant.actor?.reference?.startsWith("Location/"),
        )?.actor?.display;
        setBookingConfirmation({
          practitionerName: selectedPractitioner?.name,
          dateLabel: formatDateForDisplay(watchDate),
          timeLabel: formatTimeForDisplay(watchStartTime),
          locationLabel:
            bookedLocationLabel
            || reviewResolvedBlock?.locationRef?.display
            || bookingOrg?.name
            || "this practice",
          serviceLabel: reviewServiceLabel(
            reviewResolvedBlock?.serviceRef?.display,
            serviceFilterOptions.find((opt) => opt.id === selectedServiceFilter)?.display,
            pinnedServiceLabel,
          ),
          pendingPracticeConfirmation: needsConfirmation,
        });
        handleClearAll();
        setReviewStep(3);

      } catch (appointmentError: unknown) {
        // Not known to be made or refused: the check stands in for the steps, and no time is re-offered.
        if (isBookingUnconfirmed(appointmentError) || isBookingRetired(appointmentError)) return;
        console.error("Appointment creation error:", appointmentError);
        // No slot rollback here: Appointment/post.ts frees the orphaned slot itself
        // (releaseOrphanedBookingSlots). The client DELETE was removed with the
        // DELETE /R4/Slot route in.

        // Provide more specific error message
        const errorMessage = getErrorMessage(
          appointmentError,
          "Failed to create appointment",
        );

        // BRANCH ON THE SERVER'S CODE, NOT ITS ENGLISH. The 409 body is an OperationOutcome carrying
        // a machine-readable guard code (twice) plus the conflicting appointment's start; this used to
        // read `errorMessage.includes("active upcoming appointment with this practitioner")`.
        //
        // That coupling made a copy edit a silent regression: rewording user-facing prose - the
        // lowest-risk change anyone makes - dropped the patient from the guard message to a generic
        // failure, and stopped the form resetting to step 1. Nothing on the server said the sentence
        // was load-bearing.
        //
        // It was ALSO already wrong: `"already being processed"` matched the slot-reservation
        // conflict too, so a TIME collision was reported to the patient as a PRACTITIONER conflict.
        // The codes distinguish them; the substring never could.
        const guard = readAppointmentGuardOutcome(
          appointmentError instanceof HttpError ? appointmentError.body : undefined,
        );

        if (guard?.code === "ACTIVE_APPOINTMENT_EXISTS") {
          // THE SERVER ALREADY TOLD US WHEN, and this site used to call with no argument at all -
          // so the patient was told "you already have an appointment" and not which one.
          // `buildSelfBookingGuardMessage` has always rendered the date when given one; the data was
          // being thrown away one layer up, with the rest of the OperationOutcome.
          const held = guard.existingAppointmentStart
            ? ({ resourceType: "Appointment", start: guard.existingAppointmentStart } as Appointment)
            : undefined;
          showSelfBookingGuardMessage(held, unblockedOtherPractitionerCount);
          setStepOneRefusal(buildSelfBookingGuardMessage(held, unblockedOtherPractitionerCount));
          setFormDataForSubmission(null);
          setReviewStep(1);
          return;
        }

        if (guard?.code === "BOOKING_IN_PROGRESS") {
          const inProgress = "Another booking request for this practitioner is already being processed. Please wait a moment and try again.";
          toast.error(inProgress, { position: "top-right" });
          setStepOneRefusal(inProgress);
          setReviewStep(1);
          return;
        }

        // A TAKEN SLOT IS A DENIAL, NOT A FAILURE. Ruled 2026-09-06: a refusal renders as a denial
        // naming what is denied, never as a failure. This code rides a different extension from the
        // two guard codes above, so `readAppointmentGuardOutcome` returns null for it and it used to
        // reach the patient through the generic path below as
        // "Failed to create appointment: ERROR: This time is no longer available..." - the server's
        // own sentence behind a wrapper and an internal shout.
        //
        // THE LOSER GOES BACK TO THE TIME STEP. Ruled 2026-09-11: the slot being reviewed no longer
        // exists, so the choice is re-offered rather than left on screen under a message telling the
        // patient to choose another time. Leaving them on the review armed its primary control to
        // repeat the request that had just failed. This follows the in-progress branch above and for
        // the same reason: what they were choosing is no longer choosable.
        if (readSlotReservationCode(
          appointmentError instanceof HttpError ? appointmentError.body : undefined,
        )) {
          // The lost time is let go and the day read again, so the time just taken is gone and another can be picked.
          returnLostPickToTimeChoice(asDenial(errorMessage), {
            clearPick: clearPickedTime,
            forgetPlan: () => setFormDataForSubmission(null),
            showRefusal: (message) => {
              toast.error(message, { position: "top-right" });
              setStepOneRefusal(message);
            },
            rereadTimes: () => loadSlots(watchDate),
            toTimeChoice: () => setReviewStep(1),
          });
          return;
        }

        // A REFUSED BOOKING GOES BACK TO THE CHOICE IT REFUSED. The 403 names something chosen on step 1 -
        // the kind of visit, the place, the clinician - so it is re-offered with the server's reason above
        // it, as the guard branches above do. Left on review, nothing on screen said why Confirm failed.
        const refusal = bookingRefusal(appointmentError);
        if (refusal) {
          toast.error(refusal, { position: "top-right" });
          setStepOneRefusal(refusal);
          setReviewStep(1);
          return;
        }

        // Rethrown as it came, so the report below can tell a server's answer from a code error.
        throw appointmentError;
      }
    } catch (err: unknown) {
      if (isBookingUnconfirmed(err) || isBookingRetired(err)) return;
      console.error("Error creating appointment:", err);
      toast.error(bookingFailure(err), { position: "top-right" });
      // Stay on review step so user can try again
      setReviewStep(2);
    } finally {
      await booking.abandonIfUnsent(begun);
      setSubmitting(false);
    }
  };

  // Format time for display
  const formatTimeForDisplay = (timeString: string, dateString: string = watchDate) => {
    if (!timeString) return "Not selected";
    const [hours, minutes] = timeString.split(":");
    const hour = parseInt(hours);
    const period = hour >= 12 ? "PM" : "AM";
    const displayHour = hour % 12 || 12;
    // The zone is appended ONLY when the patient is on a different clock from the practice - see
    // viewerZoneNotice. A converted time that does not say which clock it is on is worse than no
    // conversion, because nothing tells the patient it happened.
    const label = zoneLabelForVisit(dateString, timeString);
    const zone = label ? ` ${label}` : "";
    return `${displayHour}:${minutes} ${period}${zone}`;
  };


  // Handle clear all
  const handleClearAll = () => {
    selfBookingGuardRequestRef.current += 1;
    setCheckingSelfBookingGuard(false);
    reset();
    setSelectedPractitioner(null);
    setSelectedSchedule(null);
    setPractitionerRole(null);
    setPractitioner(undefined);
    setFormDataForSubmission(null);
    setReviewStep(1);
    // toast.error(undefined);
    // setSuccessState(undefined);
    setSelectedDate(null);
    setSelectedServiceFilter('');
    setSelectedLocationFilter('');
    // Guided-flow state (Task 7 review fix): without this, Clear All left flowAnswers stale - the
    // AnsweredLine summaries kept showing "answered" steps above a form that had just been wiped, the
    // exact "state is active but the UI disagrees" defect this redesign exists to remove.
    setFlowAnswers({});
    setShowAllServices(false);
    // Same hole as handleEditStep above: reset() wipes the reasonForVisit RHF field but leaves any prior
    // "Find my service" results (and the tried-flag) alive, so the next attempt could render stale
    // suggestion cards, or a stale "no match" notice, for a reason the patient no longer typed.
    setSuggestions([]);
    setSuggestTried(false);
  };

  // Handle edit (go back to step 1)
  const handleEdit = () => {
    setReviewStep(1);
  };

  // Handle close dialog
  const handleClose = () => {
    if (onClose) {
      onClose();
    }
    handleClearAll();
  };

  // Steps 3/4's headings name the upstream answer they narrow by ("... that offer {service}", "... at
  // {location}"). isAnswered() runs first - this file has no type gate, so an unguarded `.value` on the
  // StepStatus union would fail at runtime, not compile time.
  const serviceName = isAnswered(flowState.steps.service) ? flowState.steps.service.value : "";
  const locationName = isAnswered(flowState.steps.location) ? flowState.steps.location.value : "";

  const bookingDataPending = isBookingDataLoading ||
    (requireNewPatientExamGate && derivedPatientType === "loading") ||
    (restrictToNewPatientExam && healthcareServicesLoading);
  // A practice with nothing bookable online gets its refusal alone: no how-to note, no Clear All, no Book.
  const offersNothingOnline = !bookingDataPending && serviceFilterOptions.length === 0;

  // No progress bar: removed 2026-07-28 (Spencer). The answered-step summary grid above the live question
  // already shows position - how far you've come and what's left - so a 2px bar added nothing. Its
  // denominator was also misleading: it counted only VISIBLE steps, and every step after the current one
  // is hidden, so it was always answered/(answered+1) - reading 50% after one of seven questions.

  if (isTimeWindowRequest) {
    return (
      <PatientTimeWindowRequest onSuccess={onSuccess} onClose={onClose} bookingOrganization={awayOrganization} />
    );
  }

  if (booking.recovery) {
    return (
      <div className="py-2" data-booking-state="checking">
        <CheckingYourBooking control={booking} onDone={onClose} />
      </div>
    );
  }

  return (
    <div className="py-2">
      <div className="self-booking-head">
      {/* A practice that confirms bookings takes requests, and the outcome says so, so the title does too. */}
      <p className="ahr-overlay-title pb-1 px-2">
        {heldForReview ? "Request an appointment" : "Book an appointment"}
      </p>
      {/* Which practice this books with; a patient can hold more than one. */}
      {bookingOrg?.name && (
        <p className="self-booking-practice px-2">{bookingOrg.name}</p>
      )}
      {/* 🗣️ Spencer, 2026-09-09: the emergency line sits under the heading and is
          always on screen, rather than appearing over a list of suggestions.

          ⛔ UNCONDITIONAL, and that is the design rather than laziness. Showing it only for
          reasons that sound urgent is a classifier, and a classifier can be wrong in the
          direction that kills - while this product never assesses urgency, which is the rule
          the assistant’s own refusal already runs on. A constant sentence cannot be wrong
          that way, and it costs one line on every booking that is not an emergency.

          ⭐ SMALL, ITALIC AND QUIET, in the explanatory-text standard the rest of the app
          uses. A red panel over every booking would be the wall of alarm that came off the
          patient’s home, and a warning shown every time stops being read - which costs
          exactly the reader it exists for.
          🔻 2026-09-09, Spencer: SHORTENED SO IT HOLDS ONE LINE ON A PHONE. At 390 the old sentence
          measured 384px against 357px of available width, so it wrapped directly under the heading -
          and a two-line caution at the top of a form is the shape people learn to skip. The short
          form measures 305px and clears the same space by 52px, which is headroom enough that a
          practice theme nudging the type does not put it back onto two lines.
          ⚠️ THE ASSISTANT SPEAKS THIS SENTENCE TOO, in `assistantAnswer.ts`. They are meant to be the
          SAME words, so a patient meets one sentence in this product rather than two versions of it -
          change one and you have to change the other. */}
      <p className="ahr-field-help px-2 pb-2">
        If emergency, call 911 or go to nearest emergency room.
      </p>
      </div>

      {/* {success && (
        <>
          <Notice status="success" onRemove={() => setSuccessState(undefined)}>
            {success}
          </Notice>
          <Spacer margin="24px" />
        </>
      )} */}

      {/* {error && (
        <>
          <Notice status="error" onRemove={() => setError(undefined)}>
            <div style={{ whiteSpace: "pre-line" }}>{error}</div>
          </Notice>
          <Spacer margin="24px" />
        </>
      )} */}

      {/* Main Form Content */}
      <FormProvider {...methods}>
        <div
          ref={stepBodyRef}
          tabIndex={-1}
          aria-label={STEP_NAMES[reviewStep as 1 | 2 | 3]}
          className="self-booking-body thin-scrollbar p-2"
        >
          {/* Step 1: Selection */}
          {reviewStep === 1 && (
            <div className="space-y-2">
              <StepRefusal message={stepOneRefusal} />
              {asksAsRequest && !offersNothingOnline && (
                <div className="self-booking-note">
                  <p>
                    This is an appointment{" "}
                    <span className="font-semibold">request</span>. Choose your
                    preferred provider and time — the practice will confirm the
                    actual appointment and may adjust the time.
                  </p>
                </div>
              )}
              {/*
               * THE SLOT IS HELD, AND SAYING SO IS THE POINT OF THIS BANNER.
               *
               * A patient picking a time in review mode has one question the old wording left
               * unanswered: can somebody else take this while I wait? Without an answer the safe
               * assumption is that they can, which turns a confirmation delay into a reason to ring
               * the practice - the exact call this screen exists to avoid.
               *
               * IT IS TRUE, AND IT WAS CHECKED RATHER THAN COPIED FROM THE DECK. A booking creates
               * its own `busy` Slot at the chosen time, and the server frees that Slot only on a
               * REJECTED booking - "a rejected booking must never leave the chosen time held as an
               * orphan busy Slot". A pending appointment is not a rejected one, so the time stays
               * held for exactly as long as the practice takes.
               */}
              {viewerIsPatient && isReviewBooking && !offersNothingOnline && (
                <div className="self-booking-note">
                  <p>
                    Pick your preferred time below — the practice will review and
                    confirm your appointment, and you will get an email once it is
                    confirmed. Your time is held while they do.
                  </p>
                </div>
              )}
              {/* Loading gate covers TWO independent async signals that both feed this screen: the
                  booking data itself (schedules/practitioners, isBookingDataLoading) AND, when the org
                  requires the new-patient-exam gate, whether this patient has been SEEN here
                  (derivedPatientType — see the effect above).

                  ⚠️ THE SECOND ONE STILL HAS TO BE WAITED FOR EVEN THOUGH NOBODY IS ASKED ANY MORE.
                  It decides `restrictToNewPatientExam`, which narrows the services to the consult-typed
                  ones. Rendering the service step while it is still "loading" would offer the
                  full catalogue for an instant and then pin it, or pin it and then release it - a list
                  that changes under the patient's hand either way.

                  This does NOT skip the reason step: once the gate clears, it renders as normal. */}
              {servicesUnverified ? (
                <div className="ak-notice flex-wrap" role="status" data-testid="services-unverified">
                  {servicesBasis.state === 'checking' ? 'Checking available services' : 'Available services could not be verified.'}
                  {servicesBasis.state === 'unavailable' && (
                    <button type="button" className="btn btn-blue ml-2" onClick={() => void retryServices()}>Retry</button>
                  )}
                </div>
              ) : bookingDataPending ? (
                <div className="space-y-3 py-2">
                  <Skeleton className="h-12 w-full rounded" />
                  <Skeleton className="h-12 w-full rounded" />
                </div>
              ) : offersNothingOnline ? (
                <div className="rounded-md border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-900" data-testid="nothing-to-offer">
                  {describeNothingToOffer(nothingToOffer, bookingOrg?.name)}
                </div>
              ) : (
                <>
              {/* The answered-step summary: every answered step, in STEP_ORDER, as ONE LIST above the
                  live question - see AnsweredLine for why the row is shaped the way it is.
                  🗣️ Spencer, 2026-09-09: it was `sm:grid-cols-3`, and THAT is what made this modal span
                  the screen. Three answers across a row need the width of three answers, so the dialog
                  grew to roughly 1750px on a desktop; one column took it to 512px. The hairline between
                  rows is doing the work the column gaps used to: it separates four answers that are all
                  the same colour and weight, which is what made them read as one paragraph of black text.
                  The bottom border closes the list off against the question below it. */}
              {answeredSteps.length > 0 && (
                <div className="divide-y divide-border border-b border-border">
                  {answeredSteps.map(({ key, ...item }) => (
                    <AnsweredLine key={key} {...item} />
                  ))}
                </div>
              )}
              {/* Step 0 is RETIRED (Spencer, 2026-09-09). It asked "Have you been seen by X before?"
                  because the old appointment-shaped read could not tell an established patient from an
                  unrecorded one. Seen now means an Encounter, the server reads the same record, and a
                  patient's answer about their own history cannot override one we hold. Nothing is left
                  unexplained by its removal: when the gate applies, the service step renders as answered
                  and locked with its own reason, "required for your first visit with this practice". */}
              {/* Step 1: Reason for visit — required on all flows so the practice knows why. Placed FIRST
                  per Spencer (foundational for the future need-first auto-suggest: describe the need, then
                  narrow by service). It is the WHOLE of reasonCode: the field carries the patient's words
                  and no coding, because nothing in this flow codes a reason. The
                  react-hook-form field (reasonForVisit) stays the source of truth for submission —
                  flowAnswers.reason only drives the guided flow's own step machine, committed on blur so a
                  step never collapses out from under the patient mid-keystroke. */}
              {flowState.steps.reason.kind === "current" && (
                <div className="w-full">
                  <label className="self-booking-q">
                    Reason for booking?{" "}
                    <span className="text-destructive">*</span>
                  </label>
                  <textarea
                    value={watch("reasonForVisit")}
                    onChange={(e) =>
                      setValue("reasonForVisit", e.target.value, {
                        shouldValidate: true,
                      })
                    }
                    rows={3}
                    placeholder="Briefly describe the reason for your visit"
                    className="w-full rounded-[2px] border border-border bg-surface px-3 py-2 text-sm focus:border-primary focus:outline-none focus:ring-1 focus:ring-primary"
                  />
                  {errors.reasonForVisit && (
                    <p className="text-sm text-destructive mt-1">
                      {errors.reasonForVisit.message}
                    </p>
                  )}
                  {/* The step's own advance control, and the ONLY way out of it — the reason used to
                      commit on blur, which meant a patient who typed and stopped saw no next action at
                      all until they happened to click elsewhere. Committing here instead also makes the
                      assist genuinely mandatory (Spencer's spec): the reason cannot become answered
                      without it having run, so the service step can never open with nothing in it.
                      When the new-patient exam pins the service there is nothing to match, so the same
                      control just advances. */}
                  <div className="mt-2 flex justify-end">
                    <button
                      type="button"
                      className="btn btn-blue-ghost"
                      disabled={!watch("reasonForVisit")?.trim() || suggestLoading}
                      onClick={() => {
                        const trimmed = watch("reasonForVisit")?.trim();
                        if (!trimmed) return;
                        setFlowAnswers((prev) => ({ ...prev, reason: trimmed }));
                        if (!matchingAvailable) setShowAllServices(true);
                        else if (flowState.serviceAssistRequired) void runSuggest();
                      }}
                    >
                      {suggestLoading
                        ? "Finding..."
                        : flowState.serviceAssistRequired && matchingAvailable
                          ? "Find my service"
                          : "Continue"}
                    </button>
                  </div>
                  {!matchingAvailable && <p className="mt-2 text-sm text-secondary">Choose a service yourself in this demo; automated service matching is unavailable.</p>}
                </div>
              )}
              {/* Step 2: Service — "Find my service" is a REQUIRED step (the patient clicks it to advance)
                  but its engine is an LLM explicitly allowed to fail (card 038 is fail-open by design, and
                  the standing rule forbids an uncontrolled API in the critical path). So it is a required
                  CLICK, never a required RESULT: two escape hatches — a failed/empty result offers "click
                  here to manually select a service", and a SUCCESSFUL result offers "See all services"
                  alongside the suggestions, because a match that doesn't fit must not trap the patient
                  either. Skipped entirely when the service is pinned by the new-patient exam policy
                  (flowState.serviceAssistRequired === false) — asking an LLM to match an already-decided
                  service is meaningless. Visibility is gated on the step machine (flowState.steps.service),
                  never on serviceFilterOptions.length — that option-count gating is exactly what made this
                  button and the chosen-service token disappear (design doc §0).
                  This step has NO header or button of its own: the "Find my service" control lives in the
                  reason step, which is what commits the reason and runs the assist. Rendering it here too
                  produced a second identical button directly above the results it had just produced. */}
              {flowState.steps.service.kind === "current" &&
                flowState.serviceAssistRequired &&
                !showAllServices && (
                <div className="w-full">
                  {suggestLoading ? (
                    <Skeleton className="h-12 w-full rounded" />
                  ) : suggestions.length > 0 ? (
                    <div className="space-y-2">
                      {/* The current question, named as the deck names it (.curq). A label, not the
                          button: the control stays in the reason step. */}
                      <p className="self-booking-curq">Find my service</p>
                      {/* ONE QUESTION, AND ANSWERING IT IS OPTIONAL. Offered only when more than five
                          services cleared the floor - a list too long to choose from. It sits ABOVE the
                          suggestions rather than in place of them, because the suggestions are already
                          usable and this only shortens them: a patient who ignores it books exactly as
                          they would have. Choosing an answer re-runs the same assist with one more fact,
                          and the question does not come back, so the flow can never interrogate. */}
                      {clarifyQuestion && (
                        <div className="rounded-[2px] border border-line-soft bg-sunken px-3 py-2">
                          <p className="text-sm">{clarifyQuestion.question}</p>
                          <div className="mt-2 flex flex-wrap gap-2">
                            {clarifyQuestion.options.map((option) => (
                              <button
                                key={option}
                                type="button"
                                onClick={() => {
                                  // THE ANSWER FOLDS INTO THE REASON, in the patient's own
                                  // sentence, so the practice reads one reason for the visit
                                  // rather than a reason plus a hidden filter beside it. It is
                                  // also why the second pass needs no extra field: the reason
                                  // itself now carries the fact.
                                  const current = (watch("reasonForVisit") ?? "").trim();
                                  setValue(
                                    "reasonForVisit",
                                    current ? `${current} - ${option}` : option,
                                    { shouldValidate: true },
                                  );
                                  setClarifyAnswer(option);
                                  setClarifyQuestion(undefined);
                                }}
                                className="btn btn-blue-ghost"
                              >
                                {option}
                              </button>
                            ))}
                          </div>
                        </div>
                      )}
                      {matchedCount > suggestions.length && (
                        /* THE COUNT IS STATED, so a reader knows whether they are looking at
                           four or forty before they start scrolling. And when there is no
                           question to tap - the candidates had no clean discriminator - the
                           same line becomes the TEXT PATH, pointing at the reason field that is
                           already on screen rather than adding a second input beside it. Two
                           inputs that look alike leave somebody to work out how they combine
                           into the one sentence the practice reads. */
                        <p className="text-sm text-ink-muted">
                          Showing {suggestions.length} of {matchedCount} services that could fit.
                          {!clarifyQuestion && " Add a little more detail to your reason above and we can narrow it down."}
                        </p>
                      )}
                      <div className="space-y-2 max-h-72 overflow-y-auto">
                        {suggestions.map((s) => {
                          // ONE SUGGESTION IS MARKED, OR NONE IS. The confidence has always reached this
                          // component and was never drawn, so two proposals arrived looking equally
                          // weighted and the patient - the person least equipped to break the tie, which
                          // is why they typed a sentence instead of picking from the catalogue - chose
                          // between two reasonable-sounding rationales.
                          //
                          // And it is withheld when the top two are close. A rank is not a preference:
                          // 0.71 against 0.70 is an ordering accident, and drawing it as RECOMMENDED
                          // turns arithmetic into advice on the one screen where a model's judgement
                          // reaches a patient directly.
                          const recommended = s.id === recommendedId;
                          // HOVER MUST NOT LOOK LIKE RECOMMENDED. Hovering used to set border-primary
                          // and bg-accent, which is exactly what the recommended card wears at rest, so
                          // pointing at any suggestion gave it the marked one's appearance and only the
                          // label told them apart. The primary border is reserved for the recommendation
                          // now; hover keeps its own feedback in the background alone.
                          return (
                            <button
                              key={s.id}
                              type="button"
                              onClick={() => handleServiceFilterChange(s.id)}
                              className={recommended ? "self-booking-sug self-booking-sug--top" : "self-booking-sug"}
                            >
                              <span className="self-booking-sug-name">
                                {s.display}
                                {recommended && <span className="self-booking-recmd">Recommended</span>}
                              </span>
                              <span className="self-booking-sug-why">{s.rationale}</span>
                            </button>
                          );
                        })}
                      </div>
                      {/* Escape hatch 2: a SUCCESSFUL suggest call can still fail the patient if none of
                          the results fit. Without this door alongside the results, a success would trap
                          them worse than a failure would. */}
                      <button
                        type="button"
                        onClick={() => setShowAllServices(true)}
                        className="self-booking-sugout"
                      >
                        None of these?{" "}
                        <span className="self-booking-sugout-link">
                          See all services
                        </span>
                      </button>
                    </div>
                  ) : suggestTried ? (
                    // Escape hatch 1: the assist failed or found nothing - the only way out is the same
                    // manual list the success path offers, so a fail-open LLM can never dead-end the flow.
                    <div className="self-booking-note">
                      Unable to find a matching service based on your reason for booking, please be more
                      specific or{" "}
                      <button
                        type="button"
                        onClick={() => setShowAllServices(true)}
                        className="self-booking-note-link"
                      >
                        see all services
                      </button>
                      .
                    </div>
                  ) : null}
                </div>
              )}
              {/* Care type + Location — paired 50/50 on desktop to save vertical space. */}
              <div className="grid grid-cols-1 md:grid-cols-2 gap-3 items-start">
              {/* Derived service picker — the org's patient-facing roles offered by booking-enabled
                  practitioners. A Select (not a token grid) so it scales when a practice offers many
                  services; the options stay plain-language and it matches the Location select below.
                  Rendered once the assist has been bypassed (showAllServices) or was never required (a
                  pinned/single-remaining-option service — handled entirely by the step machine, see the
                  AnsweredLine above). Selecting feeds handleServiceFilterChange -> selectedServiceFilter ->
                  practitionerOptions, narrowing the practitioner list. Options are the self-bookable
                  services (design §4), not org roles. */}
              {/* No live-update backstop needed here (Task 9): this whole branch is already nested inside
                  the `serviceFilterOptions.length === 0 ? <amber "no bookable services" box> : <>...` split
                  above (:2431) — serviceFilterOptions dropping to 0 flips THAT outer conditional on the next
                  render, replacing this entire step tree before this Select could ever go blank. Adding a
                  second, inner `serviceFilterOptions.length === 0` check here would be unreachable dead
                  code (same memoized value, same render pass). */}
              {flowState.steps.service.kind === "current" &&
                (showAllServices || !flowState.serviceAssistRequired) && (
                  <div>
                    {/* NOT a <label>: a Radix Select's trigger is a button, and `htmlFor` cannot bind
                        to it - so the label named nothing and clicking it focused nothing. The trigger
                        takes `aria-labelledby` instead, which is what actually makes a screen reader
                        announce the question when the control receives focus. */}
                    <p id="book-service-label" className="self-booking-q">
                      What type of care do you need?
                    </p>
                    <Select
                      value={selectedServiceFilter}
                      onValueChange={handleServiceFilterChange}
                    >
                      <SelectTrigger aria-labelledby="book-service-label" className="w-full rounded px-2">
                        <SelectValue placeholder="Select a service" />
                      </SelectTrigger>
                      <SelectContent className="bg-white text-sm">
                        <SelectGroup>
                          {serviceFilterOptions.map((opt) => (
                            <SelectItem key={opt.id} value={opt.id} disabled={!opt.bookable}>
                              {opt.display}
                              {!opt.bookable && (
                                // The reason, not just the refusal. "Call us" is the whole of what the
                                // patient can do about it: this is a gap in how the practice set the
                                // service up, and nothing the patient does on this screen will close it.
                                <span className="block text-xs text-muted-foreground">
                                  Not available to book online - please call the practice
                                </span>
                              )}
                            </SelectItem>
                          ))}
                        </SelectGroup>
                      </SelectContent>
                    </Select>
                  </div>
                )}
              {/* Location — "Select from the following locations that offer {service}:" while current
                  (a real Select, with an explicit "Any location" choice first); collapses into the
                  AnsweredLine above once answered. A single remaining site is answered by the step machine
                  with its reason stated, not degraded to a silent, non-interactive label — that silent lock
                  ("it just feels broken") is the reported bug this redesign removes (design doc §0). */}
              {flowState.steps.location.kind === "current" &&
                (locationSiteOptions.length === 0 ? (
                  // Backstop (Task 9): only reachable if a live update strips the last real site out from
                  // under an open, unanswered step - resolveFlowState only auto-locks at exactly 1
                  // remaining option (bookingFlowSteps.ts), so 0 stays "current" and would otherwise render
                  // a silently near-empty Select (locationFilterOptions always has at least the synthetic
                  // "Any location" entry, so the real signal is locationSiteOptions - the axis
                  // resolveFlowState itself narrows on). Generic copy, not a designed flow state; unlike
                  // the service Select (see the comment above it), there is no outer gate that already
                  // covers this case.
                  <p className="text-sm text-muted-foreground py-2">
                    {selectedServiceFilter ? (
                      // THE ORDINARY CASE, WHICH THIS BRANCH USED TO REPORT AS A RACE. It is reachable
                      // by any route that sets a service without going through the picker - a tapped
                      // assist suggestion, a single remaining option the step machine answered - so the
                      // sentence has to be true here too and not only on the list above.
                      <>
                        <span className="font-semibold">{serviceName}</span> cannot be booked online at
                        this practice. Please call to arrange it.
                      </>
                    ) : (
                      "Those options just changed. Please reselect."
                    )}
                  </p>
                ) : (
                  <div>
                    <label id="book-location-label" className="self-booking-q">
                      Select from the following locations that offer{" "}
                      <span className="font-semibold">{serviceName}</span>:
                    </label>
                    <Select value={selectedLocationFilter} onValueChange={handleLocationFilterChange}>
                      <SelectTrigger aria-labelledby="book-location-label" className="w-full rounded px-2">
                        <SelectValue placeholder="Select a location" />
                      </SelectTrigger>
                      <SelectContent className="bg-white text-sm">
                        <SelectGroup>
                          {locationFilterOptions.map((opt) => (
                            <SelectItem key={opt.id} value={opt.id}>
                              {opt.display}
                            </SelectItem>
                          ))}
                        </SelectGroup>
                      </SelectContent>
                    </Select>
                  </div>
                ))}
              </div>
              {/* Practitioner + Date — paired 50/50; the availability/guard alerts render full-width below. */}
              <div className="grid grid-cols-1 md:grid-cols-2 gap-4 items-start">
                {/* Practitioner Selection — collapses into an AnsweredLine once answered, including the
                    single-remaining-practitioner auto-lock (kept genuinely usable by the silent auto-select
                    effect above handleRecommendationSelect — see its comment). */}
                <div className="w-full">
                  {flowState.steps.practitioner.kind === "current" && (
                    <>
                  {/* "Recommended for your reason" (card 040) — reason + chosen service -> ranked
                      practitioners, rendered directly ABOVE the manual picker. Suggest-and-highlight:
                      it never hides/replaces the Select below; empty (fail-open) renders nothing. */}
                  <PractitionerRecommendationCallout
                    recommendations={recommendations}
                    onSelect={handleRecommendationSelect}
                  />
                  <label id="book-practitioner-label" className="self-booking-q">
                    Select a{" "}
                    {asksAsRequest ? "preferred practitioner" : "practitioner"}{" "}
                    offering <span className="font-semibold">{serviceName}</span> at{" "}
                    <span className="font-semibold">{locationName}</span>{" "}
                    <span className="text-destructive">*</span>
                  </label>
                  <Select
                    value={watchPractitionerId}
                    onValueChange={handleScheduleChange}
                  >
                    <SelectTrigger aria-labelledby="book-practitioner-label" className="w-full rounded px-2">
                      <SelectValue placeholder="Select a practitioner" />
                    </SelectTrigger>

                    <SelectContent className="bg-white text-sm text-start w-full">
                      <SelectGroup className="max-content">
                        <SelectLabel>Available Practitioners</SelectLabel>
                        {practitionerOptions.length > 0 ? (
                          practitionerOptions.map((schedule) => {
                            const displayName = schedulePractitionerName(schedule, livePractitioners, undefined, getScheduleRole(schedule));
                            const subtitle =
                              schedule.specialty?.[0]?.text ||
                              schedule.specialty?.[0]?.coding?.[0]?.display ||
                              schedule.serviceType?.[0]?.text ||
                              schedule.serviceType?.[0]?.coding?.[0]?.display;
                            return (
                              <SelectItem
                                key={schedule.id}
                                value={schedule.id as string}
                              >
                                <div className="flex items-center gap-2 text-start">
                                  <div className="flex flex-col">
                                    <span className="whitespace-normal break-words">
                                      {displayName}
                                    </span>
                                    {subtitle && (
                                      <span className="text-xs text-muted-foreground">
                                        {subtitle}
                                      </span>
                                    )}
                                  </div>
                                </div>
                              </SelectItem>
                            );
                          })
                        ) : (
                          <SelectItem
                            disabled
                            key="no-practitioners"
                            value="no-practitioners"
                          >
                            <div className="flex items-center gap-2">
                              No practitioners available
                            </div>
                          </SelectItem>
                        )}
                      </SelectGroup>
                    </SelectContent>
                  </Select>
                  {/* OUTSIDE the dropdown on purpose. The "No practitioners available" line lives in the
                      list, so it is only seen by somebody who opens a picker to find out why it looks
                      wrong - which is after they have already been confused. This says the same thing
                      where they are looking, and adds the part that was missing: what to change. */}
                  {deadEnd && (
                    <p className="text-sm text-ink-muted mt-1">{deadEnd}</p>
                  )}
                  {errors.practitionerId && (
                    <p className="text-sm text-destructive mt-1">
                      {errors.practitionerId.message}
                    </p>
                  )}
                    </>
                  )}
                </div>
              {/* Date — a select of the practitioner's available dates. Shown once a practitioner with
                  availability is chosen; the fallback covers a provider with no online availability. Gated
                  on the step machine (Task 9): answered collapses to an AnsweredLine the instant
                  flowAnswers.date lands, rather than waiting on a time pick too — the old "Date & Time"
                  merged token (renderSelectionToken) held the Date select open until BOTH fields were set,
                  which broke the one-question-at-a-time contract steps 0-4 already keep. Date/time have no
                  narrowable `options` in resolveFlowState (bookingFlowSteps.ts), so this step can only ever
                  be hidden/current/answered via flowAnswers — never auto-locked to a single option. */}
              {watchPractitionerId &&
                watchAppointmentType &&
                !checkingSelfBookingGuard &&
                !activePractitionerAppointment &&
                (() => {
                  const todayStart = new Date();
                  todayStart.setHours(0, 0, 0, 0);
                  // A practitioner is "not available" only when there are genuinely no future availability
                  // events. The legacy sub-conditions this used to OR in - !practitionerRole.availableTime?.length
                  // (role-level hours, empty now that hours live on the Schedule) and
                  // !selectedSchedule.planningHorizon (only the REPRESENTATIVE block, not the union) - both
                  // false-fired: generateAvailabilityEvents already returns [] when a schedule's own
                  // planningHorizon is missing, so availabilityEvents (unioned across every matching location
                  // block) is the ground truth (, Finding C).
                  // event.start is now a local-ISO string (Task 3); parse before comparing to a Date.
                  const noAvailability =
                    selectedSchedule &&
                    practitionerRole &&
                    !opensFrom(availabilityEvents, todayStart);
                  const practitionerPhone = practitionerRole?.telecom?.find(
                    (t) => t.system === "phone",
                  )?.value;

                  if (noAvailability) {
                    return (
                      <div className="flex items-start gap-3 rounded-lg border border-amber-200 bg-amber-50 p-4 text-sm text-amber-800 mt-2 md:col-span-2">
                        <Phone className="mt-0.5 h-4 w-4 shrink-0" />
                        <p>
                          Online scheduling for{" "}
                          <span className="font-semibold">
                            {selectedPractitioner?.name ?? "this provider"}
                          </span>{" "}
                          is not currently available.{" "}
                          {practitionerPhone ? (
                            <>
                              Please call{" "}
                              <a
                                href={`tel:${practitionerPhone}`}
                                className="font-semibold underline"
                              >
                                {practitionerPhone}
                              </a>{" "}
                              for assistance from the receptionist.
                            </>
                          ) : (
                            "Please contact the receptionist for assistance."
                          )}
                        </p>
                      </div>
                    );
                  }

                  // Answered renders in the summary grid at the top, not here.
                  if (flowState.steps.date.kind !== "current") return null;

                  // Spencer, 2026-09-09: DATE joins the list above rather than sitting apart from it -
                  // same label column, same row rhythm, its control where the answers' values are. The live
                  // question is then the LAST ROW OF ONE LIST rather than a form stacked under a summary, so
                  // the eye keeps one left edge the whole way down and the modal reads as a single object.
                  // The label takes the summary's label type rather than the old `text-xs` field label for
                  // the same reason: two type sizes doing one job is what made these read as two unrelated
                  // blocks.
                  // `-mt-4` because the gap above this row measured 32px, twice what it should be.
                  // The row's own `py-2.5` is only 10px of that; the rest arrives from the step wrapper's
                  // `space-y-2` and the summary list's closing border, neither of which is this row's to
                  // change. Pulling the row up 16px halves the gap and leaves the rhythm of the rows
                  // above it - which is correct - untouched.
                  return (
                    <div className="grid grid-cols-[92px_1fr] items-center gap-x-3 py-2.5 -mt-5 md:col-span-2">
                      {/* 🚨 A <span>, NOT A <p>, AND THAT IS LOAD-BEARING. This mount gives every <p> its
                          own font-size and weight at (1,0,1), while `text-[10px]` is an ARBITRARY-VALUE
                          utility that Tailwind emits bare at (0,1,0) - so as a <p> this label lost the
                          cascade and drew at 15px/600, twice the size of the identical labels in the rows
                          directly above it, with nothing anywhere reporting a problem. AnsweredLine's
                          labels are spans for exactly this reason.
                          ⛔ The id stays - the Select below is `aria-labelledby` this element. */}
                      <span id="book-date-label" className="text-[10px] font-bold uppercase tracking-wide text-muted-foreground">
                        Date
                      </span>
                      {availableDates.length === 0 ? (
                        <p className="text-sm text-ink-muted" data-testid="book-no-dates">
                          No open times to book online. Choose another practitioner or type of care, or contact the practice.
                        </p>
                      ) : (
                      <Select
                        value={watchDate || undefined}
                        onValueChange={(value) => {
                          setValue("date", value, { shouldValidate: true });
                          setValue("startTime", "", { shouldValidate: true });
                          setValue("endTime", "", { shouldValidate: true });
                          const [year, month, day] = value
                            .split("-")
                            .map(Number);
                          const parsedDate = new Date(year, month - 1, day);
                          setSelectedDate(parsedDate);
                          // No `options.date` axis exists in resolveFlowState (see the comment above this
                          // block), so - mirroring the "Any location" precedent in
                          // handleLocationFilterChange - the answer committed here is the already-formatted
                          // display string, not the raw "YYYY-MM-DD" value: there is no options lookup that
                          // would otherwise turn the raw id into a pretty label for the AnsweredLine above.
                          setFlowAnswers((prev) => ({
                            ...prev,
                            date: parsedDate.toLocaleDateString(undefined, {
                              weekday: "short",
                              month: "short",
                              day: "numeric",
                              year: "numeric",
                            }),
                          }));
                        }}
                      >
                        <SelectTrigger aria-labelledby="book-date-label" className="w-full rounded px-2">
                          <SelectValue placeholder="Select a date" />
                        </SelectTrigger>
                        <SelectContent className="bg-white text-sm">
                          <SelectGroup>
                            {availableDates.map((opt) => (
                              <SelectItem key={opt.value} value={opt.value}>
                                {opt.label}
                              </SelectItem>
                            ))}
                          </SelectGroup>
                        </SelectContent>
                      </Select>
                      )}
                      {/* No "Please select a date" error under the control — the placeholder already
                          says "Select a date", so the message only repeated it in red before the patient
                          had done anything wrong. The zod rule still gates submission. */}
                    </div>
                  );
                })()}
              </div>

              {checkingSelfBookingGuard && (
                <div className="flex items-start gap-3 rounded-[2px] border border-border bg-sunken p-4 text-sm text-ink mt-2">
                  <Clock4 className="mt-0.5 h-4 w-4 shrink-0" />
                  <p>Checking your existing appointments...</p>
                </div>
              )}

              {!checkingSelfBookingGuard && activePractitionerAppointment && (
                <div className="flex items-start gap-3 rounded-lg border border-amber-200 bg-amber-50 p-4 text-sm text-amber-800 mt-2">
                  <CalendarDays className="mt-0.5 h-4 w-4 shrink-0" />
                  <p>
                    {buildSelfBookingGuardMessage(
                      activePractitionerAppointment,
                      unblockedOtherPractitionerCount,
                    )}
                  </p>
                </div>
              )}

              {/* Time — a select of the chosen date's open start times. Gated on the step machine
                  (Task 9), same reasoning as the Date block above: the old gate (`watchDate &&
                  !watchStartTime`) also meant editing Time via an AnsweredLine could never re-open the
                  Select, because `watchStartTime` still held the prior pick — `!watchStartTime` would stay
                  false forever. `flowState.steps.time.kind === "current"` doesn't have that problem: it
                  flips back the moment `flowAnswers.time` clears, and (fix round 1) `handleEditStep` now
                  also resets the `startTime`/`endTime` RHF fields themselves (see its definition), so the
                  reopened Select's own `value` prop no longer matches the prior pick either — re-selecting
                  the SAME time is a real change again, not a silent Radix no-op. */}
              {flowState.steps.time.kind === "current" &&
                !checkingSelfBookingGuard &&
                !activePractitionerAppointment && (
                  <div className="grid grid-cols-[92px_1fr] items-center gap-x-3 py-2.5 !-mt-1">
                    {/* TIME takes the DATE row's shape - see that block. Only these two steps do:
                        every other step asks a real QUESTION ("What type of care do you need?",
                        "Reason for booking?"), and a question does not survive being squeezed into a
                        92px label column - it belongs stacked above its control. "Date" and "Time" are
                        bare nouns, which is exactly what a label column is for. */}
                    {/* A <span> for the reason the date label is one: this mount sizes every <p>
                        at (1,0,1) and beats the bare `text-[10px]` utility, so a <p> here draws at 15px
                        and the two live questions stop matching the rows above them. */}
                    <span id="book-time-label" className="text-[10px] font-bold uppercase tracking-wide text-muted-foreground">
                      Time
                    </span>
                    <div className="min-w-0">
                    {/* Shown only when the patient's clock differs from the practice's. Every time
                        on this screen is in the PATIENT's timezone, and saying so is what keeps that
                        from being a silent conversion the patient cannot notice — a "7:00 AM" that is
                        really the practice's 9:00 AM is a missed appointment if nobody says which. */}
                    {viewerZoneNotice && (
                      <p
                        className="text-sm text-muted-foreground mb-2"
                        data-testid="viewer-timezone-notice"
                      >
                        Times are shown in your timezone (
                        {viewerZoneNotice.viewerZoneLabel}), which is different from the
                        practice&rsquo;s.
                      </p>
                    )}
                    {loading ? (
                      <Skeleton className="h-12 w-full rounded" />
                    ) : busyRead.status === "failed" ? (
                      <div className="ak-notice ak-notice--error" role="alert" data-testid="booking-times-failed">
                        <p>Available times could not be loaded for this date. Nothing is offered until the booked times are known.</p>
                        <button type="button" className="btn btn-blue-ghost" onClick={() => setBusyAttempt((attempt) => attempt + 1)}>
                          Try again
                        </button>
                      </div>
                    ) : availableTimeOptions.length === 0 ? (
                      <p className="text-sm text-muted-foreground py-2">
                        No open times for this date. Please try another date.
                      </p>
                    ) : (
                      <Select
                        value={watchStartTime || undefined}
                        onValueChange={(value) => {
                          const [hours, minutes] = value.split(":").map(Number);
                          const end = new Date();
                          end.setHours(
                            hours,
                            minutes + appointmentDurationMinutes,
                            0,
                            0,
                          );
                          const endStr = `${end
                            .getHours()
                            .toString()
                            .padStart(2, "0")}:${end
                            .getMinutes()
                            .toString()
                            .padStart(2, "0")}`;
                          setValue("startTime", value, { shouldValidate: true });
                          setValue("endTime", endStr, { shouldValidate: true });
                          // Mirrors the Date block: no `options.time` axis exists, so the answer committed
                          // is the pretty display string (formatTimeForDisplay), not the raw "HH:MM" value.
                          setFlowAnswers((prev) => ({
                            ...prev,
                            time: formatTimeForDisplay(value),
                          }));
                        }}
                      >
                        <SelectTrigger aria-labelledby="book-time-label" className="w-full rounded px-2">
                          <SelectValue placeholder="Select a time" />
                        </SelectTrigger>
                        <SelectContent className="bg-white text-sm">
                          <SelectGroup>
                            {availableTimeOptions.map((opt) => (
                              <SelectItem key={opt.value} value={opt.value}>
                                {opt.label}
                              </SelectItem>
                            ))}
                          </SelectGroup>
                        </SelectContent>
                      </Select>
                    )}
                    </div>
                    {/* Same as the date step: the placeholder already says "Select a time", so the
                        error only restated it in red. The zod rule still gates submission. */}
                  </div>
                )}
                </>
              )}
            </div>
          )}

          {/* Step 2: Review */}
          {reviewStep === 2 && (
            <div className="py-2">
              <div className="divide-y divide-border border-b border-border" data-testid="self-booking-review-rows">
                {answeredSteps.map(({ key, onEdit, ...item }) => (
                  <AnsweredLine
                    key={key}
                    {...item}
                    value={key === "service"
                      ? reviewServiceLabel(
                        reviewResolvedBlock?.serviceRef?.display,
                        serviceFilterOptions.find((opt) => opt.id === selectedServiceFilter)?.display,
                        pinnedServiceLabel,
                      )
                      : item.value}
                    onEdit={onEdit ? () => { setReviewStep(1); onEdit(); } : undefined}
                  />
                ))}
              </div>

              {/* The practice agreements this patient still owes, one box each; Confirm stays off
                  until every box is ticked. Renders nothing when all three are already agreed. */}
              <SelfBookingAuthorization
                ref={selfBookingAuthorizationRef}
                organizationName={organizationName}
                organizationId={orgOverride}
                onGateChange={setSelfBookingAuthorizationGate}
                subjectPatientId={viewerIsPatient ? undefined : patientState?.id}
              />

              {/* THE REFUSAL, INSIDE THE DIALOG — because a toast is not a guarantee that anything was
                  SHOWN. Watched in a browser 2026-08-20: a guardian booking for a dependent got a 403 from
                  `/org-authorization/agree`, and the screen said nothing at all. Confirm Booking looked
                  broken.

                   The handler already calls `toast.error`, and that call is correct — this does not
                  replace it. But a toast is `position: fixed` inside a provider tree mounted into somebody
                  else's WordPress page, so ANY ancestor with a transform, filter or containment turns it
                  into a box positioned against that ancestor instead of the viewport, where it can land
                  off-screen or clipped. Its z-index of 999999999 does not help: that only orders siblings
                  within whatever stacking context it ended up in.
                   Text rendered HERE is inside the dialog the person is already looking at, so it cannot
                  be hidden by a stacking context the dialog itself is not subject to.

                   It is deliberately not cleared on a timer. The booking did not happen; the sentence
                  stays until they change something. */}
              {confirmRefusal && (
                <p
                  className="mt-3 text-sm text-destructive"
                  role="alert"
                  data-testid="self-booking-confirm-refusal"
                >
                  {confirmRefusal}
                </p>
              )}
              {reviewZoneMissing && (
                <div className="self-booking-zone-missing" role="alert" data-testid="self-booking-zone-missing">
                  <p className="self-booking-zone-missing__title">This booking cannot be completed</p>
                  <p>This location&rsquo;s time zone is missing. Contact the practice to book.</p>
                </div>
              )}
            </div>
          )}

          {/* The confirmation. Reached only on the standalone page, and only after the appointment
              actually exists - it is set inside the success branch, after the POST resolved, never
              optimistically. A booking that fails lands back on step 1 or 2 with its own message and
              never reaches here. */}
          {reviewStep === 3 && bookingConfirmation && (
            <div className="py-2" data-booking-state="confirmed">
              <div className="self-booking-done">
                <span className="self-booking-done-tick" aria-hidden="true">
                  <Check className="size-3.5" strokeWidth={3} />
                </span>
                <div>
                  <h3 className="self-booking-done-title">
                    {bookingConfirmation.pendingPracticeConfirmation
                      ? "Your request has been sent"
                      : "Your appointment is booked"}
                  </h3>
                  <p className="self-booking-done-sub">
                    {bookingConfirmation.pendingPracticeConfirmation
                      ? `${bookingConfirmation.locationLabel} will confirm the time with you. Until then it shows as pending on your appointments.`
                      : "It is on your appointments now. You do not need to do anything else."}
                  </p>
                </div>
              </div>

              <div className="self-booking-done-rows">
                <AnsweredLine label="Date" value={bookingConfirmation.dateLabel} />
                <AnsweredLine label="Time" value={bookingConfirmation.timeLabel} />
                {bookingConfirmation.practitionerName && (
                  <AnsweredLine label="With" value={bookingConfirmation.practitionerName} />
                )}
                <AnsweredLine label="Location" value={bookingConfirmation.locationLabel} />
                <AnsweredLine label="Service" value={bookingConfirmation.serviceLabel} />
              </div>
            </div>
          )}

        </div>
          {/* Action Buttons */}
          <div className="gap-2 px-2">
            {reviewStep === 3 ? (
              <div className="flex gap-2 justify-end mt-4">
                {/* The ONLY control here, deliberately. There is no Confirm on this screen: pressing it
                    again was the obvious next action and it either did nothing or produced a refusal
                    about a booking "already being processed" - for one that had in fact succeeded.
                    It says DONE rather than "Book another appointment", which is what it read while this
                    screen belonged to the retired page. A patient who has just booked is finished, and
                    the surface is now a dialog that has somewhere to go: away. Offering to book again is
                    the same instinct the no-Confirm rule exists to stop, one step further on. */}
                <Button
                  type="button"
                  onClick={() => {
                    setBookingConfirmation(null);
                    handleClose();
                  }}
                  className="btn btn-blue cursor-pointer"
                >
                  Done
                </Button>
              </div>
            ) : reviewStep === 1 ? (
              <div className="flex gap-2 justify-end mt-4">
                {!offersNothingOnline && (
                  <Button
                    type="button"
                    onClick={handleClearAll}
                    disabled={loading || submitting}
                    className="btn btn-amber cursor-pointer"
                  >
                    Clear All
                  </Button>
                )}
                {/* Plain <button>, not the shared <Button>: that component applies variant="default"
                    (bg-primary), and cn()/tailwind-merge does not treat the custom `btn-green` as
                    conflicting with a Tailwind utility — so both classes survive and the blue variant
                    still won. Every other modal here (ArchiveConfirmModal, RecordAuthorizationDialog,
                    RoomModal) uses a plain button with the btn classes for exactly this reason. */}
                <button
                  type="button"
                  data-kind="primary-action"
                  data-state={
                    offersNothingOnline ||
                    !isValid ||
                    checkingSelfBookingGuard ||
                    activePractitionerAppointment ||
                    (requireNewPatientExamGate && derivedPatientType === "loading")
                      ? "disabled"
                      : "enabled"
                  }
                  disabled={
                    offersNothingOnline ||
                    !isValid ||
                    loading ||
                    !pickedTimeIsOffered ||
                    submitting ||
                    checkingSelfBookingGuard ||
                    Boolean(activePractitionerAppointment) ||
                    (requireNewPatientExamGate && derivedPatientType === "loading")
                  }
                  onClick={handleReview}
                  className="btn btn-green"
                >
                  {loading
                    ? "Loading..."
                    : asksAsRequest
                      ? "Request"
                      : "Book"}
                </button>
              </div>
            ) : reviewStep === 2 ? (
              /* Back at the left (Spencer, 2026-09-01), the commitment at the right. */
              <>
              <div className="self-booking-foot">
                <button
                  type="button"
                  onClick={handleEdit}
                  disabled={submitting}
                  className="self-booking-back"
                >
                  <ArrowBigLeftDash className="size-4" aria-hidden="true" />
                  Back
                </button>
                {/* Plain <button> with the btn classes, for the reason spelled out on the Book button
                    in reviewStep 1: the shared <Button> applies variant="default" (bg-primary) and
                    tailwind-merge does not treat btn-green as conflicting, so the variant wins. This
                    one carried ONLY bg-primary and no btn class at all, and bg-primary is inert under
                    the id-scoped theme - measured rgba(0, 0, 0, 0) on a transparent ground with
                    rgb(51, 48, 44) body ink. The last action of the booking flow was painting as plain
                    text while Book above it and Done after it were both filled. Green because the
                    standard reserves amber for "a state or a non-primary act" and confirming is the
                    primary act - the same green as Book, the same affirmative one step back. */}
                <button
                  type="button"
                  data-kind="primary-action"
                  onClick={handleCreateAppointment}
                  data-state={
                    selfBookingAuthorizationSatisfied(selfBookingAuthorizationGate)
                      ? "enabled"
                      : "awaiting-authorization"
                  }
                  disabled={
                    submitting ||
                    !formDataForSubmission ||
                    !pickedTimeIsOffered ||
                    checkingSelfBookingGuard ||
                    Boolean(activePractitionerAppointment) ||
                    // Without the location's clock there is no such time to book.
                    reviewZoneMissing ||
                    // The patient has been shown the authorization and has not answered it, or it
                    // could not be shown at all. Either way there is nothing to confirm yet.
                    !selfBookingAuthorizationSatisfied(selfBookingAuthorizationGate)
                  }
                  className="btn btn-green"
                >
                  {submitting
                    ? asksAsRequest
                      ? "Submitting..."
                      : "Booking..."
                    : asksAsRequest
                      ? "Send request"
                      : "Confirm booking"}
                </button>
              </div>
              {selfBookingAuthorizationGate === "unanswered" && (
                <p className="self-booking-whynot" data-testid="self-booking-whynot">
                  Please answer the agreements above before confirming.
                </p>
              )}
              </>
            ) : (
              ""
            )}
          </div>
      </FormProvider>
    </div>
  );
};

export default PatientBookAppointment;