From 055026ec2b53539eb8d86fd7753430f3f33cab16 Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Fri, 10 Jul 2026 11:36:54 -0400
Subject: [PATCH 1/4] Add i18n: typed message catalog, i18n prop, timing-aware
 copy

Every string the SDK renders itself now flows through a typed
CancelFlowMessages catalog instead of hardcoded literals. The new i18n
prop takes a locale plus deep-partial per-locale overrides; lookup runs
an exact -> base-language -> en fallback chain and empty-string
overrides are dropped so a blank field can't clobber a real string.

Timing-sensitive messages (confirm CTA, period-end notice, cancelled
success copy) accept { immediate, atPeriodEnd } pairs resolved against
the server's cancelAtPeriodEnd, which is now threaded from the token
config into FlowState. The period-end notice renders only when timing
is known to be period-end: an earlier hardcoded notice was removed
because it could contradict the merchant's setting, and that still
holds in local mode where the SDK can't verify billing behavior.

All new props are optional and default strings are unchanged, so
existing integrations render identically. Headless consumers get
messages and cancelAtPeriodEnd from useCancelFlow, plus an exported
selectTiming helper.
---
 packages/react/src/components/cancel-flow.tsx |  65 +++--
 .../src/components/steps/default-confirm.tsx  |  10 +-
 .../src/components/steps/default-feedback.tsx |   8 +-
 .../src/components/steps/default-success.tsx  |   6 +-
 .../src/components/steps/default-survey.tsx   |   9 +-
 .../steps/offer/default-contact-offer.tsx     |   5 +-
 .../steps/offer/default-discount-offer.tsx    |   7 +-
 .../steps/offer/default-pause-offer.tsx       |   9 +-
 .../steps/offer/default-plan-change-offer.tsx |   9 +-
 .../steps/offer/default-rebate-offer.tsx      |  16 +-
 .../offer/default-trial-extension-offer.tsx   |   9 +-
 .../structural/default-back-button.tsx        |   4 +-
 .../structural/default-close-button.tsx       |   4 +-
 packages/react/src/core/index.ts              |   2 +
 packages/react/src/core/machine.ts            |  13 +
 packages/react/src/core/messages.ts           | 261 ++++++++++++++++++
 packages/react/src/core/types.ts              |  37 +++
 packages/react/src/core/utils.ts              |  11 +-
 .../react/src/headless/use-cancel-flow.ts     |   1 +
 .../tests/components/cancel-flow.test.tsx     |  94 ++++++-
 packages/react/tests/core/machine.test.ts     |  49 ++++
 packages/react/tests/core/messages.test.ts    | 141 ++++++++++
 22 files changed, 716 insertions(+), 54 deletions(-)
 create mode 100644 packages/react/src/core/messages.ts
 create mode 100644 packages/react/tests/core/messages.test.ts

diff --git a/packages/react/src/components/cancel-flow.tsx b/packages/react/src/components/cancel-flow.tsx
index 5a563f7..8bd1fd6 100644
--- a/packages/react/src/components/cancel-flow.tsx
+++ b/packages/react/src/components/cancel-flow.tsx
@@ -1,5 +1,7 @@
 import { type ReactElement, useEffect } from 'react'
+import { formatPeriodEnd } from '../core/format'
 import type { CancelFlowMachine } from '../core/machine'
+import { type CancelFlowMessages, formatMessage, selectTiming } from '../core/messages'
 import type {
   CancelFlowProps,
   ComponentOverrides,
@@ -13,7 +15,7 @@ import type {
   SuccessStep,
   SurveyStep,
 } from '../core/types'
-import { appearanceToStyle, BUILT_IN_OFFER_TYPES, defaultTitles } from '../core/utils'
+import { appearanceToStyle, BUILT_IN_OFFER_TYPES } from '../core/utils'
 import { useCancelFlowMachine } from '../headless/use-cancel-flow-machine'
 import { DefaultConfirm } from './steps/default-confirm'
 import { DefaultFeedback } from './steps/default-feedback'
@@ -38,6 +40,7 @@ export function CancelFlow(props: CancelFlowProps) {
         isLoading={isLoading}
         loadError={loadError}
         onRetry={retry}
+        messages={machine.messages}
       />
     )
   }
