@evinvest/kitstart 0.14.0 → 0.16.0

package/README.md

@@ -45,7 +45,7 @@ brand's `flake.nix` is its own config plus one call — `template/flake.nix` is
 the whole of one:
 
 ```nix
-inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.14.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.16.0"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -122,7 +122,7 @@ the two must be one release. Pin the flake to the matching
 Structural only — where behaviour matters more than look. Marketing sections
 (hero, prices, reviews…) stay in the brand until two brands hold the same one.
 Each widget is a Server Component unless it needs the browser (`MapFacade`,
-`AnalyticsBoundary`, `FormSelect`), styled with the kit's token roles only, restyled through
+`AnalyticsBoundary`, `FormSelect`, `AbSwitcher`), styled with the kit's token roles only, restyled through
 `className` — and, where a brand needs geometry inside one (`Faq`, `CallBar`,
 `StatusScreen`, `PlaceDirectory`, `Coverage`), through its named parts:
 `classNames={{ list: "rounded-none", answer: "px-2" }}`, merged after the
@@ -166,6 +166,7 @@ which CI runs: `npm run check:template -- --e2e`).
 |---|---|
 | `name`, `options: { value, label }[]` | the posted field and its choices (labels are text) |
 | `defaultValue` | without it: empty under a `placeholder`, else the first option — the native rule |
+| `value` | controlled: shown and posted until the parent changes it from `onValueChange`; `""` is the placeholder, `undefined` uncontrolled |
 | `placeholder` | an empty, unpickable choice shown until one is made |
 | `required`, `disabled` | as on a `<select>`: required refuses the submit, disabled posts nothing |
 | `size` | `sm` · `md` · `lg` (the landing's) — the kit's form scale |
@@ -175,7 +176,7 @@ which CI runs: `npm run check:template -- --e2e`).
 
 - **The value survives the swap.** A choice made in the native select before
   the script arrived is read in the hydration commit; a form `reset` puts the
-  default back in both states. With nothing chosen (under a `placeholder`) it
+  default back in both states (uncontrolled; under `value`, see below). With nothing chosen (under a `placeholder`) it
   posts nothing, as a native select on its disabled placeholder does.
 - **`required` still refuses the submit.** A `type="hidden"` input is never
   validated, so under `required` the value rides in a transparent input under
@@ -192,6 +193,19 @@ which CI runs: `npm run check:template -- --e2e`).
 - **Weight.** It is a client module and pulls the kit's `Select` into the
   page: 3.8 KB gz of first-load JS on the template's place page (152,774 →
   156,565 B of its 158,000 B budget).
+- **Controlled, as an `<input>`.** Under `value` the prop is the value: a
+  pick only calls `onValueChange`, and the parent's state (or a reset of its
+  own, `setSubject("")` back to the placeholder) is what moves it. A form
+  `reset` leaves it on `value` — clear the parent's state from the form's
+  `onReset` if it should follow. Without JavaScript it is still the native
+  select, starting on `value`; a pick made there before hydration is reported
+  through `onValueChange`. Switching between `value` and `undefined` warns
+  once in development, as React does for an input, and keeps the last value.
+
+```tsx
+const [subject, setSubject] = useState<string>(LEAD.subjects[0]);
+<FormSelect name={LEAD.wire.subject} size="lg" value={subject} onValueChange={setSubject} options={subjects} />
+```
 
 ### `LeadCapture`: the lead form every brand shares
 
@@ -335,7 +349,9 @@ it is the plain POST to `/quote` it always was.
   (`contact` / `need` in `qualify-first`; in `steps` each screen moved to —
   `intro`, `need`, `estimate_<input>`, `locality`, `phone`), each with `form_id`, `layout`, `experiment`,
   `variant`; `contact_intent_click {channel}` for `phone`, `whatsapp`, `sms`,
-  `callback`, with the experiment; and on the server `lead_form_submit
+  `callback`, with the experiment (and `forced: true` on a test visit, as
+  `location_page_view`, when the boundary has `qaCookie` — see `AbSwitcher`);
+  and on the server `lead_form_submit
   {form_id, channel}` and `lead_form_reject {form_id, channel, field,
   reason}` with the posted experiment.
 - **Weight.** 8.9 KB gz of first-load JS on the template's place page
@@ -837,8 +853,9 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
 
 ## Experiments from the panel
 
-The experiments live in code (`@evinvest/experiments`, one `as const` config);
-the panel decides their weights and kill switch, and PostHog counts them.
+The experiments live in code (`@evinvest/experiments`, one `as const` config
+of variants, split equally); the panel decides any other weights and the kill
+switch, and PostHog counts them.
 
 **Overrides** (`createExperimentsSource`): `GET <base>/experiments`, the same
 base as the place source, `{ "experiments": { "<key>": { enabled?, weights?,
@@ -862,7 +879,8 @@ declared length, holdout in `[0, 1)`) is `applyOverrides`' call.
 
 **Declaration** (`declareExperiments`): at every start the landing tells the
 panel which experiments this build runs — `experiments.declared@1`, one event
-with every experiment's key, variants, weights, `enabled`, `holdout` and an
+with every experiment's key, variants, weights (always one each — the code's
+equal split), `enabled`, `holdout` and an
 optional one-line `summary`, under a fresh UUIDv7. It goes through the lead
 webhook's outbox, signed and retried like a lead (so it needs the same
 `LEAD_WEBHOOK_URL` and sqlite lead store), and the panel keeps the latest by
@@ -879,10 +897,60 @@ export async function register() {
 It never throws and never holds the start: no webhook, one that cannot be
 built, or a queue that refuses the row is logged and skipped — the panel keeps
 the last declaration. An experiment the panel would refuse (key not
-`[a-z0-9_]{1,64}`, fewer than two unique slug variants, weights not one per
-variant, negative or summing to zero, holdout outside `[0, 1)`, summary over
+`[a-z0-9_]{1,64}`, fewer than two unique slug variants, holdout outside
+`[0, 1)`, summary over
 200 characters) is left out and logged, since the panel judges the event whole.
 
+### The QA switcher: `AbSwitcher`
+
+A chip in a corner that switches an experiment's variant in one tap — for the
+owner on a phone, in production. It drives the brand proxy's own mechanism and
+adds no server path: a tap on a variant goes to the same URL with
+`?ab_<key>=<value>`, which forces it and sets the QA cookie.
+
+```tsx
+// app/[locale]/[location]/layout.tsx — a server layout; the props are plain data
+<AbSwitcher
+  experiments={[{ key: "lead_form", label: "Lead form", variants: [{ value: "a", label: "Compact" }, { value: "b", label: "Steps" }] }]}
+  qaCookie="ab__qa"              // the cookie the brand's force parameter sets
+  className="bottom-20 md:bottom-4" // over the brand's sticky bars; bottom-right by default
+/>
+```
+
+- `current` — the assignments, if the caller knows them; left out, the panel
+  reads `ab_<key>` from `document.cookie` (the normal case: the page stays
+  static, the server reads no cookie). `forceParam` — `ab_` by default.
+  `text` — the menu's words, English by default.
+- **Turning it on, on a phone, in production:** open any page with
+  `?ab_<key>=<value>`. The proxy sets the QA cookie and the chip appears;
+  every visit after is tagged as a test in analytics. Outside production
+  (`next dev`) the chip is always there.
+- **What a visitor pays:** ~190 B gz of first load on the template's place
+  page. After hydration the gate checks `NODE_ENV` and the QA cookie
+  (non-empty) and only then imports the panel — a chunk of its own, ~2.1 KB
+  gz, that a visitor without the cookie never requests. The panel is the
+  kit's `Button` and `Badge` over its own small layer, not `Popover`: sharing
+  the overlay primitives with the page made Turbopack re-split the page's
+  chunks, ~400 B gz more for every visitor.
+- **Reset** drops the experiments' assignment cookies (`ab_<key>`) and the
+  force parameters from the URL, then reloads: the variants are drawn again
+  and the visit stays a test, menu included. **Leave test** drops the QA cookie
+  too. **Minimize** and **Hide** last until the next load.
+- Screenshots: the chip and its panel carry `data-ab-switcher`; hide it in the
+  section stylesheet, `[data-ab-switcher] { display: none !important; }`.
+- **Pass the same `qaCookie` to `AnalyticsBoundary`.** Every tap in the menu
+  is a full reload, so a test visit would add page views to the place's
+  traffic; with the cookie set, the boundary's `location_page_view` and
+  `contact_intent_click` carry `forced: true`. Without the prop, or without
+  the cookie, the events are as before — no `forced` key at all.
+
+  ```tsx
+  <AnalyticsBoundary target={target} placeSlug={slug} qaCookie="ab__qa">
+  ```
+
+The decisions are plain functions in the core (`abSwitcherVisible`,
+`abVariantUrl`, `abReset`, `abAssignments`), for a brand's own tests.
+
 ## The site
 
 ```ts

