discovery-media-player 0.1.0

package/src/__tests__/viewer.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import {
+  clampZoom,
+  clampPage,
+  progressPercent,
+  arrowState,
+  fitWidth,
+  averageColor,
+  isImageDocument,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  PRERENDER_MARGIN,
+  CURRENT_PAGE_MARGIN,
+} from "../viewer";
+
+describe("visionneuse — zoom", () => {
+  it("reste dans les bornes utilisables", () => {
+    expect(clampZoom(10)).toBe(MAX_ZOOM);
+    expect(clampZoom(0.1)).toBe(MIN_ZOOM);
+    expect(clampZoom(1)).toBe(1);
+  });
+
+  // Sans arrondi, les clics successifs dérivent : 1 − 0.2 = 0.7999999999999999.
+  it("ne dérive pas au fil des clics", () => {
+    let z = 1;
+    for (let i = 0; i < 5; i++) z = clampZoom(z - 0.2);
+    expect(z).toBe(MIN_ZOOM);
+    let up = MIN_ZOOM;
+    for (let i = 0; i < 20; i++) up = clampZoom(up + 0.2);
+    expect(up).toBe(MAX_ZOOM);
+    expect(clampZoom(clampZoom(1 - 0.2))).toBe(0.8);
+  });
+
+  it("survit à une valeur absurde", () => {
+    for (const junk of [NaN, undefined, null, "abc"]) {
+      expect(clampZoom(junk as unknown as number)).toBe(MIN_ZOOM);
+    }
+  });
+});
+
+describe("visionneuse — pagination", () => {
+  it("ramène toute page dans les bornes du document", () => {
+    expect(clampPage(0, 10)).toBe(1);
+    expect(clampPage(-3, 10)).toBe(1);
+    expect(clampPage(99, 10)).toBe(10);
+    expect(clampPage("4", 10)).toBe(4);
+    expect(clampPage(undefined, 10)).toBe(1);
+  });
+
+  // Document pas encore mesuré : on ne doit ni diviser par zéro ni renvoyer 0.
+  it("tient avant que le document soit mesuré", () => {
+    expect(clampPage(5, 0)).toBe(1);
+    expect(progressPercent(1, 0)).toBe(0);
+  });
+
+  it("calcule une progression entière", () => {
+    expect(progressPercent(1, 4)).toBe(25);
+    expect(progressPercent(4, 4)).toBe(100);
+    expect(progressPercent(1, 3)).toBe(33);
+    expect(progressPercent(99, 10)).toBe(100);
+  });
+
+  it("désactive les flèches aux extrémités", () => {
+    expect(arrowState(1, 5)).toEqual({ prevDisabled: true, nextDisabled: false });
+    expect(arrowState(3, 5)).toEqual({ prevDisabled: false, nextDisabled: false });
+    expect(arrowState(5, 5)).toEqual({ prevDisabled: false, nextDisabled: true });
+    // Document non mesuré : « suivant » reste ouvert, sinon on bloquerait au chargement.
+    expect(arrowState(1, 0)).toEqual({ prevDisabled: true, nextDisabled: false });
+  });
+
+  // Confondre ces deux marges faisait considérer comme « courante » une page encore sous le pli
+  // → l'audience était en retard d'une page sur le présentateur.
+  it("distingue la marge de pré-rendu de la bande de page courante", () => {
+    expect(PRERENDER_MARGIN).toBe("500px 0px");
+    expect(CURRENT_PAGE_MARGIN).toBe("-48% 0px -48% 0px");
+    expect(PRERENDER_MARGIN).not.toBe(CURRENT_PAGE_MARGIN);
+  });
+});
+
+describe("visionneuse — largeur d'une page", () => {
+  it("en défilement, suit la largeur du cadre et le zoom", () => {
+    expect(fitWidth({ containerWidth: 900 })).toBe(900);
+    expect(fitWidth({ containerWidth: 900, zoom: 2 })).toBe(1800);
+  });
+
+  it("ne descend jamais sous une largeur lisible", () => {
+    expect(fitWidth({ containerWidth: 100 })).toBe(280);
+    expect(fitWidth({ containerWidth: 0 })).toBe(900); // cadre pas encore mesuré → repli
+  });
+
+  // Sans la borne par la hauteur, la page débordait sous la feuille de conversation.
+  it("en mode une-page, tient dans la hauteur disponible", () => {
+    const large = fitWidth({ containerWidth: 2000, containerHeight: 1000, onePage: true, aspect: 1.35 });
+    expect(large).toBeCloseTo((1000 - 28) / 1.35, 5);
+    expect(large).toBeLessThan(2000);
+  });
+
+  it("retire du calcul ce qui recouvre le document", () => {
+    const sans = fitWidth({ containerWidth: 2000, containerHeight: 1000, onePage: true });
+    const avecFeuille = fitWidth({ containerWidth: 2000, containerHeight: 1000, onePage: true, overlap: 300 });
+    const avecBandeau = fitWidth({ containerWidth: 2000, containerHeight: 1000, onePage: true, reserve: 200 });
+    expect(avecFeuille).toBeLessThan(sans);
+    expect(avecBandeau).toBeLessThan(sans);
+  });
+
+  // Panneau presque plein écran : mieux vaut une page trop haute qu'un timbre-poste illisible.
+  it("abandonne la contrainte de hauteur quand elle deviendrait absurde", () => {
+    expect(fitWidth({ containerWidth: 800, containerHeight: 200, onePage: true, overlap: 190 })).toBe(800);
+  });
+
+  it("n'agrandit jamais une page au-delà du zoom demandé", () => {
+    expect(fitWidth({ containerWidth: 400, containerHeight: 5000, onePage: true })).toBe(400);
+  });
+});
+
+describe("visionneuse — divers", () => {
+  it("moyenne une bande de pixels", () => {
+    expect(averageColor([255, 0, 0, 255, 255, 0, 0, 255])).toBe("rgb(255,0,0)");
+    expect(averageColor([0, 0, 0, 255, 255, 255, 255, 255])).toBe("rgb(128,128,128)");
+    expect(averageColor([])).toBe("rgb(0,0,0)"); // canvas vide : pas de division par zéro
+  });
+
+  // Le type MIME n'est pas toujours renvoyé par le stockage : le nom fait foi.
+  it("reconnaît une image à son nom, pas à son type déclaré", () => {
+    for (const n of ["plan.png", "vue.JPG", "a.jpeg", "b.webp", "c.gif", "d.avif", "e.png?v=2"]) {
+      expect(isImageDocument(n), n).toBe(true);
+    }
+    for (const n of ["dossier.pdf", "note.txt", "", null, "image.png.pdf"]) {
+      expect(isImageDocument(n), String(n)).toBe(false);
+    }
+    expect(isImageDocument(null, "https://x/y/photo.jpg")).toBe(true);
+  });
+});

