From 6f98346a6f33ca15b30b0d2220ae7b55fa151d3d Mon Sep 17 00:00:00 2001
From: juansilvadesign <jaypy.uxdesign@gmail.com>
Date: Thu, 9 Jul 2026 11:03:32 -0300
Subject: [PATCH 1/2] =?UTF-8?q?feat(diagnostico):=20copiar=20diagn=C3=B3st?=
 =?UTF-8?q?ico=20do=20motor=20+=20resumo=20da=20sess=C3=A3o=20no=20popup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Novo engine/telemetry.js (dual-load, como o controller): um log limitado de
amostras (1/s, 2 min — [t, latência, buffer, velocidade aplicada]) e contadores
de sessão por stream (tempo assistido, atraso recuperado pelo catch-up, pulos
para o ao vivo, travadas, latência média ponderada). Tudo vive só na memória
da aba; nada é persistido nem enviado.

O popup ganha duas ações no painel avançado: "Diagnóstico" copia um JSON com
as amostras, caps do player, estado do controlador, modo e configurações —
pronto para issues (o template de bug agora traz o bloco) — e "Resumo da
sessão" copia um texto curto e compartilhável. A ponte popup→content→página
segue o padrão do video-meta: só responde o frame que tem live de verdade;
sem live, o timeout do popup vira o aviso "abra uma live".

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AiLQznJ15KbuK73b9YxAjS
---
 .github/ISSUE_TEMPLATE/bug_report.md |  11 +++
 CHANGELOG.md                         |  14 ++++
 README.md                            |   3 +
 README.pt-BR.md                      |   3 +
 _locales/en/messages.json            |  33 ++++++++
 _locales/es/messages.json            |  33 ++++++++
 _locales/fr/messages.json            |  33 ++++++++
 _locales/pt_BR/messages.json         |  33 ++++++++
 common.js                            |  13 ++++
 content.js                           |  27 ++++++-
 engine/telemetry.js                  | 101 ++++++++++++++++++++++++
 eslint.config.mjs                    |   9 ++-
 inject.js                            |  52 +++++++++++++
 manifest.firefox.json                |   2 +-
 manifest.json                        |   2 +-
 popup.css                            |  39 ++++++++++
 popup.html                           |   3 +
 popup.js                             | 110 +++++++++++++++++++++++++++
 scripts/build-firefox.cjs            |   1 +
 scripts/build.mjs                    |   1 +
 test/telemetry.test.mjs              |  87 +++++++++++++++++++++
 21 files changed, 603 insertions(+), 7 deletions(-)
 create mode 100644 engine/telemetry.js
 create mode 100644 test/telemetry.test.mjs

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index efa2986..4526746 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -37,6 +37,17 @@ assignees: ''
 <!-- URL da transmissão ao vivo onde o problema ocorre, se puder compartilhar.
      Ajuda muito reproduzir o cenário exato. -->
 
+## Diagnóstico da extensão
+
+<!-- Com a live aberta, abra o popup do ZeroDelay > Indicadores no player >
+     "Diagnóstico" > Copiar, e cole o JSON aqui dentro do bloco abaixo.
+     Ele traz os últimos ~2 minutos do motor (latência, buffer, velocidade)
+     e as capacidades do player — nada além do que você vê no JSON. -->
+
+```json
+
+```
+
 ## Capturas de tela / console
 
 <!-- Se possível, anexe prints. Para erros de JavaScript, abra o DevTools
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f84d32f..d51c9f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,20 @@ Todas as mudanças relevantes deste projeto são documentadas neste arquivo.
 O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/)
 e o projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
 
+## [Não lançado]
+
+### Adicionado
+
+- **"Copiar diagnóstico"** no painel avançado do popup: copia um JSON com os
+  últimos ~2 minutos do motor (latência, buffer e velocidade aplicada, 1
+  amostra/s), as capacidades detectadas do player, o estado do controlador, o
+  modo e as configurações — pronto para colar num relatório de bug (o template
+  de issue já traz o espaço). 100% local: nada é coletado nem enviado; o dado
+  só existe na memória da aba e só sai do navegador se você mesmo colar.
+- **"Resumo da sessão"** ao lado do diagnóstico: copia um texto curto e
+  compartilhável com o tempo assistido, o atraso recuperado pelo catch-up, os
+  pulos para o ao vivo, as travadas e a latência média da live atual.
+
 ## [1.4.0] - 2026-07-07
 
 ### Adicionado
diff --git a/README.md b/README.md
index 2f90580..5fa3943 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,9 @@ YouTube player UI.
 - Keyboard shortcuts to toggle on/off (`Alt+Shift+Y`) and jump to live
   (`Alt+Shift+L`) — `⌘+Shift+…` on Mac — remappable at
   `chrome://extensions/shortcuts`
+- One-tap **Copy diagnostics** (the engine's last ~2 minutes, ready to paste
+  into a bug report) and a shareable **session summary** — both 100% local,
+  copied only when you ask
 
 ## Settings
 
diff --git a/README.pt-BR.md b/README.pt-BR.md
index ee7ed51..49f2081 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -39,6 +39,9 @@ YouTube.
 - Atalhos de teclado para ligar/desligar (`Alt+Shift+Y`) e pular para o ao vivo
   (`Alt+Shift+L`) — `⌘+Shift+…` no Mac —, reconfiguráveis em
   `chrome://extensions/shortcuts`
+- **Copiar diagnóstico** em um toque (os últimos ~2 minutos do motor, pronto
+  para colar num relatório de bug) e um **resumo da sessão** compartilhável —
+  ambos 100% locais, copiados só quando você pede
 
 ## Configurações
 
diff --git a/_locales/en/messages.json b/_locales/en/messages.json
index e83d4ec..81f11e0 100644
--- a/_locales/en/messages.json
+++ b/_locales/en/messages.json
@@ -245,6 +245,39 @@
    "faqShortcutsA": {
       "message": "Two shortcuts (on Mac, swap Alt for ⌘ Command):\n• Alt+Shift+Y — turn ZeroDelay on/off\n• Alt+Shift+L — jump to live\nYou can view and change them at chrome://extensions/shortcuts."
    },
+   "diagLabel": {
+      "message": "Diagnostics (for bug reports)"
+   },
+   "summaryLabel": {
+      "message": "Session summary"
+   },
+   "toolCopy": {
+      "message": "Copy"
+   },
+   "toolCopied": {
+      "message": "Copied!"
+   },
+   "toolNoLive": {
+      "message": "Open a live stream"
+   },
+   "summaryTitle": {
+      "message": "session summary"
+   },
+   "summaryWatched": {
+      "message": "watched"
+   },
+   "summaryRecovered": {
+      "message": "delay recovered"
+   },
+   "summaryJumps": {
+      "message": "jumps to live"
+   },
+   "summaryStalls": {
+      "message": "stalls"
+   },
+   "summaryAvgLatency": {
+      "message": "average latency"
+   },
    "aboutLink": {
       "message": "About ZeroDelay"
    },
