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

package/dist/index.d.ts

@@ -1,14 +1,12 @@
+import * as react from 'react';
 import { ReactNode, ComponentType, ButtonHTMLAttributes } from 'react';
+import { V as VariableValue, a as VariableConfig, A as Acquisition, P as Product, D as Direction, F as FunnelContext, R as RuntimeExperiment, b as FunnelSnapshot, c as FunnelDefinition, d as buildContext, e as ProductInput, f as PageMeta, g as PageContext } from './manifest-DQThneiG.js';
+export { B as BrowserContext, h as BuildContextOptions, C as ClickIdContext, i as CompileInput, j as Condition, k as ConditionOp, l as DeviceContext, E as EdgeCondition, m as ExperimentIssue, n as ExperimentResolution, o as ExperimentValidation, p as ExperimentVariant, q as FlowPage, r as FunnelLocales, s as FunnelManifest, G as Gate, I as IdentityContext, t as Interval, L as LocaleContext, M as ManifestEdge, u as ManifestPage, v as ManifestValidation, w as Money, O as OsContext, x as PageType, y as Predicate, z as ResolvedProduct, H as Route, S as SessionContext, J as SystemContext, U as UtmContext, K as assignVariant, N as bucketingSeed, Q as buildAcquisition, T as buildCatalog, W as compileManifest, X as currencyExponent, Y as defineFunnel, Z as definePage, _ as entryGuard, $ as evaluateCondition, a0 as evaluateGate, a1 as expectedPathLength, a2 as fnv1a, a3 as formatMoney, a4 as formatProduct, a5 as hashToUnit, a6 as isRtl, a7 as isVariantKey, a8 as nextPage, a9 as outgoingKeys, aa as pageMeta, ab as parseSlotKey, ac as pickByWeight, ad as resolveExperiments, ae as resolveLocale, af as resolveProduct, ag as resolveRoute, ah as validateExperiments } from './manifest-DQThneiG.js';
+import { a as CheckoutDriver, C as CheckoutDriverContext } from './checkout-DiQvRT5q.js';
+export { b as Checkout, c as CheckoutCallbacks, d as CheckoutHandle, e as CheckoutProps, f as CheckoutRequest, g as CheckoutResult, h as CheckoutResume, i as CheckoutStatus, F as FailureModalProps, j as FailureRoute, M as MockDriverOptions, O as OnFailedMap, U as Upsell, k as UpsellProps, l as UseCheckoutOptions, m as createMockDriver, n as driverWithEmail, u as useCheckout } from './checkout-DiQvRT5q.js';
 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;
-}
+export { C as CheckoutError, a as CheckoutErrorCategory, b as CheckoutIntent, c as CheckoutProvider, d as CheckoutSurface, I as INLINE_SURFACES, O as OffSessionReliability, P as PROVIDER_PROFILES, e as ProviderProfile, S as SurfaceCapability, U as UpsellKind, V as ValidationResult, f as checkoutError, i as isInlineSurface, g as isMerchantOfRecord, h as isOrchestrator, s as surfacesFor, v as validateCheckout, j as validateUpsell } from './capabilities-7_hy5f5G.js';
 
 declare class VariableStore {
     private state;
@@ -70,198 +68,6 @@ interface FunnelStoreConfig {
  */
 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.
- *
- * 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.
- *
- * 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.
- */
-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;
-
 /**
  * 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
@@ -306,6 +112,7 @@ interface FunnelEventDataMap {
         productId?: string;
         priceId?: string;
         productName?: string;
+        surface?: string;
     };
     'checkout.payment_added': Record<string, never>;
     'checkout.failed': {
@@ -323,6 +130,7 @@ interface FunnelEventDataMap {
     'experiment.exposure': {
         experimentId: string;
         variant: string;
+        version?: number;
     };
 }
 declare function newEventId(): string;
@@ -378,491 +186,17 @@ declare function useTracker(): {
  * 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.
+ *
+ * The math itself (resolve/format/exponents) is pure and lives in {@link ./money}
+ * so the server/tooling entry can use it without React — this module re-exports
+ * it and adds the React wiring (provider + hooks).
  */
 
-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;
-}
-/**
- * The product with its amounts resolved (currency + period math), **before**
- * locale formatting — what the catalog stores. {@link useProduct} formats it.
- */
-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[];
 
-/**
- * v2 commerce primitives — the two intents from phase-3, made trivial.
- *
- *  - `<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.
- *
- * 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}).
- *
- * Which product is charged is the author's bound variable, captured at render
- * (inline surfaces) or at `open()` time (trigger surfaces).
- */
-
-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;
-/**
- * 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.
- */
-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>>;
-}
-/**
- * Provider capabilities (researched 2026-06-23 against provider docs + Funnelfox).
- *
- * 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}.
- *
- * 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.
- */
-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;
-
-/**
- * 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.
- *
- * 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.
- */
-/**
- * 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").
- */
-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;
-
 /**
  * v2 localization — translated **text** (prices already localize via `Intl` in
  * {@link ./catalog}). Per doc 05: locales live in the funnel source — supported
@@ -881,16 +215,6 @@ declare function defineFunnel(def: FunnelDefinition): FunnelDefinition;
 /** 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;
-/**
- * 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;
@@ -914,6 +238,9 @@ interface Translation {
     /** The funnel's supported locales. */
     locales: string[];
 }
