From c009c4ff9fd8d1b8f63345c80d65cb24819ebf58 Mon Sep 17 00:00:00 2001
From: christianmat <christian_mathiesen@alumni.brown.edu>
Date: Thu, 21 May 2026 16:17:57 -0700
Subject: [PATCH 1/2] fix: render URI buttons as native anchors to avoid mobile
 popup blocker
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Primary/secondary buttons whose step exposes a URI used to navigate via
window.open() after awaiting step.complete. iOS Safari and Chrome Android
only honor window.open(_, '_blank') when it runs synchronously inside the
user gesture — any await breaks that gesture chain and the new tab is
silently dropped, so users see the flow complete but no tab opens.

The buttons now render as <a href target rel="noopener noreferrer"> so
the browser handles navigation natively, which is never popup-blocked.
The button's onClick still fires step.complete for analytics/state.

When the consumer overrides the navigate prop (e.g. next/router.push),
the button keeps rendering as <button> so the custom handler still runs
exactly as before. Visual styling is unchanged — computed text styles
(font, size, weight, line height) are pixel-identical and the base
button styles now explicitly set cursor:pointer and text-decoration:none
so the anchor matches the button in every browser.

Storybook stories added under Components/Announcement:
PrimaryButtonAsLink (renders as <a>) and
PrimaryButtonLinkWithCustomNavigate (renders as <button>).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .changeset/fix-link-button-mobile.md          |   5 +
 .../Announcement/Announcement.stories.tsx     |  91 ++++++++-
 .../src/components/Announcement/index.tsx     |   8 +-
 .../react/src/components/Banner/index.tsx     |  12 +-
 .../src/components/Button/Button.styles.ts    |   2 +
 .../react/src/components/Card/FlowCard.tsx    |  12 +-
 .../src/components/Checklist/CarouselStep.tsx |   9 +-
 .../src/components/Checklist/Collapsible.tsx  |  17 +-
 .../src/components/Checklist/FloatingStep.tsx |   9 +-
 .../react/src/components/Flow/FlowProps.ts    |  17 +-
 packages/react/src/components/Flow/index.tsx  |  11 +-
 .../src/components/Provider/FrigadeContext.ts |   2 +
 .../src/components/Provider/Provider.tsx      |   2 +
 .../react/src/components/Tour/TourStep.tsx    |  10 +-
 packages/react/src/hooks/useStepHandlers.ts   | 188 ++++++++++++------
 15 files changed, 306 insertions(+), 89 deletions(-)
 create mode 100644 .changeset/fix-link-button-mobile.md

diff --git a/.changeset/fix-link-button-mobile.md b/.changeset/fix-link-button-mobile.md
new file mode 100644
index 00000000..ad5be4cc
--- /dev/null
+++ b/.changeset/fix-link-button-mobile.md
@@ -0,0 +1,5 @@
+---
+"@frigade/react": patch
+---
+
+Fix mobile popup-blocker swallowing primary/secondary button link clicks. When a step exposes `primaryButton.uri` (or the legacy `primaryButtonUri`) and the consumer hasn't overridden the `navigate` prop, the button now renders as a native `<a href target rel>` so the browser handles navigation directly. Previously the click triggered `window.open` after an awaited `step.complete`, which iOS Safari and Chrome Android silently block as a popup because the user-gesture context was lost. Buttons without a URI, and buttons under a custom `navigate` handler, are unchanged. Visual styling is identical.
diff --git a/apps/smithy/src/stories/Announcement/Announcement.stories.tsx b/apps/smithy/src/stories/Announcement/Announcement.stories.tsx
index 1e99149e..9f36327b 100644
--- a/apps/smithy/src/stories/Announcement/Announcement.stories.tsx
+++ b/apps/smithy/src/stories/Announcement/Announcement.stories.tsx
@@ -1,4 +1,11 @@
-import { Announcement, Tour, useFlow, useFrigade } from "@frigade/react";
+import {
+  Announcement,
+  FrigadeJS,
+  Provider,
+  Tour,
+  useFlow,
+  useFrigade,
+} from "@frigade/react";
 import { useEffect } from "react";
 
 export default {
@@ -15,6 +22,88 @@ export const Default = {
   },
 };
 
