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

package/dist/manifest-B3Tdab0M.d.ts

@@ -0,0 +1,920 @@
+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 the signed anonymous `visitorId` (stable from the first
+ * pageload, matching the server-side FUNNEL split in resolve.ts); `customerId` is
+ * only the fallback for cookieless SDK embeds. visitorId-FIRST is deliberate — the
+ * anon customerId is minted server-side AFTER the first tracked event, so seeding
+ * on it would flip a returning visitor's arm between visit 1 and 2 (see
+ * {@link ../flow/experiments}.bucketingSeed). It is deliberately **not** the
+ * session id or fingerprint — a returning visitor (e.g. via winback) must keep
+ * their variant across sessions (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 fallback bucketing seed (cookieless embeds). */
+    customerId: string | null;
+    /** Signed anonymous visitor id. The preferred bucketing seed (stable from visit 1). */
+    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
+ * offerings 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 offering (a single provider-resolved price). */
+interface OfferingInput {
+    id: string;
+    /** The catalog charge 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 offering with its amounts resolved (currency + period math), **before**
+ * locale formatting — what the catalog stores. `useOffering` formats it.
+ */
+interface ResolvedOffering {
+    id: string;
+    /** The catalog charge 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 offering the author reads (every amount locale-formatted). */
+interface Offering {
+    id: string;
+    /** The catalog charge 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 an {@link OfferingInput} 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 resolveOffering(input: OfferingInput): ResolvedOffering;
+/** Build the id → {@link ResolvedOffering} catalog. Formatting happens at read time. */
+declare function buildCatalog(inputs: OfferingInput[]): Map<string, ResolvedOffering>;
+/**
+ * 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 ResolvedOffering} into a display {@link Offering} in `locale`. */
+declare function formatOffering(r: ResolvedOffering, locale: string): Offering;
+
+/**
+ * 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.
+     *
+     * OPTIONAL per-variant routing: a `@variant` page (`paywall@b`) MAY carry its own
+     * `next`. When that variant is the one served for its slot, its `next` governs
+     * routing for that visitor; absent, the variant inherits the slot's routing (the
+     * default — a pure superset, no behavior change for existing funnels). Assignment,
+     * exposure, and progress still anchor on the slot; only the next-page lookup
+     * consults the served variant's routes. See {@link FunnelPage}.
+     */
+    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;
+    /**
+     * BUILD-TIME PRERENDER OPT-OUT (SSR-isolation Option B, FIX 2). Set `dynamic: true` (alias
+     * `prerender: false`) on a page whose **structure** (which sections exist — not just their text
+     * values) depends on the visitor's `sessionValues`. Such a page can't be prerendered flash-free:
+     * the default-state markup would structurally differ from the value-applied render and reflow
+     * after hydration. Opting out makes the build SKIP prerendering it, so the renderer serves it via
+     * live SSR (the same fallback branch a build with no prerender entry already uses) — correct
+     * first paint, no pop-in. Value-only variation (text/price into a fixed structure) does NOT need
+     * this: deferred defaults make it flash-free. Omit = prerendered (the default).
+     */
+    dynamic?: boolean;
+    /** @see {@link PageMeta.dynamic} — `prerender: false` is the inverse alias (author preference). */
+    prerender?: boolean;
+}
+/**
+ * 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.
+ *
+ * OPTIONAL variant routing (default off): a served variant's OWN routing is authored by
+ * declaring the variant here with its `@` key and a `next`, e.g.
+ * `{ key: 'paywall@b', next: [{ to: 'special-offer' }] }`. A variant declared this way keys
+ * on the `@` marker, so it still collapses out of the linear flow (it is NOT a linear step);
+ * its `next` is consulted only when that variant is the one served for its slot. Omit the
+ * declaration (leave the variant an undeclared `pages/<slot>@<v>.tsx` file) to inherit the
+ * slot's routing — the existing behavior, unchanged. The slot's control keeps owning
+ * assignment/exposure/progress; only the next-page lookup for a branched variant differs.
+ */
+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;
+    /**
+     * When `true`, a visitor with no explicit language in the URL (no `/​<locale>/` path prefix and no
+     * `?language=`) is served the best match for their **browser** `Accept-Language` among `supported`
+     * (base-matched, so `en-GB` → `en`); no match falls back to `default`. When `false`/absent (the
+     * default), an unspecified visitor always gets `default` — the URL is the only way to switch.
+     */
+    autoDetectLanguage?: boolean;
+}
+/**
+ * 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 offerings this funnel sells, as SLOTS: a local, stable key each PAGE
+     * references (`useOffering('primary')`, `<Checkout offering="primary">`) → the catalog charge
+     * 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.
+     */
+    offerings?: 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 offering SLOT: the local key pages reference → the assigned catalog charge key (null = unassigned). */
+interface OfferingSlot {
+    slot: string;
+    catalogKey: string | null;
+}
+/**
+ * Normalize `FunnelDefinition.offerings` 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 `useOfferings()` is deterministic).
+ */
+declare function normalizeOfferings(offerings: FunnelDefinition['offerings']): OfferingSlot[];
+/** The unique, ASSIGNED catalog keys a funnel charges — for the promote gate + catalog reverse-lookup. */
+declare function funnelCatalogKeys(offerings: FunnelDefinition['offerings']): 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 a running experiment: which page renders, at what weight. */
+interface ExperimentArm {
+    /** 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). Projected from the unified
+ * `Experiment`/`ExperimentArm` graph (a RUNNING PAGE experiment + its arms): the
+ * experiment's `slot` names the base page, and each arm becomes a `variants` entry
+ * `{ page: arm.pageKey, weight: arm.weight }` keyed by `arm.label`. The variant
+ * *pages* are code in the LIVE build; this is the live split over them.
+ *
+ * The serve join only ever hands over RUNNING experiments, and the server's
+ * draft-write + serve guards make every active arm's page GUARANTEED present in the
+ * LIVE build (an experiment owns its arm pages' lifecycle — you end the experiment to
+ * remove a page, you can't drift it away). So there is no lifecycle/winner state and
+ * no "arm page missing" case to resolve here.
+ */
+interface RuntimeExperiment {
+    id: string;
+    /** The page key holding the flow position (the anchor / the control arm's base page). */
+    slot: string;
+    /** label → arm. The control arm's `page` is the `slot`; others are `@variant` siblings. */
+    variants: Record<string, ExperimentArm>;
+    /** 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. Each served
+ * experiment is RUNNING with all its arm pages guaranteed present in the LIVE build
+ * (the server draft-write + serve guards enforce the experiment-owned lifecycle
+ * invariant), so the visitor is bucketed deterministically on `seed` and the assigned
+ * arm's page is swapped in with no presence check. With no `seed` there is nothing
+ * stable to bucket on, so every slot renders its own control page.
+ */
+declare function resolveExperiments(pages: {
+    key: string;
+}[], experiments: RuntimeExperiment[], seed: string | null): ExperimentResolution;
+
+/**
+ * Pure, React-free page scan: find which offering SLOTS a funnel's pages reference — the first
+ * string-literal arg of `useOffering(...)` and the `offering` prop of `<Checkout>` / `<Upsell>`.
+ * Ships via `@appfunnel-dev/sdk/manifest` so the BUILD, the EDITOR, and the AI all run the SAME
+ * check. The result feeds `compileManifest({ offeringRefs })`, which flags references to slots the
+ * funnel doesn't declare (unknown) or hasn't assigned a catalog charge key to (unassigned).
+ *
+ * Non-literal args (`useOffering(selectedId)`, `offering={expr}`) and the `useOfferings()` wildcard are
+ * DYNAMIC — they can't be statically enumerated, so they're reported via `dynamic` and never turned
+ * into a hard error (validation relaxes when a funnel is dynamic). Mirrors the mask-then-read
+ * discipline the funnel.ts code-mods use, so a `useOffering('x')` inside a comment or string literal
+ * can't false-positive.
+ */
+interface OfferingRefScan {
+    /** Concrete slot names referenced by LITERAL args, deduped, in first-seen order. */
+    slots: string[];
+    /** True if any ref is a non-literal arg or a `useOfferings()` wildcard (not statically enumerable). */
+    dynamic: boolean;
+    /**
+     * Checkout-SURFACE usage the pages express — feeds the publish (provider × surface) capability
+     * gate. Absent-field back-compat: a manifest compiled before this existed simply omits it, and
+     * the gate skips (no false blocks). See {@link CheckoutUsageScan}.
+     */
+    checkout: CheckoutUsageScan;
+}
+/**
+ * What the pages ask the checkout to DO, statically — the surfaces they mount and the off-session
+ * upsell kinds they charge. Literal values only; a computed value (`surface={expr}`) sets
+ * {@link dynamic} so the publish gate WARNS instead of hard-failing (it can't enumerate it).
+ */
+interface CheckoutUsageScan {
+    /**
+     * Purchase SURFACES the pages request, deduped in first-seen order. Captures every literal
+     * `<Checkout surface="…">` plus the on-session re-collect surfaces `<Checkout|Upsell fallback="…">`
+     * and `recoverySurface="…"` (a fallback re-collects a card → it IS a purchase surface the provider
+     * must support). Validated with `validateCheckout(provider, surface)`.
+     */
+    surfaces: string[];
+    /**
+     * Off-session upsell KINDS from `<Upsell kind="…">`, deduped. A `<Upsell>` with no `kind` attr
+     * defaults to `'subscription'` (mirrors the runtime default), so an unadorned `<Upsell>` records
+     * `'subscription'`. Validated with `validateUpsell(provider, paywallSurface, kind)`.
+     */
+    upsellKinds: string[];
+    /** True if any surface/kind was a non-literal (computed) value → the gate WARNS, never blocks, on it. */
+    dynamic: boolean;
+}
+declare function scanOfferingRefs(files: Record<string, string>): OfferingRefScan;
+
+/**
+ * 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;
+    /**
+     * The page's effective ENTRY guard, serialized (SSR-isolation Option B, FIX 1): a `declarative`
+     * {@link Condition} the renderer can evaluate SERVER-SIDE against the visitor's session snapshot
+     * to pick the right prerendered variant (target vs bounce) without running tenant code, or an
+     * opaque `predicate` marker (author code — the renderer must fall back to live SSR for that
+     * deep-link). Absent = no entry guard (always restorable). Mirrors {@link entryGuard}.
+     */
+    entryGuard?: EdgeCondition;
+    /**
+     * BUILD-TIME PRERENDER OPT-OUT (SSR-isolation Option B, FIX 2). True when the page's `meta.dynamic`
+     * (or `prerender: false`) opts it out of prerendering because its STRUCTURE depends on
+     * sessionValues. The prerender stage skips it; the renderer serves it via live SSR.
+     */
+    dynamic?: boolean;
+}
+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;
+    /**
+     * True on a **variant-only branch**: an edge whose `from` is a `@variant` key,
+     * emitted when that served variant carries its OWN `meta.next` (optional divergent
+     * routing). Lets consumers (the editor's Flow canvas) tell a variant's private branch
+     * apart from a normal slot edge. Optional/absent on every non-variant edge.
+     */
+    variant?: true;
+}
+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 (`useOffering`/`<Checkout offering>`) that the funnel doesn't declare — hard error. */
+    unknownOfferingRefs: string[];
+    /** Declared slots a page references but which have no catalog charge key 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). */
+    offerings: string[];
+    /** Offering SLOTS: slot → assigned catalog key|null. `offerings` above is the unique assigned keys. */
+    offeringSlots: OfferingSlot[];
+    /** Slot names PAGES reference (from the build's scan); validated against `offeringSlots`. Absent = no scan ran. */
+    offeringRefs?: string[];
+    /**
+     * The funnel's `checkout:` driver bundle from `funnel.ts` (`FunnelDefinition.checkout`), carried so
+     * the publish gate can cross-validate it against the offerings' RESOLVED provider (§7 item 5 — the
+     * redundant field is never checked today). Absent = the funnel declares no `checkout:`.
+     */
+    checkout?: 'stripe' | 'paddle';
+    /**
+     * Checkout-SURFACE usage the pages express (from `scanOfferingRefs(...).checkout`), carried so the
+     * publish (provider × surface) capability gate can run `validateCheckout`/`validateUpsell`. Absent =
+     * no scan ran (old manifest) → the gate skips capability validation (back-compat, no false blocks).
+     */
+    checkoutRefs?: CheckoutUsageScan;
+    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 `scanOfferingRefs`) — cross-checked against the declared slots. */
+    offeringRefs?: string[];
+    /** Checkout-surface usage the pages express (from `scanOfferingRefs(...).checkout`) — carried onto the manifest for the publish capability gate. */
+    checkoutRefs?: CheckoutUsageScan;
+}
+/** Compile a funnel's spine into its declarative {@link FunnelManifest} IR. */
+declare function compileManifest(input: CompileInput): FunnelManifest;
+
+export { expectedPathLength 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, assignVariant as H, type IdentityContext as I, bucketingSeed as J, buildAcquisition as K, type LocaleContext as L, type ManifestEdge as M, buildCatalog as N, type Offering as O, type PageMeta as P, compileManifest as Q, type RuntimeExperiment as R, type SessionContext as S, currencyExponent as T, type UtmContext as U, type VariableValue as V, defineFunnel as W, definePage as X, entryGuard as Y, evaluateCondition as Z, evaluateGate as _, type VariableConfig as a, fnv1a as a0, formatMoney as a1, formatOffering as a2, hashToUnit as a3, isRtl as a4, isVariantKey as a5, nextPage as a6, outgoingKeys as a7, pageMeta as a8, parseSlotKey as a9, pickByWeight as aa, resolveExperiments as ab, resolveLocale as ac, resolveOffering as ad, resolveRoute as ae, type CheckoutUsageScan as af, type FunnelPage as ag, type OfferingRefScan as ah, type OfferingSlot as ai, funnelCatalogKeys as aj, normalizeOfferings as ak, scanOfferingRefs as al, weightsOf as am, type FunnelSnapshot as b, type FunnelDefinition as c, buildContext as d, type OfferingInput as e, type PageContext as f, type BuildContextOptions as g, type CompileInput as h, type Condition as i, type ConditionOp as j, type DeviceContext as k, type ExperimentArm as l, type ExperimentResolution as m, type FlowPage as n, type FunnelLocales as o, type FunnelManifest as p, type Interval as q, type ManifestPage as r, type ManifestValidation as s, type Money as t, type OsContext as u, type PageType as v, type Predicate as w, type ResolvedOffering as x, type Route as y, type SystemContext as z };