+/** The active (resolved) funnel locale, or `'en'` if no provider — for display
+ *  formatting (e.g. {@link ./catalog} prices) without building the full handle. */
+declare function useActiveLocale(): string;
 /**
  * `const { t, fmt, locale, dir } = useTranslation()` — translated text +
  * locale-aware `Intl` formatters for the active funnel locale.
@@ -921,161 +248,22 @@ interface Translation {
 declare function useTranslation(): Translation;
 
 /**
- * Toast — a thin convenience re-export of {@link https://sonner.emilkowal.ski | sonner}.
+ * Toast — a thin convenience over {@link https://sonner.emilkowal.ski | sonner}.
  *
  * 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.
  *
- * 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.
+ * **Dependency policy:** sonner is a direct dependency, imported statically (it's a small
+ * lib that ships with every funnel — no lazy chunk, no forwarding proxy). `toaster={false}`
+ * still renders no toaster markup; a funnel that never toasts just never calls `toast`.
  */
 
-/** Sonner's `<Toaster>` with funnel defaults (top-center); pass any `ToasterProps` to override. */
-declare function FunnelToaster(props?: ToasterProps): ReactNode;
-
 /**
- * **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.
- *
- * 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.
- */
-
-/**
- * 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 fnv1a(input: string): number;
-/** Map a seed string to a stable float in `[0, 1)`. */
-declare function hashToUnit(seed: string): number;
-/**
- * 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 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.
+ * Sonner's `<Toaster>` with funnel defaults (top-center); pass any `ToasterProps` to override.
+ * SSR-safe — sonner renders an empty container server-side and hydrates cleanly on the client.
  */
-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[];
-}
-/**
- * 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`).
- *
- * 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 validateExperiments(experiments: RuntimeExperiment[], pages: {
-    key: string;
-}[]): ExperimentValidation;
+declare function FunnelToaster(props?: ToasterProps): ReactNode;
 
 /**
  * v2 namespace layer over the flat {@link VariableStore}.
@@ -1243,6 +431,14 @@ interface NavigationState {
      */
     nextCandidates: string[];
     canGoBack: boolean;
+    /**
+     * True while a navigation's target page chunk is still resolving (a cold,
+     * un-prefetched lazy chunk). The current page stays on screen during this window
+     * (no Suspense-fallback flicker); read this to show a subtle "working" affordance
+     * so a tapped button doesn't feel dead. Usually false/instant when the next chunk
+     * was prefetched.
+     */
+    isNavigating: boolean;
 }
 /**
  * `const variant = useExperiment('welcome-headline')` — the variant key this
@@ -1294,6 +490,108 @@ declare function useNavigation(): NavigationState;
 /** `usePage()` — the current page's read-only context, reactive to navigation. */
 declare function usePage(): PageContext;
 
