@appright/funnelshift 0.16.0 → 0.18.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,15 @@ export type Bootstrap = {
         lead_step?: string;
         checkout_step?: string;
     };
+    placements?: Record<string, PlacementContent>;
+    placement_rejected?: {
+        placement: string;
+        reason: string;
+    };
+    placement_url?: URLPlacement;
+    paywall_preview?: {
+        origin: string;
+    };
 };
 export declare function readBootstrap(win?: Window): Bootstrap;
 export declare function readCreator(win?: Window): Creator | null;

package/dist/cli/build.js

@@ -2,9 +2,9 @@ import { build } from 'vite';
 import react from '@vitejs/plugin-react';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { isBuiltin } from 'node:module';
-import { join, relative } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { extractContent, extractPrerender, extractSteps } from './extract.js';
+import { extractContent, extractLayouts, extractPrerender, extractSteps } from './extract.js';
 import { check, formatLint, formatWarnings } from './lint.js';
 // The source files under dir, without node_modules; noTests also leaves out *.test.* and *.spec.* (functions/ may keep its tests
 // next to the code, and they are not part of the bundle).
@@ -163,6 +163,14 @@ export async function buildFunnel(root, slug, info, opts = {}) {
     const content = extractContent(srcs);
     const steps = extractSteps(srcs);
     const prerender = extractPrerender(srcs);
+    // layouts and their schemas (kit 0.18.0): a schema imported from another file of the project (the hosted funnel's paywall reads
+    // the main funnel's) is read from the root, never from outside it or node_modules
+    const layouts = extractLayouts(srcs, p => {
+        const abs = resolve(root, p);
+        if (!abs.startsWith(resolve(root) + sep) || abs.split(sep).includes('node_modules') || !/\.(tsx?|jsx?)$/.test(abs) || !existsSync(abs) || !statSync(abs).isFile())
+            return null;
+        return read(abs);
+    });
     if (prerender && steps[0]?.role !== 'landing') {
         throw new Error(`funnels/${slug}: prerender: true draws the landing step into index.html, so the first step needs role: 'landing'`);
     }
@@ -193,6 +201,7 @@ export async function buildFunnel(root, slug, info, opts = {}) {
         writeFileSync(join(out, '_functions.js'), fn.code);
     writeFileSync(join(out, 'manifest.json'), JSON.stringify({
         funnel: slug, kit_version: kitVersion, built_at: new Date().toISOString(), commit: info.commit, branch: info.branch, steps, content,
+        ...(layouts.length ? { layouts } : {}),
         ...(prerender ? { prerender: true } : {}),
         ...(fn ? { functions: fn.names } : {}),
     }, null, 2));

package/dist/cli/extract.d.ts

@@ -1,3 +1,4 @@
+import { type LayoutSchema } from '../layout-schema.js';
 import { type StepRole } from '../nav.js';
 type Item = {
     key: string;
@@ -22,6 +23,7 @@ type Src = {
 export type ManifestStep = {
     id: string;
     role?: StepRole;
+    placement?: string;
     sensitive?: true;
     conditional?: true;
     when_keys?: string[];
@@ -29,4 +31,9 @@ export type ManifestStep = {
 export declare function whenKeys(fn: any): string[] | null;
 export declare function extractSteps(files: Src[]): ManifestStep[];
 export declare function extractPrerender(files: Src[]): boolean;
+export type ManifestLayout = {
+    key: string;
+    schema?: LayoutSchema;
+};
+export declare function extractLayouts(files: Src[], load?: (path: string) => Src | null): ManifestLayout[];
 export {};

package/dist/cli/extract.js

@@ -1,4 +1,6 @@
+import { posix } from 'node:path';
 import { parse } from '@babel/parser';
+import { layoutSchemaProblem } from '../layout-schema.js';
 import { STEP_ROLES } from '../nav.js';
 export function literal(n) {
     if (n?.type === 'StringLiteral')
@@ -58,18 +60,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 +117,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 +207,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) {
@@ -251,3 +269,161 @@ export function extractPrerender(files) {
     }
     return false;
 }
+const LAYOUT_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+const SOURCE_EXT = ['', '.tsx', '.ts', '.jsx', '.js', '/index.tsx', '/index.ts', '/index.jsx', '/index.js'];
+function scopeOf(f, program) {
+    const consts = new Map(), exported = new Map(), imports = new Map();
+    for (const st of program.body) {
+        if (st.type === 'ImportDeclaration' && st.importKind !== 'type') {
+            for (const sp of st.specifiers) {
+                if (sp.type !== 'ImportSpecifier')
+                    continue;
+                const name = sp.imported.type === 'Identifier' ? sp.imported.name : sp.imported.value;
+                imports.set(sp.local.name, { from: st.source.value, name });
+            }
+            continue;
+        }
+        if (st.type === 'ExportNamedDeclaration' && !st.declaration && !st.source) {
+            for (const sp of st.specifiers)
+                if (sp.type === 'ExportSpecifier')
+                    exported.set(sp.exported.type === 'Identifier' ? sp.exported.name : sp.exported.value, sp.local.name);
+            continue;
+        }
+        const d = st.type === 'ExportNamedDeclaration' ? st.declaration : st;
+        if (d?.type !== 'VariableDeclaration' || d.kind !== 'const')
+            continue;
+        for (const v of d.declarations) {
+            if (v.id?.type !== 'Identifier' || !v.init)
+                continue;
+            consts.set(v.id.name, v.init);
+            if (st.type === 'ExportNamedDeclaration')
+                exported.set(v.id.name, v.id.name);
+        }
+    }
+    return { f, consts, exported, imports };
+}
+// The paywall layouts of the funnel, read statically from every defineLayout('key', Component, schema?) of its code: the key as a
+// string literal and the schema (layout-schema.ts) as a literal — written in place, or a const of one in the same file, or imported
+// by name from another file of the project (`import { schema } from './paywall'`; load reads it, a path relative to the root).
+// Anything computed is an error with file:line, never a guess. The same key twice must carry the same schema (or one of them none).
+export function extractLayouts(files, load = () => null) {
+    const scopes = new Map();
+    const scopeFor = (f) => {
+        let s = scopes.get(f.path);
+        if (!s) {
+            s = scopeOf(f, parseSource(f).program);
+            scopes.set(f.path, s);
+        }
+        return s;
+    };
+    const fileAt = (path) => files.find(x => x.path === path) ?? load(path);
+    const resolveImport = (from, spec) => {
+        if (!spec.startsWith('.'))
+            return null;
+        const base = posix.normalize(posix.join(posix.dirname(from), spec));
+        for (const ext of SOURCE_EXT) {
+            const hit = fileAt(base + ext);
+            if (hit)
+                return hit;
+        }
+        return null;
+    };
+    const found = new Map();
+    for (const f of files) {
+        const program = parseSource(f).program;
+        const calls = [];
+        walk(program, n => { if (isCall(n, 'defineLayout'))
+            calls.push(n); });
+        if (!calls.length)
+            continue;
+        const scope = scopeFor(f);
+        for (const call of calls) {
+            const at = `${f.path}:${call.loc?.start.line}`;
+            const key = literal(unwrap(call.arguments[0]));
+            if (key === null || !LAYOUT_KEY.test(key)) {
+                throw new Error(`${at}: defineLayout() key must be a layout key as a string literal (${LAYOUT_KEY.source})`);
+            }
+            const arg = unwrap(call.arguments[2]);
+            let schema;
+            if (arg && !(arg.type === 'Identifier' && arg.name === 'undefined')) {
+                const seen = new Set();
+                // a literal value; identifiers are followed to a const of this file or a named import of another file of the project
+                const value = (n, s) => {
+                    n = unwrap(n);
+                    const where = `${s.f.path}:${n?.loc?.start.line ?? call.loc?.start.line}`;
+                    const notLiteral = (what) => new Error(`${where}: defineLayout('${key}') schema must be a literal — an object of strings, numbers, ` +
+                        `booleans, arrays and objects, written in place or as a const of one (in this file or imported by name) — but ${what}; ` +
+                        `funnel-kit build reads it without running the code`);
+                    switch (n?.type) {
+                        case 'StringLiteral':
+                        case 'NumericLiteral':
+                        case 'BooleanLiteral': return n.value;
+                        case 'NullLiteral': return null;
+                        case 'TemplateLiteral':
+                            if (n.expressions.length)
+                                throw notLiteral('a template string has ${…} in it');
+                            return n.quasis[0].value.cooked;
+                        case 'UnaryExpression':
+                            if (n.operator === '-' && n.argument?.type === 'NumericLiteral')
+                                return -n.argument.value;
+                            throw notLiteral(`it has the expression ${n.operator}…`);
+                        case 'ArrayExpression':
+                            return n.elements.map((el) => {
+                                if (!el || el.type === 'SpreadElement')
+                                    throw notLiteral('an array has a spread or a hole');
+                                return value(el, s);
+                            });
+                        case 'ObjectExpression': {
+                            const out = {};
+                            for (const p of n.properties) {
+                                if (p.type !== 'ObjectProperty')
+                                    throw notLiteral(p.type === 'SpreadElement' ? 'an object has a spread (...)' : 'an object has a method');
+                                const k = p.computed ? null : p.key.type === 'Identifier' ? p.key.name : literal(p.key) ?? (p.key.type === 'NumericLiteral' ? String(p.key.value) : null);
+                                if (k === null)
+                                    throw notLiteral('an object has a computed key');
+                                out[k] = value(p.value, s);
+                            }
+                            return out;
+                        }
+                        case 'Identifier': {
+                            const id = `${s.f.path}#${n.name}`;
+                            if (seen.has(id))
+                                throw notLiteral(`'${n.name}' refers to itself`);
+                            seen.add(id);
+                            const init = s.consts.get(n.name);
+                            if (init)
+                                return value(init, s);
+                            const imp = s.imports.get(n.name);
+                            if (imp) {
+                                const other = resolveImport(s.f.path, imp.from);
+                                if (!other)
+                                    throw notLiteral(`'${n.name}' is imported from '${imp.from}', which is not a file of the project funnel-kit reads`);
+                                const os = scopeFor(other);
+                                const local = os.exported.get(imp.name);
+                                const init2 = local ? os.consts.get(local) : undefined;
+                                if (!init2)
+                                    throw notLiteral(`'${imp.name}' of ${other.path} is not an exported const`);
+                                return value(init2, os);
+                            }
+                            throw notLiteral(`'${n.name}' is not a const of ${s.f.path} or a named import`);
+                        }
+                        default:
+                            throw notLiteral(`it is ${n?.type ?? 'missing'}`);
+                    }
+                };
+                const v = value(arg, scope);
+                const bad = layoutSchemaProblem(v);
+                if (bad)
+                    throw new Error(`${at}: defineLayout('${key}') schema: ${bad}`);
+                schema = v;
+            }
+            const prev = found.get(key);
+            if (prev && prev.schema && schema && JSON.stringify(prev.schema) !== JSON.stringify(schema)) {
+                throw new Error(`${at}: defineLayout('${key}') has another schema than at ${prev.at}; one layout has one schema`);
+            }
+            if (!prev || (!prev.schema && schema))
+                found.set(key, { schema, at });
+        }
+    }
+    return [...found.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([key, { schema }]) => (schema ? { key, schema } : { key }));
+}

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, paywallPreviewOrigin, placementOf, readPlacement, readURLPlacement, PREVIEW_MSG } from './placement.js';
 export const defineStep = (s) => s;
 export const defineFunnel = (f) => f;
 export const FunnelCtx = createContext(null);
@@ -146,8 +147,47 @@ 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 given = usePaywallPreview(step);
+    const content = useMemo(() => given?.content ?? placementOf(step), [step, given]);
+    const pw = useMemo(() => (content ? { ...content, view_id: '' } : null), [content]);
+    const C = stepComponent(step, content);
+    // a new content from the admin draws the layout anew (its own state — the chosen plan — starts from the config again)
+    return _jsx(FunnelCtx.Provider, { value: ctx, children: _jsx(PaywallCtx.Provider, { value: pw, children: _jsx("div", { className: "fk-shot", children: _jsx(C, {}) }, given?.seq ?? 0) }) });
+}
+// The admin's live preview of a paywall version (kit 0.18.0): a shot page the router marks (bootstrap.paywall_preview, only with
+// ?__pw=1, framed only by the admin) takes the content to draw from the admin's frame by postMessage — the layout, the config
+// being edited and the products with their mirrored prices — instead of what the step's placement serves. Only a message from the
+// parent frame on the admin's origin is read; the page says it is ready, and after each content whether this build draws that
+// layout. A shot is no visit: nothing is tracked or stored, the buttons do nothing.
+function usePaywallPreview(step) {
+    const [given, setGiven] = useState(null);
+    const origin = useMemo(() => paywallPreviewOrigin(), []);
+    useEffect(() => {
+        if (!origin)
+            return;
+        const on = (e) => {
+            if (e.origin !== origin || e.source !== window.parent)
+                return;
+            const d = e.data;
+            if (!d || d.type !== PREVIEW_MSG.content || !d.content || typeof d.content !== 'object')
+                return;
+            const c = readPlacement({ ...d.content, placement: step.placement ?? 'preview' });
+            if (c)
+                setGiven(g => ({ content: c, seq: (g?.seq ?? 0) + 1 }));
+        };
+        window.addEventListener('message', on);
+        window.parent.postMessage({ type: PREVIEW_MSG.ready, step: step.id }, origin);
+        return () => window.removeEventListener('message', on);
+    }, [origin, step]);
+    useEffect(() => {
+        if (origin && given)
+            window.parent.postMessage({ type: PREVIEW_MSG.shown, layout: given.content.layout, drawn: !!layoutOf(given.content.layout) }, origin);
+    }, [origin, given]);
+    return given;
+}
+// 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 +230,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 +293,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 +357,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 +375,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 +408,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 +500,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,13 @@ 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 type { LayoutField, LayoutSchema, LayoutText } from './layout-schema.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/layout-schema.d.ts

@@ -0,0 +1,42 @@
+export type LayoutText = string | {
+    ru?: string;
+    en?: string;
+};
+type FieldBase = {
+    label?: LayoutText;
+    hint?: LayoutText;
+    example?: string | number | boolean | string[];
+    required?: boolean;
+};
+type TextField = FieldBase & {
+    max?: number;
+    vars?: string[];
+};
+export type LayoutField = (TextField & {
+    type: 'string';
+}) | (TextField & {
+    type: 'text';
+}) | (TextField & {
+    type: 'list';
+    item_max?: number;
+}) | (FieldBase & {
+    type: 'product';
+}) | (FieldBase & {
+    type: 'flag';
+}) | (FieldBase & {
+    type: 'number';
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}) | (FieldBase & {
+    type: 'per_product';
+    fields: Record<string, LayoutField>;
+});
+export type LayoutSchema = {
+    fields: Record<string, LayoutField>;
+    vars?: Record<string, LayoutText>;
+};
+export declare const FIELD_TYPES: readonly ['string', 'text', 'list', 'product', 'flag', 'number', 'per_product'];
+export declare const SCHEMA_MAX_BYTES: number;
+export declare function layoutSchemaProblem(schema: unknown): string | null;
+export {};

package/dist/layout-schema.js

@@ -0,0 +1,105 @@
+// The schema of a paywall layout's config (kit 0.18.0): defineLayout('scholartobe_main', Paywall, schema). It tells the admin which
+// fields the layout reads from a paywall version's `config` — the form «Конфиг» of a version draws them, the server checks a new
+// version against them (a wrong type is an error, an unknown key a warning). `funnel-kit build` writes it into the manifest
+// statically (manifest.layouts), so it must be a literal: an object of strings, numbers, booleans, arrays and objects. No React here:
+// the CLI imports it.
+export const FIELD_TYPES = ['string', 'text', 'list', 'product', 'flag', 'number', 'per_product'];
+const FIELD_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+const VAR_NAME = /^[a-z][a-z0-9_]{0,31}$/;
+const MAX_FIELDS = 64;
+// the size of a schema in the manifest
+export const SCHEMA_MAX_BYTES = 16 << 10;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const isText = (v) => typeof v === 'string' || (isObj(v) && Object.keys(v).every(k => (k === 'ru' || k === 'en') && typeof v[k] === 'string'));
+const count = (v) => typeof v === 'number' && Number.isInteger(v) && v > 0;
+function fieldProblem(at, f, nested) {
+    if (!isObj(f))
+        return `${at}: a field is an object { type: '${FIELD_TYPES.join("' | '")}', label?, hint? }`;
+    const type = f.type;
+    if (typeof type !== 'string' || !FIELD_TYPES.includes(type)) {
+        return `${at}: type ${JSON.stringify(type)} is unknown; use one of ${FIELD_TYPES.join(', ')}`;
+    }
+    if (nested && type === 'per_product')
+        return `${at}: per_product fields cannot nest another per_product`;
+    const allowed = ['type', 'label', 'hint', 'example', 'required'];
+    if (type === 'string' || type === 'text' || type === 'list')
+        allowed.push('max', 'vars');
+    if (type === 'list')
+        allowed.push('item_max');
+    if (type === 'number')
+        allowed.push('min', 'max', 'integer');
+    if (type === 'per_product')
+        allowed.push('fields');
+    const extra = Object.keys(f).find(k => !allowed.includes(k));
+    if (extra)
+        return `${at}: ${type} field has no option ${extra} (it takes ${allowed.join(', ')})`;
+    if (f.label !== undefined && !isText(f.label))
+        return `${at}: label is a string or { ru, en }`;
+    if (f.hint !== undefined && !isText(f.hint))
+        return `${at}: hint is a string or { ru, en }`;
+    if (f.required !== undefined && typeof f.required !== 'boolean')
+        return `${at}: required is true or false`;
+    if (f.example !== undefined && !['string', 'number', 'boolean'].includes(typeof f.example) &&
+        !(Array.isArray(f.example) && f.example.every(x => typeof x === 'string')))
+        return `${at}: example is a string, a number, a boolean or a list of strings`;
+    if (type === 'number') {
+        for (const k of ['min', 'max'])
+            if (f[k] !== undefined && (typeof f[k] !== 'number' || !Number.isFinite(f[k])))
+                return `${at}: ${k} is a number`;
+        if (typeof f.min === 'number' && typeof f.max === 'number' && f.min > f.max)
+            return `${at}: min is more than max`;
+        if (f.integer !== undefined && typeof f.integer !== 'boolean')
+            return `${at}: integer is true or false`;
+    }
+    else if (f.max !== undefined && !count(f.max))
+        return `${at}: max is a whole number above 0`;
+    if (f.item_max !== undefined && !count(f.item_max))
+        return `${at}: item_max is a whole number above 0`;
+    if (f.vars !== undefined && !(Array.isArray(f.vars) && f.vars.every(v => typeof v === 'string' && VAR_NAME.test(v)))) {
+        return `${at}: vars is a list of substitution names (${VAR_NAME.source})`;
+    }
+    if (type === 'per_product')
+        return fieldsProblem(`${at}.fields`, f.fields, true);
+    return null;
+}
+function fieldsProblem(at, fields, nested) {
+    if (!isObj(fields))
+        return `${at}: fields is an object { <config key>: { type, … } }`;
+    const keys = Object.keys(fields);
+    if (keys.length === 0)
+        return `${at}: no fields`;
+    if (keys.length > MAX_FIELDS)
+        return `${at}: ${keys.length} fields, the limit is ${MAX_FIELDS}`;
+    for (const k of keys) {
+        if (!FIELD_KEY.test(k))
+            return `${at}: field key ${JSON.stringify(k)} must match ${FIELD_KEY.source}`;
+        const p = fieldProblem(`${at}.${k}`, fields[k], nested);
+        if (p)
+            return p;
+    }
+    return null;
+}
+// What is wrong with a schema, in words, or null. The same check runs in defineLayout and in `funnel-kit build`.
+export function layoutSchemaProblem(schema) {
+    if (!isObj(schema))
+        return 'the schema is an object { fields: { … }, vars?: { … } }';
+    const extra = Object.keys(schema).find(k => k !== 'fields' && k !== 'vars');
+    if (extra)
+        return `the schema has no option ${extra} (it takes fields and vars)`;
+    const p = fieldsProblem('fields', schema.fields, false);
+    if (p)
+        return p;
+    if (schema.vars !== undefined) {
+        if (!isObj(schema.vars))
+            return 'vars is an object { <name>: <what it is> }';
+        for (const [k, v] of Object.entries(schema.vars)) {
+            if (!VAR_NAME.test(k))
+                return `vars: name ${JSON.stringify(k)} must match ${VAR_NAME.source}`;
+            if (!isText(v))
+                return `vars.${k}: what it is — a string or { ru, en }`;
+        }
+    }
+    if (new TextEncoder().encode(JSON.stringify(schema)).length > SCHEMA_MAX_BYTES)
+        return `the schema is over ${SCHEMA_MAX_BYTES >> 10} KB`;
+    return null;
+}

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,66 @@
+import { type ComponentType } from 'react';
+import { type LayoutSchema } from './layout-schema.js';
+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, schema?: LayoutSchema): C;
+export declare function layoutSchemaOf(key: string): LayoutSchema | undefined;
+export declare function layoutOf(key: string): ComponentType | undefined;
+export declare function clearLayouts(): void;
+export declare const PREVIEW_MSG: {
+    readonly ready: 'funnelshift:paywall-ready';
+    readonly content: 'funnelshift:paywall';
+    readonly shown: 'funnelshift:paywall-shown';
+};
+export declare function paywallPreviewOrigin(): string | null;
+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,90 @@
+// Placements on a funnel step (kit 0.17.0, the layout's schema and the admin's live preview 0.18.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';
+import { layoutSchemaProblem } from './layout-schema.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();
+const schemas = new Map();
+// defineLayout(key, Component, schema?): 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. schema (kit 0.18.0, layout-schema.ts) — the fields
+// the layout reads from config: the admin draws a form of them and checks a version against them; `funnel-kit build` writes it
+// into the manifest, so write it as a literal (or a const of one, in this file or imported by name).
+export function defineLayout(key, component, schema) {
+    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`);
+    if (schema !== undefined) {
+        const bad = layoutSchemaProblem(schema);
+        if (bad)
+            throw new Error(`defineLayout('${key}'): bad schema: ${bad}`);
+        schemas.set(key, schema);
+    }
+    else
+        schemas.delete(key);
+    layouts.set(key, component);
+    return component;
+}
+// The schema defineLayout gave the layout, or undefined.
+export function layoutSchemaOf(key) {
+    return schemas.get(key);
+}
+export function layoutOf(key) {
+    return key ? layouts.get(key) : undefined;
+}
+// For tests: forget the layouts.
+export function clearLayouts() { layouts.clear(); schemas.clear(); }
+// The messages of the admin's live preview (funnel.tsx usePaywallPreview): the page says it is ready, the admin sends the content
+// to draw, the page says whether this build draws its layout.
+export const PREVIEW_MSG = { ready: 'funnelshift:paywall-ready', content: 'funnelshift:paywall', shown: 'funnelshift:paywall-shown' };
+const ORIGIN = /^https?:\/\/[a-z0-9.-]+(:[0-9]{1,5})?$/i;
+// The admin's origin when this page is its live preview of a paywall (bootstrap.paywall_preview, a shot page with ?__pw=1), else null.
+export function paywallPreviewOrigin() {
+    const o = readBootstrap().paywall_preview?.origin;
+    return typeof o === 'string' && ORIGIN.test(o) ? o : null;
+}
+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.18.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",