@appfunnel-dev/sdk 0.17.0 → 2.0.0-canary.0

package/dist/index.d.ts

@@ -1,386 +1,1751 @@
-import { A as AppFunnelConfig, P as PageDefinition, V as VariableValue, U as UserState, L as LocaleState, T as TranslationState, N as NavigationState, a as ProductsState, b as TrackingState, c as PaymentState, D as DeviceInfo, d as PageData, F as FunnelState } from './internal-BBWDTB-l.js';
-export { C as ConditionConfig, e as ConditionGroupConfig, f as FunnelProvider, g as FunnelProviderProps, h as FunnelSettings, i as PageConfig, j as PageState, k as PageType, l as ProductConfig, m as ProductsConfig, n as Progress, R as RouteConfig, o as RuntimeProduct, p as VariableConfig, q as VariableType } from './internal-BBWDTB-l.js';
-import * as react from 'react';
-import { Appearance } from '@stripe/stripe-js';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-export { toast } from 'sonner';
+import { ReactNode, ComponentType, ButtonHTMLAttributes } from 'react';
+import { ToasterProps } from 'sonner';
+export { ToasterProps, toast } from 'sonner';
+
+type VariableType = 'string' | 'number' | 'boolean' | 'stringArray';
+type VariableValue = string | number | boolean | string[] | null | undefined;
+interface VariableConfig {
+    type: VariableType;
+    default?: VariableValue;
+    persist?: boolean;
+}
+
+declare class VariableStore {
+    private state;
+    private listeners;
+    /** Tracks which keys changed in the last mutation — used by scoped notify */
+    private changedKeys;
+    constructor(initial: Record<string, VariableValue>);
+    getState(): Record<string, VariableValue>;
+    get(key: string): VariableValue;
+    set(key: string, value: VariableValue): void;
+    setState(updater: (prev: Record<string, VariableValue>) => Record<string, VariableValue>): void;
+    /** Batch set multiple variables at once */
+    setMany(updates: Record<string, VariableValue>): void;
+    /**
+     * Subscribe to store changes.
+     *
+     * @param listener - callback fired when relevant keys change
+     * @param scope - optional scope to limit notifications:
+     *   - `{ keys: ['data.x', 'user.email'] }` — only fire when these exact keys change
+     *   - `{ prefix: 'answers.' }` — only fire when any key starting with this prefix changes
+     *   - omit or `{}` — fire on every change (global listener)
+     */
+    subscribe(listener: () => void, scope?: {
+        keys?: string[];
+        prefix?: string;
+    }): () => void;
+    private notify;
+}
 
 /**
- * Type helper for appfunnel.config.ts.
- * Returns the config object unchanged — exists purely for TypeScript autocomplete.
- */
-declare function defineConfig(config: AppFunnelConfig): AppFunnelConfig;
-/**
- * Define page metadata co-located with the page component.
- * Export this from your page file alongside the default React component.
- *
- * @example
- * ```tsx
- * // pages/quiz.tsx
- * import { definePage, useVariable, useNavigation } from '@appfunnel-dev/sdk'
+ * v2 store seeding — builds a {@link VariableStore} holding only the **writable**
+ * namespaces (`user` / `responses` / `data`), each persisted to the backend.
  *
- * export const page = definePage({
- *   name: 'Quiz',
- *   type: 'default',
- *   routes: [
- *     { to: 'checkout', when: { variable: 'plan', equals: 'premium' } },
- *     { to: 'success' },  // fallback
- *   ],
- * })
+ * Seeds the {@link VariableStore} with v2 prefixes (no legacy `answers.`/`query.`
+ * aliasing). Read-only computed values do NOT live
+ * here — see {@link ./context}. Three deliberate namespaces:
  *
- * export default function Quiz() {
- *   // ...
- * }
- * ```
- *
- * The CLI build step collects all `page` exports and assembles them into
- * the full config (pages map + routes map + computed route manifest for analytics).
+ *  - `user.*`      persistent identity attributes (cross-session)
+ *  - `responses.*` the clean, aggregated funnel answers
+ *  - `data.*`      working/scratch state — persisted (so reload + return survive)
+ *                  but kept separate from responses so analytics aggregates only
+ *                  real answers and `data` can hold intermediate garbage
  */
-declare function definePage(definition: PageDefinition): PageDefinition;
 
