@fanfare-io/fanfare-sdk-react 0.11.0 → 0.13.0

package/dist/components/checkout/checkout-processing-panel.d.ts

@@ -0,0 +1,10 @@
+import { CheckoutProcessingSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * Default processing panel shown for the gap between a submitted reservation checkout and the
+ * server's confirmation.
+ *
+ * The consumer must not navigate away while the payment settles, so the wait is announced rather
+ * than shown only as motion.
+ */
+export declare function CheckoutProcessingPanel(_props: CheckoutProcessingSlotProps): React.ReactElement;

package/dist/components/checkout/index.d.ts

@@ -0,0 +1,4 @@
+export { CheckoutProcessingPanel } from './checkout-processing-panel';
+export { PaymentCollectionPanel } from './payment-collection-panel';
+export { ReceiptPanel } from './receipt-panel';
+export { ReservationCheckoutPanel } from './reservation-checkout-panel';

package/dist/components/checkout/payment-collection-panel.d.ts

@@ -0,0 +1,18 @@
+import { PaymentCollectionSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * Default payment-collection panel for pre-auth distributions, rendered both when the consumer is
+ * about to enter and when a failed authorization leaves a retry open.
+ *
+ * The hold amount is rendered from the view's own figure — the client never derives one.
+ *
+ * The configuration block reaches this panel on the entry mount only. A retry is offered from an
+ * ended view, which carries none, so that mount renders payment as unavailable and a consumer with
+ * a saved method submits without needing Stripe.js at all.
+ *
+ * Entry has no server-side resume: a paused authorization is carried forward by submitting the
+ * identical payment input again, held here from the first submit, so exactly one payment method is
+ * minted across the whole flow. An ended view carries no pending action, so the retry mount reaches
+ * none of this.
+ */
+export declare function PaymentCollectionPanel({ preAuthAmount, preAuthCurrencyCode, savedPaymentMethods, paymentProvider, onEnter, isEntering, intent, pendingAction, onRetryPaymentConfig, ...slotProps }: PaymentCollectionSlotProps): React.ReactElement;

package/dist/components/checkout/receipt-panel.d.ts

@@ -0,0 +1,10 @@
+import { ReceiptSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * Default panel for a completed Fanfare-managed payment.
+ *
+ * The order reference is the outcome. An admission credential appears only on the arm that carries
+ * one, and stays subordinate to the purchase: payment is terminal, so a receipt must never read as
+ * the thing that admits its holder.
+ */
+export declare function ReceiptPanel(props: ReceiptSlotProps): React.ReactElement;

package/dist/components/checkout/reservation-checkout-panel.d.ts

@@ -0,0 +1,18 @@
+import { ReservationCheckoutSlotProps } from '../widgets/experience-widget';
+import * as React from "react";
+/**
+ * Default reservation-checkout panel for post-win checkout flows.
+ *
+ * `Countdown`'s `onComplete` is a no-op: the journey machine owns the reservation's expiry (it
+ * arms its own timer and transitions the sequence to `ended` when the deadline passes), so the
+ * panel never disables itself locally — it simply stops being rendered once the phase changes.
+ *
+ * Elements renders only on the internal-processor arm. The discriminator is `processor`; an absent
+ * configuration block on that arm means the configuration read failed, which is a retryable outage
+ * inside a ticking window — never a signal that another processor is in play.
+ *
+ * A pending action adds visible substates over the same screen rather than replacing it: the card
+ * field stays mounted through the whole challenge, because a consumer whose bank prompt failed may
+ * need to submit again with the card they already typed.
+ */
+export declare function ReservationCheckoutPanel({ reservation, savedPaymentMethods, processor, paymentProvider, pendingAction, onConfirm, onResume, isConfirming, onRetryPaymentConfig, ...slotProps }: ReservationCheckoutSlotProps): React.ReactElement;

package/dist/components/checkout/stripe-card-field.d.ts

@@ -0,0 +1,29 @@
+import { StripeClientConfig } from './stripe-client';
+/**
+ * The SDK's card-entry field: a Stripe Card Element and the controller that turns it into a
+ * payment-method id. It knows nothing about reservations, pre-auth, or amounts.
+ *
+ * `@stripe/stripe-js` is a type-only dependency across the SDK, so no vendor bytes ship in any
+ * chunk. This module is the one lazy split: it is reached only through a dynamic `import()` from
+ * the panel that renders new-card entry, so the Card Element wiring stays out of the adapter's
+ * entry chunk. Nothing statically imported from `src/index.ts` may reach it.
+ *
+ * Stripe.js is unsupported inside a shadow root, and the Solid adapter's web components attach one
+ * unconditionally, so the element mounts into a container this file appends to the light DOM and
+ * positions over its in-panel anchor. The theme's custom properties do not cross the shadow
+ * boundary, so the resolved values the card style needs are copied onto that container.
+ */
+import * as React from "react";
+export interface StripeCardController {
+    /** Resolves the `pm_…` id, or rejects with an `Error` carrying already-localized copy. */
+    createPaymentMethod: () => Promise<string>;
+}
+export interface StripeCardFieldProps {
+    config: StripeClientConfig;
+    onController: (controller: StripeCardController | null) => void;
+    onChange?: (state: {
+        complete: boolean;
+        errorMessage: string | null;
+    }) => void;
+}
+export declare function StripeCardField({ config, onController, onChange }: StripeCardFieldProps): React.ReactElement;

package/dist/components/checkout/stripe-client.d.ts

@@ -0,0 +1,71 @@
+import { ReservationPaymentAffordance } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { Stripe, StripeConstructor, StripeElementStyle } from '@stripe/stripe-js';
+/**
+ * The wire block a checkout-capable view carries, reached through the adapter's declared
+ * dependency on `fanfare-sdk-core` rather than the contracts package: core re-exports the contract
+ * types so adapter modules never resolve `@fanfare-io/fanfare-sdk-contracts` directly.
+ */
+type PaymentProviderConfig = NonNullable<ReservationPaymentAffordance["paymentProvider"]>;
+declare global {
+    interface Window {
+        Stripe?: StripeConstructor;
+    }
+}
+export interface StripeClientConfig {
+    publishableKey: string;
+    stripeAccount?: string;
+}
+/**
+ * Loads Stripe.js once per page. A failure is never retained: a memoized rejection would strand
+ * every subsequent payer on the page, not just the one whose load failed. Retry is the caller's
+ * decision — this module never schedules one.
+ */
+export declare function loadStripeJs(): Promise<StripeConstructor>;
+/**
+ * One Stripe client per (publishable key, connected account). A construction that rejects drops
+ * its cache entry for the same reason the loader does.
+ */
+export declare function getStripe(config: StripeClientConfig): Promise<Stripe>;
+/**
+ * Re-serializes a theme color into the spelling a CSS color parser produces.
+ *
+ * Custom properties are untyped, so a theme color arrives from `getComputedStyle` as whatever token
+ * stream the stylesheet declared — and a minifier is free to rewrite `oklch(0.63 0.24 25)` as
+ * `oklch(63% .24 25)`. Stripe's element options go through a stricter parser than CSS's: a spelling
+ * every browser accepts can still be rejected there, and the rejection is silent — the element
+ * mounts a frame that never renders its input. The invariant this restores is that colors reach
+ * Stripe in the serialization its parser accepts.
+ *
+ * `null` means the value is not a color the parser recognizes, and the caller must omit the key
+ * rather than guess: assigning an unparsable value leaves `fillStyle` on its previous one, so
+ * emitting the read-back would emit some other color entirely. Where no parser exists — server
+ * rendering, or a DOM without canvas — the value passes through: the mismatch only arises where a
+ * real browser serializes computed styles.
+ */
+export declare function normalizeCssColor(value: string): string | null;
+/**
+ * Maps the SDK theme's resolved custom properties onto the Card Element's `style` option. Stripe's
+ * `Appearance` API governs the Elements group Payment Element consumes and does not reach the
+ * legacy Card Element, so `style` is the only theming path — there is deliberately no second one.
+ *
+ * Property names are the values of `THEME_CSS_VARS` (the adapter's `theme/theme.types.ts`), spelled
+ * literally here because this file must stay identical across adapters. `--ff-color-primary` and
+ * `--ff-color-background` have no Card Element equivalent: the element's background is the host
+ * page's, supplied by the panel around the iframe.
+ *
+ * Every color is re-serialized on the way out; a color the parser rejects is omitted, which leaves
+ * Stripe on its own default for that slot. The font stack is not a color and is forwarded as read.
+ */
+export declare function deriveStripeCardStyle(root: HTMLElement): StripeElementStyle;
+/**
+ * The one binding between a view's wire configuration and a Stripe client.
+ *
+ * `null` means no usable Stripe client configuration reached this view. On a checkout-capable arm
+ * that has exactly one cause — the configuration read failed — because the processor discriminator
+ * is the `processor` field (reserved) or `checkoutMode` (enterable), never the presence of this
+ * block. The condition is transient and retryable.
+ */
+export declare function resolveStripeClientConfig(source: PaymentProviderConfig | undefined): StripeClientConfig | null;
+/** Test-only seam over every memo this module holds. Never exported from an adapter's public entry. */
+export declare function resetStripeClientCache(): void;
+export {};

package/dist/components/checkout/use-payment-challenge.d.ts

@@ -0,0 +1,32 @@
+import { StripeClientConfig } from './stripe-client';
+/** `idle` covers both "no challenge yet" and "this attempt has settled". */
+export type PaymentChallengePhase = "idle" | "challenging" | "resuming";
+/**
+ * How the last attempt ended, when it ended badly — the fact a panel needs to offer the right way
+ * out, which the error copy alone cannot carry.
+ *
+ * - `cancelled` — the prompt ended without the card being refused: the consumer dismissed it, or the
+ *   authentication behind it failed. Reopening that same prompt is the recovery.
+ * - `declined` — the card was refused, or the prompt could not be opened at all. That secret is
+ *   spent; only a fresh submission can produce another.
+ * - `resume_failed` — the prompt succeeded and the operation behind it did not. The challenge is
+ *   answered, so the recovery is to run that operation again, never to reopen the prompt.
+ */
+export type PaymentChallengeRecovery = "cancelled" | "declined" | "resume_failed";
+export interface PaymentChallenge {
+    phase: PaymentChallengePhase;
+    /** Localized copy for the attempt that produced it; terminal until another attempt starts. */
+    error: string | null;
+    /** Set together with `error`, and cleared when the next attempt starts. */
+    recovery: PaymentChallengeRecovery | null;
+    /**
+     * Open the bank prompt for `clientSecret`. Once per secret per instance: a repeat call carrying a
+     * secret this instance already launched is a no-op, and a genuinely new secret launches again.
+     */
+    launch: (clientSecret: string, resume: () => Promise<void>) => void;
+    /** Reopen the same prompt on the consumer's own instruction, then run the same resume. */
+    retry: (clientSecret: string, resume: () => Promise<void>) => void;
+}
+/** Test-only seam. Never exported from the adapter's public entry. */
+export declare function resetPaymentChallengeState(): void;
+export declare function usePaymentChallenge(config: StripeClientConfig | null): PaymentChallenge;

package/dist/components/checkout/use-payment-method-selection.d.ts

@@ -0,0 +1,8 @@
+import { PaymentMethodSummary } from '@fanfare-io/fanfare-sdk-core/experiences';
+/**
+ * Tracks the selected saved payment method for a checkout panel. The list can still be loading on
+ * mount (nothing selected yet) or a previously selected card can be removed out from under the
+ * panel — falls back to the default method, else the first, else `undefined`, both on initial
+ * mount and whenever the list changes, so submit never carries a stale/deleted `paymentMethodId`.
+ */
+export declare function usePaymentMethodSelection(savedPaymentMethods: PaymentMethodSummary[]): [string | undefined, (id: string) => void];

package/dist/components/compositions/index.d.ts

@@ -10,6 +10,6 @@ export { JourneyGate, type JourneyGateProps, type JourneyGateStage } from './jou
 export { ChallengeGate, type ChallengeGateProps } from './challenge-gate';
 export { AccessCodeForm, type AccessCodeFormProps } from './access-code-form';
 export { GrantedPanel, type GrantedPanelProps } from './granted-panel';
-export { OutcomePanel, type OutcomePanelProps } from './outcome-panel';
+export { OutcomePanel, type OutcomeAction, type OutcomePanelProps } from './outcome-panel';
 export { EndedModule, type EndedModuleProps } from './ended-module';
 export { ErrorView, type ErrorViewProps } from './error-view';

package/dist/components/compositions/outcome-panel.d.ts

@@ -4,6 +4,15 @@ import { OutcomeReason } from '../module';
  * (e.g. the expired re-enter button label) so each module shows terminology
  * appropriate to its mechanism rather than queue-specific copy.
  */
+/**
+ * A host-provided action for a terminal panel, such as "See what's still
+ * available" after a loss. The widget renders it as a secondary button; the
+ * host decides where it leads.
+ */
+export interface OutcomeAction {
+    label: string;
+    onClick: () => void;
+}
 export type ParticipationType = "queue" | "draw" | "auction" | "timed_release" | "appointment";
 export interface OutcomePanelProps {
     outcomeReason: OutcomeReason;
@@ -14,9 +23,11 @@ export interface OutcomePanelProps {
     participationType?: ParticipationType;
     onReenter?: () => Promise<void>;
     isReentering?: boolean;
+    /** Secondary action offered once the outcome is final. */
+    action?: OutcomeAction;
     className?: string;
 }
-export declare function OutcomePanel({ outcomeReason, participationType, onReenter, isReentering, className, }: OutcomePanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function OutcomePanel({ outcomeReason, participationType, onReenter, isReentering, action, className, }: OutcomePanelProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace OutcomePanel {
     var displayName: string;
 }

package/dist/components/module/index.d.ts

@@ -13,6 +13,8 @@ export { PanelHeading } from './panel-heading';
 export type { PanelHeadingProps, PanelHeadingVariant } from './panel-heading';
 export { InfoPanel } from './info-panel';
 export type { InfoPanelProps } from './info-panel';
+export { StageSteps } from './stage-steps';
+export type { StageStep, StageStepStatus, StageStepsProps } from './stage-steps';
 export { AlertPanel } from './alert-panel';
 export type { AlertPanelProps } from './alert-panel';
 export { normalizeOutcomeReason, normalizeSequenceOutcomeReason } from './outcome-reason';

package/dist/components/module/stage-steps.d.ts

@@ -0,0 +1,26 @@
+/**
+ * StageSteps
+ *
+ * A row of named stages for a phase whose end time is unknown. Completed
+ * stages read solid, the active stage pulses and its connector flows toward
+ * the next, and pending stages stay outlined. It communicates where the
+ * consumer is in a process without implying a percentage or a deadline.
+ *
+ *   <StageSteps
+ *     steps={[
+ *       { label: "You're in", status: "done" },
+ *       { label: "Drawing", status: "active" },
+ *       { label: "Results", status: "pending" },
+ *     ]}
+ *   />
+ */
+import * as React from "react";
+export type StageStepStatus = "done" | "active" | "pending";
+export interface StageStep {
+    label: string;
+    status: StageStepStatus;
+}
+export interface StageStepsProps extends React.HTMLAttributes<HTMLDivElement> {
+    steps: readonly StageStep[];
+}
+export declare const StageSteps: React.ForwardRefExoticComponent<StageStepsProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/widgets/experience-widget.d.ts

@@ -1,7 +1,8 @@
 import { BotMitigationState, RoutingChallenge } from '@fanfare-io/fanfare-sdk-core/challenges';
-import { JourneyHandle, JourneySnapshot, JourneyView, SequenceView } from '@fanfare-io/fanfare-sdk-core/experiences';
+import { CheckoutNextAction, CheckoutProcessor, FanfareCheckoutResult, JourneyHandle, JourneySnapshot, JourneyView, PaymentInput, PaymentMethodSummary, ReservationPaymentAffordance, SequenceView } from '@fanfare-io/fanfare-sdk-core/experiences';
 import { BrandTheme, WidgetVariant } from '../../theme';
 import { AuthInputMode } from '../auth/auth-input';
+import { OutcomeAction } from '../compositions/outcome-panel';
 import * as React from "react";
 type ParticipationType = "queue" | "draw" | "auction" | "timed_release" | "appointment";
 type EnterableSlotSequence = Extract<SequenceView, {
@@ -59,6 +60,74 @@ export interface GrantedSlotProps extends SlotProps {
     grant?: string;
     expiresAt?: number;
 }
+export interface PaymentCollectionSlotProps extends SlotProps {
+    preAuthAmount: string;
+    preAuthCurrencyCode: string;
+    savedPaymentMethods: PaymentMethodSummary[];
+    /** Rejects on a recoverable payment failure (e.g. a declined card) — the panel owns recovery UI for its own submit. */
+    onEnter: (paymentInput: PaymentInput) => Promise<void>;
+    isEntering: boolean;
+    /** "enter" collects payment before first entry; "reenter" collects payment to retry after a failed or expired authorization hold. */
+    intent: "enter" | "reenter";
+    /**
+     * Client configuration for the processor authorizing this entry, as the server supplied it.
+     * Carried by the enterable arm only — a retry is offered from an ended view, which holds no
+     * configuration.
+     */
+    paymentProvider?: PaymentProviderConfig;
+    /** Present while the processor is waiting on an out-of-band action; re-submitting entry resolves it. */
+    pendingAction?: CheckoutNextAction;
+    /**
+     * Re-reads the consumer's journeys from the server so a provider configuration that was missing
+     * or unreadable at render can arrive. This is the panel's only recovery when `paymentProvider` is
+     * absent — the value is a prop, so nothing the panel does to its own state can produce it.
+     */
+    onRetryPaymentConfig?: () => Promise<void>;
+}
+/**
+ * The processor's client configuration block, named through the affordance that carries it: core
+ * re-exports the affordance but not the contract's own name for this shape.
+ */
+type PaymentProviderConfig = NonNullable<ReservationPaymentAffordance["paymentProvider"]>;
+export interface ReservationCheckoutSlotProps extends SlotProps {
+    reservation: {
+        token: string;
+        expiresAt: number;
+    };
+    savedPaymentMethods: PaymentMethodSummary[];
+    /** Which processor executes this reservation's payment leg; narrow before rendering processor-specific UI. */
+    processor: CheckoutProcessor;
+    /** Client configuration for the processor settling this reservation, as the server supplied it. */
+    paymentProvider?: PaymentProviderConfig;
+    /** Present while the processor is waiting on an out-of-band action; complete it, then call `onResume`. */
+    pendingAction?: CheckoutNextAction;
+    /** Rejects on a recoverable payment failure (e.g. a declined card) — the panel owns recovery UI for its own submit. */
+    onConfirm: (paymentInput: PaymentInput) => Promise<void>;
+    /** Re-submits the paused checkout after `pendingAction` has been completed. Idempotent server-side. */
+    onResume: () => Promise<void>;
+    isConfirming: boolean;
+    /**
+     * Re-reads the consumer's journeys from the server so a provider configuration that was missing
+     * or unreadable at render can arrive. This is the panel's only recovery when `paymentProvider` is
+     * absent — the value is a prop, so nothing the panel does to its own state can produce it.
+     */
+    onRetryPaymentConfig?: () => Promise<void>;
+}
+export type CheckoutProcessingSlotProps = SlotProps;
+/**
+ * A Fanfare-managed payment is terminal: it produces a receipt, never an admission credential. The
+ * `grant` arm carries the credential the mechanism itself issued alongside the payment; a purchase
+ * that ends the journey has no credential to carry, so the arms are discriminated rather than
+ * making the grant optional — a slot implementation can never read one that does not exist.
+ */
+export type ReceiptSlotProps = SlotProps & ({
+    kind: "grant";
+    admissionGrant: string;
+    checkout: FanfareCheckoutResult;
+} | {
+    kind: "purchase";
+    checkout: FanfareCheckoutResult;
+});
 export interface ExpiredSlotProps extends SlotProps {
     reason: string;
     endedAt?: Date;
@@ -69,7 +138,8 @@ export interface EndedSlotProps extends SlotProps {
 }
 export interface ErrorSlotProps extends SlotProps {
     error: string;
-    onRetry: () => void;
+    /** Absent when the refusal cannot be cleared by retrying — render no retry affordance. */
+    onRetry?: () => void;
 }
 export interface LoadingSlotProps extends SlotProps {
     /** Stage-specific message (e.g. routing). `undefined` for generic loading — show just a spinner. */
@@ -93,6 +163,10 @@ export interface ExperienceWidgetSlots {
     enterable?: (props: EnterableSlotProps) => React.ReactNode;
     participating?: (props: ParticipatingSlotProps) => React.ReactNode;
     granted?: (props: GrantedSlotProps) => React.ReactNode;
+    paymentCollection?: (props: PaymentCollectionSlotProps) => React.ReactNode;
+    reservationCheckout?: (props: ReservationCheckoutSlotProps) => React.ReactNode;
+    checkoutProcessing?: (props: CheckoutProcessingSlotProps) => React.ReactNode;
+    receipt?: (props: ReceiptSlotProps) => React.ReactNode;
     expired?: (props: ExpiredSlotProps) => React.ReactNode;
     ended?: (props: EndedSlotProps) => React.ReactNode;
     error?: (props: ErrorSlotProps) => React.ReactNode;
@@ -125,16 +199,25 @@ export interface ExperienceWidgetProps {
     children?: (props: ExperienceRenderProps) => React.ReactNode;
     /** Checkout URL for granted state */
     checkoutUrl?: string;
+    /**
+     * Action offered on terminal panels (not selected, sold out, closed), such as
+     * a link back to what is still available. Omit to show none.
+     */
+    endedAction?: OutcomeAction;
     /** Called when journey state changes */
     onJourneyChange?: (snapshot: JourneySnapshot) => void;
     /** Called when the journey receives a grant */
     onGranted?: (grant: string) => void;
+    /** Called when a Fanfare-managed checkout completes (pre-auth capture or post-win reservation checkout) */
+    onFanfareCheckout?: (result: FanfareCheckoutResult) => void;
+    /** Called when the consumer wins a `post_win` distribution and must complete checkout before `expiresAt` */
+    onReserved?: (expiresAt: number) => void;
     /** Called when an error occurs */
     onError?: (error: Error) => void;
     /** Additional class name */
     className?: string;
 }
-export declare function ExperienceWidget({ experienceId, autoStart, accessCode, autoEnterWaitlist, theme, variant, slots, children, checkoutUrl, onJourneyChange, onGranted, onError, className, }: ExperienceWidgetProps): import("react/jsx-runtime").JSX.Element;
+export declare function ExperienceWidget({ experienceId, autoStart, accessCode, autoEnterWaitlist, theme, variant, slots, children, checkoutUrl, endedAction, onJourneyChange, onGranted, onFanfareCheckout, onReserved, onError, className, }: ExperienceWidgetProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ExperienceWidget {
     var displayName: string;
 }

package/dist/components/widgets/internal/auction-module.d.ts

@@ -1,5 +1,6 @@
 import { AuctionDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
 import { ReadableAtom } from 'nanostores';
+import { OutcomeAction } from '../../compositions/outcome-panel';
 import { OutcomeReason } from '../../module';
 export interface AuctionModuleProps {
     display$?: ReadableAtom<AuctionDisplayState>;
@@ -23,11 +24,13 @@ export interface AuctionModuleProps {
     checkoutUrl?: string;
     onCheckoutClick?: () => void;
     outcomeReason?: OutcomeReason;
+    /** Host-provided action shown on the terminal panel. */
+    outcomeAction?: OutcomeAction;
     onReenter?: () => Promise<void>;
     isReentering?: boolean;
     className?: string;
 }
-export declare function AuctionModule({ display$, fallbackState, sequencePhase, canEnter, canLeave, onEnter, onLeave, onBid, isEntering, isLeaving, countdownTo, defaultBidAmount, currencyCode, locale, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, onReenter, isReentering, className, }: AuctionModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AuctionModule({ display$, fallbackState, sequencePhase, canEnter, canLeave, onEnter, onLeave, onBid, isEntering, isLeaving, countdownTo, defaultBidAmount, currencyCode, locale, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, }: AuctionModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace AuctionModule {
     var displayName: string;
 }

package/dist/components/widgets/internal/draw-module.d.ts

@@ -1,5 +1,6 @@
 import { DrawDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
 import { ReadableAtom } from 'nanostores';
+import { OutcomeAction } from '../../compositions/outcome-panel';
 import { OutcomeReason } from '../../module';
 export interface DrawModuleProps {
     /** Reactive display state atom from the journey */
@@ -30,6 +31,8 @@ export interface DrawModuleProps {
     onCheckoutClick?: () => void;
     /** Denial reason (denied) */
     outcomeReason?: OutcomeReason;
+    /** Host-provided action shown on the terminal panel. */
+    outcomeAction?: OutcomeAction;
     /** Re-enter handler (denied with reason="expired") */
     onReenter?: () => Promise<void>;
     /** Whether re-entering is in progress */
@@ -37,7 +40,7 @@ export interface DrawModuleProps {
     /** Additional class name */
     className?: string;
 }
-export declare function DrawModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, countdownTo, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, onReenter, isReentering, className, }: DrawModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function DrawModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, countdownTo, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, }: DrawModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace DrawModule {
     var displayName: string;
 }

package/dist/components/widgets/internal/queue-module.d.ts

@@ -1,5 +1,6 @@
 import { QueueDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
 import { ReadableAtom } from 'nanostores';
+import { OutcomeAction } from '../../compositions/outcome-panel';
 import { OutcomeReason } from '../../module';
 export interface QueueModuleProps {
     display$?: ReadableAtom<QueueDisplayState>;
@@ -17,11 +18,13 @@ export interface QueueModuleProps {
     checkoutUrl?: string;
     onCheckoutClick?: () => void;
     outcomeReason?: OutcomeReason;
+    /** Host-provided action shown on the terminal panel. */
+    outcomeAction?: OutcomeAction;
     onReenter?: () => Promise<void>;
     isReentering?: boolean;
     className?: string;
 }
-export declare function QueueModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, closeAt, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, onReenter, isReentering, className, }: QueueModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function QueueModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, isEntering, isLeaving, closeAt, grant: _grant, expiresAt, checkoutUrl, onCheckoutClick, outcomeReason, outcomeAction, onReenter, isReentering, className, }: QueueModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace QueueModule {
     var displayName: string;
 }

package/dist/components/widgets/internal/timed-release-module.d.ts

@@ -1,5 +1,6 @@
 import { TimedReleaseDisplayState } from '@fanfare-io/fanfare-sdk-core/internals';
 import { ReadableAtom } from 'nanostores';
+import { OutcomeAction } from '../../compositions/outcome-panel';
 import { OutcomeReason } from '../../module';
 export interface TimedReleaseModuleProps {
     display$?: ReadableAtom<TimedReleaseDisplayState>;
@@ -17,11 +18,13 @@ export interface TimedReleaseModuleProps {
     grant?: string;
     expiresAt?: number | Date;
     outcomeReason?: OutcomeReason;
+    /** Host-provided action shown on the terminal panel. */
+    outcomeAction?: OutcomeAction;
     onReenter?: () => Promise<void>;
     isReentering?: boolean;
     className?: string;
 }
-export declare function TimedReleaseModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, onComplete, isEntering, isLeaving, countdownTo, checkoutUrl, onCheckoutClick, grant: _grant, expiresAt, outcomeReason, onReenter, isReentering, className, }: TimedReleaseModuleProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function TimedReleaseModule({ display$, sequencePhase, canEnter, canLeave, onEnter, onLeave, onComplete, isEntering, isLeaving, countdownTo, checkoutUrl, onCheckoutClick, grant: _grant, expiresAt, outcomeReason, outcomeAction, onReenter, isReentering, className, }: TimedReleaseModuleProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace TimedReleaseModule {
     var displayName: string;
 }

package/dist/hooks/use-fanfare-dom-bridge.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Mirrors one journey into a stable DOM target.
+ *
+ * The bridge latches `data-fanfare-version`, `data-fanfare-experience-id`,
+ * `data-fanfare-stage`, `data-fanfare-phase`, `data-fanfare-mechanism`,
+ * `data-fanfare-expires-at`, and `data-fanfare-outcome` on `opts.target`,
+ * defaulting to `document.documentElement`, and dispatches `fanfare:state-change`
+ * on that same element. Queue position is event-only, and a terminal outcome
+ * crosses as its type alone — the free-text qualifier that may accompany one
+ * stays on the typed SDK surface.
+ * Installation happens in an effect, so the first paint can be unbridged;
+ * vanilla `createDomBridge` stamps synchronously.
+ *
+ * Install stamps the current state and emits nothing; events are
+ * transition-only, so a consumer waiting for one may wait arbitrarily long — or
+ * forever, when the journey has ended or its queue is stable — and should read
+ * the latched attributes instead of expecting an initial event.
+ *
+ * Unmounting or changing `experienceId` disposes the bridge, which returns the
+ * bridge attributes to their pre-install state. Changing `opts.target` does not
+ * reinstall it. The target must be an
+ * already-mounted, stable element; a `ref.current` read in the render that
+ * creates the ref is null. Use this hook from a keyed subtree to move targets.
+ * `{ target: ref.current ?? undefined }` — the natural React spelling —
+ * silently bridges `document.documentElement`, because a nullish target is
+ * indistinguishable from "no target wanted".
+ *
+ * Calling this hook twice for the same experience and target is unsupported:
+ * it duplicates events, creates conflicting stamps, and allows one owner to
+ * remove the other owner's stamps during teardown. Distinct experiences alone
+ * do not separate two hooks: two calls with no `opts.target` both stamp
+ * `document.documentElement` and contend for the same attribute names, so give
+ * each call its own target when a page bridges more than one experience. The
+ * hook also creates the journey on read when one does not already exist, which
+ * arms its pollers.
+ *
+ * A reinstall emits nothing. When the context SDK identity changes — the `ssr`
+ * read-only SDK swapping to the live SDK on first paint, or a provider
+ * re-init — the hook disposes and reinstalls; install stamps without emitting,
+ * so an events-only consumer never learns of a delta it did not cause. The
+ * attributes remain correct.
+ *
+ * Dispose the bridge before destroying its handle or SDK. Destroying either
+ * while the bridge is live emits one final ready-projection event and restamps
+ * ready attributes — a reset the bridge cannot distinguish from a legitimate
+ * restart. Under `FanfareProvider`, unmount is safe: the provider defers SDK
+ * destruction through its lifecycle queue, so this hook's dispose runs first
+ * and that path emits no such event. When the provider replaces its SDK
+ * without unmounting the bridge — a change to a config value, or `ssr` mode
+ * dropping `publishableKey` — that ordering is not guaranteed and a live
+ * bridge may emit one final ready event and restamp. A caller supplying its
+ * own SDK through `FanfareContext` gets no deferral and is a direct-destroy
+ * caller.
+ */
+export declare function useFanfareDomBridge(experienceId: string | undefined, opts?: {
+    target?: Element;
+}): void;

package/dist/hooks/use-sdk-event.d.ts

@@ -0,0 +1,20 @@
+import { SDKEvents } from '@fanfare-io/fanfare-sdk-core/events';
+type SDKEventKey = keyof SDKEvents;
+/**
+ * Subscribe to a typed Fanfare SDK event for the lifetime of the component.
+ *
+ * The handler is read from a ref refreshed on every render, so passing an inline
+ * closure never re-subscribes. The subscription is re-established when the SDK
+ * instance identity changes (the provider swapping its first-paint SDK for the
+ * live one) or when `event` changes; events emitted during such a swap are not
+ * delivered.
+ *
+ * @example
+ * ```tsx
+ * useSdkEvent("journey:granted", (data) => {
+ *   analytics.track("granted", { experienceId: data.experienceId });
+ * });
+ * ```
+ */
+export declare function useSdkEvent<K extends SDKEventKey>(event: K, handler: (data: SDKEvents[K]) => void): void;
+export {};