diff --git a/_locales/es/messages.json b/_locales/es/messages.json
index 6c06b5e..1a71620 100644
--- a/_locales/es/messages.json
+++ b/_locales/es/messages.json
@@ -245,6 +245,39 @@
    "faqShortcutsA": {
       "message": "Dos atajos (en Mac, cambia Alt por ⌘ Command):\n• Alt+Shift+Y — activar/desactivar ZeroDelay\n• Alt+Shift+L — saltar al directo\nPuedes verlos y cambiarlos en chrome://extensions/shortcuts."
    },
+   "diagLabel": {
+      "message": "Diagnóstico (para reportar problemas)"
+   },
+   "summaryLabel": {
+      "message": "Resumen de la sesión"
+   },
+   "toolCopy": {
+      "message": "Copiar"
+   },
+   "toolCopied": {
+      "message": "¡Copiado!"
+   },
+   "toolNoLive": {
+      "message": "Abre un directo"
+   },
+   "summaryTitle": {
+      "message": "resumen de la sesión"
+   },
+   "summaryWatched": {
+      "message": "visto"
+   },
+   "summaryRecovered": {
+      "message": "retraso recuperado"
+   },
+   "summaryJumps": {
+      "message": "saltos al directo"
+   },
+   "summaryStalls": {
+      "message": "cortes"
+   },
+   "summaryAvgLatency": {
+      "message": "latencia media"
+   },
    "aboutLink": {
       "message": "Acerca de ZeroDelay"
    },
diff --git a/_locales/fr/messages.json b/_locales/fr/messages.json
index 20bd05f..3750361 100644
--- a/_locales/fr/messages.json
+++ b/_locales/fr/messages.json
@@ -245,6 +245,39 @@
    "faqShortcutsA": {
       "message": "Deux raccourcis (sur Mac, remplacez Alt par ⌘ Command) :\n• Alt+Shift+Y — activer/désactiver ZeroDelay\n• Alt+Shift+L — aller au direct\nVous pouvez les voir et les modifier dans chrome://extensions/shortcuts."
    },
+   "diagLabel": {
+      "message": "Diagnostic (pour signaler un problème)"
+   },
+   "summaryLabel": {
+      "message": "Résumé de la session"
+   },
+   "toolCopy": {
+      "message": "Copier"
+   },
+   "toolCopied": {
+      "message": "Copié !"
+   },
+   "toolNoLive": {
+      "message": "Ouvrez un direct"
+   },
+   "summaryTitle": {
+      "message": "résumé de la session"
+   },
+   "summaryWatched": {
+      "message": "visionné"
+   },
+   "summaryRecovered": {
+      "message": "retard rattrapé"
+   },
+   "summaryJumps": {
+      "message": "sauts vers le direct"
+   },
+   "summaryStalls": {
+      "message": "blocages"
+   },
+   "summaryAvgLatency": {
+      "message": "latence moyenne"
+   },
    "aboutLink": {
       "message": "À propos"
    },
diff --git a/_locales/pt_BR/messages.json b/_locales/pt_BR/messages.json
index 4c91e43..2ec6621 100644
--- a/_locales/pt_BR/messages.json
+++ b/_locales/pt_BR/messages.json
@@ -245,6 +245,39 @@
    "faqShortcutsA": {
       "message": "São dois atalhos (no Mac, troque Alt por ⌘ Command):\n• Alt+Shift+Y — ativar/desativar o ZeroDelay\n• Alt+Shift+L — pular para o ao vivo\nVocê pode vê-los e mudá-los em chrome://extensions/shortcuts."
    },
+   "diagLabel": {
+      "message": "Diagnóstico (para relatar problemas)"
+   },
+   "summaryLabel": {
+      "message": "Resumo da sessão"
+   },
+   "toolCopy": {
+      "message": "Copiar"
+   },
+   "toolCopied": {
+      "message": "Copiado!"
+   },
+   "toolNoLive": {
+      "message": "Abra uma live"
+   },
+   "summaryTitle": {
+      "message": "resumo da sessão"
+   },
+   "summaryWatched": {
+      "message": "assistido"
+   },
+   "summaryRecovered": {
+      "message": "atraso recuperado"
+   },
+   "summaryJumps": {
+      "message": "pulos para o ao vivo"
+   },
+   "summaryStalls": {
+      "message": "travadas"
+   },
+   "summaryAvgLatency": {
+      "message": "latência média"
+   },
    "aboutLink": {
       "message": "Sobre o ZeroDelay"
    },
