@appright/funnelshift 0.0.0-stage → 0.15.0

package/bin/funnel-kit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli/index.js'

package/dist/anchors.d.ts

@@ -0,0 +1,4 @@
+export declare function anchorTarget(hash: string): Element | 'top' | null;
+export declare function scrollToHash(hash: string, smooth?: boolean): boolean;
+export declare function installAnchors(root: HTMLElement): () => void;
+export declare function scrollToInitialHash(): () => void;

package/dist/anchors.js

@@ -0,0 +1,94 @@
+// In-page anchors (kit 0.13.0). The router puts <base href="/<project>/<funnel>/"> into the page, so a plain <a href="#pricing"> is
+// resolved against the funnel's root: the browser loads that address (a new page, the creator's path and the utm lost) instead of
+// scrolling. The kit takes such a click over: it scrolls to the element, and puts the hash in the address with replaceState (the
+// path and the query as they are; replace, not push, so the step history of backnav.ts stays as it is).
+//
+// Taken over: a plain left click on an <a> whose href starts with # inside the funnel, that nothing else has handled
+// (defaultPrevented), with no modifier key and no other target. An id that is not on the page still gets no navigation. Not in a frame:
+// the admin's preview must not touch the history.
+const IGNORE_TARGET = /^(?:_blank|_parent|_top)$/i;
+const reduced = () => {
+    try {
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    catch {
+        return false;
+    }
+};
+// The element a hash names: by id, else by the name of an old-style anchor; null for none. '#' and '#top' name the top of the page.
+export function anchorTarget(hash) {
+    if (hash === '' || hash === '#' || hash === '#top')
+        return 'top';
+    let id = hash.slice(1);
+    try {
+        id = decodeURIComponent(id);
+    }
+    catch { /* keep it as it is */ }
+    return document.getElementById(id) ?? document.getElementsByName(id)[0] ?? null;
+}
+// Smooth scroll (instant with prefers-reduced-motion) to the element; scroll-margin-top of the element is honoured by the browser.
+export function scrollToHash(hash, smooth = true) {
+    const t = anchorTarget(hash);
+    if (t === null)
+        return false;
+    const behavior = smooth && !reduced() ? 'smooth' : 'auto';
+    try {
+        if (t === 'top')
+            window.scrollTo({ top: 0, behavior });
+        else
+            t.scrollIntoView({ behavior, block: 'start' });
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+export function installAnchors(root) {
+    let framed = false;
+    try {
+        framed = window.self !== window.top;
+    }
+    catch {
+        framed = true;
+    }
+    const onClick = (e) => {
+        try {
+            if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+                return;
+            const from = e.target instanceof Element ? e.target : e.target instanceof Node ? e.target.parentElement : null;
+            const a = from?.closest('a');
+            if (!a || !root.contains(a) || a.hasAttribute('download'))
+                return;
+            const href = a.getAttribute('href');
+            if (href === null || !href.startsWith('#') || IGNORE_TARGET.test(a.getAttribute('target') ?? ''))
+                return;
+            e.preventDefault();
+            if (!scrollToHash(href))
+                return;
+            if (!framed && href.length > 1)
+                history.replaceState(history.state, '', location.pathname + location.search + href);
+        }
+        catch { /* a click must never break */ }
+    };
+    root.addEventListener('click', onClick);
+    return () => root.removeEventListener('click', onClick);
+}
+// The address came with a hash (a shared link to a section): once the step is drawn, scroll to it. The content may still be growing
+// (images, a client render after hydration), so it is tried again a moment later.
+export function scrollToInitialHash() {
+    let timers = [];
+    const hash = (() => { try {
+        return location.hash;
+    }
+    catch {
+        return '';
+    } })();
+    if (hash.length > 1) {
+        const go = () => { try {
+            scrollToHash(hash, false);
+        }
+        catch { /* ignore */ } };
+        timers = [setTimeout(go, 0), setTimeout(go, 400)];
+    }
+    return () => timers.forEach(clearTimeout);
+}

package/dist/answers.d.ts

@@ -0,0 +1,11 @@
+export declare const PROP_KEY: RegExp;
+export declare const MAX_VALUE = 1000;
+export declare const MAX_PROPS = 128;
+export declare const MAX_LIST = 50;
+export declare const MAX_EVENT_BYTES: number;
+export declare function cut(s: string, n?: number): {
+    text: string;
+    cut: boolean;
+};
+export declare function encodeAnswer(key: string, value: unknown, label?: unknown): Record<string, string>;
+export declare function packAnswers(answers: Record<string, string>[]): Record<string, string>[];

package/dist/answers.js

@@ -0,0 +1,100 @@
+import { readBootstrap } from './bootstrap.js';
+// How an answer becomes event props (spec "all events" §2.1). Every answer set() on a step goes into $step_complete:
+//   answer_<key>  the value, stable, what filters use;
+//   label_<key>   the text the person saw (only when set() was given one);
+//   answer_<key>_truncated = 'true' when the value was cut.
+// The same limits hold on the server: a prop name matches PROP_KEY, a value is at most MAX_VALUE characters, an event has at
+// most MAX_PROPS props.
+export const PROP_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+export const MAX_VALUE = 1000;
+export const MAX_PROPS = 128;
+export const MAX_LIST = 50;
+// One event's props stay under this many UTF-8 bytes (keys plus values), so the event fits a sendBeacon body (64 KB) and a
+// batch of the server (256 KB) with room to spare. 128 answers of 1000 multi-byte characters would be far bigger.
+export const MAX_EVENT_BYTES = 32 * 1024;
+const enc = new TextEncoder();
+const TRUNCATED = '_truncated';
+// cut keeps at most n characters (code points, the way the server counts them), so an emoji is never split in half.
+export function cut(s, n = MAX_VALUE) {
+    if (s.length <= n)
+        return { text: s, cut: false }; // UTF-16 length is never smaller than the code point count
+    const cps = Array.from(s);
+    return cps.length <= n ? { text: s, cut: false } : { text: cps.slice(0, n).join(''), cut: true };
+}
+function scalar(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint')
+        return String(v);
+    try {
+        return JSON.stringify(v) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+const item = (v) => scalar(v).replaceAll('|', '/');
+// A single answer's | becomes ¦ (broken bar): the analytics split a value on | into list elements, and one answer must
+// stay one value. List elements already turn their | into / (item); labels keep theirs (they are matched by position).
+function encodeValue(v) {
+    if (Array.isArray(v)) {
+        const r = cut(v.slice(0, MAX_LIST).map(item).join('|'));
+        return { text: r.text, cut: r.cut || v.length > MAX_LIST };
+    }
+    return cut(scalar(v).replaceAll('|', '¦'));
+}
+function encodeLabel(label, value) {
+    if (Array.isArray(label)) {
+        // Labels go with values by index: the label of value i is element i. A missing label in the middle stays an empty
+        // element (the ones after it keep their index); missing labels at the end are left out.
+        const n = Array.isArray(value) ? Math.min(value.length, MAX_LIST) : 1;
+        const parts = label.slice(0, n).map(l => (typeof l === 'string' ? l.replaceAll('|', '/') : ''));
+        while (parts.length && parts[parts.length - 1] === '')
+            parts.pop();
+        return cut(parts.join('|')).text;
+    }
+    return typeof label === 'string' ? cut(label).text : '';
+}
+// encodeAnswer: the props of one answer. A key that would give an invalid prop name, or ends in _truncated (that suffix is
+// the flag of a cut answer), gives nothing (a warning in preview and dev; the value is never printed).
+export function encodeAnswer(key, value, label) {
+    const name = 'answer_' + key;
+    if (!key || !PROP_KEY.test(name) || key.endsWith(TRUNCATED)) {
+        if (readBootstrap().env !== 'prod')
+            console.warn(`funnel-kit: answer key "${key.slice(0, 80)}" is not allowed (answer_ + key must match ${PROP_KEY} and not end in ${TRUNCATED}), not tracked`);
+        return {};
+    }
+    const v = encodeValue(value);
+    const out = { [name]: v.text };
+    const l = label === undefined ? '' : encodeLabel(label, value);
+    if (l)
+        out['label_' + key] = l;
+    // answer_<key>_truncated is longer than the answer name: for a key near the limit the flag would be an invalid prop
+    // (dropped by the tracker anyway), so it is only added when it fits.
+    if (v.cut && PROP_KEY.test(name + TRUNCATED))
+        out[name + TRUNCATED] = 'true';
+    return out;
+}
+// packAnswers: one event's props per element, at most MAX_PROPS props and MAX_EVENT_BYTES bytes each; the props of one
+// answer are never split between events (an answer bigger than the budget gets an event of its own). The first element goes
+// into $step_complete, the rest into $step_answers of the same step.
+export function packAnswers(answers) {
+    const out = [{}];
+    let n = 0;
+    let bytes = 0;
+    for (const a of answers) {
+        const size = Object.keys(a).length;
+        const b = Object.entries(a).reduce((t, [k, v]) => t + enc.encode(k).length + enc.encode(v).length, 0);
+        if (n > 0 && (n + size > MAX_PROPS || bytes + b > MAX_EVENT_BYTES)) {
+            out.push({});
+            n = 0;
+            bytes = 0;
+        }
+        Object.assign(out[out.length - 1], a);
+        n += size;
+        bytes += b;
+    }
+    return out;
+}

package/dist/attribution.d.ts

@@ -0,0 +1,34 @@
+export type Attribution = {
+    utm: Record<string, string>;
+    click_id_type: string;
+    click_id: string;
+    referrer_host: string;
+    referrer?: string;
+    landing_path: string;
+    landing_params: Record<string, string>;
+    path_segs: string[];
+    click_network: string;
+    creator: string;
+    channel: string;
+    entry_creator: string;
+    entry_channel: string;
+};
+export type AttributionOptions = {
+    project?: string;
+    funnel?: string;
+    local?: Storage;
+    now?: () => number;
+    mountPath?: string;
+    own?: boolean;
+};
+export declare const CREATOR_WINDOW_MS: number;
+export declare const MAX_PARAMS = 50;
+export declare const MAX_PARAM_KEY = 64;
+export declare const MAX_PARAM_VALUE = 500;
+export declare const MAX_PARAMS_BYTES = 6144;
+export declare const DROPPED_KEY = "$dropped";
+export declare const CLICK_IDS: readonly (readonly [string, string])[];
+export declare function pathSegments(pathname: string, project: string, funnel: string): string[];
+export declare function segmentsUnder(pathname: string, mountPath: string): string[];
+export declare function capParams(entries: Iterable<[string, string]>): Record<string, string>;
+export declare function attribution(loc?: Location, doc?: Document, store?: Storage, opts?: AttributionOptions): Attribution;

package/dist/attribution.js

@@ -0,0 +1,237 @@
+// The session's first landing, per project (af_entry:<project>): one tab may open funnels of several projects, and one
+// project must never send another's landing (stage review C1). kit 0.7.0; 0.6 kept a smaller record under af_attr.
+const KEY = 'af_entry:';
+const CREATOR_KEY = 'af_creator:';
+export const CREATOR_WINDOW_MS = 30 * 24 * 3600 * 1000;
+// A path segment: 1–64 of [A-Za-z0-9._-], kept lower-cased; anything else is dropped (spec §1.1).
+const SEG = /^[A-Za-z0-9._-]{1,64}$/;
+const MAX_SEGS = 16;
+export const MAX_PARAMS = 50;
+export const MAX_PARAM_KEY = 64;
+export const MAX_PARAM_VALUE = 500;
+// The params serialized as JSON stay within this many bytes (UTF-8); the rest are dropped, and their number goes as the param
+// $dropped. The server keeps the same cap.
+export const MAX_PARAMS_BYTES = 6144;
+export const DROPPED_KEY = '$dropped';
+// Codes the router serves as files of the build, never a creator (the server refuses them as cards too).
+const RESERVED_CODES = new Set(['.', '..', 'assets', 'index.html', '_functions.js']);
+const UTM_KEYS = ['source', 'medium', 'campaign', 'content', 'term'];
+// The ad networks by their click id (spec §1.4), in this order of preference. click_id_type is the param's name, lower-cased.
+export const CLICK_IDS = [
+    ['fbclid', 'meta'], ['gclid', 'google'], ['gbraid', 'google'], ['wbraid', 'google'], ['ttclid', 'tiktok'], ['msclkid', 'microsoft'],
+    ['twclid', 'x'], ['li_fat_id', 'linkedin'], ['sccid', 'snapchat'], ['ScCid', 'snapchat'], ['epik', 'pinterest'], ['rdt_cid', 'reddit'],
+    ['yclid', 'yandex'],
+];
+const chars = (s) => [...s];
+const cutTo = (s, n) => (s.length <= n ? s : chars(s).slice(0, n).join(''));
+function get(s, k) { try {
+    return s?.getItem(k) ?? null;
+}
+catch {
+    return null;
+} }
+function put(s, k, v) { try {
+    s?.setItem(k, v);
+}
+catch { /* storage unavailable: this page only */ } }
+// The valid segments of the path after /<project>/<funnel>/, lower-cased; a segment that does not fit is dropped and the rest
+// keep their order. A path outside the funnel (vite dev) has none.
+export function pathSegments(pathname, project, funnel) {
+    const prefix = `/${project}/${funnel}`;
+    if (!project || !funnel || (pathname !== prefix && !pathname.startsWith(prefix + '/')))
+        return [];
+    const out = [];
+    for (const raw of pathname.slice(prefix.length).split('/')) {
+        if (!raw || out.length >= MAX_SEGS)
+            continue;
+        let s;
+        try {
+            s = decodeURIComponent(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!SEG.test(s) || s.toLowerCase() === 'index.html')
+            continue;
+        out.push(s.toLowerCase());
+    }
+    return out;
+}
+// The same under any mount: the valid segments of the path after mountPath ("/" or "/<something>/").
+export function segmentsUnder(pathname, mountPath) {
+    const prefix = mountPath.replace(/\/+$/, '');
+    if (pathname !== prefix && !pathname.startsWith(prefix + '/'))
+        return [];
+    const out = [];
+    for (const raw of pathname.slice(prefix.length).split('/')) {
+        if (!raw || out.length >= MAX_SEGS)
+            continue;
+        let s;
+        try {
+            s = decodeURIComponent(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!SEG.test(s) || s.toLowerCase() === 'index.html')
+            continue;
+        out.push(s.toLowerCase());
+    }
+    return out;
+}
+const seg = (v) => (v && SEG.test(v) ? v.toLowerCase() : '');
+// The Meta cookies _fbp and _fbc (kit 0.11.0): first-touch fields for a later conversions API call (no CAPI yet). They are kept as
+// the landing params fbp and fbc, unless the link already carries params of those names.
+const META_COOKIES = [['_fbp', 'fbp'], ['_fbc', 'fbc']];
+function metaCookies(doc) {
+    let jar = '';
+    try {
+        jar = doc.cookie;
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const [cookie, key] of META_COOKIES) {
+        const m = new RegExp(`(?:^|;\\s*)${cookie}=([^;]*)`).exec(jar);
+        let v = '';
+        try {
+            v = m ? decodeURIComponent(m[1]) : '';
+        }
+        catch {
+            v = m?.[1] ?? '';
+        }
+        if (v && !v.includes('@') && chars(v).length <= 128)
+            out.push([key, v]);
+    }
+    return out;
+}
+const bytes = (s) => new TextEncoder().encode(s).length;
+// capParams keeps params in their order while they fit MAX_PARAMS keys and MAX_PARAMS_BYTES serialized; the number of those
+// that did not fit (plus an earlier count in $dropped) goes as $dropped, which takes one of the keys.
+export function capParams(entries) {
+    const out = {};
+    let size = 2, n = 0, dropped = 0;
+    const reserve = bytes(`,"${DROPPED_KEY}":"999999"`);
+    for (const [k, v] of entries) {
+        if (k === DROPPED_KEY) {
+            const d = Number(v);
+            if (Number.isInteger(d) && d > 0 && d < 1e6)
+                dropped += d;
+            continue;
+        }
+        const add = bytes(JSON.stringify(k)) + bytes(JSON.stringify(v)) + 2;
+        if (n >= MAX_PARAMS || size + add > MAX_PARAMS_BYTES - reserve) {
+            dropped++;
+            continue;
+        }
+        out[k] = v;
+        size += add;
+        n++;
+    }
+    if (dropped > 0) {
+        if (n >= MAX_PARAMS) {
+            delete out[Object.keys(out)[n - 1]];
+            dropped++;
+        }
+        out[DROPPED_KEY] = String(Math.min(dropped, 999999));
+    }
+    return out;
+}
+function entryOf(loc, doc, project, funnel, mountPath) {
+    const q = new URLSearchParams(loc.search);
+    const seen = new Set();
+    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))
+            continue;
+        seen.add(k);
+        fit.push([k, cutTo(v, MAX_PARAM_VALUE)]);
+    }
+    for (const [k, v] of metaCookies(doc))
+        if (!seen.has(k))
+            fit.push([k, v]);
+    const params = capParams(fit);
+    const utm = {};
+    for (const k of UTM_KEYS) {
+        const v = q.get('utm_' + k) || q.get(k);
+        if (v)
+            utm[k] = cutTo(v, 128);
+    }
+    const click = CLICK_IDS.find(([p]) => q.get(p));
+    let ref = '', referrer = '';
+    try {
+        const u = new URL(doc.referrer);
+        if (u.hostname !== loc.hostname) {
+            ref = u.hostname;
+            referrer = /^(https?|android-app):$/.test(u.protocol) ? cutTo(`${u.protocol}//${u.hostname}${u.pathname}`, 1024) : '';
+        }
+    }
+    catch { /* no referrer */ }
+    const segs = mountPath ? segmentsUnder(loc.pathname, mountPath) : pathSegments(loc.pathname, project, funnel);
+    const creator = segs[0] && !RESERVED_CODES.has(segs[0]) ? segs[0] : '';
+    // …/creator1/tiktok and …/creator1?source=tiktok say the same: without a second segment the link's source is the channel.
+    const channel = creator ? segs[1] ?? seg(utm.source) : '';
+    return {
+        utm, click_id_type: click ? click[0].toLowerCase() : '', click_id: click ? cutTo(q.get(click[0]), 256) : '', referrer_host: ref, referrer,
+        landing_path: cutTo(loc.pathname, 512), landing_params: params, path_segs: segs, click_network: click ? click[1] : '',
+        entry_creator: creator, entry_channel: channel,
+    };
+}
+// The attribution of this page load. store keeps the session's first landing (sessionStorage), opts.local the project's creator
+// (localStorage). Storage that is blocked or full makes it this page's only; it never throws.
+export function attribution(loc = location, doc = document, store = sessionStorage, opts = {}) {
+    const project = opts.project ?? '', funnel = opts.funnel ?? '';
+    const now = (opts.now ?? Date.now)();
+    let local = opts.local;
+    if (local === undefined) {
+        try {
+            local = localStorage;
+        }
+        catch {
+            local = undefined;
+        }
+    }
+    const here = entryOf(loc, doc, project, funnel, opts.mountPath);
+    const key = KEY + project;
+    let entry = null;
+    try {
+        entry = JSON.parse(get(store, key) ?? 'null');
+    }
+    catch { /* corrupt: a new one */ }
+    // A stored landing must be this project's: one under another project's path is never sent (and is replaced).
+    const mine = (e) => !project || opts.own || (typeof e.landing_path === 'string' && e.landing_path.startsWith(`/${project}/`));
+    if (!entry || typeof entry !== 'object' || !Array.isArray(entry.path_segs) || !mine(entry)) {
+        entry = here;
+        put(store, key, JSON.stringify(entry));
+    }
+    // The Meta cookies often appear only after the landing (the pixel sets them): the first landing of the session takes them in
+    // when they show up later, so the first touch has them.
+    const late = metaCookies(doc).filter(([k]) => !(k in entry.landing_params));
+    if (late.length) {
+        entry = { ...entry, landing_params: capParams([...Object.entries(entry.landing_params), ...late]) };
+        put(store, key, JSON.stringify(entry));
+    }
+    // The creator: this page's link when it has one (last click), otherwise the project's within the window.
+    const ckey = CREATOR_KEY + project;
+    let creator = '', channel = '';
+    if (here.entry_creator) {
+        creator = here.entry_creator;
+        channel = here.entry_channel;
+        if (project)
+            put(local, ckey, JSON.stringify({ c: creator, ch: channel, at: now }));
+    }
+    else if (project) {
+        try {
+            const saved = JSON.parse(get(local, ckey) ?? 'null');
+            if (saved && typeof saved.c === 'string' && typeof saved.at === 'number' && now - saved.at <= CREATOR_WINDOW_MS) {
+                creator = seg(saved.c);
+                channel = creator ? seg(typeof saved.ch === 'string' ? saved.ch : '') : '';
+            }
+        }
+        catch { /* corrupt: none */ }
+    }
+    return { ...entry, creator, channel };
+}

package/dist/autotrack.d.ts

@@ -0,0 +1,4 @@
+export type AutoTrackKey = 'scroll' | 'sections' | 'perf' | 'errors' | 'activeTime' | 'fieldErrors' | 'network';
+export type AutoTrack = boolean | Partial<Record<AutoTrackKey, boolean>>;
+export declare function autoOn(a: AutoTrack | undefined, key: AutoTrackKey): boolean;
+export declare const SERVICE_SIGNALS: readonly ['$scroll', '$section_view', '$perf', '$error', '$field_error'];

package/dist/autotrack.js

@@ -0,0 +1,13 @@
+export function autoOn(a, key) {
+    if (a === undefined || a === true)
+        return true;
+    if (a === false)
+        return false;
+    return a[key] !== false;
+}
+// The names of the service signals: events the kit sends by itself about how a page behaved, not what a person did in the funnel
+// (kit 0.13.0). They live in the raw events and in their own small rollups; the analytics pre-aggregation (sessions, step and
+// funnel counts) must ignore them, so a new signal never makes the hot path heavier. Their volume is bounded: $scroll at most 4
+// per step view, $section_view once per section and view (20 at most), $perf once per page load, $error 5 per page load,
+// $field_error 20 per step view. The same list in Go: server/internal/event ServiceSignals (a Go test keeps the two equal).
+export const SERVICE_SIGNALS = ['$scroll', '$section_view', '$perf', '$error', '$field_error'];

package/dist/backnav.d.ts

@@ -0,0 +1,15 @@
+export type BackNavOptions = {
+    index: () => number;
+    stepId: (index: number) => string;
+    prev: () => number | null;
+    next: () => number | null;
+    reached: () => number;
+    back: (p: number) => void;
+    forward: (n: number) => void;
+};
+export type BackNav = {
+    push: (index: number) => void;
+    syncBack: () => void;
+    off: () => void;
+};
+export declare function installBackNav(o: BackNavOptions): BackNav;

package/dist/backnav.js

@@ -0,0 +1,73 @@
+// The browser's Back (kit 0.13.0): a phone's swipe or back button, the browser's own, moves the funnel one step back instead of
+// leaving the page for Instagram or Google. Every step the funnel moves on to (next, skip) gets a history entry of its own
+// (pushState without a URL: the address, its query and hash stay as they are); Back lands on the entry of the step before, and the
+// kit shows that step the way the funnel's own back() does, respecting `when`. The first step gets no entry: Back from it leaves
+// the page as it always did (no trap). Forward goes on only to a step already visited in this page load, else it is undone.
+// A popstate without our state (an anchor's hash, another script's entry) is not ours and is left alone.
+//
+// The state is { funnelStep, idx, pos }: pos counts our entries, so the direction of a move is known whatever the steps say.
+// After a reload the entries of the old page load stay behind the current one with their old pos; Back through them is passed on
+// (history.back()) until it leaves the page, so a reload never makes the funnel a trap either.
+const ours = (s) => !!s && typeof s === 'object' && typeof s.funnelStep === 'string'
+    && Number.isInteger(s.pos) && Number.isInteger(s.idx);
+export function installBackNav(o) {
+    let pos = 0;
+    try {
+        const s = history.state;
+        if (ours(s))
+            pos = s.pos;
+    }
+    catch { /* no history */ }
+    const state = (index) => ({ funnelStep: o.stepId(index), idx: index, pos });
+    // The entry the page opened with stands for the step on screen, so a Back that lands on it is ours.
+    try {
+        history.replaceState(state(o.index()), '');
+    }
+    catch { /* a sandboxed frame: no history to use */ }
+    const onPop = (e) => {
+        try {
+            const s = e.state;
+            if (!ours(s) || s.pos === pos)
+                return;
+            if (s.pos < pos) {
+                const p = o.prev();
+                pos = s.pos;
+                if (p === null) {
+                    history.back();
+                    return;
+                } // an entry of an earlier page load behind the first step: on to the exit
+                o.back(p);
+            }
+            else {
+                const n = o.next();
+                if (n !== null && n <= o.reached()) {
+                    pos = s.pos;
+                    o.forward(n);
+                }
+                else
+                    history.go(pos - s.pos);
+            }
+        }
+        catch { /* the funnel must work without it */ }
+    };
+    addEventListener('popstate', onPop);
+    return {
+        push(index) {
+            try {
+                pos += 1;
+                history.pushState(state(index), '');
+            }
+            catch { /* no history to use */ }
+        },
+        syncBack() {
+            try {
+                if (pos > 0) {
+                    pos -= 1;
+                    history.go(-1);
+                }
+            }
+            catch { /* no history to use */ }
+        },
+        off() { removeEventListener('popstate', onPop); },
+    };
+}

package/dist/blocks/Choice.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+export type PickHandlers<V, L> = {
+    onChange: (v: V) => void;
+    onPick?: (v: V, label: L) => void;
+} | {
+    onChange?: (v: V) => void;
+    onPick: (v: V, label: L) => void;
+};
+export declare function Choice<T extends string>(p: {
+    options: {
+        value: T;
+        label: string;
+        icon?: ReactNode;
+    }[];
+    value?: T;
+    name: string;
+    labelledBy?: string;
+    label?: string;
+} & PickHandlers<T, string>): import("react").JSX.Element;

package/dist/blocks/Choice.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useRef } from 'react';
+import { LabelCtx } from '../offer.js';
+export function Choice(p) {
+    const refs = useRef([]);
+    const withLabel = useContext(LabelCtx);
+    const pick = (i) => {
+        const o = p.options[i];
+        p.onPick?.(o.value, o.label);
+        withLabel(o.value, o.label, () => p.onChange?.(o.value));
+    };
+    const chosen = p.options.findIndex(o => o.value === p.value);
+    const stop = chosen >= 0 ? chosen : 0;
+    function onKeyDown(e, i) {
+        const n = p.options.length;
+        // Alt+Arrow is "back/forward" in browsers, Cmd/Ctrl+Arrow is an OS or browser shortcut: arrows with them are left alone.
+        const plain = !e.altKey && !e.metaKey && !e.ctrlKey;
+        let to = -1;
+        if (plain && (e.key === 'ArrowDown' || e.key === 'ArrowRight'))
+            to = (i + 1) % n;
+        else if (plain && (e.key === 'ArrowUp' || e.key === 'ArrowLeft'))
+            to = (i - 1 + n) % n;
+        else if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            pick(i);
+            return;
+        }
+        else
+            return;
+        e.preventDefault();
+        pick(to);
+        refs.current[to]?.focus();
+    }
+    return (_jsxs("div", { className: "fk-choice", role: "radiogroup", "aria-labelledby": p.labelledBy, "aria-label": p.label, children: [p.value !== undefined && _jsx("input", { type: "hidden", name: p.name, value: p.value }), p.options.map((o, i) => {
+                const on = i === chosen;
+                return (_jsxs("button", { ref: el => { refs.current[i] = el; }, type: "button", role: "radio", "aria-checked": on, tabIndex: i === stop ? 0 : -1, className: "fk-choice__option", onClick: () => pick(i), onKeyDown: e => onKeyDown(e, i), children: [o.icon != null && _jsx("span", { className: "fk-choice__icon", "aria-hidden": "true", children: o.icon }), _jsx("span", { className: "fk-choice__label", children: o.label }), _jsx("span", { className: "fk-choice__mark", "aria-hidden": "true" })] }, o.value));
+            })] }));
+}

package/dist/blocks/Cta.d.ts

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react';
+export declare function Cta(p: {
+    children: ReactNode;
+    onClick: () => void;
+    pending?: boolean;
+    disabled?: boolean;
+}): import("react").JSX.Element;