discovery-media-player 0.1.0

package/src/__tests__/live.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect } from "vitest";
+import {
+  escapeHtml,
+  initials,
+  avatarHtml,
+  formatMessageBody,
+  flattenPresence,
+  attendeeKey,
+  authorToken,
+  reactorId,
+  isMine,
+  canModerate,
+  isMentioned,
+  shouldNotify,
+  unreadLabel,
+  STORAGE_KEYS,
+  type KeyValueStore,
+} from "../live";
+
+function memoryStore(seed: Record<string, string> = {}): KeyValueStore & { data: Record<string, string> } {
+  const data = { ...seed };
+  return { data, getItem: (k) => (k in data ? data[k] : null), setItem: (k, v) => { data[k] = v; } };
+}
+
+const hostileStore: KeyValueStore = {
+  getItem() { throw new Error("navigation privée"); },
+  setItem() { throw new Error("navigation privée"); },
+};
+
+describe("live — présence dédoublonnée", () => {
+  // LE bug « je me vois deux fois » : la clé du canal contient un identifiant tiré au sort à chaque
+  // chargement, donc un reconnecté occupe deux entrées. Seule l'identité stable les fond.
+  it("fond deux entrées du même participant reconnecté", () => {
+    const list = flattenPresence({
+      "moi@example.fr:aleatoire1": [{ uid: "moi@example.fr", name: "Moi" }],
+      "moi@example.fr:aleatoire2": [{ uid: "moi@example.fr", name: "Moi" }],
+      "autre:xyz": [{ uid: "autre@example.fr", name: "Autre" }],
+    });
+    expect(list).toHaveLength(2);
+    expect(list.map((p) => p.name)).toEqual(["Moi", "Autre"]);
+  });
+
+  it("l'identité est insensible à la casse et retombe sur l'email puis le nom", () => {
+    expect(flattenPresence({ a: [{ email: "A@Example.fr" }], b: [{ email: "a@example.fr" }] })).toHaveLength(1);
+    expect(flattenPresence({ a: [{ name: "Léa" }], b: [{ name: "léa" }] })).toHaveLength(1);
+  });
+
+  // En cas de collision, c'est la métadonnée du présentateur qui porte le rôle : la perdre
+  // ferait disparaître le badge « présentateur » de la liste des participants.
+  it("le présentateur l'emporte sur son propre doublon spectateur", () => {
+    const list = flattenPresence({
+      onglet1: [{ uid: "u1", name: "Léa", role: "viewer" }],
+      onglet2: [{ uid: "u1", name: "Léa", role: "presenter" }],
+    });
+    expect(list).toHaveLength(1);
+    expect(list[0].role).toBe("presenter");
+  });
+
+  // Sans identité, on ne peut PAS dédoublonner : fondre des inconnus distincts en un seul
+  // masquerait des participants réels.
+  it("garde distincts les participants sans aucune identité", () => {
+    expect(flattenPresence({ a: [{}], b: [{}] })).toHaveLength(2);
+  });
+
+  it("supporte un état vide, nul ou biscornu", () => {
+    expect(flattenPresence(null)).toEqual([]);
+    expect(flattenPresence(undefined)).toEqual([]);
+    expect(flattenPresence({})).toEqual([]);
+    expect(flattenPresence({ a: [] })).toEqual([]);
+  });
+});
+
+describe("live — échappement et mise en forme", () => {
+  it("échappe ce qui pourrait sortir du balisage", () => {
+    expect(escapeHtml('<b>&"')).toBe("&lt;b&gt;&amp;&quot;");
+    expect(escapeHtml(null)).toBe("");
+    expect(escapeHtml(undefined)).toBe("");
+  });
+
+  // Un message contenant </script> a déjà produit un XSS stocké sur la page audience.
+  it("neutralise une tentative de fermeture de balise", () => {
+    const out = formatMessageBody("</script><script>alert(1)</script>");
+    expect(out).not.toMatch(/<\/script/i);
+    expect(out).not.toMatch(/<script/i);
+  });
+
+  it("neutralise un gestionnaire d'événement injecté", () => {
+    const out = formatMessageBody('<img src=x onerror="alert(1)">');
+    expect(out).not.toMatch(/<img/i);
+    expect(out).toContain("&lt;img");
+  });
+
+  // L'ordre est vital : enrichir AVANT d'échapper rendrait le balisage de l'auteur exécutable.
+  it("échappe d'abord, enrichit ensuite", () => {
+    const out = formatMessageBody('Voir <b>ici</b> https://exemple.fr/a?x=1&y=2');
+    expect(out).toContain("&lt;b&gt;ici&lt;/b&gt;");
+    expect(out).toContain('<a href="https://exemple.fr/a?x=1&amp;y=2"');
+    expect(out).toContain("rel=noreferrer");
+  });
+
+  it("ne transforme en lien QUE http(s) — jamais javascript: ni data:", () => {
+    for (const hostile of ["javascript:alert(1)", "data:text/html,<b>x</b>", "vbscript:x"]) {
+      expect(formatMessageBody(hostile)).not.toContain("<a href");
+    }
+  });
+
+  it("met en valeur les mentions, accents compris", () => {
+    expect(formatMessageBody("salut @léa ça va")).toContain("<span class=cm-mention>@léa</span>");
+    expect(formatMessageBody("email@exemple.fr")).not.toContain("cm-mention"); // pas en début de mot
+  });
+
+  it("initiales et avatar de repli", () => {
+    expect(initials("Léa Martin")).toBe("LM");
+    expect(initials("Solo")).toBe("S");
+    expect(initials("")).toBe("?");
+    expect(initials(undefined)).toBe("?");
+    expect(avatarHtml("", "Léa Martin")).toBe("LM");
+    expect(avatarHtml('x" onerror="alert(1)', "n")).toBe('<img src="x&quot; onerror=&quot;alert(1)" alt="">');
+  });
+});
+
+describe("live — identité persistante", () => {
+  it("un membre est identifié par son email, en minuscules", () => {
+    expect(attendeeKey({ email: "Lea@Example.FR" }, memoryStore())).toBe("lea@example.fr");
+  });
+
+  it("un anonyme reçoit une clé persistante, réutilisée ensuite", () => {
+    const store = memoryStore();
+    const first = attendeeKey(null, store, "session", () => "abc123");
+    expect(first).toBe("anon-abc123");
+    expect(store.data[STORAGE_KEYS.attendeeKey]).toBe("anon-abc123");
+    expect(attendeeKey(null, store, "session", () => "autre")).toBe("anon-abc123");
+  });
+
+  // Sans persistance, le participant comptera pour deux visites : c'est dégradé, pas cassé.
+  it("retombe sur l'identifiant de session si le stockage est indisponible", () => {
+    expect(attendeeKey(null, hostileStore, "session-42")).toBe("anon-session-42");
+    expect(attendeeKey(null, null, "session-42")).toBe("anon-session-42");
+  });
+
+  it("le jeton d'auteur est créé une fois puis réutilisé", () => {
+    const store = memoryStore();
+    const token = authorToken(store, () => "jeton-stable");
+    expect(token).toBe("jeton-stable");
+    expect(authorToken(store, () => "autre")).toBe("jeton-stable");
+  });
+
+  it("le jeton d'auteur survit à un stockage qui lève", () => {
+    expect(authorToken(hostileStore, () => "ephemere")).toBe("ephemere");
+  });
+
+  it("l'identifiant de réaction retombe sur le nom pour un anonyme", () => {
+    expect(reactorId({ email: "A@B.fr" })).toBe("a@b.fr");
+    expect(reactorId({ name: "Léa" })).toBe("léa");
+    expect(reactorId(null)).toBe("");
+  });
+});
+
+describe("live — prédicats", () => {
+  it("reconnaît mes messages par email, et par nom entre anonymes", () => {
+    expect(isMine({ author_email: "a@b.fr" }, { email: "a@b.fr" })).toBe(true);
+    expect(isMine({ author_email: "a@b.fr" }, { email: "z@b.fr" })).toBe(false);
+    expect(isMine({ author_name: "Léa" }, { name: "Léa" })).toBe(true);
+    expect(isMine({ author_name: "Léa" }, { name: "Autre" })).toBe(false);
+  });
+
+  // Un membre identifié ne doit pas s'approprier le message d'un anonyme homonyme.
+  it("ne mélange pas un auteur identifié et un lecteur anonyme", () => {
+    expect(isMine({ author_email: "a@b.fr", author_name: "Léa" }, { name: "Léa" })).toBe(false);
+    expect(isMine({ author_name: "Léa" }, { email: "a@b.fr", name: "Léa" })).toBe(false);
+  });
+
+  it("seul le présentateur modère", () => {
+    expect(canModerate({ role: "presenter" })).toBe(true);
+    expect(canModerate({ role: "viewer" })).toBe(false);
+    expect(canModerate(null)).toBe(false);
+  });
+
+  it("détecte une citation par le prénom, sauf la sienne", () => {
+    const me = { name: "Léa Martin", email: "lea@b.fr" };
+    expect(isMentioned({ body: "merci @léa" }, me)).toBe(true);
+    expect(isMentioned({ body: "MERCI @LÉA" }, me)).toBe(true);
+    expect(isMentioned({ body: "merci @thomas" }, me)).toBe(false);
+    expect(isMentioned({ body: "@léa je me cite", author_email: "lea@b.fr" }, me)).toBe(false);
+    expect(isMentioned({ body: "@léa" }, null)).toBe(false);
+  });
+});
+
+describe("live — badge de non-lus", () => {
+  const me = { email: "moi@b.fr", name: "Moi" };
+  const base = { me, historyLoaded: true, chatHidden: true };
+
+  it("compte un message reçu quand le panneau est fermé", () => {
+    expect(shouldNotify({ ...base, msg: { author_email: "autre@b.fr", body: "coucou" } })).toBe(true);
+  });
+
+  // Sans cette garde, l'historique rechargé au join afficherait un badge de dizaines de messages vus.
+  it("ne compte jamais l'historique rejoué", () => {
+    expect(shouldNotify({ ...base, historyLoaded: false, msg: { author_email: "autre@b.fr" } })).toBe(false);
+  });
+
+  it("ne compte ni mes messages, ni les supprimés, ni panneau ouvert", () => {
+    expect(shouldNotify({ ...base, msg: { author_email: "moi@b.fr" } })).toBe(false);
+    expect(shouldNotify({ ...base, msg: { author_email: "autre@b.fr", deleted: true } })).toBe(false);
+    expect(shouldNotify({ ...base, chatHidden: false, msg: { author_email: "autre@b.fr" } })).toBe(false);
+  });
+
+  it("plafonne le libellé à 9+", () => {
+    expect([0, 1, 9, 10, 250].map(unreadLabel)).toEqual(["", "1", "9", "9+", "9+"]);
+  });
+});