diff --git a/common.js b/common.js
index e176ebc..5422122 100644
--- a/common.js
+++ b/common.js
@@ -153,6 +153,19 @@ export const label = {
     faqShortcutsQ: msg('faqShortcutsQ', 'Existem atalhos de teclado?'),
     faqShortcutsA: msg('faqShortcutsA', 'São dois atalhos (no Mac, troque Alt por ⌘ Command):\n• Alt+Shift+Y — ativar/desativar o ZeroDelay\n• Alt+Shift+L — pular para o ao vivo\nVocê pode vê-los e mudá-los em chrome://extensions/shortcuts.'),
 
+    // Diagnostics + session summary (the two copy tools in the advanced panel).
+    diagLabel: msg('diagLabel', 'Diagnóstico (para relatar problemas)'),
+    summaryLabel: msg('summaryLabel', 'Resumo da sessão'),
+    toolCopy: msg('toolCopy', 'Copiar'),
+    toolCopied: msg('toolCopied', 'Copiado!'),
+    toolNoLive: msg('toolNoLive', 'Abra uma live'),
+    summaryTitle: msg('summaryTitle', 'resumo da sessão'),
+    summaryWatched: msg('summaryWatched', 'assistido'),
+    summaryRecovered: msg('summaryRecovered', 'atraso recuperado'),
+    summaryJumps: msg('summaryJumps', 'pulos para o ao vivo'),
+    summaryStalls: msg('summaryStalls', 'travadas'),
+    summaryAvgLatency: msg('summaryAvgLatency', 'latência média'),
+
     // Footer links — project page + issue tracker on GitHub.
     aboutLink: msg('aboutLink', 'Sobre o ZeroDelay'),
     reportIssue: msg('reportIssue', 'Relatar um problema'),
diff --git a/content.js b/content.js
index 8b4d5b0..8347eed 100644
--- a/content.js
+++ b/content.js
@@ -70,8 +70,32 @@ function main(common) {
 
     // Active-tab-only path: background.js sends this directly to the tab the
     // "go-live" shortcut was pressed on (PR #16).
-    function onRuntimeMessage(msg) {
+    function onRuntimeMessage(msg, _sender, sendResponse) {
         if (msg?.type === 'go-live') dispatchGoLive();
+        else if (msg?.type === 'zd-diagnostics') return relayDiagnostics(sendResponse);
+    }
+
+    // Popup → engine diagnostics relay. Every frame gets the request; only a
+    // frame whose engine has live samples answers (see inject.js), so the first
+    // response IS the live one. When no frame answers, the port simply closes
+    // unanswered and the popup's own timeout reads it as "no live here".
+    function relayDiagnostics(sendResponse) {
+        let settled = false;
+        const finish = payload => {
+            if (settled) return;
+            settled = true;
+            document.removeEventListener('_zd_diag_response', onResponse);
+            try { sendResponse(payload); } catch { /* popup closed while we waited */ }
+        };
+        const onResponse = e => { if (e.detail?.ok) finish(e.detail); };
+        document.addEventListener('_zd_diag_response', onResponse);
+        document.dispatchEvent(new CustomEvent('_zd_diag_request'));
+        setTimeout(() => {
+            if (settled) return;
+            settled = true;   // stop listening; deliberately never responds
+            document.removeEventListener('_zd_diag_response', onResponse);
+        }, 800);
+        return true;   // keep the message channel open for the async response
     }
 
     // Guard against double-registration if the content script re-inits in the
@@ -127,6 +151,7 @@ function main(common) {
         return s;
     };
     injectScript('engine/controller.js');
+    injectScript('engine/telemetry.js');
     injectScript('inject.js').id = '_live_catch_up';
 }
 
diff --git a/engine/telemetry.js b/engine/telemetry.js
new file mode 100644
index 0000000..8e954a0
--- /dev/null
+++ b/engine/telemetry.js
@@ -0,0 +1,101 @@
+// ZeroDelay — keep YouTube live streams in real time
+// Author: João Gustavo França <joao@solitus.com.br> (https://github.com/joaogfc)
+//
+// Local telemetry behind "Copy diagnostics" and the session summary: a bounded
+// sample log of the engine's recent behavior plus per-stream session counters.
+// Everything lives in the page's memory and dies with the tab — nothing is
+// persisted or sent anywhere; the only way any of it leaves the browser is the
+// viewer explicitly copying it from the popup.
+//
+// Dual-loaded on purpose, exactly like engine/controller.js:
+//   • Browser: classic script injected before inject.js, exposing
+//     `window.ZeroDelay.createSampleLog` / `createSessionStats`.
+//   • Node/tests: the sibling engine/package.json ({"type":"commonjs"}) makes
+//     `module.exports` work (see test/telemetry.test.mjs).
+'use strict';
+(function () {
+    // Round to `p` decimals (null for non-finite) — keeps the copied JSON
+    // compact and byte-stable so two reports of the same stream diff cleanly.
+    function round(v, p = 2) {
+        if (!isFinite(v)) return null;
+        const f = Math.pow(10, p);
+        return Math.round(v * f) / f;
+    }
+
+    // Fixed-capacity sample log: one sample per second, two minutes deep by
+    // default. Samples are compact arrays — [tSec, latency, buffer, rate] —
+    // not objects, so 120 of them paste comfortably into a GitHub issue while
+    // still showing exactly how a catch-up or a stall developed.
+    function createSampleLog(capacity = 120, minIntervalMs = 1000) {
+        const samples = [];
+        let started = null;   // first sample's timestamp = t0 of the log
+        let last_at = 0;
+
+        // Called from the engine's hot loop every tick; only actually records
+        // once per `minIntervalMs`. Returns whether the sample was taken.
+        function add(nowMs, latency, buffer, rate) {
+            if (nowMs - last_at < minIntervalMs) return false;
+            last_at = nowMs;
+            if (started === null) started = nowMs;
+            samples.push([round((nowMs - started) / 1000, 0), round(latency), round(buffer), round(rate)]);
+            if (samples.length > capacity) samples.splice(0, samples.length - capacity);
+            return true;
+        }
+
+        return { add, list: () => samples.slice(), size: () => samples.length };
+    }
+
+    // Per-stream session counters (a fresh one is created per attach, like the
+    // controller, so numbers never mix two lives). `recovered` integrates
+    // (rate − 1)·dt — the seconds of live delay the catch-up actually ate —
+    // and `rebuilt` its sub-1.0x mirror (the band mode / conservative brake).
+    function createSessionStats(nowMs = Date.now()) {
+        const started_at = nowMs;
+        let watch = 0;          // seconds of live actually watched
+        let recovered = 0;      // seconds of delay removed by rate > 1.0
+        let rebuilt = 0;        // seconds given back by rate < 1.0 (cushion rebuilds)
+        let latency_sum = 0;    // time-weighted, for the average
+        let jumps = 0;          // seekToLiveHead calls (skip + manual)
+        let stalls = 0;         // real live 'waiting' events (as the watchdog counts them)
+        let last = null;        // previous tick's timestamp
+
+        // dt is capped at 2s: a background-throttled tab or a suspended laptop
+        // must not book watch-minutes that never played.
+        function onTick(nowMs2, rate, latency) {
+            const dt = last === null ? 0 : Math.min(Math.max((nowMs2 - last) / 1000, 0), 2);
+            last = nowMs2;
+            if (!isFinite(latency)) return;   // not live stats — don't count
+            watch += dt;
+            latency_sum += latency * dt;
+            if (isFinite(rate)) {
+                if (rate > 1.001) recovered += (rate - 1.0) * dt;
+                else if (rate < 0.999) rebuilt += (1.0 - rate) * dt;
+            }
+        }
+
+        function onJump() { jumps++; }
+        function onStall() { stalls++; }
+
+        function snapshot() {
+            return {
+                startedAt: started_at,
+                watchSec: round(watch, 0),
+                recoveredSec: round(recovered, 1),
+                rebuiltSec: round(rebuilt, 1),
+                jumps,
+                stalls,
+                latencyAvg: watch > 0 ? round(latency_sum / watch, 1) : null,
+            };
+        }
+
+        return { onTick, onJump, onStall, snapshot };
+    }
+
+    const api = { createSampleLog, createSessionStats };
+    if (typeof module !== 'undefined' && module.exports) module.exports = api;
+    if (typeof window !== 'undefined') {
+        const zd = (window.ZeroDelay = window.ZeroDelay || {});
+        zd.createSampleLog = createSampleLog;
+        zd.createSessionStats = createSessionStats;
+    }
+}());
diff --git a/eslint.config.mjs b/eslint.config.mjs
index dcfb746..4da5d25 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -19,11 +19,12 @@ export default [
         },
     },
 
-    // Classic scripts in the page (MAIN) world — not ES modules. controller.js
-    // is ALSO loaded as CommonJS in Node/tests, so it legitimately touches
-    // `module`/`exports`; those globals are harmless for inject.js, which ignores them.
+    // Classic scripts in the page (MAIN) world — not ES modules. The engine/
+    // modules are ALSO loaded as CommonJS in Node/tests, so they legitimately
+    // touch `module`/`exports`; those globals are harmless for inject.js,
+    // which ignores them.
     {
-        files: ['inject.js', 'engine/controller.js'],
+        files: ['inject.js', 'engine/*.js'],
         languageOptions: {
             sourceType: 'script',
             globals: { ...globals.browser, ...globals.commonjs, ZeroDelay: 'writable' },
diff --git a/inject.js b/inject.js
index 4732620..edef0d6 100644
--- a/inject.js
+++ b/inject.js
@@ -10,6 +10,11 @@
     const zd = (typeof window !== 'undefined' && window.ZeroDelay) ? window.ZeroDelay : null;
     const classicFactory = (zd && typeof zd.createController === 'function') ? zd.createController : null;
     const bandFactory = (zd && typeof zd.createBandController === 'function') ? zd.createBandController : null;
+    // Local telemetry (engine/telemetry.js, injected alongside the controller):
+    // powers "Copy diagnostics" + the session summary. Optional — a load failure
+    // only disables those two popup buttons, never the engine itself.
+    const sampleLogFactory = (zd && typeof zd.createSampleLog === 'function') ? zd.createSampleLog : null;
+    const sessionStatsFactory = (zd && typeof zd.createSessionStats === 'function') ? zd.createSessionStats : null;
 
     // Pick the controller for the current settings: the buffer-regulation one
     // ("Personalizado") when `band` is on, otherwise the classic catch-up one. Both
@@ -207,6 +212,7 @@
             if (player.getPlayerStateObject()?.isPlaying) {
                 player.seekToLiveHead();
                 if (caps.playVideo) player.playVideo();
+                if (session_stats) session_stats.onJump();
             }
         }
     }
@@ -216,6 +222,7 @@
         if (!player || !caps?.seekLive) return;
         player.seekToLiveHead();
         if (caps.playVideo) player.playVideo();
+        if (session_stats) session_stats.onJump();
     }
 
     function video_instance() {
@@ -321,6 +328,8 @@
     let current_settings;
     let last_active_ping = 0;
     let last_meta_key = null;     // dedupes _live_catch_up_video_meta dispatches
+    let sample_log = sampleLogFactory ? sampleLogFactory() : null;          // diagnostics ring log
+    let session_stats = sessionStatsFactory ? sessionStatsFactory() : null; // session summary counters
 
     // --- Resilience state (R1/R2/R3) ----------------------------------------
     // The engine drives entirely off UNDOCUMENTED player methods. `caps` records
@@ -356,6 +365,7 @@
         const now = Date.now();
         if (now < stall_cooldown_until || now - last_stall < 5000) return;
         last_stall = now;
+        if (session_stats) session_stats.onStall();
         stall_times = stall_times.filter(t => now - t < 90000);
         stall_times.push(now);
         if (stall_times.length >= 2) {
@@ -448,6 +458,12 @@
                 : reset_playbackRate();
         }
 
+        // Local telemetry: one sample per second of what the engine saw and did
+        // (applied_rate is the player's own echo — what actually played, not
+        // what we asked for). Page-memory only; see engine/telemetry.js.
+        if (sample_log) sample_log.add(active_now, latency, health, applied_rate);
+        if (session_stats) session_stats.onTick(active_now, applied_rate, latency);
+
         // Calm "good moment" for the optional donation motion: stream stable (resting
         // at ~1.0x with a healthy buffer), held a few seconds, re-announced at most
         // every 20s. content.js gates it to an eligible viewer, once per session.
@@ -579,6 +595,37 @@
         }));
     }
 
