@appfunnel-dev/sdk 2.0.0-canary.1 → 2.0.0-canary.3

package/dist/manifest-Cr2y1op6.d.cts

@@ -0,0 +1,814 @@
+import { ComponentType } from 'react';
+
+type VariableType = 'string' | 'number' | 'boolean' | 'stringArray';
+type VariableValue = string | number | boolean | string[] | null | undefined;
+interface VariableConfig {
+    type: VariableType;
+    default?: VariableValue;
+    persist?: boolean;
+}
+
+/**
+ * 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;
+
+/**
+ * Pure catalog math — no React, no I/O. Split out of {@link ./catalog} so the
+ * server/tooling entry (`@appfunnel-dev/sdk/manifest`) can compile/resolve
+ * products without pulling react-dom or any component code into its graph.
+ * {@link ./catalog} re-exports everything here and adds the React wiring.
+ */
+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;
+    /** The catalog product KEY this input charges (the slot's assignment). Defaults to `id` (legacy/identity slots). */
+    catalogKey?: 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. `useProduct` formats it.
+ */
+interface ResolvedProduct {
+    id: string;
+    /** The catalog product KEY charged (the CHARGE identity; `id` is the SLOT/display identity). */
+    catalogKey: 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;
+    /** The catalog product KEY charged (the CHARGE identity; `id` is the SLOT/display identity). */
+    catalogKey: 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).
+ * Per-period amounts are **integer minor units** (each derived from the exact
+ * daily rate, then rounded — never round-then-multiply, so error doesn't compound).
+ */
+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>;
+/**
+ * The minor-unit exponent for a currency (`USD`→2, `JPY`→0, `KWD`/`BHD`→3),
+ * derived from `Intl.NumberFormat(...).resolvedOptions().maximumFractionDigits`
+ * with a fallback of 2 for unknown/invalid codes.
+ */
+declare function currencyExponent(currency: string): number;
+/** Format minor units of `currency` in `locale` (exponent-aware: 7900 JPY = ¥7,900). */
+declare function formatMoney(minor: number, currency: string, locale: string): Money;
+/** Format a {@link ResolvedProduct} into a display {@link Product} in `locale`. */
+declare function formatProduct(r: ResolvedProduct, locale: string): Product;
+
+/**
+ * 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;
+}
+/**
+ * A page as declared in `funnel.ts` — the key + its metadata, flattened. This is the
+ * AUTHORED shape (funnel.ts owns the page list, order, and routing); the build generates
+ * the code-split `mount.tsx` from it. Routing (`next`) must stay DECLARATIVE (Route[] with
+ * `{ to, when }` conditions, no predicate functions) so the web builder UI can edit it.
+ */
+interface FunnelPage extends PageMeta {
+    key: string;
+}
+/**
+ * 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;
+    /**
+     * The funnel's pages — order, type, and declarative routing — the source of truth the
+     * web builder edits and the build generates `mount.tsx` from. Each `key` maps to a
+     * `pages/<key>.tsx` component. Omit `pages` on hand-written funnels that still ship their
+     * own `mount.tsx` (back-compat); new/generated funnels declare them here.
+     */
+    pages?: FunnelPage[];
+    /** Which checkout provider the paywall/checkout uses. The build wires the driver. */
+    checkout?: 'stripe' | 'paddle';
+    /** `responses.*` runtime variables (default values). */
+    responses?: Record<string, VariableConfig>;
+    /** `data.*` working/scratch variables (default values). */
+    data?: Record<string, VariableConfig>;
+    /**
+     * The catalog products this funnel sells, as SLOTS: a local, stable key each PAGE
+     * references (`useProduct('primary')`, `<Checkout product="primary">`) → the catalog product
+     * KEY it's assigned to. Swap the assignment to change the offer WITHOUT touching page code;
+     * `null` = a declared-but-unassigned slot. A bare `string[]` is legacy sugar for IDENTITY
+     * slots (`['pro'] ≡ { pro: 'pro' }`) — every existing funnel keeps working. Prices resolve
+     * from the project catalog per environment (Live/Test) at render.
+     */
+    products?: string[] | Record<string, string | null>;
+    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;
+/** A funnel product SLOT: the local key pages reference → the assigned catalog product key (null = unassigned). */
+interface ProductSlot {
+    slot: string;
+    catalogKey: string | null;
+}
+/**
+ * Normalize `FunnelDefinition.products` to a slot list. A legacy `string[]` becomes IDENTITY
+ * slots (`['pro'] → [{ slot:'pro', catalogKey:'pro' }]`); a `{ slot: key|null }` map becomes its
+ * entries (insertion order preserved, so `useProducts()` is deterministic).
+ */
+declare function normalizeProducts(products: FunnelDefinition['products']): ProductSlot[];
+/** The unique, ASSIGNED catalog keys a funnel charges — for the promote gate + catalog reverse-lookup. */
+declare function funnelCatalogKeys(products: FunnelDefinition['products']): string[];
+
+/**
+ * Pure locale resolution — no React. Split out of {@link ./translation} so the
+ * server/tooling entry (`@appfunnel-dev/sdk/manifest`) can resolve a visitor's
+ * locale without pulling component code. {@link ./translation} re-exports it.
+ */
+
+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;
+
+/**
+ * **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 signed `visitorId`, else the known `customerId`.
+ * Never the session id or fingerprint (landmine #4). `null` when neither is known
+ * — the caller then serves control instead of bucketing on nothing.
+ *
+ * visitorId-FIRST (not customerId-first) is deliberate: the customerId injected for an
+ * anonymous visitor is minted server-side AFTER the first tracked event, so it is absent on
+ * visit 1 and present on visit 2 — seeding on it would flip a returning visitor's arm and
+ * count them in two arms of the same version. The signed `af_vid` cookie is the durable
+ * identity that's stable from the first pageload, so it seeds; customerId is only the fallback
+ * for cookieless SDK embeds. This matches the server-side FUNNEL split, which already seeds on
+ * the verified visitorId (resolve.ts). (Cross-device stable bucketing for IDENTIFIED customers
+ * is P3's IdentitySDK job, not this anonymous path.)
+ */
+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;
+    /** Platform record version (immutable-while-running; reweight = new version). Rides on
+     *  exposure events so results key on (experimentId, version, variant). */
+    version?: number;
+}
+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>;
+    /** Experiment id → platform record version (rides on exposure events). */
+    versionOf: Record<string, number>;
+}
+/**
+ * Weights map (label → weight) for one experiment's arms. Exported (via the pure
+ * manifest entry) so the server-side FUNNEL split (renderer resolve) projects arms
+ * the same way before calling {@link assignVariant}, instead of re-inlining it.
+ */
+declare function weightsOf(variants: Record<string, {
+    weight: number;
+}>): Record<string, number>;
+/**
+ * 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[];
+}
+/**
+ * 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;
+
+/**
+ * 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` = none of the hard errors: the original set (dead ends, unreachable
+     * pages, bad targets, missing email capture) AND the structural errors added
+     * later (duplicate keys, orphan variants, no reachable finish). Slug
+     * collisions are a **warning** — reported but not folded into `ok` (slugs are
+     * display/URL sugar; keys are the routing identity).
+     */
+    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;
+    /** Page keys that appear more than once (keys are the stable ids — hard error). */
+    duplicateKeys: string[];
+    /** Flow pages sharing a slug (URL ambiguity — warning, not folded into `ok`). */
+    slugCollisions: {
+        slug: string;
+        pages: string[];
+    }[];
+    /** Variant pages (`x@b`) whose slot (`x`) doesn't exist as a flow page (hard error). */
+    orphanVariants: string[];
+    /**
+     * True when no `finish` page is reachable from the start — e.g. the flow loops
+     * (a cycle with no exit) or every path stalls before a terminal page. Dead ends
+     * catch pages with no outgoing edge; this catches funnels that *never end* even
+     * though every page can proceed. Hard error.
+     */
+    noReachableFinish: boolean;
+    /** Slot names a PAGE references (`useProduct`/`<Checkout product>`) that the funnel doesn't declare — hard error. */
+    unknownProductRefs: string[];
+    /** Declared slots a page references but which have no catalog product assigned (map value `null`) — hard error. */
+    unassignedSlots: string[];
+}
+interface FunnelManifest {
+    id: string;
+    pages: ManifestPage[];
+    flow: {
+        start: string | null;
+        nodes: string[];
+        edges: ManifestEdge[];
+    };
+    /** The unique, ASSIGNED catalog keys the funnel charges (for the promote gate + catalog reverse-lookup). */
+    products: string[];
+    /** Product SLOTS: slot → assigned catalog key|null. `products` above is the unique assigned keys. */
+    productSlots: ProductSlot[];
+    /** Slot names PAGES reference (from the build's scan); validated against `productSlots`. Absent = no scan ran. */
+    productRefs?: 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;
+    }[];
+    /** Slot names the funnel's PAGES reference (from `scanProductRefs`) — cross-checked against the declared slots. */
+    productRefs?: string[];
+}
+/** Compile a funnel's spine into its declarative {@link FunnelManifest} IR. */
+declare function compileManifest(input: CompileInput): FunnelManifest;
+
+export { evaluateCondition as $, type Acquisition as A, type BrowserContext as B, type ClickIdContext as C, type Direction as D, type EdgeCondition as E, type FunnelContext as F, type Gate as G, type Route as H, type IdentityContext as I, type SystemContext as J, assignVariant as K, type LocaleContext as L, type ManifestEdge as M, bucketingSeed as N, type OsContext as O, type Product as P, buildAcquisition as Q, type RuntimeExperiment as R, type SessionContext as S, buildCatalog as T, type UtmContext as U, type VariableValue as V, compileManifest as W, currencyExponent as X, defineFunnel as Y, definePage as Z, entryGuard as _, type VariableConfig as a, evaluateGate as a0, expectedPathLength as a1, fnv1a as a2, formatMoney as a3, formatProduct as a4, hashToUnit as a5, isRtl as a6, isVariantKey as a7, nextPage as a8, outgoingKeys as a9, pageMeta as aa, parseSlotKey as ab, pickByWeight as ac, resolveExperiments as ad, resolveLocale as ae, resolveProduct as af, resolveRoute as ag, validateExperiments as ah, type FunnelPage as ai, type ProductSlot as aj, funnelCatalogKeys as ak, normalizeProducts as al, weightsOf as am, type FunnelSnapshot as b, type FunnelDefinition as c, buildContext as d, type ProductInput as e, type PageMeta as f, type PageContext as g, type BuildContextOptions as h, type CompileInput as i, type Condition as j, type ConditionOp as k, type DeviceContext as l, type ExperimentIssue as m, type ExperimentResolution as n, type ExperimentValidation as o, type ExperimentVariant as p, type FlowPage as q, type FunnelLocales as r, type FunnelManifest as s, type Interval as t, type ManifestPage as u, type ManifestValidation as v, type Money as w, type PageType as x, type Predicate as y, type ResolvedProduct as z };