package/dist/core/ab-gate.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The QA switcher's one decision a visitor pays for, apart from the rest
+ * (`ab-switcher.ts`) so the gate's bundle carries this function and nothing
+ * else: the panel's helpers arrive with the panel.
+ */
+/**
+ * Whether the switcher shows: always outside production, and in production
+ * only to a visit carrying the QA cookie with a value — the cookie the brand's
+ * force parameter sets, so nobody else ever downloads the panel.
+ */
+export declare function abSwitcherVisible(cookies: string, qaCookie: string, nodeEnv: string | undefined): boolean;

package/dist/core/ab-gate.js

@@ -0,0 +1,19 @@
+/**
+ * The QA switcher's one decision a visitor pays for, apart from the rest
+ * (`ab-switcher.ts`) so the gate's bundle carries this function and nothing
+ * else: the panel's helpers arrive with the panel.
+ */
+/**
+ * Whether the switcher shows: always outside production, and in production
+ * only to a visit carrying the QA cookie with a value — the cookie the brand's
+ * force parameter sets, so nobody else ever downloads the panel.
+ */
+export function abSwitcherVisible(cookies, qaCookie, nodeEnv) {
+    if (nodeEnv !== "production")
+        return true;
+    // Presence and non-empty only, no decoding: every visitor runs this.
+    return cookies.split(";").some(pair => {
+        const eq = pair.indexOf("=");
+        return eq > 0 && pair.slice(0, eq).trim() === qaCookie && pair.slice(eq + 1).trim() !== "";
+    });
+}

package/dist/core/ab-switcher.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The QA switcher's decisions, as plain functions over strings: what the
+ * cookies assign, where a variant's tap leads, what a reset clears — whether
+ * the menu shows at all is `ab-gate.ts`. The lazy panel only applies them to
+ * `document.cookie` and `location`.
+ *
+ * The mechanism is the brand proxy's, unchanged: it keeps an assignment in a
+ * cookie `ab_<key>`, and `?ab_<key>=<value>` forces a variant and sets the QA
+ * cookie that marks the visit as a test.
+ */
+/** The prefix of an assignment cookie: `ab_lead_form` holds `lead_form`'s variant. */
+export declare const AB_COOKIE_PREFIX = "ab_";
+/** The default prefix of the query parameter that forces a variant. */
+export declare const AB_FORCE_PARAM = "ab_";
+/** A cookie's value from a `document.cookie` string, by exact name, or `null`. */
+export declare function cookieValue(cookies: string, name: string): string | null;
+/** Each key's assigned variant read off the cookies; a key with none is left out. */
+export declare function abAssignments(cookies: string, keys: readonly string[]): Record<string, string>;
+/** The same page forcing `key` to `value`: the other parameters and the hash kept, an earlier force replaced. */
+export declare function abVariantUrl(href: string, key: string, value: string, forceParam?: string): string;
+export interface AbReset {
+    /** Each a `document.cookie` assignment that deletes one cookie. */
+    cookies: string[];
+    /** The page without the force parameters: left in, a reload would force the variant again. */
+    url: string;
+}
+/**
+ * What a reset clears. `"reassign"` drops the experiments' assignments only —
+ * the variant is drawn again and the visit stays a test, the menu with it;
+ * `"leave"` drops the QA cookie too. The QA cookie may itself start with the
+ * assignment prefix (`ab__qa`), so it is excluded by name, never by pattern.
+ */
+export declare function abReset(href: string, keys: readonly string[], qaCookie: string, mode: "reassign" | "leave", forceParam?: string): AbReset;

package/dist/core/ab-switcher.js

