From b29c667af76e894b1b9c235224765d17684e62e4 Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Tue, 19 May 2026 12:05:15 -0400
Subject: [PATCH 1/4] feat: freeform survey responses, refactor: pass customer
 and subscription to all steps, style: plan change step with awareness of
 current plan

---
 apps/playground/src/RecipeBrowser.tsx         |   8 +
 packages/react/src/components/cancel-flow.tsx |  35 +++-
 .../src/components/steps/default-confirm.tsx  |   4 +-
 .../src/components/steps/default-survey.tsx   |  15 ++
 .../steps/offer/default-plan-change-offer.tsx |  20 ++-
 .../components/structural/default-modal.tsx   |   4 +-
 packages/react/src/core/format.ts             |  20 +++
 packages/react/src/core/index.ts              |   4 +-
 packages/react/src/core/machine.ts            |  39 ++--
 packages/react/src/core/transform.ts          |   3 +-
 packages/react/src/core/types.ts              |  53 ++++--
 packages/react/src/core/utils.ts              |   8 +
 .../react/src/headless/use-cancel-flow.ts     |   4 +-
 packages/react/src/styles/cancel-flow.css     |  61 +++++--
 .../tests/components/cancel-flow.test.tsx     | 167 ++++++++++++++++++
 packages/react/tests/core/machine.test.ts     | 110 ++++++++++++
 .../tests/headless/use-cancel-flow.test.tsx   |  83 +++++++++
 17 files changed, 582 insertions(+), 56 deletions(-)
 create mode 100644 packages/react/tests/headless/use-cancel-flow.test.tsx

diff --git a/apps/playground/src/RecipeBrowser.tsx b/apps/playground/src/RecipeBrowser.tsx
index 7f23ac1..b5d6dfe 100644
--- a/apps/playground/src/RecipeBrowser.tsx
+++ b/apps/playground/src/RecipeBrowser.tsx
@@ -35,6 +35,7 @@ const RECIPES: Recipe[] = [
       <NpsWithFaces
         step={{ type: 'nps', title: 'How was your experience?' }}
         customer={null}
+        subscriptions={[]}
         onNext={noop}
         onBack={noop}
       />
@@ -53,6 +54,7 @@ const RECIPES: Recipe[] = [
           copy: { headline: '', body: '', cta: '', declineCta: '' },
         }}
         customer={null}
+        subscriptions={[]}
         onAccept={noopAsync}
         onDecline={noop}
         isProcessing={false}
@@ -93,6 +95,8 @@ const RECIPES: Recipe[] = [
             declineCta: 'No thanks, continue',
           },
         }}
+        customer={null}
+        subscriptions={[]}
         onAccept={noopAsync}
         onDecline={noop}
         isProcessing={false}
@@ -117,6 +121,8 @@ const RECIPES: Recipe[] = [
             declineCta: 'No thanks, continue',
           },
         }}
+        customer={null}
+        subscriptions={[]}
         onAccept={noopAsync}
         onDecline={noop}
         isProcessing={false}