+/**
+ * Funnel asset map: logical name (e.g. `logo.svg`) → content-addressed CDN URL,
+ * injected by the renderer. Assets live in a SHARED content-addressed store
+ * (`appfunnel/assets/<hash>`), so identical content is stored once across all
+ * builds and funnels while staying immutable. Both SSR and client read the same
+ * injected map → URLs match. Defaults to `{}` (no provider needed in tests).
+ */
+declare const AssetsContext: react.Context<Record<string, string>>;
+/** Provides the funnel's asset map (mounted for you by {@link createFunnelTree}). */
+declare function AssetsProvider({ assets, children, }: {
+    assets?: Record<string, string>;
+    children: ReactNode;
+}): ReactNode;
+/** The whole asset map (logical name → CDN URL). `{}` outside a provider. */
+declare function useAssets(): Record<string, string>;
+/** `useAsset('logo.svg')` — one asset's CDN URL, or `undefined` if not injected. */
+declare function useAsset(name: string): string | undefined;
+/** What the renderer injects when mounting a funnel build (SSR and hydration). */
+interface MountOpts {
+    /** Platform-resolved product prices (one currency per visitor). */
+    products?: ProductInput[];
+    /** Explicit locale override (URL/param/geo); wins over the detected device locale. */
+    locale?: string;
+    mode?: 'test' | 'live';
+    /** Deep-link / reload entry page (honored only if its entry guard passes). */
+    initialKey?: string;
+    /** Asset map: logical name → content-addressed CDN URL. */
+    assets?: Record<string, string>;
+    /** The SIGNED anonymous visitor id (bare id, verified server-side; phase-1 §1.2) — the
+     *  renderer mints/reads the `af_vid` cookie and injects the value here. Feeds
+     *  `context.identity.visitorId` (experiment bucketing fallback seed, session continuity). */
+    visitorId?: string | null;
+    /** Known customer id (identified visitor) — the preferred bucketing seed. */
+    customerId?: string | null;
+    /** Platform tracking config (phase-1 §1.4). Present → `createFunnelTree` wires the real
+     *  platform tracker (events POST to the shared ingestion endpoint). Absent (preview, tests,
+     *  bare mounts) → the console tracker. Serializable on purpose — it crosses the sealed-build
+     *  boundary as data. */
+    tracking?: {
+        apiBase: string;
+        campaignId: string;
+        /** WebFunnel DB id (NOT the funnel.ts config id). */
+        funnelId: string;
+        /** FUNNEL-split assignment (phase-4) — the tracker emits its exposure event. */
+        experiment?: {
+            id: string;
+            variant: string;
+            version?: number;
+        };
+    };
+    /** Server-hydrated namespace snapshot (phase-1 §1.1): flat namespaced keys
+     *  (`user.email`, `responses.goal`, …) from the visitor's latest session — the renderer
+     *  resolves it by visitorId so a returning visitor resumes with their answers. */
+    sessionValues?: Record<string, string | number | boolean | null | string[]>;
+    /** RUNNING page-experiment records (phase-4): platform-owned wiring over the bundle's
+     *  `@variant` pages, injected at render time — no rebuild to start/stop/reweight. */
+    experiments?: RuntimeExperiment[];
+    /** The server-resolved session id backing `sessionValues` — seeds the tracker (fallback)
+     *  and `context.session.id`. */
+    sessionId?: string | null;
+}
+/**
+ * The shape a funnel build's `mount.tsx` module must export — the named,
+ * versioned contract between a build and the renderer/editor:
+ * `import type { MountModule } from '@appfunnel-dev/sdk'`.
+ */
+type MountModule = {
+    pages: RuntimePage[];
+    tree: (opts: MountOpts) => ReactNode;
+};
+interface CreateFunnelTreeInput {
+    /** The funnel's spine (`defineFunnel(...)`). */
+    config: FunnelDefinition;
+    /** Code-split pages in file order (the same array `mount.tsx` exports). */
+    pages: RuntimePage[];
+    /** Persistent chrome wrapped around the page area (mounted once). */
+    layout?: ComponentType<{
+        children: ReactNode;
+    }>;
+    /**
+     * The platform checkout driver factory — `mount.tsx` imports it from a driver
+     * subpath entry (`import { stripeCheckoutDriver } from '@appfunnel-dev/sdk/driver-stripe'`)
+     * and passes it here, so the provider choice stays in the SDK-owned authoring
+     * contract while the ctx (apiBase/campaign/funnel/mode/identity) stays
+     * renderer-injected. Called once per `tree()` mount, only when tracking config
+     * is present — without it there is no API to charge against (preview, tests,
+     * bare mounts) and the mock driver fallback stays in place. Test mode still
+     * constructs the real driver: the wire contract carries `mode`, and the server
+     * resolves the provider's TEST store from it (that's the quarantine, not the client).
+     */
+    checkoutDriver?: (ctx: CheckoutDriverContext) => CheckoutDriver;
+}
+/**
+ * Build a funnel's `tree(opts)` — the standard provider stack over your pages.
+ *
+ * ```tsx
+ * export const pages: RuntimePage[] = [ ... ]
+ * export const tree = createFunnelTree({ config, pages, layout: Layout })
+ * ```
+ */
+declare function createFunnelTree({ config, pages, layout, checkoutDriver, }: CreateFunnelTreeInput): (opts: MountOpts) => ReactNode;
+
 /**
  * The two-tier component model (doc 07 §"magic ≠ black box"): the magic lives in
  * headless hooks (`useField`, `useNavigation`); these styleable components are
@@ -1606,6 +904,56 @@ declare function isIntegrationEvent(name: string): boolean;
 /** The events that feed integrations — the set a pixel loader subscribes to. */
 declare function integrationEvents(): CatalogEvent[];
 
