@evinvest/kitstart 0.17.0 → 0.19.1

package/README.md

@@ -18,7 +18,7 @@ stays in the brand.
 | `@evinvest/kitstart/proxy` | edge | `createProxy(site)`, `PROXY_MATCHER` |
 | `@evinvest/kitstart/next` | Next server (routes, RSC) | `quoteRoute`, `bookingRoute`, `confirmRoute`, `sitemapRoute`, `robotsRoute`, `ogRoute`, `healthRoute`, `createPlaceLoader`, `loadLocale`, `placeMetadata` / `brandMetadata` / `statusMetadata`, `metadataBase` |
 | `@evinvest/kitstart/next/config` | `next.config.ts`, `vitest.config.ts` | `withLanding`, `buildEnv` and the `assets/` readers |
-| `@evinvest/kitstart/react` | either side | `LangSwitch`, `CallBar`, `StatusScreen`, `PlaceDirectory`, `AreaChips`, `Coverage`, `MapFacade` (client), `QuoteFormShell`, `FormSelect` (client), `LeadCapture` (client), `LeadBooking` (client) and its adapters, `Faq`, `AnalyticsBoundary` (client), plus the kit and marketing pieces a landing composes with |
+| `@evinvest/kitstart/react` | either side | `LangSwitch`, `CallBar`, `StatusScreen`, `PlaceDirectory`, `AreaChips`, `Coverage`, `MapFacade` (client), `QuoteFormShell`, `FormSelect` (client) with `loadLazyParts` for tests, `LeadCapture` (client), `LeadBooking` (client) and its adapters, `Faq`, `AnalyticsBoundary` (client), plus the kit and marketing pieces a landing composes with |
 | `@evinvest/kitstart/testing` | a brand's vitest | `describeLandingContract(site, { globalsCss, proxySource, text })`, `describeLeadStoreContract(name, harness)`, `storefrontPlace`, `serviceAreaPlace`, `testLead` |
 | `@evinvest/kitstart/testing/e2e` | a brand's Playwright | `defineSectionSuite(sections)`, `settle(page, selector)`, `BREAKPOINTS` |
 | bin `kitstart-size` | plain node | `kitstart-size [<build root>] [--route …] [--budget …]`: first-load JS of a place page against the target in `tests/bundle_budget.txt` (passes with a warning up to its tolerance, 20 % by default — see [The bundle budget](#the-bundle-budget)); fails closed |
@@ -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.17.0"; # the version in package-lock.json
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.19.1"; # the version in package-lock.json
 inputs.ev.inputs.v_flakes.follows = "v_flakes";
 
 landing = ev.lib.mkLanding {
@@ -143,12 +143,16 @@ boundary never imports the site config.
 
 A form's select, for the fields inside `QuoteFormShell`. On the server and
 without JavaScript it is the kit's `NativeSelect` — a real `<select name>`
-the form posts as is. After hydration (`useSyncExternalStore`, so the
-server's HTML and the first client render agree) it is the kit's `Select`:
-the list drawn in the palette, never the platform's menu, and the value in an
-input of the same `name`. Both states are one box — height, width, border,
-radius and inset — so the swap moves nothing (checked by the template's e2e,
-which CI runs: `npm run check:template -- --e2e`).
+the form posts as is. Hydrated, it stays that select, live — a choice there
+reaches `onValueChange` — until the kit's `Select` is here: a chunk of its
+own, asked for once the page is idle, or sooner when a mouse moves over the
+field or it takes the focus. Then it is the kit's `Select`: the list drawn in
+the palette, never the platform's menu, and the value in an input of the
+same `name`. A press before that opens the platform's list at once, never a
+wait on the chunk; a select holding the focus (its picker may be open) is
+swapped only once the focus leaves. Both states are one box — height, width,
+border, radius and inset — so the swap moves nothing (checked by the
+template's e2e, which CI runs: `npm run check:template -- --e2e`).
 
 ```tsx
 <Field className="flex flex-col gap-2">
@@ -190,9 +194,11 @@ which CI runs: `npm run check:template -- --e2e`).
   letters jump, Enter chooses, Escape and Tab close with focus back on the
   trigger; the trigger is a `combobox` named by the `FieldLabel`, and so is
   its list, with the kit's focus ring.
-- **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).
+- **Weight.** The kit's `Select` — the list's placing, dismissal and keys —
+  is out of the first load, in `FormSelectKit`'s chunk; the native select and
+  the value's plumbing stay. With `@evinvest/uikit` before 0.28 a page whose
+  form uses the kit's `Field` still loads `Select` up front: that `Field`
+  imported `SelectTrigger` to recognise the control it labels.
 - **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
@@ -237,10 +243,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 +263,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`
@@ -359,6 +366,130 @@ it is the plain POST to `/quote` it always was.
   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 +548,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 +913,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

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;
@@ -94,3 +102,4 @@ export declare function qaVisit(cookies: string, qaCookie: string): boolean;
  * gz less than returning the bare sink.
  */
 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 } : {};

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;

package/dist/core/channels.js

@@ -1,5 +1,6 @@
 import { telHref, whatsappHref } from "@evinvest/marketing";
 import { DEFAULT_TIME_ZONE, isOpenAt, nextOpening } from "./place/hours.js";
+import { telegramHref } from "./messenger.js";
 import { isMobilePhone, normalizePhone } from "./phone.js";
 // Open: a person answers, so the call leads — calls convert many times what a
 // form does. Closed: a call rings out, so the channels that wait for the
@@ -21,6 +22,9 @@ export function resolveChannels(facts, options) {
         sms: facts.phone !== null && (facts.sms ?? isMobilePhone(facts.phone)),
         callback: facts.callback ?? true,
         form: true,
+        // Never in the lists below: a bot is offered by a `messenger` variant,
+        // with the lead posted first, not as one more bare link.
+        telegram: false,
     };
     const order = (open === false ? CLOSED : OPEN).filter(c => has[c]);
     const prefer = options.prefer;
@@ -35,7 +39,11 @@ export function smsHref(phone, body) {
     const number = normalizePhone(phone) ?? phone.replace(/[^\d+]/g, "");
     return body ? `sms:${number}?&body=${encodeURIComponent(body)}` : `sms:${number}`;
 }
-/** The link a channel opens, or `null` for the two that are forms on the page. */
+/**
+ * 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 function channelHref(channel, facts, message) {
     switch (channel) {
         case "phone":
@@ -44,6 +52,8 @@ export function channelHref(channel, facts, message) {
             return facts.whatsapp ? whatsappHref(facts.whatsapp, message) : null;
         case "sms":
             return facts.phone ? smsHref(facts.phone, message) : null;
+        case "telegram":
+            return facts.telegram ? telegramHref(facts.telegram, message) : null;
         case "callback":
         case "form":
             return null;

package/dist/core/lead-capture-text.d.ts

@@ -1,3 +1,4 @@
+import type { LeadCaptureMessengerText } from "./messenger-text.js";
 /**
  * Every word `LeadCapture` prints. Plain strings, not the copy contract's
  * `Said<F>`: the form is a client island, and a function cannot cross from a
@@ -10,9 +11,12 @@
  *
  * The flows' words (`LeadCaptureFlowText`) are optional here so a brand's own
  * text object written before them still type-checks; a key left out falls
- * back to the kit's, in the page's language (`flowTextOf`).
+ * back to the kit's, in the page's language (`flowTextOf`). The `messenger`
+ * variants' words (`LeadCaptureMessengerText`) likewise (`messengerTextOf`),
+ * their defaults in `LEAD_CAPTURE_MESSENGER_TEXT` — not spread in here: this
+ * module reaches the client island, and only a variant's chunk needs them.
  */
-export interface LeadCaptureText extends Partial<LeadCaptureFlowText> {
+export interface LeadCaptureText extends Partial<LeadCaptureFlowText>, Partial<LeadCaptureMessengerText> {
     title: string;
     lede: string;
     needLabel: string;

package/dist/core/lead.d.ts

@@ -60,6 +60,12 @@ export interface LeadSchema<S extends string> {
      * the landing contract holds it to the form's phone rule, so the server
      * never refuses a number the form let through. A bare string is a reason
      * about the whole form (`field: "form"`).
+     *
+     * A messenger lead (`whatsapp`, `telegram`) answers to it too: the
+     * candidate carries its `channel`, and `validateLead` asks no phone of one
+     * — the chat is how we answer. The contract holds a brand's own rule to
+     * that (`messengerRuleDisagreements`): a messenger lead is never refused
+     * for a postcode or a phone it was not asked for.
      */
     validate?: (lead: LeadCandidate) => LeadVerdict;
     /**
@@ -84,13 +90,17 @@ export interface LeadSchema<S extends string> {
     flows?: LeadFlows;
 }
 /**
- * How the lead was asked for: the quote form, or "call me back" — the form cut
- * to a phone number. Posted as `CHANNEL_FIELD`; anything else, or nothing (a
- * page cached before the field existed), is `form`.
+ * How the lead was asked for: the quote form, "call me back" — the form cut
+ * to a phone number — or a messenger the visitor was sent on to, the lead
+ * posted first (`whatsapp`, `telegram`). Posted as `CHANNEL_FIELD`; anything
+ * else, or nothing (a page cached before the field existed), is `form`.
  */
-export type LeadChannel = "form" | "callback";
+export type LeadChannel = "form" | "callback" | "whatsapp" | "telegram";
 export declare const LEAD_CHANNELS: readonly LeadChannel[];
 export declare const CHANNEL_FIELD = "channel";
+/** A lead whose answer goes by chat: the phone is optional, no consent is asked. */
+export type MessengerChannel = Extract<LeadChannel, "whatsapp" | "telegram">;
+export declare function isMessengerChannel(channel: LeadChannel | undefined): channel is MessengerChannel;
 /**
  * The callback's consent: a checkbox whose value is the sentence it shows, in
  * the language it shows it, so the row keeps what was agreed to. Absent → the
@@ -111,7 +121,8 @@ export declare const SUBMISSION_ID: RegExp;
 export declare const LEAD_ERROR_PARAM = "lead_error";
 /** A refusal the server sent back: which of the card's forms, and the field it is about. */
 export interface LeadError {
-    channel: LeadChannel;
+    /** A messenger lead is posted behind the visitor's back: no form of the card shows its refusal. */
+    channel: Extract<LeadChannel, "form" | "callback">;
     field: string;
 }
 /** What a refused field may be named: a slug, never markup. */
@@ -150,8 +161,14 @@ export declare const CARD_FIELD = "card";
 export declare const CARD_ID: RegExp;
 /** A rule's answer as a rejection: a bare reason, or a field that is not a slug, is about the `form`. */
 export declare function rejectionOf(verdict: LeadVerdict): LeadRejection | null;
-/** The default form rule: a number we can call — the one the form blocks on (`phoneProblem`). */
-export declare function validateLead(lead: Pick<LeadCandidate, "mobile">): LeadRejection | null;
+/**
+ * The default form rule: a number we can call — the one the form blocks on
+ * (`phoneProblem`). A messenger lead needs none, but one typed must be a
+ * number: the operator may call it.
+ */
+export declare function validateLead(lead: Pick<LeadCandidate, "mobile"> & {
+    channel?: LeadChannel | undefined;
+}): LeadRejection | null;
 /** The default callback rule: the same number rule, worded for the log. */
 export declare function validateCallbackLead(lead: Pick<LeadCandidate, "mobile">): LeadRejection | null;
 /**
@@ -189,6 +206,12 @@ export interface Lead {
     flow?: LeadFlow;
     /** Only on an `estimate` or `fixed` lead: the price the server computed. */
     price?: LeadPrice;
+    /**
+     * The reference the visitor's chat message carries (`AQ-7K3F`,
+     * `MESSAGE_REF`), posted by the card that minted it — on a form lead too,
+     * when its success sends the visitor on to a messenger. Not personal data.
+     */
+    messageRef?: string;
 }
 /**
  * The price a lead was taken at — the server's own number, from the posted
@@ -250,10 +273,10 @@ export interface LeadStore {
  * The lead schema's version, shared by every adapter: 1 the Rust server's
  * table (`job`, `zip`, `mobile`, `at`), 2 + the place, 3 + the spam verdict,
  * 4 + the brand's extras, 5 + the channel and the callback's consent, 6 + the
- * script's submission id, unique, 7 + the flow and the price it was taken at.
- * Append only.
+ * script's submission id, unique, 7 + the flow and the price it was taken at,
+ * 8 + the messenger reference (`message_ref`). Append only.
  */
-export declare const LEAD_SCHEMA_VERSION = 7;
+export declare const LEAD_SCHEMA_VERSION = 8;
 /** A field is capped, not rejected: a long answer is still a customer. */
 export declare const MAX_FIELD = 200;
 /**