+/** v2 namespace → store-key prefix (sans trailing dot). 1:1, no legacy aliasing. */
+declare const NAMESPACE_PREFIX: {
+    readonly user: "user";
+    readonly responses: "responses";
+    readonly data: "data";
+};
+type WritableNamespace = keyof typeof NAMESPACE_PREFIX;
+interface FunnelStoreConfig {
+    responses?: Record<string, VariableConfig>;
+    data?: Record<string, VariableConfig>;
+}
 /**
- * Read/write a single variable.
+ * Seed a store from a funnel's declared `responses`/`data` defaults, then layer
+ * server / session-restored values on top (highest priority).
+ */
+declare function createFunnelStore(config?: FunnelStoreConfig, sessionValues?: Record<string, VariableValue>): VariableStore;
+
+/**
+ * v2 `context` — the **read-only, computed** namespace.
+ *
+ * Everything the funnel can *read* but never *write*: the device, the visitor's
+ * locale, the current page, acquisition params (UTM), the session, and system
+ * facts (funnel id, test/live mode, clock). It supersedes the v0 flat
+ * `page.*`/`device.*`/`browser.*`/`os.*`/`query.*`/`metadata.*` system variables
+ * (see {@link ./systemVariables}) by folding them into one nested object.
  *
- * **Advanced** — this hook is not intended for normal page usage.
- * Prefer accessing variables through the standard page props instead.
+ * Why it's *not* in the {@link ./variableStore}: the store holds **writable**
+ * state (`user`/`responses`/`data`) that persists + re-renders per key. Context
+ * is derived and read-only, so it lives as a plain object on a React context —
+ * no subscriptions, no churn. The one moving part (`page`) is merged into the
+ * snapshot from navigation state at read time.
  *
- * ```tsx
- * const [email, setEmail] = useVariable<string>('email')
- * const [count, setCount] = useVariable<number>('count')
- * const [agreed, setAgreed] = useVariable<boolean>('agreed')
- * const [tags, setTags] = useVariable<string[]>('tags')
- * ```
+ * Authors read it through hooks (`useDevice()`, `useLocale()`, `usePage()`,
+ * `useUtm()`) or inside routing/condition predicates as `s.context.*`.
+ */
+interface DeviceContext {
+    type: 'mobile' | 'tablet' | 'desktop';
+    isMobile: boolean;
+    isTablet: boolean;
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    colorDepth: number;
+    pixelRatio: number;
+}
+interface BrowserContext {
+    name: string;
+    version: string;
+    userAgent: string;
+    language: string;
+    cookieEnabled: boolean;
+    online: boolean;
+}
+interface OsContext {
+    name: string;
+    timezone: string;
+}
+interface LocaleContext {
+    /** Full locale, e.g. `en-US`. */
+    locale: string;
+    /** Language subtag, e.g. `en`. */
+    language: string;
+    /** Region subtag, e.g. `US` (may be empty). */
+    region: string;
+    /** IANA timezone, e.g. `America/New_York`. */
+    timeZone: string;
+}
+interface PageContext {
+    /** Current page key. */
+    key: string;
+    /** Current page URL slug (`meta.slug`, defaults to the key) — what the renderer puts in the path. */
+    slug: string;
+    /** 0-based position in the visited history. */
+    index: number;
+    /** Total pages in the (expected) flow. */
+    total: number;
+    /** 0–100. */
+    progressPercentage: number;
+    /** Epoch ms the current page was entered. */
+    startedAt: number;
+}
+/** Acquisition / ad params captured on entry (the old `query.*` utm slice). */
+interface UtmContext {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    content?: string;
+    term?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Per-network ad **click-ids** captured from the entry URL — the matching signals
+ * the server CAPI needs. Named per network (not a generic bag) so the platform +
+ * each integration map them precisely; `[key]` catches any others.
+ */
+interface ClickIdContext {
+    /** Meta / Facebook */
+    fbclid?: string;
+    /** Google Ads (+ gbraid/wbraid for app↔web) */
+    gclid?: string;
+    gbraid?: string;
+    wbraid?: string;
+    /** Microsoft / Bing */
+    msclkid?: string;
+    /** TikTok */
+    ttclid?: string;
+    /** Twitter / X */
+    twclid?: string;
+    /** Snapchat */
+    sccid?: string;
+    /** LinkedIn */
+    li_fat_id?: string;
+    /** Pinterest */
+    epik?: string;
+    /** Reddit */
+    rdt_cid?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * The full acquisition snapshot captured once on entry — the funnel reads `utm` /
+ * `clickIds` off {@link FunnelContext}; the SDK forwards this whole thing to the
+ * tracker (`setAcquisition`) so the platform persists it **first-class**: per-visit
+ * on the session + **first-touch (write-once) on the Customer**, and the click-ids /
+ * `_fbp`/`_fbc` cookies feed CAPI. Not stored as a generic attribute/answer.
+ */
+interface Acquisition {
+    utm: UtmContext;
+    clickIds: ClickIdContext;
+    /** CAPI cookies (`_fbp`/`_fbc`) read from `document.cookie` (not funnel-readable). */
+    cookies: {
+        fbp?: string;
+        fbc?: string;
+    };
+    /** `document.referrer` at entry. */
+    referrer: string;
+    /** Entry URL path (the landing page). */
+    landingPath: string;
+}
+interface SessionContext {
+    /** Server session id; null until resolved. */
+    id: string | null;
+    /** Epoch ms the session began. */
+    startedAt: number;
+    /** `document.referrer` at entry. */
+    referrer: string;
+}
+/**
+ * Durable identity for **stable experiment bucketing** (phase-4 §4.2). The
+ * preferred seed is `customerId` once known; before identification it's the
+ * signed anonymous `visitorId` (P1). It is deliberately **not** the session id or
+ * fingerprint — a returning visitor (e.g. via winback) must keep their variant
+ * across sessions/devices (landmine #4). Both null = unidentifiable traffic, and
+ * the experiment layer falls back to control rather than bucket on nothing.
  */
-declare function useVariable<T extends VariableValue>(id: string): [T, (value: T) => void];
+interface IdentityContext {
+    /** Known customer id (post-identification). The preferred bucketing seed. */
+    customerId: string | null;
+    /** Signed anonymous visitor id. The fallback bucketing seed. */
+    visitorId: string | null;
+}
+interface SystemContext {
+    funnelId: string;
+    campaignId: string;
+    /** Render mode — `test` for preview/QA, `live` for public traffic. */
+    mode: 'test' | 'live';
+    /** Epoch ms captured at build time (stable per render, not a live clock). */
+    now: number;
+}
+/** The whole read-only computed namespace, as read in predicates: `s.context.*`. */
+interface FunnelContext {
+    device: DeviceContext;
+    browser: BrowserContext;
+    os: OsContext;
+    locale: LocaleContext;
+    page: PageContext;
+    utm: UtmContext;
+    /** Per-network ad click-ids captured on entry (funnel-readable; also forwarded for CAPI). */
+    clickIds: ClickIdContext;
+    session: SessionContext;
+    identity: IdentityContext;
+    system: SystemContext;
+}
+/**
+ * Assemble the full {@link Acquisition} snapshot from the context + `document`
+ * (cookies, referrer, path) — captured once on entry, forwarded to the tracker for
+ * first-class persistence (session + first-touch Customer) + CAPI.
+ */
+declare function buildAcquisition(context: FunnelContext): Acquisition;
+interface BuildContextOptions {
+    funnelId?: string;
+    campaignId?: string;
+    mode?: 'test' | 'live';
+    /** Stable build-time clock (avoids `Date.now()` churn in renders/tests). */
+    now?: number;
+    sessionId?: string | null;
+    /** Known customer id — the preferred stable bucketing seed (phase-4 §4.2). */
+    customerId?: string | null;
+    /** Signed anonymous visitor id — the fallback bucketing seed. */
+    visitorId?: string | null;
+    /** Overrides for any slice — used by the server to hydrate `utm`/`session`. */
+    overrides?: Partial<FunnelContext>;
+}
+/**
+ * Build the read-only {@link FunnelContext} once, at mount. `page` starts at the
+ * first page and is replaced per navigation when assembling a snapshot.
+ */
+declare function buildContext(opts?: BuildContextOptions): FunnelContext;
 
 /**
- * Read all variables (including system variables). Read-only.
- * Use useVariable() to write individual variables.
+ * v2 tracking seam — the funnel runtime emits a **fixed event taxonomy**, but
+ * never talks to the network itself. It calls a {@link Tracker} the platform/CLI
+ * injects via {@link FunnelProvider}. The real implementation is the existing
+ * {@link ./tracker}.`FunnelTracker` (session id, ad attribution, debounced
+ * persistence, CAPI fan-out); tests and local dev use {@link createConsoleTracker}.
+ *
+ * The taxonomy is preserved verbatim from v0 so analytics keep working:
+ *   funnel.start · page.view · page.exit · user.registered · experiment.exposure ·
+ *   checkout.start · checkout.payment_added · checkout.failed · purchase.complete
  *
- * **Advanced** — this hook is not intended for normal page usage.
- * Prefer accessing variables through the standard page props instead.
+ * Where each fires (all from the SDK runtime):
+ *   - `funnel.start` / `page.view` / `page.exit` / `experiment.exposure` — navigation
+ *     ({@link ../flow/flow}.`FunnelView`); `page.exit` carries duration + active (visible) time.
+ *   - `user.registered` — `identify()`, the first time `user.email` is written.
+ *   - `checkout.*` / `purchase.complete` — the commerce primitives ({@link ../commerce/checkout}).
+ *     `checkout.payment_added` is reported by an inline driver via `onPaymentAdded` (optional).
  *
- * Warning: this hook subscribes to ALL variable changes, so the
- * component will re-render on every single variable update.
+ * A `responses.set(...)` does **not** emit a discrete event — values are batched into
+ * `userData` and persisted (debounced). Only the events above fire.
  */
-declare function useVariables(): Record<string, VariableValue>;
 
-type DateFormat = 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY-MM-DD';
+interface FunnelEventDataMap {
+    'funnel.start': Record<string, never>;
+    'page.view': {
+        pageId: string;
+        pageKey?: string;
+        pageName?: string;
+        isInitial?: boolean;
+        eventId?: string;
+    };
+    'page.exit': {
+        pageId: string;
+        durationMs: number;
+        activeMs: number;
+    };
+    'user.registered': {
+        email: string;
+        eventId?: string;
+    };
+    'checkout.start': {
+        productId?: string;
+        priceId?: string;
+        productName?: string;
+    };
+    'checkout.payment_added': Record<string, never>;
+    'checkout.failed': {
+        category: string;
+        declineCode?: string;
+        productId?: string;
+        intent?: string;
+    };
+    'purchase.complete': {
+        amount?: number;
+        currency?: string;
+        email?: string;
+        eventId?: string;
+    };
+    'experiment.exposure': {
+        experimentId: string;
+        variant: string;
+    };
+}
+declare function newEventId(): string;
+type KnownFunnelEvent = keyof FunnelEventDataMap;
+/**
+ * The surface the runtime needs from a tracker. A subset of `FunnelTracker`, so
+ * the real one satisfies it directly; the console tracker is a trivial stub.
+ */
+interface Tracker {
+    /** Emit a known event (typed) or any custom event name. */
+    track<E extends KnownFunnelEvent>(event: E, data?: FunnelEventDataMap[E], userData?: Record<string, unknown>): void;
+    track(event: string, data?: Record<string, unknown>, userData?: Record<string, unknown>): void;
+    /**
+     * Identify by email — fires `user.registered` (idempotent in the impl). The
+     * optional `eventId` is the browser↔CAPI dedup key for the registration event.
+     */
+    identify(email: string, eventId?: string): void;
+    /** Push the latest variable snapshot for batched/debounced persistence. */
+    setVariables?(variables: Record<string, unknown>): void;
+    /**
+     * The acquisition snapshot (utm + click-ids + `_fbp`/`_fbc` + referrer), pushed
+     * once on entry. The platform persists it first-class — per-visit on the session +
+     * **first-touch (write-once) on the Customer** — and feeds it to CAPI. Optional;
+     * the console/test trackers ignore it.
+     */
+    setAcquisition?(acquisition: Acquisition): void;
+}
+/** A no-op-ish tracker that logs to the console — for tests, preview, local dev. */
+declare function createConsoleTracker(opts?: {
+    silent?: boolean;
+}): Tracker;
+/**
+ * `const { track } = useTracker()` — emit a custom event. Auto events
+ * (page.view, identify, purchase, …) fire on their own; this is the escape
+ * hatch for funnel-specific events (`track('quiz_skipped', { step: 3 })`).
+ */
+declare function useTracker(): {
+    track: Tracker['track'];
+};
 
 /**
- * Read built-in user state (email, name, customerId).
+ * v2 `products` — the **read-only** product catalog.
+ *
+ * **AppFunnel does not manage currency.** Multi-currency is entirely the payment
+ * provider's job: the provider (or its preview API) resolves the visitor's price,
+ * and we receive a single resolved `{ amount, currency }` per product. No FX, no
+ * currency selection, no conversion on our side. (FX appears only for frozen-USD
+ * *reporting*, never display — phase-3 §3.6b.) A provider that doesn't localize
+ * simply gives one currency.
  *
- * Only re-renders when a `user.*` variable changes.
- * For reading/writing arbitrary user fields, use `useUserProperty('fieldName')`.
+ * Our only job is **display**: pick the product by logical id and **format** its
+ * amount. Formatting happens at read time in the funnel's **active locale** (so
+ * switching language reformats `kr 79,00` ⇄ `$9.99`), while the **currency** is
+ * whatever the provider resolved. Currency selection is the platform's; the
+ * authoring funnel only ever names a product id.
  */
-declare function useUser(): UserState;
+
+type Interval = 'day' | 'week' | 'month' | 'year' | 'one_time';
+/** What the platform hands the funnel per product (a single provider-resolved price). */
+interface ProductInput {
+    id: string;
+    name?: string;
+    displayName?: string;
+    /** Provider-resolved price in **minor units** (the provider chose the currency). */
+    amount: number;
+    /** Currency of `amount`, as the provider resolved it (e.g. `DKK`). */
+    currency: string;
+    interval?: Interval;
+    intervalCount?: number;
+    trialDays?: number;
+    /** Trial price in minor units (omit/0 = free trial). */
+    trialAmount?: number;
+    /** Settlement provider — opaque to the author, used by the checkout driver. */
+    provider?: string;
+}
+/** A money value with a locale-formatted string. */
+interface Money {
+    /** Major units, e.g. `79`. */
+    amount: number;
+    /** Minor units, e.g. `7900`. */
+    minor: number;
+    currency: string;
+    /** Locale-formatted, e.g. `kr 79,00` / `€9,99` / `$9.99`. */
+    formatted: string;
+}
 /**
- * Read/write a user property by field name.
- * Auto-prefixes with `user.` — no need to define in config.
- *
- * ```tsx
- * const [dob, setDob] = useUserProperty('dateOfBirth')
- * const [gender, setGender] = useUserProperty('gender')
- * ```
+ * The product with its amounts resolved (currency + period math), **before**
+ * locale formatting — what the catalog stores. {@link useProduct} formats it.
  */
-declare function useUserProperty(field: string): [string, (value: string) => void];
+interface ResolvedProduct {
+    id: string;
+    name: string;
+    displayName: string;
+    provider: string;
+    currency: string;
+    priceMinor: number;
+    perDayMinor: number;
+    perWeekMinor: number;
+    perMonthMinor: number;
+    perYearMinor: number;
+    period: string;
+    periodly: string;
+    hasTrial: boolean;
+    trialDays: number;
+    trialMinor: number;
+}
+/** Display-ready product the author reads (every amount locale-formatted). */
+interface Product {
+    id: string;
+    name: string;
+    displayName: string;
+    provider: string;
+    price: Money;
+    /** e.g. `month`, `quarter`, `one-time`. */
+    period: string;
+    /** e.g. `monthly`, `quarterly`, `one-time`. */
+    periodly: string;
+    /** Period-normalized prices (for "just $0.27/day" style copy). */
+    perDay: Money;
+    perWeek: Money;
+    perMonth: Money;
+    perYear: Money;
+    hasTrial: boolean;
+    trialDays: number;
+    trialPrice: Money | null;
+}
+/** Resolve a {@link ProductInput} into amounts + period math (no formatting yet). */
+declare function resolveProduct(input: ProductInput): ResolvedProduct;
+/** Build the id → {@link ResolvedProduct} catalog. Formatting happens at read time. */
+declare function buildCatalog(inputs: ProductInput[]): Map<string, ResolvedProduct>;
+/** Format a {@link ResolvedProduct} into a display {@link Product} in `locale`. */
+declare function formatProduct(r: ResolvedProduct, locale: string): Product;
+/** `useProduct('monthly')` — one product, formatted in the active locale. */
+declare function useProduct(id: string | undefined): Product | undefined;
+/** `useProducts()` — every product, formatted in the active locale, in order. */
+declare function useProducts(): Product[];
+
 /**
- * Read/write the user's date of birth.
- * Always stores the value as YYYY-MM-DD regardless of input format.
+ * v2 commerce primitives — the two intents from phase-3, made trivial.
  *
- * @param format - How the input string should be interpreted (default: MM/DD/YYYY).
+ *  - `<Checkout product surface>` — the **purchase** primitive. The `surface`
+ *    prop picks presentation; some surfaces render **inline** (express wallets,
+ *    inline card, provider iframe), some **open on click** (sheet/popup/redirect).
+ *    `<Checkout>` covers both: it renders inline surfaces and renders a trigger
+ *    button for the rest (`asChild` to use your own button).
+ *  - `<Upsell product>` — the **upsell** primitive. Off-session charge to the
+ *    saved method, no card re-entry, one tap.
+ *  - `useCheckout()` — the headless hook under both, always available for a
+ *    fully-custom CTA.
  *
- * ```tsx
- * const [dob, setDob] = useDateOfBirth()              // defaults to MM/DD/YYYY
- * const [dob, setDob] = useDateOfBirth('DD/MM/YYYY')  // explicit EU format
+ * The SDK never talks to a provider. It owns the state machine + the analytics
+ * (`checkout.start` / `purchase.complete`) + post-charge navigation, and
+ * delegates the actual charge/render to an injected {@link CheckoutDriver}
+ * (the real one is platform-side; tests use {@link createMockDriver}).
  *
- * setDob('03/15/1990')  // stored as "1990-03-15"
- * setDob('03151990')    // stored as "1990-03-15"
- * ```
+ * Which product is charged is the author's bound variable, captured at render
+ * (inline surfaces) or at `open()` time (trigger surfaces).
  */
-declare function useDateOfBirth(format?: DateFormat): [string, (value: string) => void];
 
+type CheckoutSurface = 'express' | 'element' | 'embedded' | 'sheet' | 'popup' | 'redirect';
+type CheckoutProvider = 'stripe' | 'paddle' | 'whop' | 'primer' | 'solidgate';
+type CheckoutIntent = 'purchase' | 'upsell';
+/** Surfaces that render inline (vs. those that open on click). */
+declare const INLINE_SURFACES: ReadonlySet<CheckoutSurface>;
+declare function isInlineSurface(surface: CheckoutSurface): boolean;
 /**
- * Read/write a single response variable (answers.*).
- *
- * ```tsx
- * const [goal, setGoal] = useResponse<string>('goal')
- * const [interests, setInterests] = useResponse<string[]>('interests')
- * ```
+ * The kind of off-session upsell (researched against Funnelfox's changelog, which
+ * ships these as distinct features). The discriminating real-world constraint is
+ * **stacking a 2nd concurrent subscription** — Paddle can't, SolidGate/Stripe can.
  */
-declare function useResponse<T extends VariableValue>(key: string): [T, (value: T) => void];
+type UpsellKind = 'subscription' | 'one-time' | 'upgrade';
+/** Reliability of an off-session upsell charge AFTER a purchase on a surface. */
+type OffSessionReliability = 'reliable' | 'conditional' | 'none';
+interface SurfaceCapability {
+    purchase: boolean;
+    /** Apple/Google Pay available on this surface. */
+    wallets: boolean;
+    /** Reliability of an off-session upsell after a purchase on this surface. */
+    offSession: OffSessionReliability;
+}
+interface ProviderProfile {
+    /** Merchant-of-Record (handles tax/compliance) vs. a PSP you settle through. */
+    isMoR: boolean;
+    /** Upsell kinds this provider can charge off-session (one-click, no re-entry). */
+    offSessionUpsells: UpsellKind[];
+    /** Who charges the saved method off-session: you (PSP) or the provider (MoR/managed). */
+    tokenModel: 'merchant' | 'provider';
+    /** Routes across multiple processors (Primer; SolidGate also offers this) vs. a single acquirer. */
+    orchestrator: boolean;
+    /** Supported surfaces → per-surface capabilities. **Absent = not supported.** */
+    surfaces: Partial<Record<CheckoutSurface, SurfaceCapability>>;
+}
 /**
- * Read all response variables as a flat object (without the `answers.` prefix).
+ * Provider capabilities (researched 2026-06-23 against provider docs + Funnelfox).
  *
- * Only re-renders when an `answers.*` variable changes.
+ * Three real-world corrections to the naive model:
+ *  1. **Off-session upsell support is per-provider by *kind*** (`offSessionUpsells`):
+ *     Paddle can't stack a 2nd concurrent subscription (upgrade + one-time only);
+ *     Stripe/SolidGate/Whop/Primer can do all kinds.
+ *  2. **Off-session *reliability* varies by the paywall surface** (`SurfaceCapability.
+ *     offSession`): Stripe **managed** checkout (`embedded`/`redirect`) upsells as a
+ *     direct charge against Stripe's vault → `conditional` (may decline); Elements
+ *     surfaces are `reliable`.
+ *  3. **Surface availability is a hard constraint.** MoR/managed providers can't
+ *     expose a raw card field to your own UI: Paddle has no `express`/`element`/your
+ *     `sheet`; Whop has no raw `element`/`express`; Primer has no hosted `redirect`;
+ *     Stripe/SolidGate have no `popup`. A missing entry means "not possible."
+ */
+declare const PROVIDER_PROFILES: Record<CheckoutProvider, ProviderProfile>;
+interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+    /** Non-fatal caveat (e.g. Paddle upgrade-only). */
+    note?: string;
+}
+/** Surfaces a provider supports, for the editor/AI to steer authors. */
+declare function surfacesFor(provider: CheckoutProvider): CheckoutSurface[];
+/** Whether a provider is a Merchant of Record (it owns tax/compliance). */
+declare function isMerchantOfRecord(provider: CheckoutProvider): boolean;
+/** Whether a provider routes across multiple processors (Primer, SolidGate). */
+declare function isOrchestrator(provider: CheckoutProvider): boolean;
+/**
+ * Validate a (provider, surface) for a **purchase**: the surface must exist for
+ * the provider and accept a payment. Surface availability is the real constraint
+ * (e.g. Paddle has no `element`).
+ */
+declare function validateCheckout(provider: CheckoutProvider, surface: CheckoutSurface): ValidationResult;
+/**
+ * Validate an **off-session upsell** of `kind` after a purchase made on
+ * `paywallSurface`. Combines provider support for the kind (Paddle can't stack a
+ * 2nd subscription) with the paywall surface's off-session reliability (Stripe
+ * managed checkout is `conditional` — returned as a `note`, not a hard block).
+ */
+declare function validateUpsell(provider: CheckoutProvider, paywallSurface: CheckoutSurface, kind?: UpsellKind): ValidationResult;
+type CheckoutStatus = 'idle' | 'loading' | 'requires_action' | 'success' | 'error';
+interface CheckoutRequest {
+    product: string;
+    intent: CheckoutIntent;
+    surface?: CheckoutSurface;
+    /** For `upsell` intent — which kind of off-session charge (default `subscription`). */
+    kind?: UpsellKind;
+}
+/**
+ * Normalized failure category — the driver/platform maps each provider's decline
+ * codes into one of these so funnels can route/recover by reason. `authentication_
+ * required` (3DS/SCA) and `requires_payment_method` are the cases an **off-session**
+ * upsell can't satisfy → recover on-session (re-collect a card).
+ */
+type CheckoutErrorCategory = 'card_declined' | 'insufficient_funds' | 'expired_card' | 'authentication_required' | 'requires_payment_method' | 'processing_error' | 'canceled' | 'unknown';
+interface CheckoutError {
+    category: CheckoutErrorCategory;
+    message: string;
+    /** Raw provider decline code, if any (e.g. Stripe `card_declined`/`insufficient_funds`). */
+    declineCode?: string;
+    /** Whether re-attempting (e.g. an on-session re-collection) may succeed. */
+    retryable: boolean;
+}
+/** Build a {@link CheckoutError} (driver/test helper). */
+declare function checkoutError(category: CheckoutErrorCategory, message: string, extra?: {
+    declineCode?: string;
+    retryable?: boolean;
+}): CheckoutError;
+interface CheckoutResult {
+    ok: boolean;
+    error?: CheckoutError;
+    /** Charged amount in minor units (for the purchase event). */
+    amountMinor?: number;
+    currency?: string;
+    /**
+     * The **server-minted** dedup id for the purchase event — the platform creates it
+     * when the charge settles and fires CAPI with it; the SDK emits `purchase.complete`
+     * with the same id so the browser pixel dedupes against the server. (Server is the
+     * source of truth for payment events; the SDK doesn't mint these.)
+     */
+    eventId?: string;
+}
+interface CheckoutCallbacks {
+    onSuccess: (result: CheckoutResult) => void;
+    onError: (error: CheckoutError) => void;
+    /**
+     * The inline surface reports a valid payment method was entered (e.g. Stripe's
+     * Payment Element became `complete`), before the charge. Drives the
+     * `checkout.payment_added` analytics step; optional — drivers that can't observe
+     * it (or off-session charges) simply never call it.
+     */
+    onPaymentAdded?: () => void;
+}
+/**
+ * The provider seam. The platform injects the real one (Stripe/Paddle/Whop/…);
+ * tests use {@link createMockDriver}.
  *
- * ```tsx
- * const responses = useResponses()
- * // { goal: 'weight_loss', interests: ['yoga', 'running'] }
- * ```
+ * Most providers ship their **own React SDK** (`@stripe/react-stripe-js`,
+ * `@paddle/paddle-js`, Primer's React components, …). A driver's `renderInline`
+ * returns exactly that: the provider's React element mounted in our chrome (inline,
+ * or inside the `<Sheet>`). Those provider SDKs live in the **driver/platform**
+ * package, not our core funnel SDK — which is why the driver is injected: the core
+ * stays lean and provider-agnostic, and you only pull the SDK for the provider you use.
  */
-declare function useResponses(): Record<string, VariableValue>;
+interface CheckoutDriver {
+    provider: CheckoutProvider;
+    /** Trigger a charge (trigger surfaces + programmatic). Resolves when settled. */
+    start(req: CheckoutRequest): Promise<CheckoutResult>;
+    /** Render an inline surface (e.g. the provider's React payment element); report via callbacks. */
+    renderInline?(req: CheckoutRequest, cb: CheckoutCallbacks): ReactNode;
+}
+interface MockDriverOptions {
+    /** The result a successful charge resolves with. */
+    result?: CheckoutResult;
+    /** Make **off-session** charges (no surface) fail — to exercise the upsell fallback. */
+    failOffSession?: CheckoutError | boolean;
+}
+/** A console/no-op driver — tests, preview, local dev. Succeeds unless configured to fail. */
+declare function createMockDriver(provider?: CheckoutProvider, options?: MockDriverOptions): CheckoutDriver;
+interface UseCheckoutOptions {
+    intent?: CheckoutIntent;
+    /** For `upsell` intent — which kind of off-session charge (default `subscription`). */
+    kind?: UpsellKind;
+    /** Advance to the next page after a successful charge (default: true). */
+    advanceOnSuccess?: boolean;
+    onSuccess?: (result: CheckoutResult) => void;
+    onError?: (error: CheckoutError) => void;
+}
+interface CheckoutHandle {
+    /** Start the charge for a product; resolves with the result (no surface = off-session). */
+    open: (product: string, surface?: CheckoutSurface) => Promise<CheckoutResult>;
+    status: CheckoutStatus;
+    /** The last failure, structured so you can route/recover by `category`. */
+    error: CheckoutError | null;
+    isLoading: boolean;
+    reset: () => void;
+    /** Build the callbacks an inline surface reports through (used by `<Checkout>`). */
+    callbacksFor: (product: string, surface?: CheckoutSurface) => CheckoutCallbacks & {
+        onStart: () => void;
+    };
+}
+/**
+ * The headless checkout hook. Owns the state machine + analytics + post-charge
+ * navigation; delegates the charge to the injected {@link CheckoutDriver}.
+ */
+declare function useCheckout(opts?: UseCheckoutOptions): CheckoutHandle;
+interface CheckoutProps extends UseCheckoutOptions {
+    /** Logical product id (the author's bound selection). */
+    product: string;
+    surface: CheckoutSurface;
+    /** Render your own trigger element instead of the default button (trigger surfaces). */
+    asChild?: boolean;
+    /** Trigger label / your trigger element. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * The purchase primitive. Three presentation modes by `surface`:
+ *  - **inline** (`express`/`element`/`embedded`) — the driver renders the
+ *    provider UI in place (keyed by product so a selection change remounts it);
+ *  - **SDK sheet** (`sheet`) — a trigger opens the AppFunnel-owned {@link Sheet}
+ *    and the driver renders the provider element inside it;
+ *  - **provider-hosted** (`popup`/`redirect`) — a trigger hands off to the
+ *    provider's own overlay/page.
+ */
+declare function Checkout({ product, surface, asChild, children, className, ...options }: CheckoutProps): ReactNode;
+interface UpsellProps extends Omit<UseCheckoutOptions, 'intent'> {
+    product: string;
+    /**
+     * If the off-session charge fails, present this surface **on-session** to
+     * re-collect a card and charge again — e.g. `fallback="sheet"` opens the
+     * payment sheet, `fallback="popup"` the provider overlay. Omit to just report
+     * the failure (via `onError` / the `checkout.failed` event).
+     */
+    fallback?: CheckoutSurface;
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * The upsell primitive — an off-session, one-tap charge to the saved method (no
+ * surface, no card re-entry). On failure, optionally `fallback` to an on-session
+ * surface to re-collect and retry.
+ */
+declare function Upsell({ product, fallback, asChild, children, className, ...options }: UpsellProps): ReactNode;
 
 /**
- * Read all URL query parameters as a flat object (without the `query.` prefix).
+ * The funnel **spine** — the constrained, declarative configuration authored as
+ * code (`defineFunnel` / `pageMeta` / `definePage`) yet **dashboard-editable**
+ * (static AST parse → pretty UI → codegen) and compiled to the manifest IR.
+ *
+ * Principle: **presentation = code** (the page components), **configuration =
+ * data** (this spine). See docs/platform-v2/06-funnel-project-model.md.
  *
- * Only re-renders when a `query.*` variable changes.
+ * Routing is **declarative nodes + code predicates** (decided — doc 06): a
+ * page's `next` is an ordered list of {@link Route}s, each with a **static `to`
+ * page key** (so the dashboard can draw every possible edge without executing
+ * anything) and an optional `when` **gate** that returns true/false. The gate is
+ * either a declarative {@link Condition} (one field — UI-editable data) or a code
+ * {@link Predicate} (`s => boolean` — the escape hatch, opaque body but the edge
+ * is still visible). First matching route wins; a route with no `when` is the
+ * fallback. Multiple conditions = multiple routes (or boolean logic in one
+ * predicate). Omit `next` entirely for the default linear flow.
  */
-declare function useQueryParams(): Record<string, string>;
 /**
- * Read a single query parameter by name.
- *
- * ```tsx
- * const utmSource = useQueryParam('utm_source')
- * ```
+ * Read-only view of every namespace a routing/condition predicate can branch
+ * on. `user`/`responses`/`data` are the writable namespaces; `context` is the
+ * read-only computed one ({@link FunnelContext}).
+ */
+interface FunnelSnapshot {
+    user: Record<string, VariableValue>;
+    responses: Record<string, VariableValue>;
+    data: Record<string, VariableValue>;
+    context: FunnelContext;
+}
+/** A code-predicate gate — `s => s.responses.goal === 'gain'`. */
+type Predicate = (s: FunnelSnapshot) => boolean;
+type ConditionOp = 'eq' | 'neq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte' | 'exists' | 'empty' | 'contains';
+/**
+ * A declarative gate over **one** namespaced field — UI-editable data the
+ * dashboard renders as a condition row (`field` `op` `value`). `field` is a
+ * dotted path into the snapshot: `responses.goal`, `user.country`,
+ * `context.device.isMobile`.
+ */
+interface Condition {
+    field: string;
+    op: ConditionOp;
+    value?: VariableValue | VariableValue[];
+}
+/** An edge gate: either declarative data ({@link Condition}) or a {@link Predicate}. */
+type Gate = Condition | Predicate;
+/**
+ * One routing edge out of a page. `to` is a **static** target key (the dashboard
+ * reads these to draw the flow graph); `when` gates the edge (omit = fallback).
+ */
+interface Route {
+    to: string;
+    when?: Gate;
+}
+/** Evaluate a declarative {@link Condition} against a snapshot. */
+declare function evaluateCondition(cond: Condition, s: FunnelSnapshot): boolean;
+/** Evaluate either gate kind to a boolean. */
+declare function evaluateGate(gate: Gate, s: FunnelSnapshot): boolean;
+/**
+ * Resolve an ordered list of routes to a target page key, or `undefined` to fall
+ * through to the linear next. First route whose gate passes (or has no `when`)
+ * wins.
+ */
+declare function resolveRoute(routes: Route[] | undefined, s: FunnelSnapshot): string | undefined;
+type PageType = 'default' | 'email-capture' | 'paywall' | 'upsell' | 'finish';
+interface PageMeta {
+    /** Page kind — drives behavior + analytics (e.g. `paywall`, `upsell`). */
+    type?: PageType;
+    /** URL slug; defaults to the page key. */
+    slug?: string;
+    /**
+     * Ordered routing edges out of this page (first match wins). Each has a static
+     * `to` key + an optional `when` gate. Omit for the default linear flow.
+     */
+    next?: Route[];
+    /**
+     * Entry precondition for **deep-link / reload** restoration. When the runtime is
+     * asked to start *on this page* (not via in-funnel navigation), it restores there
+     * only if `guard` passes against the restored snapshot — otherwise it falls back
+     * to the start page. e.g. an upsell page: `guard: s => s.data.purchased === true`.
+     * Reaching the page via `next()` is unaffected (routing already gated it). Omit =
+     * always restorable. Same gate kind as routing (`Condition` or predicate).
+     */
+    guard?: Gate;
+}
+/**
+ * Identity helper for a page's co-located metadata.
+ * `export const meta = pageMeta({ type: 'paywall', next: s => … })`.
+ */
+declare function pageMeta(meta: PageMeta): PageMeta;
+/**
+ * The effective entry guard for a page: an explicit `meta.guard` if the author set
+ * one, **otherwise** the page-type default (e.g. paywall/upsell need email). The
+ * explicit guard fully **overrides** the default — it's not combined. Returns
+ * `undefined` when neither applies.
+ */
+declare function entryGuard(meta?: PageMeta): Gate | undefined;
+/**
+ * Identity helper for a page component. The page is plain React that reaches the
+ * runtime through hooks (`useResponse`, `useNavigation`, …) — there is no `sdk`
+ * prop. `export default definePage(function Welcome() { … })`.
+ */
+declare function definePage<P extends object = Record<string, never>>(component: ComponentType<P>): ComponentType<P>;
+/** A page in the flow: its key + (optional) co-located meta. */
+interface FlowPage {
+    key: string;
+    meta?: PageMeta;
+}
+/**
+ * Decide the next page from `currentKey`:
+ *  1. the current page's `next` routes ({@link resolveRoute}), if one matches, else
+ *  2. the next page in file order (the default linear flow), else
+ *  3. `undefined` (end of funnel / current key not found).
+ */
+declare function nextPage(pages: FlowPage[], currentKey: string, s: FunnelSnapshot): string | undefined;
+/**
+ * Every page a visitor *could* go to next from `currentKey` — all route targets
+ * (regardless of gate, since we don't know which will pass) plus the linear next.
+ * Used to **prefetch** the likely-next page chunks; not for navigation.
+ */
+declare function outgoingKeys(pages: FlowPage[], currentKey: string): string[];
+/**
+ * The number of pages on the path from `startKey` to a `finish` (or the end of
+ * the flow) **given the current state** — the denominator for progress. It walks
+ * the actual routing ({@link nextPage}) rather than counting all files, so a
+ * branched funnel reaches 100% on whichever path the visitor's answers select.
+ * Re-traced per navigation; a visited set guards against routing cycles.
+ */
+declare function expectedPathLength(pages: FlowPage[], startKey: string, s: FunnelSnapshot): number;
+interface FunnelLocales {
+    default: string;
+    supported: string[];
+    fallback?: string;
+}
+/**
+ * The funnel-level spine. Flow is mostly inferred from page file order + each
+ * page's `next`; this holds the funnel-wide config. Stays **thin** — routing
+ * lives co-located on pages (doc 06: "funnel.ts stays thin").
  */
-declare function useQueryParam(key: string): string;
+interface FunnelDefinition {
+    id: string;
+    /** `responses.*` runtime variables (default values). */
+    responses?: Record<string, VariableConfig>;
+    /** `data.*` working/scratch variables (default values). */
+    data?: Record<string, VariableConfig>;
+    /** Product ids from the platform catalog this funnel uses (prices resolved at render). */
+    products?: string[];
+    locales?: FunnelLocales;
+    /**
+     * When `true`, the funnel shows the **geo-specific** currency/price the payment
+     * provider resolves (Stripe `currency_options`, Paddle preview, Whop, SolidGate,
+     * …). When `false` (default), a single fixed currency is used. AppFunnel does no
+     * FX — this only toggles whether the platform asks the provider for the geo
+     * price; the SDK just displays whatever resolved `{amount, currency}` it's handed.
+     * (See docs/platform-v2 phase-3 §3.6.)
+     */
+    locationAwareCurrency?: boolean;
+}
+/** Identity helper for a funnel definition. */
+declare function defineFunnel(def: FunnelDefinition): FunnelDefinition;
 
 /**
- * Read/write a single data variable (data.*).
+ * v2 localization — translated **text** (prices already localize via `Intl` in
+ * {@link ./catalog}). Per doc 05: locales live in the funnel source — supported
+ * locales + default + fallback are funnel config ({@link FunnelLocales}), and
+ * each locale is a flat `key → string` **catalog** (`messages/en.json`, …),
+ * versioned + published with the funnel. The dashboard's manual translation
+ * table edits exactly these catalogs.
  *
- * ```tsx
- * const [tier, setTier] = useData<string>('selectedPlanTier')
- * const [seen, setSeen] = useData<boolean>('hasSeenOnboarding')
- * ```
+ * Lookup walks a **fallback chain** (active → fallback → default) so a missing
+ * string never blanks — it falls through, and only as a last resort returns the
+ * key (flagged in dev). Interpolation is simple `{{var}}`; plurals use the
+ * built-in `Intl.PluralRules`; numbers/dates/percent use `Intl`. No ICU, no rich
+ * markup (markup stays in TSX).
  */
-declare function useData<T extends VariableValue>(key: string): [T, (value: T) => void];
 
+/** locale → (message key → string). The shape of `messages/<locale>.json`. */
+type MessageCatalog = Record<string, Record<string, string>>;
+type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+type Direction = 'ltr' | 'rtl';
+/** Whether a locale is right-to-left (by language subtag). */
+declare function isRtl(locale: string): boolean;
 /**
- * Get the user's locale from the browser.
- *
- * Provides language, region, and currency info derived from the browser.
- * Combine with i18n libraries (react-i18next, next-intl, etc.) for translations.
- *
- * ```tsx
- * const { language, region, currency } = useLocale()
- * // language: 'en', region: 'US', currency: 'USD'
- * ```
+ * Resolve the active locale: `override` (URL/param) → `detected` (device) →
+ * funnel default, each only if supported (matched by exact tag or language
+ * subtag). Mirrors doc 05's resolution chain (the geo/header steps happen
+ * server-side and arrive via `override`/`detected`).
+ */
+declare function resolveLocale(config: FunnelLocales | undefined, detected: string, override?: string): string;
+interface TFunction {
+    /** Translate a key, with optional `{{var}}` params. Missing → fallback → key. */
+    (key: string, params?: Record<string, string | number>): string;
+    /** Locale-correct plural: `t.plural(n, { one: '# day', other: '# days' })` (`#` → n). */
+    plural: (n: number, forms: Partial<Record<PluralCategory, string>>, params?: Record<string, string | number>) => string;
+}
+interface Formatters {
+    number: (n: number, opts?: Intl.NumberFormatOptions) => string;
+    date: (d: Date | number, opts?: Intl.DateTimeFormatOptions) => string;
+    percent: (n: number, opts?: Intl.NumberFormatOptions) => string;
+}
+interface Translation {
+    t: TFunction;
+    fmt: Formatters;
+    /** The active (resolved) locale. */
+    locale: string;
+    /** Switch locale at runtime (preview / language picker). */
+    setLocale: (locale: string) => void;
+    /** Text direction for the active locale. */
+    dir: Direction;
+    /** The funnel's supported locales. */
+    locales: string[];
+}
+/**
+ * `const { t, fmt, locale, dir } = useTranslation()` — translated text +
+ * locale-aware `Intl` formatters for the active funnel locale.
  */
-declare function useLocale(): LocaleState;
+declare function useTranslation(): Translation;
 
 /**
- * Access translations for the current locale.
+ * Toast — a thin convenience re-export of {@link https://sonner.emilkowal.ski | sonner}.
  *
- * ```tsx
- * const { t, locale, setLocale } = useTranslation()
+ * Authors call `toast.success(...)` / `toast.error(...)` anywhere in their funnel.
+ * `FunnelProvider` auto-mounts {@link FunnelToaster} (opt out with `toaster={false}`),
+ * so toasts work with no setup; render it yourself if you want a custom location.
  *
- * return (
- *   <div>
- *     <h1>{t('welcome', { name: 'John' })}</h1>
- *     <button onClick={() => setLocale('de')}>Deutsch</button>
- *   </div>
- * )
- * ```
+ * This is the *one* opinionated UI we re-export — kept deliberately thin (just the
+ * imperative `toast` + a defaulted `<Toaster>`), because error/info surfacing is a
+ * near-universal funnel need and sonner is tiny. Everything else stays headless.
  */
-declare function useTranslation(): TranslationState;
+
+/** Sonner's `<Toaster>` with funnel defaults (top-center); pass any `ToasterProps` to override. */
+declare function FunnelToaster(props?: ToasterProps): ReactNode;
 
 /**
- * Navigation hook — evaluates routes, navigates between pages, tracks progress.
+ * **Runtime page-level experiments** — A/B/n on a *single page inside one funnel*,
+ * resolved at render time (phase-4). No funnel duplication: a slot (e.g. the page
+ * `welcome`) has alternate versions filed as siblings (`welcome@b.tsx`), and the
+ * runtime shows **one** of them per visitor, collapsing the losers out of the
+ * linear flow. The flow keeps stable **slot keys** (the control's key); only the
+ * rendered component swaps — so routing, the manifest, and analytics all key on the
+ * slot, not the variant.
+ *
+ * **Where the wiring lives:** the *variant pages* are code (compiled into the
+ * bundle). The *experiment wiring* — slot, variant→page map, weights, status — is
+ * **operational data the platform owns** (a DB record, edited by the dashboard,
+ * changed without recompiling the funnel). The SDK is storage-agnostic: the
+ * platform hands the runtime experiment records to `FunnelProvider`, the same way
+ * it hands in resolved product prices. This module just resolves them.
+ *
+ * **The only source-side marker** is the `@` in a variant file's key
+ * (`welcome@b`): it tells the *build* (manifest, flow graph) that a page is an
+ * off-flow variant of its slot, so the structure is correct without the DB. The
+ * label/weight/experiment-id are not in source.
  *
- * Only re-renders when the router's current page changes (not on variable changes).
- * Variables are read lazily at navigation time — callbacks are referentially stable.
+ * Bucketing is a deterministic FNV-1a hash, **namespaced by experiment id** so
+ * independent experiments bucket orthogonally (the basis for layering 100+ tests,
+ * §4.3). The seed is the durable identity ({@link bucketingSeed}) — never the
+ * session/fingerprint — so a returning visitor keeps their variant (landmine #4).
+ * Stability across an *add-a-variant* edit is the platform's job: an experiment's
+ * variant set is immutable while running (reweighting / adding an arm = a new
+ * experiment version), so within one record the assignment never moves.
+ *
+ * This module is pure (no React, no I/O) → it unit-tests trivially and the
+ * dashboard/server can reuse the same assignment math.
  */
-declare function useNavigation(): NavigationState;
 
 /**
- * Products hook — access product list, selected product, and selection handler.
- *
- * Only re-renders when `products.selectedProductId` changes.
+ * FNV-1a 32-bit hash → unsigned int. Deterministic and isomorphic (no `crypto`,
+ * runs the same in the browser, a worker, and a build). The same math v0 used,
+ * kept because it's sound — only the *seed* changes (identity, not session).
  */
-declare function useProducts(): ProductsState;
-
+declare function fnv1a(input: string): number;
+/** Map a seed string to a stable float in `[0, 1)`. */
+declare function hashToUnit(seed: string): number;
 /**
- * Tracking hook — fire custom events.
+ * Pick a variant key by weight from a stable unit position `u ∈ [0,1)`. Variants
+ * are walked in declaration order and the first whose cumulative weight band
+ * contains `u` wins, so the same `u` always lands in the same variant.
  */
-declare function useTracking(): TrackingState;
-
+declare function pickByWeight(weights: Record<string, number>, u: number): string;
+/**
+ * Deterministically assign a visitor (`seed`) to a variant of one experiment.
+ * The hash is **namespaced by `experimentId`** so two experiments on the same
+ * traffic don't correlate (orthogonal layering).
+ */
+declare function assignVariant(experimentId: string, seed: string, weights: Record<string, number>): string;
+/**
+ * The stable bucketing seed: the known `customerId`, else the signed `visitorId`.
+ * Never the session id or fingerprint (landmine #4). `null` when neither is known
+ * — the caller then serves control instead of bucketing on nothing.
+ */
+declare function bucketingSeed(context: FunnelContext): string | null;
+/** Split a page key into its slot + optional variant: `welcome@b` → `{ slot, variant: 'b' }`. */
+declare function parseSlotKey(key: string): {
+    slot: string;
+    variant?: string;
+};
+/** True if a page key is an off-flow variant (`welcome@b`), by the source-side `@` marker. */
+declare function isVariantKey(key: string): boolean;
+/** One arm of an experiment: which page renders, at what weight. */
+interface ExperimentVariant {
+    /** The page key this arm renders (the slot's control, or a `@variant` sibling). */
+    page: string;
+    /** Relative weight in the split (need not sum to 100; zero = paused arm). */
+    weight: number;
+}
+/**
+ * A runtime experiment record — the operational wiring the **platform** owns and
+ * hands to the SDK (not authored in the funnel source). The variant *pages* are
+ * code in the bundle; this is the live config over them.
+ */
+interface RuntimeExperiment {
+    id: string;
+    /** The page key holding the flow position (the anchor / control). */
+    slot: string;
+    /** label → arm. One arm's `page` is the `slot` (control); others are `@variant` siblings. */
+    variants: Record<string, ExperimentVariant>;
+    /** Lifecycle. Absent = running. */
+    status?: 'running' | 'paused' | 'stopped';
+    /** When stopped, the variant label everyone sees until promotion bakes it into the slot. */
+    winner?: string;
+    /** Primary metric (analytics only; not used for resolution). */
+    metric?: string;
+}
+interface ExperimentResolution {
+    /** experiment id → assigned variant label. */
+    assignments: Record<string, string>;
+    /** Page keys forming the effective linear flow (variant siblings removed), in order. */
+    activeKeys: string[];
+    /** Slot key → the page key whose component should render there. */
+    render: Record<string, string>;
+    /** Variant page key → its slot key. For remapping a route that targets a variant. */
+    slotOf: Record<string, string>;
+    /** Slot key → the experiment id it hosts (drives the exposure event). */
+    experimentOf: Record<string, string>;
+}
+/**
+ * Resolve which page version each experiment slot shows for this visitor, and
+ * which page keys remain in the linear flow.
+ *
+ * Variant pages are detected structurally by the `@` in their key, so they
+ * collapse out of the linear flow even for a slot with no active experiment.
+ * For each *running* experiment the visitor is bucketed (stable on `seed`); a
+ * *stopped* one serves its `winner`; a *paused* one (or no seed) serves the slot.
+ */
+declare function resolveExperiments(pages: {
+    key: string;
+}[], experiments: RuntimeExperiment[], seed: string | null): ExperimentResolution;
+/** One referential problem with an experiment record. */
+interface ExperimentIssue {
+    /** The offending experiment id (`'*'` for a cross-experiment issue). */
+    experimentId: string;
+    code: 'slot_missing' | 'slot_is_variant' | 'slot_conflict' | 'duplicate_id' | 'variant_page_missing' | 'variant_slot_mismatch' | 'no_control' | 'no_traffic' | 'negative_weight' | 'bad_winner' | 'single_arm' | 'orphan_variant';
+    message: string;
+}
+interface ExperimentValidation {
+    ok: boolean;
+    errors: ExperimentIssue[];
+    warnings: ExperimentIssue[];
+}
 /**
- * Payment hook — reads payment-related variables and provides a purchase action.
+ * Cross-check experiment records against the funnel's pages — the publish-time /
+ * experiment-edit gate that catches the dangling references the runtime can't see
+ * (the experiment wiring lives in the DB; the pages live in the build, so they can
+ * drift). Pure: hand it the runtime experiments + the funnel's page keys (e.g.
+ * `manifest.pages`).
  *
- * Only re-renders when payment/card variables change.
+ * Errors block; warnings inform. `orphan_variant` is a warning, not an error — a
+ * `@variant` file with no running experiment is dead-but-harmless (a paused test, or
+ * one not wired yet).
  */
-declare function usePayment(): PaymentState;
+declare function validateExperiments(experiments: RuntimeExperiment[], pages: {
+    key: string;
+}[]): ExperimentValidation;
 
 /**
- * Read device, browser, and OS metadata.
+ * v2 namespace layer over the flat {@link VariableStore}.
+ *
+ * **The public surface is hooks, not a god object.** Reactive reads use
+ * `useState`-shaped tuple hooks (`const [goal, setGoal] = useResponse('goal')`);
+ * read-only computed values use `useDevice()`/`useLocale()`/`usePage()`/`useUtm()`.
+ * `useFunnel()` returns an **imperative, non-subscribing** handle for use in
+ * handlers/effects only — it is not the documented primary API and carries no
+ * `sdk` branding.
  *
- * These values are set once on mount and don't change, so this hook
- * will rarely (if ever) re-render.
+ * Three writable namespaces (`user`/`responses`/`data`) + the read-only
+ * `context`. Entitlements are **not** here — they're the separate app/IdentitySDK.
  *
- * ```tsx
- * const { device, browser, os } = useDeviceInfo()
- * if (device.isMobile) { ... }
- * ```
+ * All writes route through {@link Namespace.set}, so persistence + identify fire
+ * from one place (the "magic behind set()", doc 07 §Layer 1).
+ */
+/** A typed view over one writable namespace's slice of the store. */
+declare class Namespace<T extends Record<string, VariableValue> = Record<string, VariableValue>> {
+    private readonly store;
+    readonly name: WritableNamespace;
+    /** Side-effect run after every write (persistence, identify). */
+    private readonly onWrite;
+    private readonly dot;
+    constructor(store: VariableStore, name: WritableNamespace, 
+    /** Side-effect run after every write (persistence, identify). */
+    onWrite: (ns: WritableNamespace, values: Partial<T>) => void);
+    /** Fully-qualified store key for a namespace-relative key. */
+    storeKey(key: string): string;
+    /** The store-key prefix this namespace reads/writes (e.g. `user.`). */
+    get prefix(): string;
+    /** Read the whole namespace as a flat object (prefix stripped). */
+    getAll(): T;
+    /** Read one key, or the whole namespace when called with no argument. */
+    get<K extends keyof T & string>(key: K): T[K];
+    get(): T;
+    /** Write one or more keys from a plain object (batched + side-effected). */
+    set(values: Partial<T>): void;
+}
+/**
+ * The imperative funnel handle (`useFunnel()`). Non-reactive — for event
+ * handlers and effects. Reactive render reads go through the hooks instead.
  */
-declare function useDeviceInfo(): DeviceInfo;
+interface Funnel {
+    user: Namespace;
+    responses: Namespace;
+    data: Namespace;
+    /** Read-only computed namespace. `page` reflects the latest navigation. */
+    readonly context: FunnelContext;
+    /** Live page-level experiment records (platform/DB-sourced); the runtime buckets visitors into them. */
+    readonly experiments: RuntimeExperiment[];
+    /** Emit a custom analytics event. */
+    track: Tracker['track'];
+    /** A point-in-time snapshot for predicates (routing/conditions). */
+    snapshot(): FunnelSnapshot;
+}
+interface FunnelProviderProps {
+    /** Mount from a funnel definition (the normal case). */
+    config?: FunnelDefinition;
+    /** Server / session-restored values overriding declared defaults. */
+    sessionValues?: Record<string, VariableValue>;
+    /** The platform tracker; defaults to a silent console tracker (tests/dev). */
+    tracker?: Tracker;
+    /** Computed-context seed (funnel id, test/live mode, server-hydrated utm/session). */
+    context?: Parameters<typeof buildContext>[0];
+    /** Products with their provider-resolved price (`{ amount, currency }`). */
+    products?: ProductInput[];
+    /** Live page-level experiment records, platform/DB-sourced (not authored in funnel code). */
+    experiments?: RuntimeExperiment[];
+    /** The platform checkout driver; defaults to a mock that resolves successfully. */
+    checkout?: CheckoutDriver;
+    /** Message catalogs per locale (`messages/<locale>.json`) for translation. */
+    messages?: MessageCatalog;
+    /** Explicit locale override (URL/param/geo); wins over the detected device locale. */
+    locale?: string;
+    /** Auto-mount the toast `<Toaster>` (default true). Pass props to customize, or `false` to opt out. */
+    toaster?: boolean | ToasterProps;
+    /** Advanced / testing: supply a pre-built store instead of a `config`. */
+    store?: VariableStore;
+    children: ReactNode;
+}
+/**
+ * Mounts a funnel: builds the writable {@link VariableStore} + the read-only
+ * {@link FunnelContext} (once) and provides the runtime to the tree via hooks.
+ */
+declare function FunnelProvider({ config, sessionValues, tracker, context: contextOpts, products, experiments, checkout, messages, locale: localeOverride, toaster, store, children, }: FunnelProviderProps): ReactNode;
+/**
+ * The imperative handle. Does **not** subscribe — use it in event handlers and
+ * effects (`useFunnel().responses.set({...})`). For reactive reads use the hooks.
+ */
+declare function useFunnel(): Funnel;
+/**
+ * `const [goal, setGoal] = useResponse('goal')` — one funnel answer,
+ * `useState`-shaped and per-key reactive. Writing persists + (later) feeds
+ * analytics aggregation.
+ */
+declare const useResponse: (key: string) => [VariableValue, (value: VariableValue) => void];
+/**
+ * `const [height, setHeight] = useUserAttribute('height')` — any field on the
+ * user. The platform routes known fields → typed column, custom → attribute;
+ * the author doesn't specify which. Writing `email` also identifies the visitor.
+ */
+declare const useUserAttribute: (key: string) => [VariableValue, (value: VariableValue) => void];
+/**
+ * `const [score, setScore] = useData('score')` — working/scratch state. Persisted
+ * (survives reload/return) but kept out of `responses` aggregation.
+ */
+declare const useData: (key: string) => [VariableValue, (value: VariableValue) => void];
+/**
+ * The headless field hook — `useField('responses.goal')` — the building block
+ * the styleable components (`<Choice>`) wrap. Takes a namespaced path and
+ * returns `{ value, set }`. Accepts only writable namespaces.
+ */
+declare function useField(path: string): {
+    value: VariableValue;
+    set: (value: VariableValue) => void;
+};
+/** `useDevice()` — viewport, device type, pixel ratio (read-only). */
+declare function useDevice(): FunnelContext['device'];
+/** `useLocale()` — resolved locale/language/region/timezone (read-only). */
+declare function useLocale(): FunnelContext['locale'];
+/** `useUtm()` — the 5 utm params captured on entry (read-only). */
+declare function useUtm(): FunnelContext['utm'];
+/** `useClickIds()` — per-network ad click-ids captured on entry (read-only). */
+declare function useClickIds(): FunnelContext['clickIds'];
+/** `useSystem()` — funnel id, test/live mode, build clock (read-only). */
+declare function useSystem(): FunnelContext['system'];
+/** Read a dotted path out of context, e.g. `useContextValue('device.isMobile')`. */
+declare function useContextValue(path: string): unknown;
 
-interface SafeAreaInsets {
-    top: number;
-    right: number;
-    bottom: number;
-    left: number;
+/** What a page's `load` resolves to — a component, or a module default-exporting one. */
+type PageModule = ComponentType | {
+    default: ComponentType;
+};
+/**
+ * A page wired into the runtime. Provide **either** an eager `Component` (small
+ * funnels, tests) **or** a lazy `load` (code-split: the renderer hands a dynamic
+ * `import()` so a big funnel ships one chunk per page, not the whole funnel).
+ */
+interface RuntimePage {
+    key: string;
+    meta?: PageMeta;
+    /** Eager component. Provide this or `load`. */
+    Component?: ComponentType;
+    /** Lazy loader for a code-split chunk. Provide this or `Component`. */
+    load?: () => Promise<PageModule>;
+}
+interface NavigationState {
+    /** The current page's read-only context (key, index, total, progress). */
+    page: PageContext;
+    /** Advance via the current page's `next` predicate, else the linear next. */
+    next: () => void;
+    /** Go to the previous page in history. */
+    back: () => void;
+    /** Jump to a specific page key. */
+    go: (key: string) => void;
+    /** Warm a page's code-split chunk ahead of navigation (e.g. on link hover). No-op for eager pages. */
+    prefetch: (key: string) => void;
+    /**
+     * The page keys the visitor could go to next, already resolved to the chunk that
+     * would render (experiment variant applied). The **renderer** maps these to chunk
+     * URLs and emits `<link rel="modulepreload">` (the browser-native, non-executing,
+     * SSR-able prefetch — see v0 `HeadlessFunnelRenderer`). The SDK's `load()`-based
+     * `prefetch` is the fallback for mounts without a modulepreload manager.
+     */
+    nextCandidates: string[];
+    canGoBack: boolean;
 }
 /**
- * Returns the current safe-area insets (in px) from `env(safe-area-inset-*)`.
+ * `const variant = useExperiment('welcome-headline')` — the variant key this
+ * visitor is assigned in an experiment (`undefined` if not in one). Page-variant
+ * swapping is automatic; this is for branching *within* a page or custom logging.
+ */
+declare function useExperiment(id: string): string | undefined;
+/**
+ * Renders the funnel: shows the current page and drives navigation. `next()`
+ * resolves the current page's `next` predicate against the live snapshot
+ * (writable namespaces + read-only `context`), falling back to the linear next
+ * page in file order (see {@link nextPage}).
+ *
+ * Auto-emits `funnel.start` on mount and `page.view` on each page change, and
+ * keeps `context.page` in sync so predicates and `usePage()` see the live page.
  *
- * Useful for positioning fixed elements above the Safari home-indicator bar.
+ * Pass a `layout` (a `{ children }` component) for **persistent chrome** — a
+ * header, progress bar, background — rendered *inside* the nav context but
+ * *outside* the page swap, so it mounts once and never remounts on navigation
+ * (and can read `usePage`/`useNavigation`).
  *
- * ```tsx
- * const { bottom } = useSafeArea()
- * <div style={{ position: 'fixed', bottom: 0, paddingBottom: bottom }} />
- * ```
+ * Must live inside `<FunnelProvider>`.
  */
-declare function useSafeArea(): SafeAreaInsets;
+declare function FunnelView({ pages, initialKey, layout, fallback, prefetch: prefetchMode, onNavigate, }: {
+    pages: RuntimePage[];
+    initialKey?: string;
+    layout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /** Shown in the page area while a lazy page's chunk loads (the layout persists around it). */
+    fallback?: ReactNode;
+    /**
+     * `'auto'` (default): the SDK warms next-likely chunks by calling `load()`.
+     * `'off'`: the **renderer** owns prefetch (via `<link rel="modulepreload">` over
+     * `useNavigation().nextCandidates`) — avoids the redundant `load()` execution.
+     */
+    prefetch?: 'auto' | 'off';
+    /**
+     * Fires on every page change (incl. the initial page) with the current page key
+     * + slug. The **renderer** uses it to sync the URL path (`history.replaceState`,
+     * v0-style — funnel back is in-memory, not browser history). Fires for the
+     * *resolved* page, so if an entry `guard` bounced a deep-link to the start, the
+     * URL gets corrected.
+     */
+    onNavigate?: (key: string, slug: string) => void;
+}): ReactNode;
+/** `const { next, back, go, page } = useNavigation()`. */
+declare function useNavigation(): NavigationState;
+/** `usePage()` — the current page's read-only context, reactive to navigation. */
+declare function usePage(): PageContext;
 
-interface KeyboardState {
-    /** Whether the virtual keyboard is currently visible */
-    isOpen: boolean;
-    /** Height of the keyboard in pixels (0 when closed) */
-    height: number;
+/**
+ * The two-tier component model (doc 07 §"magic ≠ black box"): the magic lives in
+ * headless hooks (`useField`, `useNavigation`); these styleable components are
+ * thin, restyle-able wrappers over them. Every `<Choice>` reduces to `useField`
+ * + your own JSX — eject any time. They pass `className`/DOM props straight
+ * through and never dictate a pixel beyond the minimum.
+ */
+interface ChoiceOption {
+    value: string;
+    label?: ReactNode;
+}
+interface ChoiceProps {
+    /** Writable namespaced path to bind, e.g. `responses.goal`. */
+    bind: string;
+    /** The selectable options (a bare string is shorthand for `{value, label}`). */
+    options: (string | ChoiceOption)[];
+    /** Class applied to each option button. */
+    className?: string;
+    /** Class applied to the selected option button (in addition to `className`). */
+    selectedClassName?: string;
+    /** Advance navigation after a choice (handy for single-tap question pages). */
+    advanceOnSelect?: boolean;
+}
+/**
+ * Single-select bound to a writable field. `<Choice bind="responses.goal"
+ * options={["lose", "gain"]} />` — selecting persists + (later) tracks; pass
+ * `advanceOnSelect` to move to the next page on tap.
+ */
+declare function Choice({ bind, options, className, selectedClassName, advanceOnSelect, }: ChoiceProps): ReactNode;
+interface NextProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    children?: ReactNode;
+}
+/** A button that advances the funnel (the current page's `next`, else linear). */
+declare function Next({ children, onClick, ...rest }: NextProps): ReactNode;
+interface BackProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    children?: ReactNode;
 }
+/** A button that returns to the previous page; hidden when there's no history. */
+declare function Back({ children, onClick, ...rest }: BackProps): ReactNode;
+
 /**
- * Detects the virtual keyboard on mobile devices.
+ * Imperative, promise-based modal registry — our trimmed adaptation of
+ * eBay's `@ebay/nice-modal-react` (MIT). The model: a module-level registry +
+ * a reducer-backed store, so any code can `showModal(MyModal)` from anywhere
+ * (no prop-drilling, no rendering the modal where you trigger it) and get back a
+ * **promise** that resolves when the modal calls `resolve()` — perfect for
+ * confirm/upsell/detail flows.
  *
- * Uses the VirtualKeyboard API where available, with a
- * visualViewport fallback for Safari/older browsers.
+ * Every modal is keyed by a **stable id**, which also makes it natural to bind
+ * analytics later (open/close per id, like pages).
  *
- * The visualViewport path follows the approach described at
- * https://martijnhols.nl/blog/how-to-get-document-height-ios-safari-osk
- * to handle iOS Safari's delayed viewport updates on keyboard close.
+ * Pair it with the controlled chrome in {@link ./overlay}: a `defineModal`
+ * component renders a `<Sheet open={m.visible} onClose={m.hide}>`/`<Modal>`.
+ * The runtime ({@link ./namespaces}.FunnelProvider) mounts {@link ModalRoot} for
+ * you, so there's no provider to wire.
  *
- * ```tsx
- * const { isOpen, height } = useKeyboard()
- * <div style={{ position: 'fixed', bottom: isOpen ? height : 0 }} />
- * ```
+ * Trimmed vs upstream: dropped the antd/mui/bootstrap binding adapters and the
+ * standalone `<Provider>` (folded into the funnel runtime).
  */
-declare function useKeyboard(): KeyboardState;
 
+interface ModalState {
+    id: string;
+    args?: Record<string, unknown>;
+    visible?: boolean;
+    delayVisible?: boolean;
+    keepMounted?: boolean;
+}
+/** The handle `useModal()` returns to control one modal. */
+interface ModalHandler<Props = Record<string, unknown>> {
+    id: string;
+    args?: Record<string, unknown>;
+    visible: boolean;
+    keepMounted: boolean;
+    show: (args?: Props) => Promise<unknown>;
+    hide: () => Promise<unknown>;
+    remove: () => void;
+    /** Resolve the promise returned by `show()` (e.g. a confirm result). */
+    resolve: (value?: unknown) => void;
+    /** Reject the promise returned by `show()`. */
+    reject: (value?: unknown) => void;
+    /** Resolve the promise returned by `hide()` (after a close transition). */
+    resolveHide: (value?: unknown) => void;
+}
+/** Register a component as an id-keyed modal so the placeholder can render it. */
+declare function registerModal(id: string, comp: ComponentType<any>, props?: Record<string, unknown>): void;
+declare function unregisterModal(id: string): void;
+/** Show a modal (by component or id). Returns a promise resolved by `resolve()`. */
+declare function showModal<T = unknown>(modal: string | ComponentType<any>, args?: Record<string, unknown>): Promise<T>;
+/** Hide a modal. Returns a promise resolved by `resolveHide()` (post-transition). */
+declare function hideModal<T = unknown>(modal: string | ComponentType<any>): Promise<T>;
+/** Remove a modal from the tree (frees its state; better than just hiding). */
+declare function removeModal(modal: string | ComponentType<any>): void;
+declare function useModal(): ModalHandler;
+declare function useModal(modal: string, args?: Record<string, unknown>): ModalHandler;
+declare function useModal<P extends object>(modal: ComponentType<P>, args?: Partial<P>): ModalHandler<P>;
+interface ModalHocProps {
+    id: string;
+    defaultVisible?: boolean;
+    keepMounted?: boolean;
+}
 /**
- * Read page-level system variables.
+ * Wrap a component into an id-keyed modal. Inside it, `useModal()` (no args)
+ * gives the handle. Render a controlled `<Sheet>`/`<Modal>` with
+ * `open={m.visible} onClose={m.hide}`.
+ */
+declare function defineModal<P extends object>(Comp: ComponentType<P>): ComponentType<P & ModalHocProps>;
+
+/**
+ * Raw, **controlled** overlay chrome — `<Sheet>` (a drawer) and `<Modal>` (a
+ * centered dialog). Headless and styleable (className/portal/dismiss), the same
+ * two-tier contract as `<Choice>`: thin wrappers you restyle or eject.
  *
- * Re-renders when page variables change (e.g. on navigation).
+ * These are the presentation layer. For *imperative*, promise-based modals
+ * triggered from anywhere, wrap one in `defineModal` and `showModal(...)`
+ * (see {@link ./modals}) — that registry drives these controlled primitives.
+ * They're also used directly (no registry) where local state is simpler, e.g.
+ * the checkout `sheet` surface.
  *
- * ```tsx
- * const { currentId, progressPercentage, startedAt } = usePageData()
- * ```
+ * Deliberately minimal: portal to `document.body`, lock body scroll while open,
+ * dismiss on Escape / backdrop. No animation engine, no focus-trap dependency.
  */
-declare function usePageData(): PageData;
 
+type SheetSide = 'bottom' | 'top' | 'left' | 'right';
+interface OverlayCommon {
+    className?: string;
+    backdropClassName?: string;
+    dismissOnBackdrop?: boolean;
+    ariaLabel?: string;
+    children: ReactNode;
+}
+type SheetProps = OverlayCommon & {
+    /** Edge the drawer slides from (default `bottom`). */
+    side?: SheetSide;
+};
 /**
- * Convenience hook that combines all SDK hooks.
- * Useful for simple funnels where you don't want multiple hook imports.
+ * An edge-anchored drawer. Inside a `defineModal` it auto-binds — `<Sheet>…`;
+ * outside one, control it with `open`/`onClose`.
  */
-declare function useFunnel(): FunnelState;
+declare function Sheet(props: SheetProps): ReactNode;
+type ModalProps = OverlayCommon;
+/** A centered dialog. Auto-binds to its `defineModal` — `<Modal>…`. */
+declare function Modal(props: ModalProps): ReactNode;
 
-interface StripePaymentHandle {
-    /** Programmatically submit the payment form */
-    submit: () => Promise<void>;
+/**
+ * The **`window.appfunnel` event bus** — the client-side integration surface
+ * (port of v0 `admin/lib/funnel/utils/appfunnelRuntime.ts`).
+ *
+ * Every taxonomy event the runtime emits is mirrored here, so on-page pixels and
+ * custom scripts integrate by **subscribing** — `window.appfunnel.on('purchase.complete', …)`
+ * — instead of the funnel hand-injecting pixel config per page. The pre-built pixel
+ * loaders (Meta/TikTok/GTM/Clarity) are just subscribers; CAPI stays the server-side
+ * default (this is the *client* sink of the same events). See doc 08 §3.
+ *
+ * Two deliberate properties vs. v0:
+ *  - **Replay history** (`events`): async pixels load *after* `funnel.start`/`page.view`
+ *    fire, so a late subscriber would miss them. The bus keeps a bounded history a
+ *    subscriber can replay (the GTM `dataLayer` trick) — no lost events.
+ *  - **Subscribe + read only.** The window surface exposes `on`/`off`/`events` + read
+ *    getters; it has **no `emit`** (third-party code can't forge events) and **no
+ *    mutating actions** (`setVariable`/navigation) — the funnel can't be driven through
+ *    it. (v0's full-control Custom-JS API is deferred pending the bus-control-scope
+ *    decision; doc 08 §3 + §4.)
+ */
+
+/** Read accessors the bus exposes — wired to the funnel's store + context. */
+interface BusAccessors {
+    getVariable: (key: string) => unknown;
+    getVariables: () => Record<string, unknown>;
+    getCurrentPageId: () => string | null;
+    getCustomerId: () => string | null;
+    getVisitorId: () => string | null;
 }
-interface StripePaymentFormBaseProps {
-    /** Product ID override (default: currently selected product) */
-    productId?: string;
-    /** "checkout" for full payment, "validate-only" to just collect card */
-    mode?: 'checkout' | 'validate-only';
-    /** Additional CSS class */
-    className?: string;
-    /** Stripe Appearance override */
-    appearance?: Appearance;
-}
-interface StripePaymentFormElementsProps extends StripePaymentFormBaseProps {
-    /** "elements" for PaymentElement, "embedded" for Stripe Embedded Checkout */
-    variant?: 'elements';
-    /** Page key to redirect to after successful embedded checkout */
-    successPageKey?: string;
-    /** Called on successful payment */
-    onSuccess?: () => void;
-    /** Called on payment error */
-    onError?: (error: string) => void;
-    /** Called when the Stripe form is ready to accept submissions */
-    onReady?: () => void;
-    /** PaymentElement layout option (default: 'tabs') */
-    layout?: 'tabs' | 'accordion' | 'auto';
-    automaticTax?: never;
-    managedPayments?: never;
-    allowPromotionCodes?: never;
-}
-interface StripePaymentFormEmbeddedProps extends StripePaymentFormBaseProps {
-    /** "embedded" for Stripe Embedded Checkout */
-    variant: 'embedded';
-    /** Page key to redirect to after successful embedded checkout */
-    successPageKey: string;
-    /** Enable Stripe automatic tax calculation */
-    automaticTax?: boolean;
-    /** Enable Stripe managed payments — Stripe controls tax, payment methods, etc. (forces embedded mode) */
-    managedPayments?: boolean;
-    /** Allow promotion codes in checkout */
-    allowPromotionCodes?: boolean;
-    onSuccess?: never;
-    onError?: never;
-    onReady?: never;
-    layout?: never;
-}
-type StripePaymentFormProps = StripePaymentFormElementsProps | StripePaymentFormEmbeddedProps;
-/**
- * Stripe payment component supporting PaymentElement and Embedded Checkout.
- *
- * In dev mode (`globalThis.__APPFUNNEL_DEV__`), renders a demo form that
- * simulates Stripe UI and emulates purchases without real Stripe calls.
- *
- * Use a ref to submit the form from an external button:
- * ```tsx
- * const paymentRef = useRef<StripePaymentHandle>(null)
- *
- * <StripePaymentForm ref={paymentRef} onSuccess={goToNextPage} />
- * <button onClick={() => paymentRef.current?.submit()}>Pay Now</button>
- * ```
- */
-declare const StripePaymentForm: react.ForwardRefExoticComponent<StripePaymentFormProps & react.RefAttributes<StripePaymentHandle>>;
-
-interface PaddleCheckoutProps {
-    /** Product ID to checkout (default: currently selected product) */
-    productId?: string;
-    /** Display mode: overlay opens Paddle in a modal, inline renders embedded */
-    mode?: 'overlay' | 'inline';
-    /** Called on successful checkout */
-    onSuccess?: () => void;
-    /** Called on checkout error */
-    onError?: (error: string) => void;
-    /** Additional CSS class */
-    className?: string;
+interface BusEvent {
+    event: string;
+    data: unknown;
+    /** Epoch ms the event was emitted (for ordering / replay). */
+    ts: number;
+}
+type Listener = (data: unknown) => void;
+/** The public `window.appfunnel` surface — subscribe + read, never emit or mutate. */
+interface AppFunnelBusApi extends BusAccessors {
+    /** Subscribe to an event (or `'*'` for all). Returns an unsubscribe fn. */
+    on(event: string, cb: Listener): () => void;
+    off(event: string, cb: Listener): void;
+    /** Bounded replay history — read past events, then `on()` for future ones. */
+    readonly events: BusEvent[];
+}
+/**
+ * The internal bus: the public {@link AppFunnelBusApi} plus `emit` (SDK-only) and
+ * `now` injection. The SDK holds this; only {@link AppFunnelBusApi} reaches `window`.
+ */
+interface FunnelBus extends AppFunnelBusApi {
+    emit(event: string, data?: unknown): void;
 }
+/** Create a bus over the given read accessors. `now` is injectable for tests. */
+declare function createBus(accessors: BusAccessors, now?: () => number): FunnelBus;
+/**
+ * Wrap a {@link Tracker} so every emitted taxonomy event is mirrored to the bus
+ * (the client sink). `identify()` also surfaces a `user.registered` to the bus, so
+ * pixels see registration. The server sink (the inner tracker → CAPI) is untouched.
+ */
+declare function withBus(tracker: Tracker, bus: FunnelBus): Tracker;
 declare global {
     interface Window {
-        Paddle?: {
-            Setup: (options: Record<string, unknown>) => void;
-            Checkout: {
-                open: (options: Record<string, unknown>) => void;
-            };
-        };
+        appfunnel?: AppFunnelBusApi;
     }
 }
 /**
- * Paddle checkout component.
- * Supports overlay (modal) and inline (embedded) modes.
+ * Attach the bus's public surface to `window.appfunnel` (client-side only).
+ * Returns a detach fn for unmount. No-op under SSR.
  */
-declare function PaddleCheckout({ productId, mode, onSuccess, onError, className, }: PaddleCheckoutProps): react_jsx_runtime.JSX.Element | null;
+declare function attachBus(bus: FunnelBus): () => void;
 
 /**
- * Integration runtime — sets up window.appfunnel event bus and initializes
- * third-party integrations (Meta Pixel, GTM, Clarity, etc.).
+ * The **event catalog** — the single source of truth for *which* events exist and
+ * how each is routed (analytics vs. integrations vs. runtime-only). Pairs with the
+ * typed payloads in {@link ./tracking}.`FunnelEventDataMap`.
  *
- * The integration loaders from the admin codebase subscribe to events via
- * window.appfunnel.on(). The FunnelTracker emits events via _emitEvent().
- * This module bridges the two by setting up the pub/sub layer.
+ * This replaces the duplication the monorepo flags (`shared/events/catalog.ts` is
+ * "documentation, not imported" — the taxonomy is re-declared in
+ * `admin/lib/funnel/tracking.ts`, each `admin/lib/integrations/*` EVENT_MAP, and
+ * `api/src/integrations/constants`). In v2 the **SDK owns the taxonomy** (it emits
+ * it), so the bus, the pixel loaders, and the platform all import *this*.
+ */
+type EventSource = 'frontend' | 'backend';
+interface EventMeta {
+    /** Where the event originates. `backend` = the server emits it (e.g. a settled charge). */
+    sources: EventSource[];
+    /** Persisted to analytics. */
+    tracking: boolean;
+    /** Forwarded to ad/integration pixels (Meta/GTM/TikTok/…). */
+    integrations: boolean;
+    /** Runtime-only JS subscription — not persisted, not sent to integrations. */
+    runtime?: boolean;
+}
+/**
+ * Every event the system knows, with its routing metadata. Keys are the taxonomy
+ * names (a superset of `FunnelEventDataMap`: it also lists the **backend-originated**
+ * monetary events the platform pushes to the client bus for pixel firing).
  */
+declare const EVENT_CATALOG: {
+    readonly 'funnel.start': {
+        readonly sources: ["frontend"];
+        readonly tracking: false;
+        readonly integrations: false;
+        readonly runtime: true;
+    };
+    readonly 'experiment.exposure': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: false;
+    };
+    readonly 'page.view': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'page.exit': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: false;
+    };
+    readonly 'user.registered': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'checkout.start': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'checkout.payment_added': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'checkout.failed': {
+        readonly sources: ["frontend"];
+        readonly tracking: true;
+        readonly integrations: false;
+    };
+    readonly 'purchase.complete': {
+        readonly sources: ["backend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'customer.first_purchase': {
+        readonly sources: ["backend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'subscription.created': {
+        readonly sources: ["backend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+    readonly 'subscription.renewal': {
+        readonly sources: ["backend"];
+        readonly tracking: true;
+        readonly integrations: true;
+    };
+};
+/** A catalog event name. */
+type CatalogEvent = keyof typeof EVENT_CATALOG;
+/** True if the event is persisted to analytics. */
+declare function isTrackableEvent(name: string): boolean;
+/** True if the event is forwarded to ad/integration pixels. */
+declare function isIntegrationEvent(name: string): boolean;
+/** The events that feed integrations — the set a pixel loader subscribes to. */
+declare function integrationEvents(): CatalogEvent[];
 
-/** Integration config map: integrationId -> config object */
-type IntegrationConfigs = Record<string, Record<string, unknown>>;
-type IntegrationLoader = (config: Record<string, unknown>) => void;
 /**
- * Register a custom integration loader.
- * Called by the CLI build or user code to add integrations.
+ * `<Script>` — the **declared third-party embed** primitive (phase-2 §2.3d).
+ *
+ * The controlled escape hatch for runtime widgets/embeds that genuinely need
+ * client code — Intercom, Trustpilot, a calendar embed, an operator pixel. Unlike
+ * arbitrary `<script>` injection, it's **declared** (the funnel author writes
+ * `<Script src=…/>`), **deduped** (injected at most once per id/src, even across
+ * page navigation in the SPA — a chat widget must not reload on every page), and
+ * **CSP-friendly** (accepts a `nonce`).
+ *
+ * CSP enforcement itself is the **renderer's** job: it scans the funnel's declared
+ * `<Script src>`s (build-time) into the `script-src` allowlist and supplies the
+ * `nonce`. This component just injects the tag at the right time.
+ *
+ * For *analytics* pixels, prefer subscribing to the `window.appfunnel` bus
+ * ({@link ../tracking/bus}) — `<Script>` is for non-analytics third-party widgets
+ * (and the pixel loader snippets, which then subscribe to the bus).
  */
-declare function registerIntegration(id: string, loader: IntegrationLoader): void;
+interface ScriptProps {
+    /** The third-party script URL. */
+    src: string;
+    /**
+     * When to inject. `afterInteractive` (default) injects on mount (after hydration);
+     * `lazyOnload` waits for idle/`load` so it never competes with the funnel's own JS.
+     */
+    strategy?: 'afterInteractive' | 'lazyOnload';
+    /** Dedup key (defaults to `src`) — the script injects at most once per id. */
+    id?: string;
+    /** Defaults to `true`. */
+    async?: boolean;
+    defer?: boolean;
+    /** CSP nonce — supplied by the renderer. */
+    nonce?: string;
+    /** Extra attributes (e.g. `data-*`). */
+    attributes?: Record<string, string>;
+    onLoad?: () => void;
+    onError?: () => void;
+}
+/**
+ * Injects a third-party script once. Renders nothing. Persists across navigation
+ * (the tag is never removed on unmount — third-party widgets should stay loaded).
+ */
+declare function Script({ src, strategy, id, async, defer, nonce, attributes, onLoad, onError, }: ScriptProps): null;
+
+/**
+ * The **manifest** — the declarative IR a funnel project compiles to (doc 06).
+ * It's the machine-readable artifact the platform operates on without executing
+ * the funnel: the dashboard draws the flow graph from it, analytics binds to its
+ * **stable ids**, validation runs against it, and the renderer reads it to resolve
+ * routing.
+ *
+ * `compileManifest` evaluates the spine (the funnel config + each page's co-located
+ * `meta`) into that IR. It's pure — no I/O — so it unit-tests trivially. **It runs
+ * server-side**, as the IR step of the publish build over the canonical files in our
+ * storage (R2). The client/CLI never produces the authoritative manifest — R2 is the
+ * source of truth, the server compiles. (A local dev preview may run it for itself,
+ * but that output is never published.)
+ *
+ * Edge model mirrors the runtime ({@link ../flow/spine}.`nextPage`): a page's
+ * `meta.next` routes become **branch** edges (with a serialized condition — a
+ * declarative {@link Condition}, or an opaque marker for a code predicate), and the
+ * implicit file-order fall-through becomes a **linear** edge (unless an
+ * unconditional route already covers it, or the page is a `finish`).
+ *
+ * Experiments are **not** compiled here. A variant page is recognised structurally
+ * by the `@` in its key (`welcome@b`) and tagged `variantOf` + collapsed out of the
+ * linear flow; the experiment *wiring* (labels/weights/status) is operational data
+ * the platform owns and overlays at render time, not part of the funnel build.
+ *
+ * Stable ids: the page **key** is the source anchor, so `id === key` here. The
+ * durable analytics id is the semantic page name (a slot survives a winner being
+ * promoted into it); transient `@variant` pages only ever key analytics by
+ * `(experimentId, variant)` in immutable results — a platform concern.
+ */
+
+interface ManifestPage {
+    id: string;
+    key: string;
+    type: PageType;
+    slug: string;
+    index: number;
+    /**
+     * Set on a variant page (`welcome@b`) to its **slot** (`welcome`) — a structural
+     * marker that this node is an off-flow alternate, not a linear step. The
+     * experiment *wiring* (label/weight/id) is operational data the platform owns,
+     * not the manifest.
+     */
+    variantOf?: string;
+}
+type EdgeCondition = {
+    kind: 'declarative';
+    condition: Condition;
+}
+/** A code predicate — opaque body; `label` may be supplied later by AST parsing. */
+ | {
+    kind: 'predicate';
+    label?: string;
+};
+interface ManifestEdge {
+    from: string;
+    to: string;
+    kind: 'branch' | 'linear';
+    /** Absent = unconditional (a fallback route, or the linear fall-through). */
+    condition?: EdgeCondition;
+}
+interface ManifestValidation {
+    ok: boolean;
+    /** Page ids you can't proceed from (and that aren't a `finish`). */
+    deadEnds: string[];
+    /** Page ids not reachable from the start. */
+    unreachable: string[];
+    /** Routes whose target page key doesn't exist. */
+    badTargets: {
+        from: string;
+        to: string;
+    }[];
+    /** True if the funnel never writes `user.email` (the mandatory identity step). */
+    missingEmailCapture: boolean;
+}
+interface FunnelManifest {
+    id: string;
+    pages: ManifestPage[];
+    flow: {
+        start: string | null;
+        nodes: string[];
+        edges: ManifestEdge[];
+    };
+    products: string[];
+    locales?: FunnelLocales;
+    validation: ManifestValidation;
+}
+interface CompileInput {
+    funnel: FunnelDefinition;
+    /** Pages in file order (the default flow); `meta` holds type/slug/next. */
+    pages: {
+        key: string;
+        meta?: PageMeta;
+    }[];
+}
+/** Compile a funnel's spine into its declarative {@link FunnelManifest} IR. */
+declare function compileManifest(input: CompileInput): FunnelManifest;
 
-export { AppFunnelConfig, type DateFormat, DeviceInfo, FunnelState, type IntegrationConfigs, type KeyboardState, LocaleState, NavigationState, PaddleCheckout, type PaddleCheckoutProps, PageData, PageDefinition, PaymentState, ProductsState, type SafeAreaInsets, StripePaymentForm, type StripePaymentFormProps, type StripePaymentHandle, TrackingState, TranslationState, UserState, VariableValue, defineConfig, definePage, registerIntegration, useData, useDateOfBirth, useDeviceInfo, useFunnel, useKeyboard, useLocale, useNavigation, usePageData, usePayment, useProducts, useQueryParam, useQueryParams, useResponse, useResponses, useSafeArea, useTracking, useTranslation, useUser, useUserProperty, useVariable, useVariables };
+export { type Acquisition, type AppFunnelBusApi, Back, type BackProps, type BrowserContext, type BusAccessors, type BusEvent, type CatalogEvent, Checkout, type CheckoutCallbacks, type CheckoutDriver, type CheckoutError, type CheckoutErrorCategory, type CheckoutHandle, type CheckoutIntent, type CheckoutProps, type CheckoutProvider, type CheckoutRequest, type CheckoutResult, type CheckoutStatus, type CheckoutSurface, Choice, type ChoiceOption, type ChoiceProps, type ClickIdContext, type CompileInput, type Condition, type ConditionOp, type DeviceContext, type Direction, EVENT_CATALOG, type EdgeCondition, type EventMeta, type EventSource, type ExperimentIssue, type ExperimentResolution, type ExperimentValidation, type ExperimentVariant, type FlowPage, type Formatters, type Funnel, type FunnelBus, type FunnelContext, type FunnelDefinition, type FunnelEventDataMap, type FunnelLocales, type FunnelManifest, FunnelProvider, type FunnelProviderProps, type FunnelSnapshot, FunnelToaster, FunnelView, type Gate, INLINE_SURFACES, type IdentityContext, type Interval, type KnownFunnelEvent, type LocaleContext, type ManifestEdge, type ManifestPage, type ManifestValidation, type MessageCatalog, type MockDriverOptions, Modal, type ModalHandler, type ModalHocProps, type ModalProps, type ModalState, type Money, Namespace, type NavigationState, Next, type NextProps, type OffSessionReliability, type OsContext, PROVIDER_PROFILES, type PageContext, type PageMeta, type PageModule, type PageType, type PluralCategory, type Predicate, type Product, type ProductInput, type ProviderProfile, type ResolvedProduct, type Route, type RuntimeExperiment, type RuntimePage, Script, type ScriptProps, type SessionContext, Sheet, type SheetProps, type SheetSide, type SurfaceCapability, type SystemContext, type TFunction, type Tracker, type Translation, Upsell, type UpsellKind, type UpsellProps, type UseCheckoutOptions, type UtmContext, type ValidationResult, VariableStore, assignVariant, attachBus, bucketingSeed, buildAcquisition, buildCatalog, checkoutError, compileManifest, createBus, createConsoleTracker, createFunnelStore, createMockDriver, defineFunnel, defineModal, definePage, entryGuard, evaluateCondition, evaluateGate, expectedPathLength, fnv1a, formatProduct, hashToUnit, hideModal, integrationEvents, isInlineSurface, isIntegrationEvent, isMerchantOfRecord, isOrchestrator, isRtl, isTrackableEvent, isVariantKey, newEventId, nextPage, outgoingKeys, pageMeta, parseSlotKey, pickByWeight, registerModal, removeModal, resolveExperiments, resolveLocale, resolveProduct, resolveRoute, showModal, surfacesFor, unregisterModal, useCheckout, useClickIds, useContextValue, useData, useDevice, useExperiment, useField, useFunnel, useLocale, useModal, useNavigation, usePage, useProduct, useProducts, useResponse, useSystem, useTracker, useTranslation, useUserAttribute, useUtm, validateCheckout, validateExperiments, validateUpsell, withBus };