+/**
+ * The REAL platform tracker (phase-1 §1.4 / BREAKING-CHANGES B-1) — POSTs the taxonomy to
+ * `POST {apiBase}/campaign/{campaignId}/event`, the SAME ingestion endpoint v1 funnels use, so
+ * v2 sessions/customers/events land in the shared analytics graph with zero schema fork.
+ *
+ * Built INSIDE the sealed bundle from serializable config (`MountOpts.tracking`) — the renderer
+ * can only pass data across the build boundary, never live objects. Wired automatically by
+ * `createFunnelTree` when tracking config is present.
+ *
+ * Behavior:
+ *  - SSR-safe: on the server (or with no config) this is never constructed — `createFunnelTree`
+ *    only wires it client-side; the export also guards `window` for direct users.
+ *  - mode:'test' → console tracker (previews/QA never pollute shared analytics; the real
+ *    test-mode quarantine is phase-3 §3.1c).
+ *  - The FIRST event establishes the session: sends are SERIALIZED until the server returns a
+ *    `sessionId` (avoids N parallel first-events racing session creation), then fire-and-forget.
+ *    The sessionId is kept in sessionStorage (per-tab reload continuity) — durable cross-visit
+ *    identity is the `visitorId`'s job, not the session's.
+ *  - `visitorId` (bare id, SSR-injected from the af_vid cookie) rides on every event — the
+ *    ingestion side uses it for durable session lookup + anonymous-Customer continuity.
+ *  - Acquisition (utm + click-ids + fbp/fbc + referrer) is folded into the FIRST event's
+ *    `userData.query` bag — exactly where the v1 ingestion's `extractUtmParams`/attribution
+ *    upgrade logic already looks. Pushed once; never re-sent.
+ *  - Failures are swallowed (console.warn) — tracking must never break a funnel.
+ */
+
+interface PlatformTrackingConfig {
+    /** Public API origin, e.g. `https://api.appfunnel.net` (no trailing slash). */
+    apiBase: string;
+    /** Campaign DB id (the ingestion route key). */
+    campaignId: string;
+    /** WebFunnel DB id (NOT the funnel.ts config id). */
+    funnelId: string;
+    /** Verified bare visitor id (phase-1 §1.2), SSR-injected. */
+    visitorId?: string | null;
+    /** Server-resolved session id (renderer looked it up by visitorId for hydration) — a fallback
+     *  seed; a per-tab sessionStorage id wins over it (v1 tab semantics). */
+    sessionId?: string | null;
+    /** FUNNEL-split experiment assignment (phase-4): the renderer picked this funnel for the
+     *  visitor — the tracker emits the experiment.exposure (page-level exposures come from the
+     *  flow runtime instead). Deduped per (session, experiment) in analytics. */
+    experiment?: {
+        id: string;
+        variant: string;
+        version?: number;
+    };
+    mode?: 'test' | 'live';
+}
+declare function createPlatformTracker(cfg: PlatformTrackingConfig): Tracker;
+
 /**
  * `<Script>` — the **declared third-party embed** primitive (phase-2 §2.3d).
  *
@@ -1650,102 +998,4 @@ interface ScriptProps {
  */
 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 { 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 };
+export { Acquisition, type AppFunnelBusApi, AssetsContext, AssetsProvider, Back, type BackProps, type BusAccessors, type BusEvent, type CatalogEvent, CheckoutDriver, CheckoutDriverContext, Choice, type ChoiceOption, type ChoiceProps, type CreateFunnelTreeInput, Direction, EVENT_CATALOG, type EventMeta, type EventSource, type Formatters, type Funnel, type FunnelBus, FunnelContext, FunnelDefinition, type FunnelEventDataMap, FunnelProvider, type FunnelProviderProps, FunnelSnapshot, FunnelToaster, FunnelView, type KnownFunnelEvent, type MessageCatalog, Modal, type ModalHandler, type ModalHocProps, type ModalProps, type ModalState, type MountModule, type MountOpts, Namespace, type NavigationState, Next, type NextProps, PageContext, PageMeta, type PageModule, type PlatformTrackingConfig, type PluralCategory, Product, ProductInput, RuntimeExperiment, type RuntimePage, Script, type ScriptProps, Sheet, type SheetProps, type SheetSide, type TFunction, type Tracker, type Translation, VariableStore, attachBus, buildContext, createBus, createConsoleTracker, createFunnelStore, createFunnelTree, createPlatformTracker, defineModal, hideModal, integrationEvents, isIntegrationEvent, isTrackableEvent, newEventId, registerModal, removeModal, showModal, unregisterModal, useActiveLocale, useAsset, useAssets, useClickIds, useContextValue, useData, useDevice, useExperiment, useField, useFunnel, useLocale, useModal, useNavigation, usePage, useProduct, useProducts, useResponse, useSystem, useTracker, useTranslation, useUserAttribute, useUtm, withBus };