@@ -62,6 +65,7 @@ function LoadStatus({
   isLoading,
   loadError,
   onRetry,
+  messages,
 }: {
   appearance?: CancelFlowProps['appearance']
   classNames?: CancelFlowProps['classNames']
@@ -70,6 +74,7 @@ function LoadStatus({
   isLoading: boolean
   loadError: Error | null
   onRetry: () => void
+  messages: CancelFlowMessages
 }) {
   const scheme = useColorScheme(appearance?.colorScheme)
   const appearanceStyle = appearanceToStyle(appearance)
@@ -80,7 +85,7 @@ function LoadStatus({
   return (
     <div className="ck-cancel-flow" data-color-scheme={scheme} style={appearanceStyle}>
       <Modal open={true} onClose={handleClose} className={classNames?.modal} overlayClassName={classNames?.overlay}>
-        <CloseButton onClose={handleClose} className={classNames?.closeButton} />
+        <CloseButton onClose={handleClose} className={classNames?.closeButton} label={messages.common.close} />
         <div className="ck-content">
           {isLoading && (
             <div className="ck-loading" style={{ padding: '32px', textAlign: 'center' }}>
@@ -96,13 +101,13 @@ function LoadStatus({
                   margin: '0 auto 16px',
                 }}
               />
-              <p style={{ color: 'var(--ck-color-text-secondary, #6b7280)' }}>Loading your options...</p>
+              <p style={{ color: 'var(--ck-color-text-secondary, #6b7280)' }}>{messages.common.loading}</p>
             </div>
           )}
           {loadError && (
             <div className="ck-error" role="alert" style={{ padding: '32px', textAlign: 'center' }}>
               <p className="ck-error-message" style={{ marginBottom: 16 }}>
-                We couldn't load your cancellation options. Please try again.
+                {messages.common.loadError}
               </p>
               <button
                 type="button"
@@ -119,7 +124,7 @@ function LoadStatus({
                   cursor: 'pointer',
                 }}
               >
-                Try again
+                {messages.common.tryAgain}
               </button>
             </div>
           )}
@@ -141,6 +146,7 @@ interface FlowShellProps {
 function FlowShell({ machine, state, appearance, classNames, components, customComponents }: FlowShellProps) {
   const scheme = useColorScheme(appearance?.colorScheme)
   const appearanceStyle = appearanceToStyle(appearance)
+  const messages = machine.messages
 
   const Modal = components?.Modal ?? DefaultModal
   const CloseButton = components?.CloseButton ?? DefaultCloseButton
@@ -149,12 +155,14 @@ 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} overlayClassName={classNames?.overlay}>
-        <CloseButton onClose={machine.close} className={classNames?.closeButton} />
+        <CloseButton onClose={machine.close} className={classNames?.closeButton} label={messages.common.close} />
         <div className="ck-content">
-          {machine.canGoBack && <BackButton onBack={machine.back} className={classNames?.backButton} />}
+          {machine.canGoBack && (
+            <BackButton onBack={machine.back} className={classNames?.backButton} label={messages.common.back} />
+          )}
           {state.error && (
             <div className="ck-error" role="alert">
-              <p className="ck-error-message">Something went wrong. Please try again.</p>
+              <p className="ck-error-message">{messages.common.error}</p>
             </div>
           )}
           <StepRenderer state={state} machine={machine} components={components} customComponents={customComponents} />
@@ -176,6 +184,7 @@ function StepRenderer({
   customComponents?: CustomComponents
 }) {
   const stepConfig = machine.currentStep
+  const messages = machine.messages
 
   switch (state.step) {
     case 'survey': {
@@ -183,7 +192,7 @@ function StepRenderer({
       const config = stepConfig as SurveyStep | undefined
       return (
         <Survey
-          title={config?.title ?? defaultTitles.survey}
+          title={config?.title ?? messages.survey.title}
           description={config?.description}
           customer={state.customer}
           subscriptions={state.subscriptions}
@@ -195,6 +204,7 @@ function StepRenderer({
           onNext={machine.next}
           classNames={config?.classNames}
           components={components}
+          messages={messages}
         />
       )
     }
@@ -234,6 +244,7 @@ function StepRenderer({
           isProcessing={state.isProcessing}
           classNames={config?.classNames}
           components={components}
+          messages={messages}
         />
       )
     }
@@ -243,7 +254,7 @@ function StepRenderer({
       const config = stepConfig as FeedbackStep | undefined
       return (
         <Feedback
-          title={config?.title ?? defaultTitles.feedback}
+          title={config?.title ?? messages.feedback.title}
           description={config?.description}
           customer={state.customer}
           subscriptions={state.subscriptions}
@@ -254,6 +265,7 @@ function StepRenderer({
           onChange={machine.setFeedback}
           onSubmit={machine.next}
           classNames={config?.classNames}
+          messages={messages}
         />
       )
     }
@@ -263,18 +275,20 @@ function StepRenderer({
       const config = stepConfig as ConfirmStep | undefined
       return (
         <Confirm
-          title={config?.title ?? defaultTitles.confirm}
+          title={config?.title ?? messages.confirm.title}
           description={config?.description}
           customer={state.customer}
           subscriptions={state.subscriptions}
           losses={config?.losses}
           lossesLabel={config?.lossesLabel}
-          confirmLabel={config?.confirmLabel ?? 'Cancel subscription'}
-          goBackLabel={config?.goBackLabel ?? 'Go back'}
+          confirmLabel={config?.confirmLabel ?? selectTiming(messages.confirm.cta, state.cancelAtPeriodEnd)}
+          goBackLabel={config?.goBackLabel ?? messages.confirm.goBack}
+          periodEndNotice={resolvePeriodEndNotice(state, messages)}
           onConfirm={machine.cancel}
           onGoBack={machine.back}
           isProcessing={state.isProcessing}
           classNames={config?.classNames}
+          messages={messages}
         />
       )
     }
@@ -288,17 +302,21 @@ function StepRenderer({
           outcome={state.outcome ?? 'cancelled'}
           offer={machine.currentOffer ?? undefined}
           title={
-            isSaved ? (config?.savedTitle ?? 'Welcome back!') : (config?.cancelledTitle ?? 'Subscription cancelled')
+            isSaved
+              ? (config?.savedTitle ?? messages.success.saved.title)
+              : (config?.cancelledTitle ?? selectTiming(messages.success.cancelled.title, state.cancelAtPeriodEnd))
           }
           description={
             isSaved
-              ? (config?.savedDescription ?? 'Your offer has been applied.')
-              : (config?.cancelledDescription ?? "We're sorry to see you go.")
+              ? (config?.savedDescription ?? messages.success.saved.description)
+              : (config?.cancelledDescription ??
+                selectTiming(messages.success.cancelled.description, state.cancelAtPeriodEnd))
           }
           customer={state.customer}
           subscriptions={state.subscriptions}
           onClose={machine.close}
           classNames={config?.classNames}
+          messages={messages}
         />
       )
     }
@@ -330,6 +348,21 @@ function StepRenderer({
   }
 }
 
+// The notice makes a factual claim about billing behavior, so it requires the
+// timing to be KNOWN to be period-end — the server-resolved value in token
+// mode. `null` (local mode) stays silent: an earlier hardcoded version of this
+// notice was removed precisely because it could contradict the merchant's
+// actual setting. Also empty when the period end can't be determined or the
+// resolved message is blank.
+function resolvePeriodEndNotice(state: FlowState, messages: CancelFlowMessages): string | undefined {
+  if (state.cancelAtPeriodEnd !== true) return undefined
+  const template = selectTiming(messages.confirm.periodEndNotice, state.cancelAtPeriodEnd)
+  if (!template) return undefined
+  const periodEnd = formatPeriodEnd(state.subscriptions)
+  if (!periodEnd) return undefined
+  return formatMessage(template, { periodEnd })
+}
+
 // Skip runs in an effect so we don't mutate machine state during render.
 function UnregisteredStepFallback({ step, onSkip }: { step: string; onSkip: () => void }) {
   useEffect(() => {
diff --git a/packages/react/src/components/steps/default-confirm.tsx b/packages/react/src/components/steps/default-confirm.tsx
index 4daeae0..05a858f 100644
--- a/packages/react/src/components/steps/default-confirm.tsx
+++ b/packages/react/src/components/steps/default-confirm.tsx
@@ -1,3 +1,4 @@
+import { defaultMessages } from '../../core/messages'
 import type { ConfirmStepProps } from '../../core/types'
 import { cn } from '../../core/utils'
 import { RichText } from '../rich-text'
@@ -9,11 +10,14 @@ export function DefaultConfirm({
   lossesLabel,
   confirmLabel,
   goBackLabel,
+  periodEndNotice,
   onConfirm,
   onGoBack,
   isProcessing,
   classNames,
+  messages,
 }: ConfirmStepProps) {
+  const m = messages ?? defaultMessages
   const hasLosses = Array.isArray(losses) && losses.length > 0
   return (
     <div className={cn('ck-step ck-step-confirm', classNames?.root)}>
@@ -24,7 +28,7 @@ export function DefaultConfirm({
 
       {hasLosses && (
         <div className={cn('ck-loss-block', classNames?.lossList)}>
-          <div className={cn('ck-loss-label', classNames?.lossLabel)}>{lossesLabel ?? "You'll lose access to:"}</div>
+          <div className={cn('ck-loss-label', classNames?.lossLabel)}>{lossesLabel ?? m.confirm.lossesLabel}</div>
           <ul className="ck-loss-list">
             {losses.map((item) => (
               <li key={item} className={cn('ck-loss-item', classNames?.lossItem)}>
@@ -38,13 +42,15 @@ export function DefaultConfirm({
         </div>
       )}
 
+      {periodEndNotice && <p className={cn('ck-period-end', classNames?.periodEndNotice)}>{periodEndNotice}</p>}
+
       <button
         type="button"
         className={cn('ck-button ck-button-danger', classNames?.confirmButton)}
         onClick={onConfirm}
         disabled={isProcessing}
       >
-        {isProcessing ? 'Processing...' : confirmLabel}
+        {isProcessing ? m.common.processing : confirmLabel}
       </button>
       <button type="button" className={cn('ck-button-link', classNames?.goBackButton)} onClick={onGoBack}>
         {goBackLabel}
diff --git a/packages/react/src/components/steps/default-feedback.tsx b/packages/react/src/components/steps/default-feedback.tsx
index d736c22..a9b6239 100644
--- a/packages/react/src/components/steps/default-feedback.tsx
+++ b/packages/react/src/components/steps/default-feedback.tsx
@@ -1,4 +1,5 @@
 import { useState } from 'react'
+import { defaultMessages, formatMessage } from '../../core/messages'
 import type { FeedbackStepProps } from '../../core/types'
 import { cn } from '../../core/utils'
 import { RichText } from '../rich-text'
@@ -13,12 +14,15 @@ export function DefaultFeedback({
   onChange,
   onSubmit,
   classNames,
+  messages,
 }: FeedbackStepProps) {
+  const m = messages ?? defaultMessages
   const [focused, setFocused] = useState(false)
   const hasMin = minLength > 0
   const isUnderMin = hasMin && value.length > 0 && value.length < minLength
   const isValid = !required || value.length >= minLength
-  const placeholderText = placeholder ?? (hasMin ? `At least ${minLength} characters…` : 'Type your thoughts…')
+  const placeholderText =
+    placeholder ?? (hasMin ? formatMessage(m.feedback.placeholderWithMin, { minLength }) : m.feedback.placeholder)
 
   return (
     <div className={cn('ck-step ck-step-feedback', classNames?.root)}>
@@ -62,7 +66,7 @@ export function DefaultFeedback({
         onClick={onSubmit}
         disabled={!isValid}
       >
-        Continue
+        {m.common.continue}
       </button>
     </div>
   )
diff --git a/packages/react/src/components/steps/default-success.tsx b/packages/react/src/components/steps/default-success.tsx
index df27fe1..aed8dd6 100644
--- a/packages/react/src/components/steps/default-success.tsx
+++ b/packages/react/src/components/steps/default-success.tsx
@@ -1,9 +1,11 @@
+import { defaultMessages } from '../../core/messages'
 import type { SuccessStepProps } from '../../core/types'
 import { cn } from '../../core/utils'
 import { RichText } from '../rich-text'
 import { Checkmark } from './shared'
 
-export function DefaultSuccess({ title, description, onClose, classNames }: SuccessStepProps) {
+export function DefaultSuccess({ title, description, onClose, classNames, messages }: SuccessStepProps) {
+  const m = messages ?? defaultMessages
   return (
     <div className={cn('ck-step ck-step-success', classNames?.root)}>
       <div className={cn('ck-success-icon', classNames?.icon)}>
@@ -17,7 +19,7 @@ export function DefaultSuccess({ title, description, onClose, classNames }: Succ
 
       <div className="ck-success-actions">
         <button type="button" className={cn('ck-button ck-button-primary', classNames?.closeButton)} onClick={onClose}>
-          Done
+          {m.common.done}
         </button>
       </div>
     </div>
diff --git a/packages/react/src/components/steps/default-survey.tsx b/packages/react/src/components/steps/default-survey.tsx
index 7888256..bd1c921 100644
--- a/packages/react/src/components/steps/default-survey.tsx
+++ b/packages/react/src/components/steps/default-survey.tsx
@@ -1,3 +1,4 @@
+import { defaultMessages } from '../../core/messages'
 import type { ReasonButtonProps, SurveyStepProps } from '../../core/types'
 import { cn } from '../../core/utils'
 import { RichText } from '../rich-text'
@@ -33,7 +34,9 @@ export function DefaultSurvey({
   onNext,
   classNames,
   components,
+  messages,
 }: SurveyStepProps) {
+  const m = messages ?? defaultMessages
   const ReasonButton = components?.ReasonButton ?? DefaultReasonButton
   const selected = reasons.find((r) => r.id === selectedReason)
   const showFollowup = selected?.freeform === true
@@ -60,11 +63,11 @@ export function DefaultSurvey({
       {showFollowup && (
         <textarea
           className={cn('ck-reason-followup', classNames?.followupInput)}
-          placeholder="Tell us more (optional)"
+          placeholder={m.survey.followupPlaceholder}
           rows={3}
           value={followupResponse}
           onChange={(e) => onFollowupResponseChange(e.target.value)}
-          aria-label="Additional detail"
+          aria-label={m.survey.followupAriaLabel}
         />
       )}
 
@@ -74,7 +77,7 @@ export function DefaultSurvey({
         onClick={onNext}
         disabled={!selectedReason}
       >
-        Continue
+        {m.common.continue}
       </button>
     </div>
   )
diff --git a/packages/react/src/components/steps/offer/default-contact-offer.tsx b/packages/react/src/components/steps/offer/default-contact-offer.tsx
index 4bbc294..38d3c77 100644
--- a/packages/react/src/components/steps/offer/default-contact-offer.tsx
+++ b/packages/react/src/components/steps/offer/default-contact-offer.tsx
@@ -1,3 +1,4 @@
+import { defaultMessages } from '../../../core/messages'
 import type { OfferStepProps } from '../../../core/types'
 import { cn } from '../../../core/utils'
 import { RichText } from '../../rich-text'
@@ -14,7 +15,9 @@ export function DefaultContactOffer({
   onDecline,
   isProcessing,
   classNames,
+  messages,
 }: OfferStepProps) {
+  const msg = messages ?? defaultMessages
   const headline = title ?? offer.copy.headline
   const body = description ?? offer.copy.body
 
@@ -30,7 +33,7 @@ export function DefaultContactOffer({
           onClick={() => onAccept()}
           disabled={isProcessing}
         >
-          {isProcessing ? 'Processing...' : offer.copy.cta}
+          {isProcessing ? msg.common.processing : offer.copy.cta}
         </button>
         <button type="button" className={cn('ck-button-link', classNames?.declineButton)} onClick={onDecline}>
           {offer.copy.declineCta}
diff --git a/packages/react/src/components/steps/offer/default-discount-offer.tsx b/packages/react/src/components/steps/offer/default-discount-offer.tsx
index 82a5758..81bdccd 100644
--- a/packages/react/src/components/steps/offer/default-discount-offer.tsx
+++ b/packages/react/src/components/steps/offer/default-discount-offer.tsx
@@ -1,4 +1,5 @@
 import { discountPhrase } from '../../../core/format'
+import { defaultMessages } from '../../../core/messages'
 import type { OfferDecision, OfferStepProps } from '../../../core/types'
 import { cn } from '../../../core/utils'
 import { RichText } from '../../rich-text'
@@ -11,7 +12,9 @@ export function DefaultDiscountOffer({
   onDecline,
   isProcessing,
   classNames,
+  messages,
 }: OfferStepProps) {
+  const msg = messages ?? defaultMessages
   const o = offer as OfferDecision & {
     percentOff?: number
     amountOff?: number
@@ -29,7 +32,7 @@ export function DefaultDiscountOffer({
 
       <div className={cn('ck-offer-card', classNames?.card)}>
         <div className="ck-offer-details ck-offer-discount">
-          <div className="ck-offer-discount-eyebrow">Limited-time offer</div>
+          <div className="ck-offer-discount-eyebrow">{msg.offer.limitedTimeEyebrow}</div>
           <div className="ck-offer-discount-phrase">{phrase}</div>
         </div>
         <button
@@ -38,7 +41,7 @@ export function DefaultDiscountOffer({
           onClick={() => onAccept()}
           disabled={isProcessing}
         >
-          {isProcessing ? 'Processing...' : offer.copy.cta}
+          {isProcessing ? msg.common.processing : offer.copy.cta}
         </button>
         <button type="button" className={cn('ck-button-link', classNames?.declineButton)} onClick={onDecline}>
           {offer.copy.declineCta}
diff --git a/packages/react/src/components/steps/offer/default-pause-offer.tsx b/packages/react/src/components/steps/offer/default-pause-offer.tsx
index e644aa3..f87eaaf 100644
--- a/packages/react/src/components/steps/offer/default-pause-offer.tsx
+++ b/packages/react/src/components/steps/offer/default-pause-offer.tsx
@@ -1,5 +1,6 @@
 import { useState } from 'react'
 import { formatMonthDayLong } from '../../../core/format'
+import { defaultMessages } from '../../../core/messages'
 import type { OfferDecision, OfferStepProps } from '../../../core/types'
 import { cn } from '../../../core/utils'
 import { RichText } from '../../rich-text'
@@ -12,7 +13,9 @@ export function DefaultPauseOffer({
   onDecline,
   isProcessing,
   classNames,
+  messages,
 }: OfferStepProps) {
+  const msg = messages ?? defaultMessages
   const o = offer as OfferDecision & { months: number }
   const max = Math.max(1, o.months)
   const [months, setMonths] = useState<number>(1)
@@ -30,7 +33,7 @@ export function DefaultPauseOffer({
       {body && <RichText as="div" html={body} className={cn('ck-step-description', classNames?.description)} />}
 
       <div className={cn('ck-offer-card ck-pause-card', classNames?.card)}>
-        <div className="ck-pause-eyebrow">We&apos;ll see you back on</div>
+        <div className="ck-pause-eyebrow">{msg.offer.pauseEyebrow}</div>
         <div className="ck-pause-date">{resumeDate}</div>
         {max > 1 && (
           <div className={cn('ck-pause-chips', classNames?.pauseSlider)}>
@@ -42,7 +45,7 @@ export function DefaultPauseOffer({
                 className={cn('ck-pause-chip', m === months && 'ck-pause-chip--selected')}
                 aria-pressed={m === months}
               >
-                {m} {m === 1 ? 'month' : 'months'}
+                {m} {m === 1 ? msg.common.month : msg.common.months}
               </button>
             ))}
           </div>
@@ -54,7 +57,7 @@ export function DefaultPauseOffer({
         onClick={() => onAccept({ months })}
         disabled={isProcessing}
       >
-        {isProcessing ? 'Processing...' : offer.copy.cta}
+        {isProcessing ? msg.common.processing : offer.copy.cta}
       </button>
       <button type="button" className={cn('ck-button-link', classNames?.declineButton)} onClick={onDecline}>
         {offer.copy.declineCta}
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 cf5a8d4..7362b62 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
@@ -1,5 +1,6 @@
 import { useState } from 'react'
 import { formatPriceFromMinor } from '../../../core/format'
+import { defaultMessages, formatMessage } from '../../../core/messages'
 import type { OfferDecision, OfferStepProps, PlanOption } from '../../../core/types'
 import { cn } from '../../../core/utils'
 import { RichText } from '../../rich-text'
@@ -14,7 +15,9 @@ export function DefaultPlanChangeOffer({
   onDecline,
   isProcessing,
   classNames,
+  messages,
 }: OfferStepProps) {
+  const msg = messages ?? defaultMessages
   const o = offer as OfferDecision & { plans?: PlanOption[] }
   const plans = o.plans ?? []
   // Mark the customer's current plan via their first subscription's first
@@ -27,9 +30,9 @@ export function DefaultPlanChangeOffer({
   const headline = title ?? offer.copy.headline
   const body = description ?? offer.copy.body
   const ctaLabel = isProcessing
-    ? 'Processing...'
+    ? msg.common.processing
     : selectedPlan?.name
-      ? `Switch to ${selectedPlan.name}`
+      ? formatMessage(msg.offer.switchToCta, { planName: selectedPlan.name })
       : offer.copy.cta
 
   return (
@@ -60,7 +63,7 @@ export function DefaultPlanChangeOffer({
               >
                 <div className="ck-plan-name">
                   {plan.name ?? plan.id}
-                  {isCurrent && <span className="ck-plan-current-badge">Current</span>}
+                  {isCurrent && <span className="ck-plan-current-badge">{msg.offer.currentPlanBadge}</span>}
                 </div>
                 {plan.tagline && <div className="ck-plan-tagline">{plan.tagline}</div>}
 
diff --git a/packages/react/src/components/steps/offer/default-rebate-offer.tsx b/packages/react/src/components/steps/offer/default-rebate-offer.tsx
index e898321..03f044e 100644
--- a/packages/react/src/components/steps/offer/default-rebate-offer.tsx
+++ b/packages/react/src/components/steps/offer/default-rebate-offer.tsx
@@ -1,4 +1,5 @@
 import { formatPriceFromMinor } from '../../../core/format'
+import { defaultMessages, formatMessage } from '../../../core/messages'
 import type { OfferDecision, OfferStepProps } from '../../../core/types'
 import { cn } from '../../../core/utils'
 import { RichText } from '../../rich-text'
@@ -18,7 +19,9 @@ export function DefaultRebateOffer({
   onDecline,
   isProcessing,
   classNames,
+  messages,
 }: OfferStepProps) {
+  const msg = messages ?? defaultMessages
   const o = offer as RebateDecision
   const headline = title ?? offer.copy.headline
   const body = description ?? offer.copy.body
@@ -40,22 +43,25 @@ export function DefaultRebateOffer({
         <div className="ck-offer-rebate">
           {o.amountPaidMinor != null && (
             <div className="ck-offer-rebate-row">
-              <span>You paid this period</span>
+              <span>{msg.offer.rebate.paidLabel}</span>
               <span>{formatPriceFromMinor(o.amountPaidMinor, currency)}</span>
             </div>
           )}
           <div className="ck-offer-rebate-row ck-offer-rebate-credit">
             <span>
-              Money back
+              {msg.offer.rebate.moneyBackLabel}
               {taxRefunded > 0 && (
-                <span className="ck-offer-rebate-tax"> (incl. {formatPriceFromMinor(taxRefunded, currency)} tax)</span>
+                <span className="ck-offer-rebate-tax">
+                  {' '}
+                  {formatMessage(msg.offer.rebate.inclTax, { amount: formatPriceFromMinor(taxRefunded, currency) })}
+                </span>
               )}
             </span>
             <span>−{formatPriceFromMinor(refund, currency)}</span>
           </div>
           {o.netAfterRebateMinor != null && (
             <div className="ck-offer-rebate-row ck-offer-rebate-total">
-              <span>Your net for this period</span>
+              <span>{msg.offer.rebate.netLabel}</span>
               <span>{formatPriceFromMinor(o.netAfterRebateMinor, currency)}</span>
             </div>
           )}
@@ -67,7 +73,7 @@ export function DefaultRebateOffer({
           onClick={() => onAccept()}
           disabled={isProcessing}
         >
-          {isProcessing ? 'Processing...' : offer.copy.cta}
+          {isProcessing ? msg.common.processing : offer.copy.cta}
         </button>
         <button type="button" className={cn('ck-button-link', classNames?.declineButton)} onClick={onDecline}>
           {offer.copy.declineCta}
diff --git a/packages/react/src/components/steps/offer/default-trial-extension-offer.tsx b/packages/react/src/components/steps/offer/default-trial-extension-offer.tsx
index f34a5f6..592f088 100644
--- a/packages/react/src/components/steps/offer/default-trial-extension-offer.tsx
+++ b/packages/react/src/components/steps/offer/default-trial-extension-offer.tsx
@@ -1,4 +1,5 @@
 import { formatMonthDay } from '../../../core/format'
+import { defaultMessages } from '../../../core/messages'
 import type { OfferDecision, OfferStepProps } from '../../../core/types'
 import { cn } from '../../../core/utils'
 import { RichText } from '../../rich-text'
@@ -11,7 +12,9 @@ export function DefaultTrialExtensionOffer({
   onDecline,
   isProcessing,
   classNames,
+  messages,
 }: OfferStepProps) {
+  const msg = messages ?? defaultMessages
   const o = offer as OfferDecision & { days: number }
   const headline = title ?? offer.copy.headline
   const body = description ?? offer.copy.body
@@ -28,10 +31,10 @@ export function DefaultTrialExtensionOffer({
         <div className="ck-offer-details ck-trial-block">
           <div className="ck-trial-badge">
             <div className="ck-trial-days">+{o.days}</div>
-            <div className="ck-trial-unit">{o.days === 1 ? 'day' : 'days'}</div>
+            <div className="ck-trial-unit">{o.days === 1 ? msg.common.day : msg.common.days}</div>
           </div>
           <div>
-            <div className="ck-trial-end-label">New end date</div>
+            <div className="ck-trial-end-label">{msg.offer.newEndDateLabel}</div>
             <div className="ck-trial-end-date">{newEnd}</div>
           </div>
         </div>
@@ -41,7 +44,7 @@ export function DefaultTrialExtensionOffer({
           onClick={() => onAccept()}
           disabled={isProcessing}
         >
-          {isProcessing ? 'Processing...' : offer.copy.cta}
+          {isProcessing ? msg.common.processing : offer.copy.cta}
         </button>
         <button type="button" className={cn('ck-button-link', classNames?.declineButton)} onClick={onDecline}>
           {offer.copy.declineCta}
diff --git a/packages/react/src/components/structural/default-back-button.tsx b/packages/react/src/components/structural/default-back-button.tsx
index a16bfac..4a73df5 100644
--- a/packages/react/src/components/structural/default-back-button.tsx
+++ b/packages/react/src/components/structural/default-back-button.tsx
@@ -1,7 +1,7 @@
 import type { BackButtonProps } from '../../core/types'
 import { cn } from '../../core/utils'
 
-export function DefaultBackButton({ onBack, className }: BackButtonProps) {
+export function DefaultBackButton({ onBack, className, label }: BackButtonProps) {
   return (
     <button type="button" className={cn('ck-back-button', className)} onClick={onBack}>
       <svg width="14" height="14" viewBox="0 0 20 20" fill="none" aria-hidden="true">
@@ -13,7 +13,7 @@ export function DefaultBackButton({ onBack, className }: BackButtonProps) {
           strokeLinejoin="round"
         />
       </svg>
-      <span>Back</span>
+      <span>{label ?? 'Back'}</span>
     </button>
   )
 }
diff --git a/packages/react/src/components/structural/default-close-button.tsx b/packages/react/src/components/structural/default-close-button.tsx
index e6e49b9..9abdcd8 100644
--- a/packages/react/src/components/structural/default-close-button.tsx
+++ b/packages/react/src/components/structural/default-close-button.tsx
@@ -1,9 +1,9 @@
 import type { CloseButtonProps } from '../../core/types'
 import { cn } from '../../core/utils'
 
-export function DefaultCloseButton({ onClose, className }: CloseButtonProps) {
+export function DefaultCloseButton({ onClose, className, label }: CloseButtonProps) {
   return (
-    <button type="button" className={cn('ck-close-button', className)} onClick={onClose} aria-label="Close">
+    <button type="button" className={cn('ck-close-button', className)} onClick={onClose} aria-label={label ?? 'Close'}>
       <svg width="20" height="20" viewBox="0 0 20 20" fill="none" aria-hidden="true">
         <path d="M15 5L5 15M5 5l10 10" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
       </svg>
diff --git a/packages/react/src/core/index.ts b/packages/react/src/core/index.ts
index fca9e54..d955df8 100644
--- a/packages/react/src/core/index.ts
+++ b/packages/react/src/core/index.ts
@@ -14,6 +14,8 @@ export type {
 } from './api-types'
 export { calculateDiscountedPrice, formatPeriodEnd, formatPrice } from './format'
 export { CancelFlowMachine } from './machine'
+export type { CancelFlowMessages, I18nConfig, MessagesPatch, TimingAware, TimingVariants } from './messages'
+export { buildMessages, defaultMessages, formatMessage, selectTiming } from './messages'
 export type { ResolvedStep } from './step-graph'
 export type { SessionCredentials } from './token'
 export { decodeSessionToken } from './token'
diff --git a/packages/react/src/core/machine.ts b/packages/react/src/core/machine.ts
index ecdc835..2127b93 100644
--- a/packages/react/src/core/machine.ts
+++ b/packages/react/src/core/machine.ts
@@ -11,6 +11,7 @@ import type {
 import { AnalyticsClient, directDataToSessionCustomer, toApiMode } from './api'
 import type { SdkConfig } from './api-types'
 import { applyMergeFieldsToSteps } from './merge-fields'
+import { buildMessages, type CancelFlowMessages } from './messages'
 import { buildStepGraph, type ResolvedStep, type StepGraph } from './step-graph'
 import type { SessionCredentials } from './token'
 import { defaultOfferCopy, transformSdkConfig } from './transform'
@@ -221,6 +222,7 @@ export class CancelFlowMachine {
   private presentedOffers: PresentedOffer[] = []
   private customStepResults: Record<string, unknown> = {}
   private configMode: Mode = 'live'
+  private resolvedMessages: CancelFlowMessages
   private stepEnteredAt: number = Date.now()
   private aborted = false
   // Visited-step stack. `back` pops this so it lands on the actually-seen
@@ -232,6 +234,7 @@ export class CancelFlowMachine {
     // FlowConfig extends FlowCallbacks; storing the whole config covers
     // every callback by name without a separate copy.
     this.callbacks = config
+    this.resolvedMessages = buildMessages(config.i18n)
     if (config.mode) this.configMode = config.mode
     if (config.customerAttributes) this.customerAttributes = config.customerAttributes
     if (config.appId && config.customer) {
@@ -290,6 +293,15 @@ export class CancelFlowMachine {
     return this.currentStep?.offer ?? null
   }
 
+  /**
+   * The fully resolved message catalog (defaults layered with the config's
+   * `i18n` overrides). Timing-aware values are still unresolved — pick a
+   * variant with `selectTiming(value, state.cancelAtPeriodEnd)`.
+   */
+  get messages(): CancelFlowMessages {
+    return this.resolvedMessages
+  }
+
   /** Whether `back()` would move anywhere — false on the first step and on success. */
   get canGoBack(): boolean {
     if (this.state.step === 'success') return false
@@ -480,6 +492,7 @@ export class CancelFlowMachine {
       error: null,
       customer,
       subscriptions,
+      cancelAtPeriodEnd: this.config?.settings.cancelAtPeriodEnd ?? null,
     }
   }
 
diff --git a/packages/react/src/core/messages.ts b/packages/react/src/core/messages.ts
new file mode 100644
index 0000000..631a07b
--- /dev/null
+++ b/packages/react/src/core/messages.ts
@@ -0,0 +1,261 @@
+// Message catalog for every string the SDK renders that isn't flow content.
+// Flow content (step titles, offer copy) is authored per-org in the dashboard
+// and arrives resolved in token mode; this catalog covers the chrome around
+// it. Overrides layer lowest-to-highest: built-in defaults, then each entry
+// in the locale fallback chain of `i18n.messages`, and per-step props
+// (confirmLabel, savedTitle, …) win over everything at the render site.
+
+/** Both timing variants of a message. Which one renders is decided by the
+ *  flow's effective cancel timing (`FlowState.cancelAtPeriodEnd`). */
+export interface TimingVariants {
+  immediate: string
+  atPeriodEnd: string
+}
+
+/**
+ * A message that may differ by cancellation timing. Plain strings render
+ * as-is in both cases; pass the object form when the wording should change
+ * (e.g. "Cancel" vs "Turn off auto-renew").
+ */
+export type TimingAware = string | TimingVariants
+
+export interface CancelFlowMessages {
+  common: {
+    continue: string
+    back: string
+    close: string
+    done: string
+    processing: string
+    tryAgain: string
+    loading: string
+    loadError: string
+    error: string
+    day: string
+    days: string
+    month: string
+    months: string
+  }
+  survey: {
+    title: string
+    followupPlaceholder: string
+    followupAriaLabel: string
+  }
+  feedback: {
+    title: string
+    placeholder: string
+    /** Used instead of `placeholder` when the step sets `minLength`. Supports `{minLength}`. */
+    placeholderWithMin: string
+  }
+  confirm: {
+    title: string
+    lossesLabel: string
+    cta: TimingAware
+    goBack: string
+    /** Shown between the description and the confirm button. Supports
+     *  `{periodEnd}`. An empty variant suppresses the notice. */
+    periodEndNotice: TimingAware
+  }
+  success: {
+    saved: {
+      title: string
+      description: string
+    }
+    cancelled: {
+      title: TimingAware
+      description: TimingAware
+    }
+  }
+  offer: {
+    limitedTimeEyebrow: string
+    pauseEyebrow: string
+    newEndDateLabel: string
+    currentPlanBadge: string
+    /** CTA when a plan is selected in a plan-change offer. Supports `{planName}`. */
+    switchToCta: string
+    rebate: {
+      paidLabel: string
+      moneyBackLabel: string
+      /** Tax parenthetical after the money-back label. Supports `{amount}`. */
+      inclTax: string
+      netLabel: string
+    }
+  }
+}
+
+/**
+ * Recursive partial of the catalog for overrides. Timing-aware fields also
+ * accept a plain string (applies to both timings) or a partial variant pair
+ * (the missing variant keeps the base value).
+ */
+export type MessagesPatch<T = CancelFlowMessages> = {
+  [K in keyof T]?: T[K] extends string
+    ? string
+    : T[K] extends TimingAware
+      ? string | Partial<TimingVariants>
+      : MessagesPatch<T[K]>
+}
+
+export interface I18nConfig {
+  /** UI language. Defaults to the browser language, falling back to `'en'`. */
+  locale?: string
+  /** Per-locale message overrides, e.g. `{ en: { confirm: { cta: 'Turn off auto-renew' } } }`. */
+  messages?: Record<string, MessagesPatch>
+}
+
+export const defaultMessages: CancelFlowMessages = {
+  common: {
+    continue: 'Continue',
+    back: 'Back',
+    close: 'Close',
+    done: 'Done',
+    processing: 'Processing...',
+    tryAgain: 'Try again',
+    loading: 'Loading your options...',
+    loadError: "We couldn't load your cancellation options. Please try again.",
+    error: 'Something went wrong. Please try again.',
+    day: 'day',
+    days: 'days',
+    month: 'month',
+    months: 'months',
+  },
+  survey: {
+    title: 'Why are you cancelling?',
+    followupPlaceholder: 'Tell us more (optional)',
+    followupAriaLabel: 'Additional detail',
+  },
+  feedback: {
+    title: 'Any other feedback?',
+    placeholder: 'Type your thoughts…',
+    placeholderWithMin: 'At least {minLength} characters…',
+  },
+  confirm: {
+    title: 'Confirm cancellation',
+    lossesLabel: "You'll lose access to:",
+    cta: 'Cancel subscription',
+    goBack: 'Go back',
+    periodEndNotice: {
+      immediate: '',
+      atPeriodEnd: 'Your access continues until {periodEnd}.',
+    },
+  },
+  success: {
+    saved: {
+      title: 'Welcome back!',
+      description: 'Your offer has been applied.',
+    },
+    cancelled: {
+      title: 'Subscription cancelled',
+      description: "We're sorry to see you go.",
+    },
+  },
+  offer: {
+    limitedTimeEyebrow: 'Limited-time offer',
+    pauseEyebrow: "We'll see you back on",
+    newEndDateLabel: 'New end date',
+    currentPlanBadge: 'Current',
+    switchToCta: 'Switch to {planName}',
+    rebate: {
+      paidLabel: 'You paid this period',
+      moneyBackLabel: 'Money back',
+      inclTax: '(incl. {amount} tax)',
+      netLabel: 'Your net for this period',
+    },
+  },
+}
+
+function isTimingVariants(value: unknown): value is Partial<TimingVariants> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    ('immediate' in value || 'atPeriodEnd' in value) &&
+    !Array.isArray(value)
+  )
+}
+
+/**
+ * Pick the string for the flow's effective cancel timing. `null` (timing
+ * unknown — local mode) behaves like period-end, matching the default the
+ * cancel action itself uses.
+ */
+export function selectTiming(value: TimingAware, cancelAtPeriodEnd: boolean | null): string {
+  if (typeof value === 'string') return value
+  return (cancelAtPeriodEnd ?? true) ? value.atPeriodEnd : value.immediate
+}
+
+/** Replace `{name}` tokens. Unknown tokens are left in place. */
+export function formatMessage(template: string, vars: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (match, name) => {
+    const value = vars[name]
+    return value == null ? match : String(value)
+  })
+}
+
+// Empty-string overrides are dropped (a blank dashboard field must not
+// clobber a real string — same rule as the embed), which is why defaults
+// may legitimately hold '' but patches never land one.
+function mergeValue(base: unknown, patch: unknown): unknown {
+  if (typeof patch === 'string') return patch === '' ? base : patch
+  if (isTimingVariants(patch)) {
+    const baseVariants: TimingVariants =
+      typeof base === 'string'
+        ? { immediate: base, atPeriodEnd: base }
+        : { immediate: '', atPeriodEnd: '', ...(base as Partial<TimingVariants>) }
+    const result = { ...baseVariants }
+    if (patch.immediate) result.immediate = patch.immediate
+    if (patch.atPeriodEnd) result.atPeriodEnd = patch.atPeriodEnd
+    return result
+  }
+  if (typeof patch === 'object' && patch !== null && typeof base === 'object' && base !== null) {
+    const merged: Record<string, unknown> = { ...(base as Record<string, unknown>) }
+    for (const [key, value] of Object.entries(patch)) {
+      if (value == null) continue
+      merged[key] = key in merged ? mergeValue(merged[key], value) : value
+    }
+    return merged
+  }
+  return base
+}
+
+export function mergeMessages(base: CancelFlowMessages, patch: MessagesPatch | undefined): CancelFlowMessages {
+  if (!patch) return base
+  return mergeValue(base, patch) as CancelFlowMessages
+}
+
+export function resolveLocale(explicit?: string): string {
+  if (explicit) return explicit
+  if (typeof navigator !== 'undefined' && navigator.language) return navigator.language
+  return 'en'
+}
+
+// Fallback chain, least to most specific: 'en' first so an English override
+// still shows through a partial regional catalog, then the base language,
+// then the exact tag. Keys are matched case-insensitively ('pt-BR' ≡ 'pt-br').
+function localeChain(locale: string): string[] {
+  const exact = locale.toLowerCase()
+  const base = exact.split('-')[0]
+  const chain = ['en']
+  if (base !== 'en') chain.push(base)
+  if (exact !== base) chain.push(exact)
+  return chain
+}
+
+/**
+ * Resolve the full catalog for a locale: built-in defaults, then `patches`
+ * in argument order (the org-level layer, once it exists, goes here), then
+ * the config's per-locale messages in fallback-chain order — so the
+ * developer's own overrides always end up on top.
+ */
+export function buildMessages(i18n?: I18nConfig, ...patches: Array<MessagesPatch | undefined>): CancelFlowMessages {
+  const locale = resolveLocale(i18n?.locale)
+  let resolved = defaultMessages
+  for (const patch of patches) {
+    resolved = mergeMessages(resolved, patch)
+  }
+  if (i18n?.messages) {
+    const byLowerKey = new Map(Object.entries(i18n.messages).map(([k, v]) => [k.toLowerCase(), v]))
+    for (const lang of localeChain(locale)) {
+      resolved = mergeMessages(resolved, byLowerKey.get(lang))
+    }
+  }
+  return resolved
+}
diff --git a/packages/react/src/core/types.ts b/packages/react/src/core/types.ts
index 34d6021..2dee6a1 100644
--- a/packages/react/src/core/types.ts
+++ b/packages/react/src/core/types.ts
@@ -1,4 +1,5 @@
 import type { ComponentType, ReactElement, ReactNode } from 'react'
+import type { CancelFlowMessages, I18nConfig } from './messages'
 
 // ─── Direct shape — billing data passed in and out of the SDK ─────────────
 //
@@ -520,11 +521,15 @@ export interface ModalProps {
 export interface CloseButtonProps {
   onClose: () => void
   className?: string
+  /** Accessible label. Defaults to "Close". */
+  label?: string
 }
 
 export interface BackButtonProps {
   onBack: () => void
   className?: string
+  /** Visible label. Defaults to "Back". */
+  label?: string
 }
 
 // ─── Step component props ────────────────────────────────────────────────────
@@ -544,6 +549,8 @@ export interface SurveyStepProps {
   onNext: () => void
   classNames?: SurveyClassNames
   components?: Partial<ComponentOverrides>
+  /** Resolved message catalog. Default components fall back to `defaultMessages` when absent. */
+  messages?: CancelFlowMessages
 }
 
 export interface OfferStepProps {
@@ -567,6 +574,8 @@ export interface OfferStepProps {
    * implementations can ignore this.
    */
   components?: Partial<ComponentOverrides>
+  /** Resolved message catalog. Default components fall back to `defaultMessages` when absent. */
+  messages?: CancelFlowMessages
 }
 
 export interface FeedbackStepProps {
@@ -581,6 +590,8 @@ export interface FeedbackStepProps {
   onChange: (text: string) => void
   onSubmit: () => void
   classNames?: FeedbackClassNames
+  /** Resolved message catalog. Default components fall back to `defaultMessages` when absent. */
+  messages?: CancelFlowMessages
 }
 
 export interface ConfirmStepProps {
@@ -592,10 +603,18 @@ export interface ConfirmStepProps {
   lossesLabel?: string
   confirmLabel: string
   goBackLabel: string
+  /**
+   * Timing-resolved access notice ("Your access continues until June 14, 2026."),
+   * rendered between the loss list and the confirm button. Absent when the
+   * period end is unknown or the resolved message is empty.
+   */
+  periodEndNotice?: string
   onConfirm: () => Promise<void>
   onGoBack: () => void
   isProcessing: boolean
   classNames?: ConfirmClassNames
+  /** Resolved message catalog. Default components fall back to `defaultMessages` when absent. */
+  messages?: CancelFlowMessages
 }
 
 export interface SuccessStepProps {
@@ -607,6 +626,8 @@ export interface SuccessStepProps {
   subscriptions: DirectSubscription[]
   onClose: () => void
   classNames?: SuccessClassNames
+  /** Resolved message catalog. Default components fall back to `defaultMessages` when absent. */
+  messages?: CancelFlowMessages
 }
 
 // ─── Sub-component props ─────────────────────────────────────────────────────
@@ -631,6 +652,13 @@ export interface FlowState {
   error: Error | null
   customer: DirectCustomer | null
   subscriptions: DirectSubscription[]
+  /**
+   * Effective cancel timing for this flow, resolved server-side per blueprint
+   * (token mode). `null` when unknown — local mode, or before the config
+   * fetch settles. Drives timing-aware messages; `null` reads as period-end,
+   * matching the default the cancel action uses.
+   */
+  cancelAtPeriodEnd: boolean | null
 }
 
 // ─── Flow config ─────────────────────────────────────────────────────────────
@@ -669,6 +697,13 @@ export interface FlowConfig extends FlowCallbacks {
    * this field.
    */
   mode?: Mode
+  /**
+   * Locale and message overrides for the SDK's own strings (buttons, loading
+   * and confirmation chrome). Flow content — step titles, offer copy — is
+   * authored in the dashboard and localized server-side; override it there or
+   * via `steps`. Read once at mount, like `steps`.
+   */
+  i18n?: I18nConfig
 }
 
 type OfferCallback = (offer: AcceptedOffer, customer: DirectCustomer | null) => Promise<void> | void
@@ -718,6 +753,8 @@ export interface CancelFlowProps extends FlowCallbacks {
   apiBaseUrl?: string
   /** See FlowConfig.mode. Ignored in token mode (the token is authoritative). */
   mode?: Mode
+  /** See FlowConfig.i18n. */
+  i18n?: I18nConfig
   appearance?: Appearance
   classNames?: StructuralClassNames
   components?: Partial<ComponentOverrides>
diff --git a/packages/react/src/core/utils.ts b/packages/react/src/core/utils.ts
index 4df0c52..8456ddd 100644
--- a/packages/react/src/core/utils.ts
+++ b/packages/react/src/core/utils.ts
@@ -1,4 +1,5 @@
 import type { CSSProperties } from 'react'
+import { defaultMessages } from './messages'
 import type { Appearance, AppearanceVariables } from './types'
 
 export const BUILT_IN_STEP_TYPES: readonly string[] = ['survey', 'offer', 'feedback', 'confirm', 'success']
@@ -84,9 +85,11 @@ export function appearanceToStyle(appearance?: Appearance): CSSProperties | unde
 
 // Step-level fallback titles when neither token-mode config nor local
 // step config provide one. Offer and Success are absent — Offer falls back
-// to `offer.copy.headline`, Success branches on outcome.
+// to `offer.copy.headline`, Success branches on outcome. Kept for backwards
+// compatibility; the renderer now reads titles from the message catalog,
+// which these mirror.
 export const defaultTitles = {
-  survey: 'Why are you cancelling?',
-  feedback: 'Any other feedback?',
-  confirm: 'Confirm cancellation',
+  survey: defaultMessages.survey.title,
+  feedback: defaultMessages.feedback.title,
+  confirm: defaultMessages.confirm.title,
 } as const
diff --git a/packages/react/src/headless/use-cancel-flow.ts b/packages/react/src/headless/use-cancel-flow.ts
index 3a6e823..34fda44 100644
--- a/packages/react/src/headless/use-cancel-flow.ts
+++ b/packages/react/src/headless/use-cancel-flow.ts
@@ -9,6 +9,7 @@ export function useCancelFlow(config: FlowConfig) {
     isLoading,
     loadError,
     retry,
+    messages: machine.messages,
     reasons: machine.reasons,
     currentStep: machine.currentStep,
     currentOffer: machine.currentOffer,
diff --git a/packages/react/tests/components/cancel-flow.test.tsx b/packages/react/tests/components/cancel-flow.test.tsx
index 4e0280f..785f590 100644
--- a/packages/react/tests/components/cancel-flow.test.tsx
+++ b/packages/react/tests/components/cancel-flow.test.tsx
@@ -1,6 +1,6 @@
 import { render, screen, waitFor } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { CancelFlow } from '../../src/components/cancel-flow'
 import type { AcceptedOffer, CustomOfferProps, Step } from '../../src/core/types'
 
@@ -392,9 +392,10 @@ describe('CancelFlow', () => {
       />,
     )
 
-    // The hardcoded period-end notice was removed: it always rendered when the
-    // subscription had a current period, regardless of whether the cancel is
-    // immediate or end-of-cycle, so it could contradict the merchant's setting.
+    // Local mode doesn't know the flow's cancel timing, so the notice must
+    // stay silent — a wrong "access continues" claim contradicts the
+    // merchant's setting. Token mode renders it when the server-resolved
+    // timing is period-end.
     expect(screen.queryByText(/access continues until/i)).not.toBeInTheDocument()
   })
 
@@ -459,3 +460,88 @@ describe('CancelFlow', () => {
     })
   })
 })
+
+// ─── i18n ─────────────────────────────────────────────────────────────────────
+
+function sessionToken(): string {
+  const payload = JSON.stringify({ a: 'app_1', c: 'cus_1', h: 'hash' })
+  return `ck_${btoa(payload).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`
+}
+
+function stubConfigFetch(settings: Record<string, unknown>) {
+  const config = {
+    blueprintId: 'bp_1',
+    steps: [{ type: 'confirm', guid: 'c1', title: 'Confirm cancellation' }],
+    customer: { id: 'cus_1' },
+    subscriptions: [
+      {
+        id: 'sub_1',
+        start: '2024-01-01',
+        status: { name: 'active', currentPeriod: { start: '2026-06-01', end: '2026-07-01' } },
+        items: [{ price: { id: 'p', amount: { value: 100, currency: 'USD' } } }],
+      },
+    ],
+    settings: { clickToCancelEnabled: false, strictFTCComplianceEnabled: false, ...settings },
+  }
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async (url: string) => ({
+      ok: true,
+      status: 200,
+      json: async () => (String(url).includes('cancel-flow/config') ? config : {}),
+    })),
+  )
+}
+
+describe('CancelFlow i18n', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('applies message overrides to chrome strings in local mode', async () => {
+    renderFlow({
+      i18n: {
+        locale: 'en',
+        messages: { en: { common: { continue: 'Keep going' }, survey: { title: 'Tell us why' } } },
+      },
+      steps: [{ type: 'survey', reasons: [{ id: 'r1', label: 'Too expensive' }] }, { type: 'confirm' }],
+    })
+    expect(screen.getByText('Tell us why')).toBeInTheDocument()
+    expect(screen.getByText('Keep going')).toBeInTheDocument()
+  })
+
+  it('renders the immediate variant of timing-aware messages in token mode', async () => {
+    stubConfigFetch({ cancelAtPeriodEnd: false })
+    render(
+      <CancelFlow
+        session={sessionToken()}
+        i18n={{
+          messages: {
+            en: { confirm: { cta: { immediate: 'Cancel now', atPeriodEnd: 'Turn off auto-renew' } } },
+          },
+        }}
+      />,
+    )
+    expect(await screen.findByText('Cancel now')).toBeInTheDocument()
+    // Immediate timing must not claim continued access.
+    expect(screen.queryByText(/access continues until/i)).not.toBeInTheDocument()
+  })
+
+  it('renders the period-end variant and the access notice in token mode', async () => {
+    stubConfigFetch({ cancelAtPeriodEnd: true })
+    render(
+      <CancelFlow
+        session={sessionToken()}
+        i18n={{
+          messages: {
+            en: { confirm: { cta: { immediate: 'Cancel now', atPeriodEnd: 'Turn off auto-renew' } } },
+          },
+        }}
+      />,
+    )
+    expect(await screen.findByText('Turn off auto-renew')).toBeInTheDocument()
+    // The period end formats in the runner's local timezone, so the UTC
+    // midnight boundary can land on either side of July 1.
+    expect(screen.getByText(/Your access continues until (June 30|July 1), 2026\./)).toBeInTheDocument()
+  })
+})
diff --git a/packages/react/tests/core/machine.test.ts b/packages/react/tests/core/machine.test.ts
index 4c25cc8..5cdd093 100644
--- a/packages/react/tests/core/machine.test.ts
+++ b/packages/react/tests/core/machine.test.ts
@@ -1913,3 +1913,52 @@ describe('CancelFlowMachine', () => {
     })
   })
 })
+
+describe('i18n / messages', () => {
+  it('resolves default messages with no i18n config', () => {
+    const machine = new CancelFlowMachine(baseConfig)
+    expect(machine.messages.common.continue).toBe('Continue')
+    expect(machine.messages.confirm.cta).toBe('Cancel subscription')
+  })
+
+  it('layers i18n overrides onto the defaults', () => {
+    const machine = new CancelFlowMachine({
+      ...baseConfig,
+      i18n: {
+        locale: 'en',
+        messages: {
+          en: {
+            common: { continue: 'Keep going' },
+            confirm: { cta: { immediate: 'Cancel', atPeriodEnd: 'Turn off auto-renew' } },
+          },
+        },
+      },
+    })
+    expect(machine.messages.common.continue).toBe('Keep going')
+    expect(machine.messages.confirm.cta).toEqual({ immediate: 'Cancel', atPeriodEnd: 'Turn off auto-renew' })
+    expect(machine.messages.common.back).toBe('Back')
+  })
+
+  it('leaves cancelAtPeriodEnd null in local mode', () => {
+    const machine = new CancelFlowMachine(baseConfig)
+    expect(machine.getSnapshot().cancelAtPeriodEnd).toBeNull()
+  })
+
+  it('threads the server-resolved cancelAtPeriodEnd into state in token mode', () => {
+    for (const value of [true, false]) {
+      const machine = new CancelFlowMachine({ session: 'ck_placeholder' })
+      machine.initializeFromConfig(
+        sdkConfig({
+          settings: {
+            clickToCancelEnabled: false,
+            strictFTCComplianceEnabled: false,
+            cancelAtPeriodEnd: value,
+          },
+        }),
+        {} as any,
+        { appId: 'a', customerId: 'c', authHash: 'h', mode: 'live' as const, issuedAt: 0 },
+      )
+      expect(machine.getSnapshot().cancelAtPeriodEnd).toBe(value)
+    }
+  })
+})
diff --git a/packages/react/tests/core/messages.test.ts b/packages/react/tests/core/messages.test.ts
new file mode 100644
index 0000000..4fd3348
--- /dev/null
+++ b/packages/react/tests/core/messages.test.ts
@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  buildMessages,
+  defaultMessages,
+  formatMessage,
+  mergeMessages,
+  resolveLocale,
+  selectTiming,
+} from '../../src/core/messages'
+
+describe('mergeMessages', () => {
+  it('returns the base untouched with no patch', () => {
+    expect(mergeMessages(defaultMessages, undefined)).toBe(defaultMessages)
+  })
+
+  it('overrides one key and keeps the rest', () => {
+    const merged = mergeMessages(defaultMessages, { common: { continue: 'Keep going' } })
+    expect(merged.common.continue).toBe('Keep going')
+    expect(merged.common.back).toBe('Back')
+    expect(merged.survey.title).toBe(defaultMessages.survey.title)
+  })
+
+  it('does not mutate the base catalog', () => {
+    mergeMessages(defaultMessages, { common: { continue: 'Keep going' } })
+    expect(defaultMessages.common.continue).toBe('Continue')
+  })
+
+  it('drops empty-string overrides so a blank field never clobbers a real string', () => {
+    const merged = mergeMessages(defaultMessages, { common: { continue: '' } })
+    expect(merged.common.continue).toBe('Continue')
+  })
+
+  it('replaces a timing-aware value with a plain string', () => {
+    const merged = mergeMessages(defaultMessages, { confirm: { cta: 'End membership' } })
+    expect(merged.confirm.cta).toBe('End membership')
+  })
+
+  it('expands a string base into both variants when patched with a full pair', () => {
+    const merged = mergeMessages(defaultMessages, {
+      confirm: { cta: { immediate: 'Cancel', atPeriodEnd: 'Turn off auto-renew' } },
+    })
+    expect(merged.confirm.cta).toEqual({ immediate: 'Cancel', atPeriodEnd: 'Turn off auto-renew' })
+  })
+
+  it('keeps the base value for the missing variant of a partial pair', () => {
+    const merged = mergeMessages(defaultMessages, {
+      confirm: { cta: { atPeriodEnd: 'Turn off auto-renew' } },
+    })
+    expect(merged.confirm.cta).toEqual({ immediate: 'Cancel subscription', atPeriodEnd: 'Turn off auto-renew' })
+  })
+
+  it('merges a variant pair over a variant-pair base', () => {
+    const merged = mergeMessages(defaultMessages, {
+      confirm: { periodEndNotice: { atPeriodEnd: 'Access until {periodEnd}.' } },
+    })
+    expect(merged.confirm.periodEndNotice).toEqual({ immediate: '', atPeriodEnd: 'Access until {periodEnd}.' })
+  })
+})
+
+describe('selectTiming', () => {
+  const pair = { immediate: 'Cancel', atPeriodEnd: 'Turn off auto-renew' }
+
+  it('passes plain strings through for either timing', () => {
+    expect(selectTiming('Cancel subscription', true)).toBe('Cancel subscription')
+    expect(selectTiming('Cancel subscription', false)).toBe('Cancel subscription')
+  })
+
+  it('picks the variant for the resolved timing', () => {
+    expect(selectTiming(pair, false)).toBe('Cancel')
+    expect(selectTiming(pair, true)).toBe('Turn off auto-renew')
+  })
+
+  it('treats unknown timing as period-end, matching the cancel action default', () => {
+    expect(selectTiming(pair, null)).toBe('Turn off auto-renew')
+  })
+})
+
+describe('formatMessage', () => {
+  it('replaces tokens', () => {
+    expect(formatMessage('Access until {periodEnd}.', { periodEnd: 'June 14' })).toBe('Access until June 14.')
+    expect(formatMessage('At least {minLength} characters', { minLength: 20 })).toBe('At least 20 characters')
+  })
+
+  it('leaves unknown tokens in place', () => {
+    expect(formatMessage('Hello {name}', {})).toBe('Hello {name}')
+  })
+})
+
+describe('resolveLocale / buildMessages', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('prefers the explicit locale over the browser', () => {
+    expect(resolveLocale('de')).toBe('de')
+  })
+
+  it('falls back to navigator.language', () => {
+    vi.stubGlobal('navigator', { language: 'fr-CA' })
+    expect(resolveLocale()).toBe('fr-CA')
+  })
+
+  it('resolves defaults with no config', () => {
+    expect(buildMessages()).toEqual(defaultMessages)
+  })
+
+  it('applies the locale fallback chain: en, base language, exact tag', () => {
+    const resolved = buildMessages({
+      locale: 'pt-BR',
+      messages: {
+        en: { common: { continue: 'EN override', back: 'EN back' } },
+        pt: { common: { continue: 'PT continue' } },
+        'pt-br': { common: { done: 'PT-BR done' } },
+      },
+    })
+    // Exact and base-language patches win over 'en'; untouched keys show the
+    // 'en' override through the partial regional catalog.
+    expect(resolved.common.continue).toBe('PT continue')
+    expect(resolved.common.done).toBe('PT-BR done')
+    expect(resolved.common.back).toBe('EN back')
+    expect(resolved.common.close).toBe('Close')
+  })
+
+  it('matches locale keys case-insensitively', () => {
+    const resolved = buildMessages({
+      locale: 'pt-br',
+      messages: { 'pt-BR': { common: { continue: 'PT-BR' } } },
+    })
+    expect(resolved.common.continue).toBe('PT-BR')
+  })
+
+  it('layers extra patches below the developer messages', () => {
+    // The patches argument is where the org-level layer will slot in.
+    const resolved = buildMessages(
+      { locale: 'en', messages: { en: { common: { continue: 'Developer' } } } },
+      { common: { continue: 'Org', back: 'Org back' } },
+    )
+    expect(resolved.common.continue).toBe('Developer')
+    expect(resolved.common.back).toBe('Org back')
+  })
+})

From 080a44bfb4e24fd0adca876904af8741e58ace0a Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Fri, 10 Jul 2026 12:28:57 -0400
Subject: [PATCH 2/4] Add i18n scenario to the playground test harness
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Locale picker (en / de / de-AT) exercising the fallback chain — de is a
deliberately partial catalog, de-AT has no entry and resolves via the
base language. The en catalog uses timing-aware pairs on confirm.cta and
success.cancelled.*; local mode has unknown timing so the atPeriodEnd
variants render and the access notice stays hidden, which is the
designed behavior. Steps omit per-step label props since those outrank
i18n messages and would mask the overrides.
---
 apps/playground/src/TestHarness.tsx | 75 +++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/apps/playground/src/TestHarness.tsx b/apps/playground/src/TestHarness.tsx
index 686a50b..9ac5e3c 100644
--- a/apps/playground/src/TestHarness.tsx
+++ b/apps/playground/src/TestHarness.tsx
@@ -8,6 +8,7 @@ import type {
   CustomStepProps,
   DirectCustomer,
   DirectSubscription,
+  I18nConfig,
   Mode,
   Step,
 } from '@churnkey/react/core'
@@ -23,6 +24,7 @@ type Scenario =
   | 'all-offers'
   | 'standalone-offer'
   | 'color-scheme'
+  | 'i18n'
 
 const SCENARIOS: { id: Scenario; label: string; description: string }[] = [
   {
@@ -72,6 +74,12 @@ const SCENARIOS: { id: Scenario; label: string; description: string }[] = [
     label: 'Color Scheme',
     description: 'Toggle light / dark / auto. `auto` follows OS preference.',
   },
+  {
+    id: 'i18n',
+    label: 'i18n / Text Overrides',
+    description:
+      'Message overrides via the i18n prop: chrome strings, timing-aware confirm/success copy, locale fallback chain. Local mode, so timing is unknown → pairs resolve to atPeriodEnd and the access notice stays hidden.',
+  },
 ]
 
 // A customized success step on every flow catches regressions in the
@@ -225,6 +233,51 @@ const allOffersSteps: Step[] = [
   successStep,
 ]
 
+// No confirmLabel / goBackLabel / success titles here — per-step props beat
+// i18n messages, so setting them would mask exactly what this scenario
+// exists to show. The feedback minLength exercises {minLength} interpolation.
+const i18nSteps: Step[] = [
+  {
+    type: 'survey',
+    reasons: [
+      { id: 'expensive', label: 'Too expensive', offer: { type: 'discount', percentOff: 20, durationInMonths: 3 } },
+      { id: 'missing', label: 'Missing features' },
+    ],
+  },
+  { type: 'feedback', required: true, minLength: 20 },
+  { type: 'confirm' },
+  { type: 'success' },
+]
+
+// 'en' shows targeted overrides incl. timing pairs; 'de' is a partial catalog
+// (untranslated keys fall back to the en overrides, then defaults); 'de-AT'
+// has no entry at all, proving the exact → base-language → en chain.
+const I18N_MESSAGES: I18nConfig['messages'] = {
+  en: {
+    common: { continue: 'Keep going →', done: 'All set' },
+    survey: { title: 'Mind telling us why?' },
+    confirm: {
+      cta: { immediate: 'Cancel immediately', atPeriodEnd: 'Turn off auto-renew' },
+      goBack: 'Actually, never mind',
+    },
+    success: {
+      cancelled: {
+        title: { immediate: 'Subscription cancelled', atPeriodEnd: 'Auto-renew is off' },
+        description: {
+          immediate: 'Your access has ended.',
+          atPeriodEnd: 'You keep access until the end of your billing period.',
+        },
+      },
+    },
+  },
+  de: {
+    common: { continue: 'Weiter', back: 'Zurück', done: 'Fertig', processing: 'Wird verarbeitet…' },
+    survey: { title: 'Warum möchtest du kündigen?' },
+    feedback: { title: 'Möchtest du uns noch etwas mitteilen?', placeholderWithMin: 'Mindestens {minLength} Zeichen…' },
+    confirm: { title: 'Kündigung bestätigen', cta: 'Auto-Verlängerung deaktivieren', goBack: 'Doch nicht' },
+  },
+}
+
 // Flow starts directly on an offer step. Exercises buildInitialState's
 // currentStep.offer read for the first step and the offer-first entry path.
 const standaloneOfferSteps: Step[] = [
@@ -596,6 +649,7 @@ export function TestHarness() {
   const [mode, setMode] = useState<Mode>('test')
   const [open, setOpen] = useState(false)
   const [colorScheme, setColorScheme] = useState<'light' | 'dark' | 'auto'>('light')
+  const [locale, setLocale] = useState<'en' | 'de' | 'de-AT'>('en')
   const logRef = useRef<HTMLDivElement>(null)
   const [logs, setLogs] = useState<string[]>([])
 
@@ -705,6 +759,8 @@ export function TestHarness() {
         return allOffersSteps
       case 'standalone-offer':
         return standaloneOfferSteps
+      case 'i18n':
+        return i18nSteps
       case 'token':
       case 'token-analytics':
         return undefined
@@ -870,6 +926,23 @@ export function TestHarness() {
         </fieldset>
       )}
 
+      {/* Locale picker (i18n scenario only) */}
+      {scenario === 'i18n' && (
+        <fieldset style={{ border: '1px solid #e5e7eb', borderRadius: 8, padding: 16, marginBottom: 16 }}>
+          <legend style={{ fontSize: 13, fontWeight: 600, color: '#374151', padding: '0 4px' }}>Locale</legend>
+          <div style={{ display: 'flex', gap: 6 }}>
+            {(['en', 'de', 'de-AT'] as const).map((l) => (
+              <Pill key={l} label={l} selected={locale === l} onClick={() => setLocale(l)} />
+            ))}
+          </div>
+          <p style={{ fontSize: 12, color: '#6b7280', margin: '8px 0 0' }}>
+            <code>de</code> is a partial catalog — untranslated keys fall through to the <code>en</code> overrides, then
+            defaults. <code>de-AT</code> has no catalog entry and resolves via the base language. Switching locale
+            remounts the flow (the machine reads <code>i18n</code> once at mount).
+          </p>
+        </fieldset>
+      )}
+
       {/* Launch */}
       <button
         type="button"
@@ -938,6 +1011,8 @@ export function TestHarness() {
       {/* CancelFlow */}
       {open && (
         <CancelFlow
+          key={scenario === 'i18n' ? locale : undefined}
+          i18n={scenario === 'i18n' ? { locale, messages: I18N_MESSAGES } : undefined}
           appId={needsAppId && appId ? appId : undefined}
           customer={customer}
           subscriptions={subscriptions}

From 10a8fbb8b61eb1b4d18d91c6852ec7f1895b59cd Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Fri, 10 Jul 2026 14:10:52 -0400
Subject: [PATCH 3/4] Let local mode declare its cancel timing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up: timing-aware messages silently resolved to the
atPeriodEnd variant in local mode, where the SDK has no way to know the
real timing — an immediate-cancel integration could show "Turn off
auto-renew" copy. New optional cancelAtPeriodEnd on FlowConfig /
CancelFlowProps lets the developer declare their billing behavior;
token mode's server-resolved value stays authoritative.

An explicit declaration also satisfies the known-timing gate on the
confirm step's access-until notice, so local integrations that declare
period-end get it too. The playground i18n scenario grows a timing
picker exercising all three states.
---
 apps/playground/src/TestHarness.tsx           | 21 ++++++++++-
 packages/react/src/components/cancel-flow.tsx |  5 ++-
 packages/react/src/core/machine.ts            |  4 +-
 packages/react/src/core/types.ts              | 19 ++++++++--
 .../tests/components/cancel-flow.test.tsx     | 37 +++++++++++++++++++
 packages/react/tests/core/machine.test.ts     | 26 +++++++++++++
 6 files changed, 103 insertions(+), 9 deletions(-)

diff --git a/apps/playground/src/TestHarness.tsx b/apps/playground/src/TestHarness.tsx
index 9ac5e3c..108759e 100644
--- a/apps/playground/src/TestHarness.tsx
+++ b/apps/playground/src/TestHarness.tsx
@@ -78,7 +78,7 @@ const SCENARIOS: { id: Scenario; label: string; description: string }[] = [
     id: 'i18n',
     label: 'i18n / Text Overrides',
     description:
-      'Message overrides via the i18n prop: chrome strings, timing-aware confirm/success copy, locale fallback chain. Local mode, so timing is unknown → pairs resolve to atPeriodEnd and the access notice stays hidden.',
+      'Message overrides via the i18n prop: chrome strings, timing-aware confirm/success copy, locale fallback chain. Declare the cancel timing to flip variants; leave it undeclared and pairs resolve to atPeriodEnd with the access notice hidden.',
   },
 ]
 
@@ -650,6 +650,7 @@ export function TestHarness() {
   const [open, setOpen] = useState(false)
   const [colorScheme, setColorScheme] = useState<'light' | 'dark' | 'auto'>('light')
   const [locale, setLocale] = useState<'en' | 'de' | 'de-AT'>('en')
+  const [localTiming, setLocalTiming] = useState<'period-end' | 'immediate' | 'undeclared'>('undeclared')
   const logRef = useRef<HTMLDivElement>(null)
   const [logs, setLogs] = useState<string[]>([])
 
@@ -940,6 +941,19 @@ export function TestHarness() {
             defaults. <code>de-AT</code> has no catalog entry and resolves via the base language. Switching locale
             remounts the flow (the machine reads <code>i18n</code> once at mount).
           </p>
+          <div style={{ fontSize: 13, fontWeight: 600, color: '#374151', padding: '12px 0 4px' }}>
+            Cancel timing (local declaration)
+          </div>
+          <div style={{ display: 'flex', gap: 6 }}>
+            {(['undeclared', 'immediate', 'period-end'] as const).map((t) => (
+              <Pill key={t} label={t} selected={localTiming === t} onClick={() => setLocalTiming(t)} />
+            ))}
+          </div>
+          <p style={{ fontSize: 12, color: '#6b7280', margin: '8px 0 0' }}>
+            Sets the <code>cancelAtPeriodEnd</code> prop. <code>period-end</code> shows the access-until notice on
+            confirm; <code>undeclared</code> resolves pairs to atPeriodEnd but keeps the notice hidden. In token mode
+            the server-resolved value wins.
+          </p>
         </fieldset>
       )}
 
@@ -1011,8 +1025,11 @@ export function TestHarness() {
       {/* CancelFlow */}
       {open && (
         <CancelFlow
-          key={scenario === 'i18n' ? locale : undefined}
+          key={scenario === 'i18n' ? `${locale}-${localTiming}` : undefined}
           i18n={scenario === 'i18n' ? { locale, messages: I18N_MESSAGES } : undefined}
+          cancelAtPeriodEnd={
+            scenario === 'i18n' && localTiming !== 'undeclared' ? localTiming === 'period-end' : undefined
+          }
           appId={needsAppId && appId ? appId : undefined}
           customer={customer}
           subscriptions={subscriptions}
diff --git a/packages/react/src/components/cancel-flow.tsx b/packages/react/src/components/cancel-flow.tsx
index 8bd1fd6..d0fee8f 100644
--- a/packages/react/src/components/cancel-flow.tsx
+++ b/packages/react/src/components/cancel-flow.tsx
@@ -349,8 +349,9 @@ function StepRenderer({
 }
 
 // The notice makes a factual claim about billing behavior, so it requires the
-// timing to be KNOWN to be period-end — the server-resolved value in token
-// mode. `null` (local mode) stays silent: an earlier hardcoded version of this
+// timing to be KNOWN to be period-end — server-resolved in token mode, or the
+// developer's explicit cancelAtPeriodEnd declaration in local mode. `null`
+// (undeclared local mode) stays silent: an earlier hardcoded version of this
 // notice was removed precisely because it could contradict the merchant's
 // actual setting. Also empty when the period end can't be determined or the
 // resolved message is blank.
diff --git a/packages/react/src/core/machine.ts b/packages/react/src/core/machine.ts
index 2127b93..5d23195 100644
--- a/packages/react/src/core/machine.ts
+++ b/packages/react/src/core/machine.ts
@@ -222,6 +222,7 @@ export class CancelFlowMachine {
   private presentedOffers: PresentedOffer[] = []
   private customStepResults: Record<string, unknown> = {}
   private configMode: Mode = 'live'
+  private localCancelAtPeriodEnd: boolean | null = null
   private resolvedMessages: CancelFlowMessages
   private stepEnteredAt: number = Date.now()
   private aborted = false
@@ -235,6 +236,7 @@ export class CancelFlowMachine {
     // every callback by name without a separate copy.
     this.callbacks = config
     this.resolvedMessages = buildMessages(config.i18n)
+    if (typeof config.cancelAtPeriodEnd === 'boolean') this.localCancelAtPeriodEnd = config.cancelAtPeriodEnd
     if (config.mode) this.configMode = config.mode
     if (config.customerAttributes) this.customerAttributes = config.customerAttributes
     if (config.appId && config.customer) {
@@ -492,7 +494,7 @@ export class CancelFlowMachine {
       error: null,
       customer,
       subscriptions,
-      cancelAtPeriodEnd: this.config?.settings.cancelAtPeriodEnd ?? null,
+      cancelAtPeriodEnd: this.config?.settings.cancelAtPeriodEnd ?? this.localCancelAtPeriodEnd,
     }
   }
 
diff --git a/packages/react/src/core/types.ts b/packages/react/src/core/types.ts
index 2dee6a1..94ba493 100644
--- a/packages/react/src/core/types.ts
+++ b/packages/react/src/core/types.ts
@@ -653,10 +653,11 @@ export interface FlowState {
   customer: DirectCustomer | null
   subscriptions: DirectSubscription[]
   /**
-   * Effective cancel timing for this flow, resolved server-side per blueprint
-   * (token mode). `null` when unknown — local mode, or before the config
-   * fetch settles. Drives timing-aware messages; `null` reads as period-end,
-   * matching the default the cancel action uses.
+   * Effective cancel timing for this flow: the server-resolved value per
+   * blueprint (token mode), else the developer's `cancelAtPeriodEnd`
+   * declaration (local mode), else `null` — unknown. Drives timing-aware
+   * messages; `null` reads as period-end, matching the default the cancel
+   * action uses.
    */
   cancelAtPeriodEnd: boolean | null
 }
@@ -704,6 +705,14 @@ export interface FlowConfig extends FlowCallbacks {
    * via `steps`. Read once at mount, like `steps`.
    */
   i18n?: I18nConfig
+  /**
+   * Local-mode declaration of your billing behavior: does cancellation take
+   * effect at the end of the billing period (`true`) or immediately
+   * (`false`)? Drives timing-aware messages and the confirm step's
+   * access-until notice. In token mode the server-resolved value is
+   * authoritative and this is ignored.
+   */
+  cancelAtPeriodEnd?: boolean
 }
 
 type OfferCallback = (offer: AcceptedOffer, customer: DirectCustomer | null) => Promise<void> | void
@@ -755,6 +764,8 @@ export interface CancelFlowProps extends FlowCallbacks {
   mode?: Mode
   /** See FlowConfig.i18n. */
   i18n?: I18nConfig
+  /** See FlowConfig.cancelAtPeriodEnd. Local mode only; the token config wins. */
+  cancelAtPeriodEnd?: boolean
   appearance?: Appearance
   classNames?: StructuralClassNames
   components?: Partial<ComponentOverrides>
diff --git a/packages/react/tests/components/cancel-flow.test.tsx b/packages/react/tests/components/cancel-flow.test.tsx
index 785f590..befaaf4 100644
--- a/packages/react/tests/components/cancel-flow.test.tsx
+++ b/packages/react/tests/components/cancel-flow.test.tsx
@@ -545,3 +545,40 @@ describe('CancelFlow i18n', () => {
     expect(screen.getByText(/Your access continues until (June 30|July 1), 2026\./)).toBeInTheDocument()
   })
 })
+
+describe('local-mode timing declaration', () => {
+  const timingSteps: Step[] = [{ type: 'confirm' }]
+  const i18n = {
+    messages: {
+      en: { confirm: { cta: { immediate: 'Cancel now', atPeriodEnd: 'Turn off auto-renew' } } },
+    },
+  }
+
+  it('cancelAtPeriodEnd={false} selects the immediate variant in local mode', () => {
+    renderFlow({ steps: timingSteps, cancelAtPeriodEnd: false, i18n })
+    expect(screen.getByText('Cancel now')).toBeInTheDocument()
+    expect(screen.queryByText(/access continues until/i)).not.toBeInTheDocument()
+  })
+
+  it('cancelAtPeriodEnd={true} selects the period-end variant and renders the notice', () => {
+    // appId + customer are required for subscriptions to reach flow state —
+    // the notice needs the current period end from there.
+    renderFlow({
+      steps: timingSteps,
+      cancelAtPeriodEnd: true,
+      i18n,
+      appId: 'app_test',
+      customer: { id: 'cus_1' },
+      subscriptions: [
+        {
+          id: 'sub_1',
+          start: '2024-01-01',
+          status: { name: 'active', currentPeriod: { start: '2026-06-01', end: '2026-07-01' } },
+          items: [{ price: { id: 'p', amount: { value: 100, currency: 'USD' } } }],
+        },
+      ],
+    })
+    expect(screen.getByText('Turn off auto-renew')).toBeInTheDocument()
+    expect(screen.getByText(/Your access continues until (June 30|July 1), 2026\./)).toBeInTheDocument()
+  })
+})
diff --git a/packages/react/tests/core/machine.test.ts b/packages/react/tests/core/machine.test.ts
index 5cdd093..e64f56e 100644
--- a/packages/react/tests/core/machine.test.ts
+++ b/packages/react/tests/core/machine.test.ts
@@ -1962,3 +1962,29 @@ describe('i18n / messages', () => {
     }
   })
 })
+
+describe('local-mode cancelAtPeriodEnd declaration', () => {
+  it('threads the declared timing into state', () => {
+    for (const value of [true, false]) {
+      const machine = new CancelFlowMachine({ ...baseConfig, cancelAtPeriodEnd: value })
+      expect(machine.getSnapshot().cancelAtPeriodEnd).toBe(value)
+    }
+  })
+
+  it('stays null when undeclared', () => {
+    const machine = new CancelFlowMachine(baseConfig)
+    expect(machine.getSnapshot().cancelAtPeriodEnd).toBeNull()
+  })
+
+  it('token-mode server value overrides the local declaration', () => {
+    const machine = new CancelFlowMachine({ session: 'ck_placeholder', cancelAtPeriodEnd: true })
+    machine.initializeFromConfig(
+      sdkConfig({
+        settings: { clickToCancelEnabled: false, strictFTCComplianceEnabled: false, cancelAtPeriodEnd: false },
+      }),
+      {} as any,
+      { appId: 'a', customerId: 'c', authHash: 'h', mode: 'live' as const, issuedAt: 0 },
+    )
+    expect(machine.getSnapshot().cancelAtPeriodEnd).toBe(false)
+  })
+})

From cde7e8f7d6f312ba0eeb299c50b0bdcd5bc4820f Mon Sep 17 00:00:00 2001
From: Rob Moore <rcmoore38@gmail.com>
Date: Fri, 10 Jul 2026 16:27:37 -0400
Subject: [PATCH 4/4] Keep the local timing declaration out of token mode
 entirely
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-ups. The local cancelAtPeriodEnd declaration leaked into
token mode when the server omitted settings.cancelAtPeriodEnd, so the
displayed timing could diverge from the cancel action's own
end-of-period fallback — and contradicted the prop's documented
token-mode behavior. The declaration is now stored only in local mode;
an absent server value leaves timing unknown, whose copy default
matches the action's fallback.

Also corrects the periodEndNotice doc: empty variants only suppress via
the DEFAULTS (that's how immediate timing hides the notice) — empty
override values are dropped like any blank override, so suppression
goes through the Confirm component or classNames instead.
---
 packages/react/src/core/machine.ts        |  9 ++++++++-
 packages/react/src/core/messages.ts       |  6 +++++-
 packages/react/src/core/types.ts          |  5 +++--
 packages/react/tests/core/machine.test.ts | 20 ++++++++++++++++++++
 4 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/core/machine.ts b/packages/react/src/core/machine.ts
index 5d23195..dde8d4b 100644
--- a/packages/react/src/core/machine.ts
+++ b/packages/react/src/core/machine.ts
@@ -236,7 +236,14 @@ export class CancelFlowMachine {
     // every callback by name without a separate copy.
     this.callbacks = config
     this.resolvedMessages = buildMessages(config.i18n)
-    if (typeof config.cancelAtPeriodEnd === 'boolean') this.localCancelAtPeriodEnd = config.cancelAtPeriodEnd
+    // Local mode only — in token mode the server-resolved value is
+    // authoritative, and when the server omits it the timing must stay
+    // unknown rather than silently adopting the local claim. `null` copy
+    // reads as period-end, matching the token cancel action's fallback, so
+    // display and execution stay consistent either way.
+    if (!config.session && typeof config.cancelAtPeriodEnd === 'boolean') {
+      this.localCancelAtPeriodEnd = config.cancelAtPeriodEnd
+    }
     if (config.mode) this.configMode = config.mode
     if (config.customerAttributes) this.customerAttributes = config.customerAttributes
     if (config.appId && config.customer) {
diff --git a/packages/react/src/core/messages.ts b/packages/react/src/core/messages.ts
index 631a07b..ad1b74d 100644
--- a/packages/react/src/core/messages.ts
+++ b/packages/react/src/core/messages.ts
@@ -52,7 +52,11 @@ export interface CancelFlowMessages {
     cta: TimingAware
     goBack: string
     /** Shown between the description and the confirm button. Supports
-     *  `{periodEnd}`. An empty variant suppresses the notice. */
+     *  `{periodEnd}`. The default immediate variant is empty, which
+     *  suppresses the notice for immediate timing; empty OVERRIDE values are
+     *  dropped like any blank override, so to remove the notice entirely
+     *  replace the `Confirm` component or hide it via
+     *  `classNames.periodEndNotice`. */
     periodEndNotice: TimingAware
   }
   success: {
diff --git a/packages/react/src/core/types.ts b/packages/react/src/core/types.ts
index 94ba493..86f8f4e 100644
--- a/packages/react/src/core/types.ts
+++ b/packages/react/src/core/types.ts
@@ -709,8 +709,9 @@ export interface FlowConfig extends FlowCallbacks {
    * Local-mode declaration of your billing behavior: does cancellation take
    * effect at the end of the billing period (`true`) or immediately
    * (`false`)? Drives timing-aware messages and the confirm step's
-   * access-until notice. In token mode the server-resolved value is
-   * authoritative and this is ignored.
+   * access-until notice. In token mode this is ignored: the server-resolved
+   * value is authoritative, and if the server omits it the timing is treated
+   * as unknown rather than falling back to this declaration.
    */
   cancelAtPeriodEnd?: boolean
 }
diff --git a/packages/react/tests/core/machine.test.ts b/packages/react/tests/core/machine.test.ts
index e64f56e..baf4cf2 100644
--- a/packages/react/tests/core/machine.test.ts
+++ b/packages/react/tests/core/machine.test.ts
@@ -1988,3 +1988,23 @@ describe('local-mode cancelAtPeriodEnd declaration', () => {
     expect(machine.getSnapshot().cancelAtPeriodEnd).toBe(false)
   })
 })
+
+// Pavel's review on #34: the local declaration must not leak into token mode
+// even when the server omits settings.cancelAtPeriodEnd — display would
+// otherwise diverge from the cancel action's own end-of-period fallback.
+describe('token mode ignores the local timing declaration', () => {
+  it('stays null when the server omits cancelAtPeriodEnd despite a local declaration', () => {
+    const machine = new CancelFlowMachine({ session: 'ck_placeholder', cancelAtPeriodEnd: false })
+    machine.initializeFromConfig(
+      sdkConfig({ settings: { clickToCancelEnabled: false, strictFTCComplianceEnabled: false } }),
+      {} as any,
+      { appId: 'a', customerId: 'c', authHash: 'h', mode: 'live' as const, issuedAt: 0 },
+    )
+    expect(machine.getSnapshot().cancelAtPeriodEnd).toBeNull()
+  })
+
+  it('stays null pre-fetch in token mode', () => {
+    const machine = new CancelFlowMachine({ session: 'ck_placeholder', cancelAtPeriodEnd: false })
+    expect(machine.getSnapshot().cancelAtPeriodEnd).toBeNull()
+  })
+})