+    // --- Diagnostics bridge ("Copy diagnostics" in the popup) ----------------
+    // Request/response over CustomEvents, like the video-meta bridge above. The
+    // engine only answers when it actually has live samples to report: a VOD or
+    // idle frame stays silent, so the popup's timeout can say "open a live"
+    // instead of copying an empty shell (and, with several frames listening,
+    // the first response is by construction the one with the live). The payload
+    // is engine-side truth only — the popup adds version/settings/mode from its
+    // own world. Nothing here is persisted or sent anywhere; the viewer sees
+    // the JSON on their clipboard and decides where it goes.
+    document.addEventListener('_zd_diag_request', () => {
+        const samples = sample_log ? sample_log.list() : [];
+        if (!player || samples.length === 0) return;
+        let vd = null;
+        if (caps?.videoData) {
+            try { vd = player.getVideoData(); } catch { vd = null; }
+        }
+        document.dispatchEvent(new CustomEvent('_zd_diag_response', {
+            detail: {
+                ok: true,
+                degraded: engine_degraded,
+                caps,
+                video: vd ? { id: vd.video_id || '', channel: vd.channel_id || '', isLive: vd.isLive === true } : null,
+                appliedRate: applied_rate,
+                yieldedToUser: yielded_to_user,
+                controller: (controller && typeof controller.getState === 'function') ? controller.getState() : null,
+                session: session_stats ? session_stats.snapshot() : null,
+                samples,
+            },
+        }));
+    });
+
     // --- Player detection + (re)attach (R2) ---------------------------------
     // Runs on first load AND on every SPA navigation (YouTube reuses the tab and
     // may rebuild the player bar). Idempotent: video listeners bind once per
@@ -627,6 +674,11 @@
         controller_center = current_settings ? current_settings.centerBuffer : null;
         seekableEnds = [];
 
+        // Fresh stream, fresh telemetry: the sample log and the session counters
+        // describe THIS live only (mirrors the controller reset above).
+        sample_log = sampleLogFactory ? sampleLogFactory() : null;
+        session_stats = sessionStatsFactory ? sessionStatsFactory() : null;
+
         // The stall watchdog counts buffering events for THIS stream (a mode too
         // aggressive for this connection). Reset the count on a fresh stream, or a
         // stall on the previous live would combine with one here into a spurious
diff --git a/manifest.firefox.json b/manifest.firefox.json
index 48053d7..0237d5d 100644
--- a/manifest.firefox.json
+++ b/manifest.firefox.json
@@ -58,6 +58,6 @@
    "version": "1.4.0",
    "web_accessible_resources": [ {
       "matches": [ "https://www.youtube.com/*" ],
-      "resources": [ "common.js", "inject.js", "engine/controller.js", "overlay.js", "pix.js", "vendor/qrcode.js", "fonts/DepartureMono-Regular.woff2" ]
+      "resources": [ "common.js", "inject.js", "engine/controller.js", "engine/telemetry.js", "overlay.js", "pix.js", "vendor/qrcode.js", "fonts/DepartureMono-Regular.woff2" ]
    } ]
 }
diff --git a/manifest.json b/manifest.json
index 74e9ce3..73a536f 100644
--- a/manifest.json
+++ b/manifest.json
@@ -48,6 +48,6 @@
    "version": "1.4.0",
    "web_accessible_resources": [ {
       "matches": [ "https://www.youtube.com/*" ],
-      "resources": [ "common.js", "inject.js", "engine/controller.js", "overlay.js", "pix.js", "vendor/qrcode.js", "fonts/DepartureMono-Regular.woff2" ]
+      "resources": [ "common.js", "inject.js", "engine/controller.js", "engine/telemetry.js", "overlay.js", "pix.js", "vendor/qrcode.js", "fonts/DepartureMono-Regular.woff2" ]
    } ]
 }
diff --git a/popup.css b/popup.css
index c10520e..c5f77ca 100644
--- a/popup.css
+++ b/popup.css
@@ -1045,6 +1045,45 @@ html {
     box-shadow: 0 0 0 3px var(--sync-soft), 0 0 8px -2px var(--sync-glow);
 }
 