+// TEMP verification harness for the mobile popup-blocker fix. Uses __readOnly
+// + __flowStateOverrides to mock an Announcement whose primary CTA opens a
+// URL in a new tab. With the fix in place, the primary button renders as
+// `<a href target="_blank" rel="noopener noreferrer">` so mobile browsers
+// don't block the popup.
+const MOCK_FLOW_ID = "flow_mock_link_button";
+const linkButtonFlowOverride = {
+  [MOCK_FLOW_ID]: {
+    flowSlug: MOCK_FLOW_ID,
+    flowName: "Link Button Repro",
+    flowType: FrigadeJS.FlowType.ANNOUNCEMENT,
+    data: {
+      steps: [
+        {
+          id: "step-one",
+          title: "Payment links are here",
+          subtitle: "Now you can create an order and send your customers a link to pay through multiplate.",
+          primaryButton: {
+            title: "Learn more",
+            uri: "https://example.com/learn-more",
+            target: "_blank",
+          },
+          secondaryButton: { title: "Dismiss" },
+          $state: {
+            completed: false,
+            started: false,
+            visible: true,
+            blocked: false,
+            skipped: false,
+          },
+        },
+      ],
+    },
+    $state: {
+      currentStepId: "step-one",
+      visible: true,
+      started: false,
+      completed: false,
+      skipped: false,
+      currentStepIndex: 0,
+    },
+  },
+};
+
+export const PrimaryButtonAsLink = {
+  args: { flowId: MOCK_FLOW_ID, modal: true, dismissible: true },
+  decorators: [
+    (Story, { args }) => (
+      <Provider
+        apiKey="api_storybook_mock_link_button"
+        userId="storybook_mock_user"
+        __readOnly={true}
+        __flowStateOverrides={linkButtonFlowOverride}
+      >
+        <Story {...args} />
+      </Provider>
+    ),
+  ],
+};
+
+// Same mock flow, but with a custom navigate handler — should fall back to
+// rendering as <button> so the consumer's navigate gets called as before.
+export const PrimaryButtonLinkWithCustomNavigate = {
+  args: { flowId: MOCK_FLOW_ID, modal: true, dismissible: true },
+  decorators: [
+    (Story, { args }) => (
+      <Provider
+        apiKey="api_storybook_mock_link_button_custom_nav"
+        userId="storybook_mock_user_2"
+        __readOnly={true}
+        __flowStateOverrides={linkButtonFlowOverride}
+        navigate={(url, target) => {
+          console.log("custom navigate:", url, target);
+          window.open(url, target);
+        }}
+      >
+        <Story {...args} />
+      </Provider>
+    ),
+  ],
+};
+
 export const TestReset = {
   args: {
     dismissible: true,
diff --git a/packages/react/src/components/Announcement/index.tsx b/packages/react/src/components/Announcement/index.tsx
index 1222aba6..62c2d18f 100644
--- a/packages/react/src/components/Announcement/index.tsx
+++ b/packages/react/src/components/Announcement/index.tsx
@@ -25,8 +25,8 @@ export function Announcement({ flowId, ...props }: AnnouncementProps) {
       {({
         flow,
         handleDismiss,
-        handlePrimary,
-        handleSecondary,
+        primaryButtonProps,
+        secondaryButtonProps,
         parentProps: { containerProps, dismissible },
         step,
       }) => {
@@ -82,15 +82,15 @@ export function Announcement({ flowId, ...props }: AnnouncementProps) {
               {secondaryButtonTitle && (
                 <Dialog.Secondary
                   disabled={disabled}
-                  onClick={handleSecondary}
                   title={secondaryButtonTitle}
+                  {...secondaryButtonProps}
                 />
               )}
               {primaryButtonTitle && (
                 <Dialog.Primary
                   disabled={disabled}
-                  onClick={handlePrimary}
                   title={primaryButtonTitle}
+                  {...primaryButtonProps}
                 />
               )}
             </Flex.Row>
diff --git a/packages/react/src/components/Banner/index.tsx b/packages/react/src/components/Banner/index.tsx
index 25a17f19..eb2c586d 100644
--- a/packages/react/src/components/Banner/index.tsx
+++ b/packages/react/src/components/Banner/index.tsx
@@ -10,8 +10,8 @@ export function Banner({ flowId, ...props }: BannerProps) {
     <Flow as={null} flowId={flowId} {...props}>
       {({
         handleDismiss,
-        handlePrimary,
-        handleSecondary,
+        primaryButtonProps,
+        secondaryButtonProps,
         parentProps: { containerProps, dismissible },
         step,
       }) => {
@@ -51,9 +51,13 @@ export function Banner({ flowId, ...props }: BannerProps) {
             <Card.Secondary
               disabled={disabled}
               title={secondaryButtonTitle}
-              onClick={handleSecondary}
+              {...secondaryButtonProps}
+            />
+            <Card.Primary
+              disabled={disabled}
+              title={primaryButtonTitle}
+              {...primaryButtonProps}
             />
-            <Card.Primary disabled={disabled} title={primaryButtonTitle} onClick={handlePrimary} />
             {dismissible && <Card.Dismiss onClick={handleDismiss} />}
           </Card>
         )
diff --git a/packages/react/src/components/Button/Button.styles.ts b/packages/react/src/components/Button/Button.styles.ts
index d9a6c29a..a1230969 100644
--- a/packages/react/src/components/Button/Button.styles.ts
+++ b/packages/react/src/components/Button/Button.styles.ts
@@ -5,11 +5,13 @@ const base = {
   borderWidth: 'md',
   borderRadius: 'md',
   borderStyle: 'solid',
+  cursor: 'pointer',
   'cursor:disabled': 'not-allowed',
   display: 'flex',
   gap: '2',
   padding: '2 4',
   fontFamily: 'inherit',
+  textDecoration: 'none',
 
   'opacity:disabled': '0.6',
   'pointerEvents:disabled': 'none',
diff --git a/packages/react/src/components/Card/FlowCard.tsx b/packages/react/src/components/Card/FlowCard.tsx
index 015e8e44..a9ce22d3 100644
--- a/packages/react/src/components/Card/FlowCard.tsx
+++ b/packages/react/src/components/Card/FlowCard.tsx
@@ -15,7 +15,13 @@ export function FlowCard({ part, ...props }: FlowProps) {
       part={['card', part]}
       {...props}
     >
-      {({ handleDismiss, handlePrimary, handleSecondary, parentProps: { dismissible }, step }) => {
+      {({
+        handleDismiss,
+        primaryButtonProps,
+        secondaryButtonProps,
+        parentProps: { dismissible },
+        step,
+      }) => {
         const primaryButtonTitle = step.primaryButton?.title ?? step.primaryButtonTitle
         const secondaryButtonTitle = step.secondaryButton?.title ?? step.secondaryButtonTitle
 
@@ -38,8 +44,8 @@ export function FlowCard({ part, ...props }: FlowProps) {
             />
 
             <Flex.Row gap={3} justifyContent="flex-end" part="card-footer">
-              <Card.Secondary title={secondaryButtonTitle} onClick={handleSecondary} />
-              <Card.Primary title={primaryButtonTitle} onClick={handlePrimary} />
+              <Card.Secondary title={secondaryButtonTitle} {...secondaryButtonProps} />
+              <Card.Primary title={primaryButtonTitle} {...primaryButtonProps} />
             </Flex.Row>
           </>
         )
diff --git a/packages/react/src/components/Checklist/CarouselStep.tsx b/packages/react/src/components/Checklist/CarouselStep.tsx
index 04da823d..87243a03 100644
--- a/packages/react/src/components/Checklist/CarouselStep.tsx
+++ b/packages/react/src/components/Checklist/CarouselStep.tsx
@@ -15,7 +15,10 @@ interface CarouselStepProps {
 }
 
 export function CarouselStep({ onPrimary, onSecondary, step }: CarouselStepProps) {
-  const { handlePrimary, handleSecondary } = useStepHandlers(step, { onPrimary, onSecondary })
+  const { primaryButtonProps, secondaryButtonProps } = useStepHandlers(step, {
+    onPrimary,
+    onSecondary,
+  })
 
   const { blocked, completed, skipped } = step.$state
 
@@ -78,13 +81,13 @@ export function CarouselStep({ onPrimary, onSecondary, step }: CarouselStepProps
       >
         <Card.Secondary
           disabled={blocked}
-          onClick={handleSecondary}
           title={step.secondaryButton?.title}
+          {...secondaryButtonProps}
         />
         <Card.Primary
           disabled={blocked}
-          onClick={handlePrimary}
           title={step.primaryButton?.title}
+          {...primaryButtonProps}
         />
       </Flex.Row>
     </Card>
diff --git a/packages/react/src/components/Checklist/Collapsible.tsx b/packages/react/src/components/Checklist/Collapsible.tsx
index b93f23bd..4e666c69 100644
--- a/packages/react/src/components/Checklist/Collapsible.tsx
+++ b/packages/react/src/components/Checklist/Collapsible.tsx
@@ -54,8 +54,8 @@ export interface CollapsibleProps extends FlowPropsWithoutChildren {
 }
 
 function DefaultCollapsibleStep({
-  handlePrimary,
-  handleSecondary,
+  primaryButtonProps,
+  secondaryButtonProps,
   open,
   onOpenChange,
   step,
@@ -100,8 +100,12 @@ function DefaultCollapsibleStep({
         />
         <Card.Subtitle color="neutral.400">{subtitle}</Card.Subtitle>
         <Flex.Row gap={3} part="collapsible-footer">
-          <Card.Secondary title={secondaryButtonTitle} onClick={handleSecondary} />
-          <Card.Primary disabled={disabled} title={primaryButtonTitle} onClick={handlePrimary} />
+          <Card.Secondary title={secondaryButtonTitle} {...secondaryButtonProps} />
+          <Card.Primary
+            disabled={disabled}
+            title={primaryButtonTitle}
+            {...primaryButtonProps}
+          />
         </Flex.Row>
       </CollapsibleStep.Content>
     </CollapsibleStep.Root>
@@ -115,7 +119,8 @@ const defaultStepTypes = {
 function StepWrapper({ flow, step, ...props }: FlowChildrenProps) {
   const { onPrimary, onSecondary, openStepId, setOpenStepId, stepTypes } =
     useContext(CollapsibleContext)
-  const { handlePrimary, handleSecondary } = useStepHandlers(step, { onPrimary, onSecondary })
+  const { handlePrimary, handleSecondary, primaryButtonProps, secondaryButtonProps } =
+    useStepHandlers(step, { onPrimary, onSecondary })
 
   const open = (openStepId ?? flow.getCurrentStep().id) === step.id
 
@@ -141,6 +146,8 @@ function StepWrapper({ flow, step, ...props }: FlowChildrenProps) {
       {...props}
       handlePrimary={handlePrimary}
       handleSecondary={handleSecondary}
+      primaryButtonProps={primaryButtonProps}
+      secondaryButtonProps={secondaryButtonProps}
     />
   )
 }
diff --git a/packages/react/src/components/Checklist/FloatingStep.tsx b/packages/react/src/components/Checklist/FloatingStep.tsx
index 2d71bbef..3a2160f1 100644
--- a/packages/react/src/components/Checklist/FloatingStep.tsx
+++ b/packages/react/src/components/Checklist/FloatingStep.tsx
@@ -13,7 +13,8 @@ import { floatingTransitionCSS } from '@/components/Checklist/Floating.styles'
 
 export function FloatingStep({ onPrimary, onSecondary, openStepId, setOpenStepId, step }) {
   const anchorPointerEnterTimeout = useRef<ReturnType<typeof setTimeout>>()
-  const { handlePrimary, handleSecondary } = useStepHandlers(step, { onPrimary, onSecondary })
+  const { handlePrimary, handleSecondary, primaryButtonProps, secondaryButtonProps } =
+    useStepHandlers(step, { onPrimary, onSecondary })
 
   const isStepOpen = openStepId === step.id
 
@@ -90,15 +91,17 @@ export function FloatingStep({ onPrimary, onSecondary, openStepId, setOpenStepId
           <Flex.Row gap={3} justifyContent="flex-end" part="card-footer">
             <Card.Secondary
               disabled={step.$state.blocked}
-              onClick={wrappedHandleSecondary}
               padding="1 2"
               title={secondaryButtonTitle}
+              {...secondaryButtonProps}
+              onClick={wrappedHandleSecondary}
             />
             <Card.Primary
               disabled={step.$state.blocked}
-              onClick={wrappedHandlePrimary}
               padding="1 2"
               title={primaryButtonTitle}
+              {...primaryButtonProps}
+              onClick={wrappedHandlePrimary}
             />
           </Flex.Row>
         </Card>
diff --git a/packages/react/src/components/Flow/FlowProps.ts b/packages/react/src/components/Flow/FlowProps.ts
index 2365e734..caae08fd 100644
--- a/packages/react/src/components/Flow/FlowProps.ts
+++ b/packages/react/src/components/Flow/FlowProps.ts
@@ -5,7 +5,11 @@ import type { Flow as FlowType, FlowStep } from '@frigade/js'
 import type { BoxProps } from '@/components/Box'
 
 import type { DismissHandler, FlowHandlerProp } from '@/hooks/useFlowHandlers'
-import type { StepHandler, StepHandlerProp } from '@/hooks/useStepHandlers'
+import type {
+  ButtonLinkProps,
+  StepHandler,
+  StepHandlerProp,
+} from '@/hooks/useStepHandlers'
 
 export interface BoxPropsWithoutChildren extends Omit<BoxProps, 'children'> {}
 
@@ -93,6 +97,17 @@ export interface FlowChildrenProps {
   handleDismiss: DismissHandler
   handlePrimary: StepHandler
   handleSecondary: StepHandler
+  /**
+   * Props to spread on the primary button component. When the step exposes a
+   * URI and the consumer hasn't overridden `navigate`, these include
+   * `as="a" href target rel` so the rendered element is a native anchor —
+   * native anchor clicks are not subject to mobile popup blocking.
+   */
+  primaryButtonProps: { onClick: StepHandler } & ButtonLinkProps
+  /**
+   * Props to spread on the secondary button component. See `primaryButtonProps`.
+   */
+  secondaryButtonProps: { onClick: StepHandler } & ButtonLinkProps
   parentProps: ParentProps
   step: FlowStep
 }
diff --git a/packages/react/src/components/Flow/index.tsx b/packages/react/src/components/Flow/index.tsx
index 88a1eda5..dfa03ab6 100644
--- a/packages/react/src/components/Flow/index.tsx
+++ b/packages/react/src/components/Flow/index.tsx
@@ -64,10 +64,11 @@ export function Flow({
     onDismiss,
   })
 
-  const { handlePrimary, handleSecondary } = useStepHandlers(step, {
-    onPrimary,
-    onSecondary,
-  })
+  const { handlePrimary, handleSecondary, primaryButtonProps, secondaryButtonProps } =
+    useStepHandlers(step, {
+      onPrimary,
+      onSecondary,
+    })
 
   const isModal =
     mergedProps?.modal ||
@@ -153,6 +154,8 @@ export function Flow({
         handleDismiss,
         handlePrimary,
         handleSecondary,
+        primaryButtonProps,
+        secondaryButtonProps,
         parentProps: {
           as,
           dismissible,
diff --git a/packages/react/src/components/Provider/FrigadeContext.ts b/packages/react/src/components/Provider/FrigadeContext.ts
index a04ec85e..6f2ccc0d 100644
--- a/packages/react/src/components/Provider/FrigadeContext.ts
+++ b/packages/react/src/components/Provider/FrigadeContext.ts
@@ -7,6 +7,7 @@ export interface ProviderContext extends Omit<ProviderProps, 'children' | 'theme
   currentModal: string | null
   setCurrentModal: Dispatch<SetStateAction<string | null>>
   frigade?: Frigade
+  hasCustomNavigate: boolean
   hasInitialized: boolean
   registerComponent: (flowId: string, callback?: CollectionsRegistryCallback) => void
   unregisterComponent: (flowId: string) => void
@@ -18,6 +19,7 @@ export const FrigadeContext = createContext<ProviderContext>({
   currentModal: null,
   setCurrentModal: () => {},
   navigate: () => {},
+  hasCustomNavigate: false,
   hasInitialized: false,
   registerComponent: () => {},
   unregisterComponent: () => {},
diff --git a/packages/react/src/components/Provider/Provider.tsx b/packages/react/src/components/Provider/Provider.tsx
index 64bce88a..c41f5dd9 100644
--- a/packages/react/src/components/Provider/Provider.tsx
+++ b/packages/react/src/components/Provider/Provider.tsx
@@ -233,6 +233,7 @@ export function Provider({
     }
   }
 
+  const hasCustomNavigate = navigate != null
   const navigateHandler =
     navigate ??
     ((url, target = '_self') => {
@@ -251,6 +252,7 @@ export function Provider({
         currentModal,
         setCurrentModal,
         navigate: navigateHandler,
+        hasCustomNavigate,
         ...props,
         frigade: frigade,
         registerComponent,
diff --git a/packages/react/src/components/Tour/TourStep.tsx b/packages/react/src/components/Tour/TourStep.tsx
index cb050950..38624be0 100644
--- a/packages/react/src/components/Tour/TourStep.tsx
+++ b/packages/react/src/components/Tour/TourStep.tsx
@@ -45,7 +45,7 @@ export function TourStep({
   step,
   ...props
 }: TourStepProps) {
-  const { handlePrimary, handleSecondary } = useStepHandlers(step, {
+  const { primaryButtonProps, secondaryButtonProps } = useStepHandlers(step, {
     onPrimary,
     onSecondary,
   })
@@ -118,10 +118,14 @@ export function TourStep({
           )}
           <Card.Secondary
             disabled={disabled}
-            onClick={handleSecondary}
             title={secondaryButtonTitle}
+            {...secondaryButtonProps}
+          />
+          <Card.Primary
+            disabled={disabled}
+            title={primaryButtonTitle}
+            {...primaryButtonProps}
           />
-          <Card.Primary disabled={disabled} onClick={handlePrimary} title={primaryButtonTitle} />
         </Card.Footer>
       </Card>
     </Hint>
diff --git a/packages/react/src/hooks/useStepHandlers.ts b/packages/react/src/hooks/useStepHandlers.ts
index 7af5828a..62e6572d 100644
--- a/packages/react/src/hooks/useStepHandlers.ts
+++ b/packages/react/src/hooks/useStepHandlers.ts
@@ -32,8 +32,49 @@ export type StepHandler = (
   optimistic?: boolean
 ) => Promise<boolean>
 
+export interface ButtonLinkProps {
+  as?: 'a'
+  href?: string
+  target?: string
+  rel?: string
+}
+
+function getPrimaryUri(step: FlowStep): { uri?: string; target?: string } {
+  if (step == null) return {}
+  if (step.primaryButton != null) {
+    return { uri: step.primaryButton.uri, target: step.primaryButton.target }
+  }
+  return { uri: step.primaryButtonUri, target: step.primaryButtonUriTarget }
+}
+
+function getSecondaryUri(step: FlowStep): { uri?: string; target?: string } {
+  if (step == null) return {}
+  if (step.secondaryButton != null) {
+    return { uri: step.secondaryButton.uri, target: step.secondaryButton.target }
+  }
+  return { uri: step.secondaryButtonUri, target: step.secondaryButtonUriTarget }
+}
+
+// When the step exposes a URI and the consumer hasn't overridden `navigate`,
+// render the button as a native anchor. Mobile browsers (Safari iOS, Chrome
+// Android) only allow `window.open(_, '_blank')` when it runs synchronously in
+// a user gesture — the awaited step.complete call breaks that gesture chain
+// and the new tab is silently blocked. A real <a href target="_blank"> click
+// is never popup-blocked.
+function getLinkProps(uri: string | undefined, target: string | undefined): ButtonLinkProps {
+  if (uri == null) return {}
+  const linkProps: ButtonLinkProps = { as: 'a', href: uri }
+  if (target != null) {
+    linkProps.target = target
+    if (target === '_blank') {
+      linkProps.rel = 'noopener noreferrer'
+    }
+  }
+  return linkProps
+}
+
 export function useStepHandlers(step: FlowStep, { onPrimary, onSecondary }: StepHandlerProps = {}) {
-  const { navigate } = useContext(FrigadeContext)
+  const { navigate, hasCustomNavigate } = useContext(FrigadeContext)
 
   const stepActions = useMemo(
     () =>
@@ -56,75 +97,106 @@ export function useStepHandlers(step: FlowStep, { onPrimary, onSecondary }: Step
     [step]
   )
 
-  return {
-    handlePrimary: useCallback<StepHandler>(
-      async (e, properties, optimistic = true) => {
-        const continueDefault = await onPrimary?.(step, e, properties)
-        if (continueDefault === false) {
-          e.preventDefault()
-          return false
+  const { uri: primaryUri, target: primaryTarget } = getPrimaryUri(step)
+  const { uri: secondaryUri, target: secondaryTarget } = getSecondaryUri(step)
+
+  // Render as anchor only when we own the navigation. If the consumer passed a
+  // custom `navigate` (e.g. next/router.push), they expect that callback to
+  // run — fall back to the legacy button + onClick path so their behavior is
+  // preserved.
+  const renderPrimaryAsLink = primaryUri != null && !hasCustomNavigate
+  const renderSecondaryAsLink = secondaryUri != null && !hasCustomNavigate
+
+  const handlePrimary = useCallback<StepHandler>(
+    async (e, properties, optimistic = true) => {
+      const continueDefault = await onPrimary?.(step, e, properties)
+      if (continueDefault === false) {
+        e.preventDefault()
+        return false
+      }
+
+      if (step.primaryButton != null) {
+        const primaryAction =
+          step.primaryButton.action === false ? false : stepActions[step.primaryButton.action]
+
+        if (typeof primaryAction === 'function') {
+          await primaryAction(properties, optimistic)
+        } else if (primaryAction !== false) {
+          await step.complete(properties, optimistic)
         }
 
-        if (step.primaryButton != null) {
-          const primaryAction =
-            step.primaryButton.action === false ? false : stepActions[step.primaryButton.action]
+        if (step.primaryButton.uri != null && !renderPrimaryAsLink) {
+          navigate(step.primaryButton.uri, step.primaryButton.target)
+        }
+      } else {
+        await step.complete(properties, optimistic)
 
-          if (typeof primaryAction === 'function') {
-            await primaryAction(properties, optimistic)
-          } else if (primaryAction !== false) {
-            await step.complete(properties, optimistic)
-          }
+        if (step.primaryButtonUri != null && !renderPrimaryAsLink) {
+          navigate(step.primaryButtonUri, step.primaryButtonUriTarget)
+        }
+      }
 
-          if (step.primaryButton.uri != null) {
-            navigate(step.primaryButton.uri, step.primaryButton.target)
-          }
-        } else {
-          await step.complete(properties, optimistic)
+      return true
+    },
+    [navigate, onPrimary, renderPrimaryAsLink, step, stepActions]
+  )
 
-          if (step.primaryButtonUri != null) {
-            navigate(step.primaryButtonUri, step.primaryButtonUriTarget)
-          }
-        }
+  const handleSecondary = useCallback<StepHandler>(
+    async (e, properties) => {
+      const continueDefault = await onSecondary?.(step, e, properties)
 
-        return true
-      },
-      [navigate, onPrimary, step, stepActions]
-    ),
+      if (continueDefault === false) {
+        e.preventDefault()
+        return false
+      }
 
-    handleSecondary: useCallback<StepHandler>(
-      async (e, properties) => {
-        const continueDefault = await onSecondary?.(step, e, properties)
+      if (step.secondaryButton != null) {
+        const secondaryAction =
+          step.secondaryButton.action === false ? false : stepActions[step.secondaryButton.action]
 
-        if (continueDefault === false) {
-          e.preventDefault()
-          return false
+        if (typeof secondaryAction === 'function') {
+          secondaryAction()
+        } else if (secondaryAction !== false) {
+          step.complete(properties)
         }
 
-        if (step.secondaryButton != null) {
-          const secondaryAction =
-            step.secondaryButton.action === false ? false : stepActions[step.secondaryButton.action]
-
-          if (typeof secondaryAction === 'function') {
-            secondaryAction()
-          } else if (secondaryAction !== false) {
-            step.complete(properties)
-          }
-
-          if (step.secondaryButton.uri != null) {
-            navigate(step.secondaryButton.uri, step.secondaryButton.target)
-          }
-        } else {
-          // Should there be a step.skip method?
-          step.complete(properties)
+        if (step.secondaryButton.uri != null && !renderSecondaryAsLink) {
+          navigate(step.secondaryButton.uri, step.secondaryButton.target)
+        }
+      } else {
+        // Should there be a step.skip method?
+        step.complete(properties)
 
-          if (step.secondaryButtonUri != null) {
-            navigate(step.secondaryButtonUri, step.secondaryButtonUriTarget)
-          }
+        if (step.secondaryButtonUri != null && !renderSecondaryAsLink) {
+          navigate(step.secondaryButtonUri, step.secondaryButtonUriTarget)
         }
+      }
 
-        return true
-      },
-      [navigate, onSecondary, step, stepActions]
-    ),
+      return true
+    },
+    [navigate, onSecondary, renderSecondaryAsLink, step, stepActions]
+  )
+
+  const primaryButtonProps = useMemo(
+    () => ({
+      onClick: handlePrimary,
+      ...(renderPrimaryAsLink ? getLinkProps(primaryUri, primaryTarget) : {}),
+    }),
+    [handlePrimary, primaryTarget, primaryUri, renderPrimaryAsLink]
+  )
+
+  const secondaryButtonProps = useMemo(
+    () => ({
+      onClick: handleSecondary,
+      ...(renderSecondaryAsLink ? getLinkProps(secondaryUri, secondaryTarget) : {}),
+    }),
+    [handleSecondary, renderSecondaryAsLink, secondaryTarget, secondaryUri]
+  )
+
+  return {
+    handlePrimary,
+    handleSecondary,
+    primaryButtonProps,
+    secondaryButtonProps,
   }
 }

From e2e4fcdb650cc5872db186a3ee0d801198394402 Mon Sep 17 00:00:00 2001
From: christianmat <christian_mathiesen@alumni.brown.edu>
Date: Fri, 22 May 2026 09:26:19 -0700
Subject: [PATCH 2/2] fix: include anchors in flex-sizing selectors in
 announcement and carousel

The footer CSS used `& > button { flex-basis: 50%; flex-grow: 1 }` to make
primary and secondary share the row evenly. When the primary renders as
an anchor (the link-button path) the selector misses it and only the
button-shaped secondary gets the 50/50 rule, so the anchor shrinks to its
content width and the button stretches to fill the rest.

Match `& > button, & > a` so both element types size identically.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/react/src/components/Announcement/index.tsx     | 2 +-
 packages/react/src/components/Checklist/CarouselStep.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/components/Announcement/index.tsx b/packages/react/src/components/Announcement/index.tsx
index 62c2d18f..84d9067c 100644
--- a/packages/react/src/components/Announcement/index.tsx
+++ b/packages/react/src/components/Announcement/index.tsx
@@ -71,7 +71,7 @@ export function Announcement({ flowId, ...props }: AnnouncementProps) {
 
             <Flex.Row
               css={{
-                '& > button': {
+                '& > button, & > a': {
                   flexBasis: '50%',
                   flexGrow: 1,
                 },
diff --git a/packages/react/src/components/Checklist/CarouselStep.tsx b/packages/react/src/components/Checklist/CarouselStep.tsx
index 87243a03..e88820cd 100644
--- a/packages/react/src/components/Checklist/CarouselStep.tsx
+++ b/packages/react/src/components/Checklist/CarouselStep.tsx
@@ -66,7 +66,7 @@ export function CarouselStep({ onPrimary, onSecondary, step }: CarouselStepProps
       <Flex.Row
         css={{
           '@container (max-width: 200px)': {
-            '& > button': {
+            '& > button, & > a': {
               flexBasis: '50%',
               flexGrow: 1,
             },