@evinvest/kitstart 0.16.0 → 0.18.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.16.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.18.0"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -237,10 +237,10 @@ it is the plain POST to `/quote` it always was.
 | `needDisplay` | how the need is asked: `select` (default on `single`) · `tiles` (default otherwise) · `cards`, a grid with each need's `icon` |
 | `intro`, `localityStep` | `steps` only: a question before the need, posted as a brand's extra, whose answer may turn the form into a callback · the postcode on its own screen (`own`, default) or on the phone's (`with-phone`) |
 | `focusNext` | on one screen: after a choice the focus moves to the next empty field, and Enter in a field moves to the next empty one before it submits. Off by default; always so in `steps` |
-| `questions` | by estimate input id: `{ display?: "tiles" \| "cards", unknown?: true, unknownSpan?: 2, badges?: { [option]: text }, shortLabels?: { [option]: text }, step?: number, next?: string }` — see [The compact form](#the-compact-form) and [steps](#one-question-per-screen-layoutsteps) |
+| `questions` | by estimate input id: `{ display?: "tiles" \| "cards", unknown?: true, unknownSpan?: 2, badges?: { [option]: text }, shortLabels?: { [option]: text }, previewLabels?: { [option]: text }, step?: number, next?: string }` — see [The compact form](#the-compact-form) and [steps](#one-question-per-screen-layoutsteps) |
 | `price`, `taxCredit` | `box` (default) · `compact`: the price on one line, what is left after a tax credit of `taxCredit` (a ratio, `0.5`), the breakdown behind "Détail" |
 | `afterPhone` | a node right under the phone field: one line of reassurance |
-| `channelsDisplay`, `channelIcons` | the other ways out: `stack` (default, under `otherChannels`) · `row`, one row of compact buttons named by `otherChannels` · the brand's icon per channel (`phone`, `whatsapp`, `sms`, `callback`) |
+| `channelsDisplay`, `channelIcons` | the other ways out: `stack` (default, under `otherChannels`) · `row`, one row of compact buttons named by `otherChannels` · the brand's icon per channel (`phone`, `whatsapp`, `sms`, `callback`, `telegram`) |
 | `locality` | `required` (default) · `optional` |
 | `name` | `{ field, required? }`: a name field posted as the brand's extra; off by default |
 | `extras` | the brand's own fields, after the phone |
@@ -257,7 +257,8 @@ it is the plain POST to `/quote` it always was.
 | `bookingVariant` · `bookingEmbed` · `bookingAdapters` | the `booking_provider` variant that picks the place's provider · the providers' embeds (after cookie consent) rather than a new tab · the brand's adapters over the built-ins (from a client component) — see [Booking](#booking-manual-link-google_calendar-cal_com) |
 | `initialError` | `leadErrorOf(searchParams)` on a page that reads its query: the refusal a 303 brought back, drawn on the server by the card it names (`lead_card`) so the card says why without a script (see *Refusals*) |
 | `head`, `trust` | the brand's heading instead of the title; a slot beside the submit. Like `extras`, `done` and `booking`, any node, built on the server or not, and never asked for a `key`: each slot sits alone in a keyed fragment |
-| `className` · `classNames` | the root · its parts: `root`, `head`, `title`, `lede`, `form`, `contact`, `field`, `label`, `control` (every input, the need's select in both states, the callback's phone), `hint`, `error` (a refusal: under the field, or above the submit), `chips`, `chip`, `needs`, `need`, `summary`, `icon` (a need's or an intro answer's icon), `submit`, `trust`, `privacy` (not drawn when `text.privacy` is `""`), `opening`, `others`, `channel`, `channelIcon`, `primary`, `callback`, `callbackSummary`, `callbackForm`, `callbackLede`, `callbackSubmit`, `consent`, `done`, for `steps` `progress`, `stepBack`, `step` (each screen), `answers`, `answer` (the chips of the screens answered), `stepNext`, `intro`, `introOption`, and for the flows `estimate`, `estimateInput`, `estimateLegend`, `estimateGrid` (an input's answers: 2 columns, 3 from `sm`), `estimateOption` (an answer's tile), `estimateUnknown` (the "I don't know" tile, after `estimateOption`), `badge`, `optionPrice` (a card's total), `price`, `priceTotal`, `breakdown`, `priceNote`, `priceLine`, `priceTaxCredit`, `priceDetail` (`price="compact"`), `photos`, `priced`, `pricedPrice`, `pricedNote`, and for the booking `booking`, `bookingCta`, `bookingNote`, `prefer`, `preferOption`, `preferSubmit` |
+| `className` · `classNames` | the root · its parts: `root`, `head`, `title`, `lede`, `form`, `contact`, `field`, `label`, `control` (every input, the need's select in both states, the callback's phone), `hint`, `error` (a refusal: under the field, or above the submit), `chips`, `chip`, `needs`, `need`, `summary`, `icon` (a need's or an intro answer's icon), `submit`, `trust`, `privacy` (not drawn when `text.privacy` is `""`), `opening`, `others`, `channel`, `channelIcon`, `primary`, `callback`, `callbackSummary`, `callbackForm`, `callbackLede`, `callbackSubmit`, `consent`, `done`, for `steps` `progress`, `stepBack`, `step` (each screen), `answers`, `answer` (the chips of the screens answered), `stepNext`, `intro`, `introOption`, and for the flows `estimate`, `estimateInput`, `estimateLegend`, `estimateGrid` (an input's answers: 2 columns, 3 from `sm`), `estimateOption` (an answer's tile), `estimateUnknown` (the "I don't know" tile, after `estimateOption`), `badge`, `optionPrice` (a card's total), `price`, `priceTotal`, `breakdown`, `priceNote`, `priceLine`, `priceTaxCredit`, `priceDetail` (`price="compact"`: the «Détail» trigger), `priceDetailContent` (its popover), `photos`, `priced`, `pricedPrice`, `pricedNote`, and for the booking `booking`, `bookingCta`, `bookingNote`, `prefer`, `preferOption`, `preferSubmit`, and for a `messenger` variant `messenger`, `messengerSlot`, `messengerCta`, `messengerSecondary`, `messengerSquare`, `messengerSegment`, `messengerTile`, `messengerTrigger`, `messengerPreview`, `messengerPicker`, `messengerOption`, `messengerQr`, `messengerReturn`, `messengerHint` |
+| `messenger`, `messengers`, `refPrefix`, `brand`, `messengerTiming` | the `lead_channel` arm (`MessengerVariant`, absent → the control) · `messengerFacts(site, place)` · the chat reference's prefix (`AQ`) · the message's greeting · the estimate's question whose answer is the message's timing line (`{ input: "frequency" }`) — see *Messengers* below |
 
 - **Taps.** A need the page knows is not asked again, and a place serving one
   commune fills it: focus the phone, type, send — two taps. `qualify-first`
@@ -349,16 +350,140 @@ 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 `forced: true` on a test visit, as
-  `location_page_view`, when the boundary has `qaCookie` — see `AbSwitcher`);
-  and on the server `lead_form_submit
+  `callback`, with the experiment; and on the server `lead_form_submit
   {form_id, channel}` and `lead_form_reject {form_id, channel, field,
-  reason}` with the posted experiment.
+  reason}` with the posted experiment. On a test visit every one of them —
+  page view, intents, funnel, booking, and the server's two when
+  `quoteRoute` has `qaCookie` — carries `forced: true` (see `AbSwitcher`).
 - **Weight.** 8.9 KB gz of first-load JS on the template's place page
   (157,287 → 166,361 B against its 158,000 B target: +5.3 %, a warning
   within the 20 % tolerance); the refusals and the shared phone rule are
   2.0 KB of it, sending (the id, the busy state, the retry) 0.6 KB.
 
+### Messengers: `messenger`, WhatsApp and the bot
+
+The `lead_channel` experiment's arms. WhatsApp: the customer sends the brand's
+prefilled message, answered by hand in WhatsApp Business. Telegram: the
+brand's bot, opened as `t.me/<bot>?start=<ref>`. The phone is asked only for
+a call; no text messages. Either way the lead is **posted first**, in the
+background, so the panel has it before the chat starts.
+
+```tsx
+import { messengerFacts } from "@evinvest/kitstart";
+
+<LeadCapture
+  {...controlProps}
+  messenger={arm === "c" ? { kind: "segment" } : undefined} // undefined → the control
+  messengers={messengerFacts(site, place)} // the place's own WhatsApp, its bot — each `null` when off
+                                            // (a bot's name: `TELEGRAM_BOT`, 5–32 chars ending in `bot`)
+  refPrefix="AQ"                            // the lead's chat reference: AQ-7K3F
+  brand="Aquafix"                           // the message's greeting
+  channelIcons={{ whatsapp: <WhatsAppIcon />, telegram: <TelegramIcon />, callback: <PhoneIcon /> }}
+  classNames={{ messengerSlot: "h-[92px]" }} // every state of a variant one height
+/>
+```
+
+| `kind` | Figma | the card |
+|---|---|---|
+| `select` `{side: "prefix" \| "suffix"}` | AQ-1 / VF-1 | the channel picked in the phone field (the kit's `Select`, an overlay): WhatsApp — the number optional, the button opens the chat; Appel — the control; Telegram — no number, the button opens the bot |
+| `segment` | AQ-2 | «WhatsApp \| Appel» over the slot (the message ready / the phone); «ou via Telegram» under the button |
+| `tiles` | VF-2 | «Recevoir mon devis par» and a tile per channel over the slot (the message / what the bot does / the phone) |
+| `thanks` | AQ-3 | the control's form; the in-card success adds a photo on WhatsApp (a QR code on a computer) and the bot. The card stays (`done`) |
+| `swap` | AQ-4 / VF-3 | no phone: the WhatsApp button, then [Telegram][Être rappelé]; «Être rappelé» swaps in the phone and [WhatsApp square][submit] |
+| `saga` | AQ-5 | the channel first, on a screen of its own (cards), then the job and the channel's slot; «Changer de canal» back |
+| `urgency` `{field}` | AQ-6 | «C’est urgent ?» — posted as the brand's extra `field` (`today` / `later`; list it in `site.lead.extras`) — today a call, «je compare» the message |
+| `sheet` | VF-4 | the estimate, the postcode and one button; the kit's `Drawer`: WhatsApp / Telegram / a call, the phone asked in the drawer |
+| `chip` | VF-5 | the lede becomes a chip «Réponse sur WhatsApp ▾» (a `Select` overlay); the slot follows it |
+| `split` | VF-6 | the slot over one row: «Devis sur WhatsApp» with [Telegram][📞] squares; 📞 turns it into «Être rappelé» with [WhatsApp][Telegram] |
+
+- **Fallback** (Figma «Выключено в панели»). No WhatsApp for the place — no
+  number of its own, or `messengers.whatsapp: false` from the panel — and
+  every kind is the control, with «ou via Telegram» under the submit when the
+  bot is on; `urgency` keeps its question (both answers ask the phone) and
+  `thanks` keeps the bot. No bot — every Telegram piece is left out. The arm
+  stays assigned; every event says what the card had: `channels_available`
+  (`wa,tg` | `wa` | `tg` | `none`). The switches are the form's only: `contactOf` — the
+  header, the call bar, the control's own WhatsApp link — keeps the number.
+- **The reference** `message_ref`: `<refPrefix>-<4 Crockford base32>`,
+  minted in the browser once the script runs, and again only once the
+  visitor is back from the chat and has answered «Message envoyé ?» — never
+  in the tap: the reference posted is the one in the link, the QR code and
+  the return screen, and a second tap on the same lead is the same lead; the WhatsApp message ends with `Réf. AQ-7K3F`, the bot's
+  `start` is the reference itself. Posted with every lead of the card (a
+  `thanks` success sends the form lead's own), stored (`message_ref`, schema
+  8), mailed (`Réf.`), and sent to the panel under `panelMessenger`.
+- **The message** (`messengerMessage`, ≤ 400 characters, nothing typed about
+  the person): `Bonjour {brand} 👋`, the need with the estimate's answers
+  («Ménage standard · 2 ch. · 40–70 m²»: each answer as
+  `questions[id].previewLabels` says it — a tile's «2» is «2 ch.» here — else
+  its `shortLabels`, else its label; «Je ne sais pas» left out),
+  the postcode, the estimate shown (a priced need), the timing, `Réf. {ref}` —
+  a line without its value left out. The slot shows it as a preview, so the
+  visitor sees there is nothing to write: «Bonjour Vifnet 👋 · Ménage
+  standard · 2 ch. · 40–70 m² · 2 sem. · env. 77 € · 63130 · Réf. VF-7K3F»
+  (the timing by its `previewLabels` / `shortLabels`, the price through `messengerPreviewPrice`,
+  `"env. {price}"`). The timing is `urgency`'s answer («aujourd’hui» / «pas
+  pressé»), else the answer to the estimate's question `messengerTiming`
+  names — `messengerTiming={{ input: "frequency" }}`, its whole label on a line
+  of its own, out of the need's list; none until it is answered, nor for «Je
+  ne sais pas». Each line is a key a brand rewords: `{ ...LEAD_CAPTURE_TEXT.fr,
+  messageTiming: "Fréquence : {timing}", messagePrice: "Estimation vue sur le
+  site : env. {price} / passage" }`.
+- **Icons** (`channelIcons`): `whatsapp` and `telegram` before their
+  buttons, items, tiles and segments; `phone` (else `callback`) before every
+  call inside a variant — «Être rappelé», its submit, the squares.
+- **The tap.** A real `<a href>` — the OS opens the app from the tap. A
+  number typed must be one (the browser says so, nothing leaves). The lead is
+  posted (`keepalive`, `channel=whatsapp|telegram`, the reference, what was
+  filled; the same submission id for a second tap). On a computer (`hover:
+  hover`, `pointer: fine`, ≥ 768 px) WhatsApp becomes a QR code in the slot
+  (`qrcode-generator`, loaded on that tap only) with «ou ouvrir WhatsApp Web»
+  and «Être rappelé»; the bot opens in a new tab. In an app's own browser
+  (Instagram, Facebook, TikTok, Line, Snapchat) a hint says how to leave it,
+  with «Copier le message».
+- **Back on the page** (`visibilitychange`), the card asks «Message
+  envoyé ?» over the form: reopen the chat, «Je n’ai pas pu envoyer → être
+  rappelé» (the variant's call state, the phone focused), or «C’est envoyé».
+- **The server.** A `whatsapp` / `telegram` lead needs no phone (one typed
+  is held to the rule) and no consent, and is never sent back for a changed
+  price; `validateLead` knows the channel. A brand's own rule must not
+  refuse one for the postcode or the phone it was not asked — the testing
+  subpath's `messengerRuleDisagreements(site.lead)` lists where it does.
+- **Words**: `LeadCaptureMessengerText` — optional keys of the card's
+  `text`, a key left out the kit's in the page's language (`messengerTextOf`;
+  the defaults are `LEAD_CAPTURE_MESSENGER_TEXT`, kept out of
+  `LEAD_CAPTURE_TEXT` so the control's island never carries them). A brand
+  overrides by spreading: `{ ...LEAD_CAPTURE_TEXT.fr, messengerWhatsappCta: "Envoyer sur WhatsApp →" }`. **Parts**:
+  `messenger` (the variant's column), `messengerSlot` (the fixed box),
+  `messengerCta` (the main button: a messenger's, or the call's submit inside
+  the variant — its height and type, as `channel` / `primary` are the
+  control's), `messengerSecondary` (Telegram and «Être rappelé» beside it,
+  «ou via Telegram», «Rouvrir WhatsApp», the QR's «Être rappelé»),
+  `messengerSquare` (the icon squares of `split` / `swap`), `messengerSegment`
+  (a `segment` item), `messengerTile` (a `tiles` tile, an `urgency` answer) —
+  both after `messengerOption`, `messengerTrigger` (the channel picker's
+  button: `select`'s in the field — its tint — and `chip`'s),
+  `messengerPreview` (the message, the bot's card), `messengerPicker` (the
+  segment, the tiles, `select`'s field box, the chip, the drawer's body),
+  `messengerOption` (a picker's item, a `saga` / `sheet` card, a segment's
+  item, a tile), `messengerQr`,
+  `messengerReturn`, `messengerHint`. A part with a size keeps its line
+  height (`leading-6`) unless it sets one.
+- **Events**: every `LeadCapture` event carries `channels_available` and,
+  with a variant, `messenger_variant`; `lead_messenger_open {channel, device,
+  inapp, message_ref}`, `lead_messenger_return {channel, answer: sent |
+  failed, message_ref}`, `contact_intent_click {channel: telegram |
+  whatsapp_qr}`; `lead_form_submit` has `message_ref` and the posted
+  `channels_available`.
+- **Weight.** Each kind is its own chunk, fetched only by the arm that draws
+  it; the control pays for the dispatch alone, and the QR encoder for nobody
+  until a desktop tap. The server writes the variant into the page whole (no
+  boundary of its own: React would reveal a large one late, the contact block
+  missing for a frame); hydrating, the card waits for its variant's chunk,
+  the server's markup kept as it is. Until the chunk and the reference are
+  there, its messenger links lead nowhere (`aria-disabled`, no `href`); a
+  browser without scripts gets the control's phone and submit (`<noscript>`).
+
 ### One question per screen: `layout="steps"`
 
 ```tsx
@@ -417,8 +542,13 @@ Pieces any layout takes, for a card that fits a phone's screen:
   {price}" — a brand may write "≈ {price}"), then, with `taxCredit` (a ratio
   of the price a tax credit gives back, `0.5` for the French *crédit
   d'impôt*), what is left to pay (`priceTaxCredit`, `data-credit-cents`),
-  and the breakdown and `priceNote` behind a `<details>` ("Détail",
-  `priceDetail`). Read out as it changes, the line only.
+  and the breakdown and `priceNote` behind «Détail» (`text.priceDetail`): the
+  kit's `Popover`, over the card — opening it moves nothing — closed by a tap
+  outside or Escape and kept 8 px inside the screen; without a script (and
+  until hydration) a `<details>` opening in place. Parts: `priceDetail` the
+  trigger in both (the button, or the summary — style it directly, not
+  through `[&>summary]`), `priceDetailContent` the popover's box (or the
+  details' body). Read out as it changes, the line only.
 - **A question as cards** (`questions: { frequency: { display: "cards" } }`):
   one answer a line, each with the total it would make given the other
   answers (once they are given), and an optional `badges` tag per option.
@@ -777,10 +907,17 @@ export const POST = quoteRoute(site, { env: serverEnv, notifier, webhook, unavai
   `LEAD_WEBHOOK_KEY_ID` and `LEAD_WEBHOOK_SECRET` are required, and the URL
   must be `https:`, or `http:` to a `*.svc` / `*.svc.cluster.local` host or
   loopback — the body carries PII. All checked at boot.
-- **The channel.** `channelOf(lead)` is `form` or `callback`. For the
-  Service-Arb panel, map it through `panelChannel`: its `properties.channel`
-  is a closed set (`form` | `phone_inbound` | `callback`) that refuses the
-  whole event outside it, and a callback goes as `callback` (panel v0.3.0 on).
+- **The channel.** `channelOf(lead)` is `form`, `callback`, `whatsapp` or
+  `telegram`. For the Service-Arb panel use `ctx.channel` (or
+  `panelChannel(channel, panelMessenger)`): its `properties.channel` is a
+  closed set that refuses the whole event outside it; a callback goes as
+  `callback` (panel v0.3.0 on), a messenger lead as `form` until
+  `panelMessenger` is on.
+- **Messenger leads: `panelMessenger`, off.** On: `ctx.channel` says
+  `whatsapp` / `telegram`, and `ctx.messageRef` carries the lead's chat
+  reference for `properties.message_ref`. Off (the default, until the panel
+  takes them): a messenger lead goes as a `form`, without its reference —
+  the leads table and the mail keep both either way.
 - **Queued before the 303, sent after it.** The body is built once, from the
   lead and `ctx` (`leadId`, `brandId`, `locale`, `formId`, `at`, and a fresh
   `idempotencyKey` for the receiver to deduplicate by), and written to the
@@ -921,6 +1058,15 @@ adds no server path: a tap on a variant goes to the same URL with
   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.
+- **An experiment with no assignment is off.** The proxy assigns every
+  running experiment on the page the menu mounts on, so one with no
+  `ab_<key>` cookie (or missing from `current`) is shown `not running`
+  (`text.unassigned`), its variants disabled — the proxy would refuse the
+  force — and `–` on the chip. A test the panel only **paused** keeps its
+  visitors' cookies (dropping them would redraw everyone on resume), so the
+  brand's proxy lists paused tests for a QA browser only in the cookie
+  `<qaCookie>_off` (`ab__qa_off=lead_form,hero`); those read `not running`
+  too (`abRunning`).
 - **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
@@ -938,16 +1084,30 @@ adds no server path: a tap on a variant goes to the same URL with
   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.
+- **Pass the same `qaCookie` to `AnalyticsBoundary` and `quoteRoute`
+  (#219).** Every tap in the menu is a full reload, so a test visit would add
+  page views — and form events — to the place's traffic. The mark is the
+  sink's, not each event's: `analyticsSink(target, slug, id, qaCookie)` reads
+  the cookie at every capture and adds `forced: true` on a test visit, so the
+  boundary's page views and intents, the lead form's funnel
+  (`lead_form_view` … `lead_estimate_shown`) and the booking's
+  `lead_booking_open` / `lead_booking_done` all say it, and so will any event
+  added later. `quoteRoute`'s `qaCookie` reads the post's `Cookie` header the
+  same way for `lead_form_submit` and `lead_form_reject`. A test visit is the
+  cookie set with a non-empty value — any value — on both sides
+  (`qaVisit(cookies, name)`, exported for a brand's own server events).
+  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">
   ```
 
+  ```ts
+  // app/quote/route.ts
+  export const POST = quoteRoute(site, { env: serverEnv, notifier, unavailable, qaCookie: "ab__qa" });
+  ```
+
 The decisions are plain functions in the core (`abSwitcherVisible`,
 `abVariantUrl`, `abReset`, `abAssignments`), for a brand's own tests.
 

package/dist/core/ab-gate.js

@@ -11,7 +11,9 @@
 export function abSwitcherVisible(cookies, qaCookie, nodeEnv) {
     if (nodeEnv !== "production")
         return true;
-    // Presence and non-empty only, no decoding: every visitor runs this.
+    // Presence and non-empty only, no decoding: every visitor runs this. The
+    // rule is `qaVisit`'s (analytics.ts), copied so the switcher and the
+    // analytics island share no module; `forced.node.test.ts` holds them equal.
     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

@@ -16,6 +16,14 @@ export declare const AB_FORCE_PARAM = "ab_";
 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>;
+/**
+ * `assigned` without the tests the brand's panel has paused. The brand's proxy
+ * lists them, for a QA browser only, in the cookie `<qaCookie>_off`
+ * (`lead_form,hero`): a paused test keeps every visitor's assignment cookie —
+ * dropping it would redraw them on resume — so its cookie alone cannot tell
+ * the menu it is off, and a force of it is refused.
+ */
+export declare function abRunning(assigned: Readonly<Record<string, string>>, cookies: string, qaCookie: 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 {

package/dist/core/ab-switcher.js

@@ -38,6 +38,17 @@ export function abAssignments(cookies, keys) {
     }
     return out;
 }
+/**
+ * `assigned` without the tests the brand's panel has paused. The brand's proxy
+ * lists them, for a QA browser only, in the cookie `<qaCookie>_off`
+ * (`lead_form,hero`): a paused test keeps every visitor's assignment cookie —
+ * dropping it would redraw them on resume — so its cookie alone cannot tell
+ * the menu it is off, and a force of it is refused.
+ */
+export function abRunning(assigned, cookies, qaCookie) {
+    const paused = new Set((cookieValue(cookies, `${qaCookie}_off`) ?? "").split(","));
+    return Object.fromEntries(Object.entries(assigned).filter(([key]) => !paused.has(key)));
+}
 /** 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);

package/dist/core/accept.d.ts

@@ -1,6 +1,7 @@
 import { type RateLimiter } from "./antispam.js";
 import { type Lead, type LeadChannel } from "./lead.js";
 import type { PricingModel } from "./pricing/model.js";
+import type { ChannelsAvailable } from "./messenger.js";
 import type { Site } from "./site.js";
 /** Hidden fields the form carries besides what the visitor types. */
 export declare const LOCATION_FIELD = "location";
@@ -9,6 +10,12 @@ export declare const FORM_ID_FIELD = "form_id";
 /** The site's experiment assignment, posted so the submit counts in the right arm. */
 export declare const EXPERIMENT_FIELD = "experiment";
 export declare const VARIANT_FIELD = "variant";
+/**
+ * Which messengers the card offered (`channels_available`), posted so the
+ * submit's event says it as the card's own events do: an arm whose place had
+ * no WhatsApp drew the control, and its numbers must not mix with the arm's.
+ */
+export declare const CHANNELS_FIELD = "channels_available";
 /**
  * The page's analytics id (`ANALYTICS_ID`), posted by the script only: the
  * webhook's `ctx.analyticsId`, for `lead.created`'s `analytics_id`. Never
@@ -26,7 +33,14 @@ export declare const PRICE_CHANGED = "price_changed";
 export interface SubmitTags {
     experiment?: string;
     variant?: string;
+    channels_available?: ChannelsAvailable;
 }
+/**
+ * What a post says about the card it came from, for its events: the site's
+ * assignment and the messengers the card offered — slugs only, anything else
+ * dropped.
+ */
+export declare function submitTagsOf(form: FormData): SubmitTags;
 export type Outcome<L extends string> = 
 /**
  * `ref`: the lead's public reference (`leadRef`). `duplicate`: a resend of

package/dist/core/accept.js

@@ -1,6 +1,6 @@
 import { ANALYTICS_ID, experimentProps } from "./analytics.js";
 import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELDS, RENDERED_AT_FIELD, screen } from "./antispam.js";
-import { channelOf, MAX_FIELD, readCandidate, validateCandidate } from "./lead.js";
+import { channelOf, isMessengerChannel, MAX_FIELD, readCandidate, validateCandidate } from "./lead.js";
 import { answeredUnknown, flowOf, readEstimateInputs } from "./pricing/flow.js";
 import { priceOf } from "./pricing/price.js";
 /** Hidden fields the form carries besides what the visitor types. */
@@ -10,6 +10,12 @@ export const FORM_ID_FIELD = "form_id";
 /** The site's experiment assignment, posted so the submit counts in the right arm. */
 export const EXPERIMENT_FIELD = "experiment";
 export const VARIANT_FIELD = "variant";
+/**
+ * Which messengers the card offered (`channels_available`), posted so the
+ * submit's event says it as the card's own events do: an arm whose place had
+ * no WhatsApp drew the control, and its numbers must not mix with the arm's.
+ */
+export const CHANNELS_FIELD = "channels_available";
 /**
  * The page's analytics id (`ANALYTICS_ID`), posted by the script only: the
  * webhook's `ctx.analyticsId`, for `lead.created`'s `analytics_id`. Never
@@ -23,6 +29,16 @@ export const ANALYTICS_ID_FIELD = "analytics_id";
 export const SHOWN_CENTS_FIELD = "shown_cents";
 /** The refusal of a lead shown at a price that has since changed (`lead_error=price_changed`). */
 export const PRICE_CHANGED = "price_changed";
+const CHANNELS_AVAILABLE = ["wa,tg", "wa", "tg", "none"];
+/**
+ * What a post says about the card it came from, for its events: the site's
+ * assignment and the messengers the card offered — slugs only, anything else
+ * dropped.
+ */
+export function submitTagsOf(form) {
+    const channels = CHANNELS_AVAILABLE.find(c => c === form.get(CHANNELS_FIELD));
+    return { ...experimentProps(field(form, EXPERIMENT_FIELD), field(form, VARIANT_FIELD)), ...(channels ? { channels_available: channels } : {}) };
+}
 const FORM_ID = /^[a-z0-9_-]{1,32}$/;
 function field(form, name) {
     const value = form.get(name);
@@ -134,7 +150,9 @@ async function accept(site, form, clientKey, deps) {
     // is refused with the fresh price, for the visitor to confirm. A page from
     // before the field posts none, and is taken as before.
     const shown = field(form, SHOWN_CENTS_FIELD);
-    if (sale.price && shown !== null && /^\d{1,12}$/.test(shown) && Number(shown) !== sale.price.cents) {
+    // A messenger lead is posted as the visitor leaves for the chat: nobody is
+    // left to confirm a price, so it is taken at the server's, as any quote is.
+    if (sale.price && !isMessengerChannel(candidate.channel) && shown !== null && /^\d{1,12}$/.test(shown) && Number(shown) !== sale.price.cents) {
         deps.log.warn(`quote: a ${sale.flow} for ${candidate.subject} was shown at ${shown} and is now ${sale.price.cents}; sent back to confirm`);
         return { kind: "invalid", why: "price changed", field: PRICE_CHANGED, channel: channelOf(candidate), formId, locale, slug, cents: sale.price.cents };
     }
@@ -199,7 +217,7 @@ async function accept(site, form, clientKey, deps) {
             deps.log.error(`quote: lead ${id} is stored but its notification failed`, error);
         }
     });
-    const tags = experimentProps(field(form, EXPERIMENT_FIELD), field(form, VARIANT_FIELD));
+    const tags = submitTagsOf(form);
     deps.defer(() => deps.capture(lead, formId, tags));
     return { kind: "stored", id, ref, lead, locale, formId };
 }

package/dist/core/analytics.d.ts

@@ -19,8 +19,11 @@ export declare const EVENTS: {
     readonly estimateShown: "lead_estimate_shown";
     readonly bookingOpen: "lead_booking_open";
     readonly bookingDone: "lead_booking_done";
+    readonly messengerOpen: "lead_messenger_open";
+    readonly messengerReturn: "lead_messenger_return";
 };
-export type IntentChannel = "form_open" | "whatsapp" | "phone" | "sms" | "callback" | "booking";
+/** `whatsapp_qr`: on a computer, the QR code that opens WhatsApp on the phone was shown. */
+export type IntentChannel = "form_open" | "whatsapp" | "phone" | "sms" | "callback" | "booking" | "telegram" | "whatsapp_qr";
 /**
  * A form field as events name it — the role, never the brand's wire name, so
  * one field reads the same on every site. A brand's extra is its own name.
@@ -40,7 +43,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", "forced"];
+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", "channels_available", "message_ref", "messenger_variant", "inapp", "answer"];
 /**
  * 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
@@ -49,6 +52,11 @@ export declare const ALLOWED_PROPS: readonly ["brand_id", "location_id", "source
 export declare const ANALYTICS_ID: RegExp;
 /** What an experiment's assignment looks like on the wire: short slugs, nothing a person typed. */
 export declare const EXPERIMENT_SLUG: RegExp;
+declare const CHANNELS_AVAILABLE: readonly ["wa,tg", "wa", "tg", "none"];
+/** `channels_available` as an event property, or nothing when it is not one of the four. */
+export declare function channelsProps(value: string | null | undefined): {
+    channels_available: (typeof CHANNELS_AVAILABLE)[number];
+} | Record<string, never>;
 /** An experiment's assignment as event properties, or nothing when it is not a pair of slugs. */
 export declare function experimentProps(experiment: string | null | undefined, variant: string | null | undefined): {
     experiment: string;
@@ -69,6 +77,14 @@ export interface AnalyticsTarget {
     host: string;
     brandId: string;
 }
+/**
+ * Whether a `Cookie` string — `document.cookie` or a request's header — makes
+ * the visit a test: the QA cookie is set with a non-empty value, any value.
+ * The one rule both sides apply (the sink in the browser, `quoteRoute` on the
+ * server). `abSwitcherVisible` keeps its own copy on purpose: a module the
+ * switcher shared with the analytics island cost a chunk of its own.
+ */
+export declare function qaVisit(cookies: string, qaCookie: string): boolean;
 /**
  * Cookieless by construction: a beacon sink keeps its `distinct_id` in memory,
  * writes no cookie and no storage, and needs no consent banner. `sendBeacon`
@@ -76,5 +92,14 @@ export interface AnalyticsTarget {
  * followed by the page handing the visitor to another app. `distinctId`:
  * the visitor's id, held by the caller so a lead can name it; a random one
  * per sink without it.
+ *
+ * `qaCookie`: the brand's QA cookie (`AbSwitcher`'s). Every capture then checks
+ * `cookies` — a request's `Cookie` header on the server; left out, the
+ * browser's `document.cookie`, read at that capture — and adds `forced: true`
+ * on a test visit (`qaVisit`), so no event, present or future, has to
+ * remember it. Without `qaCookie` no cookie is read and no `forced` key sent.
+ * One wrapper for both cases, not a branch: on the place page that is ~10 B
+ * gz less than returning the bare sink.
  */
-export declare function analyticsSink(target: AnalyticsTarget, locationId: string | null, distinctId?: string): AnalyticsSink;
+export declare function analyticsSink(target: AnalyticsTarget, locationId: string | null, distinctId?: string, qaCookie?: string, cookies?: string): AnalyticsSink;
+export {};

package/dist/core/analytics.js

@@ -28,6 +28,11 @@ export const EVENTS = {
     // and — only where the provider says so on the page (Cal.com's embed) — booked.
     bookingOpen: "lead_booking_open",
     bookingDone: "lead_booking_done",
+    // A messenger CTA of a `messenger` variant: the lead was posted and the
+    // visitor sent on (`channel`, `device`, `inapp`) — and, back on the page,
+    // what they said of it (`answer`: `sent` | `failed`).
+    messengerOpen: "lead_messenger_open",
+    messengerReturn: "lead_messenger_return",
 };
 /**
  * Every property name an event may carry. A customer's phone or address comes
@@ -60,6 +65,17 @@ export const ALLOWED_PROPS = [
     // 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 messengers the card offered: `wa,tg` | `wa` | `tg` | `none` — on every
+    // event of a `LeadCapture`, so an arm that fell back to the control is told apart.
+    "channels_available",
+    // The lead's chat reference (`AQ-7K3F`): drawn at random, not personal data.
+    "message_ref",
+    // The `messenger` variant's kind (`segment`, `tiles`…).
+    "messenger_variant",
+    // `lead_messenger_open`: opened from an app's own browser (Instagram, TikTok…).
+    "inapp",
+    // `lead_messenger_return`: `sent` | `failed`.
+    "answer",
 ];
 /**
  * The beacon's `distinct_id` as a lead may carry it to the panel
@@ -69,6 +85,12 @@ export const ALLOWED_PROPS = [
 export const ANALYTICS_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 /** What an experiment's assignment looks like on the wire: short slugs, nothing a person typed. */
 export const EXPERIMENT_SLUG = /^[a-z0-9_-]{1,32}$/;
+const CHANNELS_AVAILABLE = ["wa,tg", "wa", "tg", "none"];
+/** `channels_available` as an event property, or nothing when it is not one of the four. */
+export function channelsProps(value) {
+    const known = CHANNELS_AVAILABLE.find(c => c === value);
+    return known ? { channels_available: known } : {};
+}
 /** An experiment's assignment as event properties, or nothing when it is not a pair of slugs. */
 export function experimentProps(experiment, variant) {
     return experiment && variant && EXPERIMENT_SLUG.test(experiment) && EXPERIMENT_SLUG.test(variant) ? { experiment, variant } : {};
@@ -80,6 +102,19 @@ export function experimentProps(experiment, variant) {
 export function countsAsPageView(pathname) {
     return !pathname.replace(/\/+$/, "").endsWith(THANKS);
 }
+/**
+ * Whether a `Cookie` string — `document.cookie` or a request's header — makes
+ * the visit a test: the QA cookie is set with a non-empty value, any value.
+ * The one rule both sides apply (the sink in the browser, `quoteRoute` on the
+ * server). `abSwitcherVisible` keeps its own copy on purpose: a module the
+ * switcher shared with the analytics island cost a chunk of its own.
+ */
+export function qaVisit(cookies, qaCookie) {
+    return cookies.split(";").some(pair => {
+        const eq = pair.indexOf("=");
+        return eq > 0 && pair.slice(0, eq).trim() === qaCookie && pair.slice(eq + 1).trim() !== "";
+    });
+}
 /**
  * Cookieless by construction: a beacon sink keeps its `distinct_id` in memory,
  * writes no cookie and no storage, and needs no consent banner. `sendBeacon`
@@ -87,13 +122,22 @@ export function countsAsPageView(pathname) {
  * followed by the page handing the visitor to another app. `distinctId`:
  * the visitor's id, held by the caller so a lead can name it; a random one
  * per sink without it.
+ *
+ * `qaCookie`: the brand's QA cookie (`AbSwitcher`'s). Every capture then checks
+ * `cookies` — a request's `Cookie` header on the server; left out, the
+ * browser's `document.cookie`, read at that capture — and adds `forced: true`
+ * on a test visit (`qaVisit`), so no event, present or future, has to
+ * remember it. Without `qaCookie` no cookie is read and no `forced` key sent.
+ * One wrapper for both cases, not a branch: on the place page that is ~10 B
+ * gz less than returning the bare sink.
  */
-export function analyticsSink(target, locationId, distinctId) {
-    return createBeaconSink({
+export function analyticsSink(target, locationId, distinctId, qaCookie, cookies) {
+    const sink = createBeaconSink({
         key: target.key ?? undefined,
         ...(distinctId !== undefined ? { distinctId } : {}),
         host: target.host,
         allowedProps: ALLOWED_PROPS,
         globalProps: locationId ? { brand_id: target.brandId, location_id: locationId } : { brand_id: target.brandId },
     });
+    return { capture: (event, props, options) => sink.capture(event, qaCookie && qaVisit(cookies ?? document.cookie, qaCookie) ? { ...props, forced: true } : props, options) };
 }

package/dist/core/channels.d.ts

@@ -3,9 +3,11 @@ import type { OpeningHours } from "./place/types.js";
 /**
  * The ways a visitor can reach the business, named as `contact_intent_click`
  * names them, so a channel and its event are one word. `form` is the quote
- * form; `callback` is the form cut to a phone number ("Rappelez-moi").
+ * form; `callback` is the form cut to a phone number ("Rappelez-moi");
+ * `telegram` is the brand's bot, opened with the lead's `message_ref` — drawn
+ * by a `messenger` variant only, never by the resolver's list.
  */
-export type CaptureChannel = "phone" | "whatsapp" | "sms" | "callback" | "form";
+export type CaptureChannel = "phone" | "whatsapp" | "sms" | "callback" | "form" | "telegram";
 /** What decides which channels exist: the place's numbers and hours. */
 export interface ChannelFacts {
     /** `contactOf(site, place)` — the place's numbers, the brand's as fallback. */
@@ -16,6 +18,8 @@ export interface ChannelFacts {
     sms?: boolean;
     /** Default: offered. A surface with no form to post it from turns it off. */
     callback?: boolean;
+    /** The bot's username, without `@` (`messengerFacts`); absent or `null` → no Telegram. */
+    telegram?: string | null;
 }
 export interface ChannelOptions {
     now: Date;
@@ -43,5 +47,9 @@ export declare function resolveChannels(facts: ChannelFacts, options: ChannelOpt
  * `&body=`) and Android (which reads `?body=`) accept.
  */
 export declare function smsHref(phone: string, body?: string): string;
-/** The link a channel opens, or `null` for the two that are forms on the page. */
-export declare function channelHref(channel: CaptureChannel, facts: Pick<ChannelFacts, "phone" | "whatsapp">, message?: string): string | null;
+/**
+ * The link a channel opens, or `null` for the two that are forms on the page.
+ * `message` is the prefilled text — for `telegram`, the bot's `start`
+ * parameter: the lead's `message_ref`.
+ */
+export declare function channelHref(channel: CaptureChannel, facts: Pick<ChannelFacts, "phone" | "whatsapp" | "telegram">, message?: string): string | null;