package/src/bridge.ts

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: MIT
+//
+// ⚠️ CE FICHIER EST SOUS MIT, pas AGPL — délibérément, et c'est le seul.
+// C'est le contrat que l'application hôte doit importer pour parler au player. Le placer sous la
+// licence du cœur obligerait un hôte à ouvrir son propre code pour avoir le droit d'échanger dix
+// messages avec une iframe : la licence deviendrait un péage à l'intégration, ce qui n'est pas ce
+// qu'on protège. On protège le player, pas ceux qui s'y branchent.
+
+// Contrat postMessage entre le PLAYER (iframe) et l'APPLICATION HÔTE qui l'affiche.
+//
+// Le player vit dans une iframe : il possède le document, la barre d'outils et la présentation,
+// mais tout ce qui exige le jeton de session de l'hôte (inviter l'équipe, passer la main, ouvrir
+// la modale de partage) doit remonter à l'application. Ce fichier est le SEUL endroit où le
+// format de ces messages est décrit — les deux côtés l'importent.
+//
+// Il était auparavant écrit à la main des deux côtés : dix types de messages dupliqués, non
+// typés, validés par des `String(d.slug || "")` sans borne. Deux bugs en sont venus (validation
+// d'origine trop stricte qui bloquait la réception en production ; fermeture du viewer avant le
+// retrait de présence, qui laissait un participant fantôme).
+//
+// VALIDATION PAR TYPE, PAS PAR ORIGINE — délibéré. Un contrôle strict de `e.origin` bloquait la
+// réception en production (l'iframe et l'app ne partagent pas toujours la même origine perçue).
+// Les actions transportées sont inoffensives : elles ouvrent une modale ou ferment une vue, et
+// tout ce qui touche aux données est revérifié côté serveur avec le JWT. Le `slug` est en
+// revanche borné ici (charset + longueur) : c'est la seule donnée qui traverse la frontière.
+
+/** Préfixe historique des messages sur le fil. Neutralisable d'un seul endroit le jour de l'ouverture. */
+const WIRE_PREFIX = "3dd-doc-";
+
+/** Slugs de partage et de présentation : `randomBytes(9).toString("base64url")` → 12 caractères. */
+const SLUG_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+/** Messages émis par le player vers l'application hôte. */
+export type PlayerMessage =
+  | { type: "close" }
+  | { type: "share" }
+  | { type: "embed-ready" }
+  // ⚠️ Le silence ne suffit pas. `embed-ready` absent peut vouloir dire deux choses OPPOSÉES :
+  // le player n'est pas là (instance absente, en panne, en cours de déploiement) — ou le player
+  // REFUSE d'afficher (partage révoqué, mur d'accès, greffon manquant en fail-closed). Un hôte
+  // qui replie sur le lecteur du navigateur transformerait alors un refus en ouverture.
+  // Signalé par un hôte en cours d'intégration. `reason` reste indicatif : la décision est déjà prise.
+  | { type: "embed-denied"; reason: string }
+  | { type: "present-left" }
+  | { type: "present-denied" }
+  | { type: "present-invite"; slug: string }
+  | { type: "present-handover"; slug: string }
+  | { type: "present-switch"; slug: string };
+
+/** Messages émis par l'application hôte vers le player. */
+export type HostMessage = { type: "handover-done" };
+
+const PLAYER_PLAIN = ["close", "share", "embed-ready", "present-left", "present-denied"] as const;
+const PLAYER_WITH_REASON = ["embed-denied"] as const;
+const PLAYER_WITH_SLUG = ["present-invite", "present-handover", "present-switch"] as const;
+const HOST_PLAIN = ["handover-done"] as const;
+
+type WireMessage = { type: string; slug?: string; reason?: string };
+
+/** Forme transportée sur le fil (préfixée), pour un message typé. */
+export function toWire(msg: PlayerMessage | HostMessage): WireMessage {
+  const wire: WireMessage = { type: WIRE_PREFIX + msg.type };
+  if ("slug" in msg && msg.slug) wire.slug = msg.slug;
+  if ("reason" in msg && msg.reason) wire.reason = String(msg.reason).slice(0, 40);
+  return wire;
+}
+
+function parse<T extends { type: string }>(
+  data: unknown,
+  plain: readonly string[],
+  withSlug: readonly string[],
+): T | null {
+  if (!data || typeof data !== "object") return null;
+  const raw = (data as { type?: unknown }).type;
+  if (typeof raw !== "string" || !raw.startsWith(WIRE_PREFIX)) return null;
+  const type = raw.slice(WIRE_PREFIX.length);
+  if (plain.includes(type)) return { type } as T;
+  if (PLAYER_WITH_REASON.includes(type as never)) {
+    const reason = (data as { reason?: unknown }).reason;
+    // Motif borné et sans surprise : il traverse une frontière et finit parfois à l'écran.
+    return { type, reason: /^[a-z-]{1,40}$/.test(String(reason || "")) ? String(reason) : "unknown" } as unknown as T;
+  }
+  if (!withSlug.includes(type)) return null;
+  const slug = (data as { slug?: unknown }).slug;
+  // Un message à slug SANS slug valide est rejeté : mieux vaut ne rien ouvrir qu'ouvrir sur du vide.
+  if (typeof slug !== "string" || !SLUG_RE.test(slug)) return null;
+  return { type, slug } as unknown as T;
+}
+
+/** Côté HÔTE : lit un message reçu du player. `null` si ce n'en est pas un. */
+export function parsePlayerMessage(data: unknown): PlayerMessage | null {
+  return parse<PlayerMessage>(data, PLAYER_PLAIN, PLAYER_WITH_SLUG);
+}
+
+/** Côté PLAYER : lit un message reçu de l'hôte. `null` si ce n'en est pas un. */
+export function parseHostMessage(data: unknown): HostMessage | null {
+  return parse<HostMessage>(data, HOST_PLAIN, []);
+}
+
+// ── Runtime ────────────────────────────────────────────────────────────────────────────────────
+// Tout est en `try` : un player qui ne parvient pas à parler à son hôte doit continuer à afficher
+// le document. Perdre le bouton « Partager » est ennuyeux, perdre le document est inacceptable.
+
+/** Côté PLAYER : envoie un message à l'application hôte. */
+export function sendToHost(msg: PlayerMessage, target?: Window | null): void {
+  try {
+    const win = target || (typeof window !== "undefined" ? window.parent : null);
+    if (win) win.postMessage(toWire(msg), "*");
+  } catch { /* l'hôte est peut-être absent (page publique) : sans effet */ }
+}
+
+/** Côté HÔTE : envoie un message au player. */
+export function sendToPlayer(frame: HTMLIFrameElement | null | undefined, msg: HostMessage): void {
+  try {
+    frame?.contentWindow?.postMessage(toWire(msg), "*");
+  } catch { /* iframe déjà détruite */ }
+}
+
+/** Côté HÔTE : écoute les messages du player. Renvoie la fonction de désabonnement. */
+export function onPlayerMessage(cb: (msg: PlayerMessage) => void, win?: Window): () => void {
+  const target = win || (typeof window !== "undefined" ? window : null);
+  if (!target) return () => {};
+  const handler = (e: MessageEvent) => {
+    const msg = parsePlayerMessage(e.data);
+    if (msg) cb(msg);
+  };
+  target.addEventListener("message", handler);
+  return () => target.removeEventListener("message", handler);
+}
+
+/** Côté PLAYER : écoute les messages de l'hôte. Renvoie la fonction de désabonnement. */
+export function onHostMessage(cb: (msg: HostMessage) => void, win?: Window): () => void {
+  const target = win || (typeof window !== "undefined" ? window : null);
+  if (!target) return () => {};
+  const handler = (e: MessageEvent) => {
+    const msg = parseHostMessage(e.data);
+    if (msg) cb(msg);
+  };
+  target.addEventListener("message", handler);
+  return () => target.removeEventListener("message", handler);
+}