package/src/__tests__/presentation-content.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import {
+  sanitizeContent,
+  cycleMapType,
+  mapTypeLabel,
+  initialMapContent,
+  MAP_TYPES,
+  DEFAULT_CENTER,
+  type MapContent,
+} from "../presentation-content";
+
+/** Le retour est une union : ce raccourci évite de répéter l'affinage dans chaque assertion. */
+const asMap = (input: unknown) => sanitizeContent(input) as MapContent | null;
+
+// Ce contrat traverse trois frontières : le navigateur du présentateur le produit, le serveur le
+// valide, le navigateur de chaque spectateur l'applique. Il n'avait AUCUN test alors qu'une
+// divergence s'y traduit par une audience qui ne voit pas ce que montre le présentateur — sans
+// erreur nulle part.
+
+describe("contenu de présentation — retour au document", () => {
+  // `null` = « on présente le document ». C'est le repli sûr : jamais un écran vide.
+  it("tout ce qui n'est pas reconnu ramène au document", () => {
+    for (const input of [null, undefined, "", 0, "map", [], { kind: "pdf" }, {}, { kind: "evil" }, { kind: 42 }]) {
+      expect(sanitizeContent(input), JSON.stringify(input)).toBeNull();
+    }
+  });
+});
+
+describe("contenu de présentation — carte", () => {
+  it("conserve une carte valide", () => {
+    expect(sanitizeContent({ kind: "map", center: [48.85, 2.35], zoom: 14, marker: [48.86, 2.34], mapType: "satellite", label: "Paris" }))
+      .toEqual({ kind: "map", center: [48.85, 2.35], zoom: 14, marker: [48.86, 2.34], mapType: "satellite", label: "Paris" });
+  });
+
+  it("retombe sur la France entière quand le centre est inexploitable", () => {
+    for (const center of [undefined, "48,2", ["a", "b"], [1]]) {
+      expect(asMap({ kind: "map", center })?.center, JSON.stringify(center)).toEqual(DEFAULT_CENTER);
+    }
+  });
+
+  it("borne le zoom entre 1 et 21, et le tronque", () => {
+    expect(asMap({ kind: "map", zoom: 99 })?.zoom).toBe(21);
+    expect(asMap({ kind: "map", zoom: -5 })?.zoom).toBe(1);
+    expect(asMap({ kind: "map", zoom: 12.7 })?.zoom).toBe(12);
+    expect(asMap({ kind: "map", zoom: "14" })?.zoom).toBe(14);
+  });
+
+  it("n'accepte qu'un fond de carte connu", () => {
+    for (const t of MAP_TYPES) expect(asMap({ kind: "map", mapType: t })?.mapType).toBe(t);
+    for (const t of ["terrain", "", null, "<script>"]) expect(asMap({ kind: "map", mapType: t })?.mapType).toBeNull();
+  });
+
+  // Le libellé est saisi par le présentateur et s'affiche chez tous : il est borné ici, échappé à l'affichage.
+  it("borne le libellé à 160 caractères", () => {
+    expect(asMap({ kind: "map", label: "x".repeat(500) })?.label).toHaveLength(160);
+    expect(asMap({ kind: "map", label: "" })?.label).toBeNull();
+  });
+
+  it("ne garde un marqueur que s'il est exploitable", () => {
+    expect(asMap({ kind: "map", marker: [1, 2] })?.marker).toEqual([1, 2]);
+    for (const m of [undefined, null, "1,2", ["a", 2]]) {
+      expect(asMap({ kind: "map", marker: m })?.marker, JSON.stringify(m)).toBeNull();
+    }
+  });
+});
+
+describe("contenu de présentation — Street View", () => {
+  it("conserve une vue valide", () => {
+    expect(sanitizeContent({ kind: "streetview", position: [48.85, 2.35], pov: { heading: 90, pitch: 10 }, zoom: 2 }))
+      .toEqual({ kind: "streetview", position: [48.85, 2.35], pov: { heading: 90, pitch: 10 }, zoom: 2 });
+  });
+
+  // Une vue Street View sans position n'a aucun sens : on ramène au document.
+  it("refuse une vue sans position exploitable", () => {
+    for (const position of [undefined, null, "48,2", [1], ["a", "b"]]) {
+      expect(sanitizeContent({ kind: "streetview", position }), JSON.stringify(position)).toBeNull();
+    }
+  });
+
+  // Au-delà de ±90° l'orientation verticale se retourne : la borne évite une audience la tête à l'envers.
+  it("borne l'inclinaison à ±90° et le zoom à 0–5", () => {
+    expect(sanitizeContent({ kind: "streetview", position: [1, 2], pov: { pitch: 200 } })).toMatchObject({ pov: { pitch: 90 } });
+    expect(sanitizeContent({ kind: "streetview", position: [1, 2], pov: { pitch: -200 } })).toMatchObject({ pov: { pitch: -90 } });
+    expect(sanitizeContent({ kind: "streetview", position: [1, 2], zoom: 50 })?.zoom).toBe(5);
+  });
+
+  it("se passe d'une orientation absente ou biscornue", () => {
+    expect(sanitizeContent({ kind: "streetview", position: [1, 2] })).toMatchObject({ pov: { heading: 0, pitch: 0 } });
+    expect(sanitizeContent({ kind: "streetview", position: [1, 2], pov: "nord" })).toMatchObject({ pov: { heading: 0, pitch: 0 } });
+  });
+});
+
+describe("contenu de présentation — bouton de fond de carte", () => {
+  it("tourne dans l'ordre, et repart de zéro depuis l'inconnu", () => {
+    expect(cycleMapType("roadmap")).toBe("satellite");
+    expect(cycleMapType("satellite")).toBe("hybrid");
+    expect(cycleMapType("hybrid")).toBe("roadmap");
+    expect(cycleMapType(null)).toBe("roadmap");
+    expect(cycleMapType("terrain")).toBe("roadmap");
+  });
+
+  // Le bouton annonce ce vers quoi on va, pas ce qu'on regarde.
+  it("annonce la destination, pas l'état courant", () => {
+    expect(mapTypeLabel("roadmap")).toContain("Satellite");
+    expect(mapTypeLabel("satellite")).toContain("Hybride");
+    expect(mapTypeLabel("hybrid")).toContain("Plan");
+    expect(mapTypeLabel(null)).toContain("Plan");
+  });
+});
+
+describe("contenu de présentation — départ", () => {
+  it("démarre sur la France entière, et survit à son propre aller-retour", () => {
+    const initial = initialMapContent();
+    expect(initial).toMatchObject({ kind: "map", center: DEFAULT_CENTER, zoom: 6, marker: null });
+    expect(sanitizeContent(initial)).toEqual(initial);
+  });
+
+  // Le contenu revient du serveur puis repart : il doit être stable, sinon la carte dériverait
+  // à chaque aller-retour.
+  it("est idempotent", () => {
+    const once = sanitizeContent({ kind: "map", center: [48.85, 2.35], zoom: 14, mapType: "hybrid", label: "Paris" });
+    expect(sanitizeContent(once)).toEqual(once);
+    const sv = sanitizeContent({ kind: "streetview", position: [48.85, 2.35], pov: { heading: 12, pitch: 3 }, zoom: 2 });
+    expect(sanitizeContent(sv)).toEqual(sv);
+  });
+
+  it("ne partage pas son tableau de centre entre deux appels", () => {
+    const a = initialMapContent();
+    a.center[0] = 0;
+    expect(initialMapContent().center).toEqual(DEFAULT_CENTER);
+  });
+});