@@ -0,0 +1,65 @@
+/**
+ * The QA switcher's decisions, as plain functions over strings: what the
+ * cookies assign, where a variant's tap leads, what a reset clears — whether
+ * the menu shows at all is `ab-gate.ts`. The lazy panel only applies them to
+ * `document.cookie` and `location`.
+ *
+ * The mechanism is the brand proxy's, unchanged: it keeps an assignment in a
+ * cookie `ab_<key>`, and `?ab_<key>=<value>` forces a variant and sets the QA
+ * cookie that marks the visit as a test.
+ */
+/** The prefix of an assignment cookie: `ab_lead_form` holds `lead_form`'s variant. */
+export const AB_COOKIE_PREFIX = "ab_";
+/** The default prefix of the query parameter that forces a variant. */
+export const AB_FORCE_PARAM = "ab_";
+/** A cookie's value from a `document.cookie` string, by exact name, or `null`. */
+export function cookieValue(cookies, name) {
+    for (const pair of cookies.split(";")) {
+        const eq = pair.indexOf("=");
+        if (eq < 0 || pair.slice(0, eq).trim() !== name)
+            continue;
+        const raw = pair.slice(eq + 1).trim();
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return null;
+}
+/** Each key's assigned variant read off the cookies; a key with none is left out. */
+export function abAssignments(cookies, keys) {
+    const out = {};
+    for (const key of keys) {
+        const value = cookieValue(cookies, `${AB_COOKIE_PREFIX}${key}`);
+        if (value)
+            out[key] = value;
+    }
+    return out;
+}
+/** The same page forcing `key` to `value`: the other parameters and the hash kept, an earlier force replaced. */
+export function abVariantUrl(href, key, value, forceParam = AB_FORCE_PARAM) {
+    const url = new URL(href);
+    url.searchParams.set(`${forceParam}${key}`, value);
+    return url.toString();
+}
+/**
+ * What a reset clears. `"reassign"` drops the experiments' assignments only —
+ * the variant is drawn again and the visit stays a test, the menu with it;
+ * `"leave"` drops the QA cookie too. The QA cookie may itself start with the
+ * assignment prefix (`ab__qa`), so it is excluded by name, never by pattern.
+ */
+export function abReset(href, keys, qaCookie, mode, forceParam = AB_FORCE_PARAM) {
+    const names = keys.map(k => `${AB_COOKIE_PREFIX}${k}`).filter(n => n !== qaCookie);
+    if (mode === "leave")
+        names.push(qaCookie);
+    const url = new URL(href);
+    for (const key of keys)
+        url.searchParams.delete(`${forceParam}${key}`);
+    // `/fr#quote` with no force parameter would otherwise be the URL itself: the
+    // browser only scrolls to the anchor, the page never reloads, and the cookies
+    // just dropped are never re-drawn.
+    url.hash = "";
+    return { cookies: names.map(n => `${n}=; path=/; max-age=0`), url: url.toString() };
+}

package/dist/core/analytics.d.ts

@@ -40,7 +40,7 @@ export type LeadStep = "need" | "contact" | "intro" | "locality" | "phone" | `es
  * throws, prod drops) rather than by review. `experiment` and `variant` are
  * the site's assignment, passed in; `field` is a field's role, never its value.
  */
-export declare const ALLOWED_PROPS: readonly ["brand_id", "location_id", "source", "device", "channel", "form_id", "experiment", "variant", "field", "step", "layout", "reason", "blocking", "need", "cents_bucket", "provider"];
+export declare const ALLOWED_PROPS: readonly ["brand_id", "location_id", "source", "device", "channel", "form_id", "experiment", "variant", "field", "step", "layout", "reason", "blocking", "need", "cents_bucket", "provider", "forced"];
 /**
  * The beacon's `distinct_id` as a lead may carry it to the panel
  * (`lead.created`'s `analytics_id`), so PostHog can join the lead to the

package/dist/core/analytics.js

@@ -57,6 +57,9 @@ export const ALLOWED_PROPS = [
     "cents_bucket",
     // The booking's provider, `manual` | `link` | `cal_com` — never its URL.
     "provider",
+    // A test visit (`true`): the brand's QA cookie was set, by a forced variant
+    // or the QA menu. Absent otherwise, never `false`.
+    "forced",
 ];
 /**
  * The beacon's `distinct_id` as a lead may carry it to the panel

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { createAcceptLead, ANALYTICS_ID_FIELD, EXPERIMENT_FIELD, FORM_ID_FIELD,
 export { areaServedNodes, breadcrumbNode, businessId, businessNode, faqPageNode, offerNodes, organizationId, organizationNode, placeGraph, websiteId, type OfferInput, type PageGraphCopy, type QuestionAnswer, } from "./core/seo/ld.js";
 export { AI_CRAWLERS, ogImageUrl, robotsFor, sitemapFor, type RobotsFile, type RobotsRule, type SitemapEntry, } from "./core/seo/sitemap.js";
 export { ALLOWED_PROPS, ANALYTICS_ID, analyticsSink, countsAsPageView, EVENTS, EXPERIMENT_SLUG, experimentProps, type AnalyticsTarget, type IntentChannel, type LeadField, type LeadStep, } from "./core/analytics.js";
+export { AB_COOKIE_PREFIX, AB_FORCE_PARAM, abAssignments, abReset, abVariantUrl, cookieValue, type AbReset, } from "./core/ab-switcher.js";
+export { abSwitcherVisible } from "./core/ab-gate.js";
 export type { CallBarText, CopySlice, CoreText, PageMetaCopy, QuoteFormCopy, Said, StatusAction, StatusCopy, StatusScreenText, } from "./core/content.js";
 export { BOOKING_LIMITS, BOOKING_PROVIDERS, BOOKING_STATUSES, BookingConfigError, bookingConfigProblems, BOOKING_EXPERIMENT, bookingHref, bookingOf, bookingRequestedProperties, bookingRequestProblems, calComHostsProblems, DEFAULT_BOOKING, DEFAULT_CAL_COM_HOSTS, isBookingProvider, isLeadRef, isPageProvider, isPreferredPart, parseBookingConfig, parseBookingRequest, PREFERRED_PARTS, type BookingChoice, type BookingConfig, type BookingPrefill, type BookingProvider, type BookingRequest, type BookingRequestedProperties, type BookingRules, type BookingStatus, type OpenBookingConfig, type PageProvider, type PreferredPart, } from "./core/booking/index.js";
 export { brandStatusTarget, statusTarget, thanksChannel, thanksSuffix, type StatusTarget } from "./core/status.js";

package/dist/index.js

@@ -17,6 +17,8 @@ export { createAcceptLead, ANALYTICS_ID_FIELD, EXPERIMENT_FIELD, FORM_ID_FIELD,
 export { areaServedNodes, breadcrumbNode, businessId, businessNode, faqPageNode, offerNodes, organizationId, organizationNode, placeGraph, websiteId, } from "./core/seo/ld.js";
 export { AI_CRAWLERS, ogImageUrl, robotsFor, sitemapFor, } from "./core/seo/sitemap.js";
 export { ALLOWED_PROPS, ANALYTICS_ID, analyticsSink, countsAsPageView, EVENTS, EXPERIMENT_SLUG, experimentProps, } from "./core/analytics.js";
+export { AB_COOKIE_PREFIX, AB_FORCE_PARAM, abAssignments, abReset, abVariantUrl, cookieValue, } from "./core/ab-switcher.js";
+export { abSwitcherVisible } from "./core/ab-gate.js";
 export { BOOKING_LIMITS, BOOKING_PROVIDERS, BOOKING_STATUSES, BookingConfigError, bookingConfigProblems, BOOKING_EXPERIMENT, bookingHref, bookingOf, bookingRequestedProperties, bookingRequestProblems, calComHostsProblems, DEFAULT_BOOKING, DEFAULT_CAL_COM_HOSTS, isBookingProvider, isLeadRef, isPageProvider, isPreferredPart, parseBookingConfig, parseBookingRequest, PREFERRED_PARTS, } from "./core/booking/index.js";
 export { brandStatusTarget, statusTarget, thanksChannel, thanksSuffix } from "./core/status.js";
 // A landing needs these beside the machinery; re-exported by name so a brand

package/dist/react/AbSwitcher.d.ts

@@ -0,0 +1,9 @@
+import type { AbSwitcherProps } from "./ab-switcher-types.js";
+/**
+ * The QA menu's gate: everything a visitor downloads for it. On the server and
+ * on the first client render it is nothing — the page stays static, no cookie
+ * is read there — and after mount it loads the panel only outside production
+ * or for a visit carrying the QA cookie. Nothing heavy is imported here: the
+ * panel and the kit come with the dynamic import, in their own chunk.
+ */
+export declare function AbSwitcher(props: AbSwitcherProps): import("react").JSX.Element | null;

package/dist/react/AbSwitcher.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { abSwitcherVisible } from "../core/ab-gate.js";
+/**
+ * The QA menu's gate: everything a visitor downloads for it. On the server and
+ * on the first client render it is nothing — the page stays static, no cookie
+ * is read there — and after mount it loads the panel only outside production
+ * or for a visit carrying the QA cookie. Nothing heavy is imported here: the
+ * panel and the kit come with the dynamic import, in their own chunk.
+ */
+export function AbSwitcher(props) {
+    const [Panel, setPanel] = useState(null);
+    const { qaCookie } = props;
+    useEffect(() => {
+        if (!abSwitcherVisible(document.cookie, qaCookie, process.env.NODE_ENV))
+            return;
+        // An answer after unmount is dropped by React; no flag to carry.
+        void import("./AbSwitcherPanel.js").then(m => setPanel(() => m.AbSwitcherPanel));
+    }, [qaCookie]);
+    return Panel ? _jsx(Panel, { ...props }) : null;
+}

package/dist/react/AbSwitcherPanel.d.ts

@@ -0,0 +1,8 @@
+import type { AbSwitcherProps } from "./ab-switcher-types.js";
+/**
+ * The QA menu itself, loaded only when `AbSwitcher` lets it: a chip in a
+ * corner and, on a tap, each experiment's variants. A tap on a variant is the
+ * brand's own force parameter — no other way in. Minimized and hidden live in
+ * memory only: a reload brings the chip back.
+ */
+export declare function AbSwitcherPanel({ experiments, qaCookie, current, forceParam, className, text }: AbSwitcherProps): import("react").JSX.Element | null;

package/dist/react/AbSwitcherPanel.js

@@ -0,0 +1,77 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge, Button, cn } from "@evinvest/uikit";
+import { useEffect, useRef, useState } from "react";
+import { abAssignments, abReset, abVariantUrl, AB_FORCE_PARAM } from "../core/ab-switcher.js";
+const TEXT = {
+    title: "A/B test switcher",
+    reset: "Reset",
+    leave: "Leave test",
+    minimize: "Minimize",
+    hide: "Hide",
+    unassigned: "not assigned",
+};
+/**
+ * The QA menu itself, loaded only when `AbSwitcher` lets it: a chip in a
+ * corner and, on a tap, each experiment's variants. A tap on a variant is the
+ * brand's own force parameter — no other way in. Minimized and hidden live in
+ * memory only: a reload brings the chip back.
+ */
+export function AbSwitcherPanel({ experiments, qaCookie, current, forceParam = AB_FORCE_PARAM, className, text }) {
+    const t = { ...TEXT, ...text };
+    const keys = experiments.map(e => e.key);
+    const [assigned] = useState(() => current ?? abAssignments(document.cookie, keys));
+    const [open, setOpen] = useState(false);
+    const [minimized, setMinimized] = useState(false);
+    const [hidden, setHidden] = useState(false);
+    const root = useRef(null);
+    const chip = useRef(null);
+    const close = (refocus) => {
+        setOpen(false);
+        if (refocus)
+            chip.current?.focus();
+    };
+    useDismiss(open, root, close);
+    const reset = (mode) => {
+        const plan = abReset(location.href, keys, qaCookie, mode, forceParam);
+        for (const c of plan.cookies)
+            document.cookie = c;
+        location.replace(plan.url);
+    };
+    if (hidden)
+        return null;
+    return (_jsxs("div", { "data-ab-switcher": "", ref: root, className: cn("fixed right-4 bottom-4 z-40", className), children: [open && (_jsxs("div", { role: "dialog", "aria-label": t.title, className: "absolute right-0 bottom-full mb-2 flex w-80 max-w-[calc(100vw-2rem)] flex-col gap-4 rounded-md border border-border bg-popover p-3 text-ink shadow-md", children: [experiments.map((e, i) => (_jsx(ExperimentRow, { experiment: e, value: assigned[e.key], unassigned: t.unassigned, autoFocus: i === 0, onPick: v => location.assign(abVariantUrl(location.href, e.key, v, forceParam)) }, e.key))), _jsxs("div", { className: "flex flex-wrap gap-2", children: [_jsx(Button, { variant: "primary", size: "touch", className: "flex-1", onClick: () => reset("reassign"), children: t.reset }), _jsx(Button, { variant: "outline", size: "touch", className: "flex-1", onClick: () => reset("leave"), children: t.leave })] }), _jsxs("div", { className: "flex gap-2", children: [_jsx(Button, { variant: "ghost", size: "touch", className: "flex-1", onClick: () => { setMinimized(true); close(true); }, children: t.minimize }), _jsx(Button, { variant: "ghost", size: "touch", className: "flex-1", onClick: () => setHidden(true), children: t.hide })] })] })), _jsxs(Button, { ref: chip, variant: "secondary", size: "touch", icon: minimized, "aria-label": t.title, "aria-expanded": open, className: cn("shadow-md", !minimized && "gap-1.5 px-3"), onClick: () => { if (open)
+                    close(false);
+                else {
+                    setOpen(true);
+                    setMinimized(false);
+                } }, children: [_jsx("span", { className: "font-semibold", children: "A/B" }), !minimized && keys.map(k => _jsx(Badge, { variant: "outline", className: "border-current/40 text-current", children: assigned[k] ?? "–" }, k))] })] }));
+}
+/**
+ * Escape closes and gives the focus back to the chip; a tap outside closes.
+ * Not the kit's `Popover`: sharing its primitives with the page makes
+ * Turbopack re-split the page's chunks, ~400 B gz on every visitor's first
+ * load for a menu almost nobody opens. The panel is not portaled — the chip's
+ * fixed corner is its anchor — so the root holds both.
+ */
+function useDismiss(open, root, close) {
+    useEffect(() => {
+        if (!open)
+            return;
+        const key = (e) => e.key === "Escape" && close(true);
+        const down = (e) => !(e.target instanceof Node && root.current?.contains(e.target)) && close(false);
+        document.addEventListener("keydown", key);
+        document.addEventListener("pointerdown", down, true);
+        return () => {
+            document.removeEventListener("keydown", key);
+            document.removeEventListener("pointerdown", down, true);
+        };
+    }, [open, root, close]);
+}
+function ExperimentRow({ experiment: e, value, unassigned, autoFocus, onPick }) {
+    const labelId = `ab-switcher-${e.key}`;
+    return (_jsxs("div", { role: "group", "aria-labelledby": labelId, className: "flex flex-col gap-2", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-2 text-sm", children: [_jsx("span", { id: labelId, className: "font-medium text-ink", children: e.label ?? e.key }), value === undefined && _jsx("span", { className: "text-xs text-ink-soft", children: unassigned })] }), _jsx("div", { className: "flex flex-wrap gap-2", children: e.variants.map((v, i) => {
+                    const on = v.value === value;
+                    return (_jsx(Button, { variant: on ? "primary" : "outline", size: "touch", "aria-pressed": on, autoFocus: autoFocus && i === 0, className: "flex-1", onClick: () => onPick(v.value), children: v.label }, v.value));
+                }) })] }));
+}

package/dist/react/AnalyticsBoundary.d.ts

@@ -7,8 +7,16 @@ import { type AnalyticsTarget } from "../core/analytics.js";
  * writes no cookie. `target` is plain data from the server layout — the key
  * is read from the container when the page renders, never inlined.
  */
-export declare function AnalyticsBoundary({ target, placeSlug, children }: {
+export interface AnalyticsBoundaryProps {
     target: AnalyticsTarget;
     placeSlug: string | null;
+    /**
+     * The cookie the brand's force parameter sets (`AbSwitcher`'s `qaCookie`).
+     * A visit carrying it is a test: its page views and intents say
+     * `forced: true`, so the QA menu's reloads do not count as a place's
+     * traffic. Read in the browser at each event, never on the server.
+     */
+    qaCookie?: string;
     children: ReactNode;
-}): import("react").JSX.Element;
+}
+export declare function AnalyticsBoundary({ target, placeSlug, qaCookie, children }: AnalyticsBoundaryProps): import("react").JSX.Element;

package/dist/react/AnalyticsBoundary.js

@@ -12,6 +12,15 @@ import { newSubmissionId } from "./use-lead-submit.js";
  */
 const INTENT_ATTR = "data-intent";
 const INTENTS = ["form_open", "booking", "sms", "callback"];
+/**
+ * Whether the QA cookie is set with a value. Its own copy, not `ab-gate`'s:
+ * a module shared with `AbSwitcher` makes Turbopack split it into a chunk of
+ * its own, which costs every visitor more than these lines.
+ */
+const qaVisit = (name) => document.cookie.split(";").some(c => {
+    const eq = c.indexOf("=");
+    return eq > 0 && c.slice(0, eq).trim() === name && c.slice(eq + 1).trim() !== "";
+});
 function source() {
     const utm = new URLSearchParams(window.location.search).get("utm_source");
     if (utm)
@@ -26,14 +35,7 @@ function source() {
         return "unknown";
     }
 }
-/**
- * The only client island analytics needs. Everything it wraps stays server
- * rendered; this adds one delegated listener (capture phase, never cancelling
- * the navigation) and a page-view beacon. With no key it sends nothing, and it
- * writes no cookie. `target` is plain data from the server layout — the key
- * is read from the container when the page renders, never inlined.
- */
-export function AnalyticsBoundary({ target, placeSlug, children }) {
+export function AnalyticsBoundary({ target, placeSlug, qaCookie, children }) {
     // On the target's values: a server layout hands a fresh object every render.
     const { key, host, brandId } = target;
     // One visitor for the boundary's life, in memory only: a sink rebuilt for
@@ -41,25 +43,29 @@ export function AnalyticsBoundary({ target, placeSlug, children }) {
     const [distinctId] = useState(newSubmissionId);
     const sink = useMemo(() => analyticsSink({ key, host, brandId }, placeSlug, distinctId), [key, host, brandId, placeSlug, distinctId]);
     const pathname = usePathname();
+    // Spread into an event: `{}` without the cookie, so a brand that never
+    // passes `qaCookie` sends exactly what it sent before.
+    const forced = () => (qaCookie && qaVisit(qaCookie) ? { forced: true } : {});
     useEffect(() => {
         if (!countsAsPageView(pathname))
             return;
         sink.capture(EVENTS.pageView, {
             source: source(),
             device: window.matchMedia("(max-width: 767px)").matches ? "mobile" : "desktop",
+            ...forced(),
         });
-    }, [sink, pathname]);
+    }, [sink, pathname, qaCookie]);
     useEffect(() => {
         const onClick = (event) => {
             const el = event.target instanceof Element ? event.target.closest(`[${INTENT_ATTR}]`) : null;
             const channel = el?.getAttribute(INTENT_ATTR);
             if (channel && INTENTS.some(i => i === channel))
-                sink.capture(EVENTS.intent, { channel, ...experimentOf(el) }, { transport: "beacon" });
+                sink.capture(EVENTS.intent, { channel, ...experimentOf(el), ...forced() }, { transport: "beacon" });
         };
         document.addEventListener("click", onClick, { capture: true });
         return () => document.removeEventListener("click", onClick, { capture: true });
-    }, [sink]);
+    }, [sink, qaCookie]);
     // A link inside an experiment's island (`LeadCapture`) carries the
     // assignment on itself, which is what the tracker reads.
-    return (_jsx(AnalyticsIdContext.Provider, { value: key ? distinctId : null, children: _jsx(AnalyticsSinkContext.Provider, { value: sink, children: _jsx(ContactLinkTracker, { channels: ["phone", "whatsapp"], onContact: ({ channel, data }) => sink.capture(EVENTS.intent, { channel, ...experimentProps(data["experiment"], data["variant"]) }, { transport: "beacon" }), children: children }) }) }));
+    return (_jsx(AnalyticsIdContext.Provider, { value: key ? distinctId : null, children: _jsx(AnalyticsSinkContext.Provider, { value: sink, children: _jsx(ContactLinkTracker, { channels: ["phone", "whatsapp"], onContact: ({ channel, data }) => sink.capture(EVENTS.intent, { channel, ...experimentProps(data["experiment"], data["variant"]), ...forced() }, { transport: "beacon" }), children: children }) }) }));
 }

package/dist/react/FormSelect.d.ts

@@ -22,6 +22,12 @@ export interface FormSelectProps {
     options: readonly FormSelectOption[];
     /** Without it: empty under a `placeholder`, else the first option — a native select's own rule. */
     defaultValue?: string | undefined;
+    /**
+     * Controlled: the value shown and posted, kept until the parent changes it
+     * from `onValueChange` (a form reset leaves it too). `undefined` is
+     * uncontrolled, as on an `<input>`; `""` is the placeholder.
+     */
+    value?: string | undefined;
     /** An empty, unpickable choice shown until one is made. */
     placeholder?: string | undefined;
     required?: boolean | undefined;

package/dist/react/FormSelect.js

@@ -26,11 +26,14 @@ export function FormSelectView({ scripted, ...props }) {
     const native = useRef(null);
     // The box, not the trigger: `SelectTrigger` keeps its own ref for placing the list.
     const box = useRef(null);
-    const state = useFormSelectValue({ initial, native, box, scripted, onValueChange: props.onValueChange });
+    const state = useFormSelectValue({ initial, controlled: props.value, native, box, scripted, onValueChange: props.onValueChange });
     const hint = placeholder !== undefined ? { placeholder } : {};
     const aria = { "aria-describedby": props["aria-describedby"], "aria-invalid": props["aria-invalid"] || state.invalid || undefined };
     if (!scripted) {
-        return (_jsx(NativeSelect, { ref: native, name: name, id: id, size: size, ...hint, required: required, disabled: disabled, defaultValue: initial, wrapperClassName: cn(BOX, className), className: classNames?.trigger, ...aria, children: options.map(o => (_jsx(NativeSelectOption, { value: o.value, children: o.label }, o.value))) }));
+        return (_jsx(NativeSelect, { ref: native, name: name, id: id, size: size, ...hint, required: required, disabled: disabled, 
+            // Uncontrolled even under `value`: before the script nothing could
+            // follow a change, and a pick made then must survive into the swap.
+            defaultValue: state.value, wrapperClassName: cn(BOX, className), className: classNames?.trigger, ...aria, children: options.map(o => (_jsx(NativeSelectOption, { value: o.value, children: o.label }, o.value))) }));
     }
     return (_jsxs("span", { ref: box, "data-slot": "form-select", className: cn(BOX, className), children: [_jsxs(Select, { value: state.value, onValueChange: state.choose, open: state.open, onOpenChange: state.setOpen, children: [_jsx(SelectTrigger, { id: id, size: size, disabled: disabled, "aria-required": required || undefined, className: cn(TRIGGER, TRIGGER_TEXT[size], classNames?.trigger), ...aria, children: _jsx(SelectValue, { ...hint }) }), _jsx(SelectContent, { className: classNames?.content, children: options.map(o => (_jsx(SelectItem, { value: o.value, className: cn(size === "lg" && "py-2.5 text-base", classNames?.item), children: o.label }, o.value))) })] }), required ? (
             // Validated, so not `type="hidden"` (which the browser never checks);

package/dist/react/ab-switcher-types.d.ts

@@ -0,0 +1,39 @@
+/** One variant of an experiment, as the menu offers it. */
+export interface AbSwitcherVariant {
+    /** The value the force parameter carries and the cookie holds: `b`. */
+    value: string;
+    label: string;
+}
+/** One experiment the menu switches. */
+export interface AbSwitcherExperiment {
+    /** The experiment's key: the cookie is `ab_<key>`, the force parameter `<forceParam><key>`. */
+    key: string;
+    label?: string;
+    variants: readonly AbSwitcherVariant[];
+}
+/** The menu's words; English unless the brand says otherwise. */
+export interface AbSwitcherText {
+    /** The chip's and the panel's accessible name. */
+    title: string;
+    reset: string;
+    leave: string;
+    minimize: string;
+    hide: string;
+    /** Shown for an experiment no cookie assigns yet. */
+    unassigned: string;
+}
+/**
+ * Plain data, so a server layout mounts it. Positioned by `className`: a brand
+ * lifts the chip over its own sticky bars.
+ */
+export interface AbSwitcherProps {
+    experiments: readonly AbSwitcherExperiment[];
+    /** The cookie the brand's force parameter sets to mark a test visit: `ab__qa`. */
+    qaCookie: string;
+    /** The assignments, when the caller knows them; otherwise read from `ab_<key>` cookies. */
+    current?: Readonly<Record<string, string>>;
+    /** The prefix of the parameter that forces a variant; `ab_` by default. */
+    forceParam?: string;
+    className?: string;
+    text?: Partial<AbSwitcherText>;
+}

package/dist/react/ab-switcher-types.js

@@ -0,0 +1 @@
+export {};

package/dist/react/form-select-value.d.ts

@@ -3,9 +3,15 @@ import { type InvalidEvent, type RefObject } from "react";
  * The value `FormSelect` posts, across the swap from the native select and
  * through the form's own life: a reset, and a required check that points at
  * the kit's trigger instead of an input nobody sees.
+ *
+ * `controlled` (a `value` prop) follows React's input idiom: the prop is the
+ * value, a choice reaches the parent only through `onValueChange`, and a reset
+ * leaves it where the parent holds it. The own state still follows the prop,
+ * so a switch back to uncontrolled keeps the last value, as an `<input>` does.
  */
 export declare function useFormSelectValue(opts: {
     initial: string;
+    controlled: string | undefined;
     native: RefObject<HTMLSelectElement | null>;
     box: RefObject<HTMLElement | null>;
     scripted: boolean;

package/dist/react/form-select-value.js

@@ -1,23 +1,45 @@
 "use client";
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
+const DEV = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
 /**
  * The value `FormSelect` posts, across the swap from the native select and
  * through the form's own life: a reset, and a required check that points at
  * the kit's trigger instead of an input nobody sees.
+ *
+ * `controlled` (a `value` prop) follows React's input idiom: the prop is the
+ * value, a choice reaches the parent only through `onValueChange`, and a reset
+ * leaves it where the parent holds it. The own state still follows the prop,
+ * so a switch back to uncontrolled keeps the last value, as an `<input>` does.
  */
 export function useFormSelectValue(opts) {
-    const { initial, native, box, scripted, onValueChange } = opts;
-    const [value, setValue] = useState(initial);
+    const { initial, controlled, native, box, scripted, onValueChange } = opts;
+    const [own, setOwn] = useState(controlled ?? initial);
     const [invalid, setInvalid] = useState(false);
     const [open, setOpen] = useState(false);
-    const initialRef = useRef(initial);
-    initialRef.current = initial;
+    const isControlled = controlled !== undefined;
+    if (isControlled && own !== controlled)
+        setOwn(controlled);
+    const value = isControlled ? controlled : own;
+    useModeWarning(isControlled);
+    // The effects below run once or on a form event: they read the latest props here.
+    const latest = useRef({ initial, isControlled, value, onValueChange });
+    latest.current = { initial, isControlled, value, onValueChange };
     // A choice made in the native select before the script arrived survives the
     // swap: read in the hydration commit, before the scripted render. Once —
-    // later renders never hold the native select.
+    // later renders never hold the native select. Under a `value` it is the
+    // parent's to take, so it is reported instead of kept — and only a real
+    // pick: a `value` no option carries leaves the browser on its own default,
+    // which is no choice of the visitor's.
     useLayoutEffect(() => {
-        if (native.current)
-            setValue(native.current.value);
+        const select = native.current;
+        if (!select)
+            return;
+        const picked = select.value;
+        const { isControlled: held, value: shown, onValueChange: report } = latest.current;
+        if (!held)
+            setOwn(picked);
+        else if (picked !== shown && picked !== untouched(select))
+            report?.(picked);
     }, [native]);
     // A form reset puts a native select back on its default; so does this.
     // Interactive validation — the browser's own, on a submit — is told apart
@@ -27,7 +49,10 @@ export function useFormSelectValue(opts) {
         const form = box.current?.closest("form");
         if (!scripted || !form)
             return;
-        const reset = () => setValue(initialRef.current);
+        const reset = () => {
+            if (!latest.current.isControlled)
+                setOwn(latest.current.initial);
+        };
         // On the document, not the form: a submit button may sit outside it
         // (`form="…"`), and the click may land on an icon inside the button.
         const submit = (e) => {
@@ -48,7 +73,8 @@ export function useFormSelectValue(opts) {
         };
     }, [box, scripted]);
     const choose = (next) => {
-        setValue(next);
+        if (!isControlled)
+            setOwn(next);
         setInvalid(false);
         onValueChange?.(next);
     };
@@ -70,3 +96,22 @@ export function useFormSelectValue(opts) {
     };
     return { value, choose, invalid, open, setOpen, onInvalid };
 }
+/**
+ * What a single select shows before anyone touches it: the option marked
+ * `selected` in the markup, else the first enabled one (HTML's selectedness
+ * setting). A pick of that same option is indistinguishable, and harmless.
+ */
+function untouched(select) {
+    const options = Array.from(select.options);
+    return (options.find(o => o.defaultSelected) ?? options.find(o => !o.disabled))?.value;
+}
+/** React's warning for an `<input>` that changes mode: once, and nothing else changes. */
+function useModeWarning(isControlled) {
+    const first = useRef(isControlled);
+    const warned = useRef(false);
+    if (!DEV || warned.current || first.current === isControlled)
+        return;
+    warned.current = true;
+    console.error(`@evinvest/kitstart: a FormSelect is changing from ${first.current ? "controlled to uncontrolled" : "uncontrolled to controlled"}. ` +
+        "Keep one of `value` and `defaultValue` for its lifetime; `value={undefined}` makes it uncontrolled.");
+}

package/dist/react/index.d.ts

@@ -1,8 +1,11 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture` and `LeadBooking` are client modules, each its own file
- * with its own `"use client"`, so a page pays for what it renders.
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture`, `LeadBooking`
+ * and `AbSwitcher` are client modules, each its own file with its own
+ * `"use client"`, so a page pays for what it renders. `AbSwitcher` is a gate
+ * of a few hundred bytes; its panel (`AbSwitcherPanel`) is a dynamic import,
+ * fetched only by a QA visit.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
  * `bg-card`…); a brand restyles through `className`, a widget's named parts
@@ -10,7 +13,9 @@
  * must scan the package: `@source "<path to>/node_modules/@evinvest/kitstart/dist";`,
  * relative to the stylesheet (`../../node_modules/…` from `src/app/`).
  */
-export { AnalyticsBoundary } from "./AnalyticsBoundary.js";
+export { AbSwitcher } from "./AbSwitcher.js";
+export type { AbSwitcherExperiment, AbSwitcherProps, AbSwitcherText, AbSwitcherVariant } from "./ab-switcher-types.js";
+export { AnalyticsBoundary, type AnalyticsBoundaryProps } from "./AnalyticsBoundary.js";
 export { AreaChips } from "./AreaChips.js";
 export { CallBar, type CallBarPart, type CallBarProps } from "./CallBar.js";
 export { Coverage, type CoveragePart, type CoverageProps } from "./Coverage.js";

package/dist/react/index.js

@@ -1,8 +1,11 @@
 /**
  * `@evinvest/kitstart/react` — the structural widgets every landing shares,
  * where behaviour matters more than look. Server components by default; only
- * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture` and `LeadBooking` are client modules, each its own file
- * with its own `"use client"`, so a page pays for what it renders.
+ * `MapFacade`, `AnalyticsBoundary`, `FormSelect`, `LeadCapture`, `LeadBooking`
+ * and `AbSwitcher` are client modules, each its own file with its own
+ * `"use client"`, so a page pays for what it renders. `AbSwitcher` is a gate
+ * of a few hundred bytes; its panel (`AbSwitcherPanel`) is a dynamic import,
+ * fetched only by a QA visit.
  *
  * Styled with the kit's token roles only (`text-ink`, `border-border`,
  * `bg-card`…); a brand restyles through `className`, a widget's named parts