+/* ----------------------------------------- Diagnostics / session-copy tools */
+/* Compact copy buttons at the end of the advanced panel (label left, action
+ * right, like the indicator rows). Neutral until they speak: green flash on a
+ * successful copy, amber when there is no live to read from. Mono, like every
+ * other number-adjacent affordance. */
+.tool-copy {
+    flex: none;
+    min-width: 88px;
+    padding: 6px 12px;
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+    background: var(--surface-2);
+    color: var(--text-dim);
+    font-family: var(--font-mono);
+    font-size: 11px;
+    cursor: pointer;
+    transition: color 150ms var(--ease), border-color 150ms var(--ease), background 150ms var(--ease);
+}
+
+.tool-copy:hover {
+    color: var(--text);
+    border-color: var(--text-faint);
+}
+
+.tool-copy:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--sync-soft);
+}
+
+.tool-copy.is-done {
+    color: var(--ok);
+    border-color: var(--ok);
+}
+
+.tool-copy.is-fail {
+    color: var(--warn);
+    border-color: var(--warn);
+}
+
 /* ---------------------------------------------------------------- Footer */
 .app-footer {
     display: flex;
diff --git a/popup.html b/popup.html
index 7d35471..622d227 100644
--- a/popup.html
+++ b/popup.html
@@ -108,6 +108,9 @@ <h2 id="modes-title" class="section-title"></h2>
                 <div class="group">
                     <div id="indicator-rows" class="rows"></div>
                 </div>
+                <div class="group">
+                    <div id="tools-rows" class="rows"></div>
+                </div>
             </div>
         </section>
 
diff --git a/popup.js b/popup.js
index 098c4e5..8df42fa 100644
--- a/popup.js
+++ b/popup.js
@@ -59,6 +59,37 @@ function sanitizeSvg(node) {
 
 const getStorage = keys => new Promise(res => chrome.storage.local.get(keys, res));
 
+// Copy plain text to the clipboard; execCommand is the fallback when the
+// async Clipboard API is unavailable or denied (same recipe as the PIX button).
+async function copyText(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+        return true;
+    } catch {
+        try {
+            const ta = document.createElement('textarea');
+            ta.value = text;
+            ta.style.position = 'fixed';
+            ta.style.opacity = '0';
+            document.body.append(ta);
+            ta.select();
+            const ok = document.execCommand('copy');
+            ta.remove();
+            return ok;
+        } catch { return false; }
+    }
+}
+
+// "45s" / "12m30s" / "1h04m" — durations in the session summary.
+function fmtDuration(sec) {
+    if (!Number.isFinite(sec) || sec < 0) return '—';
+    const s = Math.round(sec);
+    if (s < 60) return s + 's';
+    const m = Math.floor(s / 60), r = s % 60;
+    if (m < 60) return r ? `${m}m${String(r).padStart(2, '0')}s` : `${m}m`;
+    return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`;
+}
+
 /**
  * Wire ARIA radiogroup keyboard behavior: one tab-stop for the group (roving
  * tabindex) plus arrow/Home/End navigation that also activates the option.
@@ -290,6 +321,84 @@ function renderIndicators() {
     }
 }
 
+// ------------------------------------------------ Diagnostics / session copy
+// Ask the active tab's engine for its diagnostics payload. content.js relays
+// the request into the page; inject.js only answers from a frame actually
+// tracking a live, so a silent tab (VOD, no YouTube, no live yet) resolves
+// null through the timeout and the button says "open a live" instead.
+function requestDiagnostics() {
+    const viaTab = new Promise(resolve => {
+        chrome.tabs.query({ active: true, currentWindow: true }, tabs => {
+            const tabId = tabs?.[0]?.id;
+            if (tabId == null) { resolve(null); return; }
+            try {
+                chrome.tabs.sendMessage(tabId, { type: 'zd-diagnostics' }, resp => {
+                    void chrome.runtime.lastError;   // no receiver = not a YouTube tab
+                    resolve(resp || null);
+                });
+            } catch { resolve(null); }
+        });
+    });
+    const timeout = new Promise(resolve => setTimeout(() => resolve(null), 1200));
+    return Promise.race([viaTab, timeout]);
+}
+
+function renderTools() {
+    const rows = $('#tools-rows');
+
+    const wireCopy = (labelText, build) => {
+        const btn = el('button', { class: 'tool-copy', type: 'button', text: L.toolCopy });
+        let revert;
+        const flash = (cls, text) => {
+            clearTimeout(revert);
+            btn.classList.remove('is-done', 'is-fail');
+            btn.classList.add(cls);
+            btn.textContent = text;
+            revert = setTimeout(() => {
+                btn.classList.remove('is-done', 'is-fail');
+                btn.textContent = L.toolCopy;
+            }, 1800);
+        };
+        btn.addEventListener('click', async () => {
+            const payload = await requestDiagnostics();
+            const text = payload ? build(payload) : null;
+            if (text && await copyText(text)) flash('is-done', L.toolCopied);
+            else flash('is-fail', L.toolNoLive);
+        });
+        rows.append(buildRow({ label: labelText, control: btn }));
+    };
+
+    // Full diagnostics: the engine's own truth (caps, controller state, the
+    // last two minutes of samples) plus what only this world knows — version,
+    // browser, resolved settings/mode. JSON, ready to paste into an issue.
+    wireCopy(L.diagLabel, payload => {
+        const report = {
+            zerodelay: chrome.runtime.getManifest().version,
+            browser: navigator.userAgent,
+            lang: chrome.i18n.getUILanguage(),
+            mode: common.deriveMode(state),
+            settings: Object.fromEntries(common.storage.map(k => [k, state[k]])),
+            ...payload,
+        };
+        delete report.ok;   // transport flag, not diagnostics
+        return JSON.stringify(report, null, 2);
+    });
+
+    // Session summary: a short, human, shareable text.
+    wireCopy(L.summaryLabel, payload => {
+        const s = payload.session;
+        if (!s) return null;
+        return [
+            `ZeroDelay — ${L.summaryTitle}`,
+            `${L.summaryWatched}: ${fmtDuration(s.watchSec)}`,
+            `${L.summaryRecovered}: ${fmtDuration(s.recoveredSec)}`,
+            `${L.summaryJumps}: ${s.jumps} · ${L.summaryStalls}: ${s.stalls}`,
+            s.latencyAvg != null ? `${L.summaryAvgLatency}: ${s.latencyAvg}s` : null,
+            'github.com/joaogfc/ZeroDelay',
+        ].filter(Boolean).join('\n');
+    });
+}
+
 function renderAdvancedToggle() {
     const toggle = $('#advanced-toggle');
     const panel = $('#advanced-panel');
@@ -696,6 +805,7 @@ function updateChannelHint() {
     renderChannelMemory();
     renderBandControl();
     renderIndicators();
+    renderTools();
     renderAdvancedToggle();
     renderFaq();
     renderReset();
diff --git a/scripts/build-firefox.cjs b/scripts/build-firefox.cjs
index 4df8f59..f4c769f 100644
--- a/scripts/build-firefox.cjs
+++ b/scripts/build-firefox.cjs
@@ -19,6 +19,7 @@ const files = [
     'inject.js',
     'overlay.js',
     'engine/controller.js',
+    'engine/telemetry.js',
     'pix.js',
     'popup.js',
     'popup.css',
diff --git a/scripts/build.mjs b/scripts/build.mjs
index b9e4d5a..1ce0d50 100644
--- a/scripts/build.mjs
+++ b/scripts/build.mjs
@@ -20,6 +20,7 @@ const SHIP_FILES = [
     'inject.js',
     'overlay.js',
     'engine/controller.js',
+    'engine/telemetry.js',
     'pix.js',
     'popup.js',
     'popup.css',
diff --git a/test/telemetry.test.mjs b/test/telemetry.test.mjs
new file mode 100644
index 0000000..de505e6
--- /dev/null
+++ b/test/telemetry.test.mjs
@@ -0,0 +1,87 @@
+// Tests for the local-telemetry primitives behind "Copy diagnostics" and the
+// session summary (engine/telemetry.js — loaded here through its CommonJS
+// face, exactly like the controller tests do).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { createSampleLog, createSessionStats } = require('../engine/telemetry.js');
+
+test('sample log records at most one sample per interval', () => {
+    const log = createSampleLog(120, 1000);
+    assert.equal(log.add(1000, 3.0, 5.0, 1.0), true);
+    assert.equal(log.add(1400, 3.1, 5.1, 1.0), false);  // 400ms later — skipped
+    assert.equal(log.add(2000, 3.2, 5.2, 1.25), true);
+    assert.equal(log.size(), 2);
+});
+
+test('sample log samples are compact [t, latency, buffer, rate] arrays with t relative to the first', () => {
+    const log = createSampleLog(120, 1000);
+    log.add(5000, 3.456, 5.123, 1.0);
+    log.add(6000, 2.987, 4.5, 1.25);
+    assert.deepEqual(log.list(), [
+        [0, 3.46, 5.12, 1],
+        [1, 2.99, 4.5, 1.25],
+    ]);
+});
+
+test('sample log trims to capacity, dropping the oldest', () => {
+    const log = createSampleLog(3, 1000);
+    for (let i = 0; i < 5; i++) log.add((i + 1) * 1000, i, i, 1.0);
+    const t = log.list().map(s => s[0]);
+    assert.deepEqual(t, [2, 3, 4]);   // first two (t=0, t=1) dropped
+});
+
+test('sample log stores null for non-finite readings instead of NaN', () => {
+    const log = createSampleLog(120, 1000);
+    log.add(1000, NaN, Infinity, 1.0);
+    assert.deepEqual(log.list()[0], [0, null, null, 1]);
+});
+
+test('session stats integrate recovered/rebuilt seconds from the rate', () => {
+    const s = createSessionStats(0);
+    s.onTick(0, 1.0, 5.0);          // first tick establishes the clock (dt=0)
+    s.onTick(1000, 1.25, 5.0);      // 1s at 1.25x -> 0.25s recovered
+    s.onTick(2000, 1.25, 5.0);      // +0.25s
+    s.onTick(3000, 0.9, 5.0);       // 1s at 0.90x -> 0.1s rebuilt
+    const snap = s.snapshot();
+    assert.equal(snap.recoveredSec, 0.5);
+    assert.equal(snap.rebuiltSec, 0.1);
+    assert.equal(snap.watchSec, 3);
+});
+
+test('session stats compute a time-weighted average latency', () => {
+    const s = createSessionStats(0);
+    s.onTick(0, 1.0, 4.0);
+    s.onTick(1000, 1.0, 4.0);      // 1s at 4.0
+    s.onTick(2000, 1.0, 2.0);      // 1s at 2.0
+    assert.equal(s.snapshot().latencyAvg, 3.0);
+});
+
+test('session stats cap dt so a throttled/suspended tab cannot book unplayed time', () => {
+    const s = createSessionStats(0);
+    s.onTick(0, 1.0, 3.0);
+    s.onTick(60000, 1.0, 3.0);      // a minute gap counts as at most 2s
+    assert.equal(s.snapshot().watchSec, 2);
+});
+
+test('session stats ignore ticks without live latency', () => {
+    const s = createSessionStats(0);
+    s.onTick(0, 1.0, NaN);
+    s.onTick(1000, 1.25, NaN);      // no live stats — nothing counts
+    const snap = s.snapshot();
+    assert.equal(snap.watchSec, 0);
+    assert.equal(snap.recoveredSec, 0);
+    assert.equal(snap.latencyAvg, null);
+});
+
+test('session stats count jumps and stalls', () => {
+    const s = createSessionStats(0);
+    s.onJump();
+    s.onJump();
+    s.onStall();
+    const snap = s.snapshot();
+    assert.equal(snap.jumps, 2);
+    assert.equal(snap.stalls, 1);
+});

From 7d94c78dcc411813606fd42208a2cd3238b3a7c3 Mon Sep 17 00:00:00 2001
From: juansilvadesign <jaypy.uxdesign@gmail.com>
Date: Thu, 9 Jul 2026 11:23:33 -0300
Subject: [PATCH 2/2] ci(canary): sonda noturna das APIs privadas do player
 numa live real
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Todo dia, scripts/canary.mjs (npm run canary) carrega a extensão descompactada
num Chrome via puppeteer (devDep que o repo já tinha), abre uma live 24/7
(padrão: Lofi Girl; CANARY_VIDEO para trocar) e verifica as duas coisas que
hoje só relatório de usuário revelava DEPOIS do estrago: (1) as oito APIs
privadas do player que o motor usa ainda existem — o risco que o próprio
ROADMAP chama de existencial — e (2) o motor liga e amostra a live de verdade,
provado pela ponte de diagnóstico (_zd_diag_request/_response). Duas tentativas
com navegador novo; relatório em canary-report.json (gitignored, vira artifact).

Falha abre/atualiza UMA issue deduplicada (label canary) — nunca bloqueia
merge, porque YouTube visto de IP de datacenter é instável por natureza
(validado na prática: nesta rede a live carrega playability UNPLAYABLE mesmo
com todas as APIs presentes; o relatório agora distingue esse caso de uma
mudança real de API e manda verificar localmente).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AiLQznJ15KbuK73b9YxAjS
---
 .github/workflows/canary.yml |  84 +++++++++++++
 .gitignore                   |   3 +
 CHANGELOG.md                 |  11 ++
 package.json                 |   1 +
 scripts/canary.mjs           | 228 +++++++++++++++++++++++++++++++++++
 5 files changed, 327 insertions(+)
 create mode 100644 .github/workflows/canary.yml
 create mode 100644 scripts/canary.mjs

diff --git a/.github/workflows/canary.yml b/.github/workflows/canary.yml
new file mode 100644
index 0000000..a964dcc
--- /dev/null
+++ b/.github/workflows/canary.yml
@@ -0,0 +1,84 @@
+# Nightly canary: load the extension on a real 24/7 live and verify that
+# (1) YouTube's private player APIs the engine depends on still exist, and
+# (2) the engine comes alive and samples the stream (via its own diagnostics
+# bridge). This is the project's early-warning system for the risk ROADMAP.md
+# calls out: a YouTube-side refactor silently breaking everyone at once.
+#
+# Deliberately NOT part of the PR/push CI: YouTube from a datacenter IP is
+# inherently flaky (consent walls, robot checks, regional ads). A failure
+# files/updates ONE deduplicated issue (label: canary) for a human to verify
+# locally — it never blocks merges.
+name: Canary
+
+on:
+  schedule:
+    - cron: '23 6 * * *'   # daily, off the top of the hour
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  canary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci --no-audit --no-fund
+      - name: Probe a live stream with the extension loaded
+        run: node scripts/canary.mjs
+        env:
+          # Repository variable to repoint when the default 24/7 stream dies.
+          CANARY_VIDEO: ${{ vars.CANARY_VIDEO }}
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: canary-report
+          path: canary-report.json
+          if-no-files-found: ignore
+      - name: File (or update) the canary issue
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let report = '(canary-report.json missing — the run crashed before probing)';
+            try { report = fs.readFileSync('canary-report.json', 'utf8'); } catch {}
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            const body = [
+              '## Canário vermelho 🐤',
+              '',
+              'A sonda noturna falhou ao validar as APIs privadas do player / o motor numa live real.',
+              `Execução: ${runUrl}`,
+              '',
+              '**Antes de reagir:** rode `npm run canary` localmente — IP de datacenter no CI',
+              'é naturalmente instável (consent wall, robot check). Se falhar local também,',
+              'as APIs do YouTube provavelmente mudaram (ver `caps` no relatório).',
+              '',
+              '<details><summary>canary-report.json</summary>',
+              '',
+              '```json',
+              report.slice(0, 60000),
+              '```',
+              '</details>',
+            ].join('\n');
+            const { data: open } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo,
+              state: 'open', labels: 'canary', per_page: 1,
+            });
+            if (open.length) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                issue_number: open[0].number, body,
+              });
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner, repo: context.repo.repo,
+                title: '[Canary]: sonda noturna falhou — verificar APIs do player',
+                labels: ['canary'], body,
+              });
+            }
diff --git a/.gitignore b/.gitignore
index d7a81bd..cad5c4d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,9 @@ node_modules/
 # Marketing/store assets — não versionados (gerados a partir dos HTML localmente).
 publishing/assets/
 