package/src/__tests__/presentation-state.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { presentationTransition, switchDocUrl } from "../presentation-state";
+
+const genres = (row: unknown, view = {}) =>
+  presentationTransition(row as never, view).map((a) => a.kind);
+
+describe("suivi de l'audience — l'ordre est une règle", () => {
+  // Une présentation terminée l'emporte sur tout : le reste de l'état n'a plus de sens.
+  it("une présentation terminée coupe court", () => {
+    expect(genres({ active: false, current_page: 4, content: { kind: "map" }, file_url: "https://x/y" }))
+      .toEqual(["ended"]);
+  });
+
+  // Le présentateur montre autre chose : l'audience ne doit ni revenir au PDF ni suivre ses pages.
+  it("une carte SUSPEND le suivi du document", () => {
+    expect(genres({ active: true, content: { kind: "map", center: [48.8, 2.3], zoom: 14 }, current_page: 7 }))
+      .toEqual(["show-map"]);
+    expect(genres({ active: true, content: { kind: "streetview", position: [48.8, 2.3] }, current_page: 7 }))
+      .toEqual(["show-map"]);
+  });
+
+  it("revenir au document quitte la carte", () => {
+    expect(genres({ active: true, current_page: 3 })).toEqual(["leave-map", "show-page"]);
+    expect(genres({ active: true, content: null, current_page: 3 })).toEqual(["leave-map", "show-page"]);
+  });
+
+  // La page 3 de l'ancien document n'est pas la page 3 du nouveau.
+  it("un changement de document précède — et remplace — un changement de page", () => {
+    const actions = presentationTransition(
+      { active: true, file_url: "https://x/neuf.pdf", current_page: 9 },
+      { docUrl: "https://x/ancien.pdf" },
+    );
+    expect(actions.map((a) => a.kind)).toEqual(["leave-map", "switch-doc"]);
+    expect(actions[1]).toMatchObject({ kind: "switch-doc", url: "https://x/neuf.pdf" });
+  });
+
+  it("le même document ne déclenche pas de rechargement", () => {
+    expect(genres({ active: true, file_url: "https://x/a.pdf", current_page: 5 }, { docUrl: "https://x/a.pdf" }))
+      .toEqual(["leave-map", "show-page"]);
+  });
+
+  it("ne fait rien d'un état absent ou vide", () => {
+    expect(genres(null)).toEqual(["nothing"]);
+    expect(genres(undefined)).toEqual(["nothing"]);
+    expect(genres({ active: true })).toEqual(["leave-map"]);
+  });
+});
+
+// ⚠️ LE point de sécurité de la bascule vers `broadcast` : sur la voie « table », le contenu venait
+// de notre base, donc déjà assaini. Sur la voie « diffusion », il vient du NAVIGATEUR du
+// présentateur — et rien n'empêche un participant d'émettre sur le canal. Sans re-validation, il
+// imposerait une vue à toute l'audience.
+describe("suivi de l'audience — un état diffusé n'est pas digne de confiance", () => {
+  it("re-valide le contenu reçu, quelle que soit sa provenance", () => {
+    const actions = presentationTransition({ active: true, content: { kind: "map", zoom: 9999, center: ["x", "y"] } });
+    expect(actions[0]).toMatchObject({ kind: "show-map" });
+    expect(actions[0]).toMatchObject({ content: { zoom: 21, center: [46.6, 2.5] } });
+  });
+
+  it("un contenu inconnu ramène au document au lieu d'obéir", () => {
+    for (const hostile of [{ kind: "iframe", src: "https://attaquant" }, { kind: 42 }, "map", []]) {
+      expect(genres({ active: true, content: hostile, current_page: 2 }), JSON.stringify(hostile))
+        .toEqual(["leave-map", "show-page"]);
+    }
+  });
+});
+
+describe("rechargement d'un document changé", () => {
+  // Sans paramètre qui change, pdf.js ressert son cache : l'audience continue de voir l'ANCIEN
+  // document pendant que le présentateur commente le nouveau.
+  it("ajoute un cache-buster, en respectant la requête existante", () => {
+    expect(switchDocUrl("/api/doc?present=abc&file=1", "2026-08-13T10:00:00Z"))
+      .toBe("/api/doc?present=abc&file=1&v=2026-08-13T10%3A00%3A00Z");
+    expect(switchDocUrl("/fichier.pdf", "2026-08-13T10:00:00Z")).toBe("/fichier.pdf?v=2026-08-13T10%3A00%3A00Z");
+  });
+
+  it("reste distinct même sans horodatage", () => {
+    const a = switchDocUrl("/x?file=1");
+    expect(a).toMatch(/&v=\d+$/);
+  });
+});

