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

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 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-Cr2y1op6.cjs';
-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-Cr2y1op6.cjs';
+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-Dl7faaKe.cjs';
+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-Dl7faaKe.cjs';
+import { NavSnapshot } from './protocol.cjs';
 import { a as CheckoutDriver, C as CheckoutDriverContext } from './checkout-Dz8cGkB_.cjs';
 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-Dz8cGkB_.cjs';
 import { ToasterProps } from 'sonner';
@@ -113,8 +114,16 @@ interface FunnelEventDataMap {
         priceId?: string;
         productName?: string;
         surface?: string;
+        amount?: number;
+        currency?: string;
+        eventId?: string;
+    };
+    'checkout.payment_added': {
+        productId?: string;
+        amount?: number;
+        currency?: string;
+        eventId?: string;
     };
-    'checkout.payment_added': Record<string, never>;
     'checkout.failed': {
         category: string;
         declineCode?: string;
@@ -126,6 +135,13 @@ interface FunnelEventDataMap {
         currency?: string;
         email?: string;
         eventId?: string;
+        productId?: string;
+    };
+    'subscription.created': {
+        amount?: number;
+        currency?: string;
+        productId?: string;
+        eventId?: string;
     };
     'experiment.exposure': {
         experimentId: string;
@@ -171,6 +187,99 @@ declare function useTracker(): {
     track: Tracker['track'];
 };
 
+/**
+ * The **`window.appfunnel` event bus** — the client-side integration surface
+ * (port of v0 `admin/lib/funnel/utils/appfunnelRuntime.ts`).
+ *
+ * Every taxonomy event the runtime emits is mirrored here, so on-page pixels and
+ * custom scripts integrate by **subscribing** — `window.appfunnel.on('purchase.complete', …)`
+ * — instead of the funnel hand-injecting pixel config per page. The pre-built pixel
+ * loaders (Meta/TikTok/GTM/Clarity) are just subscribers; CAPI stays the server-side
+ * default (this is the *client* sink of the same events). See doc 08 §3.
+ *
+ * Two deliberate properties vs. v0:
+ *  - **Replay history** (`events`): async pixels load *after* `funnel.start`/`page.view`
+ *    fire, so a late subscriber would miss them. The bus keeps a bounded history a
+ *    subscriber can replay (the GTM `dataLayer` trick) — no lost events.
+ *  - **Subscribe + read + drive.** The window surface exposes `on`/`off`/`events` + read
+ *    getters, and — resolving the deferred bus-control-scope decision (doc 08 §3/§4) —
+ *    **flow control**: `goTo`/`goNext`/`goPrevious` + a `navigation()` snapshot, so a host
+ *    page (the live editor, or an author's own external nav UI) can drive the funnel. It
+ *    still has **no `emit`** (third-party code can't forge taxonomy events) and no
+ *    `setVariable` (state stays funnel-owned). Flow control is a no-op (warns once) until a
+ *    `<FunnelView>` mounts and registers itself via {@link FunnelBus.registerNavigation}.
+ */
+
+/** Read accessors the bus exposes — wired to the funnel's store + context. */
+interface BusAccessors {
+    getVariable: (key: string) => unknown;
+    getVariables: () => Record<string, unknown>;
+    getCurrentPageId: () => string | null;
+    getCustomerId: () => string | null;
+    getVisitorId: () => string | null;
+}
+interface BusEvent {
+    event: string;
+    data: unknown;
+    /** Epoch ms the event was emitted (for ordering / replay). */
+    ts: number;
+}
+type Listener = (data: unknown) => void;
+/** The flow-control seam a mounted `<FunnelView>` registers into the bus (SDK-internal). */
+interface NavigationControl {
+    /** Jump to a page key. Returns `false` if the key isn't a real page (no navigation happened). */
+    goTo(pageKey: string): boolean;
+    goNext(): void;
+    goPrevious(): void;
+    snapshot(): NavSnapshot | null;
+}
+/**
+ * The public `window.appfunnel` surface — subscribe + read + drive the flow. It never
+ * exposes `emit` (no forged events) or `setVariable` (state stays funnel-owned).
+ */
+interface AppFunnelBusApi extends BusAccessors {
+    /** Subscribe to an event (or `'*'` for all). Returns an unsubscribe fn. */
+    on(event: string, cb: Listener): () => void;
+    off(event: string, cb: Listener): void;
+    /** Bounded replay history — read past events, then `on()` for future ones. */
+    readonly events: BusEvent[];
+    /** Jump the flow to a page key. Returns `false` for an unknown key (or before the flow mounts). */
+    goTo(pageKey: string): boolean;
+    /** Advance via the current page's `next` predicate (else the linear next). */
+    goNext(): void;
+    /** Step back to the previous page in flow history. */
+    goPrevious(): void;
+    /** The current flow snapshot, or `null` before a `<FunnelView>` mounts. */
+    navigation(): NavSnapshot | null;
+}
+/**
+ * The internal bus: the public {@link AppFunnelBusApi} plus `emit` (SDK-only) and
+ * `now` injection. The SDK holds this; only {@link AppFunnelBusApi} reaches `window`.
+ */
+interface FunnelBus extends AppFunnelBusApi {
+    emit(event: string, data?: unknown): void;
+    /** SDK-only: a mounted `<FunnelView>` registers its flow control; returns an unregister fn. */
+    registerNavigation(nav: NavigationControl): () => void;
+}
+/** Create a bus over the given read accessors. `now` is injectable for tests. */
+declare function createBus(accessors: BusAccessors, now?: () => number): FunnelBus;
+/**
+ * Wrap a {@link Tracker} so every emitted taxonomy event is mirrored to the bus
+ * (the client sink). `identify()` also surfaces a `user.registered` to the bus, so
+ * pixels see registration. The server sink (the inner tracker → CAPI) is untouched.
+ */
+declare function withBus(tracker: Tracker, bus: FunnelBus): Tracker;
+declare global {
+    interface Window {
+        appfunnel?: AppFunnelBusApi;
+    }
+}
+/**
+ * Attach the bus's public surface to `window.appfunnel` (client-side only).
+ * Returns a detach fn for unmount. No-op under SSR.
+ */
+declare function attachBus(bus: FunnelBus): () => void;
+
 /**
  * v2 `products` — the **read-only** product catalog.
  *
@@ -325,6 +434,15 @@ interface FunnelProviderProps {
     config?: FunnelDefinition;
     /** Server / session-restored values overriding declared defaults. */
     sessionValues?: Record<string, VariableValue>;
+    /**
+     * FLASH-FREE HYDRATION (SSR-isolation Option B): when true, the store is seeded with
+     * DEFAULTS only for the initial (hydration) render — matching the build-time-prerendered
+     * DEFAULT-state markup — and `sessionValues` are applied as a POST-hydration state update in
+     * a mount effect (`store.setMany`), so a returning visitor's saved answers pop into
+     * already-visible controls without an empty-shell flash or a hydration mismatch. Off (the
+     * default) preserves the original behavior: `sessionValues` seed the store at construction
+     * (used by SSR itself and by non-prerendered mounts). The client entry sets this to true. */
+    deferSessionValues?: boolean;
     /** The platform tracker; defaults to a silent console tracker (tests/dev). */
     tracker?: Tracker;
     /** Computed-context seed (funnel id, test/live mode, server-hydrated utm/session). */
@@ -349,7 +467,7 @@ interface FunnelProviderProps {
  * Mounts a funnel: builds the writable {@link VariableStore} + the read-only
  * {@link FunnelContext} (once) and provides the runtime to the tree via hooks.
  */
-declare function FunnelProvider({ config, sessionValues, tracker, context: contextOpts, products, experiments, checkout, messages, locale: localeOverride, toaster, store, children, }: FunnelProviderProps): ReactNode;
+declare function FunnelProvider({ config, sessionValues, deferSessionValues, tracker, context: contextOpts, products, experiments, checkout, messages, locale: localeOverride, toaster, store, children, }: FunnelProviderProps): ReactNode;
 /**
  * The imperative handle. Does **not** subscribe — use it in event handlers and
  * effects (`useFunnel().responses.set({...})`). For reactive reads use the hooks.
@@ -462,9 +580,20 @@ declare function useExperiment(id: string): string | undefined;
  *
  * Must live inside `<FunnelProvider>`.
  */
-declare function FunnelView({ pages, initialKey, layout, fallback, prefetch: prefetchMode, onNavigate, }: {
+declare function FunnelView({ pages, initialKey, trustInitialKey, layout, fallback, prefetch: prefetchMode, onNavigate, }: {
     pages: RuntimePage[];
     initialKey?: string;
+    /**
+     * FLASH-FREE HYDRATION (SSR-isolation Option B, FIX 1): honor `initialKey` VERBATIM as the entry
+     * page, WITHOUT re-evaluating its entry `guard` on the client. The SERVER already resolved the
+     * true entry — either by evaluating a declarative guard to pick the prerendered target-vs-bounce,
+     * or by running the real guard inside the fallback SSR render — and threaded the resolved key
+     * here. With `deferSessionValues` on, the client's initial snapshot is EMPTY (saved answers arrive
+     * post-hydration), so re-running the guard here would wrongly bounce a qualified visitor and
+     * mismatch the server markup. Set by the client entry (via createFunnelTree) alongside
+     * `deferSessionValues`; the guard still protects in-funnel navigation and non-deferred mounts.
+     */
+    trustInitialKey?: boolean;
     layout?: ComponentType<{
         children: ReactNode;
     }>;
@@ -552,6 +681,23 @@ interface MountOpts {
     /** The server-resolved session id backing `sessionValues` — seeds the tracker (fallback)
      *  and `context.session.id`. */
     sessionId?: string | null;
+    /** Mount the cross-origin {@link EmbedBridge} — the Funnel Embed API (flow snapshot + goTo/goNext/
+     *  goPrevious + screenshot, over the versioned wire protocol). Set ONLY by preview surfaces (the live
+     *  editor + the sealed `/preview/<buildId>` build); a live prod funnel leaves it off so it can't be
+     *  driven / can't leak its flow state to an embedder. */
+    embed?: boolean;
+    /** FLASH-FREE HYDRATION (SSR-isolation Option B): set by the CLIENT entry only. The initial
+     *  render is seeded with DEFAULTS (matching the build-time default-state prerender it hydrates
+     *  against), then `sessionValues` are applied post-hydration via `store.setMany` — a returning
+     *  visitor's saved answers pop into already-visible controls, no empty flash, no mismatch. Unset
+     *  on SSR (the server render must bake sessionValues into the markup, the original behavior). */
+    deferSessionValues?: boolean;
+    /** SSR-isolation Option B, FIX 1: render `initialKey` VERBATIM without evaluating its entry guard.
+     *  Set by the build-time PRERENDER stage so a guarded page (paywall/upsell) prerenders its OWN
+     *  default-state markup (the renderer decides target-vs-bounce at serve time by evaluating the
+     *  guard against the visitor's session). Defaults to `deferSessionValues` (the client trusts the
+     *  server-resolved key); the prerender sets it true explicitly while leaving sessionValues baked. */
+    trustInitialKey?: boolean;
 }
 /**
  * The shape a funnel build's `mount.tsx` module must export — the named,
@@ -743,76 +889,6 @@ type ModalProps = OverlayCommon;
 /** A centered dialog. Auto-binds to its `defineModal` — `<Modal>…`. */
 declare function Modal(props: ModalProps): ReactNode;
 
-/**
- * The **`window.appfunnel` event bus** — the client-side integration surface
- * (port of v0 `admin/lib/funnel/utils/appfunnelRuntime.ts`).
- *
- * Every taxonomy event the runtime emits is mirrored here, so on-page pixels and
- * custom scripts integrate by **subscribing** — `window.appfunnel.on('purchase.complete', …)`
- * — instead of the funnel hand-injecting pixel config per page. The pre-built pixel
- * loaders (Meta/TikTok/GTM/Clarity) are just subscribers; CAPI stays the server-side
- * default (this is the *client* sink of the same events). See doc 08 §3.
- *
- * Two deliberate properties vs. v0:
- *  - **Replay history** (`events`): async pixels load *after* `funnel.start`/`page.view`
- *    fire, so a late subscriber would miss them. The bus keeps a bounded history a
- *    subscriber can replay (the GTM `dataLayer` trick) — no lost events.
- *  - **Subscribe + read only.** The window surface exposes `on`/`off`/`events` + read
- *    getters; it has **no `emit`** (third-party code can't forge events) and **no
- *    mutating actions** (`setVariable`/navigation) — the funnel can't be driven through
- *    it. (v0's full-control Custom-JS API is deferred pending the bus-control-scope
- *    decision; doc 08 §3 + §4.)
- */
-
-/** Read accessors the bus exposes — wired to the funnel's store + context. */
-interface BusAccessors {
-    getVariable: (key: string) => unknown;
-    getVariables: () => Record<string, unknown>;
-    getCurrentPageId: () => string | null;
-    getCustomerId: () => string | null;
-    getVisitorId: () => string | null;
-}
-interface BusEvent {
-    event: string;
-    data: unknown;
-    /** Epoch ms the event was emitted (for ordering / replay). */
-    ts: number;
-}
-type Listener = (data: unknown) => void;
-/** The public `window.appfunnel` surface — subscribe + read, never emit or mutate. */
-interface AppFunnelBusApi extends BusAccessors {
-    /** Subscribe to an event (or `'*'` for all). Returns an unsubscribe fn. */
-    on(event: string, cb: Listener): () => void;
-    off(event: string, cb: Listener): void;
-    /** Bounded replay history — read past events, then `on()` for future ones. */
-    readonly events: BusEvent[];
-}
-/**
- * The internal bus: the public {@link AppFunnelBusApi} plus `emit` (SDK-only) and
- * `now` injection. The SDK holds this; only {@link AppFunnelBusApi} reaches `window`.
- */
-interface FunnelBus extends AppFunnelBusApi {
-    emit(event: string, data?: unknown): void;
-}
-/** Create a bus over the given read accessors. `now` is injectable for tests. */
-declare function createBus(accessors: BusAccessors, now?: () => number): FunnelBus;
-/**
- * Wrap a {@link Tracker} so every emitted taxonomy event is mirrored to the bus
- * (the client sink). `identify()` also surfaces a `user.registered` to the bus, so
- * pixels see registration. The server sink (the inner tracker → CAPI) is untouched.
- */
-declare function withBus(tracker: Tracker, bus: FunnelBus): Tracker;
-declare global {
-    interface Window {
-        appfunnel?: AppFunnelBusApi;
-    }
-}
-/**
- * Attach the bus's public surface to `window.appfunnel` (client-side only).
- * Returns a detach fn for unmount. No-op under SSR.
- */
-declare function attachBus(bus: FunnelBus): () => void;
-
 /**
  * The **event catalog** — the single source of truth for *which* events exist and
  * how each is routed (analytics vs. integrations vs. runtime-only). Pairs with the

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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-Cr2y1op6.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-Cr2y1op6.js';
+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-Dl7faaKe.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-Dl7faaKe.js';
+import { NavSnapshot } from './protocol.js';
 import { a as CheckoutDriver, C as CheckoutDriverContext } from './checkout-7Dy6IedP.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-7Dy6IedP.js';
 import { ToasterProps } from 'sonner';
@@ -113,8 +114,16 @@ interface FunnelEventDataMap {
         priceId?: string;
         productName?: string;
         surface?: string;
+        amount?: number;
+        currency?: string;
+        eventId?: string;
+    };
+    'checkout.payment_added': {
+        productId?: string;
+        amount?: number;
+        currency?: string;
+        eventId?: string;
     };
-    'checkout.payment_added': Record<string, never>;
     'checkout.failed': {
         category: string;
         declineCode?: string;
@@ -126,6 +135,13 @@ interface FunnelEventDataMap {
         currency?: string;
         email?: string;
         eventId?: string;
+        productId?: string;
+    };
+    'subscription.created': {
+        amount?: number;
+        currency?: string;
+        productId?: string;
+        eventId?: string;
     };
     'experiment.exposure': {
         experimentId: string;
@@ -171,6 +187,99 @@ declare function useTracker(): {
     track: Tracker['track'];
 };
 
+/**
+ * The **`window.appfunnel` event bus** — the client-side integration surface
+ * (port of v0 `admin/lib/funnel/utils/appfunnelRuntime.ts`).
+ *
+ * Every taxonomy event the runtime emits is mirrored here, so on-page pixels and
+ * custom scripts integrate by **subscribing** — `window.appfunnel.on('purchase.complete', …)`
+ * — instead of the funnel hand-injecting pixel config per page. The pre-built pixel
+ * loaders (Meta/TikTok/GTM/Clarity) are just subscribers; CAPI stays the server-side
+ * default (this is the *client* sink of the same events). See doc 08 §3.
+ *
+ * Two deliberate properties vs. v0:
+ *  - **Replay history** (`events`): async pixels load *after* `funnel.start`/`page.view`
+ *    fire, so a late subscriber would miss them. The bus keeps a bounded history a
+ *    subscriber can replay (the GTM `dataLayer` trick) — no lost events.
+ *  - **Subscribe + read + drive.** The window surface exposes `on`/`off`/`events` + read
+ *    getters, and — resolving the deferred bus-control-scope decision (doc 08 §3/§4) —
+ *    **flow control**: `goTo`/`goNext`/`goPrevious` + a `navigation()` snapshot, so a host
+ *    page (the live editor, or an author's own external nav UI) can drive the funnel. It
+ *    still has **no `emit`** (third-party code can't forge taxonomy events) and no
+ *    `setVariable` (state stays funnel-owned). Flow control is a no-op (warns once) until a
+ *    `<FunnelView>` mounts and registers itself via {@link FunnelBus.registerNavigation}.
+ */
+
+/** Read accessors the bus exposes — wired to the funnel's store + context. */
+interface BusAccessors {
+    getVariable: (key: string) => unknown;
+    getVariables: () => Record<string, unknown>;
+    getCurrentPageId: () => string | null;
+    getCustomerId: () => string | null;
+    getVisitorId: () => string | null;
+}
+interface BusEvent {
+    event: string;
+    data: unknown;
+    /** Epoch ms the event was emitted (for ordering / replay). */
+    ts: number;
+}
+type Listener = (data: unknown) => void;
+/** The flow-control seam a mounted `<FunnelView>` registers into the bus (SDK-internal). */
+interface NavigationControl {
+    /** Jump to a page key. Returns `false` if the key isn't a real page (no navigation happened). */
+    goTo(pageKey: string): boolean;
+    goNext(): void;
+    goPrevious(): void;
+    snapshot(): NavSnapshot | null;
+}
+/**
+ * The public `window.appfunnel` surface — subscribe + read + drive the flow. It never
+ * exposes `emit` (no forged events) or `setVariable` (state stays funnel-owned).
+ */
+interface AppFunnelBusApi extends BusAccessors {
+    /** Subscribe to an event (or `'*'` for all). Returns an unsubscribe fn. */
+    on(event: string, cb: Listener): () => void;
+    off(event: string, cb: Listener): void;
+    /** Bounded replay history — read past events, then `on()` for future ones. */
+    readonly events: BusEvent[];
+    /** Jump the flow to a page key. Returns `false` for an unknown key (or before the flow mounts). */
+    goTo(pageKey: string): boolean;
+    /** Advance via the current page's `next` predicate (else the linear next). */
+    goNext(): void;
+    /** Step back to the previous page in flow history. */
+    goPrevious(): void;
+    /** The current flow snapshot, or `null` before a `<FunnelView>` mounts. */
+    navigation(): NavSnapshot | null;
+}
+/**
+ * The internal bus: the public {@link AppFunnelBusApi} plus `emit` (SDK-only) and
+ * `now` injection. The SDK holds this; only {@link AppFunnelBusApi} reaches `window`.
+ */
+interface FunnelBus extends AppFunnelBusApi {
+    emit(event: string, data?: unknown): void;
+    /** SDK-only: a mounted `<FunnelView>` registers its flow control; returns an unregister fn. */
+    registerNavigation(nav: NavigationControl): () => void;
+}
+/** Create a bus over the given read accessors. `now` is injectable for tests. */
+declare function createBus(accessors: BusAccessors, now?: () => number): FunnelBus;
+/**
+ * Wrap a {@link Tracker} so every emitted taxonomy event is mirrored to the bus
+ * (the client sink). `identify()` also surfaces a `user.registered` to the bus, so
+ * pixels see registration. The server sink (the inner tracker → CAPI) is untouched.
+ */
+declare function withBus(tracker: Tracker, bus: FunnelBus): Tracker;
+declare global {
+    interface Window {
+        appfunnel?: AppFunnelBusApi;
+    }
+}
+/**
+ * Attach the bus's public surface to `window.appfunnel` (client-side only).
+ * Returns a detach fn for unmount. No-op under SSR.
+ */
+declare function attachBus(bus: FunnelBus): () => void;
+
 /**
  * v2 `products` — the **read-only** product catalog.
  *
@@ -325,6 +434,15 @@ interface FunnelProviderProps {
     config?: FunnelDefinition;
     /** Server / session-restored values overriding declared defaults. */
     sessionValues?: Record<string, VariableValue>;
+    /**
+     * FLASH-FREE HYDRATION (SSR-isolation Option B): when true, the store is seeded with
+     * DEFAULTS only for the initial (hydration) render — matching the build-time-prerendered
+     * DEFAULT-state markup — and `sessionValues` are applied as a POST-hydration state update in
+     * a mount effect (`store.setMany`), so a returning visitor's saved answers pop into
+     * already-visible controls without an empty-shell flash or a hydration mismatch. Off (the
+     * default) preserves the original behavior: `sessionValues` seed the store at construction
+     * (used by SSR itself and by non-prerendered mounts). The client entry sets this to true. */
+    deferSessionValues?: boolean;
     /** The platform tracker; defaults to a silent console tracker (tests/dev). */
     tracker?: Tracker;
     /** Computed-context seed (funnel id, test/live mode, server-hydrated utm/session). */
@@ -349,7 +467,7 @@ interface FunnelProviderProps {
  * Mounts a funnel: builds the writable {@link VariableStore} + the read-only
  * {@link FunnelContext} (once) and provides the runtime to the tree via hooks.
  */
-declare function FunnelProvider({ config, sessionValues, tracker, context: contextOpts, products, experiments, checkout, messages, locale: localeOverride, toaster, store, children, }: FunnelProviderProps): ReactNode;
+declare function FunnelProvider({ config, sessionValues, deferSessionValues, tracker, context: contextOpts, products, experiments, checkout, messages, locale: localeOverride, toaster, store, children, }: FunnelProviderProps): ReactNode;
 /**
  * The imperative handle. Does **not** subscribe — use it in event handlers and
  * effects (`useFunnel().responses.set({...})`). For reactive reads use the hooks.
@@ -462,9 +580,20 @@ declare function useExperiment(id: string): string | undefined;
  *
  * Must live inside `<FunnelProvider>`.
  */
-declare function FunnelView({ pages, initialKey, layout, fallback, prefetch: prefetchMode, onNavigate, }: {
+declare function FunnelView({ pages, initialKey, trustInitialKey, layout, fallback, prefetch: prefetchMode, onNavigate, }: {
     pages: RuntimePage[];
     initialKey?: string;
+    /**
+     * FLASH-FREE HYDRATION (SSR-isolation Option B, FIX 1): honor `initialKey` VERBATIM as the entry
+     * page, WITHOUT re-evaluating its entry `guard` on the client. The SERVER already resolved the
+     * true entry — either by evaluating a declarative guard to pick the prerendered target-vs-bounce,
+     * or by running the real guard inside the fallback SSR render — and threaded the resolved key
+     * here. With `deferSessionValues` on, the client's initial snapshot is EMPTY (saved answers arrive
+     * post-hydration), so re-running the guard here would wrongly bounce a qualified visitor and
+     * mismatch the server markup. Set by the client entry (via createFunnelTree) alongside
+     * `deferSessionValues`; the guard still protects in-funnel navigation and non-deferred mounts.
+     */
+    trustInitialKey?: boolean;
     layout?: ComponentType<{
         children: ReactNode;
     }>;
@@ -552,6 +681,23 @@ interface MountOpts {
     /** The server-resolved session id backing `sessionValues` — seeds the tracker (fallback)
      *  and `context.session.id`. */
     sessionId?: string | null;
+    /** Mount the cross-origin {@link EmbedBridge} — the Funnel Embed API (flow snapshot + goTo/goNext/
+     *  goPrevious + screenshot, over the versioned wire protocol). Set ONLY by preview surfaces (the live
+     *  editor + the sealed `/preview/<buildId>` build); a live prod funnel leaves it off so it can't be
+     *  driven / can't leak its flow state to an embedder. */
+    embed?: boolean;
+    /** FLASH-FREE HYDRATION (SSR-isolation Option B): set by the CLIENT entry only. The initial
+     *  render is seeded with DEFAULTS (matching the build-time default-state prerender it hydrates
+     *  against), then `sessionValues` are applied post-hydration via `store.setMany` — a returning
+     *  visitor's saved answers pop into already-visible controls, no empty flash, no mismatch. Unset
+     *  on SSR (the server render must bake sessionValues into the markup, the original behavior). */
+    deferSessionValues?: boolean;
+    /** SSR-isolation Option B, FIX 1: render `initialKey` VERBATIM without evaluating its entry guard.
+     *  Set by the build-time PRERENDER stage so a guarded page (paywall/upsell) prerenders its OWN
+     *  default-state markup (the renderer decides target-vs-bounce at serve time by evaluating the
+     *  guard against the visitor's session). Defaults to `deferSessionValues` (the client trusts the
+     *  server-resolved key); the prerender sets it true explicitly while leaving sessionValues baked. */
+    trustInitialKey?: boolean;
 }
 /**
  * The shape a funnel build's `mount.tsx` module must export — the named,
@@ -743,76 +889,6 @@ type ModalProps = OverlayCommon;
 /** A centered dialog. Auto-binds to its `defineModal` — `<Modal>…`. */
 declare function Modal(props: ModalProps): ReactNode;
 
-/**
- * The **`window.appfunnel` event bus** — the client-side integration surface
- * (port of v0 `admin/lib/funnel/utils/appfunnelRuntime.ts`).
- *
- * Every taxonomy event the runtime emits is mirrored here, so on-page pixels and
- * custom scripts integrate by **subscribing** — `window.appfunnel.on('purchase.complete', …)`
- * — instead of the funnel hand-injecting pixel config per page. The pre-built pixel
- * loaders (Meta/TikTok/GTM/Clarity) are just subscribers; CAPI stays the server-side
- * default (this is the *client* sink of the same events). See doc 08 §3.
- *
- * Two deliberate properties vs. v0:
- *  - **Replay history** (`events`): async pixels load *after* `funnel.start`/`page.view`
- *    fire, so a late subscriber would miss them. The bus keeps a bounded history a
- *    subscriber can replay (the GTM `dataLayer` trick) — no lost events.
- *  - **Subscribe + read only.** The window surface exposes `on`/`off`/`events` + read
- *    getters; it has **no `emit`** (third-party code can't forge events) and **no
- *    mutating actions** (`setVariable`/navigation) — the funnel can't be driven through
- *    it. (v0's full-control Custom-JS API is deferred pending the bus-control-scope
- *    decision; doc 08 §3 + §4.)
- */
-
-/** Read accessors the bus exposes — wired to the funnel's store + context. */
-interface BusAccessors {
-    getVariable: (key: string) => unknown;
-    getVariables: () => Record<string, unknown>;
-    getCurrentPageId: () => string | null;
-    getCustomerId: () => string | null;
-    getVisitorId: () => string | null;
-}
-interface BusEvent {
-    event: string;
-    data: unknown;
-    /** Epoch ms the event was emitted (for ordering / replay). */
-    ts: number;
-}
-type Listener = (data: unknown) => void;
-/** The public `window.appfunnel` surface — subscribe + read, never emit or mutate. */
-interface AppFunnelBusApi extends BusAccessors {
-    /** Subscribe to an event (or `'*'` for all). Returns an unsubscribe fn. */
-    on(event: string, cb: Listener): () => void;
-    off(event: string, cb: Listener): void;
-    /** Bounded replay history — read past events, then `on()` for future ones. */
-    readonly events: BusEvent[];
-}
-/**
- * The internal bus: the public {@link AppFunnelBusApi} plus `emit` (SDK-only) and
- * `now` injection. The SDK holds this; only {@link AppFunnelBusApi} reaches `window`.
- */
-interface FunnelBus extends AppFunnelBusApi {
-    emit(event: string, data?: unknown): void;
-}
-/** Create a bus over the given read accessors. `now` is injectable for tests. */
-declare function createBus(accessors: BusAccessors, now?: () => number): FunnelBus;
-/**
- * Wrap a {@link Tracker} so every emitted taxonomy event is mirrored to the bus
- * (the client sink). `identify()` also surfaces a `user.registered` to the bus, so
- * pixels see registration. The server sink (the inner tracker → CAPI) is untouched.
- */
-declare function withBus(tracker: Tracker, bus: FunnelBus): Tracker;
-declare global {
-    interface Window {
-        appfunnel?: AppFunnelBusApi;
-    }
-}
-/**
- * Attach the bus's public surface to `window.appfunnel` (client-side only).
- * Returns a detach fn for unmount. No-op under SSR.
- */
-declare function attachBus(bus: FunnelBus): () => void;
-
 /**
  * The **event catalog** — the single source of truth for *which* events exist and
  * how each is routed (analytics vs. integrations vs. runtime-only). Pairs with the