@ticketboothapp/booking 1.2.167 → 1.2.169

package/src/components/booking/useAdminChangeCheckoutController.ts

@@ -12,6 +12,7 @@ import {
   type AddOn,
   type AdminAmendmentOperationSnapshot,
   type AdminAmendmentRefundDisposition,
+  type AdminAmendmentActiveAdjustmentSnapshot,
   type AdminFeAuthoritativeReceipt,
   type AdminPromoApplicationScope,
   type Availability,
@@ -42,6 +43,7 @@ import {
 import type { ChangeBookingFlowProps } from './booking-flow-types';
 import type { CheckoutModalLineItem } from './CheckoutModal';
 import type { Currency } from './CurrencySwitcher';
+import type { AdminAdjustmentComponentOption } from './admin-adjustment-components';
 import {
   findMergedAvailabilityForSelection,
   findMergedReturnVacancies,
@@ -91,6 +93,10 @@ export interface AdminChangeLatestQuote {
   quoteExpiresAt?: string;
   pricingVersion?: string;
   quotedTotal?: number;
+  amountPreviouslyPaid?: number;
+  currentPaymentCreditTotal?: number;
+  projectedPaymentCreditTotal?: number;
+  refundCandidate?: number;
   paymentCreditTotal?: number;
   refundDecisionOperations?: AdminAmendmentOperationSnapshot[];
   returnPriceTreatmentOperations?: AdminAmendmentOperationSnapshot[];
@@ -100,8 +106,11 @@ export interface AdminChangeLatestQuote {
   quotePreviousTotalCents?: number;
   quoteNewTotalCents?: number;
   serverPreview: ChangeBookingServerPreview;
+  authoritativeItineraryDisplay?: ItineraryDisplayStep[] | null;
   pricingDriftDetail?: ChangeBookingQuotePricingDriftDetail;
   ticketPricingTrace?: ChangeBookingQuoteTicketPricingTrace | null;
+  selectableAdjustmentComponents?: AdminAdjustmentComponentOption[];
+  reversibleAdjustments?: AdminAmendmentActiveAdjustmentSnapshot[];
 }
 
 export interface UseAdminChangeCheckoutControllerParams {
@@ -146,6 +155,7 @@ export interface UseAdminChangeCheckoutControllerParams {
   providerPricingOverrides: AdminChangeProviderLineOverride[];
   mergedProviderAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
+  adminReverseAdjustmentIds: string[];
   refundDispositionsByOperationId: NonNullable<
     ProviderDashboardChangeBookingPayload['refundDispositionsByOperationId']
   >;
@@ -248,6 +258,7 @@ export function useAdminChangeCheckoutController({
   providerPricingOverrides,
   mergedProviderAdditionalAdjustments,
   adminStructuredAdjustments,
+  adminReverseAdjustmentIds,
   refundDispositionsByOperationId,
   providerApplyAuthoritativeReceipt,
   onSuccess,
@@ -370,6 +381,7 @@ export function useAdminChangeCheckoutController({
       providerPricingOverrides,
       mergedProviderAdditionalAdjustments,
       adminStructuredAdjustments,
+      adminReverseAdjustmentIds,
       refundDispositionsByOperationId,
       pricingV2QuoteId: authoritativeQuote?.quoteId ?? null,
       pricingV2QuotedTotal: authoritativeQuote?.quotedTotal ?? authoritativeQuote?.serverDisplay?.total ?? null,
@@ -487,6 +499,10 @@ export function useAdminChangeCheckoutController({
             promoCode: appliedPromoCode,
             promoApplicationScope,
             structuredAdjustments: adminStructuredAdjustments,
+            reverseAdjustmentIds: adminReverseAdjustmentIds,
+            includeSelectableAdjustmentComponents: adminStructuredAdjustments.some(
+              (adjustment) => adjustment.scope === 'SELECTED_COMPONENTS',
+            ),
             refundDispositionsByOperationId,
             previousPassengerCount: changeFlowInitialTicketCount,
             previousAvailabilityId: initialValues?.availabilityId ?? null,

package/src/components/booking/useAdminChangeProductReset.ts

@@ -8,6 +8,7 @@ interface ResetRef {
 
 export interface UseAdminChangeProductResetParams {
   selectedChangeProductId: string;
+  setQuantities: Dispatch<SetStateAction<Record<string, number>>>;
   setSelectedAvailability: Dispatch<SetStateAction<Availability | null>>;
   setSelectedReturnOption: Dispatch<SetStateAction<ReturnOption | null>>;
   setAddOns: Dispatch<SetStateAction<AddOn[]>>;
@@ -21,6 +22,7 @@ export interface UseAdminChangeProductResetParams {
 
 export function useAdminChangeProductReset({
   selectedChangeProductId,
+  setQuantities,
   setSelectedAvailability,
   setSelectedReturnOption,
   setAddOns,
@@ -36,6 +38,9 @@ export function useAdminChangeProductReset({
   useEffect(() => {
     if (previousSelectedChangeProductIdRef.current === selectedChangeProductId) return;
     previousSelectedChangeProductIdRef.current = selectedChangeProductId;
+    // Ticket categories belong to the selected product family. In particular, a private
+    // RESOURCE quantity must not survive a switch to a regular ADULT/CHILD/INFANT product.
+    setQuantities({});
     setSelectedAvailability(null);
     setSelectedReturnOption(null);
     setAddOns([]);
@@ -47,6 +52,7 @@ export function useAdminChangeProductReset({
     setError('');
   }, [
     selectedChangeProductId,
+    setQuantities,
     setSelectedAvailability,
     setSelectedReturnOption,
     setAddOns,

package/src/components/booking/useAdminChangeProtectedPricing.ts

@@ -20,6 +20,7 @@ type AdminCustomReceiptLine = {
   amountInput: string;
   amountSign?: number;
   calculation: 'FIXED_AMOUNT' | 'PERCENTAGE';
+  sourceAdjustmentId?: string;
 };
 
 function addOnSelectionTotal(selections: AddOnSelection[] | null | undefined, addOns: AddOn[]): number {
@@ -220,6 +221,9 @@ export function useAdminChangeProtectedPricing({
     () =>
       roundMoney(
         adminCustomReceiptLines.reduce((sum, line) => {
+          // Existing ledger adjustments are already included in the persisted receipt. Their
+          // edit delta is server-priced as reverse + replace and must not be added again here.
+          if (line.sourceAdjustmentId) return sum;
           if (line.calculation !== 'FIXED_AMOUNT') return sum;
           const raw = line.amountInput.trim();
           if (raw === '' || raw === '+' || raw === '-') return sum;

package/src/components/booking/useAdminChangeQuoteDisplayState.tsx

@@ -55,7 +55,7 @@ export interface UseAdminChangeQuoteDisplayStateParams {
   pickupLocationId: string | null;
   quantities: Record<string, number>;
   addOnSelections: AddOnSelection[];
-  initialAddOnMinQtyByKey: Map<string, number>;
+  initialAddOnQtyByKey: Map<string, number>;
   changeFlowResolvedInitialProductOptionId: string | null;
   selectedParentProductChanged: boolean;
   isProviderDashboardChange: boolean;
@@ -65,6 +65,7 @@ export interface UseAdminChangeQuoteDisplayStateParams {
   editableSummaryPreSubtotalDelta: number;
   adminCustomAdjustmentTotal: number;
   adminCustomReceiptLines: AdminCustomReceiptLine[];
+  adminReverseAdjustmentIds: string[];
   isManualOverrideEligibleLine: (line: ProviderDashboardPricingLine) => boolean;
   isAdmin: boolean;
   useAdminFeAuthoritativeQuote: boolean;
@@ -99,7 +100,7 @@ export function useAdminChangeQuoteDisplayState({
   pickupLocationId,
   quantities,
   addOnSelections,
-  initialAddOnMinQtyByKey,
+  initialAddOnQtyByKey,
   changeFlowResolvedInitialProductOptionId,
   selectedParentProductChanged,
   isProviderDashboardChange,
@@ -109,6 +110,7 @@ export function useAdminChangeQuoteDisplayState({
   editableSummaryPreSubtotalDelta,
   adminCustomAdjustmentTotal,
   adminCustomReceiptLines,
+  adminReverseAdjustmentIds,
   isManualOverrideEligibleLine,
   isAdmin,
   useAdminFeAuthoritativeQuote,
@@ -321,7 +323,7 @@ export function useAdminChangeQuoteDisplayState({
     pickupLocationId,
     quantities,
     addOnSelections,
-    initialAddOnMinQtyByKey,
+    initialAddOnQtyByKey,
     changeFlowResolvedInitialProductOptionId,
     productChanged: selectedParentProductChanged,
   });
@@ -344,8 +346,8 @@ export function useAdminChangeQuoteDisplayState({
     providerQuotedLines,
     hasChangeSelection,
     editableSummaryPreSubtotalDelta,
-    adminCustomAdjustmentTotal,
     adminCustomReceiptLines,
+    adminReverseAdjustmentIds,
     isManualOverrideEligibleLine,
   });
 

package/src/components/booking/useAdminChangeQuotePreview.ts

@@ -29,12 +29,14 @@ import type { Currency } from './CurrencySwitcher';
 import type { AdminChangeLatestQuote } from './useAdminChangeCheckoutController';
 import {
   buildAdminChangeQuoteRequestKey,
+  canRequestAdminChangeQuote,
   canReuseCompletedAdminChangeQuote,
 } from './admin-change-quote-request-key';
 import {
   buildAdminChangeV2QuoteRequest,
   quoteAdminChangeV2ForUi,
 } from './admin-change-v2-quote-request';
+import { friendlyChangeBookingError } from './change-booking-error-message';
 import type { ProviderDashboardChangeBookingPayload } from './provider-dashboard-change-booking';
 
 type AddOnSelection = { addOnId: string; variantId?: string; quantity?: number };
@@ -43,7 +45,12 @@ type AdminCustomReceiptLine = {
   amountInput: string;
   amountSign?: number;
   calculation: 'FIXED_AMOUNT' | 'PERCENTAGE';
-  scope: 'POSITIVE_AMENDMENT_VALUE' | 'CURRENT_ACTIVE_TICKETS' | 'CURRENT_ACTIVE_BOOKING';
+  scope:
+    | 'POSITIVE_AMENDMENT_VALUE'
+    | 'CURRENT_ACTIVE_TICKETS'
+    | 'CURRENT_ACTIVE_BOOKING'
+    | 'SELECTED_COMPONENTS';
+  selectedComponentIds: string[];
   taxBehavior: 'NON_TAXABLE' | 'TAXABLE' | 'PRE_TAX_DISCOUNT' | 'POST_TAX_DISCOUNT';
   reasonCode: string;
 };
@@ -71,6 +78,8 @@ export interface UseAdminChangeQuotePreviewParams {
   promoApplicationScope: AdminPromoApplicationScope;
   adminCustomReceiptLines: AdminCustomReceiptLine[];
   adminStructuredAdjustments: NonNullable<ProviderDashboardChangeBookingPayload['structuredAdjustments']>;
+  adminReverseAdjustmentIds: string[];
+  needsAdjustmentDiscovery: boolean;
   refundDispositionsByOperationId: Record<string, AdminAmendmentRefundDisposition>;
   useAdminFeAuthoritativeQuote: boolean;
   latestChangeQuote: AdminChangeLatestQuote | null;
@@ -132,6 +141,8 @@ export function useAdminChangeQuotePreview({
   promoApplicationScope,
   adminCustomReceiptLines,
   adminStructuredAdjustments,
+  adminReverseAdjustmentIds,
+  needsAdjustmentDiscovery,
   refundDispositionsByOperationId,
   useAdminFeAuthoritativeQuote,
   latestChangeQuote,
@@ -167,10 +178,9 @@ export function useAdminChangeQuotePreview({
   onPricePreviewChange,
 }: UseAdminChangeQuotePreviewParams): UseAdminChangeQuotePreviewResult {
   const lastChangeFlowPreviewKeyRef = useRef<string | null>(null);
-
   const changeFlowNeedsServerPrice =
     isCustomerSelfServeChange &&
-    hasChangeSelection &&
+    hasEffectiveChangeSelection &&
     !!initialValues?.bookingReference?.trim() &&
     !!lastName.trim();
 
@@ -179,13 +189,44 @@ export function useAdminChangeQuotePreview({
     (latestChangeQuote.refundDecisionOperations?.length ?? 0) === 0;
   const refundDecisionRequired = (latestChangeQuote?.refundDecisionOperations?.length ?? 0) > 0;
   const hasPublishedChangeQuote = latestChangeQuote !== null;
+  /**
+   * Existing admin adjustments must be discoverable before the operator makes a change.
+   * Initial selection hydration can briefly leave the live availability/return unset, so use
+   * the persisted booking identities for this read-only discovery quote instead of waiting for
+   * the editable target controls to become complete.
+   */
+  const quoteAvailability = useMemo<Availability | null>(() => {
+    if (selectedAvailability) return selectedAvailability;
+    if (!needsAdjustmentDiscovery || !initialValues?.dateTime?.trim()) return null;
+    const optionId = initialValues.productOptionId?.trim() || initialValues.productId?.trim();
+    if (!optionId) return null;
+    return {
+      dateTime: initialValues.dateTime.trim(),
+      availabilityId: initialValues.availabilityId?.trim() || undefined,
+      productOptionId: optionId,
+      vacancies: Math.max(totalQuantity, 1),
+      currency,
+    };
+  }, [
+    selectedAvailability,
+    needsAdjustmentDiscovery,
+    initialValues?.dateTime,
+    initialValues?.availabilityId,
+    initialValues?.productOptionId,
+    initialValues?.productId,
+    totalQuantity,
+    currency,
+  ]);
+  const quoteReturnAvailabilityId =
+    selectedReturnOption?.returnAvailabilityId ??
+    (needsAdjustmentDiscovery ? initialValues?.returnAvailabilityId?.trim() || null : null);
   const changeQuoteInputsKey = useMemo(() => buildAdminChangeQuoteRequestKey({
     bookingReference: initialValues?.bookingReference,
     lastName,
     productId: product.productId,
-    selectedAvailability,
+    selectedAvailability: quoteAvailability,
     pickupLocationId,
-    returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+    returnAvailabilityId: quoteReturnAvailabilityId,
     quantities,
     addOnSelections,
     adminCustomReceiptLines,
@@ -193,15 +234,16 @@ export function useAdminChangeQuotePreview({
     promoCode: appliedPromoCode,
     promoApplicationScope,
     structuredAdjustments: adminStructuredAdjustments,
+    reverseAdjustmentIds: adminReverseAdjustmentIds,
     refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   }), [
     initialValues?.bookingReference,
     lastName,
     product.productId,
-    selectedAvailability,
+    quoteAvailability,
     pickupLocationId,
-    selectedReturnOption?.returnAvailabilityId,
+    quoteReturnAvailabilityId,
     quantities,
     addOnSelections,
     adminCustomReceiptLines,
@@ -209,11 +251,22 @@ export function useAdminChangeQuotePreview({
     appliedPromoCode,
     promoApplicationScope,
     adminStructuredAdjustments,
+    adminReverseAdjustmentIds,
     refundDispositionsByOperationId,
     useAdminFeAuthoritativeQuote,
   ]);
   const destinationRequiresReturnSelection = Boolean(selectedAvailability?.returnOptions?.length);
   const missingRequiredReturnSelection = destinationRequiresReturnSelection && !selectedReturnOption;
+  const quoteMissingRequiredReturnSelection =
+    missingRequiredReturnSelection && !needsAdjustmentDiscovery;
+  const canRequestChangeQuote = canRequestAdminChangeQuote({
+    isCustomerSelfServeChange,
+    hasEffectiveChangeSelection: hasEffectiveChangeSelection || needsAdjustmentDiscovery,
+    hasSelectedAvailability: quoteAvailability != null,
+    bookingReference: initialValues?.bookingReference,
+    lastName,
+    missingRequiredReturnSelection: quoteMissingRequiredReturnSelection,
+  });
 
   const changeFlowSubmitDisabled =
     missingRequiredReturnSelection ||
@@ -279,20 +332,23 @@ export function useAdminChangeQuotePreview({
         : 'Change booking (no charge)';
   })();
 
-  const checkoutFormError =
+  const rawCheckoutFormError =
     (error || '') ||
     (missingRequiredReturnSelection ? 'Please select a return time for this product.' : '') ||
     (isChangeQuoteBlocked && !refundDecisionRequired
       ? (latestChangeQuote?.reasonIfBlocked ?? 'This change cannot be priced right now.')
       : '') ||
     (changeQuoteFetchError ?? '');
+  const checkoutFormError = friendlyChangeBookingError(rawCheckoutFormError);
 
   const changeFlowSelectionPreview = useMemo((): ChangeFlowSelectionPreview | null => {
     if (!selectedAvailability || totalQuantity <= 0) return null;
     const ticketsLine = formatTicketLineItemsForSummary(
       ticketLineItems.map((l) => ({ category: l.category, qty: l.qty }))
     );
-    const itinerary = computeItineraryDisplay();
+    const itinerary =
+      latestChangeQuote?.authoritativeItineraryDisplay ??
+      computeItineraryDisplay();
     const itinerarySteps =
       itinerary?.map((s) => ({
         time: s.time?.trim() || null,
@@ -336,6 +392,7 @@ export function useAdminChangeQuotePreview({
     latestChangeQuote?.quotedTotal,
     latestChangeQuote?.serverDisplay?.total,
     latestChangeQuote?.serverPreview?.totalNewBooking,
+    latestChangeQuote?.authoritativeItineraryDisplay,
   ]);
 
   useEffect(() => {
@@ -407,13 +464,7 @@ export function useAdminChangeQuotePreview({
       return;
     }
 
-    if (
-      !hasChangeSelection ||
-      !selectedAvailability ||
-      !initialValues?.bookingReference?.trim() ||
-      !lastName.trim() ||
-      missingRequiredReturnSelection
-    ) {
+    if (!canRequestChangeQuote || !quoteAvailability || !initialValues?.bookingReference?.trim()) {
       setLatestChangeQuote(null);
       setChangeQuoteLoading(false);
       setChangeQuoteFetchError(null);
@@ -435,7 +486,7 @@ export function useAdminChangeQuotePreview({
       return;
     }
 
-    const optionId = getAvailabilityOptionId(selectedAvailability);
+    const optionId = getAvailabilityOptionId(quoteAvailability);
     if (!optionId) {
       setLatestChangeQuote(null);
       setChangeQuoteLoading(false);
@@ -462,15 +513,20 @@ export function useAdminChangeQuotePreview({
             lastName,
             parentProductId: product.productId,
             optionId,
-            selectedAvailability,
+            selectedAvailability: quoteAvailability,
             pickupLocationId,
-            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+            returnAvailabilityId: quoteReturnAvailabilityId,
             bookingItems,
             addOnSelections,
             cancellationPolicyId: cancellationPolicyId ?? null,
             promoCode: appliedPromoCode,
             promoApplicationScope,
             structuredAdjustments: adminStructuredAdjustments,
+            reverseAdjustmentIds: adminReverseAdjustmentIds,
+            includeSelectableAdjustmentComponents:
+              needsAdjustmentDiscovery || adminCustomReceiptLines.some(
+                (line) => line.scope === 'SELECTED_COMPONENTS',
+              ),
             refundDispositionsByOperationId,
             previousPassengerCount: changeFlowInitialTicketCount,
             previousAvailabilityId: initialValues.availabilityId ?? null,
@@ -522,7 +578,7 @@ export function useAdminChangeQuotePreview({
     // Fetching is controlled by the canonical user-input identity. Do not add quote-derived
     // totals, receipt objects, or display lines here: a response must not trigger another quote.
     isCustomerSelfServeChange,
-    hasChangeSelection,
+    canRequestChangeQuote,
     missingRequiredReturnSelection,
     changeQuoteInputsKey,
     hasPublishedChangeQuote,

package/src/components/booking/useAdminCustomReceiptLines.ts

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { AdminAmendmentActiveAdjustmentSnapshot } from '../../lib/booking-api';
 
 export type AdminCustomReceiptLine = {
   id: string;
@@ -6,63 +7,223 @@ export type AdminCustomReceiptLine = {
   amountInput: string;
   amountSign: 1 | -1;
   calculation: 'FIXED_AMOUNT' | 'PERCENTAGE';
-  scope: 'POSITIVE_AMENDMENT_VALUE' | 'CURRENT_ACTIVE_TICKETS' | 'CURRENT_ACTIVE_BOOKING';
+  scope:
+    | 'POSITIVE_AMENDMENT_VALUE'
+    | 'CURRENT_ACTIVE_TICKETS'
+    | 'CURRENT_ACTIVE_BOOKING'
+    | 'SELECTED_COMPONENTS';
+  selectedComponentIds: string[];
   taxBehavior: 'NON_TAXABLE' | 'TAXABLE' | 'PRE_TAX_DISCOUNT' | 'POST_TAX_DISCOUNT';
   reasonCode: string;
+  /** Immutable ledger id. Existing lines are edited by reversing this id and adding a replacement. */
+  sourceAdjustmentId?: string;
+  replacementAdjustmentId?: string;
+  isDirty?: boolean;
 };
 
 type AdminCustomReceiptLinePatch = Partial<
   Pick<
     AdminCustomReceiptLine,
-    'label' | 'amountInput' | 'amountSign' | 'calculation' | 'scope' | 'taxBehavior' | 'reasonCode'
+    | 'label'
+    | 'amountInput'
+    | 'amountSign'
+    | 'calculation'
+    | 'scope'
+    | 'selectedComponentIds'
+    | 'taxBehavior'
+    | 'reasonCode'
   >
 >;
 
-export function useAdminCustomReceiptLines(resetKey: string | null | undefined) {
+export function lineFromActiveAdjustment(
+  adjustment: AdminAmendmentActiveAdjustmentSnapshot,
+  replacementAdjustmentId: string,
+): AdminCustomReceiptLine {
+  const percentage = adjustment.mode !== 'FIXED_AMOUNT';
+  return {
+    id: `existing:${adjustment.adjustmentId}`,
+    label:
+      adjustment.reason?.trim() ||
+      adjustment.referenceCode?.trim() ||
+      adjustment.reasonCode.replace(/_/g, ' ').toLowerCase(),
+    amountInput: percentage
+      ? String(Math.abs(adjustment.percentageBasisPoints ?? 0) / 100)
+      : (Math.abs(adjustment.amountCents) / 100).toFixed(2),
+    amountSign: adjustment.amountCents < 0 ? -1 : 1,
+    calculation: percentage ? 'PERCENTAGE' : 'FIXED_AMOUNT',
+    scope: adjustment.scope,
+    selectedComponentIds:
+      adjustment.scope === 'SELECTED_COMPONENTS' ? adjustment.affectedComponentIds : [],
+    taxBehavior: adjustment.taxBehavior,
+    reasonCode: adjustment.reasonCode,
+    sourceAdjustmentId: adjustment.adjustmentId,
+    replacementAdjustmentId,
+    isDirty: false,
+  };
+}
+
+export function reverseAdjustmentIdsForAdminCustomLines(
+  lines: AdminCustomReceiptLine[],
+  removedExistingAdjustmentIds: string[] = [],
+): string[] {
+  return Array.from(new Set([
+    ...removedExistingAdjustmentIds,
+    ...lines.flatMap((line) =>
+      line.sourceAdjustmentId && line.isDirty ? [line.sourceAdjustmentId] : [],
+    ),
+  ])).sort();
+}
+
+export function useAdminCustomReceiptLines(
+  resetKey: string | null | undefined,
+  reversibleAdjustments: AdminAmendmentActiveAdjustmentSnapshot[] | undefined,
+) {
   const [adminCustomReceiptLines, setAdminCustomReceiptLines] = useState<AdminCustomReceiptLine[]>([]);
+  const [appliedAdminCustomReceiptLines, setAppliedAdminCustomReceiptLines] = useState<
+    AdminCustomReceiptLine[]
+  >([]);
+  const [removedExistingAdjustmentIds, setRemovedExistingAdjustmentIds] = useState<string[]>([]);
+  const [appliedRemovedExistingAdjustmentIds, setAppliedRemovedExistingAdjustmentIds] = useState<
+    string[]
+  >([]);
+  const [hasHydratedExistingAdjustments, setHasHydratedExistingAdjustments] = useState(false);
   const adminCustomLineIdRef = useRef(0);
   const previousResetKeyRef = useRef(resetKey);
+  const hydratedResetKeyRef = useRef<string | null | undefined>(undefined);
+  const skipHydrationForResetKeyRef = useRef<string | null | undefined>(undefined);
 
-  const handleAddAdminCustomReceiptLine = useCallback(() => {
+  const nextDraftId = useCallback((prefix: 'admin-rcpt' | 'admin-edit') => {
     adminCustomLineIdRef.current += 1;
+    return `${prefix}-${Date.now().toString(36)}-${adminCustomLineIdRef.current}`;
+  }, []);
+
+  const handleAddAdminCustomReceiptLine = useCallback(() => {
+    const id = nextDraftId('admin-rcpt');
     setAdminCustomReceiptLines((prev) => [
       ...prev,
       {
-        id: `admin-rcpt-${adminCustomLineIdRef.current}`,
+        id,
         label: '',
         amountInput: '',
         amountSign: 1,
         calculation: 'FIXED_AMOUNT',
         scope: 'POSITIVE_AMENDMENT_VALUE',
-        taxBehavior: 'NON_TAXABLE',
+        selectedComponentIds: [],
+        taxBehavior: 'TAXABLE',
         reasonCode: 'STAFF_ADJUSTMENT',
       },
     ]);
-  }, []);
+    return id;
+  }, [nextDraftId]);
 
   const handleUpdateAdminCustomReceiptLine = useCallback(
     (id: string, patch: AdminCustomReceiptLinePatch) => {
       setAdminCustomReceiptLines((prev) =>
-        prev.map((line) => (line.id === id ? { ...line, ...patch } : line))
+        prev.map((line) =>
+          line.id === id
+            ? { ...line, ...patch, ...(line.sourceAdjustmentId ? { isDirty: true } : {}) }
+            : line,
+        )
       );
     },
     [],
   );
 
   const handleRemoveAdminCustomReceiptLine = useCallback((id: string) => {
+    const removed = adminCustomReceiptLines.find((line) => line.id === id);
+    if (removed?.sourceAdjustmentId) {
+      setRemovedExistingAdjustmentIds((current) =>
+        current.includes(removed.sourceAdjustmentId!)
+          ? current
+          : [...current, removed.sourceAdjustmentId!],
+      );
+    }
     setAdminCustomReceiptLines((prev) => prev.filter((line) => line.id !== id));
-  }, []);
+  }, [adminCustomReceiptLines]);
+
+  const handleApplyAdminCustomReceiptLines = useCallback(() => {
+    setAppliedAdminCustomReceiptLines(adminCustomReceiptLines);
+    setAppliedRemovedExistingAdjustmentIds(removedExistingAdjustmentIds);
+  }, [adminCustomReceiptLines, removedExistingAdjustmentIds]);
 
   useEffect(() => {
     if (previousResetKeyRef.current === resetKey) return;
     previousResetKeyRef.current = resetKey;
     setAdminCustomReceiptLines([]);
+    setAppliedAdminCustomReceiptLines([]);
+    setRemovedExistingAdjustmentIds([]);
+    setAppliedRemovedExistingAdjustmentIds([]);
+    setHasHydratedExistingAdjustments(false);
+    hydratedResetKeyRef.current = undefined;
+    skipHydrationForResetKeyRef.current =
+      reversibleAdjustments === undefined ? undefined : resetKey;
+    // `reversibleAdjustments` is intentionally sampled only when the reset key changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [resetKey]);
 
+  useEffect(() => {
+    if (reversibleAdjustments === undefined) return;
+    // A product-family reset and clearing the previous quote happen in separate effects.
+    // Never hydrate the new editor from the previous target's quote during that transition.
+    if (skipHydrationForResetKeyRef.current === resetKey) {
+      skipHydrationForResetKeyRef.current = undefined;
+      return;
+    }
+    if (hydratedResetKeyRef.current === resetKey) return;
+    hydratedResetKeyRef.current = resetKey;
+    const hydratedLines = reversibleAdjustments.map((adjustment) =>
+      lineFromActiveAdjustment(adjustment, nextDraftId('admin-edit')),
+    );
+    setAdminCustomReceiptLines(hydratedLines);
+    setAppliedAdminCustomReceiptLines(hydratedLines);
+    setRemovedExistingAdjustmentIds([]);
+    setAppliedRemovedExistingAdjustmentIds([]);
+    setHasHydratedExistingAdjustments(true);
+  }, [nextDraftId, resetKey, reversibleAdjustments]);
+
+  const adminReverseAdjustmentIds = reverseAdjustmentIdsForAdminCustomLines(
+    appliedAdminCustomReceiptLines,
+    appliedRemovedExistingAdjustmentIds,
+  );
+  const hasPendingAdminCustomReceiptLineChanges = useMemo(
+    () =>
+      JSON.stringify({
+        lines: adminCustomReceiptLines,
+        removedIds: [...removedExistingAdjustmentIds].sort(),
+      }) !==
+      JSON.stringify({
+        lines: appliedAdminCustomReceiptLines,
+        removedIds: [...appliedRemovedExistingAdjustmentIds].sort(),
+      }),
+    [
+      adminCustomReceiptLines,
+      appliedAdminCustomReceiptLines,
+      removedExistingAdjustmentIds,
+      appliedRemovedExistingAdjustmentIds,
+    ],
+  );
+  const pendingAdminCustomReceiptLineIds = useMemo(() => {
+    const appliedLinesById = new Map(
+      appliedAdminCustomReceiptLines.map((line) => [line.id, line]),
+    );
+    return adminCustomReceiptLines.flatMap((line) => {
+      const appliedLine = appliedLinesById.get(line.id);
+      return !appliedLine || JSON.stringify(line) !== JSON.stringify(appliedLine)
+        ? [line.id]
+        : [];
+    });
+  }, [adminCustomReceiptLines, appliedAdminCustomReceiptLines]);
+
   return {
     adminCustomReceiptLines,
+    appliedAdminCustomReceiptLines,
+    adminReverseAdjustmentIds,
+    hasPendingAdminCustomReceiptLineChanges,
+    pendingAdminCustomReceiptLineIds,
+    hasHydratedExistingAdjustments,
     handleAddAdminCustomReceiptLine,
     handleUpdateAdminCustomReceiptLine,
     handleRemoveAdminCustomReceiptLine,
+    handleApplyAdminCustomReceiptLines,
   };
 }