package/src/__tests__/tracking.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect } from "vitest";
+import { createTracker, type TrackerOptions } from "../tracking";
+
+// Environnement navigateur minimal et PILOTABLE : c'est tout l'intérêt d'avoir sorti ce code des
+// template literals — le temps, la visibilité et le focus deviennent des variables du test.
+function harness(over: Partial<TrackerOptions> = {}) {
+  const sent: Array<Record<string, unknown>> = [];
+  const listeners = new Map<string, Set<() => void>>();
+  const timers: Array<{ fn: () => void; every: number; id: number }> = [];
+  let clock = 1_000_000;
+  let visible = true;
+  let focused = true;
+  let nextTimer = 1;
+
+  const target = {
+    addEventListener: (type: string, h: () => void) => {
+      if (!listeners.has(type)) listeners.set(type, new Set());
+      listeners.get(type)!.add(h);
+    },
+    removeEventListener: (type: string, h: () => void) => { listeners.get(type)?.delete(h); },
+  };
+  const doc = {
+    ...target,
+    get visibilityState() { return visible ? "visible" : "hidden"; },
+    hasFocus: () => focused,
+  } as unknown as Document;
+  const win = {
+    ...target,
+    setInterval: (fn: () => void, every: number) => { const id = nextTimer++; timers.push({ fn, every, id }); return id; },
+    clearInterval: (id: number) => { const i = timers.findIndex((t) => t.id === id); if (i >= 0) timers.splice(i, 1); },
+  } as unknown as Window;
+
+  const tracker = createTracker({
+    doc, win,
+    now: () => clock,
+    send: (p) => sent.push(p),
+    sessionId: "sess-test",
+    ...over,
+  });
+
+  return {
+    tracker, sent, listeners, timers,
+    /** Avance le temps SANS déclencher les minuteries — le temps passe, on ne persiste pas. */
+    advance: (ms: number) => { clock += ms; },
+    fire: (type: string) => listeners.get(type)?.forEach((h) => h()),
+    hide: () => { visible = false; },
+    show: () => { visible = true; },
+    blur: () => { focused = false; },
+    focus: () => { focused = true; },
+    tickTimers: () => timers.slice().forEach((t) => t.fn()),
+    events: () => sent.map((p) => p.event),
+  };
+}
+
+describe("tracking — séparation des deux populations", () => {
+  it("un lien public journalise l'ouverture puis les pages atteintes", () => {
+    const h = harness({ slug: "Ab3-_xYz9012" });
+    h.tracker.start();
+    h.tracker.setPage(2);
+    expect(h.events()).toEqual(["open", "page"]);
+    expect(h.sent[1]).toMatchObject({ slug: "Ab3-_xYz9012", event: "page", page: 2, maxPage: 2 });
+  });
+
+  // Un aperçu interne qui journaliserait un `open` gonflerait l'entonnoir du prospect.
+  it("un aperçu interne n'émet AUCUN open ni page", () => {
+    const h = harness({ internal: { docId: "doc-1", email: "moi@example.fr", name: "Moi" } });
+    h.tracker.start();
+    h.tracker.setPage(2);
+    h.tracker.setPage(3);
+    expect(h.events()).toEqual([]);
+    h.tracker.flush();
+    expect(h.events()).toEqual(["session"]);
+  });
+
+  it("sans slug ni contexte interne, rien n'est envoyé du tout", () => {
+    const h = harness();
+    h.tracker.start();
+    h.tracker.setPage(4);
+    h.tracker.flush();
+    expect(h.sent).toEqual([]);
+  });
+});
+
+describe("tracking — le temps ne compte que si on regarde vraiment", () => {
+  it("compte le temps passé, page par page", () => {
+    const h = harness({ slug: "s" });
+    h.tracker.start();
+    h.advance(4000);
+    h.tracker.setPage(2);
+    h.advance(6000);
+    h.tracker.flush();
+    const session = h.sent.find((p) => p.event === "session")!;
+    expect(session.pagesTime).toEqual({ 1: 4, 2: 6 });
+    expect(session.totalSeconds).toBe(10);
+  });
+
+  it("ne compte pas un onglet caché, et persiste en partant", () => {
+    const h = harness({ slug: "s" });
+    h.tracker.start();
+    h.advance(3000);
+    h.hide();
+    h.fire("visibilitychange");
+    expect(h.events()).toEqual(["open", "session"]); // caché ⇒ on persiste tout de suite
+    h.advance(600_000); // dix minutes dans un onglet oublié
+    h.show();
+    h.fire("visibilitychange");
+    h.advance(2000);
+    h.tracker.flush();
+    const last = h.sent[h.sent.length - 1];
+    expect(last.totalSeconds).toBe(5); // 3 + 2, les dix minutes cachées ne comptent pas
+  });
+
+  it("ne compte pas une fenêtre sans focus", () => {
+    const h = harness({ slug: "s" });
+    h.tracker.start();
+    h.advance(3000);
+    h.blur();
+    h.fire("blur");
+    h.advance(120_000);
+    h.focus();
+    h.fire("focus");
+    h.advance(1000);
+    h.tracker.flush();
+    expect(h.sent[h.sent.length - 1].totalSeconds).toBe(4);
+  });
+
+  it("met en pause après inactivité, et repart à la première interaction", () => {
+    const h = harness({ slug: "s", idleMs: 60_000 });
+    h.tracker.start();
+    h.advance(70_000);
+    h.tickTimers(); // la minuterie d'inactivité constate 70 s > 60 s
+    const afterIdle = h.tracker.totalSeconds();
+    h.advance(300_000);
+    expect(h.tracker.totalSeconds()).toBe(afterIdle); // le chrono est bien arrêté
+    h.tracker.noteActivity();
+    h.advance(5000);
+    expect(h.tracker.totalSeconds()).toBe(afterIdle + 5);
+  });
+});
+
+describe("tracking — progression dans le document", () => {
+  it("ne journalise une page qu'à la première visite (l'entonnoir mesure la progression)", () => {
+    const h = harness({ slug: "s" });
+    h.tracker.start();
+    h.tracker.setPage(2);
+    h.tracker.setPage(3);
+    h.tracker.setPage(2); // retour en arrière
+    h.tracker.setPage(3); // et re-avance
+    expect(h.events()).toEqual(["open", "page", "page"]);
+    expect(h.tracker.maxPage()).toBe(3);
+  });
+
+  it("ignore une page nulle ou identique à la courante", () => {
+    const h = harness({ slug: "s" });
+    h.tracker.start();
+    h.tracker.setPage(0);
+    h.tracker.setPage(2);
+    h.tracker.setPage(2);
+    expect(h.events()).toEqual(["open", "page"]);
+  });
+});
+
+describe("tracking — forme des charges utiles", () => {
+  it("session publique : rattachée au slug", () => {
+    const h = harness({ slug: "Ab3-_xYz9012" });
+    h.tracker.start();
+    h.tracker.setPageCount(12);
+    h.tracker.setPage(5);
+    h.advance(3000);
+    h.tracker.flush();
+    expect(h.sent[h.sent.length - 1]).toMatchObject({
+      event: "session", sessionId: "sess-test", slug: "Ab3-_xYz9012",
+      numPages: 12, maxPage: 5, totalSeconds: 3,
+    });
+    expect(h.sent[h.sent.length - 1].internal).toBeUndefined();
+  });
+
+  it("session interne : rattachée au document et au membre, jamais à un slug", () => {
+    const h = harness({ internal: { docId: "doc-1", email: "moi@example.fr", name: "Moi" } });
+    h.tracker.start();
+    h.tracker.setPageCount(4);
+    h.tracker.flush();
+    const p = h.sent[h.sent.length - 1];
+    expect(p).toMatchObject({ event: "session", internal: true, docId: "doc-1", email: "moi@example.fr", name: "Moi" });
+    expect(p.slug).toBeUndefined();
+  });
+});
+
+describe("tracking — cycle de vie", () => {
+  it("persiste périodiquement, puis plus rien après stop()", () => {
+    const h = harness({ slug: "s", sessionEveryMs: 12_000 });
+    h.tracker.start();
+    h.advance(12_000);
+    h.tickTimers();
+    expect(h.events().filter((e) => e === "session")).toHaveLength(1);
+
+    h.tracker.stop();
+    expect(h.timers).toHaveLength(0);
+    h.fire("beforeunload"); // écouteurs retirés → sans effet
+    expect(h.events().filter((e) => e === "session")).toHaveLength(1);
+  });
+
+  it("start() deux fois ne double pas les écouteurs", () => {
+    const h = harness({ slug: "s" });
+    h.tracker.start();
+    h.tracker.start();
+    expect(h.timers).toHaveLength(2); // inactivité + session, une seule fois
+    expect(h.events()).toEqual(["open"]);
+  });
+
+  // Perdre une mesure est ennuyeux ; perdre l'affichage du document est inacceptable.
+  it("un transport qui échoue n'interrompt pas la lecture", () => {
+    const h = harness({ slug: "s", send: () => { throw new Error("réseau coupé"); } });
+    expect(() => { h.tracker.start(); h.tracker.setPage(2); h.tracker.flush(); }).not.toThrow();
+    expect(h.tracker.maxPage()).toBe(2); // l'état interne reste juste
+  });
+});