@agg-build/ui 4.7.4 → 4.9.1

package/dist/trading.mjs

@@ -8,11 +8,13 @@ import {
   PlaceOrderFailureView,
   PlaceOrderSuccessView,
   SettlementDetails,
+  createAggClientSharedKycInitiator,
   parseAmount,
   parseVenue,
   useClaimWinnings,
-  useResolvedMarketClaim
-} from "./chunk-CB3DDQBP.mjs";
+  useResolvedMarketClaim,
+  venueRequiresSharedKyc
+} from "./chunk-GKYBQEBC.mjs";
 import {
   SETTLEMENT_SECTION_ID,
   Settlement,
@@ -30,9 +32,9 @@ import {
   prepareSettlementDifferences,
   resolveDifferenceIconClassName,
   useEventTradingContext
-} from "./chunk-MAQ52KM5.mjs";
-import "./chunk-XR6C3MZX.mjs";
-import "./chunk-UQ7XJIAZ.mjs";
+} from "./chunk-TNNLRRHC.mjs";
+import "./chunk-H7L4HDXS.mjs";
+import "./chunk-NYL6A6AD.mjs";
 export {
   FundKalshiModal,
   PlaceOrder,
@@ -44,6 +46,7 @@ export {
   SETTLEMENT_SECTION_ID,
   Settlement,
   SettlementDetails,
+  createAggClientSharedKycInitiator,
   defaultSettlementSectionLabel,
   defaultTradingDisclaimer,
   getSettlementDifferenceId,
@@ -61,5 +64,6 @@ export {
   resolveDifferenceIconClassName,
   useClaimWinnings,
   useEventTradingContext,
-  useResolvedMarketClaim
+  useResolvedMarketClaim,
+  venueRequiresSharedKyc
 };

package/dist/types/index.d.mts

@@ -7,6 +7,7 @@ export * from "./pages";
 export * from "./modals";
 export * from "./trading";
 export * from "./constants";
+export * from "./kyc";
 export * from "./shared/utils";
 export { DEPOSIT_MODAL_OPEN_EVENT, WITHDRAW_MODAL_OPEN_EVENT, requestAggDepositModalOpen, requestAggWithdrawModalOpen, } from "./shared/deposit-modal-events";
 export type { AvailableSizes } from "./shared/types";

package/dist/types/index.d.ts

@@ -7,6 +7,7 @@ export * from "./pages";
 export * from "./modals";
 export * from "./trading";
 export * from "./constants";
+export * from "./kyc";
 export * from "./shared/utils";
 export { DEPOSIT_MODAL_OPEN_EVENT, WITHDRAW_MODAL_OPEN_EVENT, requestAggDepositModalOpen, requestAggWithdrawModalOpen, } from "./shared/deposit-modal-events";
 export type { AvailableSizes } from "./shared/types";

package/dist/types/kyc/index.d.mts

@@ -0,0 +1,3 @@
+export * from "./shared-kyc";
+export * from "./shared-kyc-modal";
+export * from "./use-shared-kyc-flow";

package/dist/types/kyc/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./shared-kyc";
+export * from "./shared-kyc-modal";
+export * from "./use-shared-kyc-flow";

package/dist/types/kyc/shared-kyc-modal.d.mts

@@ -0,0 +1,12 @@
+export type SharedKycModalState = "initial" | "initiating" | "pending" | "error" | "success";
+export interface SharedKycModalProps {
+    open: boolean;
+    state?: SharedKycModalState;
+    errorMessage?: string;
+    onOpenChange: (open: boolean) => void;
+    onStartVerification: () => void;
+}
+export declare const SharedKycModal: {
+    ({ open, state, errorMessage, onOpenChange, onStartVerification, }: SharedKycModalProps): JSX.Element;
+    displayName: string;
+};

package/dist/types/kyc/shared-kyc-modal.d.ts

@@ -0,0 +1,12 @@
+export type SharedKycModalState = "initial" | "initiating" | "pending" | "error" | "success";
+export interface SharedKycModalProps {
+    open: boolean;
+    state?: SharedKycModalState;
+    errorMessage?: string;
+    onOpenChange: (open: boolean) => void;
+    onStartVerification: () => void;
+}
+export declare const SharedKycModal: {
+    ({ open, state, errorMessage, onOpenChange, onStartVerification, }: SharedKycModalProps): JSX.Element;
+    displayName: string;
+};

package/dist/types/kyc/shared-kyc.d.mts

@@ -0,0 +1,31 @@
+import { Venue, type AggClient } from "@agg-build/sdk";
+export type SharedKycStatus = "loading" | "unverified" | "verified";
+export interface SharedKycInitiationRequest {
+    venue: Venue;
+    redirectUri: string;
+}
+export interface SharedKycInitiationResult {
+    kycUrl?: string;
+}
+export interface SharedKycIntegration {
+    /** Backend-authoritative shared status for the current app-scoped user. */
+    status: SharedKycStatus;
+    /** Starts external verification for the venue that triggered the shared requirement. */
+    initiateVerification: (request: SharedKycInitiationRequest) => Promise<SharedKycInitiationResult>;
+    /** Refetches backend-authoritative status after an external redirect returns. */
+    refreshStatus: () => Promise<SharedKycStatus>;
+    /** Optional navigation override. Defaults to a same-tab location assignment. */
+    navigate?: (url: string) => void;
+}
+export interface SharedKycVenueCapability {
+    venue: string | null | undefined;
+    /** Prefer backend capability metadata whenever it is available. */
+    requiresKyc?: boolean | null;
+}
+/**
+ * Frontend fallback until venue capability metadata is returned by the API.
+ * Keep the temporary venue list private so components never encode venue names.
+ */
+export declare const venueRequiresSharedKyc: ({ venue, requiresKyc, }: SharedKycVenueCapability) => boolean;
+/** Adapts the existing SDK initiation method to the shared frontend boundary. */
+export declare const createAggClientSharedKycInitiator: (client: Pick<AggClient, "initiateKyc">) => SharedKycIntegration["initiateVerification"];

package/dist/types/kyc/shared-kyc.d.ts

@@ -0,0 +1,31 @@
+import { Venue, type AggClient } from "@agg-build/sdk";
+export type SharedKycStatus = "loading" | "unverified" | "verified";
+export interface SharedKycInitiationRequest {
+    venue: Venue;
+    redirectUri: string;
+}
+export interface SharedKycInitiationResult {
+    kycUrl?: string;
+}
+export interface SharedKycIntegration {
+    /** Backend-authoritative shared status for the current app-scoped user. */
+    status: SharedKycStatus;
+    /** Starts external verification for the venue that triggered the shared requirement. */
+    initiateVerification: (request: SharedKycInitiationRequest) => Promise<SharedKycInitiationResult>;
+    /** Refetches backend-authoritative status after an external redirect returns. */
+    refreshStatus: () => Promise<SharedKycStatus>;
+    /** Optional navigation override. Defaults to a same-tab location assignment. */
+    navigate?: (url: string) => void;
+}
+export interface SharedKycVenueCapability {
+    venue: string | null | undefined;
+    /** Prefer backend capability metadata whenever it is available. */
+    requiresKyc?: boolean | null;
+}
+/**
+ * Frontend fallback until venue capability metadata is returned by the API.
+ * Keep the temporary venue list private so components never encode venue names.
+ */
+export declare const venueRequiresSharedKyc: ({ venue, requiresKyc, }: SharedKycVenueCapability) => boolean;
+/** Adapts the existing SDK initiation method to the shared frontend boundary. */
+export declare const createAggClientSharedKycInitiator: (client: Pick<AggClient, "initiateKyc">) => SharedKycIntegration["initiateVerification"];

package/dist/types/kyc/use-shared-kyc-flow.d.mts

@@ -0,0 +1,19 @@
+import type { SharedKycModalState } from "./shared-kyc-modal";
+import type { SharedKycIntegration, SharedKycInitiationRequest } from "./shared-kyc";
+type KycVenue = SharedKycInitiationRequest["venue"];
+interface UseSharedKycFlowOptions {
+    integration?: SharedKycIntegration;
+    userId?: string | null;
+    fallbackErrorMessage: string;
+}
+export interface UseSharedKycFlowResult {
+    activeVenue: KycVenue | null;
+    errorMessage?: string;
+    isModalOpen: boolean;
+    modalState: SharedKycModalState;
+    closeModal: () => void;
+    openForVenue: (venue: KycVenue) => void;
+    startVerification: () => Promise<void>;
+}
+export declare const useSharedKycFlow: ({ integration, userId, fallbackErrorMessage, }: UseSharedKycFlowOptions) => UseSharedKycFlowResult;
+export {};

package/dist/types/kyc/use-shared-kyc-flow.d.ts

@@ -0,0 +1,19 @@
+import type { SharedKycModalState } from "./shared-kyc-modal";
+import type { SharedKycIntegration, SharedKycInitiationRequest } from "./shared-kyc";
+type KycVenue = SharedKycInitiationRequest["venue"];
+interface UseSharedKycFlowOptions {
+    integration?: SharedKycIntegration;
+    userId?: string | null;
+    fallbackErrorMessage: string;
+}
+export interface UseSharedKycFlowResult {
+    activeVenue: KycVenue | null;
+    errorMessage?: string;
+    isModalOpen: boolean;
+    modalState: SharedKycModalState;
+    closeModal: () => void;
+    openForVenue: (venue: KycVenue) => void;
+    startVerification: () => Promise<void>;
+}
+export declare const useSharedKycFlow: ({ integration, userId, fallbackErrorMessage, }: UseSharedKycFlowOptions) => UseSharedKycFlowResult;
+export {};

package/dist/types/modals/index.d.mts

@@ -1,6 +1,8 @@
 export * from "../deposit";
 export * from "../withdraw";
 export * from "../onboarding";
+export * from "../paper-trading";
 export * from "../profile";
 export * from "../geo-block-modal";
 export * from "../geo-block-banner";
+export * from "../kyc/shared-kyc-modal";

package/dist/types/modals/index.d.ts

@@ -1,6 +1,8 @@
 export * from "../deposit";
 export * from "../withdraw";
 export * from "../onboarding";
+export * from "../paper-trading";
 export * from "../profile";
 export * from "../geo-block-modal";
 export * from "../geo-block-banner";
+export * from "../kyc/shared-kyc-modal";

package/dist/types/pages/event-market/event-market.shared.d.mts

@@ -22,8 +22,9 @@ type EventMarketPageMobileTradeProps = {
     onOpenChange: (nextOpen: boolean) => void;
     midpointsResult?: UseMidpointsResult;
     onBeforePrimaryAction?: EventMarketPageProps["onBeforePrimaryAction"];
+    sharedKyc?: EventMarketPageProps["sharedKyc"];
 };
-export declare const EventMarketPageMobileTrade: ({ classNames, eventTradingState, executionMode, showPlaceOrder, isOpen, onOpenChange, midpointsResult, onBeforePrimaryAction, }: EventMarketPageMobileTradeProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const EventMarketPageMobileTrade: ({ classNames, eventTradingState, executionMode, showPlaceOrder, isOpen, onOpenChange, midpointsResult, onBeforePrimaryAction, sharedKyc, }: EventMarketPageMobileTradeProps) => import("react/jsx-runtime").JSX.Element | null;
 export declare const EventMarketPageUnavailableState: ({ ariaLabel: _ariaLabel, }: Pick<EventMarketPageProps, "ariaLabel">) => JSX.Element;
 export declare const EventMarketPageNotFoundState: ({ ariaLabel: _ariaLabel, }: Pick<EventMarketPageProps, "ariaLabel">) => JSX.Element;
 export declare const EventMarketPageLoadingState: ({ classNames, stickyOrderPanel, }: Pick<EventMarketPageProps, "classNames" | "stickyOrderPanel">) => JSX.Element;

package/dist/types/pages/event-market/event-market.shared.d.ts

@@ -22,8 +22,9 @@ type EventMarketPageMobileTradeProps = {
     onOpenChange: (nextOpen: boolean) => void;
     midpointsResult?: UseMidpointsResult;
     onBeforePrimaryAction?: EventMarketPageProps["onBeforePrimaryAction"];
+    sharedKyc?: EventMarketPageProps["sharedKyc"];
 };
-export declare const EventMarketPageMobileTrade: ({ classNames, eventTradingState, executionMode, showPlaceOrder, isOpen, onOpenChange, midpointsResult, onBeforePrimaryAction, }: EventMarketPageMobileTradeProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const EventMarketPageMobileTrade: ({ classNames, eventTradingState, executionMode, showPlaceOrder, isOpen, onOpenChange, midpointsResult, onBeforePrimaryAction, sharedKyc, }: EventMarketPageMobileTradeProps) => import("react/jsx-runtime").JSX.Element | null;
 export declare const EventMarketPageUnavailableState: ({ ariaLabel: _ariaLabel, }: Pick<EventMarketPageProps, "ariaLabel">) => JSX.Element;
 export declare const EventMarketPageNotFoundState: ({ ariaLabel: _ariaLabel, }: Pick<EventMarketPageProps, "ariaLabel">) => JSX.Element;
 export declare const EventMarketPageLoadingState: ({ classNames, stickyOrderPanel, }: Pick<EventMarketPageProps, "classNames" | "stickyOrderPanel">) => JSX.Element;

package/dist/types/pages/event-market/event-market.types.d.mts

@@ -51,6 +51,8 @@ export type EventMarketPageBaseProps = {
      * `false` to cancel or throw to abort. See `PlaceOrderProps.onBeforePrimaryAction`.
      */
     onBeforePrimaryAction?: PlaceOrderProps["onBeforePrimaryAction"];
+    /** Optional backend-authoritative shared KYC integration for the Place Order surface. */
+    sharedKyc?: PlaceOrderProps["sharedKyc"];
     executionMode?: "live" | "paper";
     /** Optional resolved-event claim summary shown inside the read-only order panel. */
     resolvedClaim?: PlaceOrderResolvedClaimSummary;

package/dist/types/pages/event-market/event-market.types.d.ts

@@ -51,6 +51,8 @@ export type EventMarketPageBaseProps = {
      * `false` to cancel or throw to abort. See `PlaceOrderProps.onBeforePrimaryAction`.
      */
     onBeforePrimaryAction?: PlaceOrderProps["onBeforePrimaryAction"];
+    /** Optional backend-authoritative shared KYC integration for the Place Order surface. */
+    sharedKyc?: PlaceOrderProps["sharedKyc"];
     executionMode?: "live" | "paper";
     /** Optional resolved-event claim summary shown inside the read-only order panel. */
     resolvedClaim?: PlaceOrderResolvedClaimSummary;

package/dist/types/pages/event-market/sports-event-market-page.d.mts

@@ -1,7 +1,7 @@
 import type { VenueEventWithMarkets } from "../../events/item/event-list-item.types";
 import type { EventMarketPageProps } from "./event-market.types";
 export declare const SportsEventMarketPage: {
-    ({ event, defaultMarketId, defaultOutcomeId, classNames, ariaLabel, showPlaceOrder, executionMode, stickyOrderPanel, resolvedClaim, onBeforePrimaryAction, }: Extract<EventMarketPageProps, {
+    ({ event, defaultMarketId, defaultOutcomeId, classNames, ariaLabel, showPlaceOrder, executionMode, stickyOrderPanel, resolvedClaim, onBeforePrimaryAction, sharedKyc, }: Extract<EventMarketPageProps, {
         event: VenueEventWithMarkets;
     }>): JSX.Element;
     displayName: string;

package/dist/types/pages/event-market/sports-event-market-page.d.ts

@@ -1,7 +1,7 @@
 import type { VenueEventWithMarkets } from "../../events/item/event-list-item.types";
 import type { EventMarketPageProps } from "./event-market.types";
 export declare const SportsEventMarketPage: {
-    ({ event, defaultMarketId, defaultOutcomeId, classNames, ariaLabel, showPlaceOrder, executionMode, stickyOrderPanel, resolvedClaim, onBeforePrimaryAction, }: Extract<EventMarketPageProps, {
+    ({ event, defaultMarketId, defaultOutcomeId, classNames, ariaLabel, showPlaceOrder, executionMode, stickyOrderPanel, resolvedClaim, onBeforePrimaryAction, sharedKyc, }: Extract<EventMarketPageProps, {
         event: VenueEventWithMarkets;
     }>): JSX.Element;
     displayName: string;

package/dist/types/pages/user-profile/components/positions-value-card.d.mts

@@ -5,9 +5,25 @@ type PositionsValueCardProps = {
     isLoading?: boolean;
     className?: string;
     icon?: ReactNode;
+    /**
+     * Small uppercase note sitting to the right of the value, baseline-aligned
+     * with it (Figma node 4772:31141). Optional — most cards have none.
+     */
+    caption?: string;
+    /**
+     * Tighter mobile padding and a single-line label, per the paper profile
+     * frames (Figma 4772:33662 / 4772:31126).
+     *
+     * Opt-in rather than the default: these cards also render on the live
+     * profile, where the wider column means labels have room to wrap and the
+     * 20px padding is what every partner already sees. Turning it on globally
+     * would resize live cards and make a long or localized label overflow
+     * instead of wrapping.
+     */
+    compact?: boolean;
 };
 export declare const PositionsValueCard: {
-    ({ label, valueLabel, isLoading, className, icon, }: PositionsValueCardProps): JSX.Element;
+    ({ label, valueLabel, isLoading, className, icon, caption, compact, }: PositionsValueCardProps): JSX.Element;
     displayName: string;
 };
 export {};

package/dist/types/pages/user-profile/components/positions-value-card.d.ts

@@ -5,9 +5,25 @@ type PositionsValueCardProps = {
     isLoading?: boolean;
     className?: string;
     icon?: ReactNode;
+    /**
+     * Small uppercase note sitting to the right of the value, baseline-aligned
+     * with it (Figma node 4772:31141). Optional — most cards have none.
+     */
+    caption?: string;
+    /**
+     * Tighter mobile padding and a single-line label, per the paper profile
+     * frames (Figma 4772:33662 / 4772:31126).
+     *
+     * Opt-in rather than the default: these cards also render on the live
+     * profile, where the wider column means labels have room to wrap and the
+     * 20px padding is what every partner already sees. Turning it on globally
+     * would resize live cards and make a long or localized label overflow
+     * instead of wrapping.
+     */
+    compact?: boolean;
 };
 export declare const PositionsValueCard: {
-    ({ label, valueLabel, isLoading, className, icon, }: PositionsValueCardProps): JSX.Element;
+    ({ label, valueLabel, isLoading, className, icon, caption, compact, }: PositionsValueCardProps): JSX.Element;
     displayName: string;
 };
 export {};

package/dist/types/pages/user-profile/components/user-info-card.d.mts

@@ -6,10 +6,20 @@ type UserInfoCardProps = {
     onWithdraw?: () => void;
     /** Whether deposits are blocked for the user's geo location. */
     isDepositBlocked?: boolean;
+    /**
+     * Keep the actions row when there are no money actions, so it still holds
+     * the mobile Edit button. Set by a paper profile, which supplies no
+     * deposit/withdraw handler and would otherwise lose the only way to edit a
+     * profile on mobile.
+     *
+     * Opt-in so a live partner that wires `onEditProfile` but no money handlers
+     * keeps rendering no row at all, exactly as it does today.
+     */
+    showEditOnlyActions?: boolean;
     className?: string;
 };
 export declare const UserInfoCard: {
-    ({ user, onEditProfile, onDeposit, onWithdraw, isDepositBlocked, className, }: UserInfoCardProps): JSX.Element;
+    ({ user, onEditProfile, onDeposit, onWithdraw, isDepositBlocked, showEditOnlyActions, className, }: UserInfoCardProps): JSX.Element;
     displayName: string;
 };
 export {};

package/dist/types/pages/user-profile/components/user-info-card.d.ts

@@ -6,10 +6,20 @@ type UserInfoCardProps = {
     onWithdraw?: () => void;
     /** Whether deposits are blocked for the user's geo location. */
     isDepositBlocked?: boolean;
+    /**
+     * Keep the actions row when there are no money actions, so it still holds
+     * the mobile Edit button. Set by a paper profile, which supplies no
+     * deposit/withdraw handler and would otherwise lose the only way to edit a
+     * profile on mobile.
+     *
+     * Opt-in so a live partner that wires `onEditProfile` but no money handlers
+     * keeps rendering no row at all, exactly as it does today.
+     */
+    showEditOnlyActions?: boolean;
     className?: string;
 };
 export declare const UserInfoCard: {
-    ({ user, onEditProfile, onDeposit, onWithdraw, isDepositBlocked, className, }: UserInfoCardProps): JSX.Element;
+    ({ user, onEditProfile, onDeposit, onWithdraw, isDepositBlocked, showEditOnlyActions, className, }: UserInfoCardProps): JSX.Element;
     displayName: string;
 };
 export {};

package/dist/types/paper-trading/index.d.mts

@@ -0,0 +1,6 @@
+export { PaperTradingBadge } from "./paper-trading-badge";
+export type { PaperTradingBadgeClassNames, PaperTradingBadgeProps } from "./paper-trading-badge";
+export { PaperTradingOnboarding } from "./paper-trading-onboarding";
+export type { PaperTradingOnboardingProps } from "./paper-trading-onboarding";
+export { PaperOnboardingModal } from "./paper-onboarding-modal";
+export type { PaperOnboardingModalClassNames, PaperOnboardingModalProps, PaperOnboardingStep, PaperOnboardingStepKey, } from "./paper-onboarding-modal.types";

package/dist/types/paper-trading/index.d.ts

@@ -0,0 +1,6 @@
+export { PaperTradingBadge } from "./paper-trading-badge";
+export type { PaperTradingBadgeClassNames, PaperTradingBadgeProps } from "./paper-trading-badge";
+export { PaperTradingOnboarding } from "./paper-trading-onboarding";
+export type { PaperTradingOnboardingProps } from "./paper-trading-onboarding";
+export { PaperOnboardingModal } from "./paper-onboarding-modal";
+export type { PaperOnboardingModalClassNames, PaperOnboardingModalProps, PaperOnboardingStep, PaperOnboardingStepKey, } from "./paper-onboarding-modal.types";

package/dist/types/paper-trading/paper-onboarding-modal.d.mts

@@ -0,0 +1,15 @@
+import type { PaperOnboardingModalProps } from "./paper-onboarding-modal.types";
+/**
+ * Three-step intro shown once, on a user's first sign-in to a paper app.
+ *
+ * Figma node 4772:31182 lays the three states out side by side; this is one
+ * modal that advances through them, not three modals.
+ *
+ * All copy resolves through `labels.paperTrading.onboarding` — the design's
+ * strings were written against an earlier daily-allowance model and are still
+ * being revised, so nothing here renders a literal.
+ */
+export declare const PaperOnboardingModal: {
+    ({ open, onDismiss, startingBalanceLabel, classNames, }: PaperOnboardingModalProps): JSX.Element;
+    displayName: string;
+};

package/dist/types/paper-trading/paper-onboarding-modal.d.ts

@@ -0,0 +1,15 @@
+import type { PaperOnboardingModalProps } from "./paper-onboarding-modal.types";
+/**
+ * Three-step intro shown once, on a user's first sign-in to a paper app.
+ *
+ * Figma node 4772:31182 lays the three states out side by side; this is one
+ * modal that advances through them, not three modals.
+ *
+ * All copy resolves through `labels.paperTrading.onboarding` — the design's
+ * strings were written against an earlier daily-allowance model and are still
+ * being revised, so nothing here renders a literal.
+ */
+export declare const PaperOnboardingModal: {
+    ({ open, onDismiss, startingBalanceLabel, classNames, }: PaperOnboardingModalProps): JSX.Element;
+    displayName: string;
+};

package/dist/types/paper-trading/paper-onboarding-modal.types.d.mts

@@ -0,0 +1,33 @@
+import type { IconName } from "../primitives/icon";
+export type PaperOnboardingStepKey = "realMarkets" | "zeroRisk" | "readyToTrade";
+export type PaperOnboardingStep = {
+    key: PaperOnboardingStepKey;
+    icon: IconName;
+    title: string;
+    body: string;
+};
+export type PaperOnboardingModalClassNames = {
+    overlay?: string;
+    card?: string;
+    icon?: string;
+    eyebrow?: string;
+    title?: string;
+    body?: string;
+    dots?: string;
+    footer?: string;
+};
+export type PaperOnboardingModalProps = {
+    /** Controls visibility. Drive this from `usePaperOnboarding().isOpen`. */
+    open: boolean;
+    /**
+     * Called when the user finishes, skips, or closes the intro. Wire it to
+     * `usePaperOnboarding().dismiss` so the intro does not return next session.
+     */
+    onDismiss: () => void;
+    /**
+     * One-time paper grant, pre-formatted (e.g. "$10,000"). Interpolated into
+     * the step 2 body so the figure is never hardcoded in copy.
+     */
+    startingBalanceLabel: string;
+    classNames?: PaperOnboardingModalClassNames;
+};

package/dist/types/paper-trading/paper-onboarding-modal.types.d.ts

@@ -0,0 +1,33 @@
+import type { IconName } from "../primitives/icon";
+export type PaperOnboardingStepKey = "realMarkets" | "zeroRisk" | "readyToTrade";
+export type PaperOnboardingStep = {
+    key: PaperOnboardingStepKey;
+    icon: IconName;
+    title: string;
+    body: string;
+};
+export type PaperOnboardingModalClassNames = {
+    overlay?: string;
+    card?: string;
+    icon?: string;
+    eyebrow?: string;
+    title?: string;
+    body?: string;
+    dots?: string;
+    footer?: string;
+};
+export type PaperOnboardingModalProps = {
+    /** Controls visibility. Drive this from `usePaperOnboarding().isOpen`. */
+    open: boolean;
+    /**
+     * Called when the user finishes, skips, or closes the intro. Wire it to
+     * `usePaperOnboarding().dismiss` so the intro does not return next session.
+     */
+    onDismiss: () => void;
+    /**
+     * One-time paper grant, pre-formatted (e.g. "$10,000"). Interpolated into
+     * the step 2 body so the figure is never hardcoded in copy.
+     */
+    startingBalanceLabel: string;
+    classNames?: PaperOnboardingModalClassNames;
+};

package/dist/types/paper-trading/paper-trading-badge.d.mts

@@ -0,0 +1,50 @@
+export type PaperTradingBadgeClassNames = {
+    root?: string;
+    pill?: string;
+    tooltip?: string;
+};
+/**
+ * Where this instance is mounted. Three exist, each hiding itself wherever
+ * another is the right host, so exactly one is ever on screen:
+ *
+ * - `brand` — beside the logo. Mobile only, at any auth state (Figma
+ *   4772:34179).
+ * - `chip` — inside the connect button's balance chip, which itself only
+ *   renders from `md` up and only once signed in (Figma 4772:31076).
+ * - `signedOut` — beside the sign-in control on desktop, where there is no
+ *   chip yet. Desktop only; mobile is already covered by `brand`.
+ */
+export type PaperTradingBadgePlacement = "brand" | "chip" | "signedOut";
+export type PaperTradingBadgeProps = {
+    placement?: PaperTradingBadgePlacement;
+    /**
+     * Whether a user is signed in. Passed down rather than read from a hook so
+     * this stays a pure presentational component that renders outside the
+     * provider stack — the same contract `AuthConnectButtonView` follows.
+     * Only the `brand` placement uses it; see the note in the component.
+     */
+    isAuthenticated?: boolean;
+    /**
+     * Render even when the app is not in paper mode. Off by default so the
+     * pill can be mounted unconditionally in a partner's header — it simply
+     * disappears in a live app. Used by Storybook.
+     */
+    forceVisible?: boolean;
+    classNames?: PaperTradingBadgeClassNames;
+};
+/**
+ * Header pill marking the whole app as simulated, with an explanatory tooltip.
+ *
+ * Figma node 4772:31077 — 10px bold uppercase in the app's primary colour on a
+ * 10%-alpha primary fill, 12/4 padding, fully rounded. Rendered directly
+ * rather than through the `Badge` primitive because Badge imposes its own
+ * type scale and padding, which do not match this spec.
+ *
+ * Renders nothing until the app mode has resolved from `/app/config` —
+ * flashing "PAPER TRADING" over a real-money app, even briefly, is the one
+ * mistake here that would genuinely mislead someone about their funds.
+ */
+export declare const PaperTradingBadge: {
+    ({ placement, isAuthenticated, forceVisible, classNames, }: PaperTradingBadgeProps): JSX.Element | null;
+    displayName: string;
+};

package/dist/types/paper-trading/paper-trading-badge.d.ts

@@ -0,0 +1,50 @@
+export type PaperTradingBadgeClassNames = {
+    root?: string;
+    pill?: string;
+    tooltip?: string;
+};
+/**
+ * Where this instance is mounted. Three exist, each hiding itself wherever
+ * another is the right host, so exactly one is ever on screen:
+ *
+ * - `brand` — beside the logo. Mobile only, at any auth state (Figma
+ *   4772:34179).
+ * - `chip` — inside the connect button's balance chip, which itself only
+ *   renders from `md` up and only once signed in (Figma 4772:31076).
+ * - `signedOut` — beside the sign-in control on desktop, where there is no
+ *   chip yet. Desktop only; mobile is already covered by `brand`.
+ */
+export type PaperTradingBadgePlacement = "brand" | "chip" | "signedOut";
+export type PaperTradingBadgeProps = {
+    placement?: PaperTradingBadgePlacement;
+    /**
+     * Whether a user is signed in. Passed down rather than read from a hook so
+     * this stays a pure presentational component that renders outside the
+     * provider stack — the same contract `AuthConnectButtonView` follows.
+     * Only the `brand` placement uses it; see the note in the component.
+     */
+    isAuthenticated?: boolean;
+    /**
+     * Render even when the app is not in paper mode. Off by default so the
+     * pill can be mounted unconditionally in a partner's header — it simply
+     * disappears in a live app. Used by Storybook.
+     */
+    forceVisible?: boolean;
+    classNames?: PaperTradingBadgeClassNames;
+};
+/**
+ * Header pill marking the whole app as simulated, with an explanatory tooltip.
+ *
+ * Figma node 4772:31077 — 10px bold uppercase in the app's primary colour on a
+ * 10%-alpha primary fill, 12/4 padding, fully rounded. Rendered directly
+ * rather than through the `Badge` primitive because Badge imposes its own
+ * type scale and padding, which do not match this spec.
+ *
+ * Renders nothing until the app mode has resolved from `/app/config` —
+ * flashing "PAPER TRADING" over a real-money app, even briefly, is the one
+ * mistake here that would genuinely mislead someone about their funds.
+ */
+export declare const PaperTradingBadge: {
+    ({ placement, isAuthenticated, forceVisible, classNames, }: PaperTradingBadgeProps): JSX.Element | null;
+    displayName: string;
+};

package/dist/types/paper-trading/paper-trading-onboarding.d.mts

@@ -0,0 +1,16 @@
+import type { PaperOnboardingModalClassNames } from "./paper-onboarding-modal.types";
+export type PaperTradingOnboardingProps = {
+    classNames?: PaperOnboardingModalClassNames;
+};
+/**
+ * Drop-in paper-trading intro. Renders nothing in a live app, and nothing for
+ * a user who has already seen it — mount it once, high in the tree, and forget
+ * about it.
+ *
+ * Pairs `usePaperOnboarding` (when to show) with `PaperOnboardingModal` (what
+ * to show). Use the modal directly if you need to drive visibility yourself.
+ */
+export declare const PaperTradingOnboarding: {
+    ({ classNames, }: PaperTradingOnboardingProps): JSX.Element | null;
+    displayName: string;
+};