+# Canary probe output (scripts/canary.mjs — uploaded as a CI artifact, never committed)
+canary-report.json
+
 # OS / editor / cloud cruft
 .DS_Store
 Thumbs.db
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d51c9f8..1e0b841 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,17 @@ e o projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
   compartilhável com o tempo assistido, o atraso recuperado pelo catch-up, os
   pulos para o ao vivo, as travadas e a latência média da live atual.
 
+### Adicionado (ferramentas do repositório)
+
+- **Canário noturno no CI** (`.github/workflows/canary.yml` +
+  `scripts/canary.mjs` / `npm run canary`): todo dia, carrega a extensão numa
+  live 24/7 de verdade e confere (1) que as APIs privadas do player que o motor
+  usa ainda existem e (2) que o motor liga e amostra a live (pela ponte de
+  diagnóstico). Falha abre/atualiza UMA issue deduplicada (label `canary`) —
+  nunca bloqueia merge, porque YouTube visto de IP de datacenter é
+  naturalmente instável. É o alarme antecipado para o risco que o ROADMAP
+  aponta como existencial: o YouTube refatorar o player e quebrar todo mundo.
+
 ## [1.4.0] - 2026-07-07
 
 ### Adicionado
diff --git a/package.json b/package.json
index 9e22eae..f576da2 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,7 @@
       "test": "node --test",
       "validate": "node scripts/validate.mjs",
       "check:locales": "node scripts/check-locales.mjs",
