@zevra/support-widget 0.2.0

package/src/contexte.ts

@@ -0,0 +1,173 @@
+// ============================================================================
+// Le relevé automatique du contexte technique. PUR.
+// ============================================================================
+//
+// Ce que le widget joint tout seul à une demande : l'URL, le navigateur, la
+// version de l'app, la taille de la fenêtre, la langue, et les dernières
+// erreurs de console. C'est ce qui fait la différence entre « ça marche pas »
+// et un ticket qu'on peut reproduire.
+//
+// ⚠️ TOUT CE QUI EST RELEVÉ FINIT EN BASE, DANS UN MAIL, ET SOUS LES YEUX DE
+// L'ÉQUIPE. Le relevé n'est donc pas « tout ce qu'on peut lire » : c'est ce
+// qui diagnostique, et rien de plus. D'où le traitement de l'URL ci-dessous,
+// qui est la décision principale de ce fichier.
+//
+// La fonction est PURE : on lui passe ce qu'on a lu de la fenêtre. Sans cette
+// séparation, il faudrait un navigateur pour tester le cas « l'app n'a pas
+// déclaré sa version » — c'est-à-dire qu'on ne le testerait pas.
+
+import type { ContexteReleve } from './types'
+
+export const LONGUEUR_CHAMP = 500
+export const LONGUEUR_USER_AGENT = 300
+
+export interface SourceContexte {
+  url?: string | null
+  userAgent?: string | null
+  langue?: string | null
+  largeur?: number | null
+  hauteur?: number | null
+  version?: string | null
+  erreurs?: readonly string[]
+  extra?: Record<string, unknown> | null
+}
+
+/**
+ * Nettoie l'URL de la page. PUR.
+ *
+ * ⚠️ LA VALEUR DES PARAMÈTRES EST RETIRÉE, LEUR NOM EST GARDÉ.
+ *
+ * Une query string porte régulièrement un jeton de lien magique
+ * (`?jeton=…`), une adresse (`?email=…`), un identifiant de dossier. Copiée
+ * dans un ticket, elle est recopiée dans la base du support, dans l'accusé de
+ * réception, dans la copie d'écran de l'équipe — et un jeton de connexion qui
+ * traîne dans un fil de support est un jeton utilisable.
+ *
+ * Mais l'information « il y avait un paramètre `jeton` » diagnostique
+ * réellement (elle dit sur quelle variante de la page on était). On garde donc
+ * les noms : `?jeton=abc&page=2` devient `?jeton&page`.
+ *
+ * Le fragment (`#…`) part entièrement : il ne sert presque jamais au
+ * diagnostic et sert, lui, aux jetons des flux d'autorisation implicites.
+ */
+export function nettoyerUrl(brut: string | null | undefined): string | undefined {
+  const texte = typeof brut === 'string' ? brut.trim() : ''
+  if (texte === '') return undefined
+
+  let url: URL | null = null
+  try {
+    url = new URL(texte)
+  } catch {
+    url = null
+  }
+
+  if (url === null) {
+    // Une URL relative, ou quelque chose qu'on n'a pas su lire. On ne devine
+    // pas : on coupe avant le premier `?` ou `#`, ce qui est le comportement
+    // prudent quoi qu'il y ait derrière.
+    const coupe = texte.split(/[?#]/)[0]
+    return borner(coupe, LONGUEUR_CHAMP)
+  }
+
+  const noms = [...new Set([...url.searchParams.keys()])]
+  const query = noms.length > 0 ? `?${noms.join('&')}` : ''
+  return borner(`${url.origin}${url.pathname}${query}`, LONGUEUR_CHAMP)
+}
+
+/**
+ * Déduit le système d'exploitation du user agent. PUR.
+ *
+ * ⚠️ L'ORDRE DES TESTS EST LA FONCTION. Un user agent Android contient
+ * « Linux » ; un iPhone contient « like Mac OS X ». Tester Linux ou macOS en
+ * premier classerait tous les téléphones en poste de travail — et on
+ * chercherait longtemps pourquoi un bug « de bureau » ne se reproduit pas.
+ *
+ * Rend `undefined` quand on ne peut pas conclure, JAMAIS « inconnu » : un
+ * champ vide se lit comme « pas relevé », un « inconnu » écrit se lit comme
+ * une valeur mesurée.
+ */
+export function deduireOs(userAgent: string | null | undefined): string | undefined {
+  const ua = typeof userAgent === 'string' ? userAgent : ''
+  if (ua === '') return undefined
+  if (/iphone|ipad|ipod/i.test(ua)) return 'iOS'
+  if (/android/i.test(ua)) return 'Android'
+  if (/windows nt/i.test(ua)) return 'Windows'
+  if (/mac os x|macintosh/i.test(ua)) return 'macOS'
+  if (/cros/i.test(ua)) return 'ChromeOS'
+  if (/linux/i.test(ua)) return 'Linux'
+  return undefined
+}
+
+/** « 1440 × 900 ». Rend `undefined` si une des deux mesures manque. */
+export function formaterViewport(
+  largeur: number | null | undefined,
+  hauteur: number | null | undefined,
+): string | undefined {
+  if (!estMesure(largeur) || !estMesure(hauteur)) return undefined
+  return `${Math.round(largeur)} × ${Math.round(hauteur)}`
+}
+
+/**
+ * Assemble le contexte. PUR.
+ *
+ * Une clé absente est OMISE, pas mise à `null` ou à `''` : « viewport: 0 × 0 »
+ * ressemble à une mesure, alors que c'est une absence de mesure — et c'est sur
+ * cette fausse mesure qu'on partirait chercher un bug d'affichage.
+ */
+export function relever(source: SourceContexte): ContexteReleve {
+  const contexte: ContexteReleve = {}
+
+  const url = nettoyerUrl(source.url)
+  if (url) contexte.url = url
+
+  const ua = texteOuRien(source.userAgent, LONGUEUR_USER_AGENT)
+  if (ua) contexte.user_agent = ua
+
+  const version = texteOuRien(source.version, 100)
+  if (version) contexte.version = version
+
+  const os = deduireOs(source.userAgent)
+  if (os) contexte.os = os
+
+  const viewport = formaterViewport(source.largeur, source.hauteur)
+  if (viewport) contexte.viewport = viewport
+
+  const langue = texteOuRien(source.langue, 20)
+  if (langue) contexte.langue = langue
+
+  const erreurs = (source.erreurs ?? [])
+    .map((ligne) => texteOuRien(ligne, LONGUEUR_CHAMP))
+    .filter((ligne): ligne is string => ligne !== undefined)
+  if (erreurs.length > 0) contexte.console = erreurs
+
+  if (source.extra && typeof source.extra === 'object' && !Array.isArray(source.extra)) {
+    // L'app hôte peut joindre ce qu'elle veut (dossier courant, rôle, drapeau
+    // de fonctionnalité). On ne garde que ce qui se sérialise : un objet
+    // circulaire ferait jeter la sérialisation du corps au moment de l'envoi,
+    // c'est-à-dire loin d'ici, dans un message incompréhensible.
+    try {
+      const rendu = JSON.stringify(source.extra)
+      if (rendu !== undefined && rendu.length <= 4000) {
+        contexte.extra = JSON.parse(rendu) as Record<string, unknown>
+      }
+    } catch {
+      // Un extra illisible ne doit pas emporter le reste du contexte.
+    }
+  }
+
+  return contexte
+}
+
+function estMesure(valeur: number | null | undefined): valeur is number {
+  return typeof valeur === 'number' && Number.isFinite(valeur) && valeur > 0
+}
+
+function texteOuRien(valeur: unknown, longueur: number): string | undefined {
+  if (typeof valeur !== 'string') return undefined
+  const detoure = valeur.trim()
+  return detoure === '' ? undefined : borner(detoure, longueur)
+}
+
+function borner(texte: string, longueur: number): string {
+  return texte.length <= longueur ? texte : `${texte.slice(0, longueur - 1)}…`
+}

package/src/index.tsx

@@ -0,0 +1,241 @@
+'use client'
+
+// ============================================================================
+// @zevra/support-widget — le bouton « Aide » et son tiroir.
+// ============================================================================
+//
+// ⚠️ CE PAQUET NE CONNAÎT AUCUNE CLÉ ET AUCUNE URL DE SUPPORT. Il n'appelle
+// que `/api/support/*` sur SON PROPRE domaine — les routes que
+// `creerRoutesSupport()` de `@zevra/support` installe côté serveur de l'app
+// hôte. C'est ce relais qui détient `SUPPORT_API_KEY` et qui décide, à partir
+// de la session de l'app, de qui parle. Tout ce qui traverse ce paquet est
+// lisible dans l'onglet Réseau du premier visiteur venu ; la clé, non.
+//
+// Pose minimale, dans une app Next :
+//
+//   'use client'
+//   import { WidgetSupport } from '@zevra/support-widget'
+//   export function Aide() {
+//     return <WidgetSupport version={process.env.NEXT_PUBLIC_VERSION} />
+//   }
+
+import { useEffect, useMemo, useState, type ReactNode } from 'react'
+
+import { creerClientRelais, BASE_PAR_DEFAUT, type ClientRelais } from './client-relais'
+import { Tiroir } from './composants/tiroir'
+import { injecterFeuille } from './styles'
+import { installerTamponErreurs } from './tampon-erreurs'
+import type { TypeDemande } from './types'
+
+export interface ProprietesWidgetSupport {
+  /** Base des routes de relais dans VOTRE app. Défaut : `/api/support`. */
+  base?: string
+  /** Libellé du bouton flottant. */
+  libelle?: string
+  /** Titre du tiroir. */
+  titre?: string
+  position?:
+    | 'bas-droite'
+    | 'bas-gauche'
+    | 'haut-droite'
+    | 'haut-gauche'
+    | 'haut-centre'
+    | 'bas-centre'
+  /**
+   * Décalage vertical du bouton, en pixels.
+   *
+   * ⚠️ Il existe pour les barres fixes. Posé en haut sans décalage, le bouton
+   * recouvre l'en-tête de l'app hôte — dont ce paquet ne connaît ni la hauteur
+   * ni l'existence. C'est à l'app de la donner ; 20 px par défaut, comme en bas.
+   */
+  decalage?: number
+  /**
+   * Bouton discret : filet et papier au lieu du bouton plein.
+   *
+   * ⚠️ À employer quand le widget est posé sur une app dont il n'est PAS
+   * l'action principale — c'est-à-dire presque toujours. La charte n'admet
+   * qu'un seul bouton plein par écran, et ce bouton-là appartient à l'app
+   * hôte, jamais à son bouton d'aide.
+   */
+  discret?: boolean
+  /**
+   * Ce qui s'affiche DANS le bouton à la place du libellé — un logo, en
+   * général.
+   *
+   * ⚠️ LE WIDGET NE PORTE AUCUN LOGO, et n'en portera pas : une marque
+   * recopiée dans un paquet est une marque qui diverge de la charte à la
+   * première évolution, et qui pèse dans le bundle de toutes les apps.
+   * L'app hôte passe le sien, depuis le paquet ou ses propres fichiers.
+   *
+   * ⚠️ `libelle` reste OBLIGATOIRE quand on pose une marque : il devient le
+   * nom accessible du bouton. Une image seule, sans nom, est un bouton muet
+   * pour un lecteur d'écran.
+   */
+  marque?: ReactNode
+  /** La version de votre app, jointe au contexte technique. */
+  version?: string | null
+  /** Les types proposés. Retirez `idee` si vous n'en voulez pas. */
+  typesOfferts?: readonly TypeDemande[]
+  /** Affiche l'onglet « Bêta ». Défaut : oui — il se tait s'il n'y a rien. */
+  betaOfferte?: boolean
+  /** Propose la capture d'écran. Défaut : oui. */
+  captureOfferte?: boolean
+  /** Ce que VOUS voulez joindre en plus (dossier courant, rôle, drapeau…). */
+  contexteSupplementaire?: () => Record<string, unknown>
+  /** Client injecté — pour les tests, ou pour un transport particulier. */
+  client?: ClientRelais
+  onOuvrir?: () => void
+  onEnvoye?: (reference: string) => void
+}
+
+const TYPES_PAR_DEFAUT: readonly TypeDemande[] = ['bug', 'question', 'idee']
+
+/** Le bord auquel le bouton s'accroche. Le côté, lui, se lit dans le suffixe. */
+function bordVertical(position: string): 'haut' | 'bas' {
+  return position.startsWith('haut') ? 'haut' : 'bas'
+}
+
+/** Le côté : centre, gauche, ou droite par défaut. */
+function coteHorizontal(position: string): 'centre' | 'gauche' | 'droite' {
+  if (position.endsWith('centre')) return 'centre'
+  return position.endsWith('gauche') ? 'gauche' : 'droite'
+}
+
+export function WidgetSupport({
+  base = BASE_PAR_DEFAUT,
+  libelle = 'Aide',
+  titre = 'Aide et retours',
+  position = 'bas-droite',
+  decalage,
+  discret,
+  marque,
+  version,
+  typesOfferts = TYPES_PAR_DEFAUT,
+  betaOfferte = true,
+  captureOfferte = true,
+  contexteSupplementaire,
+  client: clientInjecte,
+  onOuvrir,
+  onEnvoye,
+}: ProprietesWidgetSupport) {
+  const [ouvert, setOuvert] = useState(false)
+  const client = useMemo(
+    () => clientInjecte ?? creerClientRelais(base),
+    [clientInjecte, base],
+  )
+
+  useEffect(() => {
+    injecterFeuille(typeof document === 'undefined' ? null : document)
+    // ⚠️ Filet de sécurité, PAS la pose recommandée. Posé ici, le tampon
+    // manque les erreurs du démarrage de l'app — précisément celles qu'on
+    // signale. La pose se fait dans l'entrée de l'app hôte (voir
+    // `installerTamponErreurs` et docs/integration.md) ; celle-ci ne sert que
+    // si personne ne l'a faite. La fonction est idempotente.
+    installerTamponErreurs()
+  }, [])
+
+  return (
+    <>
+      <button
+        type="button"
+        className={[
+          'zvs-racine',
+          'zvs-lanceur',
+          `zvs-lanceur--${bordVertical(position)}`,
+          `zvs-lanceur--${coteHorizontal(position)}`,
+          discret ? 'zvs-lanceur--discret' : '',
+        ]
+          .filter((c) => c !== '')
+          .join(' ')}
+        style={
+          typeof decalage === 'number'
+            ? { [bordVertical(position) === 'haut' ? 'top' : 'bottom']: `${decalage}px` }
+            : undefined
+        }
+        // Une image seule ne nomme pas le bouton : le libellé devient le nom
+        // accessible dès qu'il n'est plus écrit.
+        aria-label={marque ? libelle : undefined}
+        aria-haspopup="dialog"
+        aria-expanded={ouvert}
+        onClick={() => {
+          setOuvert(true)
+          onOuvrir?.()
+        }}
+      >
+        {marque ? <span className="zvs-marque">{marque}</span> : libelle}
+      </button>
+
+      {/* Le tiroir n'est PAS rendu quand il est fermé : son contenu interroge
+          le relais au montage (liste des demandes, campagne de bêta). Rendu en
+          permanence, il appellerait deux routes à chaque chargement de page
+          pour un panneau que personne n'a ouvert. */}
+      {ouvert ? (
+        <Tiroir
+          client={client}
+          titre={titre}
+          typesOfferts={typesOfferts}
+          version={version}
+          contexteSupplementaire={contexteSupplementaire}
+          betaOfferte={betaOfferte}
+          captureOfferte={captureOfferte}
+          onFermer={() => setOuvert(false)}
+          onEnvoye={onEnvoye}
+        />
+      ) : null}
+    </>
+  )
+}
+
+export { creerClientRelais, ErreurRelais, BASE_PAR_DEFAUT } from './client-relais'
+export type { ClientRelais, DescripteurPiece } from './client-relais'
+
+export {
+  TamponErreurs,
+  TAILLE_TAMPON,
+  formaterArgument,
+  formaterEntree,
+  installerTamponErreurs,
+  tamponErreurs,
+} from './tampon-erreurs'
+
+export { deduireOs, formaterViewport, nettoyerUrl, relever } from './contexte'
+export type { SourceContexte } from './contexte'
+
+export {
+  ID_FEUILLE,
+  PREFIXE,
+  classesDeLaFeuille,
+  feuilleDeStyle,
+  injecterFeuille,
+  referencesDeTokens,
+} from './styles'
+
+export {
+  LONGUEUR_DESCRIPTION,
+  LONGUEUR_TITRE,
+  estTypeDemande,
+  signalementValide,
+  typesAfficher,
+  verifierSignalement,
+} from './validation'
+export type { SaisieSignalement } from './validation'
+
+export { capturerEcran, decoderDataUrl, deposerBinaire, TYPE_MIME_CAPTURE } from './capture'
+export type { CaptureFaite, OptionsCapture, ResultatCapture } from './capture'
+
+export { COTE_MINIMAL, choisirZone, rectangleEntre, zoneDansImage, zoneExploitable } from './zone'
+export type { EntreeZoneDansImage, Point, Rectangle } from './zone'
+
+export { LIBELLES_STATUT, LIBELLES_TYPE } from './types'
+export type {
+  AuteurMessage,
+  ContexteReleve,
+  DemandeLue,
+  MessageLu,
+  PieceLue,
+  ProgrammeActif,
+  ResumeDemande,
+  ScenarioCampagne,
+  StatutDemande,
+  TypeDemande,
+} from './types'

package/src/styles.ts

@@ -0,0 +1,211 @@
+// ============================================================================
+// L'habillage du widget. PUR (la feuille), impur (la pose dans le document).
+// ============================================================================
+//
+// DEUX CONTRAINTES QUI SE CONTREDISENT, ET COMMENT ELLES SE RÉSOLVENT ICI.
+//
+// 1. Le widget doit porter l'identité Zevra quand l'app hôte a `@zevra/ui`.
+// 2. Il doit rester lisible quand elle ne l'a pas — et sans conflit : il est
+//    posé DANS l'app de quelqu'un d'autre, dont il ne connaît ni les classes,
+//    ni la spécificité, ni l'ordre de chargement.
+//
+// La solution n'est ni d'importer `@zevra/ui` (ce serait une dépendance dure
+// sur un paquet que l'app n'a peut-être pas, et une feuille entière chargée
+// pour un tiroir), ni de réutiliser ses classes `zv-` (elles peuvent ne pas
+// exister, et le widget se rendrait nu).
+//
+// Elle est celle-ci : **une feuille à nous, entièrement préfixée `zvs-`, dont
+// chaque valeur de marque lit un token Zevra AVEC UN REPLI LITTÉRAL.**
+//
+//     color: var(--ink, #0b1020);
+//
+// Là où le design system est chargé, `--ink` existe et le widget est dans les
+// couleurs de la maison, y compris après un changement de charte. Là où il ne
+// l'est pas, le repli s'applique et rien n'est invisible. Aucune classe de
+// l'hôte n'est lue, aucune classe `zvs-` n'existe ailleurs : la collision est
+// impossible dans les deux sens.
+//
+// ⚠️ UN `var()` SANS REPLI EST UN BUG SILENCIEUX : dans une app sans le design
+// system, la propriété devient invalide et la couleur retombe sur l'héritage —
+// du texte blanc sur blanc, un bouton sans fond. Rien ne le signale, et ça ne
+// se voit pas chez nous (nos apps ont toutes le paquet). C'est le test
+// `styles.test.ts` qui tient cette règle.
+
+/** Préfixe unique du widget. Aucune classe de l'hôte ne commence par là. */
+export const PREFIXE = 'zvs-'
+
+/** Identifiant de la balise `<style>` : c'est lui qui rend la pose idempotente. */
+export const ID_FEUILLE = 'zvs-support-widget'
+
+/**
+ * La feuille. PUR : une chaîne, toujours la même.
+ *
+ * ⚠️ Les replis ne contiennent AUCUNE parenthèse : `referencesDeTokens` les
+ * relit avec une expression régulière simple, et un `rgb(…)` en repli la
+ * ferait passer à côté d'une référence — donc à côté du bug qu'elle garde.
+ */
+export function feuilleDeStyle(): string {
+  return `
+.zvs-racine { font-family: var(--font-text, system-ui, sans-serif); font-size: 14px; line-height: 1.5; color: var(--ink, #0b1020); }
+.zvs-racine *, .zvs-racine *::before, .zvs-racine *::after { box-sizing: border-box; }
+
+.zvs-lanceur { position: fixed; z-index: 2147483000; display: inline-flex; align-items: center; gap: 8px; min-height: var(--tap, 40px); padding: 0 16px; border: 1px solid var(--accent, #2a2aa8); border-radius: var(--r-btn, 0); background: var(--accent, #2a2aa8); color: var(--white, #ffffff); font: inherit; font-weight: 600; cursor: pointer; }
+.zvs-lanceur:hover { background: var(--accent-deep, #1e1b8c); border-color: var(--accent-deep, #1e1b8c); }
+.zvs-lanceur:focus-visible { outline: 2px solid var(--accent-deep, #1e1b8c); outline-offset: 2px; }
+.zvs-lanceur--droite { right: 20px; }
+.zvs-lanceur--gauche { left: 20px; }
+/* Le bord vertical est porte par un modificateur et non par la regle de base :
+   une app qui pose le bouton en haut a souvent deja une barre fixe, et son
+   decalage se regle alors en ligne, par la propriete du meme nom. */
+.zvs-lanceur--bas { bottom: 20px; }
+.zvs-lanceur--haut { top: 20px; }
+/* Centre : la moitie de sa propre largeur, pas celle de la fenetre — un
+   left: 50% seul decale le bouton vers la droite de sa demi-largeur. */
+.zvs-lanceur--centre { left: 50%; transform: translateX(-50%); }
+/* Discret : le bouton se pose sans reclamer l'attention. Les regles viennent
+   APRES celles du bouton plein, meme specificite : c'est l'ordre qui tranche. */
+.zvs-lanceur--discret { background: var(--paper, #f5f6fa); border-color: var(--line, #e3e6ef); color: var(--muted, #5a637a); font-weight: 500; }
+.zvs-lanceur--discret:hover { background: var(--white, #ffffff); border-color: var(--accent, #2a2aa8); color: var(--ink, #0b1020); }
+/* La marque de l'app hote. Le widget ne porte AUCUN logo : il reserve la
+   place et laisse l'app poser le sien, en image ou en SVG. */
+.zvs-marque { display: inline-flex; align-items: center; }
+.zvs-marque img, .zvs-marque svg { display: block; height: 18px; width: auto; }
+
+/* ── Le trace d'une zone a capturer ──────────────────────────────────
+   Au-dessus du tiroir : pendant le trace, le widget est masque et cette
+   surface est la seule chose vivante de la page.
+   ⚠️ PREFIXE zvs-selection ET NON zvs-zone : la classe zvs-zone designe
+   depuis toujours la ZONE DE TEXTE du formulaire. Une regle de voile posee
+   sous ce nom rend le champ fixe et plein ecran — un ecran blanc, sans la
+   moindre erreur en console (constate le 23/09/2026). */
+.zvs-selection { position: fixed; inset: 0; z-index: 2147483003; cursor: crosshair; touch-action: none; }
+.zvs-selection__voile { position: absolute; inset: 0; background: var(--ink, #0b1020); opacity: 0.38; pointer-events: none; }
+.zvs-selection__consigne { position: absolute; top: 20px; left: 50%; transform: translateX(-50%); margin: 0; padding: 8px 14px; max-width: 92vw; background: var(--white, #ffffff); border: 1px solid var(--line, #e3e6ef); border-radius: var(--r-btn, 0); color: var(--ink, #0b1020); font-family: var(--font-text, system-ui, sans-serif); font-size: 13px; text-align: center; pointer-events: none; }
+/* Filet d'accent DOUBLE d'un filet blanc : le trace passe aussi bien sur une
+   zone sombre que sur une zone claire, sans couleur semi-transparente. */
+.zvs-selection__trace { position: absolute; border: 2px solid var(--accent, #2a2aa8); outline: 1px solid var(--white, #ffffff); pointer-events: none; }
+
+/* Voile : couleur du token d'encre + opacite, jamais une couleur
+   semi-transparente ecrite en dur (ce serait une couleur en dur), et jamais
+   color-mix, qui ne se replie sur rien la ou le design system manque. */
+.zvs-voile { position: fixed; inset: 0; z-index: 2147483001; background: var(--ink, #0b1020); opacity: 0.32; }
+.zvs-tiroir { position: fixed; inset: 0 0 0 auto; z-index: 2147483002; display: flex; flex-direction: column; width: min(420px, 100vw); max-width: 100vw; background: var(--white, #ffffff); border-left: 1px solid var(--line, #e3e6ef); }
+@media (max-width: 480px) { .zvs-tiroir { inset: auto 0 0 0; height: 92vh; border-left: none; border-top: 1px solid var(--line, #e3e6ef); } }
+
+.zvs-tete { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 14px 16px; border-bottom: 1px solid var(--line, #e3e6ef); }
+.zvs-titre { margin: 0; font-family: var(--font-display, inherit); font-size: 17px; font-weight: 500; }
+.zvs-fermer { min-width: var(--tap, 40px); min-height: var(--tap, 40px); border: 1px solid transparent; border-radius: var(--r-btn, 0); background: transparent; color: var(--muted, #5a637a); font: inherit; font-size: 18px; cursor: pointer; }
+.zvs-fermer:hover { border-color: var(--line, #e3e6ef); color: var(--ink, #0b1020); }
+
+.zvs-onglets { display: flex; gap: 0; padding: 0 16px; border-bottom: 1px solid var(--line, #e3e6ef); overflow-x: auto; }
+.zvs-onglet { flex: none; min-height: var(--tap, 40px); padding: 0 12px; border: none; border-bottom: 2px solid transparent; background: transparent; color: var(--muted, #5a637a); font: inherit; font-weight: 600; cursor: pointer; white-space: nowrap; }
+.zvs-onglet[aria-selected='true'] { color: var(--accent, #2a2aa8); border-bottom-color: var(--accent, #2a2aa8); }
+
+.zvs-corps { flex: 1 1 auto; min-height: 0; overflow-y: auto; padding: 16px; display: flex; flex-direction: column; gap: 14px; }
+.zvs-pied { flex: none; padding: 12px 16px; border-top: 1px solid var(--line, #e3e6ef); display: flex; gap: 8px; justify-content: flex-end; flex-wrap: wrap; }
+
+.zvs-champ { display: flex; flex-direction: column; gap: 5px; min-width: 0; }
+.zvs-label { font-family: var(--font-mono, inherit); font-size: 10px; font-weight: 600; letter-spacing: 0.18em; text-transform: uppercase; color: var(--label, #8a93a8); }
+.zvs-saisie, .zvs-zone, .zvs-liste-deroulante { width: 100%; min-width: 0; padding: 9px 10px; border: 1px solid var(--line, #e3e6ef); border-radius: var(--r-btn, 0); background: var(--white, #ffffff); color: var(--ink, #0b1020); font: inherit; }
+.zvs-saisie:focus, .zvs-zone:focus, .zvs-liste-deroulante:focus { outline: none; border-color: var(--accent, #2a2aa8); }
+.zvs-zone { min-height: 110px; resize: vertical; }
+.zvs-saisie[aria-invalid='true'], .zvs-zone[aria-invalid='true'] { border-color: var(--err, #b5202c); }
+.zvs-erreur { color: var(--err, #b5202c); font-size: 12px; }
+.zvs-aide { color: var(--muted, #5a637a); font-size: 12px; }
+
+.zvs-bouton { min-height: var(--tap, 40px); padding: 0 14px; border: 1px solid var(--accent, #2a2aa8); border-radius: var(--r-btn, 0); background: var(--accent, #2a2aa8); color: var(--white, #ffffff); font: inherit; font-weight: 600; cursor: pointer; }
+.zvs-bouton:hover { background: var(--accent-deep, #1e1b8c); }
+.zvs-bouton[disabled], .zvs-bouton[aria-disabled='true'] { opacity: 0.55; cursor: default; }
+.zvs-bouton--fantome { background: transparent; color: var(--ink, #0b1020); border-color: var(--line, #e3e6ef); }
+.zvs-bouton--fantome:hover { background: var(--paper, #f5f6fa); }
+
+.zvs-carte { border: 1px solid var(--line, #e3e6ef); border-radius: var(--r-card, 0); background: var(--white, #ffffff); padding: 12px; display: flex; flex-direction: column; gap: 6px; min-width: 0; }
+.zvs-carte--cliquable { cursor: pointer; text-align: left; font: inherit; color: inherit; width: 100%; }
+.zvs-carte--cliquable:hover { border-color: var(--accent-line, #c9d6f5); background: var(--panel, #fbfcfe); }
+.zvs-reference { font-family: var(--font-mono, inherit); font-size: 11px; letter-spacing: 0.12em; color: var(--label, #8a93a8); }
+.zvs-ligne { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; min-width: 0; }
+.zvs-tronque { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+.zvs-coupe { overflow-wrap: anywhere; word-break: break-word; min-width: 0; }
+
+.zvs-pastille { display: inline-flex; align-items: center; padding: 2px 7px; border: 1px solid var(--line, #e3e6ef); border-radius: var(--r-pill, 0); background: var(--paper, #f5f6fa); color: var(--muted, #5a637a); font-family: var(--font-mono, inherit); font-size: 10px; letter-spacing: 0.1em; text-transform: uppercase; }
+.zvs-pastille--ouverte { background: var(--warn-soft, #faf3e2); border-color: var(--warn-line, #ebdcb4); color: var(--warn-ink, #8a6d1e); }
+.zvs-pastille--resolue { background: var(--ok-soft, #e6f3ec); border-color: var(--ok-line, #bfdccb); color: var(--ok, #1c6b4a); }
+.zvs-pastille--attente { background: var(--accent-soft, #eaf1ff); border-color: var(--accent-line, #c9d6f5); color: var(--accent, #2a2aa8); }
+
+.zvs-message { border-left: 2px solid var(--line, #e3e6ef); padding-left: 10px; display: flex; flex-direction: column; gap: 4px; }
+.zvs-message--equipe { border-left-color: var(--accent, #2a2aa8); }
+.zvs-message__corps { white-space: pre-wrap; overflow-wrap: anywhere; }
+.zvs-meta { color: var(--muted, #5a637a); font-size: 12px; }
+
+.zvs-alerte { border: 1px solid var(--line, #e3e6ef); border-left-width: 3px; border-radius: var(--r-card, 0); padding: 10px 12px; background: var(--paper, #f5f6fa); }
+.zvs-alerte--err { background: var(--err-soft, #fdece9); border-color: var(--err-line, #efc9cd); border-left-color: var(--err, #b5202c); }
+.zvs-alerte--ok { background: var(--ok-soft, #e6f3ec); border-color: var(--ok-line, #bfdccb); border-left-color: var(--ok, #1c6b4a); }
+
+.zvs-vide { color: var(--muted, #5a637a); text-align: center; padding: 24px 8px; }
+.zvs-repli { border: 1px solid var(--line, #e3e6ef); border-radius: var(--r-card, 0); padding: 8px 10px; }
+.zvs-repli summary { cursor: pointer; font-family: var(--font-mono, inherit); font-size: 10px; letter-spacing: 0.16em; text-transform: uppercase; color: var(--label, #8a93a8); }
+.zvs-code { margin: 8px 0 0; padding: 8px; background: var(--paper, #f5f6fa); font-family: var(--font-code, monospace); font-size: 11px; white-space: pre-wrap; overflow-wrap: anywhere; max-height: 180px; overflow: auto; }
+.zvs-vignette { display: block; max-width: 100%; height: auto; border: 1px solid var(--line, #e3e6ef); }
+.zvs-scenario { display: flex; flex-direction: column; gap: 6px; border-top: 1px solid var(--hairline, #eef1f8); padding-top: 10px; }
+.zvs-etapes { margin: 0; padding-left: 18px; color: var(--muted, #5a637a); font-size: 13px; }
+.zvs-sr { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+`.trim()
+}
+
+export interface ReferenceToken {
+  propriete: string
+  repli: string | null
+}
+
+/**
+ * Relève toutes les références `var(--…)` d'une feuille et dit si chacune a un
+ * repli. PUR — c'est la fonction que le test interroge.
+ */
+export function referencesDeTokens(css: string): ReferenceToken[] {
+  const references: ReferenceToken[] = []
+  const motif = /var\(\s*(--[\w-]+)\s*([^)]*)\)/g
+  let trouve: RegExpExecArray | null
+  while ((trouve = motif.exec(css)) !== null) {
+    const suite = trouve[2].trim()
+    const repli = suite.startsWith(',') ? suite.slice(1).trim() : null
+    references.push({ propriete: trouve[1], repli: repli === '' ? null : repli })
+  }
+  return references
+}
+
+/**
+ * Relève les classes employées par une feuille. PUR.
+ *
+ * Sert au test qui interdit toute classe hors du préfixe : une règle sur
+ * `.card` ou `.bouton` repeindrait les éléments de l'app hôte, depuis un
+ * paquet qu'elle a installé pour un bouton d'aide.
+ */
+export function classesDeLaFeuille(css: string): string[] {
+  const classes = new Set<string>()
+  const motif = /\.(-?[_a-zA-Z][\w-]*)/g
+  let trouve: RegExpExecArray | null
+  while ((trouve = motif.exec(css)) !== null) classes.add(trouve[1])
+  return [...classes].sort()
+}
+
+interface DocumentObserve {
+  getElementById(id: string): unknown
+  createElement(balise: string): { id: string; textContent: string | null }
+  head: { appendChild(noeud: unknown): unknown } | null
+}
+
+/**
+ * Pose la feuille dans le document, une fois. IMPUR.
+ *
+ * ⚠️ Idempotent par l'identifiant : le widget peut être monté deux fois (un
+ * rendu strict de React le fait exprès en développement), et deux feuilles
+ * identiques ne cassent rien mais s'accumulent à chaque remontage.
+ */
+export function injecterFeuille(document: DocumentObserve | null | undefined): void {
+  if (!document || typeof document.getElementById !== 'function') return
+  if (document.getElementById(ID_FEUILLE)) return
+  const balise = document.createElement('style')
+  balise.id = ID_FEUILLE
+  balise.textContent = feuilleDeStyle()
+  document.head?.appendChild(balise)
+}