@ticketboothapp/booking 1.2.61 → 1.2.63

package/src/components/booking/PrivateShuttleBookingFlow.tsx

@@ -1176,9 +1176,10 @@ export function PrivateShuttleBookingFlow({
   const cancelPendingReservation = useCallback(() => {
     if (paymentSubmitInFlightRef.current) return;
     const pending = pendingReservationRef.current;
-    if (!pending) return;
-    pendingReservationRef.current = null;
-    cancelReservation(pending.reservationReference).catch(() => {});
+    if (pending) {
+      pendingReservationRef.current = null;
+      cancelReservation(pending.reservationReference).catch(() => {});
+    }
     setShowCheckoutModal(false);
     setCheckoutModalData(null);
     setCheckoutClientSecret('');
@@ -1187,9 +1188,10 @@ export function PrivateShuttleBookingFlow({
   const cancelPendingReservationBestEffort = useCallback(() => {
     if (paymentSubmitInFlightRef.current) return;
     const pending = pendingReservationRef.current;
-    if (!pending) return;
-    pendingReservationRef.current = null;
-    cancelReservationBestEffort(pending.reservationReference);
+    if (pending) {
+      pendingReservationRef.current = null;
+      cancelReservationBestEffort(pending.reservationReference);
+    }
     setShowCheckoutModal(false);
     setCheckoutModalData(null);
     setCheckoutClientSecret('');

package/src/components/booking/PromoCodeInput.tsx

@@ -20,6 +20,8 @@ interface PromoCodeInputProps {
   onApply: () => void;
   onRemove: () => void;
   locked?: boolean;
+  /** Hide the −$ discount suffix (pending server-backed totals). */
+  hideDiscountAmount?: boolean;
 }
 
 export function PromoCodeInput({
@@ -35,6 +37,7 @@ export function PromoCodeInput({
   onApply,
   onRemove,
   locked = false,
+  hideDiscountAmount = false,
 }: PromoCodeInputProps) {
   const showSuffix = !!(appliedPromoCode || promoCodeValidating || promoCodeError);
   const suffixPadding =
@@ -97,7 +100,7 @@ export function PromoCodeInput({
             </div>
           )}
         </div>
-        {promoDiscountAmount > 0 && (
+        {promoDiscountAmount > 0 && !hideDiscountAmount && (
           <span className={styles.promoDiscount}>
             -{formatCurrencyAmount(promoDiscountAmount, currency, locale as 'en' | 'fr')}
           </span>

package/src/components/booking/ReturnTimeSelector.tsx

@@ -20,6 +20,8 @@ interface ReturnTimeSelectorProps {
   t: TranslationFn;
   onReturnSelect: (option: ReturnOption) => void;
   getStaySummary: (returnDateTime: Date) => string | null;
+  /** Hide per-person return add-on amounts until server-backed pricing. */
+  suppressPerPersonPrices?: boolean;
 }
 
 export function ReturnTimeSelector({
@@ -33,6 +35,7 @@ export function ReturnTimeSelector({
   t,
   onReturnSelect,
   getStaySummary,
+  suppressPerPersonPrices = false,
 }: ReturnTimeSelectorProps) {
   const sortedReturnOptions = [...returnOptions].sort((a, b) => {
     const timeA = parseISO(a.dateTime).getTime();
@@ -129,11 +132,15 @@ export function ReturnTimeSelector({
                   )}
                 </div>
                 <div className={`${styles.price} ${priceClass}`}>
-                  {priceAdjustmentPerPerson === 0
-                    ? 'Included'
-                    : priceAdjustmentPerPerson > 0
-                    ? `+${formatCurrencyAmount(priceAdjustmentPerPerson, currency, locale as 'en' | 'fr')} per person`
-                    : `${formatCurrencyAmount(priceAdjustmentPerPerson, currency, locale as 'en' | 'fr')} per person`}
+                  {suppressPerPersonPrices ? (
+                    '—'
+                  ) : priceAdjustmentPerPerson === 0 ? (
+                    'Included'
+                  ) : priceAdjustmentPerPerson > 0 ? (
+                    `+${formatCurrencyAmount(priceAdjustmentPerPerson, currency, locale as 'en' | 'fr')} per person`
+                  ) : (
+                    `${formatCurrencyAmount(priceAdjustmentPerPerson, currency, locale as 'en' | 'fr')} per person`
+                  )}
                 </div>
               </div>
             </button>

package/src/components/booking/TicketSelector.tsx

@@ -46,6 +46,8 @@ interface TicketSelectorProps {
   minimumQuantities?: Record<string, number>;
   /** Optional per-category unit floor (change flow). Keys are uppercased categories (e.g. ADULT). */
   ticketUnitFloorByCategory?: Map<string, number>;
+  /** Hide unit/strike prices (customer change flow until server-backed pricing is shown). */
+  suppressUnitPrices?: boolean;
 }
 
 export function TicketSelector({
@@ -67,6 +69,7 @@ export function TicketSelector({
   onQuantityChange,
   minimumQuantities,
   ticketUnitFloorByCategory,
+  suppressUnitPrices = false,
 }: TicketSelectorProps) {
   /** Party size vs tighter of pickup/return vacancies (parent passes min of both legs). */
   const isOverbookedTickets = totalQuantity > selectedVacancies;
@@ -147,7 +150,9 @@ export function TicketSelector({
                   )}
                 </p>
                 <p className={styles.price}>
-                  {hasDiscount ? (
+                  {suppressUnitPrices ? (
+                    <span className="text-stone-400">—</span>
+                  ) : hasDiscount ? (
                     <>
                       <span className={styles.priceStrikethrough}>
                         {formatCurrencyAmount(displayBasePrice, currency, locale as 'en' | 'fr')}

package/src/components/booking/booking-flow-types.ts

@@ -0,0 +1,141 @@
+import type { RefObject } from 'react';
+import type { Product } from '../../lib/booking-api';
+import type { BookingSourceMetadata } from '../../lib/booking/source-metadata';
+import type { Currency } from './CurrencySwitcher';
+import type { BookingFlowUiOptions } from './booking-flow-ui';
+
+/** Live selection snapshot for change-booking compare UI (parent dialog). */
+export interface ChangeFlowSelectionPreview {
+  tourName: string;
+  dateTime: string | null;
+  ticketsLine: string;
+  itinerarySteps: Array<{ time: string | null; label: string }>;
+  /** Whether the selected date/time differs from the original booking. */
+  dateChanged: boolean;
+  /** Whether the selected tickets/product option differs from the original booking. */
+  ticketsChanged: boolean;
+  /** When false, UI can hide the “new booking” column (selection matches original). */
+  hasChangesFromInitial: boolean;
+  /** New selection grand total for parent dialog; null until server quote supplies authoritative pricing. */
+  selectionTotal: number | null;
+  selectionCurrency: Currency;
+}
+
+/**
+ * Props shared by {@link NewBookingFlow} and {@link ChangeBookingFlow}
+ * (product, embed shell, attribution — not change-specific callbacks or receipt).
+ */
+export interface BookingFlowBaseProps {
+  product: Product;
+  /** Product slug (e.g. from URL) - used to look up collage images and video */
+  productId?: string;
+  onBack: () => void;
+  currency: Currency;
+  /** Scroll container ref (e.g. from BookingDialog) - scroll happens inside this element, not window */
+  contentRef?: RefObject<HTMLDivElement | null>;
+  /**
+   * Optional callback called when reservation is successfully created (before checkout redirect)
+   * If provided, indicates we're in an embedded context (e.g., provider dashboard)
+   */
+  onSuccess?: (data: { reservationReference: string; bookingReference?: string }) => void;
+  /** When true, shows tour description only (no calendar/checkout). Used for time-gated launch. */
+  isPartialLaunch?: boolean;
+  /**
+   * When true, treat the window as the scroll container (full-page layout),
+   * instead of relying on an internal scrollable div. Used on partner booking pages.
+   */
+  useWindowScroll?: boolean;
+  /** Optional promo code to auto-apply when the flow loads (e.g., partner pages). */
+  autoAppliedPromoCode?: string;
+  /** Optional extra discount percent to show on calendar date badges. */
+  calendarDiscountPercent?: number;
+  /** Optional pickup location IDs to prioritize/highlight in selector (e.g. partner-preferred). */
+  highlightedPickupLocationIds?: string[];
+  onPricePreviewChange?: (preview: {
+    subtotal: number;
+    tax: number;
+    total: number;
+    currency: Currency;
+  } | null) => void;
+  initialValues?: {
+    bookingReference?: string | null;
+    dateTime?: string | null;
+    /** Inventory slot id from booking (when API persists it); strongest match for change flow. */
+    availabilityId?: string | null;
+    /** Parent product id when option id is omitted or differs from availability rows (GYG/ticketbooth shape). */
+    productId?: string | null;
+    productOptionId?: string | null;
+    pickupLocationId?: string | null;
+    /** Original booked return slot (round-trip), when API provides it. */
+    returnAvailabilityId?: string | null;
+    /** Fallback when only return datetime is on the booking payload. */
+    returnDateTime?: string | null;
+    /** Persisted return floor per person from booking API (must match ticketbooth `return_unit_floor_per_person`). */
+    returnUnitFloorPerPerson?: number | null;
+    bookingItems?: Array<{ category: string; count: number }> | null;
+    addOnSelections?: Array<{ addOnId: string; variantId?: string; quantity?: number }> | null;
+    customer?: {
+      firstName?: string | null;
+      lastName?: string | null;
+      email?: string | null;
+    } | null;
+    promoCode?: string | null;
+    /** Booked policy id (change flow); must match server quote which uses booking.cancellationPolicyId. */
+    cancellationPolicyId?: string | null;
+    /**
+     * Change flow: currency the booking was sold in. The change UI and pricing must not switch to another currency
+     * (parent `currency` prop is ignored when this or `originalReceipt.currency` is set).
+     */
+    currency?: Currency | null;
+  };
+  /**
+   * When true, suppress the built-in itinerary box/placeholder.
+   * Useful when a parent dialog already renders its own itinerary summary UI.
+   */
+  hideItineraryBox?: boolean;
+  /** Partner / embed-only tweaks; omit for default website behavior. */
+  flowUi?: BookingFlowUiOptions;
+  /** Explicit reserve/checkout source metadata (browser URL layer + optional portal merge at call site). */
+  bookingSourceAttribution: Partial<BookingSourceMetadata>;
+  /** Dedicated partner portal app (`booking.*`): persist reserve `source` as PARTNER_PORTAL. */
+  partnerPortalBooking?: boolean;
+  /** When set (e.g. partner portal), get-availabilities requests this pricing profile from the API. */
+  availabilityPricingProfileId?: string | null;
+  /** When set (e.g. partner portal), get-availabilities filters cancellation policies by this profile. */
+  availabilityCancellationPolicyProfileId?: string | null;
+}
+
+/** Standard (new) reservation flow — no change-booking receipt or callbacks. */
+export interface NewBookingFlowProps extends BookingFlowBaseProps {}
+
+/** Change booking — adds receipt snapshot, compare preview, and dashboard selection preview hooks. */
+export interface ChangeBookingFlowProps extends BookingFlowBaseProps {
+  /** Called when date/tickets/itinerary selection updates (for side-by-side compare in dialog). */
+  onChangeFlowSelectionPreview?: (preview: ChangeFlowSelectionPreview | null) => void;
+  originalReceipt?: {
+    subtotal: number;
+    tax: number;
+    total: number;
+    currency: Currency;
+    promoAmount?: number;
+    promoLabel?: string | null;
+    lineItems?: Array<{
+      type?: string;
+      label?: string;
+      amount?: number;
+      quantity?: number;
+    }>;
+  } | null;
+  /**
+   * When true, {@link BookingFlow} renders {@link AdminChangeBookingFlow} (placeholder split from customer flow).
+   */
+  useAdminChangeBookingFlow?: boolean;
+}
+
+/**
+ * Router props for {@link BookingFlow}: discriminated union so `mode: 'change'` implies
+ * {@link ChangeBookingFlowProps}; otherwise {@link NewBookingFlowProps}.
+ */
+export type BookingFlowProps =
+  | (NewBookingFlowProps & { mode?: 'standard' })
+  | (ChangeBookingFlowProps & { mode: 'change' });

package/src/index.ts

@@ -13,7 +13,16 @@ export {
 
 /** Canonical Via Via booking UI — same modules as `@/components/booking/*` on the site. */
 export { BookingFlow } from './components/booking/BookingFlow';
-export type { ChangeFlowSelectionPreview } from './components/booking/BookingFlow';
+export { NewBookingFlow } from './components/booking/NewBookingFlow';
+export { ChangeBookingFlow } from './components/booking/ChangeBookingFlow';
+export { AdminChangeBookingFlow } from './components/booking/AdminChangeBookingFlow';
+export type {
+  BookingFlowBaseProps,
+  BookingFlowProps,
+  ChangeBookingFlowProps,
+  ChangeFlowSelectionPreview,
+  NewBookingFlowProps,
+} from './components/booking/booking-flow-types';
 export { PrivateShuttleBookingFlow } from './components/booking/PrivateShuttleBookingFlow';
 export type { BookingFlowUiOptions } from './components/booking/booking-flow-ui';
 export type {

package/src/lib/booking/change-booking-pricing-drift.ts

@@ -0,0 +1,331 @@
+import type { PriceSummaryLine } from '../../components/booking/PriceSummary';
+import type {
+  ChangeBookingQuotePricingDriftDetail,
+  ChangeBookingQuotePricingDriftLine,
+  ChangeBookingQuoteResponse,
+  ChangeBookingQuoteTicketLineTrace,
+  ChangeBookingQuoteTicketPricingTrace,
+} from '../booking-api';
+import { roundMoney } from './change-flow-pricing';
+
+export interface ChangeBookingPricingDriftRow {
+  key: string;
+  label: string;
+  /** Amount from the in-app cart / client proposal (major units). */
+  clientAmount: number | null;
+  /** Amount from the server price check (major units). */
+  serverAmount: number | null;
+  /** client − server when both present. */
+  delta: number | null;
+  /** Ticket qty when row resolved to a ticket category (for unit math in UI). */
+  clientQty?: number | null;
+  serverQty?: number | null;
+}
+
+function normalizeDriftLabelKey(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/\([^)]*\)/g, '')
+    .replace(/[^a-z0-9]+/g, '')
+    .trim();
+}
+
+function driftKey(line: PriceSummaryLine): string {
+  if (line.kind === 'ticket') {
+    return `ticket:${String(line.category || '').trim().toUpperCase()}`;
+  }
+  const type = (line.type ?? 'LINE').toUpperCase();
+  const lab = normalizeDriftLabelKey(line.label);
+  return `line:${type}:${lab}`;
+}
+
+const TICKET_CATEGORY_WORDS = new Set(['ADULT', 'CHILD', 'INFANT', 'SENIOR', 'STUDENT']);
+
+/**
+ * Aligns receipt-style server rows (e.g. label “ADULT” as a generic line) with {@link PriceSummaryLine} ticket rows
+ * (`ticket:ADULT`) so drift merge fills both “In app” and “Server” columns.
+ */
+export function canonicalDriftKey(line: PriceSummaryLine): string {
+  if (line.kind === 'ticket') {
+    return `ticket:${String(line.category || '').trim().toUpperCase()}`;
+  }
+  const type = (line.type ?? 'LINE').toUpperCase();
+  const labRaw = line.label.trim();
+
+  const lettersOnly = labRaw.toUpperCase().replace(/[^A-Z]/g, '');
+  if (lettersOnly.length >= 3 && TICKET_CATEGORY_WORDS.has(lettersOnly) && labRaw.length <= 32) {
+    return `ticket:${lettersOnly}`;
+  }
+
+  const multi = labRaw.match(/^(\d+)\s*[×x]\s*(.+)$/i);
+  if (multi) {
+    const cat = multi[2]
+      .trim()
+      .toUpperCase()
+      .replace(/[^A-Z]/g, '');
+    if (TICKET_CATEGORY_WORDS.has(cat)) {
+      return `ticket:${cat}`;
+    }
+  }
+
+  const lab = normalizeDriftLabelKey(line.label);
+  return `line:${type}:${lab}`;
+}
+
+function driftLabel(line: PriceSummaryLine): string {
+  if (line.kind === 'ticket') {
+    return `${line.category} × ${line.qty}`;
+  }
+  return line.label.trim() || line.type || 'Line';
+}
+
+function driftAmount(line: PriceSummaryLine): number {
+  return line.kind === 'ticket' ? line.itemTotal : line.amount;
+}
+
+/** Sum line amounts (major units) for debug totals when API sends receipt-style rows only. */
+export function sumPriceSummaryLinesMajorUnits(lines: PriceSummaryLine[]): number {
+  let s = 0;
+  for (const line of lines) {
+    s += driftAmount(line);
+  }
+  return roundMoney(s);
+}
+
+function num(v: unknown): number | undefined {
+  if (v == null || v === '') return undefined;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * Normalize `pricingDriftDetail` from `POST …/change/quote`, including snake_case keys used by temporary BE payloads.
+ */
+export function normalizePricingDriftDetailFromQuote(
+  quote: ChangeBookingQuoteResponse,
+): ChangeBookingQuotePricingDriftDetail | undefined {
+  const q = quote as unknown as Record<string, unknown>;
+  const nested =
+    (quote.pricingDriftDetail as Record<string, unknown> | undefined) ??
+    (q.pricing_drift_detail as Record<string, unknown> | undefined);
+  if (!nested || typeof nested !== 'object') return undefined;
+
+  const n = nested as Record<string, unknown>;
+  const rawLines = (a: unknown): ChangeBookingQuotePricingDriftDetail['serverLineItems'] => {
+    if (!Array.isArray(a)) return undefined;
+    return a as ChangeBookingQuotePricingDriftDetail['serverLineItems'];
+  };
+
+  const comp = n.lineComparisons ?? n.line_comparisons;
+  const lineComparisons =
+    Array.isArray(comp) && comp.length > 0
+      ? (comp as unknown[]).map((x) => {
+          if (!x || typeof x !== 'object') return { label: '' };
+          const o = x as Record<string, unknown>;
+          return {
+            label: String(o.label ?? ''),
+            clientAmountMajorUnits: num(o.clientAmountMajorUnits ?? o.client_amount_major_units) ?? null,
+            serverAmountMajorUnits: num(o.serverAmountMajorUnits ?? o.server_amount_major_units) ?? null,
+          };
+        })
+      : undefined;
+
+  const out: ChangeBookingQuotePricingDriftDetail = {
+    clientTotalMajorUnits: num(n.clientTotalMajorUnits ?? n.client_total_major_units),
+    serverTotalMajorUnits: num(n.serverTotalMajorUnits ?? n.server_total_major_units),
+    deltaMajorUnits: num(n.deltaMajorUnits ?? n.delta_major_units),
+    lineComparisons,
+    serverLineItems: rawLines(n.serverLineItems ?? n.server_line_items),
+    clientLineItems: rawLines(n.clientLineItems ?? n.client_line_items),
+  };
+
+  if (
+    out.clientTotalMajorUnits == null &&
+    out.serverTotalMajorUnits == null &&
+    out.deltaMajorUnits == null &&
+    !out.lineComparisons?.length &&
+    !out.serverLineItems?.length &&
+    !out.clientLineItems?.length
+  ) {
+    return undefined;
+  }
+  return out;
+}
+
+/**
+ * Reads optional `ticketPricingTrace` from change-quote JSON (camelCase or snake_case).
+ */
+export function normalizeTicketPricingTraceFromQuote(
+  quote: ChangeBookingQuoteResponse,
+): ChangeBookingQuoteTicketPricingTrace | undefined {
+  const q = quote as unknown as Record<string, unknown>;
+  const raw = q.ticketPricingTrace ?? q.ticket_pricing_trace;
+  if (!raw || typeof raw !== 'object') return undefined;
+  const t = raw as Record<string, unknown>;
+  const lockedRaw = t.lockedTicketUnitPriceByCategory ?? t.locked_ticket_unit_price_by_category;
+  const locked: Record<string, number> = {};
+  if (lockedRaw && typeof lockedRaw === 'object' && !Array.isArray(lockedRaw)) {
+    for (const [k, v] of Object.entries(lockedRaw as Record<string, unknown>)) {
+      const n = num(v);
+      if (n != null) locked[k] = n;
+    }
+  }
+  const linesRaw = t.ticketLines ?? t.ticket_lines;
+  const ticketLines: ChangeBookingQuoteTicketLineTrace[] = [];
+  if (Array.isArray(linesRaw)) {
+    for (const row of linesRaw) {
+      if (!row || typeof row !== 'object') continue;
+      const o = row as Record<string, unknown>;
+      const cat = String(o.category ?? '');
+      const rule = String(o.rule ?? '');
+      const lu = num(o.liveUnitMajorUnits ?? o.live_unit_major_units);
+      const lk = num(o.lockedUnitMajorUnits ?? o.locked_unit_major_units);
+      const pq = Number(o.protectedQty ?? o.protected_qty ?? 0);
+      const iq = Number(o.incrementalQty ?? o.incremental_qty ?? 0);
+      const catTot = num(o.catalogLineTotalMajorUnits ?? o.catalog_line_total_major_units);
+      const amt = num(o.ticketLineAmountMajorUnits ?? o.ticket_line_amount_major_units);
+      if (!cat || lu == null || catTot == null || amt == null) continue;
+      ticketLines.push({
+        category: cat,
+        rule,
+        liveUnitMajorUnits: lu,
+        lockedUnitMajorUnits: lk ?? undefined,
+        protectedQty: Number.isFinite(pq) ? pq : 0,
+        incrementalQty: Number.isFinite(iq) ? iq : 0,
+        catalogLineTotalMajorUnits: catTot,
+        ticketLineAmountMajorUnits: amt,
+      });
+    }
+  }
+  const bp = String(t.bookingParentProductId ?? t.booking_parent_product_id ?? '');
+  const rp = String(t.requestedParentProductId ?? t.requested_parent_product_id ?? '');
+  const bo = String(t.bookingOptionId ?? t.booking_option_id ?? '');
+  const ro = String(t.requestedOptionId ?? t.requested_option_id ?? '');
+  if (!bp || !rp || !bo || !ro) return undefined;
+  return {
+    bookingParentProductId: bp,
+    requestedParentProductId: rp,
+    bookingOptionId: bo,
+    requestedOptionId: ro,
+    sameParentProduct: Boolean(t.sameParentProduct ?? t.same_parent_product),
+    unchangedItinerary: Boolean(t.unchangedItinerary ?? t.unchanged_itinerary),
+    lockedTicketUnitPriceByCategory: Object.keys(locked).length > 0 ? locked : undefined,
+    ticketLines,
+  };
+}
+
+/**
+ * Merge client-built {@link PriceSummaryLine} rows with server receipt lines for a side-by-side drift table.
+ */
+export function mergePriceSummaryLinesForDrift(
+  clientLines: PriceSummaryLine[],
+  serverLines: PriceSummaryLine[],
+): ChangeBookingPricingDriftRow[] {
+  const mapClient = new Map<string, { label: string; amount: number; qty?: number }>();
+  const mapServer = new Map<string, { label: string; amount: number; qty?: number }>();
+
+  for (const line of clientLines) {
+    const k = canonicalDriftKey(line);
+    const qty = line.kind === 'ticket' ? line.qty : undefined;
+    mapClient.set(k, { label: driftLabel(line), amount: driftAmount(line), qty });
+  }
+  for (const line of serverLines) {
+    const k = canonicalDriftKey(line);
+    const qty = line.kind === 'ticket' ? line.qty : undefined;
+    mapServer.set(k, { label: driftLabel(line), amount: driftAmount(line), qty });
+  }
+
+  const keys = [...new Set([...mapClient.keys(), ...mapServer.keys()])];
+  keys.sort((a, b) => a.localeCompare(b));
+
+  const rows: ChangeBookingPricingDriftRow[] = [];
+  for (const key of keys) {
+    const c = mapClient.get(key);
+    const s = mapServer.get(key);
+    const clientAmount = c?.amount ?? null;
+    const serverAmount = s?.amount ?? null;
+    const label = c?.label ?? s?.label ?? key;
+    let delta: number | null = null;
+    if (clientAmount != null && serverAmount != null) {
+      delta = roundMoney(clientAmount - serverAmount);
+    }
+    const clientQty = c?.qty ?? null;
+    const serverQty = s?.qty ?? null;
+    rows.push({
+      key,
+      label,
+      clientAmount,
+      serverAmount,
+      delta,
+      clientQty: clientQty ?? undefined,
+      serverQty: serverQty ?? undefined,
+    });
+  }
+  return rows;
+}
+
+function findMergedRowForApiLabel(
+  mergedRows: ChangeBookingPricingDriftRow[],
+  apiLabel: string,
+): ChangeBookingPricingDriftRow | undefined {
+  const trimmed = apiLabel.trim();
+  if (!trimmed) return undefined;
+  const upper = trimmed.toUpperCase();
+  const norm = normalizeDriftLabelKey(trimmed);
+
+  let hit = mergedRows.find((r) => r.label === trimmed);
+  if (hit) return hit;
+
+  hit = mergedRows.find((r) => normalizeDriftLabelKey(r.label) === norm);
+  if (hit) return hit;
+
+  /** Return rows: BE label is often English "Return option (N people)" while the app may use i18n. */
+  if (/\breturn\b/i.test(trimmed) || norm.includes('return')) {
+    hit = mergedRows.find(
+      (r) =>
+        r.key.startsWith('line:RETURN') ||
+        r.key.toLowerCase().includes(':return') ||
+        /\breturn\b/i.test(r.label),
+    );
+    if (hit) return hit;
+  }
+
+  for (const cat of TICKET_CATEGORY_WORDS) {
+    if (upper === cat || upper.startsWith(`${cat} `) || new RegExp(`\\b${cat}\\b`, 'i').test(trimmed)) {
+      hit = mergedRows.find((r) => r.key === `ticket:${cat}`);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * API `lineComparisons` often omit client line amounts; fill from {@link mergePriceSummaryLinesForDrift} so “In app” is not blank.
+ */
+export function enrichLineComparisonsWithMergedRows(
+  apiLines: ChangeBookingQuotePricingDriftLine[],
+  mergedRows: ChangeBookingPricingDriftRow[],
+): ChangeBookingPricingDriftRow[] {
+  return apiLines.map((line, i) => {
+    const base = findMergedRowForApiLabel(mergedRows, line.label);
+    const clientAmount =
+      line.clientAmountMajorUnits != null && Number.isFinite(Number(line.clientAmountMajorUnits))
+        ? Number(line.clientAmountMajorUnits)
+        : base?.clientAmount ?? null;
+    const serverAmount =
+      line.serverAmountMajorUnits != null && Number.isFinite(Number(line.serverAmountMajorUnits))
+        ? Number(line.serverAmountMajorUnits)
+        : base?.serverAmount ?? null;
+    const delta =
+      clientAmount != null && serverAmount != null ? roundMoney(clientAmount - serverAmount) : null;
+    return {
+      key: `api-line:${i}`,
+      label: line.label,
+      clientAmount,
+      serverAmount,
+      delta,
+      clientQty: base?.clientQty ?? undefined,
+      serverQty: base?.serverQty ?? undefined,
+    };
+  });
+}