@pmeweb/plugin-chat 0.0.0-stage → 1.1.0

package/src/widget.js

@@ -0,0 +1,616 @@
+// The chat panel, the lazy part (dist/widget.js). The inline trigger imports it on the first touch
+// of the bubble and calls `mountChat(root)`, then `open()` on a click. Everything with a cost lives
+// here: the panel, Turnstile, the POST that opens a conversation, the socket.
+//
+// THE PANEL is a dialog (spec § 3.1 « Accessibility »): aria-modal, labelled by the name in its
+// header, focus kept inside while open, closed by Escape and its close button and NEVER by a click
+// outside, focus back on the bubble. A finished answer is announced once in a polite live region,
+// never each streamed fragment.
+//
+// THE CONVERSATION starts on the first message: a Turnstile token (action `chat`), POST
+// /api/chat/start, the ids kept in sessionStorage (they survive a reload of the tab, not a new
+// tab), then the socket and `hello { since }`. Every message carries a client-made id, so a resend
+// after a reconnect is stored once (pmeweb-chat dedups by id).
+//
+// CLOSE CODES (spike-findings.md): any close outside 4000-4999 (1006 when pmeweb-chat is force
+// deployed, a network drop) reconnects with backoff 1, 2, 4 ... 30 s and asks `since` the last seq
+// seen. A 44xx code means « do not reconnect »: 4426 (the page is older than the service) asks for a
+// reload, 4404/4410/4401 end the conversation calmly. A message typed while the socket is down is
+// QUEUED and sent on open (the spike's client dropped one); after 3 sends without an echo it shows
+// « Non envoyé » with « Réessayer ».
+//
+// The mode comes from the service: `human` shows the owner's name, « Vous répond en direct » and the
+// green dot; `bot` shows « Assistant virtuel » and no dot (spec § 6: a dot says a person is here).
+// `fallback` (daily cap, model down) and a refused start show the contact form, which posts the
+// same lead through /api/chat/start. The `lead` frame fires window.pmw?.event('chat-lead') once.
+//
+// PHOTOS (config `photos: true`, spec § 3.1): up to 3 per conversation, shrunk HERE in a canvas to a
+// 1600 px JPEG (a canvas keeps no EXIF, so the GPS position a phone writes goes with it), posted to
+// /api/chat/photo with the message's client id, shown from the local copy (never fetched back). A
+// photo from an earlier visit of the tab shows « Photo envoyée ». The picker is a real file input
+// inside its label, visually hidden but focusable; refusals are read out in a role=alert line.
+//
+// THE DEMO (manifest preview: test). Off the site's real hosts (apercu.pmeweb.ca, workers.dev,
+// astro dev, or a page without the #pmw-hosts tag: fail closed) the panel never calls /api/chat/*,
+// loads no Turnstile, opens no socket and reads no stored conversation: it shows the page's opener,
+// a visitor's question drawn from it (demoQuestion) and a canned answer, with the composer disabled
+// and a hint saying why. The client sees their face and colours in the « Contenu » preview.
+import css from './widget.css?inline'
+import { isCanonical } from '@pmeweb/loader'
+import { addScript as loadTurnstile, resetToken, tokenReady } from '@pmeweb/turnstile'
+import { CLOSE, MAX_TEXT } from './protocol.js'
+import { fill, langOf, stringsFor } from './strings.js'
+
+export const SESSION_KEY = 'pmw-chat'
+export const BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000]
+export const MAX_TRIES = 3
+export const GOAL = 'chat-lead'
+export const MAX_PHOTOS = 3
+export const PHOTO_EDGE = 1600
+export const PHOTO_QUALITY = 0.85
+const TYPING_SEND_MS = 3000
+const TYPING_SHOW_MS = 8000
+
+const CAMERA_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M4 8h3l2-3h6l2 3h3v11H4z" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/><circle cx="12" cy="13" r="3.5" fill="none" stroke="currentColor" stroke-width="2"/></svg>'
+
+/** The longest edge to PHOTO_EDGE, re-encoded as JPEG: the canvas drops every EXIF field. */
+async function shrinkPhoto(win, file) {
+  const bmp = await win.createImageBitmap(file, { imageOrientation: 'from-image' })
+  const scale = Math.min(1, PHOTO_EDGE / Math.max(bmp.width, bmp.height))
+  const w = Math.max(1, Math.round(bmp.width * scale))
+  const h = Math.max(1, Math.round(bmp.height * scale))
+  const canvas = win.document.createElement('canvas')
+  canvas.width = w
+  canvas.height = h
+  canvas.getContext('2d').drawImage(bmp, 0, 0, w, h)
+  bmp.close?.()
+  return new Promise((resolve, reject) => canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('encode'))), 'image/jpeg', PHOTO_QUALITY))
+}
+
+const OURS = { fr: { nos: 'vos', notre: 'votre', nous: 'vous' }, en: { our: 'your', us: 'you', we: 'you' } }
+const SUBJECT = { fr: /^une question sur (.+?)\s*\?$/i, en: /^(?:a |any )?questions? (?:about|on) (.+?)\s*\?$/i }
+
+/** The demo's visitor question: the opener's subject from the visitor's side, else a generic one. */
+export function demoQuestion(opener, lang) {
+  const l = langOf(lang)
+  const s = stringsFor(l)
+  const m = String(opener ?? '').trim().match(SUBJECT[l])
+  if (!m) return s.demoQuestion
+  const topic = m[1].replace(/[\p{L}’']+/gu, (w) => OURS[l][w.toLowerCase()] ?? w)
+  return fill(s.demoAsk, { topic })
+}
+
+const X_ICON = '<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M3 3l10 10M13 3L3 13" stroke="currentColor" stroke-width="2" stroke-linecap="round" fill="none"/></svg>'
+
+function el(doc, tag, attrs = {}, text) {
+  const e = doc.createElement(tag)
+  for (const [k, v] of Object.entries(attrs)) if (v !== null && v !== undefined && v !== false) e.setAttribute(k, v === true ? '' : v)
+  if (text !== undefined) e.textContent = text
+  return e
+}
+
+const defaultTurnstile = (win) => ({
+  load: () => loadTurnstile(win.document),
+  async token(form) {
+    await tokenReady(form, { win })
+    return form.querySelector('input[name="cf-turnstile-response"]')?.value ?? ''
+  },
+  reset: (form) => resetToken(form, { win }),
+})
+
+export function mountChat(root, deps = {}) {
+  if (root.pmwChat) return root.pmwChat
+  const win = deps.win ?? window
+  const doc = win.document
+  const WS = deps.WebSocket ?? win.WebSocket
+  const fetchImpl = deps.fetch ?? ((...a) => win.fetch(...a))
+  const turnstile = deps.turnstile ?? defaultTurnstile(win)
+  const uuid = deps.uuid ?? (() => win.crypto.randomUUID())
+  const shrink = deps.shrink ?? ((file) => shrinkPhoto(win, file))
+  // A data: URL, not a blob: one: site CSPs allow `img-src data:` (boilerplate worker), not blob:.
+  const preview = deps.preview ?? ((blob) => new Promise((resolve, reject) => {
+    const r = new win.FileReader()
+    r.onload = () => resolve(String(r.result))
+    r.onerror = () => reject(r.error)
+    r.readAsDataURL(blob)
+  }))
+  let cfg = {}
+  try { cfg = JSON.parse(root.querySelector('[data-pmw-chat-config]')?.textContent ?? '{}') } catch { /* defaults */ }
+  const lang = langOf(cfg.lang)
+  const s = stringsFor(lang, cfg.strings)
+  const opener = root.dataset.pmwChatOpener ?? ''
+  const bubble = root.querySelector('.pmw-chat__bubble')
+  // cfg.demo: Chat.astro switched off, rendered only for a « Contenu » preview build.
+  const demo = deps.demo ?? (cfg.demo === true || !isCanonical({ doc, hostname: win.location.hostname }))
+
+  if (!doc.getElementById('pmw-chat-style')) doc.head.append(el(doc, 'style', { id: 'pmw-chat-style' }, css))
+
+  // ---- the panel --------------------------------------------------------------------------
+  const panel = el(doc, 'div', { class: 'pmw-chat__panel', role: 'dialog', 'aria-modal': 'true', 'aria-labelledby': 'pmw-chat-name', hidden: true })
+  const head = el(doc, 'div', { class: 'pmw-chat__head' })
+  const avatar = root.querySelector('.pmw-chat__avatar')?.cloneNode(true) ?? el(doc, 'span', { class: 'pmw-chat__avatar', 'aria-hidden': 'true' })
+  // An icon may hold a <mask id>: the clone gets its own ids, since the bubble (and the original
+  // mask with it) is display:none while the panel is open.
+  for (const x of avatar.querySelectorAll('[id]')) {
+    const id = x.id
+    x.id = `${id}-head`
+    for (const u of avatar.querySelectorAll(`[mask="url(#${id})"]`)) u.setAttribute('mask', `url(#${id}-head)`)
+  }
+  const who = el(doc, 'div', { class: 'pmw-chat__who' })
+  const name = el(doc, 'p', { class: 'pmw-chat__name', id: 'pmw-chat-name' })
+  const role = el(doc, 'p', { class: 'pmw-chat__role' })
+  const dot = el(doc, 'span', { class: 'pmw-chat__dot', 'aria-hidden': 'true', hidden: true })
+  const closeBtn = el(doc, 'button', { type: 'button', class: 'pmw-chat__close', 'aria-label': s.close })
+  closeBtn.innerHTML = X_ICON
+  who.append(name, role)
+  head.append(avatar, who, dot, closeBtn)
+
+  const notice = el(doc, 'p', { class: 'pmw-chat__notice' }, s.automated)
+  if (cfg.privacyHref) {
+    notice.append(' ')
+    notice.append(el(doc, 'a', { href: cfg.privacyHref }, s.privacy))
+  }
+  const log = el(doc, 'ol', { class: 'pmw-chat__log' })
+  const greeting = el(doc, 'li', { class: 'pmw-chat__msg pmw-chat__msg--bot pmw-chat__msg--greeting' }, opener)
+  const typing = el(doc, 'li', { class: 'pmw-chat__typing', 'aria-hidden': 'true', hidden: true })
+  typing.append(el(doc, 'span'), el(doc, 'span'), el(doc, 'span'))
+  log.append(greeting)
+  const state = el(doc, 'p', { class: 'pmw-chat__state', role: 'status' })
+  const announcer = el(doc, 'p', { class: 'pmw-chat__sr', 'aria-live': 'polite' })
+
+  const widget = (form) => el(doc, 'div', {
+    class: 'cf-turnstile pmw-turnstile', 'data-sitekey': cfg.siteKey ?? '', 'data-action': 'chat', 'data-theme': 'light',
+    'data-language': lang, 'data-appearance': 'interaction-only', 'data-size': 'flexible',
+  })
+  const composer = el(doc, 'form', { class: 'pmw-chat__composer', novalidate: true })
+  const input = el(doc, 'textarea', { id: 'pmw-chat-input', name: 'message', rows: '2', maxlength: String(MAX_TEXT), autocomplete: 'off', disabled: demo, 'aria-describedby': demo ? 'pmw-chat-demo-hint' : null })
+  const send = el(doc, 'button', { type: 'submit', class: 'pmw-chat__send', disabled: demo }, s.send)
+  composer.append(el(doc, 'label', { class: 'pmw-chat__sr', for: 'pmw-chat-input' }, s.messageLabel), input, send)
+  if (demo) composer.append(el(doc, 'p', { class: 'pmw-chat__hint', id: 'pmw-chat-demo-hint' }, s.demoHint))
+  else composer.append(widget(composer))
+  let picker = null
+  const photoError = el(doc, 'p', { class: 'pmw-chat__error pmw-chat__photo-error', role: 'alert' })
+  if (cfg.photos === true) {
+    const attach = el(doc, 'label', { class: 'pmw-chat__attach' })
+    picker = el(doc, 'input', { type: 'file', class: 'pmw-chat__sr', accept: 'image/*', multiple: true, 'aria-describedby': 'pmw-chat-photo-hint', disabled: demo })
+    attach.innerHTML = CAMERA_ICON
+    attach.prepend(picker)
+    attach.append(el(doc, 'span', { class: 'pmw-chat__sr' }, s.attachPhoto))
+    composer.insertBefore(attach, input)
+    composer.append(el(doc, 'p', { class: 'pmw-chat__hint', id: 'pmw-chat-photo-hint' }, s.photoHint), photoError)
+  }
+
+  const ended = el(doc, 'div', { class: 'pmw-chat__ended', hidden: true })
+  const endedText = el(doc, 'p', {}, s.ended)
+  const restart = el(doc, 'button', { type: 'button', class: 'pmw-chat__restart' }, s.newConversation)
+  ended.append(endedText, restart)
+
+  const fallback = el(doc, 'form', { class: 'pmw-chat__fallback', novalidate: true, hidden: true, 'aria-labelledby': 'pmw-chat-fb-title' })
+  const fbIntro = el(doc, 'p', { class: 'pmw-chat__fb-intro' })
+  const field = (key, tag, attrs) => {
+    const id = `pmw-chat-fb-${key}`
+    const wrap = el(doc, 'div', { class: 'pmw-chat__field' })
+    wrap.append(el(doc, 'label', { for: id }, s[key]), el(doc, tag, { id, name: key, required: true, ...attrs }))
+    return wrap
+  }
+  const fbError = el(doc, 'p', { class: 'pmw-chat__error', role: 'alert' })
+  fallback.append(
+    el(doc, 'p', { class: 'pmw-chat__fb-title', id: 'pmw-chat-fb-title' }, s.fallbackTitle), fbIntro,
+    field('name', 'input', { autocomplete: 'name', maxlength: '100' }),
+    field('contact', 'input', { autocomplete: 'on', maxlength: '200' }),
+    field('need', 'textarea', { rows: '3', maxlength: '2000' }),
+    fbError, el(doc, 'button', { type: 'submit', class: 'pmw-chat__send' }, s.fallbackSend),
+  )
+  if (!demo) fallback.append(widget(fallback))
+  const body = el(doc, 'div', { class: 'pmw-chat__body' })
+  body.append(notice, log, state, ended, fallback)
+  panel.append(head, body, composer, announcer)
+  root.append(panel)
+
+  // ---- state ------------------------------------------------------------------------------
+  let session = null
+  if (!demo) try { session = JSON.parse(win.sessionStorage.getItem(SESSION_KEY) ?? 'null') } catch { session = null }
+  const save = () => { try { win.sessionStorage.setItem(SESSION_KEY, JSON.stringify(session)) } catch { /* this tab only */ } }
+  let ws = null
+  let attempt = 0
+  let retryTimer = null
+  let starting = null
+  let lastSeq = 0
+  let mode = 'bot'
+  let ownerName = null
+  let over = false
+  let lastTyping = 0
+  let typingTimer = null
+  const seen = new Set()
+  const pending = new Map()
+  /** Ids of photo messages in this conversation (sent or echoed), and uploads under way. */
+  const photosSent = new Set()
+  let photosBusy = 0
+
+  // The demo's name is the portal preview's, from the fragment (phase 4 spec 2.4); never on a real host.
+  const fragmentName = () => new URLSearchParams(win.location.hash.slice(1)).get('pmw-chat-botName')?.trim() || null
+  let demoName = demo ? fragmentName() : null
+  const botName = () => (demo ? demoName : session?.botName || null)
+  function header() {
+    const human = mode === 'human'
+    name.textContent = human ? (ownerName || s.assistant) : (botName() || s.assistant)
+    role.textContent = human ? s.live : (botName() ? s.assistant : '')
+    role.hidden = role.textContent === ''
+    dot.hidden = !human
+    panel.dataset.mode = mode
+  }
+  header()
+  const showState = (text) => { state.textContent = text ?? ''; state.hidden = !text }
+  showState('')
+
+  // ---- messages ---------------------------------------------------------------------------
+  const speaker = (m) => (m.role === 'visitor' ? s.you : m.role === 'owner' ? (m.by || ownerName || s.assistant) : (botName() || s.assistant))
+  function line(id, roleName) {
+    const li = el(doc, 'li', { class: `pmw-chat__msg pmw-chat__msg--${roleName}`, 'data-id': id })
+    const who = el(doc, 'span', { class: 'pmw-chat__sr' })
+    const text = el(doc, 'span', { class: 'pmw-chat__text' })
+    li.append(who, text)
+    log.insertBefore(li, typing.parentNode === log ? typing : null)
+    return li
+  }
+  const find = (id) => [...log.querySelectorAll('li[data-id]')].find((li) => li.dataset.id === id)
+  const setText = (li, m, text) => {
+    li.firstChild.textContent = fill(s.said, { name: speaker(m), text: '' })
+    // A photo with no local copy (an earlier visit of the tab) says so; the image is never fetched back.
+    li.lastChild.textContent = text === '' && m.photos?.length && !li.querySelector('img') ? s.photoSent : text
+  }
+  function hideTyping() {
+    typing.hidden = true
+    win.clearTimeout(typingTimer)
+  }
+  function render(m, { announce }) {
+    if (seen.has(m.seq)) return
+    seen.add(m.seq)
+    lastSeq = Math.max(lastSeq, m.seq)
+    let li = find(m.id)
+    if (!li) li = line(m.id, m.role)
+    li.classList.remove('is-streaming', 'is-pending', 'is-failed')
+    li.querySelector('.pmw-chat__retry')?.remove()
+    setText(li, m, m.text)
+    if (m.role === 'visitor') {
+      pending.delete(m.id)
+      if (m.photos?.length) photosSent.add(m.id)
+    }
+    else {
+      hideTyping()
+      if (announce) announcer.textContent = fill(s.said, { name: speaker(m), text: m.text })
+      if (panel.hidden) root.setAttribute('data-unread', '')
+    }
+    scroll()
+  }
+  function delta(id, text) {
+    hideTyping()
+    let li = find(id)
+    if (!li) {
+      li = line(id, 'bot')
+      li.classList.add('is-streaming')
+      setText(li, { role: 'bot' }, '')
+    }
+    li.lastChild.textContent += text
+    scroll()
+  }
+  const scroll = () => { log.scrollTop = log.scrollHeight }
+  if (demo) {
+    setText(line('demo-question', 'visitor'), { role: 'visitor' }, demoQuestion(opener, lang))
+    const answer = line('demo-answer', 'bot')
+    setText(answer, { role: 'bot' }, s.demoAnswer)
+    win.addEventListener('hashchange', () => {
+      demoName = fragmentName()
+      header()
+      setText(answer, { role: 'bot' }, s.demoAnswer)
+    })
+  }
+
+  function failed(entry) {
+    entry.failed = true
+    entry.li.classList.remove('is-pending')
+    entry.li.classList.add('is-failed')
+    if (entry.li.querySelector('.pmw-chat__retry')) return
+    const note = el(doc, 'span', { class: 'pmw-chat__retry' }, `${s.notSent} `)
+    const btn = el(doc, 'button', { type: 'button' }, s.retry)
+    btn.addEventListener('click', () => {
+      entry.failed = false
+      entry.tries = 0
+      note.remove()
+      entry.li.classList.replace('is-failed', 'is-pending')
+      if (!session) begin()
+      else if (isOpen()) transmit(entry)
+      else connect()
+    })
+    note.append(btn)
+    entry.li.append(note)
+  }
+  const isOpen = () => !!ws && ws.readyState === 1
+  function transmit(entry) {
+    if (entry.failed || !isOpen()) return
+    if (entry.tries >= MAX_TRIES) return failed(entry)
+    entry.tries++
+    ws.send(JSON.stringify({ type: 'message', id: entry.id, text: entry.text }))
+  }
+
+  // ---- the socket -------------------------------------------------------------------------
+  function connect() {
+    if (!session || over || ws) return
+    win.clearTimeout(retryTimer)
+    const proto = win.location.protocol === 'https:' ? 'wss:' : 'ws:'
+    const q = new URLSearchParams({ c: session.c, k: session.k })
+    const sock = new WS(`${proto}//${win.location.host}/api/chat/ws?${q}`)
+    ws = sock
+    sock.onopen = () => {
+      attempt = 0
+      showState('')
+      sock.send(JSON.stringify({ type: 'hello', since: lastSeq }))
+      for (const entry of pending.values()) transmit(entry)
+    }
+    sock.onmessage = (e) => {
+      let m
+      try { m = JSON.parse(e.data) } catch { return }
+      frame(m)
+    }
+    sock.onclose = (e) => {
+      if (ws === sock) ws = null
+      for (const entry of pending.values()) if (entry.tries >= MAX_TRIES) failed(entry)
+      if (e.code >= 4000 && e.code < 5000) return refused(e.code)
+      if (over) return
+      showState(s.reconnecting)
+      const wait = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]
+      attempt++
+      retryTimer = win.setTimeout(connect, wait)
+    }
+  }
+  function refused(code) {
+    if (code === CLOSE.rpc) return end(s.reload, false)
+    end(s.ended, true)
+  }
+  function end(text, canRestart) {
+    over = true
+    win.clearTimeout(retryTimer)
+    showState('')
+    endedText.textContent = text
+    restart.hidden = !canRestart
+    ended.hidden = false
+    composer.hidden = true
+    for (const entry of pending.values()) failed(entry)
+  }
+  function status(m) {
+    mode = m.mode === 'human' ? 'human' : 'bot'
+    ownerName = typeof m.ownerName === 'string' ? m.ownerName : null
+    header()
+    if (m.closed) end(s.ended, true)
+  }
+  function frame(m) {
+    switch (m?.type) {
+      case 'history':
+        for (const x of m.messages ?? []) render(x, { announce: false })
+        return status(m)
+      case 'message':
+        return render(m.msg, { announce: m.msg?.role !== 'visitor' })
+      case 'delta':
+        return delta(m.id, m.text)
+      case 'typing':
+        if (m.role === 'visitor') return
+        typing.hidden = false
+        log.append(typing)
+        win.clearTimeout(typingTimer)
+        typingTimer = win.setTimeout(hideTyping, TYPING_SHOW_MS)
+        return scroll()
+      case 'status':
+        return status(m)
+      case 'fallback':
+        return showFallback(m.reason === 'cap' ? s.fallbackCap : s.fallbackDown)
+      case 'lead':
+        return lead()
+      case 'error':
+        if (m.code === 'closed' || m.code === 'deleted') end(s.ended, true)
+    }
+  }
+  // Once per conversation: the flag rides in the session, so a reload does not count it again.
+  let fired = false
+  function lead() {
+    if (fired || session?.lead) return
+    fired = true
+    if (session) { session.lead = true; save() }
+    try { win.pmw?.event(GOAL) } catch { /* the beacon never breaks the chat */ }
+  }
+
+  // ---- starting a conversation ------------------------------------------------------------
+  async function post(form, extra) {
+    let token = ''
+    try { token = await turnstile.token(form) } catch { token = '' }
+    let res
+    let data = null
+    try {
+      res = await fetchImpl('/api/chat/start', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token, lang, page: win.location.pathname, ...extra }),
+      })
+      data = await res.json()
+    } catch {
+      res = null
+    }
+    try { turnstile.reset(form) } catch { /* a token is single-use; the next post asks again */ }
+    if (res?.ok && data) return { ok: true, data }
+    const error = res?.status === 403 ? s.turnstile : res?.status === 429 ? s.tooMany : null
+    return { ok: false, error, cap: res?.status === 409 && data?.error === 'cap' }
+  }
+  function begin() {
+    if (starting || session) return starting
+    showState(s.connecting)
+    starting = post(composer, {}).then((r) => {
+      starting = null
+      if (r.ok && r.data.conversationId && r.data.visitorKey) {
+        session = { c: r.data.conversationId, k: r.data.visitorKey, botName: typeof r.data.botName === 'string' ? r.data.botName : null }
+        save()
+        header()
+        connect()
+        return
+      }
+      for (const entry of pending.values()) failed(entry)
+      if (r.error) return showState(r.error)
+      showState('')
+      // 409 cap: the visitor's conversations for the day are used up (pmeweb-chat counts them per IP).
+      showFallback(r.cap ? s.fallbackCap : s.unavailable)
+    })
+    return starting
+  }
+  function showFallback(text) {
+    fbIntro.textContent = text
+    fallback.hidden = false
+    composer.hidden = true
+    fallback.querySelector('input')?.focus()
+  }
+  fallback.addEventListener('submit', async (e) => {
+    e.preventDefault()
+    const v = (k) => fallback.elements[k].value.trim()
+    const fields = { name: v('name'), contact: v('contact'), need: v('need') }
+    if (!fields.name || !fields.contact || !fields.need) {
+      fbError.textContent = s.fallbackMissing
+      return
+    }
+    fbError.textContent = ''
+    const r = await post(fallback, { fallbackLead: fields })
+    if (!r.ok) {
+      fbError.textContent = r.error ?? s.unavailable
+      return
+    }
+    fallback.replaceChildren(el(doc, 'p', { class: 'pmw-chat__fb-done', role: 'status' }, s.fallbackSent))
+    lead()
+  })
+
+  // ---- photos -------------------------------------------------------------------------------
+  const PHOTO_ERRORS = { 413: 'photoTooLarge', 415: 'photoUnreadable', 409: 'photoLimit', 429: 'tooMany' }
+  async function sendPhoto(file) {
+    let blob
+    let src
+    try {
+      blob = await shrink(file)
+      src = await preview(blob)
+    } catch {
+      photoError.textContent = s.photoUnreadable
+      return
+    }
+    const id = uuid()
+    const li = line(id, 'visitor')
+    li.classList.add('is-pending')
+    li.insertBefore(el(doc, 'img', { class: 'pmw-chat__photo', src, alt: s.photoAlt }), li.lastChild)
+    setText(li, { role: 'visitor' }, '')
+    scroll()
+    if (!session) await begin()
+    let res = null
+    if (session) {
+      const q = new URLSearchParams({ c: session.c, k: session.k, id })
+      try {
+        res = await fetchImpl(`/api/chat/photo?${q}`, { method: 'POST', headers: { 'content-type': 'image/jpeg' }, body: blob })
+      } catch {
+        res = null
+      }
+    }
+    if (res?.ok) {
+      li.classList.remove('is-pending')
+      photosSent.add(id)
+      if (!ws) connect()
+      return
+    }
+    li.remove()
+    photoError.textContent = s[PHOTO_ERRORS[res?.status]] ?? s.photoFailed
+  }
+  picker?.addEventListener('change', async () => {
+    const files = [...(picker.files ?? [])]
+    picker.value = ''
+    photoError.textContent = ''
+    if (over || demo || files.length === 0) return
+    const room = MAX_PHOTOS - photosSent.size - photosBusy
+    if (files.length > room) photoError.textContent = s.photoLimit
+    const take = files.slice(0, Math.max(0, room))
+    photosBusy += take.length
+    // One at a time: the first may have to start the conversation the others then use.
+    for (const f of take) {
+      try { await sendPhoto(f) } finally { photosBusy-- }
+    }
+  })
+
+  // ---- the composer -----------------------------------------------------------------------
+  function submit() {
+    const text = input.value.trim()
+    if (!text || over || demo) return
+    input.value = ''
+    const entry = { id: uuid(), text: text.slice(0, MAX_TEXT), tries: 0, failed: false }
+    entry.li = line(entry.id, 'visitor')
+    entry.li.classList.add('is-pending')
+    setText(entry.li, { role: 'visitor' }, entry.text)
+    pending.set(entry.id, entry)
+    scroll()
+    if (!session) begin()
+    else if (isOpen()) transmit(entry)
+    else connect()
+  }
+  composer.addEventListener('submit', (e) => { e.preventDefault(); submit() })
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' && !e.shiftKey && !e.isComposing) { e.preventDefault(); submit() }
+  })
+  input.addEventListener('input', () => {
+    const now = Date.now()
+    if (isOpen() && now - lastTyping > TYPING_SEND_MS) {
+      lastTyping = now
+      ws.send(JSON.stringify({ type: 'typing' }))
+    }
+  })
+  restart.addEventListener('click', () => {
+    session = null
+    try { win.sessionStorage.removeItem(SESSION_KEY) } catch { /* nothing kept */ }
+    try { ws?.close(1000) } catch { /* already closed */ }
+    ws = null
+    over = false
+    lastSeq = 0
+    seen.clear()
+    pending.clear()
+    photosSent.clear()
+    photoError.textContent = ''
+    mode = 'bot'
+    ownerName = null
+    header()
+    for (const li of [...log.querySelectorAll('li[data-id]')]) li.remove()
+    ended.hidden = true
+    composer.hidden = false
+    input.focus()
+  })
+
+  // ---- the dialog -------------------------------------------------------------------------
+  const focusables = () => [...panel.querySelectorAll('a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])')]
+    .filter((x) => !x.disabled && !x.closest('[hidden]'))
+  panel.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape') { e.preventDefault(); close(); return }
+    if (e.key !== 'Tab') return
+    const f = focusables()
+    if (f.length === 0) return
+    const first = f[0]
+    const last = f[f.length - 1]
+    if (e.shiftKey && doc.activeElement === first) { e.preventDefault(); last.focus() }
+    else if (!e.shiftKey && doc.activeElement === last) { e.preventDefault(); first.focus() }
+  })
+  closeBtn.addEventListener('click', () => close())
+
+  function show() {
+    if (!demo) turnstile.load()
+    panel.hidden = false
+    root.setAttribute('data-open', '')
+    root.removeAttribute('data-unread')
+    if (session) connect()
+    ;(demo ? closeBtn : composer.hidden ? (fallback.hidden ? restart : fallback.querySelector('input')) : input)?.focus()
+    scroll()
+  }
+  function close() {
+    panel.hidden = true
+    root.removeAttribute('data-open')
+    bubble?.focus()
+  }
+
+  root.pmwChat = { open: show, close, panel }
+  return root.pmwChat
+}