@@ -10,6 +13,7 @@
  * must scan the package: `@source "<path to>/node_modules/@evinvest/kitstart/dist";`,
  * relative to the stylesheet (`../../node_modules/…` from `src/app/`).
  */
+export { AbSwitcher } from "./AbSwitcher.js";
 export { AnalyticsBoundary } from "./AnalyticsBoundary.js";
 export { AreaChips } from "./AreaChips.js";
 export { CallBar } from "./CallBar.js";

package/dist/server/experiments-declared.d.ts

@@ -3,16 +3,20 @@ import type { LeadWebhook } from "./lead-webhook.js";
 /**
  * One experiment as the code declares it — the shape of an
  * `@evinvest/experiments` spec, so the brand's `as const` config is passed
- * as is. `variants[0]` is the control.
+ * as is. `variants[0]` is the control. No weights: the code splits equally,
+ * and re-weighting is the panel's override.
  */
 export interface DeclaredExperiment {
     readonly variants: readonly string[];
-    readonly weights: readonly number[];
     readonly enabled?: boolean;
     readonly holdout?: number;
 }
 export type ExperimentsDeclaration = Readonly<Record<string, DeclaredExperiment>>;
-/** `ExperimentDeclaration` of the panel's `experiments.declared@1`. */
+/**
+ * `ExperimentDeclaration` of the panel's `experiments.declared@1`. `weights`
+ * stays in the contract; the code always sends one each (the equal split it
+ * runs without an override).
+ */
 export interface ExperimentDeclarationV1 {
     key: string;
     variants: string[];

package/dist/server/experiments-declared.js

@@ -17,12 +17,6 @@ export function declarationProblem(key, spec, summary) {
         return "a variant is declared twice";
     if (!spec.variants.every(v => EXPERIMENT_SLUG.test(v)))
         return "a variant is not a slug ([a-z0-9_-]{1,32})";
-    if (spec.weights.length !== spec.variants.length)
-        return "not one weight per variant";
-    if (!spec.weights.every(w => Number.isFinite(w) && w >= 0))
-        return "a weight is negative or not a number";
-    if (spec.weights.reduce((sum, w) => sum + w, 0) <= 0)
-        return "the weights sum to zero";
     if (spec.holdout !== undefined && !(Number.isFinite(spec.holdout) && spec.holdout >= 0 && spec.holdout < 1))
         return "the holdout is not in [0, 1)";
     if (summary !== undefined && summary.length > MAX_SUMMARY)
@@ -60,7 +54,7 @@ export function experimentsDeclaredBody(experiments, ctx) {
         declared.push({
             key,
             variants: [...spec.variants],
-            weights: [...spec.weights],
+            weights: spec.variants.map(() => 1),
             enabled: spec.enabled ?? true,
             ...(spec.holdout !== undefined ? { holdout: spec.holdout } : {}),
             ...(summary !== undefined && summary !== "" ? { summary } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evinvest/kitstart",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Landing-site machinery for local-service brands: a site composition root, the Place/Presence/ServiceArea model with a publication gate, host/locale routing, schema.org and SEO builders, the lead funnel with its antispam, and analytics events. Pure core at '.', more subpaths per runtime.",
   "license": "BlueOak-1.0.0",
   "publishConfig": {

package/template/app/[locale]/[location]/layout.tsx

@@ -1,7 +1,8 @@
-import { AnalyticsBoundary } from "@evinvest/kitstart/react";
+import { AbSwitcher, AnalyticsBoundary } from "@evinvest/kitstart/react";
 import type { ReactNode } from "react";
 import { loadPlace } from "@/views/place/server";
 import { serverEnv } from "@/shared/config/env";
+import { EXPERIMENTS, QA_COOKIE } from "@/shared/config/experiments";
 import { site } from "@/shared/config/site";
 
 /**
@@ -22,8 +23,10 @@ export default async function PlaceLayout({ children, params }: { children: Reac
   const env = serverEnv();
   // The key is read from the container when the page renders, never inlined.
   return (
-    <AnalyticsBoundary target={{ key: env.posthogKey, host: env.posthogHost, brandId: site.brand.id }} placeSlug={view.place.slug}>
+    <AnalyticsBoundary target={{ key: env.posthogKey, host: env.posthogHost, brandId: site.brand.id }} placeSlug={view.place.slug} qaCookie={QA_COOKIE}>
       {children}
+      {/* Above the phone's call bar; nothing at all for a visit without the QA cookie. */}
+      <AbSwitcher experiments={EXPERIMENTS} qaCookie={QA_COOKIE} className="bottom-20 md:bottom-4" />
     </AnalyticsBoundary>
   );
 }

package/template/flake.nix

@@ -3,7 +3,7 @@
     v_flakes.url = "github:valeratrades/v_flakes?ref=v1.6";
     # The lib flake at the tag of the @evinvest/kitstart version in
     # package-lock.json — mkLanding refuses a mismatch.
-    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.14.0";
+    ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.16.0";
     ev.inputs.v_flakes.follows = "v_flakes";
   };
 

package/template/package.json

@@ -20,7 +20,7 @@
   "dependencies": {
     "@evinvest/analytics": "^0.4.0",
     "@evinvest/i18n": "^0.9.0",
-    "@evinvest/kitstart": "^0.14.0",
+    "@evinvest/kitstart": "^0.16.0",
     "@evinvest/marketing": "^0.3.0",
     "@evinvest/uikit": "^0.26.0",
     "next": "16.3.6",

package/template/src/shared/config/experiments.ts

@@ -0,0 +1,21 @@
+import type { AbSwitcherExperiment } from "@evinvest/kitstart/react";
+
+/**
+ * The experiments the QA menu switches — a demo: the template's proxy runs
+ * none, so a forced `?ab_lead_form=b` changes nothing here. A brand lists the
+ * experiments its proxy assigns, with the QA cookie its force parameter sets.
+ */
+export const EXPERIMENTS: readonly AbSwitcherExperiment[] = [
+  {
+    key: "lead_form",
+    label: "Lead form",
+    variants: [
+      { value: "a", label: "Compact" },
+      { value: "b", label: "Steps" },
+      { value: "c", label: "Price first" },
+    ],
+  },
+];
+
+/** Set by `?ab_<key>=<value>`; a visit carrying it is a test, and sees the menu. */
+export const QA_COOKIE = "ab__qa";

package/template/tests/e2e/ab-switcher.spec.ts

@@ -0,0 +1,114 @@
+import { expect, test, type BrowserContext, type Page, type Response } from "@playwright/test";
+import { QA_COOKIE } from "../../src/shared/config/experiments";
+
+// The QA menu (`AbSwitcher`): a visit with the QA cookie gets the chip and
+// its panel, loaded on demand; a visitor without it gets neither — the
+// panel's chunk is never even requested. A tap on a variant is the brand's
+// own force parameter; the reset drops it and keeps the visit a test.
+
+const hydrated = (page: Page) => expect(page.locator("#quote select")).toHaveCount(0);
+const chip = (page: Page) => page.getByRole("button", { name: "A/B test switcher" });
+const panel = (page: Page) => page.getByRole("dialog", { name: "A/B test switcher" });
+const scripts = (page: Page) => {
+  const seen: Response[] = [];
+  page.on("response", r => void (new URL(r.url()).pathname.endsWith(".js") && seen.push(r)));
+  return seen;
+};
+const asTester = (context: BrowserContext, baseURL: string | undefined) => context.addCookies([{ name: QA_COOKIE, value: "1", url: baseURL ?? "" }]);
+const cookieNames = async (context: BrowserContext) => (await context.cookies()).map(c => c.name);
+
+/** A test visit assigned `b`, as the brand's proxy would have left it, on a page that forces it. */
+async function assignedB(page: Page, context: BrowserContext, baseURL: string | undefined) {
+  await asTester(context, baseURL);
+  await context.addCookies([{ name: "ab_lead_form", value: "b", url: baseURL ?? "" }]);
+  await page.goto("/fr?ab_lead_form=b&utm_x=1");
+  await chip(page).click();
+  await expect(panel(page)).toBeVisible();
+}
+
+test("a new visitor gets no menu and never fetches its panel; a test visit gets both", async ({ page, context, baseURL }) => {
+  const visitor = scripts(page);
+  await page.goto("/fr");
+  await hydrated(page);
+  // Settled: the gate's effect ran on hydration, and anything it fetched is in.
+  await page.waitForLoadState("networkidle");
+  await expect(chip(page)).toHaveCount(0);
+  const fetched = visitor.map(r => r.url());
+
+  await asTester(context, baseURL);
+  const tester = scripts(page);
+  await page.goto("/fr");
+  await chip(page).click();
+  await expect(panel(page)).toBeVisible();
+  const marked = await Promise.all(tester.map(async r => ((await r.text()).includes("data-ab-switcher") ? r.url() : null)));
+  const chunks = marked.filter(u => u !== null);
+  expect(chunks.length).toBeGreaterThan(0);
+  for (const url of chunks) expect(fetched).not.toContain(url);
+});
+
+test("a variant's tap forces it by the URL; the reset drops the force and keeps the visit a test", async ({ page, context, baseURL }) => {
+  await asTester(context, baseURL);
+  await page.goto("/fr?utm_source=qa");
+  await chip(page).click();
+  await panel(page).getByRole("button", { name: "Steps" }).click();
+  await expect(page).toHaveURL(/\/fr\?utm_source=qa&ab_lead_form=b$/);
+
+  await chip(page).click();
+  await panel(page).getByRole("button", { name: "Reset", exact: true }).click();
+  await expect(page).toHaveURL(/\/fr\?utm_source=qa$/);
+  expect((await context.cookies()).map(c => c.name)).toContain(QA_COOKIE);
+  await expect(chip(page)).toBeVisible();
+});
+
+test("Reset drops the assignment and its force, keeps the other parameters and the QA cookie, and the chip", async ({ page, context, baseURL }) => {
+  await assignedB(page, context, baseURL);
+  await expect(panel(page).getByRole("button", { name: "Steps" })).toHaveAttribute("aria-pressed", "true");
+  await panel(page).getByRole("button", { name: "Reset", exact: true }).click();
+  await expect(page).toHaveURL(/\/fr\?utm_x=1$/);
+  const names = await cookieNames(context);
+  expect(names).not.toContain("ab_lead_form");
+  expect(names).toContain(QA_COOKIE);
+  await expect(chip(page)).toBeVisible();
+});
+
+test("Leave test drops the QA cookie too: after the load there is no chip", async ({ page, context, baseURL }) => {
+  await assignedB(page, context, baseURL);
+  await panel(page).getByRole("button", { name: "Leave test" }).click();
+  await expect(page).toHaveURL(/\/fr\?utm_x=1$/);
+  await hydrated(page);
+  // Settled: the gate decided on hydration, and a panel it fetched would be in.
+  await page.waitForLoadState("networkidle");
+  expect(await cookieNames(context)).not.toContain(QA_COOKIE);
+  expect(await cookieNames(context)).not.toContain("ab_lead_form");
+  await expect(chip(page)).toHaveCount(0);
+});
+
+test("Leave test from a page reached by an anchor still reloads it, and the chip goes", async ({ page, context, baseURL }) => {
+  await asTester(context, baseURL);
+  await page.goto("/fr#quote");
+  await chip(page).click();
+  // A same-URL replace with the anchor kept is a scroll, not a load: this waits forever.
+  const reloaded = page.waitForEvent("load");
+  await panel(page).getByRole("button", { name: "Leave test" }).click();
+  await reloaded;
+  await expect(page).toHaveURL(/\/fr$/);
+  await hydrated(page);
+  await page.waitForLoadState("networkidle");
+  expect(await cookieNames(context)).not.toContain(QA_COOKIE);
+  await expect(chip(page)).toHaveCount(0);
+});
+
+test("Escape closes the panel and gives the focus back to the chip", async ({ page, context, baseURL }) => {
+  await assignedB(page, context, baseURL);
+  await page.keyboard.press("Escape");
+  await expect(panel(page)).toHaveCount(0);
+  await expect(chip(page)).toBeFocused();
+});
+
+test("Hide removes the chip until the next load", async ({ page, context, baseURL }) => {
+  await assignedB(page, context, baseURL);
+  await panel(page).getByRole("button", { name: "Hide" }).click();
+  await expect(chip(page)).toHaveCount(0);
+  await page.reload();
+  await expect(chip(page)).toBeVisible();
+});

package/template/tests/e2e/screenshot-section.css

@@ -3,3 +3,9 @@
 #callbar {
   display: none !important;
 }
+
+/* The QA menu (`AbSwitcher`) rides the viewport too, and only a test visit
+ * sees it: never part of a section. */
+[data-ab-switcher] {
+  display: none !important;
+}