+      "canary": "node scripts/canary.mjs",
       "build": "node scripts/validate.mjs && node scripts/build.mjs",
       "build:firefox": "node scripts/build-firefox.cjs",
       "lint": "eslint .",
diff --git a/scripts/canary.mjs b/scripts/canary.mjs
new file mode 100644
index 0000000..561ddb0
--- /dev/null
+++ b/scripts/canary.mjs
@@ -0,0 +1,228 @@
+// ZeroDelay — keep YouTube live streams in real time
+// Author: João Gustavo França <joao@solitus.com.br> (https://github.com/joaogfc)
+//
+// Canary: loads the UNPACKED extension on a real 24/7 live stream and checks
+// the two things user bug reports can only tell us AFTER the damage is done:
+//
+//   1. YouTube's PRIVATE player APIs the engine depends on still exist
+//      (the same list inject.js probes into `caps` — the project's single
+//      biggest existential risk is YouTube renaming one of them);
+//   2. the engine actually comes alive on the stream: the diagnostics bridge
+//      (engine/telemetry.js) answers with ok + live samples and no degraded
+//      flag.
+//
+// Runs nightly in CI (.github/workflows/canary.yml) and on demand locally:
+//   npm run canary                 # headless
+//   CANARY_HEADED=1 npm run canary # watch it happen
+//   CANARY_VIDEO=<id> npm run canary
+//
+// Honest caveat: YouTube behaves differently toward datacenter IPs (consent
+// walls, robot checks, regional ads). The script retries with a fresh browser
+// and the workflow only *files an issue*, never fails a build — treat a red
+// canary as "verify locally", not "the sky fell".
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import puppeteer from 'puppeteer';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+
+// Lofi Girl's "beats to relax/study to" — streaming 24/7 for years, the
+// closest thing YouTube has to a live-stream test fixture. Overridable when
+// it finally sleeps: CANARY_VIDEO=<videoId>.
+const VIDEO_ID = process.env.CANARY_VIDEO || 'jfKfPfyJRdk';
+const WATCH_URL = `https://www.youtube.com/watch?v=${VIDEO_ID}`;
+
+const ATTEMPTS = 2;                 // fresh browser per attempt
+const PLAYER_TIMEOUT_MS = 90_000;   // #movie_player appearing
+const ENGINE_DEADLINE_MS = 150_000; // engine alive + sampling (pre-roll ads eat time)
+const MIN_SAMPLES = 5;              // ~5s of real live ticking
+
+// The exact private-API surface inject.js probes into `caps` — keep in sync.
+const REQUIRED_APIS = [
+    'getStatsForNerds', 'getProgressState', 'getVideoData', 'setPlaybackRate',
+    'getPlaybackRate', 'seekToLiveHead', 'playVideo', 'getPlayerStateObject',
+];
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+async function launch() {
+    return puppeteer.launch({
+        // Chrome's new headless supports extensions; set CANARY_HEADED=1 to watch.
+        headless: !process.env.CANARY_HEADED,
+        args: [
+            `--disable-extensions-except=${root}`,
+            `--load-extension=${root}`,
+            '--autoplay-policy=no-user-gesture-required',
+            '--mute-audio',
+            '--window-size=1280,800',
+            ...(process.env.CI ? ['--no-sandbox', '--disable-dev-shm-usage'] : []),
+        ],
+    });
+}
+
+// EU consent wall: the SOCS cookie skips it; the click is the fallback when
+// YouTube ships a variant the cookie doesn't cover.
+async function dodgeConsent(browser, page) {
+    await browser.setCookie({
+        name: 'SOCS', value: 'CAI', domain: '.youtube.com', path: '/',
+        secure: true, sameSite: 'None', expires: Math.floor(Date.now() / 1000) + 3600 * 24 * 30,
+    }).catch(() => { });
+    const clickConsent = async () => {
+        for (const label of ['Accept all', 'Aceitar tudo', 'Reject all']) {
+            const clicked = await page.evaluate(text => {
+                const btn = [...document.querySelectorAll('button')]
+                    .find(b => (b.textContent || '').trim().toLowerCase().includes(text.toLowerCase()));
+                if (btn) { btn.click(); return true; }
+                return false;
+            }, label).catch(() => false);
+            if (clicked) return true;
+        }
+        return false;
+    };
+    if (page.url().includes('consent.')) {
+        await clickConsent();
+        await sleep(3000);
+    }
+}
+
+// Probe the private player APIs in the page's MAIN world (same surface as
+// inject.js's probe_caps) plus live-stats and playability sanity reads —
+// `playability` tells a human whether a red run means "stream is down" or
+// "YouTube served this network a degraded page" (datacenter IPs get those).
+function probePlayer(page) {
+    return page.evaluate(apis => {
+        const p = document.getElementById('movie_player');
+        if (!p) return null;
+        const caps = {};
+        for (const name of apis) caps[name] = typeof p[name] === 'function';
+        let liveLatency = null, isLive = null, playability = null;
+        try {
+            const s = typeof p.getStatsForNerds === 'function' ? p.getStatsForNerds() : null;
+            if (s) liveLatency = parseFloat(s.live_latency_secs);
+        } catch { /* probed as missing below */ }
+        try {
+            const vd = typeof p.getVideoData === 'function' ? p.getVideoData() : null;
+            if (vd) isLive = vd.isLive === true;
+        } catch { /* ditto */ }
+        try {
+            const pr = typeof p.getPlayerResponse === 'function' ? p.getPlayerResponse() : null;
+            playability = pr?.playabilityStatus?.status || null;   // e.g. OK / UNPLAYABLE / LOGIN_REQUIRED
+        } catch { /* informational only */ }
+        return { caps, liveLatency: Number.isFinite(liveLatency) ? liveLatency : null, isLive, playability };
+    }, REQUIRED_APIS).catch(() => null);
+}
+
+// Round-trip the extension's own diagnostics bridge: proves content script +
+// engine + telemetry are alive on this stream, and returns real engine data.
+function requestDiagnostics(page) {
+    return page.evaluate(() => new Promise(resolve => {
+        const onResp = e => {
+            document.removeEventListener('_zd_diag_response', onResp);
+            resolve(e.detail || null);
+        };
+        document.addEventListener('_zd_diag_response', onResp);
+        document.dispatchEvent(new CustomEvent('_zd_diag_request'));
+        setTimeout(() => {
+            document.removeEventListener('_zd_diag_response', onResp);
+            resolve(null);
+        }, 2000);
+    })).catch(() => null);
+}
+
+async function attempt(n) {
+    const browser = await launch();
+    const failures = [];
+    let probe = null, diag = null;
+    try {
+        const page = await browser.newPage();
+        await dodgeConsent(browser, page);
+        await page.goto(WATCH_URL, { waitUntil: 'domcontentloaded', timeout: 60_000 });
+        await dodgeConsent(browser, page);
+
+        await page.waitForSelector('#movie_player', { timeout: PLAYER_TIMEOUT_MS });
+
+        // Nudge playback: stats only flow while the video plays.
+        await page.evaluate(() => {
+            const p = document.getElementById('movie_player');
+            if (p && typeof p.playVideo === 'function') p.playVideo();
+        }).catch(() => { });
+
+        // Give the page a moment to hydrate the player methods, then probe.
+        await sleep(5000);
+        probe = await probePlayer(page);
+        if (!probe) {
+            failures.push('#movie_player exists but could not be probed');
+        } else {
+            for (const [name, ok] of Object.entries(probe.caps)) {
+                if (!ok) failures.push(`private player API missing: ${name}()`);
+            }
+        }
+
+        // Engine liveness: poll the diagnostics bridge until it reports live
+        // samples (pre-roll ads and slow CI machines legitimately delay this).
+        // Keep re-probing the player so the report reflects the FINAL state,
+        // not the five-second snapshot.
+        const deadline = Date.now() + ENGINE_DEADLINE_MS;
+        while (Date.now() < deadline) {
+            diag = await requestDiagnostics(page);
+            if (diag && diag.ok && !diag.degraded && (diag.samples?.length || 0) >= MIN_SAMPLES) break;
+            const again = await probePlayer(page);
+            if (again) probe = again;
+            await sleep(5000);
+        }
+        if (probe && probe.isLive === false) {
+            failures.push(`video ${VIDEO_ID} did not play as LIVE here (playability: ${probe.playability || 'unknown'}) — `
+                + 'either the stream is down (repoint CANARY_VIDEO) or YouTube served this network a degraded page (verify locally)');
+        }
+        if (!diag) {
+            failures.push('engine never answered the diagnostics bridge (content script dead, or stream never ticked as live)');
+        } else if (diag.degraded) {
+            failures.push('engine reports DEGRADED — the player API surface changed under it');
+        } else if ((diag.samples?.length || 0) < MIN_SAMPLES) {
+            failures.push(`engine answered but sampled only ${diag.samples?.length || 0} live ticks (< ${MIN_SAMPLES})`);
+        }
+        if (diag && diag.ok && probe && probe.liveLatency == null) {
+            failures.push('getStatsForNerds().live_latency_secs no longer parses as a number');
+        }
+    } catch (e) {
+        failures.push(`attempt crashed: ${e?.message || e}`);
+    } finally {
+        await browser.close().catch(() => { });
+    }
+    return { attempt: n, failures, probe, diag };
+}
+
+const runs = [];
+let verdict = null;
+for (let n = 1; n <= ATTEMPTS; n++) {
+    console.log(`canary — attempt ${n}/${ATTEMPTS} on ${WATCH_URL}`);
+    const result = await attempt(n);
+    runs.push(result);
+    if (result.failures.length === 0) { verdict = 'pass'; break; }
+    console.error(`  attempt ${n} failed:\n    - ${result.failures.join('\n    - ')}`);
+}
+verdict = verdict || 'fail';
+
+const report = {
+    verdict,
+    video: VIDEO_ID,
+    at: new Date().toISOString(),
+    runs: runs.map(r => ({
+        attempt: r.attempt,
+        failures: r.failures,
+        caps: r.probe?.caps || null,
+        isLive: r.probe?.isLive ?? null,
+        playability: r.probe?.playability ?? null,
+        liveLatency: r.probe?.liveLatency ?? null,
+        engine: r.diag ? {
+            degraded: !!r.diag.degraded,
+            samples: r.diag.samples?.length || 0,
+            appliedRate: r.diag.appliedRate ?? null,
+            session: r.diag.session || null,
+        } : null,
+    })),
+};
+writeFileSync(join(root, 'canary-report.json'), JSON.stringify(report, null, 2));
+console.log(`canary — ${verdict.toUpperCase()} (report: canary-report.json)`);
+if (verdict !== 'pass') process.exit(1);