@pmeweb/plugin-chat 0.0.0-stage → 1.1.0

package/src/Chat.astro

@@ -0,0 +1,110 @@
+---
+// <Chat config={plugins.chat} lang="fr" siteKey={TURNSTILE_SITE_KEY} opener={opener} logo={logoUrl} site={site} privacyHref="/confidentialite/" />
+// Once, in Base.astro, on every page (manifest markup.pages "all"). The bubble and the opener are
+// plain HTML and CSS until touched: the inlined trigger shows them on the site's real hosts only
+// (they ship `hidden`), and imports the panel (dist/widget.js, its URL in data-pmw-lazy) on the
+// first touch. A site restyles through the --pmw-chat-* variables; it never forks this file.
+//
+// - `opener` is THIS page's line (the site's dictionary `chat.openers[path]`, else
+//   `chat.defaultOpener` with the entry's title). No opener throws at build: every page has one.
+// - The avatar is config.avatar (src/faces.js): a face `photos-<n>` or `illustration-<n>` shipped in
+//   this package, an icon `sans-visage-<n>` drawn inline, or `logo` (the `logo` prop, a URL). A face
+//   is a 96 px WebP imported `?url&no-inline` (a cached file, never a data: URL repeated in every
+//   page or refused by a CSP); only the chosen one is in the page. An icon is the SVG's own text,
+//   inlined at build: no request at all. `alt=""`: the visible « Assistant virtuel » names the
+//   button (spec § 6).
+// - The button's accessible name starts with its visible text (WCAG 2.5.3).
+// - config.photos === true (and only true) turns the panel's photo picker on.
+// - `site` is pmeweb.json: its `design.colors` colour the panel and the sans-visage circle (src/colors.js), as one
+//   zero-specificity rule a site's own --pmw-chat-* value beats. Absent, the package defaults.
+// - config.enabled is the client's switch (manifest activeWhen). Anything but `true` is off: the
+//   component renders NOTHING (no markup, no script, no CSS: chat.css is inlined here rather than
+//   imported, or the bundler would put it in every page), except in a « Contenu » preview build
+//   (PMEWEB_PORTAL_PREVIEW exactly '1', set by the site builder for its preview build and dev
+//   server, never for the publish preflight), where the bubble shows forced into the demo
+//   (`demo: true`: no request, whatever the host). No visitor-side flag turns it on.
+import code from '../dist/trigger.iife.js?raw';
+import lazy from '../dist/widget.js?url&no-inline';
+import { langOf, stringsFor } from './strings.js';
+import { AVATAR_PATTERN, FACES, ICONS } from './faces.js';
+import { HEX_RE, avatarTheme, panelTheme, siteColors, themeCss } from './colors.js';
+import chatCss from './chat.css?inline';
+
+interface Props {
+  config?: Record<string, unknown>;
+  lang?: string;
+  siteKey: string;
+  opener: string;
+  logo?: string | { src: string };
+  privacyHref?: string;
+  strings?: Record<string, string>;
+  site?: Record<string, unknown>;
+}
+const { config = {}, lang: rawLang = 'fr', siteKey, opener, logo, privacyHref, strings = {}, site } = Astro.props;
+const enabled = config.enabled === true;
+const show = enabled || process.env.PMEWEB_PORTAL_PREVIEW === '1';
+const lang = langOf(rawLang);
+const s = stringsFor(lang, strings);
+if (typeof opener !== 'string' || opener.trim() === '') throw new Error('chat : pas d’accroche pour cette page');
+if (typeof siteKey !== 'string' || siteKey === '') throw new Error('chat : la clé de site Turnstile manque');
+
+const avatar = String(config.avatar ?? '');
+const faces = import.meta.glob('../avatars/*.webp', { query: '?url&no-inline', import: 'default' });
+const icons = import.meta.glob('../avatars/*.svg', { query: '?raw', import: 'default', eager: true });
+let src: string | null = null;
+let svg: string | null = null;
+let kind: 'face' | 'icon' | 'logo';
+if (!new RegExp(AVATAR_PATTERN).test(avatar)) throw new Error(`chat : avatar « ${avatar} » inconnu (${[...FACES, ...ICONS, 'logo'].join(', ')})`);
+if (FACES.includes(avatar)) {
+  kind = 'face';
+  const face = faces[`../avatars/${avatar}.webp`];
+  if (!face) throw new Error(`chat : visage ${avatar} absent du paquet`);
+  // Only when shown: switched off, the build emits no face at all.
+  src = show ? ((await face()) as string) : null;
+} else if (ICONS.includes(avatar)) {
+  kind = 'icon';
+  const raw = icons[`../avatars/${avatar}.svg`] as string | undefined;
+  if (!raw) throw new Error(`chat : icône ${avatar} absente du paquet`);
+  // The file's own <svg> tag (xmlns, a 48 px size) becomes a decorative one sized by the CSS.
+  svg = raw.trim().replace(/<svg\b[^>]*>/, '<svg viewBox="0 0 48 48" focusable="false">');
+} else {
+  kind = 'logo';
+  src = typeof logo === 'string' ? logo : (logo?.src ?? null);
+  if (!src) throw new Error('chat : avatar « logo » sans la prop logo');
+}
+const colors = siteColors(site);
+if (config.avatarBg !== undefined && !(typeof config.avatarBg === 'string' && HEX_RE.test(config.avatarBg))) {
+  throw new Error(`chat : avatarBg « ${config.avatarBg} » invalide (#rrggbb en minuscules)`);
+}
+const vars: Record<string, string> = panelTheme(colors);
+if (kind === 'icon') {
+  const t = avatarTheme(config.avatarBg as string | undefined, colors);
+  vars['--pmw-chat-avatar-bg'] = t.bg;
+  vars['--pmw-chat-avatar-fg'] = t.fg;
+  if (t.ring) vars['--pmw-chat-avatar-ring'] = t.ring;
+}
+const theme = themeCss(vars);
+const json = JSON.stringify({ lang, siteKey, avatar: src, kind, privacyHref: privacyHref ?? null, strings, ...(config.photos === true ? { photos: true } : {}), ...(enabled ? {} : { demo: true }) }).replace(/</g, '\\u003c');
+// Every `</` and `<!--` escaped, so the inlined code cannot close or confuse its <script> tag.
+const script = code.replace(/<\//g, '<\\/').replace(/<!--/g, '<\\!--');
+---
+{show && <style is:inline set:html={chatCss} />}
+{show && theme && <style is:inline set:html={theme} />}
+{show && <div id="pmw-chat" class="pmw-chat" data-pmw-chat-opener={opener} data-pmw-lazy={lazy} lang={lang === 'en' ? 'en' : 'fr-CA'} hidden>
+  <div class="pmw-chat__teaser" hidden>
+    <button type="button" class="pmw-chat__teaser-text" data-pmw-chat-open>{opener}</button>
+    <button type="button" class="pmw-chat__teaser-close" data-pmw-chat-dismiss aria-label={s.dismissTeaser}>
+      <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>
+    </button>
+  </div>
+  <button type="button" class="pmw-chat__bubble" data-pmw-chat-open aria-haspopup="dialog" aria-label={s.openLabel}>
+    {svg ? <span class="pmw-chat__avatar pmw-chat__avatar--icon" aria-hidden="true" set:html={svg} /> : (
+      <span class:list={['pmw-chat__avatar', kind === 'logo' && 'pmw-chat__avatar--logo']} aria-hidden="true">
+        <img src={src} alt="" width="48" height="48" decoding="async" />
+      </span>
+    )}
+    <span class="pmw-chat__label">{s.assistant}</span>
+  </button>
+  <script type="application/json" data-pmw-chat-config set:html={json} />
+</div>}
+{show && <script is:inline data-pmw-plugin="chat" set:html={script} />}

package/src/build.d.ts

@@ -0,0 +1,30 @@
+export declare const CONTEXT_FORMAT: 1
+export declare const MAX_CONTEXT_BYTES: number
+
+export interface ChatContextLang {
+  /** The business's name in this language (the bot says it; pmeweb-chat falls back to the host). */
+  business?: string
+  /** What src/pages/llms.txt.ts renders for this language. */
+  llms?: string
+  /** The pricing text (the source of public/pricing.md). */
+  pricing?: string
+  /** src/i18n/<lang>.ts: flattened to `key: value` lines, strings only. */
+  dictionary?: object
+}
+
+export interface ChatContextEntry {
+  collection: string
+  /** Absent: the entry belongs to every language. */
+  lang?: 'fr' | 'en'
+  title: string
+  data?: Record<string, unknown>
+  body?: string
+}
+
+/** The JSON text of plugins/chat/context.json. Deterministic; throws above 200 KB or on an empty language. */
+export declare function chatContext(sources: {
+  langs: Partial<Record<'fr' | 'en', ChatContextLang>>
+  collections?: ChatContextEntry[]
+}): string
+
+export declare function flattenDictionary(dict: object, prefix?: string): string

package/src/build.js

@@ -0,0 +1,87 @@
+// @pmeweb/plugin-chat/build: the site's context file for pmeweb-chat (manifest `build`:
+// plugins/chat/context.json, one file for every language). The site renders it from a prerendered
+// route with sources it already has (llms.txt, its pricing text, its dictionaries, its published
+// collection entries); pmeweb-chat reads `langs[lang]` (src/context.ts there):
+//
+//   { "format": 1, "langs": { "fr": { "business": "...", "sections": [{ "title", "text" }] } } }
+//
+// DETERMINISTIC: same sources, same bytes. No date, no random id, no network, no model call (the
+// builder holds no secret, and a rebuild must not spend money). Not public: the site's worker serves
+// it only to a signed request (plugin-kit's pluginArtifacts), never to a visitor.
+
+export const CONTEXT_FORMAT = 1
+/** About 50k tokens at most: past this the prompt would cost too much per message. */
+export const MAX_CONTEXT_BYTES = 200 * 1024
+
+const LANGS = ['fr', 'en']
+const TITLES = {
+  fr: { llms: 'llms.txt', pricing: 'Tarifs', dictionary: 'Textes du site', colon: ' : ' },
+  en: { llms: 'llms.txt', pricing: 'Pricing', dictionary: 'Site text', colon: ': ' },
+}
+
+const text = (v) => (typeof v === 'string' ? v.trim() : '')
+const oneLine = (v) => v.replace(/\s*\n\s*/g, ' ').trim()
+
+/** A dictionary as `path.to.key: value` lines, strings only, in the dictionary's own order. */
+export function flattenDictionary(dict, prefix = '') {
+  const out = []
+  const walk = (v, path) => {
+    if (typeof v === 'string') {
+      if (v.trim() !== '') out.push(`${path}: ${oneLine(v)}`)
+    } else if (Array.isArray(v)) {
+      v.forEach((x, i) => walk(x, path ? `${path}.${i}` : String(i)))
+    } else if (v && typeof v === 'object') {
+      for (const [k, x] of Object.entries(v)) walk(x, path ? `${path}.${k}` : k)
+    }
+  }
+  walk(dict, prefix)
+  return out.join('\n')
+}
+
+/** One collection entry: its string fields as `key: value` lines (the title itself left out), then its body. */
+function entryText(e) {
+  const lines = []
+  for (const [k, v] of Object.entries(e.data ?? {})) {
+    if (typeof v !== 'string' || v.trim() === '' || v === e.title) continue
+    lines.push(`${k}: ${oneLine(v)}`)
+  }
+  const body = text(e.body)
+  return [lines.join('\n'), body].filter(Boolean).join('\n\n')
+}
+
+/**
+ * @param {{
+ *   langs: Partial<Record<'fr' | 'en', { business?: string, llms?: string, pricing?: string, dictionary?: object }>>,
+ *   collections?: { collection: string, lang?: 'fr' | 'en', title: string, data?: Record<string, unknown>, body?: string }[],
+ * }} sources an entry with no `lang` belongs to every language
+ * @returns {string} the JSON text of plugins/chat/context.json
+ */
+export function chatContext({ langs = {}, collections = [] } = {}) {
+  const keys = Object.keys(langs)
+  if (keys.length === 0 || keys.some((l) => !LANGS.includes(l))) {
+    throw new Error(`chat : une langue fr ou en au moins, et aucune autre (reçu ${keys.join(', ') || 'rien'})`)
+  }
+  const out = { format: CONTEXT_FORMAT, langs: {} }
+  for (const lang of LANGS.filter((l) => keys.includes(l))) {
+    const src = langs[lang] ?? {}
+    const t = TITLES[lang]
+    const sections = []
+    const add = (title, body) => { if (body) sections.push({ title, text: body }) }
+    add(t.llms, text(src.llms))
+    add(t.pricing, text(src.pricing))
+    add(t.dictionary, src.dictionary ? flattenDictionary(src.dictionary) : '')
+    for (const e of collections) {
+      if (e.lang !== undefined && e.lang !== lang) continue
+      add(`${e.collection}${t.colon}${text(e.title)}`, entryText(e))
+    }
+    if (sections.length === 0) throw new Error(`chat : contexte ${lang} vide`)
+    const part = {}
+    if (text(src.business)) part.business = text(src.business)
+    part.sections = sections
+    out.langs[lang] = part
+  }
+  const json = JSON.stringify(out)
+  const bytes = new TextEncoder().encode(json).length
+  if (bytes > MAX_CONTEXT_BYTES) throw new Error(`chat : contexte de ${bytes} octets, au-delà de 200 Ko (le prompt serait trop long)`)
+  return json
+}

package/src/chat.css

@@ -0,0 +1,65 @@
+/* @pmeweb/plugin-chat: the bubble and the opener, on the page from the first paint. Structure only:
+   the --pmw-chat-* variables are NOT declared here, each use carries its default as a fallback, so
+   a site sets them anywhere (:root, or #pmw-chat) without fighting an unlayered rule. The panel's
+   own rules arrive with the lazy widget (widget.css). Default text pairs pass AA
+   (a11y-tools/contrast.mjs): #1f2328 on #ffffff 15.8:1, #ffffff on #0a1b3d 16.98:1, #4b5563 on
+   #ffffff 7.56:1. */
+.pmw-chat[hidden] { display: none; }
+.pmw-chat {
+  position: fixed; z-index: 80;
+  right: calc(env(safe-area-inset-right, 0px) + var(--pmw-chat-right, 16px));
+  bottom: calc(env(safe-area-inset-bottom, 0px) + var(--pmw-chat-bottom, 16px));
+  display: flex; flex-direction: column; align-items: flex-end; gap: 10px;
+  font-family: var(--pmw-chat-font, inherit); font-size: 16px; line-height: 1.4;
+  color: var(--pmw-chat-fg, #1f2328);
+}
+.pmw-chat button { font: inherit; cursor: pointer; }
+.pmw-chat button:focus-visible {
+  outline: 3px solid var(--pmw-chat-focus, #0a1b3d); outline-offset: 2px;
+  box-shadow: 0 0 0 2px #ffffff;
+}
+.pmw-chat__bubble {
+  display: flex; align-items: center; gap: 10px; min-height: 56px;
+  padding: 4px 18px 4px 4px; border-radius: 999px;
+  background: var(--pmw-chat-bubble-bg, #ffffff); color: var(--pmw-chat-fg, #1f2328);
+  border: 1px solid var(--pmw-chat-border, #c9ced6);
+  box-shadow: 0 6px 20px rgb(0 0 0 / 0.16);
+}
+.pmw-chat__avatar {
+  flex: none; width: 48px; height: 48px; border-radius: 50%; overflow: hidden;
+  display: flex; align-items: center; justify-content: center;
+  background: var(--pmw-chat-avatar-bg, var(--pmw-chat-accent, #0a1b3d));
+  color: var(--pmw-chat-avatar-fg, var(--pmw-chat-accent-fg, #ffffff));
+}
+/* A sans-visage circle under 3:1 against the page: a thin ring in ink (Chat.astro sets the ring
+   variable only then, src/colors.js avatarTheme). */
+.pmw-chat__avatar--icon { box-shadow: 0 0 0 1.5px var(--pmw-chat-avatar-ring, transparent); }
+.pmw-chat__avatar img { display: block; width: 48px; height: 48px; object-fit: cover; }
+.pmw-chat__avatar--logo { background: #ffffff; border: 1px solid var(--pmw-chat-border, #c9ced6); }
+.pmw-chat__avatar--logo img { object-fit: contain; width: 36px; height: 36px; }
+.pmw-chat__avatar svg { display: block; width: 100%; height: 100%; }
+.pmw-chat__label { font-size: 15px; font-weight: 600; white-space: nowrap; }
+
+/* The opener: once per visit, after 20 s, at 30 % of the page, or on exit intent (trigger.js). */
+.pmw-chat__teaser[hidden] { display: none; }
+.pmw-chat__teaser {
+  position: relative; max-width: min(300px, calc(100vw - 32px));
+  padding: 12px 40px 12px 14px; border-radius: 12px;
+  background: var(--pmw-chat-bubble-bg, #ffffff); color: var(--pmw-chat-fg, #1f2328);
+  border: 1px solid var(--pmw-chat-border, #c9ced6); box-shadow: 0 6px 20px rgb(0 0 0 / 0.16);
+  animation: pmw-chat-in 0.22s ease both;
+}
+.pmw-chat__teaser-text { display: block; padding: 0; border: 0; background: none; color: inherit; text-align: left; font-size: 15px; }
+.pmw-chat__teaser-close {
+  position: absolute; top: 2px; right: 2px; width: 36px; height: 36px; padding: 0; border: 0; border-radius: 50%;
+  display: flex; align-items: center; justify-content: center;
+  background: none; color: var(--pmw-chat-muted, #4b5563);
+}
+.pmw-chat__teaser-close svg { width: 16px; height: 16px; }
+@keyframes pmw-chat-in { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
+@media (prefers-reduced-motion: reduce) {
+  .pmw-chat__teaser { animation: none; }
+}
+/* While the panel is open the bubble and the opener step aside. */
+.pmw-chat[data-open] .pmw-chat__bubble, .pmw-chat[data-open] .pmw-chat__teaser { display: none; }
+@media print { .pmw-chat { display: none; } }

package/src/colors.js

@@ -0,0 +1,104 @@
+// The site's palette (pmeweb.json `design.colors`, five lowercase #rrggbb: primary, accent, ink,
+// background, surface) turned into the --pmw-chat-* variables, at build, in Chat.astro. Every pair
+// keeps its WCAG minimum: a choice that would not is dropped and the package default stays.
+// contrast() is a11y-tools/contrast.mjs's ratio for opaque colours (tests/colors.test.js holds them
+// equal); this package cannot import the workspace tool, since it is published alone.
+
+export const HEX_RE = /^#[0-9a-f]{6}$/
+/** The sans-visage circle without avatarBg nor design.colors.accent (the panel's default navy). */
+export const DEFAULT_AVATAR_BG = '#0a1b3d'
+/** The dark text colour when the site declares no ink, or when its ink is too light to help. */
+export const INK_FALLBACK = '#14181f'
+const WHITE = '#ffffff'
+const KEYS = ['primary', 'accent', 'ink', 'background', 'surface']
+
+function luminance(hex) {
+  const c = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)
+    .map((v) => (v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2]
+}
+
+export function contrast(a, b) {
+  const [x, y] = [luminance(a), luminance(b)].sort((p, q) => q - p)
+  return (x + 0.05) / (y + 0.05)
+}
+
+/** design.colors, its valid entries only (lowercased). */
+export function siteColors(site) {
+  const c = site?.design?.colors
+  const out = {}
+  if (!c || typeof c !== 'object') return out
+  for (const k of KEYS) {
+    const v = typeof c[k] === 'string' ? c[k].toLowerCase() : ''
+    if (HEX_RE.test(v)) out[k] = v
+  }
+  return out
+}
+
+/**
+ * The text colour for a fill: white or the site's ink, whichever contrasts more; when neither
+ * reaches `min` (a light ink on a light fill), the dark fallback if it does. Null when nothing does.
+ */
+export function textOn(fill, ink, min) {
+  const pick = [WHITE, ink ?? INK_FALLBACK].sort((a, b) => contrast(b, fill) - contrast(a, fill))[0]
+  if (contrast(pick, fill) >= min) return pick
+  return contrast(INK_FALLBACK, fill) >= min ? INK_FALLBACK : null
+}
+
+/**
+ * The sans-visage circle: `avatarBg`, else the accent, else the package default. The glyph keeps
+ * 3:1 (a graphic). A circle under 3:1 against the page (or the bubble's surface) gets a thin ring
+ * in ink, so its edge still shows; never a text notice.
+ */
+export function avatarTheme(avatarBg, colors = {}) {
+  const bg = avatarBg ?? colors.accent ?? DEFAULT_AVATAR_BG
+  const fg = textOn(bg, colors.ink, 3) ?? [WHITE, INK_FALLBACK].sort((a, b) => contrast(b, bg) - contrast(a, bg))[0]
+  const behind = [colors.background ?? WHITE, colors.surface].filter(Boolean)
+  const ring = behind.some((b) => contrast(bg, b) < 3) ? (colors.ink ?? INK_FALLBACK) : null
+  return { bg, fg, ring }
+}
+
+const ERRORS = ['#b42318', '#ffb4ab']
+
+/** `fg` laid over `bg` at `alpha`, as an opaque #rrggbb. */
+function mix(fg, bg, alpha) {
+  const ch = (h, i) => parseInt(h.slice(i, i + 2), 16)
+  return `#${[1, 3, 5].map((i) => Math.round(ch(fg, i) * alpha + ch(bg, i) * (1 - alpha)).toString(16).padStart(2, '0')).join('')}`
+}
+
+/**
+ * The panel (and the bubble beside it) in the site's colours, two groups each all-or-nothing:
+ * - primary: the header, the visitor's bubbles and the send button, text white or ink at 4.5:1;
+ * - surface: the panel and the bubble in `surface`, text in `ink` at 4.5:1, the bot's bubbles in
+ *   `background`, and the colours that sit on them (muted, link, focus, error) re-derived so each
+ *   keeps its minimum. A group whose pair fails sets nothing: the package defaults stay.
+ */
+export function panelTheme(colors = {}) {
+  const v = {}
+  const { primary, ink, surface, background } = colors
+  if (primary) {
+    const fg = textOn(primary, ink, 4.5)
+    if (fg) Object.assign(v, { '--pmw-chat-accent': primary, '--pmw-chat-accent-fg': fg })
+  }
+  if (surface && ink && contrast(ink, surface) >= 4.5) {
+    const muted = mix(ink, surface, 0.75)
+    const page = background ?? WHITE
+    Object.assign(v, {
+      '--pmw-chat-panel-bg': surface,
+      '--pmw-chat-bubble-bg': surface,
+      '--pmw-chat-fg': ink,
+      '--pmw-chat-other-bg': background && contrast(ink, background) >= 4.5 ? background : surface,
+      '--pmw-chat-muted': contrast(muted, surface) >= 4.5 ? muted : ink,
+      '--pmw-chat-link': primary && contrast(primary, surface) >= 4.5 ? primary : ink,
+      '--pmw-chat-focus': contrast(ink, page) >= 3 ? ink : INK_FALLBACK,
+      '--pmw-chat-error': ERRORS.find((e) => contrast(e, surface) >= 4.5) ?? ink,
+    })
+  }
+  return v
+}
+
+/** One rule at zero specificity: a site's own --pmw-chat-* value, anywhere, still wins. */
+export function themeCss(vars) {
+  const decl = Object.entries(vars).map(([k, v]) => `${k}:${v}`).join(';')
+  return decl ? `:where(:root){${decl}}` : ''
+}

package/src/csp.d.ts

@@ -0,0 +1,2 @@
+/** The CSP hosts the chat needs (Turnstile's script and frame), by directive, for `mergeCsp`. */
+export declare function cspHosts(): Partial<Record<string, string[]>>

package/src/csp.js

@@ -0,0 +1,5 @@
+// The chat posts through Turnstile: its widget's script and frame. The socket and /api/chat/start
+// are same-origin, which 'self' in connect-src already covers.
+export function cspHosts() {
+  return { 'script-src': ['https://challenges.cloudflare.com'], 'frame-src': ['https://challenges.cloudflare.com'] }
+}

package/src/faces.js

@@ -0,0 +1,24 @@
+// The avatars this package ships (avatars/), the one list the component, the manifest's `avatar`
+// pattern and the tests read. A config names one as `<category>-<n>`: `photos-3`,
+// `illustration-2` (a 96 px WebP face), `sans-visage-1` (an SVG drawn in currentColor on the
+// `avatarBg` colour), or `logo` (the site's own, through the component's `logo` prop).
+//
+// ADDING A FACE IS NOT A BREAKING CHANGE: drop the file in avatars/, raise its category's count
+// here (or add a category, `3d` when its faces exist), and copy the new AVATAR_PATTERN into
+// manifest.json (tests/manifest.test.js holds the two equal). Every value a site already uses stays
+// valid. Never renumber or remove a face a site may have chosen.
+
+/** Faces per category, numbered from 1. */
+export const FACE_COUNTS = { photos: 5, illustration: 5 }
+export const ICON_COUNT = 5
+
+const range = (n) => Array.from({ length: n }, (_, i) => i + 1)
+export const FACES = Object.entries(FACE_COUNTS).flatMap(([c, n]) => range(n).map((i) => `${c}-${i}`))
+export const ICONS = range(ICON_COUNT).map((i) => `sans-visage-${i}`)
+
+const upTo = (n) => (n < 10 ? `[1-${n}]` : `(?:[1-9]|1[0-${n - 10}])`)
+export const AVATAR_PATTERN = `^(?:${[
+  ...Object.entries(FACE_COUNTS).map(([c, n]) => `${c}-${upTo(n)}`),
+  `sans-visage-${upTo(ICON_COUNT)}`,
+  'logo',
+].join('|')})$`

package/src/protocol.js

@@ -0,0 +1,53 @@
+// GENERATED by build.mjs from src/protocol.ts (a verbatim copy of pmeweb-chat/src/protocol.ts). Do not edit.
+const RPC_HEADER = "x-pmw-rpc";
+const RPC_VERSION = 1;
+const MAX_TEXT = 2e3;
+const CLOSE = { unauthorized: 4401, expired: 4410, rpc: 4426, deleted: 4404 };
+const ACTOR_HEADER = "x-pmw-actor";
+function encodeActor(actor) {
+  return JSON.stringify(actor).replace(/[\u0080-\uffff]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(v) {
+  return typeof v === "string" && UUID.test(v);
+}
+function parseClient(raw) {
+  let v;
+  try {
+    v = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return null;
+  const o = v;
+  switch (o.type) {
+    case "hello": {
+      const since = o.since;
+      if (typeof since !== "number" || !Number.isSafeInteger(since) || since < 0) return null;
+      return { type: "hello", since };
+    }
+    case "message": {
+      const { id, text } = o;
+      if (!isUuid(id)) return null;
+      if (typeof text !== "string" || text.length > MAX_TEXT || text.trim() === "") return null;
+      return { type: "message", id, text };
+    }
+    case "typing":
+    case "takeover":
+    case "handback":
+    case "close":
+      return { type: o.type };
+    default:
+      return null;
+  }
+}
+export {
+  ACTOR_HEADER,
+  CLOSE,
+  MAX_TEXT,
+  RPC_HEADER,
+  RPC_VERSION,
+  encodeActor,
+  isUuid,
+  parseClient
+};

package/src/protocol.ts

@@ -0,0 +1,113 @@
+// The one message format of every chat socket: the visitor's widget, the owner's public page, the
+// portal's tabs (spec § 5). Versioned by RPC_VERSION (plugin-rpc.json); a breaking change is a new
+// version the service accepts alongside the old one until every site is updated.
+//
+// This file is copied VERBATIM into the plugin package and the portal, and a test in each compares
+// the copy byte for byte with this one. So it imports nothing: what the service accepts (read from
+// plugin-rpc.json) lives in src/rpc.ts, which only this repo has.
+export const RPC_HEADER = 'x-pmw-rpc';
+export const RPC_VERSION = 1;
+export const MAX_TEXT = 2000;
+
+export type Role = 'visitor' | 'bot' | 'owner';
+export type Mode = 'bot' | 'human';
+
+/** Client -> server. `id` is a client-made UUID: a message re-sent after a reconnect is stored once. */
+export type ClientMsg =
+  | { type: 'hello'; since: number }
+  | { type: 'message'; id: string; text: string }
+  | { type: 'typing' }
+  | { type: 'takeover' }
+  | { type: 'handback' }
+  | { type: 'close' };
+
+/** Server -> client. `delta` streams a bot answer; the final `message` replaces it. */
+export type ServerMsg =
+  | { type: 'history'; messages: StoredMsg[]; mode: Mode; ownerName: string | null; closed: boolean }
+  | { type: 'message'; msg: StoredMsg }
+  | { type: 'delta'; id: string; text: string }
+  | { type: 'typing'; role: Role }
+  | { type: 'status'; mode: Mode; ownerName: string | null; closed: boolean }
+  | { type: 'fallback'; reason: 'cap' | 'model_down' }
+  /** To the visitor's sockets only, once per conversation: the widget fires pmw.event('chat-lead'). */
+  | { type: 'lead' }
+  | { type: 'error'; code: string };
+
+export interface StoredMsg { seq: number; id: string; role: Role; text: string; at: number; by?: string; photos?: string[] }
+
+/**
+ * Close codes (4000-4999 are the application's). A refusal is always one of these on an accepted
+ * socket, never an HTTP status: a browser's WebSocket sees only « non-101 » and would reconnect
+ * forever (spike task 1). A 44xx close means « do not reconnect »; 1006 means « reconnect ».
+ */
+export const CLOSE = { unauthorized: 4401, expired: 4410, rpc: 4426, deleted: 4404 } as const;
+
+/**
+ * Who is on a socket, and what they may do. Set ONLY by a trusted entrypoint, never by the client:
+ * ChatApi sets `visitor` after checking the visitor key, the portal sets `owner` (public link) or
+ * `staff` (portal session) after `resolveConversationAccess`. It rides to the Durable Object in
+ * ACTOR_HEADER and is stored on the socket, so every frame is judged by it.
+ */
+export const ACTOR_HEADER = 'x-pmw-actor';
+export type Scope = 'reply' | 'takeover' | 'close';
+export interface Actor {
+  kind: 'visitor' | 'owner' | 'staff';
+  /** Shown to the visitor when this person takes over (owner, staff). */
+  name?: string;
+  /** SHA-256 hex of the public link's token: revoking the link closes exactly these sockets. */
+  tokenHash?: string;
+  /** SHA-256 hex of the visitor key, compared with the one stored at start (visitor only). */
+  keyHash?: string;
+  scope: Scope[];
+}
+
+/**
+ * The actor as an ASCII header value. Owner names carry accents (« Éric »); a header must be ASCII
+ * in the Fetch spec and workerd only tolerates UTF-8 as a quirk, so every non-ASCII character is
+ * written as a JSON \u escape, which JSON.parse reads back unchanged.
+ */
+export function encodeActor(actor: Actor): string {
+  return JSON.stringify(actor).replace(/[\u0080-\uffff]/g, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isUuid(v: unknown): v is string {
+  return typeof v === 'string' && UUID.test(v);
+}
+
+/**
+ * Parses one frame from a client. Anything unexpected is null, and the caller answers
+ * `error bad_message`: a frame is never half-trusted. Only the declared fields are copied, so an
+ * extra field (a `role`, a `by`) can never ride through to storage or to the other sockets.
+ */
+export function parseClient(raw: string): ClientMsg | null {
+  let v: unknown;
+  try {
+    v = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return null;
+  const o = v as Record<string, unknown>;
+  switch (o.type) {
+    case 'hello': {
+      const since = o.since;
+      if (typeof since !== 'number' || !Number.isSafeInteger(since) || since < 0) return null;
+      return { type: 'hello', since };
+    }
+    case 'message': {
+      const { id, text } = o;
+      if (!isUuid(id)) return null;
+      if (typeof text !== 'string' || text.length > MAX_TEXT || text.trim() === '') return null;
+      return { type: 'message', id, text };
+    }
+    case 'typing':
+    case 'takeover':
+    case 'handback':
+    case 'close':
+      return { type: o.type };
+    default:
+      return null;
+  }
+}