@@ -135,6 +141,8 @@ const RECIPES: Recipe[] = [
         description="You'll lose these features you put to good use:"
         confirmLabel="Continue cancellation"
         goBackLabel="Keep my subscription"
+        customer={null}
+        subscriptions={[]}
         onConfirm={noopAsync}
         onGoBack={noop}
         isProcessing={false}
diff --git a/packages/react/src/components/cancel-flow.tsx b/packages/react/src/components/cancel-flow.tsx
index 51d8a9a..90df69d 100644
--- a/packages/react/src/components/cancel-flow.tsx
+++ b/packages/react/src/components/cancel-flow.tsx
@@ -13,7 +13,7 @@ import type {
   SuccessStep,
   SurveyStep,
 } from '../core/types'
-import { appearanceToStyle, defaultTitles } from '../core/utils'
+import { appearanceToStyle, BUILT_IN_OFFER_TYPES, defaultTitles } from '../core/utils'
 import { useCancelFlowMachine } from '../headless/use-cancel-flow-machine'
 import { DefaultConfirm } from './steps/default-confirm'
 import { DefaultFeedback } from './steps/default-feedback'
@@ -79,7 +79,7 @@ function LoadStatus({
 
   return (
     <div className="ck-cancel-flow" data-color-scheme={scheme} style={appearanceStyle}>
-      <Modal open={true} onClose={handleClose} className={classNames?.modal}>
+      <Modal open={true} onClose={handleClose} className={classNames?.modal} overlayClassName={classNames?.overlay}>
         <CloseButton onClose={handleClose} className={classNames?.closeButton} />
         <div className="ck-content">
           {isLoading && (
@@ -148,7 +148,7 @@ function FlowShell({ machine, state, appearance, classNames, components, customC
 
   return (
     <div className="ck-cancel-flow" data-color-scheme={scheme} style={appearanceStyle}>
-      <Modal open={true} onClose={machine.close} className={classNames?.modal}>
+      <Modal open={true} onClose={machine.close} className={classNames?.modal} overlayClassName={classNames?.overlay}>
         <CloseButton onClose={machine.close} className={classNames?.closeButton} />
         <div className="ck-content">
           {machine.canGoBack && <BackButton onBack={machine.back} className={classNames?.backButton} />}
@@ -185,9 +185,13 @@ function StepRenderer({
         <Survey
           title={config?.title ?? defaultTitles.survey}
           description={config?.description}
+          customer={state.customer}
+          subscriptions={state.subscriptions}
           reasons={machine.reasons}
           selectedReason={state.selectedReason}
           onSelectReason={machine.selectReason}
+          freeformText={state.freeformText}
+          onFreeformChange={machine.setFreeformText}
           onNext={machine.next}
           classNames={config?.classNames}
           components={components}
@@ -206,18 +210,24 @@ function StepRenderer({
           <CustomOffer
             offer={offer}
             customer={state.customer}
+            subscriptions={state.subscriptions}
             onAccept={machine.accept}
             onDecline={machine.decline}
             isProcessing={state.isProcessing}
           />
         )
       }
+      if (!BUILT_IN_OFFER_TYPES.includes(offer.type)) {
+        return <UnregisteredOfferFallback offerType={offer.type} onSkip={machine.decline} />
+      }
       const Offer = components?.Offer ?? DefaultOffer
       const config = stepConfig as OfferStep | undefined
       return (
         <Offer
           title={config?.title}
           description={config?.description}
+          customer={state.customer}
+          subscriptions={state.subscriptions}
           offer={offer}
           onAccept={machine.accept}
           onDecline={machine.decline}
@@ -235,6 +245,8 @@ function StepRenderer({
         <Feedback
           title={config?.title ?? defaultTitles.feedback}
           description={config?.description}
+          customer={state.customer}
+          subscriptions={state.subscriptions}
           placeholder={config?.placeholder}
           required={config?.required ?? false}
           minLength={config?.minLength ?? 0}
@@ -253,6 +265,8 @@ function StepRenderer({
         <Confirm
           title={config?.title ?? defaultTitles.confirm}
           description={config?.description}
+          customer={state.customer}
+          subscriptions={state.subscriptions}
           losses={config?.losses}
           lossesLabel={config?.lossesLabel}
           confirmLabel={config?.confirmLabel ?? 'Cancel subscription'}
@@ -281,6 +295,8 @@ function StepRenderer({
               ? (config?.savedDescription ?? 'Your offer has been applied.')
               : (config?.cancelledDescription ?? "We're sorry to see you go.")
           }
+          customer={state.customer}
+          subscriptions={state.subscriptions}
           onClose={machine.close}
           classNames={config?.classNames}
         />
@@ -305,6 +321,7 @@ function StepRenderer({
             data: config?.data,
           }}
           customer={state.customer}
+          subscriptions={state.subscriptions}
           onNext={machine.next}
           onBack={machine.back}
         />
@@ -313,8 +330,7 @@ function StepRenderer({
   }
 }
 
-// Skips a custom step the consumer didn't register a component for. The skip
-// runs in an effect so we don't mutate machine state during render.
+// Skip runs in an effect so we don't mutate machine state during render.
 function UnregisteredStepFallback({ step, onSkip }: { step: string; onSkip: () => void }) {
   useEffect(() => {
     console.warn(`[churnkey] No component registered for step type "${step}". Skipping.`)
@@ -322,3 +338,12 @@ function UnregisteredStepFallback({ step, onSkip }: { step: string; onSkip: () =
   }, [step, onSkip])
   return null
 }
+
+// Pass machine.decline as onSkip so the auto-advance doesn't record an accept.
+function UnregisteredOfferFallback({ offerType, onSkip }: { offerType: string; onSkip: () => void }) {
+  useEffect(() => {
+    console.warn(`[churnkey] No component registered for offer type "${offerType}". Skipping.`)
+    onSkip()
+  }, [offerType, onSkip])
+  return null
+}
diff --git a/packages/react/src/components/steps/default-confirm.tsx b/packages/react/src/components/steps/default-confirm.tsx
index 60a1e56..0928e4a 100644
--- a/packages/react/src/components/steps/default-confirm.tsx
+++ b/packages/react/src/components/steps/default-confirm.tsx
@@ -1,3 +1,4 @@
+import { formatPeriodEnd } from '../../core/format'
 import type { ConfirmStepProps } from '../../core/types'
 import { cn } from '../../core/utils'
 import { RichText } from '../rich-text'
@@ -5,17 +6,18 @@ import { RichText } from '../rich-text'
 export function DefaultConfirm({
   title,
   description,
+  subscriptions,
   losses,
   lossesLabel,
   confirmLabel,
   goBackLabel,
-  periodEnd,
   onConfirm,
   onGoBack,
   isProcessing,
   classNames,
 }: ConfirmStepProps) {
   const hasLosses = Array.isArray(losses) && losses.length > 0
+  const periodEnd = formatPeriodEnd(subscriptions)
   return (
     <div className={cn('ck-step ck-step-confirm', classNames?.root)}>
       <h2 className={cn('ck-step-title', classNames?.title)}>{title}</h2>
diff --git a/packages/react/src/components/steps/default-survey.tsx b/packages/react/src/components/steps/default-survey.tsx
index 52fa422..a0bdbd5 100644
--- a/packages/react/src/components/steps/default-survey.tsx
+++ b/packages/react/src/components/steps/default-survey.tsx
@@ -30,12 +30,16 @@ export function DefaultSurvey({
   reasons,
   selectedReason,
   onSelectReason,
+  freeformText,
+  onFreeformChange,
   onNext,
   classNames,
   components,
 }: SurveyStepProps) {
   const ReasonButton = components?.ReasonButton ?? DefaultReasonButton
   const listRef = useRef<HTMLDivElement>(null)
+  const selected = reasons.find((r) => r.id === selectedReason)
+  const showFreeform = selected?.freeform === true
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -80,6 +84,17 @@ export function DefaultSurvey({
         ))}
       </div>
 
+      {showFreeform && (
+        <textarea
+          className={cn('ck-reason-freeform', classNames?.freeformInput)}
+          placeholder="Tell us more (optional)"
+          rows={3}
+          value={freeformText}
+          onChange={(e) => onFreeformChange(e.target.value)}
+          aria-label="Additional detail"
+        />
+      )}
+
       <button
         type="button"
         className={cn('ck-button ck-button-primary', classNames?.continueButton)}
diff --git a/packages/react/src/components/steps/offer/default-plan-change-offer.tsx b/packages/react/src/components/steps/offer/default-plan-change-offer.tsx
index 9e2018d..109808b 100644
--- a/packages/react/src/components/steps/offer/default-plan-change-offer.tsx
+++ b/packages/react/src/components/steps/offer/default-plan-change-offer.tsx
@@ -8,6 +8,7 @@ import { Checkmark } from '../shared'
 export function DefaultPlanChangeOffer({
   title,
   description,
+  subscriptions,
   offer,
   onAccept,
   onDecline,
@@ -16,7 +17,11 @@ export function DefaultPlanChangeOffer({
 }: OfferStepProps) {
   const o = offer as OfferDecision & { plans?: PlanOption[] }
   const plans = o.plans ?? []
-  const [selectedPlanId, setSelectedPlanId] = useState<string | null>(plans[0]?.id ?? null)
+  // Mark the customer's current plan via their first subscription's first
+  // price; switching to that same plan would be a no-op so it gets disabled.
+  const currentPlanId = subscriptions[0]?.items[0]?.price.id
+  const initialPlanId = plans.find((p) => p.id !== currentPlanId)?.id ?? null
+  const [selectedPlanId, setSelectedPlanId] = useState<string | null>(initialPlanId)
   const selectedPlan = plans.find((p) => p.id === selectedPlanId) ?? null
 
   const headline = title ?? offer.copy.headline
@@ -38,16 +43,25 @@ export function DefaultPlanChangeOffer({
             const interval = plan.duration?.interval ?? 'month'
             const currency = plan.amount.currency ?? 'USD'
             const isSelected = plan.id === selectedPlanId
+            const isCurrent = plan.id === currentPlanId
 
             return (
               <button
                 type="button"
                 key={plan.id}
                 onClick={() => setSelectedPlanId(plan.id)}
-                className={cn('ck-plan-card', isSelected && 'ck-plan-card--selected')}
+                disabled={isCurrent}
+                className={cn(
+                  'ck-plan-card',
+                  isSelected && 'ck-plan-card--selected',
+                  isCurrent && 'ck-plan-card--current',
+                )}
                 aria-pressed={isSelected}
               >
-                <div className="ck-plan-name">{plan.name ?? plan.id}</div>
+                <div className="ck-plan-name">
+                  {plan.name ?? plan.id}
+                  {isCurrent && <span className="ck-plan-current-badge">Current</span>}
+                </div>
                 {plan.tagline && <div className="ck-plan-tagline">{plan.tagline}</div>}
 
                 <div className="ck-plan-price-row">
diff --git a/packages/react/src/components/structural/default-modal.tsx b/packages/react/src/components/structural/default-modal.tsx
index c0af555..7168567 100644
--- a/packages/react/src/components/structural/default-modal.tsx
+++ b/packages/react/src/components/structural/default-modal.tsx
@@ -37,7 +37,7 @@ function trapFocus(container: HTMLElement): () => void {
   return () => container.removeEventListener('keydown', handleKeyDown)
 }
 
-export function DefaultModal({ open, onClose, children, className }: ModalProps) {
+export function DefaultModal({ open, onClose, children, className, overlayClassName }: ModalProps) {
   const overlayRef = useRef<HTMLDivElement>(null)
   const modalRef = useRef<HTMLDivElement>(null)
   const previousFocusRef = useRef<HTMLElement | null>(null)
@@ -74,7 +74,7 @@ export function DefaultModal({ open, onClose, children, className }: ModalProps)
   return (
     <div
       ref={overlayRef}
-      className="ck-overlay"
+      className={cn('ck-overlay', overlayClassName)}
       onClick={(e) => {
         if (e.target === overlayRef.current) onClose()
       }}
diff --git a/packages/react/src/core/format.ts b/packages/react/src/core/format.ts
index 81c6710..cf18435 100644
--- a/packages/react/src/core/format.ts
+++ b/packages/react/src/core/format.ts
@@ -1,3 +1,5 @@
+import type { DirectSubscription } from './types'
+
 // Currencies whose smallest unit equals one major unit (no fractional part).
 // Stripe and most billing providers store these without an implicit /100.
 const ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
@@ -95,6 +97,24 @@ export function formatMonthDayLong(date: Date, locale?: string): string {
   return date.toLocaleDateString(locale, { month: 'long', day: 'numeric' })
 }
 
+/**
+ * Long-form access period end ("June 14, 2026") for the first subscription's
+ * current period. Returns null for canceled subscriptions, missing periods,
+ * and unparseable dates so Confirm can drop the "access continues until"
+ * notice cleanly instead of rendering "Invalid Date".
+ */
+export function formatPeriodEnd(
+  subscriptions: DirectSubscription[] | null | undefined,
+  locale?: string,
+): string | null {
+  const status = subscriptions?.[0]?.status
+  if (!status || !('currentPeriod' in status) || !status.currentPeriod?.end) return null
+  const end = status.currentPeriod.end
+  const d = end instanceof Date ? end : new Date(end)
+  if (Number.isNaN(d.getTime())) return null
+  return d.toLocaleDateString(locale, { month: 'long', day: 'numeric', year: 'numeric' })
+}
+
 // ─── Discount phrasing ─────────────────────────────────────────────────────
 
 /**
diff --git a/packages/react/src/core/index.ts b/packages/react/src/core/index.ts
index 580e295..e37197b 100644
--- a/packages/react/src/core/index.ts
+++ b/packages/react/src/core/index.ts
@@ -12,7 +12,7 @@ export type {
   SdkStep,
   SdkSurveyStep,
 } from './api-types'
-export { calculateDiscountedPrice, formatPrice } from './format'
+export { calculateDiscountedPrice, formatPeriodEnd, formatPrice } from './format'
 export { CancelFlowMachine } from './machine'
 export type { ResolvedStep } from './step-graph'
 export type { SessionCredentials } from './token'
@@ -73,4 +73,4 @@ export type {
   SurveyStepProps,
   TrialExtensionOffer,
 } from './types'
-export { appearanceToStyle, BUILT_IN_STEP_TYPES, cn, defaultTitles } from './utils'
+export { appearanceToStyle, BUILT_IN_OFFER_TYPES, BUILT_IN_STEP_TYPES, cn, defaultTitles } from './utils'
diff --git a/packages/react/src/core/machine.ts b/packages/react/src/core/machine.ts
index 34302e5..f97b83f 100644
--- a/packages/react/src/core/machine.ts
+++ b/packages/react/src/core/machine.ts
@@ -240,7 +240,10 @@ export class CancelFlowMachine {
       this.graph = buildStepGraph(merged, defaultOfferCopy)
     }
 
-    this.state = this.buildInitialState(null)
+    // Seed state from local props for open-source and analytics modes. Token
+    // mode overwrites both fields once initializeFromConfig settles, so these
+    // values only matter for the pre-fetch render.
+    this.state = this.buildInitialState(this.directCustomer, this.directSubscriptions ?? [])
     this.cachedSnapshot = { ...this.state }
 
     // Defer entry tracking in token mode — firing trackStepEnter before the
@@ -308,7 +311,12 @@ export class CancelFlowMachine {
 
   selectReason = (id: string): void => {
     if (!this.reasons.find((r) => r.id === id)) return
-    this.setState({ selectedReason: id })
+    // Clear freeform text on reason change so it doesn't carry across selections.
+    this.setState({ selectedReason: id, freeformText: '' })
+  }
+
+  setFreeformText = (text: string): void => {
+    this.setState({ freeformText: text })
   }
 
   next = (result?: Record<string, unknown>): void => {
@@ -425,7 +433,7 @@ export class CancelFlowMachine {
     const steps = applyMergeFieldsToSteps(merged, config.customer ?? null)
     this.graph = buildStepGraph(steps, defaultOfferCopy)
 
-    this.state = this.buildInitialState(config.customer ?? null)
+    this.state = this.buildInitialState(config.customer ?? null, config.subscriptions ?? [])
     this.cachedSnapshot = { ...this.state }
     const first = this.firstStep()
     if (first) this.trackStepEnter(first)
@@ -446,17 +454,19 @@ export class CancelFlowMachine {
     return this.graph.surveyStepId ? this.graph.stepMap[this.graph.surveyStepId] : undefined
   }
 
-  private buildInitialState(customer: DirectCustomer | null): FlowState {
+  private buildInitialState(customer: DirectCustomer | null, subscriptions: DirectSubscription[]): FlowState {
     const first = this.firstStep()
     return {
       step: first?.type ?? 'survey',
       currentStepId: this.graph.firstStepId,
       selectedReason: null,
+      freeformText: '',
       feedback: '',
       outcome: null,
       isProcessing: false,
       error: null,
       customer,
+      subscriptions,
     }
   }
 
@@ -592,14 +602,14 @@ export class CancelFlowMachine {
   }
 
   // Offer passed in so accept() can capture it before enterSuccessStep
-  // potentially moves currentStepId off the offer step.
+  // potentially moves currentStepId off the offer step. copy and decisionId
+  // are SDK-internal — strip them from the consumer-facing payload.
   private buildAcceptedOffer(offer: OfferDecision, result?: Record<string, unknown>): AcceptedOffer {
-    const { copy: _, ...offerConfig } = offer
-    return {
-      ...offerConfig,
-      reasonId: this.state.selectedReason!,
-      ...(result ? { result } : {}),
-    }
+    const { copy: _copy, decisionId: _decisionId, ...offerConfig } = offer
+    const accepted: AcceptedOffer = offerConfig
+    if (this.state.selectedReason) accepted.reasonId = this.state.selectedReason
+    if (result) accepted.result = result
+    return accepted
   }
 
   // Terminal transition. Prefer moving currentStepId to a declared success
@@ -626,12 +636,17 @@ export class CancelFlowMachine {
 
   private buildBasePayload(): SessionPayload {
     const selectedReason = this.reasons.find((r) => r.id === this.state.selectedReason)
+    // For freeform reasons, the typed text replaces the static label as
+    // surveyChoiceValue. surveyChoiceId still carries the reason id so
+    // analytics groupings hold.
+    const surveyChoiceValue =
+      selectedReason?.freeform && this.state.freeformText ? this.state.freeformText : selectedReason?.label
     const payload: SessionPayload = {
       blueprintId: this.blueprintId ?? undefined,
       customer: this.resolveSessionCustomer(),
       canceled: false,
       surveyChoiceId: this.state.selectedReason ?? undefined,
-      surveyChoiceValue: selectedReason?.label,
+      surveyChoiceValue,
       feedback: this.state.feedback || undefined,
       presentedOffers: this.presentedOffers,
       stepsViewed: this.stepsViewed,
diff --git a/packages/react/src/core/transform.ts b/packages/react/src/core/transform.ts
index c4bd956..851cd6c 100644
--- a/packages/react/src/core/transform.ts
+++ b/packages/react/src/core/transform.ts
@@ -66,8 +66,8 @@ function transformReason(r: SdkReason): ReasonConfig {
   const out: ReasonConfig = {
     id: r.id,
     label: r.label,
-    freeform: r.freeform,
   }
+  if (r.freeform) out.freeform = true
   if (r.offer) out.offer = transformOfferConfig(r.offer)
   return out
 }
@@ -94,7 +94,6 @@ function transformOfferConfig(o: SdkOffer): OfferConfig {
         type: 'pause',
         months: o.months,
         interval: o.interval,
-        datePicker: o.datePicker,
       }
     case 'plan_change':
       return {
diff --git a/packages/react/src/core/types.ts b/packages/react/src/core/types.ts
index 15619c2..11cf669 100644
--- a/packages/react/src/core/types.ts
+++ b/packages/react/src/core/types.ts
@@ -122,13 +122,11 @@ export interface PauseOffer {
   type: 'pause'
   months: number
   interval?: 'month' | 'week'
-  datePicker?: boolean
 }
 
 export interface PlanChangeOffer {
   type: 'plan_change'
   plans: PlanOption[]
-  currentPlanId?: string
 }
 
 /**
@@ -187,8 +185,11 @@ export interface OfferCopy {
 }
 
 export type AcceptedOffer = OfferConfig & {
-  reasonId: string
-  decisionId?: string
+  /** Survey reason that routed to this offer. Absent when the offer was
+   *  declared as a standalone `OfferStep`. */
+  reasonId?: string
+  /** Payload from custom offers — whatever your component passed to
+   *  `onAccept(result)`. Built-in offer types do not populate this. */
   result?: Record<string, unknown>
 }
 
@@ -197,6 +198,11 @@ export type AcceptedOffer = OfferConfig & {
 export interface ReasonConfig {
   id: string
   label: string
+  /**
+   * When true, picking this reason reveals a text input below the reason list.
+   * The text the customer types lands on the session as `surveyChoiceValue`
+   * (the reason's `id` still travels as `surveyChoiceId`).
+   */
   freeform?: boolean
   offer?: OfferConfig
 }
@@ -222,9 +228,10 @@ export interface OfferStep {
   title?: string
   description?: string
   /**
-   * Offer attached to this step. Set this for proactive save offers shown
-   * outside a survey; the SDK also populates it automatically on synthetic
-   * offer steps spawned from survey choices.
+   * Offer attached to this step. Set this to declare a standalone offer
+   * step (one that isn't routed from a survey reason). The SDK also
+   * populates this automatically on synthetic offer steps spawned from
+   * survey choices.
    */
   offer?: OfferDecision
   classNames?: OfferClassNames
@@ -411,9 +418,9 @@ export interface AppearanceVariables {
 
   // Overlay
   /**
-   * Color of the dim behind the modal. Accepts any CSS color (rgba,
-   * color-mix, etc.). Defaults to a tinted version of the primary color
-   * so any primary swap automatically re-tints the overlay.
+   * Color of the dim behind the modal. Defaults to a neutral translucent
+   * ink. Set to `color-mix(in srgb, var(--ck-color-primary) 40%, transparent)`
+   * to derive the overlay from your primary color, or any CSS color value.
    */
   overlayColor: string
 }
@@ -430,6 +437,7 @@ export interface Appearance {
 export interface CustomStepProps {
   step: CustomStepConfig
   customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   onNext: (result?: Record<string, unknown>) => void
   onBack: () => void
 }
@@ -437,6 +445,7 @@ export interface CustomStepProps {
 export interface CustomOfferProps {
   offer: OfferDecision
   customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   onAccept: (result?: Record<string, unknown>) => Promise<void>
   onDecline: () => void
   isProcessing: boolean
@@ -481,6 +490,7 @@ export interface ModalProps {
   onClose: () => void
   children: ReactNode
   className?: string
+  overlayClassName?: string
 }
 
 export interface CloseButtonProps {
@@ -498,9 +508,15 @@ export interface BackButtonProps {
 export interface SurveyStepProps {
   title: string
   description?: string
+  customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   reasons: ReasonConfig[]
   selectedReason: string | null
   onSelectReason: (id: string) => void
+  /** Free-text value when the selected reason has `freeform: true`. */
+  freeformText: string
+  /** Set the freeform text. The SDK forwards the value to the session. */
+  onFreeformChange: (text: string) => void
   onNext: () => void
   classNames?: SurveyClassNames
   components?: Partial<ComponentOverrides>
@@ -509,6 +525,8 @@ export interface SurveyStepProps {
 export interface OfferStepProps {
   title?: string
   description?: string
+  customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   offer: OfferDecision
   /**
    * Accept the offer. The optional `result` is included on the resulting
@@ -530,6 +548,8 @@ export interface OfferStepProps {
 export interface FeedbackStepProps {
   title: string
   description?: string
+  customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   placeholder?: string
   required: boolean
   minLength: number
@@ -542,11 +562,12 @@ export interface FeedbackStepProps {
 export interface ConfirmStepProps {
   title: string
   description?: string
+  customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   losses?: string[]
   lossesLabel?: string
   confirmLabel: string
   goBackLabel: string
-  periodEnd?: string
   onConfirm: () => Promise<void>
   onGoBack: () => void
   isProcessing: boolean
@@ -558,6 +579,8 @@ export interface SuccessStepProps {
   offer?: OfferDecision
   title: string
   description?: string
+  customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
   onClose: () => void
   classNames?: SuccessClassNames
 }
@@ -577,11 +600,13 @@ export interface FlowState {
   step: string
   currentStepId: string
   selectedReason: string | null
+  freeformText: string
   feedback: string
   outcome: 'saved' | 'cancelled' | null
   isProcessing: boolean
   error: Error | null
   customer: DirectCustomer | null
+  subscriptions: DirectSubscription[]
 }
 
 // ─── Flow config ─────────────────────────────────────────────────────────────
@@ -649,10 +674,4 @@ export interface CancelFlowProps extends FlowCallbacks {
   classNames?: StructuralClassNames
   components?: Partial<ComponentOverrides>
   customComponents?: CustomComponents
-  layout?: {
-    desktop?: 'modal' | 'inline' | 'drawer'
-    mobile?: 'sheet' | 'fullscreen' | 'inline'
-    breakpoint?: number
-  }
-  animation?: 'css' | 'framer' | 'none'
 }
diff --git a/packages/react/src/core/utils.ts b/packages/react/src/core/utils.ts
index 6f6840b..ff1b2a1 100644
--- a/packages/react/src/core/utils.ts
+++ b/packages/react/src/core/utils.ts
@@ -2,6 +2,14 @@ import type { CSSProperties } from 'react'
 import type { Appearance, AppearanceVariables } from './types'
 
 export const BUILT_IN_STEP_TYPES: readonly string[] = ['survey', 'offer', 'feedback', 'confirm', 'success']
+export const BUILT_IN_OFFER_TYPES: readonly string[] = [
+  'discount',
+  'pause',
+  'trial_extension',
+  'plan_change',
+  'contact',
+  'redirect',
+]
 
 export function cn(...classes: (string | undefined | null | false)[]): string {
   return classes.filter(Boolean).join(' ')
diff --git a/packages/react/src/headless/use-cancel-flow.ts b/packages/react/src/headless/use-cancel-flow.ts
index 9e9a1ec..414f7fc 100644
--- a/packages/react/src/headless/use-cancel-flow.ts
+++ b/packages/react/src/headless/use-cancel-flow.ts
@@ -2,18 +2,20 @@ import type { FlowConfig } from '../core/types'
 import { useCancelFlowMachine } from './use-cancel-flow-machine'
 
 export function useCancelFlow(config: FlowConfig) {
-  const { machine, state, isLoading, loadError } = useCancelFlowMachine(config)
+  const { machine, state, isLoading, loadError, retry } = useCancelFlowMachine(config)
 
   return {
     ...state,
     isLoading,
     loadError,
+    retry,
     reasons: machine.reasons,
     currentStep: machine.currentStep,
     currentOffer: machine.currentOffer,
     stepIndex: machine.stepIndex,
     totalSteps: machine.totalSteps,
     selectReason: machine.selectReason,
+    setFreeformText: machine.setFreeformText,
     setFeedback: machine.setFeedback,
     accept: machine.accept,
     decline: machine.decline,
diff --git a/packages/react/src/styles/cancel-flow.css b/packages/react/src/styles/cancel-flow.css
index 1bdccc0..244e787 100644
--- a/packages/react/src/styles/cancel-flow.css
+++ b/packages/react/src/styles/cancel-flow.css
@@ -71,12 +71,11 @@
   --ck-shadow-modal: 0 20px 25px -5px rgba(12, 10, 9, 0.1), 0 8px 10px -6px rgba(12, 10, 9, 0.06);
   --ck-shadow-card: 0 1px 2px rgba(12, 10, 9, 0.04), 0 1px 3px rgba(12, 10, 9, 0.06);
 
-  /* Overlay tint behind the modal. Defaults to a tinted version of the
-     primary color so any primary swap naturally re-tints the overlay.
-     Falls back gracefully on browsers without color-mix() support — the
-     declaration is invalid in those, so the rule below it (or the inline
-     style) wins. */
-  --ck-overlay-color: color-mix(in srgb, var(--ck-color-primary) 40%, transparent);
+  /* Dim behind the modal. Neutral translucent ink by default. Brands that
+     want a primary-tinted overlay can override this with their own value —
+     e.g. `color-mix(in srgb, var(--ck-color-primary) 40%, transparent)` for
+     auto re-tinting on primary swaps. */
+  --ck-overlay-color: rgba(12, 10, 9, 0.5);
 
   /* Motion */
   --ck-motion-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
@@ -144,11 +143,6 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  /* Fallback for browsers without color-mix() support — used if the token
-     evaluates to an invalid value. Modern engines (Chrome 111+, Safari
-     16.2+, Firefox 113+) resolve --ck-overlay-color from the :root rule. */
-  background: rgba(12, 10, 9, 0.5);
-  /* biome-ignore lint/suspicious/noDuplicateProperties: progressive enhancement fallback */
   background: var(--ck-overlay-color);
   z-index: 9999;
 }
@@ -353,6 +347,25 @@
   margin-bottom: 20px;
 }
 
+.ck-cancel-flow .ck-reason-freeform {
+  width: 100%;
+  font-family: var(--ck-font);
+  font-size: 14px;
+  color: var(--ck-color-text);
+  background: var(--ck-color-surface);
+  border: 1px solid var(--ck-color-border);
+  border-radius: var(--ck-radius-md);
+  padding: 10px 12px;
+  margin-bottom: 20px;
+  resize: vertical;
+  min-height: 72px;
+}
+
+.ck-cancel-flow .ck-reason-freeform:focus {
+  outline: none;
+  border-color: var(--ck-color-primary);
+}
+
 .ck-cancel-flow .ck-reason-button {
   display: flex;
   align-items: center;
@@ -613,6 +626,17 @@
   box-shadow: var(--ck-shadow-card);
 }
 
+.ck-cancel-flow .ck-plan-card--current {
+  cursor: not-allowed;
+  opacity: 0.6;
+  background: var(--ck-color-surface-muted);
+}
+
+.ck-cancel-flow .ck-plan-card--current:hover {
+  border-color: var(--ck-color-border);
+  background: var(--ck-color-surface-muted);
+}
+
 .ck-cancel-flow .ck-plan-name {
   font-family: var(--ck-font-display);
   font-size: 16px;
@@ -620,6 +644,21 @@
   letter-spacing: -0.01em;
   color: var(--ck-color-text);
   margin-bottom: 4px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.ck-cancel-flow .ck-plan-current-badge {
+  font-family: var(--ck-font);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0;
+  color: var(--ck-color-text-secondary);
+  background: var(--ck-color-surface);
+  border: 1px solid var(--ck-color-border);
+  padding: 2px 6px;
+  border-radius: var(--ck-radius-sm);
 }
 
 .ck-cancel-flow .ck-plan-tagline {
diff --git a/packages/react/tests/components/cancel-flow.test.tsx b/packages/react/tests/components/cancel-flow.test.tsx
index 4d976f5..f47247b 100644
--- a/packages/react/tests/components/cancel-flow.test.tsx
+++ b/packages/react/tests/components/cancel-flow.test.tsx
@@ -292,4 +292,171 @@ describe('CancelFlow', () => {
     // Body content renders below it.
     expect(screen.getByText('Too expensive')).toBeInTheDocument()
   })
+
+  it('forwards classNames.overlay to the overlay element', () => {
+    renderFlow({ classNames: { overlay: 'my-overlay-class' } })
+    // The overlay is the outermost dialog wrapper. Walk up from the dialog
+    // node to find it; querying by class would couple the test to the SDK's
+    // own class names.
+    const dialog = screen.getByRole('dialog')
+    const overlay = dialog.parentElement
+    expect(overlay).not.toBeNull()
+    expect(overlay).toHaveClass('my-overlay-class')
+  })
+
+  it('warns and skips an unregistered custom offer type', async () => {
+    const user = userEvent.setup()
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const stepsWithUnknownOffer: Step[] = [
+      {
+        type: 'survey',
+        reasons: [
+          {
+            id: 'pick',
+            label: 'Pick me',
+            // Custom offer type with no customComponents entry; the SDK
+            // should warn and advance via decline rather than render blank.
+            offer: { type: 'mystery-offer', data: {} },
+          },
+        ],
+      },
+      { type: 'confirm', title: 'Confirm cancellation' },
+    ]
+    render(
+      <CancelFlow
+        steps={stepsWithUnknownOffer}
+        onAccept={vi.fn().mockResolvedValue(undefined)}
+        onCancel={vi.fn().mockResolvedValue(undefined)}
+      />,
+    )
+
+    await user.click(screen.getByText('Pick me'))
+    await user.click(screen.getByText('Continue'))
+
+    await waitFor(() => {
+      expect(screen.getByText('Confirm cancellation')).toBeInTheDocument()
+    })
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('No component registered for offer type "mystery-offer"'))
+    warn.mockRestore()
+  })
+
+  it('renders a freeform textarea when the selected reason has freeform: true', async () => {
+    const user = userEvent.setup()
+    const freeformSteps: Step[] = [
+      {
+        type: 'survey',
+        reasons: [
+          { id: 'other', label: 'Other', freeform: true },
+          { id: 'expensive', label: 'Too expensive' },
+        ],
+      },
+      { type: 'confirm', title: 'Confirm cancellation' },
+    ]
+    render(
+      <CancelFlow
+        steps={freeformSteps}
+        onAccept={vi.fn().mockResolvedValue(undefined)}
+        onCancel={vi.fn().mockResolvedValue(undefined)}
+      />,
+    )
+
+    // No textarea before any reason is selected.
+    expect(screen.queryByLabelText('Additional detail')).toBeNull()
+
+    await user.click(screen.getByText('Other'))
+    const textarea = await screen.findByLabelText('Additional detail')
+
+    await user.type(textarea, 'switching to a competitor')
+    expect(textarea).toHaveValue('switching to a competitor')
+
+    // Switching to a non-freeform reason hides the textarea and clears state.
+    await user.click(screen.getByText('Too expensive'))
+    expect(screen.queryByLabelText('Additional detail')).toBeNull()
+  })
+
+  it('renders the period-end notice when the active subscription has a current period', () => {
+    render(
+      <CancelFlow
+        appId="app_test"
+        customer={{ id: 'cus_1' }}
+        subscriptions={[
+          {
+            id: 'sub_1',
+            start: '2024-01-01',
+            status: { name: 'active', currentPeriod: { start: '2025-04-01', end: '2025-05-01' } },
+            items: [{ price: { id: 'p', amount: { value: 100, currency: 'USD' } } }],
+          },
+        ]}
+        steps={[{ type: 'confirm', title: 'Confirm cancellation' }]}
+        onCancel={vi.fn().mockResolvedValue(undefined)}
+      />,
+    )
+
+    // Intl.DateTimeFormat output varies by runtime locale; assert the
+    // notice fires and at least carries the year. Tighter date matching
+    // would couple the test to the test runner's locale.
+    const notice = screen.getByText(/Your access continues until .*2025/)
+    expect(notice).toBeInTheDocument()
+  })
+
+  it("marks the customer's current plan and excludes it from preselection", async () => {
+    const user = userEvent.setup()
+    const planChangeSteps: Step[] = [
+      {
+        type: 'survey',
+        reasons: [
+          {
+            id: 'too-many-features',
+            label: 'Paying for too much',
+            offer: {
+              type: 'plan_change',
+              plans: [
+                { id: 'pro', name: 'Pro', amount: { value: 2900, currency: 'USD' } },
+                { id: 'starter', name: 'Starter', amount: { value: 900, currency: 'USD' } },
+              ],
+            },
+          },
+        ],
+      },
+      { type: 'confirm' },
+    ]
+    const onAccept = vi.fn<(offer: AcceptedOffer) => Promise<void>>().mockResolvedValue(undefined)
+    // Customer's current plan is 'pro', via subscriptions[0].items[0].price.id.
+    render(
+      <CancelFlow
+        steps={planChangeSteps}
+        onAccept={onAccept}
+        onCancel={vi.fn().mockResolvedValue(undefined)}
+        appId="app_test"
+        customer={{ id: 'cus_1' }}
+        subscriptions={[
+          {
+            id: 'sub_1',
+            start: '2024-01-01',
+            status: { name: 'active', currentPeriod: { start: '2025-04-01', end: '2025-05-01' } },
+            items: [{ price: { id: 'pro', amount: { value: 2900, currency: 'USD' } } }],
+          },
+        ]}
+      />,
+    )
+
+    await user.click(screen.getByText('Paying for too much'))
+    await user.click(screen.getByText('Continue'))
+
+    const proCard = screen.getByText('Pro').closest('button')
+    expect(proCard).toBeDisabled()
+    expect(proCard?.textContent).toContain('Current')
+
+    // Preselection skips 'pro' so the accept button targets 'starter' without
+    // further interaction.
+    const acceptButton = await screen.findByText('Switch to Starter')
+    await user.click(acceptButton)
+
+    await waitFor(() => {
+      expect(onAccept).toHaveBeenCalledWith(
+        expect.objectContaining({ type: 'plan_change', result: { planId: 'starter' } }),
+        expect.objectContaining({ id: 'cus_1' }),
+      )
+    })
+  })
 })
diff --git a/packages/react/tests/core/machine.test.ts b/packages/react/tests/core/machine.test.ts
index 5ddd491..de5be49 100644
--- a/packages/react/tests/core/machine.test.ts
+++ b/packages/react/tests/core/machine.test.ts
@@ -1640,4 +1640,114 @@ describe('CancelFlowMachine', () => {
       expect(machine.getSnapshot().customer).toEqual(mockCustomer)
     })
   })
+
+  describe('state.subscriptions and state.customer', () => {
+    const subscription = {
+      id: 's',
+      start: '2024-01-01',
+      status: { name: 'active' as const, currentPeriod: { start: '2025-04-01', end: '2025-05-01' } },
+      items: [{ price: { id: 'p', amount: { value: 100, currency: 'USD' } } }],
+    }
+
+    it('exposes the customer and subscriptions from analytics-mode props', () => {
+      // Regression: state.customer used to be null in analytics mode despite
+      // the customer prop being set, because buildInitialState was passed
+      // null at construction time.
+      const machine = new CancelFlowMachine({
+        ...baseConfig,
+        appId: 'a',
+        customer: { id: 'cus_1', email: 'jane@acme.com' },
+        subscriptions: [subscription],
+      })
+      const snap = machine.getSnapshot()
+      expect(snap.customer).toEqual({ id: 'cus_1', email: 'jane@acme.com' })
+      expect(snap.subscriptions).toEqual([subscription])
+    })
+
+    it('defaults to no customer and empty subscriptions in open-source mode', () => {
+      const machine = new CancelFlowMachine(baseConfig)
+      const snap = machine.getSnapshot()
+      expect(snap.customer).toBeNull()
+      expect(snap.subscriptions).toEqual([])
+    })
+
+    it('populates state.subscriptions from the server config in token mode', () => {
+      const machine = new CancelFlowMachine({ session: 'ck_placeholder' })
+      machine.initializeFromConfig(
+        sdkConfig({
+          customer: { id: 'cus_1' },
+          subscriptions: [subscription],
+          steps: [
+            { type: 'survey', guid: 's1', reasons: [{ id: 'r1', label: 'Test' }] },
+            { type: 'confirm', guid: 'c1' },
+          ],
+        }),
+        {} as any,
+        { appId: 'a', customerId: 'c', authHash: 'h', mode: 'live' as const, issuedAt: 0 },
+      )
+      expect(machine.getSnapshot().subscriptions).toEqual([subscription])
+    })
+  })
+
+  describe('freeform reasons', () => {
+    const withFreeform = {
+      steps: [
+        {
+          type: 'survey' as const,
+          reasons: [
+            { id: 'other', label: 'Other', freeform: true },
+            { id: 'expensive', label: 'Too expensive' },
+          ],
+        },
+        { type: 'confirm' as const },
+      ],
+    }
+
+    it('initial freeformText is empty', () => {
+      const machine = new CancelFlowMachine(withFreeform)
+      expect(machine.getSnapshot().freeformText).toBe('')
+    })
+
+    it('setFreeformText updates state', () => {
+      const machine = new CancelFlowMachine(withFreeform)
+      machine.setFreeformText('Switching to a competitor')
+      expect(machine.getSnapshot().freeformText).toBe('Switching to a competitor')
+    })
+
+    it('resets freeformText when switching reasons', () => {
+      const machine = new CancelFlowMachine(withFreeform)
+      machine.selectReason('other')
+      machine.setFreeformText('typed something')
+      machine.selectReason('expensive')
+      expect(machine.getSnapshot().freeformText).toBe('')
+    })
+  })
+
+  describe('standalone OfferStep accepts', () => {
+    it('omits reasonId when the offer was not routed from a survey', async () => {
+      const onAccept = vi.fn()
+      const machine = new CancelFlowMachine({
+        steps: [
+          {
+            type: 'offer',
+            guid: 'pause_prompt',
+            offer: {
+              type: 'pause',
+              months: 2,
+              copy: { headline: 'Pause?', body: '', cta: 'Pause', declineCta: 'No' },
+            },
+          },
+          { type: 'confirm' },
+        ],
+        onAccept,
+      })
+
+      await machine.accept()
+
+      expect(onAccept).toHaveBeenCalledTimes(1)
+      const [accepted] = onAccept.mock.calls[0]
+      expect(accepted.type).toBe('pause')
+      expect(accepted.reasonId).toBeUndefined()
+    })
+  })
 })
diff --git a/packages/react/tests/headless/use-cancel-flow.test.tsx b/packages/react/tests/headless/use-cancel-flow.test.tsx
new file mode 100644
index 0000000..0d1347f
--- /dev/null
+++ b/packages/react/tests/headless/use-cancel-flow.test.tsx
@@ -0,0 +1,83 @@
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useCancelFlow } from '../../src/headless/use-cancel-flow'
+
+// Mint a token in the format decodeSessionToken accepts. The signature is
+// not verified client-side; the hook just decodes the payload to pull out
+// appId/customerId/authHash for the fetch headers.
+function createToken(payload: Record<string, unknown>): string {
+  const json = JSON.stringify(payload)
+  const base64 = btoa(json).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+  return `ck_${base64}`
+}
+
+const TOKEN = createToken({ a: 'app_1', c: 'cus_1', h: 'h_1', m: 'live', t: 0 })
+
+const goodResponse = {
+  blueprintId: 'bp_1',
+  steps: [{ type: 'survey', guid: 's1', reasons: [{ id: 'r1', label: 'Test' }] }],
+  customer: { id: 'cus_1' },
+  subscriptions: [],
+  settings: { clickToCancelEnabled: false, strictFTCComplianceEnabled: false },
+}
+
+describe('useCancelFlow', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+  // Vitest's React 18 strict mode emits act() warnings whenever a fetch
+  // promise resolves outside a test-controlled tick. The hook deliberately
+  // fires its effect on mount and we can't get a handle on the resolution
+  // promise from the public API. The behavior is right (assertions below
+  // pass via waitFor); only the noise needs filtering.
+  let originalError: typeof console.error
+
+  beforeEach(() => {
+    fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+    originalError = console.error
+    console.error = (...args: unknown[]) => {
+      if (typeof args[0] === 'string' && args[0].includes('not wrapped in act')) return
+      originalError(...args)
+    }
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    console.error = originalError
+  })
+
+  it('exposes retry as a function on the returned object', () => {
+    fetchMock.mockResolvedValue({ ok: true, json: async () => goodResponse } as Response)
+    const { result } = renderHook(() => useCancelFlow({ session: TOKEN }))
+    expect(typeof result.current.retry).toBe('function')
+  })
+
+  it('retry re-fetches the config and clears loadError on success', async () => {
+    // First fetch fails, second succeeds. Verifies the loadError → retry →
+    // recovered flow that the docs promise.
+    fetchMock
+      .mockRejectedValueOnce(new Error('network down'))
+      .mockResolvedValueOnce({ ok: true, json: async () => goodResponse } as Response)
+
+    let hook: ReturnType<typeof renderHook<ReturnType<typeof useCancelFlow>, void>>
+    await act(async () => {
+      hook = renderHook(() => useCancelFlow({ session: TOKEN }))
+    })
+
+    await waitFor(() => {
+      expect(hook!.result.current.loadError).toBeInstanceOf(Error)
+    })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+
+    await act(async () => {
+      hook!.result.current.retry()
+    })
+
+    await waitFor(() => {
+      expect(hook!.result.current.loadError).toBeNull()
+      expect(hook!.result.current.isLoading).toBe(false)
+    })
+
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+})

From 734b08d9d85401e93fa816e442c50237fb93f28a Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Tue, 19 May 2026 12:39:05 -0400
Subject: [PATCH 2/4] refactor(react): align freeform-survey payload with embed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rename the field and action surface so the SDK's vocabulary matches the
embed widget, and split the typed text onto its own session field so
dashboard groupings by reason label stay stable.

- FlowState/SurveyStepProps: freeformText → followupResponse,
  onFreeformChange → onFollowupResponseChange
- Machine: setFreeformText → setFollowupResponse
- SurveyClassNames.freeformInput → followupInput
- CSS .ck-reason-freeform → .ck-reason-followup
- SessionPayload: add followupResponse; surveyChoiceValue is now always
  the static reason label rather than dual-use for typed text

ReasonConfig.freeform stays as the discriminator — only naming downstream
of it moves.
---
 packages/react/src/components/cancel-flow.tsx |  4 ++--
 .../src/components/steps/default-survey.tsx   | 14 +++++------
 packages/react/src/core/api.ts                |  2 ++
 packages/react/src/core/machine.ts            | 23 ++++++++++---------
 packages/react/src/core/types.ts              | 12 +++++-----
 .../react/src/headless/use-cancel-flow.ts     |  2 +-
 packages/react/src/styles/cancel-flow.css     |  4 ++--
 packages/react/tests/core/machine.test.ts     | 16 ++++++-------
 8 files changed, 40 insertions(+), 37 deletions(-)

diff --git a/packages/react/src/components/cancel-flow.tsx b/packages/react/src/components/cancel-flow.tsx
index 90df69d..5a563f7 100644
--- a/packages/react/src/components/cancel-flow.tsx
+++ b/packages/react/src/components/cancel-flow.tsx
@@ -190,8 +190,8 @@ function StepRenderer({
           reasons={machine.reasons}
           selectedReason={state.selectedReason}
           onSelectReason={machine.selectReason}
-          freeformText={state.freeformText}
-          onFreeformChange={machine.setFreeformText}
+          followupResponse={state.followupResponse}
+          onFollowupResponseChange={machine.setFollowupResponse}
           onNext={machine.next}
           classNames={config?.classNames}
           components={components}
diff --git a/packages/react/src/components/steps/default-survey.tsx b/packages/react/src/components/steps/default-survey.tsx
index a0bdbd5..5d4df8f 100644
--- a/packages/react/src/components/steps/default-survey.tsx
+++ b/packages/react/src/components/steps/default-survey.tsx
@@ -30,8 +30,8 @@ export function DefaultSurvey({
   reasons,
   selectedReason,
   onSelectReason,
-  freeformText,
-  onFreeformChange,
+  followupResponse,
+  onFollowupResponseChange,
   onNext,
   classNames,
   components,
@@ -39,7 +39,7 @@ export function DefaultSurvey({
   const ReasonButton = components?.ReasonButton ?? DefaultReasonButton
   const listRef = useRef<HTMLDivElement>(null)
   const selected = reasons.find((r) => r.id === selectedReason)
-  const showFreeform = selected?.freeform === true
+  const showFollowup = selected?.freeform === true
 
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -84,13 +84,13 @@ export function DefaultSurvey({
         ))}
       </div>
 
-      {showFreeform && (
+      {showFollowup && (
         <textarea
-          className={cn('ck-reason-freeform', classNames?.freeformInput)}
+          className={cn('ck-reason-followup', classNames?.followupInput)}
           placeholder="Tell us more (optional)"
           rows={3}
-          value={freeformText}
-          onChange={(e) => onFreeformChange(e.target.value)}
+          value={followupResponse}
+          onChange={(e) => onFollowupResponseChange(e.target.value)}
           aria-label="Additional detail"
         />
       )}
diff --git a/packages/react/src/core/api.ts b/packages/react/src/core/api.ts
index 3553ad9..d155fe6 100644
--- a/packages/react/src/core/api.ts
+++ b/packages/react/src/core/api.ts
@@ -77,6 +77,8 @@ export interface SessionPayload {
   aborted?: boolean
   surveyChoiceId?: string
   surveyChoiceValue?: string
+  /** Free-text from a `freeform: true` reason. The reason's static `label` still travels on `surveyChoiceValue`. */
+  followupResponse?: string
   feedback?: string
   acceptedOffer?: AcceptedOfferPayload
   presentedOffers?: PresentedOffer[]
diff --git a/packages/react/src/core/machine.ts b/packages/react/src/core/machine.ts
index f97b83f..8f4c291 100644
--- a/packages/react/src/core/machine.ts
+++ b/packages/react/src/core/machine.ts
@@ -311,12 +311,12 @@ export class CancelFlowMachine {
 
   selectReason = (id: string): void => {
     if (!this.reasons.find((r) => r.id === id)) return
-    // Clear freeform text on reason change so it doesn't carry across selections.
-    this.setState({ selectedReason: id, freeformText: '' })
+    // Clear follow-up text on reason change so it doesn't carry across selections.
+    this.setState({ selectedReason: id, followupResponse: '' })
   }
 
-  setFreeformText = (text: string): void => {
-    this.setState({ freeformText: text })
+  setFollowupResponse = (text: string): void => {
+    this.setState({ followupResponse: text })
   }
 
   next = (result?: Record<string, unknown>): void => {
@@ -460,7 +460,7 @@ export class CancelFlowMachine {
       step: first?.type ?? 'survey',
       currentStepId: this.graph.firstStepId,
       selectedReason: null,
-      freeformText: '',
+      followupResponse: '',
       feedback: '',
       outcome: null,
       isProcessing: false,
@@ -636,17 +636,18 @@ export class CancelFlowMachine {
 
   private buildBasePayload(): SessionPayload {
     const selectedReason = this.reasons.find((r) => r.id === this.state.selectedReason)
-    // For freeform reasons, the typed text replaces the static label as
-    // surveyChoiceValue. surveyChoiceId still carries the reason id so
-    // analytics groupings hold.
-    const surveyChoiceValue =
-      selectedReason?.freeform && this.state.freeformText ? this.state.freeformText : selectedReason?.label
+    // surveyChoiceValue is always the static label so dashboard groupings
+    // by reason stay stable. Typed text from `freeform: true` reasons
+    // travels separately on followupResponse, mirroring the embed payload.
+    const followupResponse =
+      selectedReason?.freeform && this.state.followupResponse ? this.state.followupResponse : undefined
     const payload: SessionPayload = {
       blueprintId: this.blueprintId ?? undefined,
       customer: this.resolveSessionCustomer(),
       canceled: false,
       surveyChoiceId: this.state.selectedReason ?? undefined,
-      surveyChoiceValue,
+      surveyChoiceValue: selectedReason?.label,
+      followupResponse,
       feedback: this.state.feedback || undefined,
       presentedOffers: this.presentedOffers,
       stepsViewed: this.stepsViewed,
diff --git a/packages/react/src/core/types.ts b/packages/react/src/core/types.ts
index 11cf669..a7f80aa 100644
--- a/packages/react/src/core/types.ts
+++ b/packages/react/src/core/types.ts
@@ -295,7 +295,7 @@ export interface SurveyClassNames {
   reasonButton?: string
   reasonButtonSelected?: string
   reasonLabel?: string
-  freeformInput?: string
+  followupInput?: string
   continueButton?: string
 }
 
@@ -513,10 +513,10 @@ export interface SurveyStepProps {
   reasons: ReasonConfig[]
   selectedReason: string | null
   onSelectReason: (id: string) => void
-  /** Free-text value when the selected reason has `freeform: true`. */
-  freeformText: string
-  /** Set the freeform text. The SDK forwards the value to the session. */
-  onFreeformChange: (text: string) => void
+  /** Free-text value when the selected reason has `freeform: true`. Lands on the session as `followupResponse`. */
+  followupResponse: string
+  /** Set the follow-up response. The SDK forwards the value to the session. */
+  onFollowupResponseChange: (text: string) => void
   onNext: () => void
   classNames?: SurveyClassNames
   components?: Partial<ComponentOverrides>
@@ -600,7 +600,7 @@ export interface FlowState {
   step: string
   currentStepId: string
   selectedReason: string | null
-  freeformText: string
+  followupResponse: string
   feedback: string
   outcome: 'saved' | 'cancelled' | null
   isProcessing: boolean
diff --git a/packages/react/src/headless/use-cancel-flow.ts b/packages/react/src/headless/use-cancel-flow.ts
index 414f7fc..3a6e823 100644
--- a/packages/react/src/headless/use-cancel-flow.ts
+++ b/packages/react/src/headless/use-cancel-flow.ts
@@ -15,7 +15,7 @@ export function useCancelFlow(config: FlowConfig) {
     stepIndex: machine.stepIndex,
     totalSteps: machine.totalSteps,
     selectReason: machine.selectReason,
-    setFreeformText: machine.setFreeformText,
+    setFollowupResponse: machine.setFollowupResponse,
     setFeedback: machine.setFeedback,
     accept: machine.accept,
     decline: machine.decline,
diff --git a/packages/react/src/styles/cancel-flow.css b/packages/react/src/styles/cancel-flow.css
index 244e787..cc377e7 100644
--- a/packages/react/src/styles/cancel-flow.css
+++ b/packages/react/src/styles/cancel-flow.css
@@ -347,7 +347,7 @@
   margin-bottom: 20px;
 }
 
-.ck-cancel-flow .ck-reason-freeform {
+.ck-cancel-flow .ck-reason-followup {
   width: 100%;
   font-family: var(--ck-font);
   font-size: 14px;
@@ -361,7 +361,7 @@
   min-height: 72px;
 }
 
-.ck-cancel-flow .ck-reason-freeform:focus {
+.ck-cancel-flow .ck-reason-followup:focus {
   outline: none;
   border-color: var(--ck-color-primary);
 }
diff --git a/packages/react/tests/core/machine.test.ts b/packages/react/tests/core/machine.test.ts
index de5be49..d4a9b3b 100644
--- a/packages/react/tests/core/machine.test.ts
+++ b/packages/react/tests/core/machine.test.ts
@@ -1703,23 +1703,23 @@ describe('CancelFlowMachine', () => {
       ],
     }
 
-    it('initial freeformText is empty', () => {
+    it('initial followupResponse is empty', () => {
       const machine = new CancelFlowMachine(withFreeform)
-      expect(machine.getSnapshot().freeformText).toBe('')
+      expect(machine.getSnapshot().followupResponse).toBe('')
     })
 
-    it('setFreeformText updates state', () => {
+    it('setFollowupResponse updates state', () => {
       const machine = new CancelFlowMachine(withFreeform)
-      machine.setFreeformText('Switching to a competitor')
-      expect(machine.getSnapshot().freeformText).toBe('Switching to a competitor')
+      machine.setFollowupResponse('Switching to a competitor')
+      expect(machine.getSnapshot().followupResponse).toBe('Switching to a competitor')
     })
 
-    it('resets freeformText when switching reasons', () => {
+    it('resets followupResponse when switching reasons', () => {
       const machine = new CancelFlowMachine(withFreeform)
       machine.selectReason('other')
-      machine.setFreeformText('typed something')
+      machine.setFollowupResponse('typed something')
       machine.selectReason('expensive')
-      expect(machine.getSnapshot().freeformText).toBe('')
+      expect(machine.getSnapshot().followupResponse).toBe('')
     })
   })
 

From 0cde5afaa4fe9e887d904ad919665199e23921b6 Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Tue, 19 May 2026 12:54:54 -0400
Subject: [PATCH 3/4] default offer copy on standalone offers

---
 packages/react/src/core/merge-fields.ts        | 18 +++++++++++++++---
 packages/react/src/core/step-graph.ts          | 13 ++++++++++---
 packages/react/src/core/types.ts               |  8 ++++----
 packages/react/tests/core/merge-fields.test.ts |  7 +++++--
 4 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/packages/react/src/core/merge-fields.ts b/packages/react/src/core/merge-fields.ts
index 8d3b1b0..fbf4941 100644
--- a/packages/react/src/core/merge-fields.ts
+++ b/packages/react/src/core/merge-fields.ts
@@ -5,7 +5,16 @@
 // as their text content, so the wrapper is transparent and only the inner
 // `{{…}}` needs substitution.
 
-import type { DirectCustomer, FeedbackStep, OfferDecision, OfferStep, ReasonConfig, Step, SurveyStep } from './types'
+import type {
+  DirectCustomer,
+  FeedbackStep,
+  OfferConfig,
+  OfferDecision,
+  OfferStep,
+  ReasonConfig,
+  Step,
+  SurveyStep,
+} from './types'
 
 export type MergeAttrs = Record<string, string>
 
@@ -78,7 +87,7 @@ function mergeStep(step: Step, attrs: MergeAttrs): Step {
         ...s,
         title: maybeMerge(s.title, attrs),
         description: maybeMerge(s.description, attrs),
-        offer: s.offer ? mergeOfferDecision(s.offer, attrs) : undefined,
+        offer: s.offer ? mergeOffer(s.offer, attrs) : undefined,
       }
     }
     case 'feedback': {
@@ -105,7 +114,10 @@ function mergeReason(r: ReasonConfig, attrs: MergeAttrs): ReasonConfig {
   return { ...r, label: applyMergeFields(r.label, attrs) }
 }
 
-function mergeOfferDecision(o: OfferDecision, attrs: MergeAttrs): OfferDecision {
+// Standalone OfferSteps may arrive without copy (the step graph synthesizes
+// defaults later); merging copy is a no-op when there's nothing to merge.
+function mergeOffer(o: OfferConfig | OfferDecision, attrs: MergeAttrs): OfferConfig | OfferDecision {
+  if (!('copy' in o)) return o
   return {
     ...o,
     copy: {
diff --git a/packages/react/src/core/step-graph.ts b/packages/react/src/core/step-graph.ts
index dec64bb..c51888a 100644
--- a/packages/react/src/core/step-graph.ts
+++ b/packages/react/src/core/step-graph.ts
@@ -80,7 +80,7 @@ export function buildStepGraph(
 ): StepGraph {
   if (steps.length === 0) return EMPTY_GRAPH
 
-  const resolved = steps.map((step, i) => normalizeStep(step, i))
+  const resolved = steps.map((step, i) => normalizeStep(step, i, defaultOfferCopy))
   linkNeighbors(resolved)
 
   const stepMap: Record<string, ResolvedStep> = {}
@@ -117,7 +117,11 @@ export function buildStepGraph(
   }
 }
 
-function normalizeStep(step: Step, index: number): ResolvedStep {
+function normalizeStep(
+  step: Step,
+  index: number,
+  defaultOfferCopy: (offer: OfferConfig) => OfferDecision['copy'],
+): ResolvedStep {
   // Prefer the caller-provided guid; otherwise generate a stable slug. Stable
   // ids matter for analytics and React keys.
   const guid = (step as { guid?: string }).guid ?? `step-${index}-${step.type}`
@@ -141,7 +145,10 @@ function normalizeStep(step: Step, index: number): ResolvedStep {
         ...base,
         title: s.title,
         description: s.description,
-        offer: s.offer,
+        // Standalone offers may arrive without `copy` — toDecision fills it
+        // in from defaultOfferCopy. Token-mode offers already carry copy
+        // from the server, so toDecision passes them through unchanged.
+        offer: s.offer ? toDecision(s.offer, defaultOfferCopy) : undefined,
         classNames: s.classNames,
       }
     }
diff --git a/packages/react/src/core/types.ts b/packages/react/src/core/types.ts
index a7f80aa..7a77b9d 100644
--- a/packages/react/src/core/types.ts
+++ b/packages/react/src/core/types.ts
@@ -229,11 +229,11 @@ export interface OfferStep {
   description?: string
   /**
    * Offer attached to this step. Set this to declare a standalone offer
-   * step (one that isn't routed from a survey reason). The SDK also
-   * populates this automatically on synthetic offer steps spawned from
-   * survey choices.
+   * step (one that isn't routed from a survey reason). `copy` is optional —
+   * the SDK synthesizes default copy from the offer config when none is
+   * provided, the same way it does for survey-attached offers.
    */
-  offer?: OfferDecision
+  offer?: OfferConfig | OfferDecision
   classNames?: OfferClassNames
 }
 
diff --git a/packages/react/tests/core/merge-fields.test.ts b/packages/react/tests/core/merge-fields.test.ts
index c1901ea..ecf83af 100644
--- a/packages/react/tests/core/merge-fields.test.ts
+++ b/packages/react/tests/core/merge-fields.test.ts
@@ -105,8 +105,11 @@ describe('applyMergeFieldsToSteps', () => {
     ]
     const [out] = applyMergeFieldsToSteps(steps, customer)
     const offerStep = out as Extract<Step, { type: 'offer' }>
-    expect(offerStep.offer?.copy.body).toBe('Jane, our support channel is ready')
-    expect(offerStep.offer?.copy.headline).toBe('Get in touch!')
+    // The fixture provides copy inline, so this is the decision-shape branch.
+    const offer = offerStep.offer
+    if (!offer || !('copy' in offer)) throw new Error('Expected offer with copy')
+    expect(offer.copy.body).toBe('Jane, our support channel is ready')
+    expect(offer.copy.headline).toBe('Get in touch!')
   })
 
   it('substitutes placeholders in survey reason labels', () => {

From 9b039a2c8db86720358a3bf7f8acece428b1c7bb Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Tue, 19 May 2026 13:17:39 -0400
Subject: [PATCH 4/4] clean: remove key down handler from survey

---
 .../src/components/steps/default-survey.tsx   | 31 +------------------
 1 file changed, 1 insertion(+), 30 deletions(-)

diff --git a/packages/react/src/components/steps/default-survey.tsx b/packages/react/src/components/steps/default-survey.tsx
index 5d4df8f..9699cb3 100644
--- a/packages/react/src/components/steps/default-survey.tsx
+++ b/packages/react/src/components/steps/default-survey.tsx
@@ -1,4 +1,3 @@
-import { useCallback, useRef } from 'react'
 import type { ReasonButtonProps, SurveyStepProps } from '../../core/types'
 import { cn } from '../../core/utils'
 import { RichText } from '../rich-text'
@@ -12,7 +11,6 @@ function DefaultReasonButton({ reason, index, isSelected, onSelect }: ReasonButt
       type="button"
       role="radio"
       aria-checked={isSelected}
-      tabIndex={isSelected ? 0 : -1}
       onClick={() => onSelect(reason.id)}
       className={cn('ck-reason-button', isSelected && 'ck-reason-button--selected')}
     >
@@ -37,42 +35,15 @@ export function DefaultSurvey({
   components,
 }: SurveyStepProps) {
   const ReasonButton = components?.ReasonButton ?? DefaultReasonButton
-  const listRef = useRef<HTMLDivElement>(null)
   const selected = reasons.find((r) => r.id === selectedReason)
   const showFollowup = selected?.freeform === true
 
-  const handleKeyDown = useCallback(
-    (e: React.KeyboardEvent) => {
-      if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return
-      e.preventDefault()
-
-      const currentIdx = reasons.findIndex((r) => r.id === selectedReason)
-      let nextIdx: number
-      if (e.key === 'ArrowDown') {
-        nextIdx = currentIdx < reasons.length - 1 ? currentIdx + 1 : 0
-      } else {
-        nextIdx = currentIdx > 0 ? currentIdx - 1 : reasons.length - 1
-      }
-      onSelectReason(reasons[nextIdx].id)
-
-      const buttons = listRef.current?.querySelectorAll<HTMLElement>('[role="radio"]')
-      buttons?.[nextIdx]?.focus()
-    },
-    [reasons, selectedReason, onSelectReason],
-  )
-
   return (
     <div className={cn('ck-step ck-step-survey', classNames?.root)}>
       <h2 className={cn('ck-step-title', classNames?.title)}>{title}</h2>
       {description && <RichText html={description} className={cn('ck-step-description', classNames?.description)} />}
 
-      <div
-        ref={listRef}
-        className={cn('ck-reason-list', classNames?.reasonList)}
-        role="radiogroup"
-        aria-label={title}
-        onKeyDown={handleKeyDown}
-      >
+      <div className={cn('ck-reason-list', classNames?.reasonList)} role="radiogroup" aria-label={title}>
         {reasons.map((reason, i) => (
           <ReasonButton
             key={reason.id}