package/src/chat.ts

@@ -0,0 +1,103 @@
+// Rendu des messages du chat de présentation : d'un message à son fragment HTML.
+//
+// Ces fonctions produisent une CHAÎNE, pas des nœuds — c'est ce qui les rend testables, et c'est
+// aussi ce qui les rend dangereuses : tout ce qui n'est pas échappé ici devient du balisage
+// exécutable chez tous les spectateurs. Un message contenant du balisage a déjà produit un XSS
+// stocké sur la page audience. Les tests vérifient donc non seulement la chaîne produite, mais ce
+// que le NAVIGATEUR en fait réellement une fois insérée (harnais jsdom).
+//
+// Règle sans exception : **toute** donnée venant d'un participant — nom, corps, citation, nom de
+// pièce jointe, URL, emoji de réaction — passe par `escapeHtml` ou `formatMessageBody`.
+
+import { escapeHtml, formatMessageBody, avatarHtml, isMine, canModerate, reactorId, type ChatMessage, type Me } from "./live";
+
+export interface Attachment {
+  kind?: string;
+  url?: string;
+  name?: string;
+}
+
+export interface ChatMessageFull extends ChatMessage {
+  reply_to?: number | string | null;
+  reply_name?: string;
+  reply_text?: string;
+  edited?: boolean;
+  is_presenter?: boolean;
+  attachment?: Attachment | null;
+  reactions?: Record<string, string[]> | null;
+}
+
+export interface ChatRenderContext {
+  me: Me | null | undefined;
+  /** Balisage de l'icône « réagir » — fourni par l'hôte, jamais construit ici. */
+  reactIcon?: string;
+}
+
+/** Pastilles de réaction. L'emoji vient du réseau : il est échappé comme le reste. */
+export function renderReactions(msg: ChatMessageFull | null | undefined, me: Me | null | undefined): string {
+  const reactions = (msg && msg.reactions) || {};
+  const mineId = reactorId(me);
+  let out = "";
+  for (const emoji in reactions) {
+    const reactors = reactions[emoji] || [];
+    if (!reactors.length) continue;
+    const mine = reactors.indexOf(mineId) >= 0;
+    out += `<button class="re-chip${mine ? " on" : ""}" data-e="${escapeHtml(emoji)}">${escapeHtml(emoji)} ${reactors.length}</button>`;
+  }
+  return out;
+}
+
+/** Pièce jointe : vignette d'image, ou carte PDF dont la vignette est peinte après coup. */
+export function renderAttachment(attachment: Attachment | null | undefined): string {
+  if (!attachment || !attachment.url) return "";
+  const url = escapeHtml(attachment.url);
+  if (attachment.kind === "image") {
+    return `<a class=cm-att href="${url}" target=_blank rel=noreferrer><img src="${url}" alt="" loading=lazy></a>`;
+  }
+  const label = escapeHtml(attachment.name || "Document.pdf");
+  return `<a class=cm-att-pdf href="${url}" target=_blank rel=noreferrer data-pdf="${url}"><span class=cm-att-ph></span><span class=cm-pdflabel>${label}</span></a>`;
+}
+
+/** Boutons d'action. « Modifier » n'apparaît que sur ses propres messages ; « Supprimer » aussi, sauf pour le présentateur. */
+export function renderActions(msg: ChatMessageFull, ctx: ChatRenderContext): string {
+  const mine = isMine(msg, ctx.me);
+  let actions = `<button class=cm-react title="Réagir">${ctx.reactIcon || ""}</button><button class=cm-reply title="Répondre">↩</button>`;
+  if (mine) actions += '<button class=cm-edit title="Modifier">✎</button>';
+  if (mine || canModerate(ctx.me)) actions += '<button class=cm-del-btn title="Supprimer">🗑</button>';
+  return actions;
+}
+
+/** Contenu interne d'un message, prêt à être posé dans son conteneur. */
+export function renderMessage(msg: ChatMessageFull, ctx: ChatRenderContext): string {
+  // Un message supprimé ne laisse RIEN filtrer de son contenu d'origine — ni corps, ni citation,
+  // ni pièce jointe. La suppression est une suppression, pas un masquage visuel.
+  if (msg.deleted) {
+    return '<span class=a></span><span class=b><div class="txt cm-del">Message supprimé</div></span>';
+  }
+  const quote = msg.reply_to
+    ? `<div class=cm-q><b>${escapeHtml(msg.reply_name || "")}</b> ${escapeHtml(msg.reply_text || "")}</div>`
+    : "";
+  const edited = msg.edited ? ' <span class=cm-ed>(modifié)</span>' : "";
+  const body = msg.body ? `<div class=txt>${formatMessageBody(msg.body)}${edited}</div>` : "";
+  const presenterTag = msg.is_presenter ? ' <span class=tag>présentateur</span>' : "";
+
+  return (
+    `<span class=a>${avatarHtml(msg.author_avatar, msg.author_name)}</span>` +
+    `<span class=b><div class=who><b>${escapeHtml(msg.author_name || "Invité")}</b>${presenterTag}</div>` +
+    quote +
+    body +
+    renderAttachment(msg.attachment) +
+    `<div class=cm-re>${renderReactions(msg, ctx.me)}</div></span>` +
+    `<span class=cm-act>${renderActions(msg, ctx)}</span>`
+  );
+}
+
+/** Classes du conteneur d'un message — état visuel dérivé, jamais saisi par l'auteur. */
+export function messageClassName(msg: ChatMessageFull, me: Me | null | undefined, mentioned: boolean): string {
+  return (
+    "cm" +
+    (isMine(msg, me) ? " me" : "") +
+    (msg.deleted ? " isdel" : "") +
+    (mentioned ? " mentioned" : "")
+  );
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// Point d'entrée du code navigateur du player.
+//
+// esbuild regroupe ce fichier en un IIFE exposé sous `window.Player` (cf. player/build/bundle.mjs).
+// La visionneuse — encore écrite en template literal dans api/doc.js — appelle donc
+// `Player.bridge.…` et `Player.tracking.…`. Chaque brique reste un espace de noms distinct :
+// c'est ce qui permet de les extraire une par une sans renommer les précédentes.
+
+export * as bridge from "./bridge";
+export * as tracking from "./tracking";
+export * as live from "./live";
+export * as chat from "./chat";
+export * as presentation from "./presentation-content";
+export * as viewer from "./viewer";
+export * as presentationState from "./presentation-state";

package/src/live.ts

@@ -0,0 +1,225 @@
+// Cœur logique de la présentation en direct : identité des participants, dédoublonnage de la
+// présence, échappement et mise en forme des messages, prédicats de modération et de notification.
+//
+// PÉRIMÈTRE : uniquement ce qui ne touche PAS au DOM. Le rendu (messages, panneau, dialogues,
+// vignettes PDF) reste pour l'instant dans le template de api/doc.js — il demandera un harnais
+// DOM pour être testé, et c'est un chantier distinct. Ce qui est ici est ce qui a réellement
+// cassé par le passé, et donc ce qui mérite des tests en premier :
+//
+//   - la présence dédoublonnée : sans identité stable, un participant reconnecté apparaissait
+//     DEUX fois (« je me vois deux fois ») ;
+//   - l'échappement : un titre ou un message contenant du balisage a déjà produit un XSS stocké
+//     sur la page audience ;
+//   - l'identité persistée : c'est elle qui permet de recoller les statistiques de présence
+//     d'un visiteur anonyme d'une session à l'autre.
+
+/** Stockage persistant minimal. `localStorage` lève en navigation privée → tout est en `try`. */
+export interface KeyValueStore {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+// ⚠️ Ces clés sont un CONTRAT avec les navigateurs déjà passés sur une présentation : les changer
+// fait perdre l'identité anonyme (statistiques de présence recollées) et la propriété des messages
+// (le droit de modifier/supprimer les siens). Neutralisation du préfixe = au moment de l'ouverture.
+export const STORAGE_KEYS = {
+  attendeeKey: "3dd-present-attkey",
+  authorToken: "3dd-present-authtoken",
+  chatMuted: "3dd-present-mute",
+} as const;
+
+export interface Participant {
+  uid?: string;
+  email?: string;
+  name?: string;
+  avatar?: string;
+  role?: string;
+}
+
+export interface Me {
+  email?: string;
+  name?: string;
+  role?: string;
+  member?: boolean;
+  avatar?: string;
+}
+
+export interface ChatMessage {
+  id?: number | string;
+  author_email?: string;
+  author_name?: string;
+  author_avatar?: string;
+  body?: string;
+  deleted?: boolean;
+}
+
+// ── Échappement et mise en forme ───────────────────────────────────────────────────────────────
+
+/** Échappe pour insertion dans du HTML. Tout texte venant d'un participant passe par ici. */
+export function escapeHtml(value: unknown): string {
+  return String(value == null ? "" : value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/** Initiales d'un nom, pour l'avatar de repli. */
+export function initials(name?: string): string {
+  const parts = (name || "?").trim().split(/\s+/);
+  return (((parts[0] || "")[0] || "?") + ((parts[1] || "")[0] || "")).toUpperCase();
+}
+
+/** Avatar : l'image si elle existe, sinon les initiales. Les deux sont échappées. */
+export function avatarHtml(url?: string, name?: string): string {
+  return url ? `<img src="${escapeHtml(url)}" alt="">` : escapeHtml(initials(name));
+}
+
+/**
+ * Corps d'un message, prêt à insérer : échappé D'ABORD, puis enrichi de liens et de mentions.
+ * L'ordre est vital — enrichir avant d'échapper rendrait le balisage de l'auteur exécutable.
+ * Seuls `http(s)://` sont transformés en liens : pas de `javascript:` ni de `data:`.
+ */
+export function formatMessageBody(body: unknown): string {
+  let out = escapeHtml(body);
+  out = out.replace(
+    /(https?:\/\/[^\s<]+)/g,
+    (url) => `<a href="${url}" target=_blank rel=noreferrer class=cm-link>${url}</a>`,
+  );
+  out = out.replace(
+    /(^|\s)@([\p{L}0-9_'.-]+)/gu,
+    (_all, before: string, handle: string) => `${before}<span class=cm-mention>@${handle}</span>`,
+  );
+  return out;
+}
+
+// ── Présence ───────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Aplatit l'état de présence Realtime en une liste SANS DOUBLON.
+ *
+ * La clé de présence du canal contient un identifiant tiré au sort à chaque chargement de page :
+ * un participant qui se reconnecte y apparaît donc deux fois. On collapse sur une identité
+ * STABLE (`uid`, sinon email, sinon nom) — c'est ce qui a corrigé « je me vois deux fois ».
+ * En cas de collision, la métadonnée du présentateur l'emporte : c'est elle qui porte le rôle.
+ */
+export function flattenPresence(state: Record<string, Participant[]> | null | undefined): Participant[] {
+  const byIdentity: Record<string, Participant> = {};
+  const order: string[] = [];
+  for (const key in state || {}) {
+    for (const member of (state || {})[key] || []) {
+      // Participant sans aucune identité : on ne peut pas le dédoublonner, on le garde tel quel
+      // plutôt que de fondre des inconnus distincts en un seul.
+      const identity = String(member.uid || member.email || member.name || "").toLowerCase()
+        || `_${key}_${order.length}`;
+      if (!byIdentity[identity]) { byIdentity[identity] = member; order.push(identity); }
+      else if (member.role === "presenter") byIdentity[identity] = member;
+    }
+  }
+  return order.map((id) => byIdentity[id]);
+}
+
+// ── Identité ───────────────────────────────────────────────────────────────────────────────────
+
+function readStore(store: KeyValueStore | null | undefined, key: string): string | null {
+  try { return store ? store.getItem(key) : null; } catch { return null; }
+}
+
+function writeStore(store: KeyValueStore | null | undefined, key: string, value: string): void {
+  try { store?.setItem(key, value); } catch { /* navigation privée, quota : sans effet */ }
+}
+
+/**
+ * Clé stable d'un participant pour les statistiques de présence : son email s'il est membre,
+ * sinon un identifiant de navigateur persistant. Sans lui, chaque rechargement compterait
+ * comme un nouveau participant.
+ */
+export function attendeeKey(
+  me: Me | null | undefined,
+  store?: KeyValueStore | null,
+  fallbackId = "anon",
+  randomId: () => string = () => Math.random().toString(36).slice(2, 10),
+): string {
+  if (me?.email) return String(me.email).toLowerCase();
+  try {
+    if (!store) return `anon-${fallbackId}`;
+    const existing = store.getItem(STORAGE_KEYS.attendeeKey);
+    if (existing) return existing;
+    const created = `anon-${randomId()}`;
+    store.setItem(STORAGE_KEYS.attendeeKey, created);
+    return created;
+  } catch {
+    // Stockage indisponible (navigation privée, quota) : la clé ne survivra pas au rechargement,
+    // le participant comptera pour deux visites. Dégradation acceptée, jamais une erreur.
+    return `anon-${fallbackId}`;
+  }
+}
+
+/**
+ * Jeton d'auteur : c'est lui qui prouve « ce message est le mien » pour le modifier ou le
+ * supprimer. Persistant, propre au navigateur, jamais envoyé par le serveur.
+ */
+export function authorToken(
+  store?: KeyValueStore | null,
+  randomId: () => string = () => Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2),
+): string {
+  const existing = readStore(store, STORAGE_KEYS.authorToken);
+  if (existing) return existing;
+  const created = randomId();
+  writeStore(store, STORAGE_KEYS.authorToken, created);
+  return created;
+}
+
+/** Identifiant utilisé pour marquer ses propres réactions emoji. */
+export function reactorId(me: Me | null | undefined): string {
+  return String((me && (me.email || me.name)) || "").toLowerCase();
+}
+
+// ── Prédicats ──────────────────────────────────────────────────────────────────────────────────
+
+/** Ce message est-il de moi ? Par email si connu, sinon par nom entre anonymes. */
+export function isMine(msg: ChatMessage | null | undefined, me: Me | null | undefined): boolean {
+  if (!msg || !me) return false;
+  if (msg.author_email && me.email) return msg.author_email === me.email;
+  if (!msg.author_email && !me.email) return msg.author_name === me.name;
+  return false;
+}
+
+/** Seul le présentateur modère. Le rôle vient du serveur (control_token valide), pas du client. */
+export function canModerate(me: Me | null | undefined): boolean {
+  return !!(me && me.role === "presenter");
+}
+
+/** Suis-je cité ? On compare au PRÉNOM, comme dans le chat de l'application. */
+export function isMentioned(msg: ChatMessage | null | undefined, me: Me | null | undefined): boolean {
+  if (!me || !me.name) return false;
+  const firstName = (me.name.split(/\s+/)[0] || "").toLowerCase();
+  if (!firstName) return false;
+  return String((msg && msg.body) || "").toLowerCase().includes(`@${firstName}`) && !isMine(msg, me);
+}
+
+// ── Notifications de chat ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Faut-il compter ce message comme non lu ?
+ * `historyLoaded` est la garde décisive : sans elle, l'historique rechargé au join ferait
+ * apparaître un badge de dizaines de messages déjà vus.
+ */
+export function shouldNotify(input: {
+  msg: ChatMessage | null | undefined;
+  me: Me | null | undefined;
+  historyLoaded: boolean;
+  chatHidden: boolean;
+}): boolean {
+  const { msg, me, historyLoaded, chatHidden } = input;
+  if (!historyLoaded) return false;
+  if (!msg || msg.deleted) return false;
+  if (isMine(msg, me)) return false;
+  return chatHidden;
+}
+
+/** Libellé du badge de non-lus : au-delà de 9, on écrit « 9+ ». */
+export function unreadLabel(count: number): string {
+  if (!count || count <= 0) return "";
+  return count > 9 ? "9+" : String(count);
+}