package/src/worker.d.ts

@@ -0,0 +1,62 @@
+// Types for the worker half of @pmeweb/plugin-chat.
+
+/** pmeweb.json `plugins.chat` (manifest `config`). Every value is public. */
+export interface ChatConfig {
+  /** The client's on/off switch. Anything but `true` is off: nothing on the site, every route 403. */
+  enabled?: boolean
+  provider?: 'workers-ai'
+  sms?: 'voipms'
+  photos?: boolean
+  avatar?: '1' | '2' | '3' | '4' | '5' | '6' | 'icon' | 'logo'
+}
+
+/**
+ * The CHAT service binding: pmeweb-chat's `ChatApi` named entrypoint. `fetch` carries
+ * `POST /start` and the `/ws` upgrade; `ping` is for the health route.
+ */
+export interface ChatBinding {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+  ping?(host: string): Promise<{ ok: boolean; accepts: readonly number[]; configured: boolean; missing: string[]; error?: string }>
+}
+
+export interface ChatEnv {
+  CHAT: ChatBinding
+  /** The site's Turnstile secret. Absent = every start is refused (503). */
+  TURNSTILE_SECRET?: string
+  /** A Workers Rate Limiting binding (`ratelimits` in wrangler.jsonc), keyed `chat:<ip>`. */
+  CHAT_LIMIT?: { limit(o: { key: string }): Promise<{ success: boolean }> }
+  /** The conversation-start limit (3 a minute), keyed `chat-start:<ip>`; absent, starts use CHAT_LIMIT. */
+  CHAT_START_LIMIT?: { limit(o: { key: string }): Promise<{ success: boolean }> }
+}
+
+/**
+ * Route every `/api/chat/*` request here, before the assets (`start`, `ws`, and `photo` when the
+ * config says `photos: true`). Never throws. Off `hosts` (the site's
+ * real hosts, src/data/hosts.ts) every route answers 403 `disabled`.
+ */
+export declare function handleChat(
+  request: Request,
+  env: ChatEnv,
+  ctx: { waitUntil(p: Promise<unknown>): void },
+  options: { hosts: string[]; config?: ChatConfig | Record<string, unknown>; lang?: 'fr' | 'en' | string }
+): Promise<Response>
+
+/** The largest photo the site forwards (pmeweb-chat refuses bigger ones too). */
+export declare const MAX_PHOTO_BYTES: number
+
+/** This package's version. */
+export declare const VERSION: string
+/** The ChatApi interface version this package speaks. */
+export declare const RPC_VERSION: number
+
+/**
+ * For the site's plugin health route: booleans only. `host` is the site's canonical host
+ * (`CANONICAL_HOSTS[0]`), which pmeweb-chat needs to find the client's settings; `config` is
+ * `plugins.chat`, switched off it answers `{ disabled: true }` only:
+ * `pluginHealth(request, env, { chat: (e) => health(e, { host: CANONICAL_HOSTS[0], config: plugins.chat }) })`.
+ */
+export declare function health(env: Partial<ChatEnv>, opts?: { host?: string; config?: ChatConfig | Record<string, unknown> }): Promise<{
+  version: string
+  rpc: number
+  checks: { secret: boolean; binding: boolean; limit: boolean; startLimit: boolean; rpc: boolean; settings: boolean } | { disabled: true }
+}>