@appright/funnelshift 0.16.0 → 0.17.0

package/dist/attribution.js

@@ -144,8 +144,9 @@ function entryOf(loc, doc, project, funnel, mountPath) {
     const fit = [];
     for (const [k, v] of q) {
         // __shot, __step, __build, __exp, __sig: the kit's and the router's own (a preview signature among them), not the link's;
-        // $dropped is the kit's count, never taken from a link
-        if (!k || k.startsWith('__') || k === DROPPED_KEY || chars(k).length > MAX_PARAM_KEY || seen.has(k))
+        // $dropped is the kit's count, never taken from a link; link_token is the router's (a hosted paywall's signed placement link,
+        // kit 0.17.0), ?placement next to it stays
+        if (!k || k.startsWith('__') || k === DROPPED_KEY || k === 'link_token' || chars(k).length > MAX_PARAM_KEY || seen.has(k))
             continue;
         seen.add(k);
         fit.push([k, cutTo(v, MAX_PARAM_VALUE)]);

package/dist/bootstrap.d.ts

@@ -1,3 +1,4 @@
+import type { PlacementContent, URLPlacement } from './placement.js';
 export type Env = 'prod' | 'preview' | 'dev';
 export type Creator = {
     code: string;
@@ -18,6 +19,11 @@ export type Bootstrap = {
     fn_preview?: string;
     creator?: Creator;
     variants?: Record<string, string>;
+    experiments?: Record<string, {
+        type: 'build' | 'content';
+        phase: number;
+        keys: string[];
+    }>;
     content_overrides?: Record<string, string | number | boolean>;
     fn_arm?: string;
     fn_base?: string;
@@ -28,6 +34,12 @@ export type Bootstrap = {
         lead_step?: string;
         checkout_step?: string;
     };
+    placements?: Record<string, PlacementContent>;
+    placement_rejected?: {
+        placement: string;
+        reason: string;
+    };
+    placement_url?: URLPlacement;
 };
 export declare function readBootstrap(win?: Window): Bootstrap;
 export declare function readCreator(win?: Window): Creator | null;

package/dist/cli/extract.d.ts

@@ -22,6 +22,7 @@ type Src = {
 export type ManifestStep = {
     id: string;
     role?: StepRole;
+    placement?: string;
     sensitive?: true;
     conditional?: true;
     when_keys?: string[];

package/dist/cli/extract.js

@@ -58,18 +58,11 @@ export function extractContent(files) {
 }
 const unwrap = (n) => (n && ['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'ParenthesizedExpression'].includes(n.type) ? unwrap(n.expression) : n);
 const isCall = (n, name) => n?.type === 'CallExpression' && n.callee?.type === 'Identifier' && n.callee.name === name;
-// The answer keys a step's `when` reads, when its code tells them: an arrow or function whose one parameter is only ever read as
-// `a.key`, `a?.key` or `a['key']`, or is destructured with literal keys and no rest; no parameter reads none. Anything else (the
-// parameter passed on or spread, a computed key, a function declared elsewhere) gives null: the step is conditional, its keys unknown.
-export function whenKeys(fn) {
-    fn = unwrap(fn);
-    if (fn?.type !== 'ArrowFunctionExpression' && fn?.type !== 'FunctionExpression')
-        return null;
-    if (fn.params.length === 0)
-        return [];
-    if (fn.params.length > 1)
-        return null;
-    let p = fn.params[0];
+const PLACEMENT_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+// The keys a function reads of one of its parameters, when its code tells them: the parameter is only ever read as `a.key`, `a?.key`
+// or `a['key']`, or is destructured with literal keys and no rest; an unused parameter reads none. Anything else (the parameter passed
+// on or spread, a computed key) gives null.
+function paramKeys(fn, p) {
     if (p.type === 'AssignmentPattern')
         p = p.left;
     const keys = [];
@@ -122,7 +115,20 @@ export function whenKeys(fn) {
     visit(fn.body, fn, 'body');
     return ok ? keys : null;
 }
-// Steps (id, optional role, sensitive: true when the step is marked) in screen order, read statically from `defineFunnel({ steps: [...] })` (the manifest's `steps`, which the server uses to
+// The keys a step's `when` reads, when its code tells them: the answers it reads (the first parameter) as their keys, the experiments
+// it reads (the second, `(a, ab) => ab.quiz_len === 'long'`) as `ab.<experiment>`, in the order of the parameters. Anything else (a
+// parameter passed on or spread, a computed key, a function declared elsewhere) gives null: the step is conditional, its keys unknown.
+export function whenKeys(fn) {
+    fn = unwrap(fn);
+    if (fn?.type !== 'ArrowFunctionExpression' && fn?.type !== 'FunctionExpression')
+        return null;
+    if (fn.params.length > 2)
+        return null;
+    const answers = fn.params[0] ? paramKeys(fn, fn.params[0]) : [];
+    const arms = fn.params[1] ? paramKeys(fn, fn.params[1]) : [];
+    return answers && arms ? [...answers, ...arms.map(k => `ab.${k}`)] : null;
+}
+// Steps (id, optional role and placement, sensitive: true when the step is marked) in screen order, read statically from `defineFunnel({ steps: [...] })` (the manifest's `steps`, which the server uses to
 // order the report and find the lead and paywall steps). An element is `defineStep({ id: '...' })` or an identifier declared as `const x = defineStep({...})` in the
 // same file; anything else (imports, spreads, computed ids) is an error with file:line, never a guess.
 export function extractSteps(files) {
@@ -199,6 +205,16 @@ export function extractSteps(files) {
             }
             out.role = role;
         }
+        // placement (kit 0.17.0): the project's placement the step sells in; the server refuses a publish whose placement it does not
+        // have (placement_not_found), so a typo fails there and never makes a new placement.
+        const placementProp = option('placement');
+        if (placementProp) {
+            const key = literal(unwrap(placementProp.value));
+            if (key === null || !PLACEMENT_KEY.test(key)) {
+                throw new Error(`${at(placementProp)}: defineStep() placement must be a placement key as a string literal (${PLACEMENT_KEY.source})`);
+            }
+            out.placement = key;
+        }
         // sensitive only marks the step in the admin; the manifest carries it so the server can say so (steps_order).
         const sensProp = option('sensitive');
         if (sensProp) {

package/dist/content.js

@@ -1,3 +1,4 @@
+import { readKey } from './exposure.js';
 let content = {};
 let overrides = {};
 // The reverse dictionary for $click names (clicks.ts): every text t() has produced on this page, whitespace collapsed → its key.
@@ -25,8 +26,10 @@ function valueOf(key) {
 }
 export const collapse = (s) => s.replace(/\s+/g, ' ').trim();
 // t(key, default): the published text for key, else the default written in code. The build collects every
-// t() call with its default into the manifest, so all texts are editable in the admin.
+// t() call with its default into the manifest, so all texts are editable in the admin. A read of a key that an experiment's arm sets
+// is that experiment's exposure (exposure.ts), whichever arm the visitor is in.
 export function t(key, def, vars) {
+    readKey(key);
     const v = valueOf(key);
     const s = v === undefined ? def : String(v);
     const out = vars ? s.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in vars ? String(vars[k]) : m)) : s;
@@ -36,6 +39,7 @@ export function t(key, def, vars) {
 // param(key, default): a number, string or boolean the admin (or an A/B arm) may change, of the default's type. A value that does
 // not read as that type ("abc" for a number) gives the default.
 export function param(key, def) {
+    readKey(key);
     const v = valueOf(key);
     if (v === undefined)
         return def;

package/dist/experiments.js

@@ -1,12 +1,17 @@
 // A/B in the funnel's code (kit 0.9.0, spec «A/B» §3): the visitor's arm, as the router assigned it (bootstrap.variants).
 import { useMemo } from 'react';
 import { readBootstrap } from './bootstrap.js';
-// The arm key of experiment `key` for this visitor, or null: no such experiment running, vite dev, an old router.
+import { readArm } from './exposure.js';
+// The arm key of experiment `key` for this visitor, or null: no such experiment running, vite dev, an old router. Reading the arm
+// is the first read of the experiment's value: it sends experiment_exposed (exposure.ts), except for the rule, which is no experiment.
 export function experiment(key) {
     const v = readBootstrap().variants;
     if (!v || typeof v !== 'object' || !Object.prototype.hasOwnProperty.call(v, key))
         return null;
-    return typeof v[key] === 'string' ? v[key] : null;
+    if (typeof v[key] !== 'string')
+        return null;
+    readArm(key);
+    return v[key];
 }
 // The same in a component; the bootstrap does not change while the page lives.
 export function useExperiment(key) {
@@ -14,7 +19,7 @@ export function useExperiment(key) {
 }
 // The targeting rule the router matched for this visitor (v2 track D: «Правила» in the admin), or null: no rule matched, vite dev, an
 // old router. Rules decide the build and the t()/param() values before any experiment does; this is for code that wants to know which
-// one it got. It is the `rule` key of the variants, so experiment('rule') answers the same, but a rule is no experiment: no $exposure.
+// one it got. It is the `rule` key of the variants, so experiment('rule') answers the same, but a rule is no experiment: no experiment events.
 export function rule() {
     return experiment('rule');
 }

package/dist/exposure.d.ts

@@ -1,4 +1,9 @@
 type Track = (name: string, props?: Record<string, unknown>) => void;
 export declare const RULE_KEY = "rule";
-export declare function exposeVariants(funnel: string, variants: Record<string, string> | undefined, track: Track): void;
+export type AB = Readonly<Record<string, string | undefined>>;
+export declare function readKey(key: string): void;
+export declare function readArm(experiment: string): void;
+export declare function currentAB(): AB;
+export declare function startExposure(funnel: string, track: Track): void;
+export declare function clearExposure(): void;
 export {};

package/dist/exposure.js

@@ -1,16 +1,112 @@
-// $exposure (kit 0.9.0, spec «A/B» §3): at the funnel's start, one event per experiment of the bootstrap, props {experiment, arm},
-// once per session. The variants key `rule` is the targeting rule the router matched, not an experiment: it has no $exposure: sessionStorage af_exposed:<funnel> keeps the session id (the tracker's, visit.session) and the arms already sent.
-// A new session (30 min idle) or another arm sends it again. Blocked storage: once per page load.
+import { readPlacement, readURLPlacement } from './placement.js';
 import { visit } from './server.js';
 // The variants key of the matched rule (v2 track D): it rides on every event as a variant, but a rule is no test and has no exposure.
 export const RULE_KEY = 'rule';
-export function exposeVariants(funnel, variants, track) {
-    if (!variants || typeof variants !== 'object')
+// The bootstrap if the page has one: not in Node (the landing's prerender at build time) and not without the router (vite dev).
+const boot = () => (typeof window === 'undefined' ? null : window.__FUNNEL__ ?? null);
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// The visitor's funnel experiments: { <experiment>: <arm> } without the rule and without junk.
+function armsOf(b) {
+    const out = {};
+    if (!isObj(b.variants))
+        return out;
+    for (const [experiment, arm] of Object.entries(b.variants))
+        if (experiment !== RULE_KEY && typeof arm === 'string' && arm)
+            out[experiment] = arm;
+    return out;
+}
+function metaOf(b, experiment) {
+    const m = isObj(b.experiments) && Object.prototype.hasOwnProperty.call(b.experiments, experiment) ? b.experiments[experiment] : null;
+    if (!isObj(m) || (m.type !== 'build' && m.type !== 'content') || !Array.isArray(m.keys))
+        return null;
+    return { type: m.type, phase: Number.isInteger(m.phase) ? m.phase : 1, keys: m.keys.filter((k) => typeof k === 'string') };
+}
+const funnelProps = (b, experiment, arm) => ({
+    space: 'funnel', experiment, phase: String(metaOf(b, experiment)?.phase ?? 1), arm, content_version: b.build_id, subject: `visitor:${b.visitor_id}`,
+});
+// ---- exposure: the first read of a value ----
+const exposed = new Set();
+// Experiments read before the funnel started (a t() at module level, the first render): sent when it starts.
+const pending = new Set();
+let sink = null;
+function expose(experiment) {
+    if (exposed.has(experiment) || pending.has(experiment))
+        return;
+    const b = boot();
+    const arm = b ? armsOf(b)[experiment] : undefined;
+    if (!b || !arm)
         return;
-    const entries = Object.entries(variants).filter(([experiment, arm]) => experiment !== RULE_KEY && typeof arm === 'string' && arm);
-    if (!entries.length)
+    if (!sink) {
+        pending.add(experiment);
+        return;
+    }
+    exposed.add(experiment);
+    sink('experiment_exposed', funnelProps(b, experiment, arm));
+}
+// The experiments of the bootstrap by the t()/param() keys that read them; rebuilt when the page's bootstrap is another object.
+let indexed = null;
+function experimentsOfKey(b, key) {
+    if (indexed?.b !== b) {
+        const byKey = new Map();
+        const arms = armsOf(b);
+        for (const experiment of Object.keys(arms)) {
+            const m = metaOf(b, experiment);
+            if (m?.type === 'content')
+                for (const k of m.keys)
+                    byKey.set(k, [...(byKey.get(k) ?? []), experiment]);
+        }
+        indexed = { b, byKey };
+    }
+    return indexed.byKey.get(key);
+}
+// A t() or param() of `key` was read (content.ts): that exposes the experiments that have the key among the values their arms set.
+export function readKey(key) {
+    const b = boot();
+    if (!b?.experiments)
         return;
-    const key = `af_exposed:${funnel}`;
+    for (const experiment of experimentsOfKey(b, key) ?? [])
+        expose(experiment);
+}
+// The arm of `experiment` was read (experiments.ts): experiment(), useExperiment().
+export function readArm(experiment) {
+    expose(experiment);
+}
+let frozen = null;
+// The AB of this page, one object per page load (per bootstrap): a getter per experiment, which counts as the first read.
+export function currentAB() {
+    const b = boot();
+    if (frozen && frozen.variants === (b?.variants ?? undefined))
+        return frozen.ab;
+    const ab = Object.create(null);
+    for (const [experiment, arm] of Object.entries(b ? armsOf(b) : {})) {
+        Object.defineProperty(ab, experiment, { enumerable: true, get: () => { expose(experiment); return arm; } });
+    }
+    frozen = { variants: b?.variants ?? undefined, ab: Object.freeze(ab) };
+    return frozen.ab;
+}
+// experiment_assigned for what the router assigned, once per session and arm.
+function assign(funnel, b, track) {
+    const events = [];
+    for (const [experiment, arm] of Object.entries(armsOf(b)))
+        events.push({ key: `funnel:${experiment}`, arm, props: funnelProps(b, experiment, arm) });
+    if (isObj(b.placements)) {
+        for (const entry of Object.values(b.placements)) {
+            const c = readPlacement(entry);
+            if (!c || !c.experiment || !c.arm)
+                continue;
+            events.push({ key: `placement:${c.experiment}`, arm: c.arm, props: { space: 'placement', experiment: c.experiment, phase: String(c.phase), arm: c.arm,
+                    content_version: `${c.paywall}@${c.version}`, subject: c.subject || `visitor:${b.visitor_id}`, placement: c.placement } });
+        }
+    }
+    // a url placement's arm: this funnel at the build served
+    const u = readURLPlacement();
+    if (u?.experiment) {
+        events.push({ key: `placement:${u.experiment}`, arm: u.arm, props: { space: 'placement', experiment: u.experiment, phase: String(u.phase), arm: u.arm,
+                content_version: b.build_id, subject: u.subject || `visitor:${b.visitor_id}`, placement: u.placement } });
+    }
+    if (!events.length)
+        return;
+    const store = `af_assigned:${funnel}`;
     let sid = '';
     try {
         sid = visit.session();
@@ -18,18 +114,42 @@ export function exposeVariants(funnel, variants, track) {
     catch { /* no session */ }
     let seen = {};
     try {
-        seen = JSON.parse(sessionStorage.getItem(key) ?? '{}') ?? {};
+        seen = JSON.parse(sessionStorage.getItem(store) ?? '{}') ?? {};
     }
     catch { /* blocked or junk */ }
     const arms = seen.sid === sid && seen.arms && typeof seen.arms === 'object' ? { ...seen.arms } : {};
-    for (const [experiment, arm] of entries) {
-        if (arms[experiment] === arm)
+    for (const e of events) {
+        if (arms[e.key] === e.arm)
             continue;
-        track('$exposure', { experiment, arm });
-        arms[experiment] = arm;
+        track('experiment_assigned', e.props);
+        arms[e.key] = e.arm;
     }
     try {
-        sessionStorage.setItem(key, JSON.stringify({ sid, arms }));
+        sessionStorage.setItem(store, JSON.stringify({ sid, arms }));
     }
     catch { /* storage unavailable */ }
 }
+// The funnel started: send what the router assigned, expose the build experiments (all of them for an older router, which does not
+// say where an experiment is exposed), then what was read before this moment.
+export function startExposure(funnel, track) {
+    const b = boot();
+    if (!b)
+        return;
+    assign(funnel, b, track);
+    sink = track;
+    for (const experiment of Object.keys(armsOf(b)))
+        if (!b.experiments || metaOf(b, experiment)?.type === 'build')
+            expose(experiment);
+    for (const experiment of [...pending]) {
+        pending.delete(experiment);
+        expose(experiment);
+    }
+}
+// For tests: forget what this page load has exposed and where it sends.
+export function clearExposure() {
+    exposed.clear();
+    pending.clear();
+    sink = null;
+    indexed = null;
+    frozen = null;
+}

package/dist/functions.d.ts

@@ -25,9 +25,42 @@ export type FunctionCtx = {
     variants: Readonly<Record<string, string>>;
     params: Readonly<Record<string, string | number | boolean>>;
     rule: string;
+    placement: Readonly<FunctionPlacement> | null;
     reply(status: number, body?: unknown): Reply;
     track(name: string, props?: Record<string, unknown>): void;
 };
+export type FunctionPlacement = {
+    placement: string;
+    paywall: string;
+    version: number;
+    experiment: string;
+    arm: string;
+    layout: string;
+    config: Readonly<Record<string, unknown>>;
+    products: ReadonlyArray<{
+        key: string;
+        name: string;
+        kind: string;
+        period: string;
+        access_levels: readonly string[];
+        phases: readonly {
+            kind: string;
+            period?: string;
+        }[];
+        price: {
+            price_id: string;
+            currency: string;
+            amount: number;
+            interval: string;
+        } | null;
+        refs: readonly {
+            provider: string;
+            ref_kind: string;
+            ref: string;
+        }[];
+    }>;
+    fs_ctx: string;
+};
 export type FunctionHandler<P = any, R = unknown> = (payload: P, ctx: FunctionCtx) => R | Reply | Promise<R | Reply>;
 export type FunctionsModule<F extends Record<string, FunctionHandler> = Record<string, FunctionHandler>> = {
     readonly __funnelFunctions: 1;

package/dist/funnel.js

@@ -15,12 +15,13 @@ import { installErrors } from './errors.js';
 import { batchContext } from './context.js';
 import { emailHash } from './sha256.js';
 import { visit } from './server.js';
-import { exposeVariants } from './exposure.js';
+import { currentAB, startExposure } from './exposure.js';
 import { attribution } from './attribution.js';
 import { encodeAnswer, packAnswers } from './answers.js';
 import { LabelCtx, sameValue } from './offer.js';
 import { funnelSlug, setHandoff, visitorId } from './handoff.js';
 import { installPixel, metaCookies, readPixel, revokePixel, setPixel } from './pixel.js';
+import { layoutOf, PaywallCtx, placementOf, readURLPlacement } from './placement.js';
 export const defineStep = (s) => s;
 export const defineFunnel = (f) => f;
 export const FunnelCtx = createContext(null);
@@ -146,8 +147,14 @@ function ShotView({ funnel, stepId }) {
             stepId: step.id, index, total: funnel.steps.length, progress: 0, shot: true, stopTracking: async () => { }, creator: null,
             visitorId: '', funnelId: funnelSlug() || funnel.id, userId: '', knownUser: false };
     }, [funnel, step, index]);
-    const C = step.component;
-    return _jsx(FunnelCtx.Provider, { value: ctx, children: _jsx("div", { className: "fk-shot", children: _jsx(C, {}) }) });
+    const content = useMemo(() => placementOf(step), [step]);
+    const pw = useMemo(() => (content ? { ...content, view_id: '' } : null), [content]);
+    const C = stepComponent(step, content);
+    return _jsx(FunnelCtx.Provider, { value: ctx, children: _jsx(PaywallCtx.Provider, { value: pw, children: _jsx("div", { className: "fk-shot", children: _jsx(C, {}) }) }) });
+}
+// The component a step draws: the layout its placement serves when this build registered it (defineLayout), else its own.
+function stepComponent(step, content) {
+    return (content && layoutOf(content.layout)) || step.component;
 }
 // root: the element the funnel is drawn into. With it, every click on a button, link or option inside goes as $click (clicks.ts);
 // mount() passes its element. A thumbnail never tracks clicks.
@@ -190,6 +197,15 @@ function LiveFunnel({ funnel, track, root, browserBack }) {
     // server() sends the step on screen. Set while rendering, like onScreen: a step that calls its function in its own effect runs
     // that effect before any effect of the funnel would.
     visit.step = step.id;
+    // The placement of the step (placement.ts) and this view of it: a new id each time the step comes on screen (moving on to it,
+    // «Назад» to it), the same while it stays (a re-render). server() sends the placement's signed ctx, like the step.
+    const content = useMemo(() => placementOf(step), [step]);
+    const view = useRef({ step: '', id: '' });
+    if (view.current.step !== step.id)
+        view.current = { step: step.id, id: content ? crypto.randomUUID() : '' };
+    const viewId = view.current.id;
+    const pw = useMemo(() => (content ? { ...content, view_id: viewId } : null), [content, viewId]);
+    visit.placementCtx = content?.ctx ?? '';
     // A layout effect, not a plain one: the listener is on the root before the first paint, so a click right after the screen
     // appears is never missed (a plain effect can run after the browser has already delivered that click).
     useLayoutEffect(() => {
@@ -244,9 +260,32 @@ function LiveFunnel({ funnel, track, root, browserBack }) {
         if (!started.current) {
             started.current = true;
             track('$funnel_start');
-            exposeVariants(funnel.id, readBootstrap().variants, track);
+            startExposure(funnel.id, track);
+            // A hosted paywall's link the router did not take (not in the step placement's allowed_link_keys, a bad link token): the
+            // step shows its own placement; once per page.
+            const rej = readBootstrap().placement_rejected;
+            if (rej && typeof rej === 'object' && typeof rej.reason === 'string')
+                track('placement_rejected', { placement: String(rej.placement ?? ''), reason: rej.reason });
+            // The funnel is served at a url placement's address: the opening of the address is the placement's view (and the exposure of
+            // its experiment's arm), once per page load.
+            const u = readURLPlacement();
+            if (u) {
+                track('placement_viewed', { placement: u.placement, ...(u.experiment ? { experiment: u.experiment, arm: u.arm, phase: String(u.phase) } : {}),
+                    surface: 'web_funnel', view_id: crypto.randomUUID() });
+            }
         }
         track('$step_view', {}, step.id);
+        // A view of a placement (spec §5): when the step is on screen, whatever its layout has loaded; one per view (a re-render is the
+        // same view). Without content (paused, nothing published) it still is a view of the placement, without a paywall.
+        if (step.placement) {
+            track('placement_viewed', content
+                ? { placement: content.placement, paywall: content.paywall, paywall_version: String(content.version),
+                    ...(content.experiment ? { experiment: content.experiment, arm: content.arm, phase: String(content.phase) } : {}), surface: 'web_funnel', view_id: viewId }
+                : { placement: step.placement, surface: 'web_funnel' }, step.id);
+            if (content?.layout && !layoutOf(content.layout)) {
+                track('layout_missing', { placement: content.placement, paywall: content.paywall, paywall_version: String(content.version), layout: content.layout }, step.id);
+            }
+        }
         signals.current?.newView();
     }, [step.id]);
     const ctx = useMemo(() => {
@@ -285,8 +324,9 @@ function LiveFunnel({ funnel, track, root, browserBack }) {
                 backNav.current?.push(n);
             }
         };
-        const visible = funnel.steps.filter(s => !s.when || s.when(answers)).length;
-        const pos = funnel.steps.slice(0, index + 1).filter(s => !s.when || s.when(answers)).length;
+        const ab = currentAB();
+        const visible = funnel.steps.filter(s => !s.when || s.when(answers, ab)).length;
+        const pos = funnel.steps.slice(0, index + 1).filter(s => !s.when || s.when(answers, ab)).length;
         const funnelId = funnelSlug() || funnel.id;
         return {
             answers, set, track, stepId: step.id, index, total: visible, progress: visible ? pos / visible : 0, shot: false, stopTracking, creator,
@@ -302,8 +342,8 @@ function LiveFunnel({ funnel, track, root, browserBack }) {
             } },
         };
     }, [answers, index, step, funnel, track, creator]);
-    const C = step.component;
-    return _jsx(LabelCtx.Provider, { value: withLabel, children: _jsx(FunnelCtx.Provider, { value: ctx, children: _jsx(C, {}) }) });
+    const C = stepComponent(step, content);
+    return _jsx(LabelCtx.Provider, { value: withLabel, children: _jsx(FunnelCtx.Provider, { value: ctx, children: _jsx(PaywallCtx.Provider, { value: pw, children: _jsx(C, {}) }) }) });
 }
 let current = null;
 export function track(name, props) { current?.track(name, props); }
@@ -335,6 +375,7 @@ export function mount(funnel, el = document.getElementById('root')) {
     setContent(b.content ?? {}, b.content_overrides ?? {});
     const shot = shotRequest(location.search);
     visit.step = '';
+    visit.placementCtx = '';
     visit.session = () => '';
     visit.off = () => false;
     if (shot) {
@@ -426,7 +467,8 @@ function startsOnFirstStep(funnel) {
 export function landingContext(funnel) {
     const none = () => { };
     const step = funnel.steps[0];
-    const visible = funnel.steps.filter(s => !s.when || s.when({})).length;
+    const ab = currentAB();
+    const visible = funnel.steps.filter(s => !s.when || s.when({}, ab)).length;
     return { answers: {}, set: none, next: none, back: none, skip: none, track: none, stepId: step.id, index: 0, total: visible,
         progress: visible ? 1 / visible : 0, shot: false, stopTracking: async () => { }, creator: null, visitorId: '', funnelId: funnel.id,
         userId: '', knownUser: false };

package/dist/index.d.ts

@@ -5,10 +5,12 @@ export { t, param, setContent } from './content.js';
 export { experiment, useExperiment, rule, useRule } from './experiments.js';
 export { bucketOf, pickArm } from './bucket.js';
 export { readBootstrap, readCreator, type Bootstrap, type Creator } from './bootstrap.js';
+export { defineLayout, usePaywall, type Paywall, type PaywallProduct, type PlacementContent } from './placement.js';
 export { server, ServerFnError } from './server.js';
 export { autoOn, SERVICE_SIGNALS, type AutoTrack, type AutoTrackKey } from './autotrack.js';
 export { Tracker, safeProps, type FinalEvent, type StopScope } from './tracker.js';
 export { nextIndex, prevIndex, type StepDef, type StepRole, type Answers } from './nav.js';
+export type { AB } from './exposure.js';
 export { uuidv7 } from './uuid.js';
 export { Hero } from './blocks/Hero.js';
 export { Choice } from './blocks/Choice.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { t, param, setContent } from './content.js';
 export { experiment, useExperiment, rule, useRule } from './experiments.js';
 export { bucketOf, pickArm } from './bucket.js';
 export { readBootstrap, readCreator } from './bootstrap.js';
+export { defineLayout, usePaywall } from './placement.js';
 export { server, ServerFnError } from './server.js';
 export { autoOn, SERVICE_SIGNALS } from './autotrack.js';
 export { Tracker, safeProps } from './tracker.js';

package/dist/nav.d.ts

@@ -1,12 +1,14 @@
 import type { ComponentType } from 'react';
+import { type AB } from './exposure.js';
 export type Answers = Record<string, unknown>;
 export type StepRole = 'lead' | 'paywall' | 'landing';
 export declare const STEP_ROLES: readonly StepRole[];
 export type StepDef = {
     id: string;
     component: ComponentType;
-    when?: (a: Answers) => boolean;
+    when?: (a: Answers, ab: AB) => boolean;
     role?: StepRole;
+    placement?: string;
     sensitive?: boolean;
     sample?: {
         answers?: Answers;

package/dist/nav.js

@@ -1,5 +1,6 @@
+import { currentAB } from './exposure.js';
 export const STEP_ROLES = ['lead', 'paywall', 'landing'];
-const shown = (s, a) => !s.when || s.when(a);
+const shown = (s, a) => !s.when || s.when(a, currentAB());
 export function nextIndex(steps, a, from) {
     for (let i = from + 1; i < steps.length; i++)
         if (shown(steps[i], a))

package/dist/placement.d.ts

@@ -0,0 +1,58 @@
+import { type ComponentType } from 'react';
+import type { StepDef } from './nav.js';
+export declare const PLACEMENT_KEY: RegExp;
+export type PaywallProduct = {
+    key: string;
+    name: string;
+    kind: string;
+    period: string;
+    access_levels: string[];
+    phases: {
+        kind: string;
+        period?: string;
+    }[];
+    price: {
+        price_id: string;
+        currency: string;
+        amount: number;
+        interval: string;
+    } | null;
+    refs: {
+        provider: string;
+        ref_kind: string;
+        ref: string;
+    }[];
+};
+export type PlacementContent = {
+    placement: string;
+    paywall: string;
+    version: number;
+    experiment: string;
+    arm: string;
+    phase: number;
+    layout: string;
+    config: Record<string, unknown>;
+    products: PaywallProduct[];
+    subject: string;
+    ctx: string;
+};
+export type Paywall = Readonly<PlacementContent & {
+    view_id: string;
+}>;
+export declare function readPlacement(c: unknown): PlacementContent | null;
+export type URLPlacement = {
+    placement: string;
+    experiment: string;
+    arm: string;
+    phase: number;
+    subject: string;
+};
+export declare function readURLPlacement(): URLPlacement | null;
+export declare function placementOf(step: StepDef): PlacementContent | null;
+export declare function defineLayout<C extends ComponentType<any>>(key: string, component: C): C;
+export declare function layoutOf(key: string): ComponentType | undefined;
+export declare function clearLayouts(): void;
+export declare const PaywallCtx: import("react").Context<Readonly<PlacementContent & {
+    view_id: string;
+}> | null>;
+export declare function usePaywall(): Paywall | null;

package/dist/placement.js

@@ -0,0 +1,65 @@
+// Placements on a funnel step (kit 0.17.0; spec 2026-11-04-paywalls-placements §2.3–§2.4, §4.1, §5):
+//   defineStep({ id: 'paywall', role: 'paywall', placement: 'onboarding_paywall', component: Fallback })
+//   defineLayout('scholartobe_main', Paywall)
+//   const pw = usePaywall()
+// `funnel-kit build` writes the step's placement into the manifest; publishing a build whose step names a placement the project
+// does not have fails (placement_not_found). The router puts what the placement serves now into the bootstrap
+// (bootstrap.placements, by the step's placement key): a paywall version — its layout, JSON config and products with the
+// mirrored prices and the payment references. The step then draws the layout registered under that id (defineLayout), else its
+// own component: the placement serves nothing (paused, nothing published), or the layout is not in this build (layout_missing).
+// A view of a step with a placement sends placement_viewed (funnel.tsx).
+import { createContext, useContext } from 'react';
+import { readBootstrap } from './bootstrap.js';
+export const PLACEMENT_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+const LAYOUT_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// A bootstrap entry as content, or null when it is not one.
+export function readPlacement(c) {
+    if (!isObj(c) || typeof c.placement !== 'string' || !PLACEMENT_KEY.test(c.placement) || typeof c.paywall !== 'string')
+        return null;
+    return {
+        placement: c.placement, paywall: c.paywall, version: Number.isInteger(c.version) ? c.version : 0,
+        experiment: typeof c.experiment === 'string' ? c.experiment : '', arm: typeof c.arm === 'string' ? c.arm : '',
+        phase: Number.isInteger(c.phase) ? c.phase : 0, layout: typeof c.layout === 'string' ? c.layout : '', config: isObj(c.config) ? c.config : {},
+        products: Array.isArray(c.products) ? c.products.filter(isObj) : [],
+        subject: typeof c.subject === 'string' ? c.subject : '', ctx: typeof c.ctx === 'string' ? c.ctx : '',
+    };
+}
+export function readURLPlacement() {
+    const u = readBootstrap().placement_url;
+    if (!isObj(u) || typeof u.placement !== 'string' || !PLACEMENT_KEY.test(u.placement))
+        return null;
+    const experiment = typeof u.experiment === 'string' ? u.experiment : '';
+    const arm = experiment && typeof u.arm === 'string' ? u.arm : '';
+    return { placement: u.placement, experiment: arm ? experiment : '', arm, phase: Number.isInteger(u.phase) ? u.phase : 0,
+        subject: typeof u.subject === 'string' ? u.subject : '' };
+}
+// The content the bootstrap has for the step's placement, or null (no placement, nothing served, vite dev, an old router).
+export function placementOf(step) {
+    if (!step.placement)
+        return null;
+    const all = readBootstrap().placements;
+    return readPlacement(isObj(all) ? all[step.placement] : undefined);
+}
+const layouts = new Map();
+// defineLayout(key, Component): this build draws the paywall layout `key` (a paywall version's `layout`) with Component. Call it
+// at module level, next to the funnel; the same key again replaces it.
+export function defineLayout(key, component) {
+    if (!LAYOUT_KEY.test(key))
+        throw new Error(`defineLayout: bad layout key ${JSON.stringify(key)}: use ${LAYOUT_KEY.source}`);
+    if (typeof component !== 'function' && typeof component !== 'object')
+        throw new Error(`defineLayout('${key}'): not a component`);
+    layouts.set(key, component);
+    return component;
+}
+export function layoutOf(key) {
+    return key ? layouts.get(key) : undefined;
+}
+// For tests: forget the layouts.
+export function clearLayouts() { layouts.clear(); }
+export const PaywallCtx = createContext(null);
+// The placement of the step on screen with this view's id, or null: the step names no placement, it serves nothing now, outside
+// a funnel. Read texts and the highlighted plan from config, products and their prices from products.
+export function usePaywall() {
+    return useContext(PaywallCtx);
+}

package/dist/server.d.ts

@@ -2,6 +2,7 @@ export declare const visit: {
     step: string;
     session: () => string;
     off: () => boolean;
+    placementCtx: string;
 };
 export declare class ServerFnError extends Error {
     readonly status: number;

package/dist/server.js

@@ -8,7 +8,10 @@ const SESSION = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 // (mount() sets it). server() sends both, so the router's $fn_call and the function's ctx.track events join the person's
 // journey. Neither is a secret. Outside a mounted funnel, and in a thumbnail, both stay empty and nothing is sent.
 // off: stopTracking() was called; then neither is sent, so the router records no $fn_call for this visit.
-export const visit = { step: '', session: () => '', off: () => false };
+// placementCtx (kit 0.17.0): the router's signed ctx of the placement on screen (placement.ts); sent as X-Placement-Ctx, so a
+// function called from a hosted paywall opened by a link gets the link's placement (the router checks the signature).
+export const visit = { step: '', session: () => '', off: () => false, placementCtx: '' };
+const PLACEMENT_CTX = /^fsc1\.[A-Za-z0-9._-]{1,500}$/;
 function visitHeaders() {
     const out = {};
     let off = false;
@@ -29,6 +32,8 @@ function visitHeaders() {
     catch { /* storage blocked: the call goes without it */ }
     if (SESSION.test(session))
         out['X-Session'] = session;
+    if (PLACEMENT_CTX.test(visit.placementCtx))
+        out['X-Placement-Ctx'] = visit.placementCtx;
     return out;
 }
 // status 0 means the request never got an HTTP answer: 'bad_name' (not sent) or 'network' (fetch itself failed).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appright/funnelshift",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",