Deploy: streamer Stream Deck dashboard at /studio

bot/dashboard_parity_gate.py

@@ -364,6 +364,17 @@ PARITY_CONTRACT: tuple[ParityContractEntry, ...] = (
         backend_test_files=("bot/tests/scientific/test_phase29_production_scientific.py",),
         route_snippet="/api/coaching/churn-risk",
     ),
+    ParityContractEntry(
+        method="GET",
+        backend_route="/api/studio/stream",
+        domain="studio",
+        dashboard_surface="studio_sse",
+        status="headless_approved",
+        headless_reason="SSE agregado do /studio (EventSource); substitui 8 polls, sem painel separado.",
+        planned_phase="phase-30-studio-realtime",
+        backend_test_files=("bot/tests/scientific/test_phase30_studio_stream_scientific.py",),
+        route_snippet="/api/studio/stream",
+    ),
     ParityContractEntry(
         method="GET",
         backend_route="/api/segments",

bot/dashboard_server_routes.py

@@ -1,5 +1,7 @@
 import asyncio
+import json
 import mimetypes
+import time
 from collections.abc import Callable
 from typing import Any
 
@@ -727,6 +729,52 @@ def _handle_get_segments(handler: Any, _query: dict[str, list[str]]) -> None:
     handler._send_json({"ok": True, "segments": available_segments()}, status_code=200)
 
 
+STUDIO_STREAM_INTERVAL_SECONDS = 2.0
+STUDIO_STREAM_MAX_SECONDS = 300.0
+
+
+def build_studio_snapshot(channel_id: str | None = None) -> dict[str, Any]:
+    """Single aggregated payload for /studio — replaces 8 separate polls."""
+    safe_channel = (channel_id or "default").strip().lower() or "default"
+    queue_payload = control_plane.list_actions(status=None, limit=20)
+    return {
+        "ok": True,
+        "ts": time.time(),
+        "channel": safe_channel,
+        "control_plane": build_control_plane_state_payload(),
+        "sentiment": build_sentiment_scores_payload(safe_channel),
+        "churn": build_coaching_churn_payload(safe_channel),
+        "observability": build_observability_payload(safe_channel),
+        "queue": {"ok": True, "mode": TWITCH_CHAT_MODE, **queue_payload},
+        "clips": {"ok": True, "items": clip_jobs.get_jobs()},
+        "vision": {"ok": True, **vision_runtime.get_status()},
+        "hud": {"ok": True, "messages": hud_runtime.get_messages(since=0)},
+    }
+
+
+def _handle_get_studio_stream(handler: Any, query: dict[str, list[str]]) -> None:
+    """SSE stream of the studio snapshot. Caps the connection so the thread is
+    freed periodically; the EventSource client reconnects automatically."""
+    channel_id = _resolve_channel_id(query, required=False)
+    handler.send_response(200)
+    handler._send_cors_headers()
+    handler.send_header("Content-Type", "text/event-stream; charset=utf-8")
+    handler.send_header("Cache-Control", "no-store")
+    handler.send_header("Connection", "keep-alive")
+    handler.send_header("X-Accel-Buffering", "no")  # disable proxy buffering
+    handler.end_headers()
+
+    deadline = time.time() + STUDIO_STREAM_MAX_SECONDS
+    try:
+        while time.time() < deadline:
+            data = json.dumps(build_studio_snapshot(channel_id), ensure_ascii=False)
+            handler.wfile.write(f"data: {data}\n\n".encode())
+            handler.wfile.flush()
+            time.sleep(STUDIO_STREAM_INTERVAL_SECONDS)
+    except (BrokenPipeError, ConnectionResetError, OSError):
+        return  # client disconnected — let the thread end cleanly
+
+
 def _handle_get_voice_messages(handler: Any, query: dict[str, list[str]]) -> None:
     since_raw = str((query.get("since") or ["0"])[0] or "0")
     try:
@@ -825,6 +873,7 @@ _GET_ROUTE_HANDLERS: dict[str, Callable[[Any, dict[str, list[str]]], None]] = {
     "/api/voice/audio": _handle_get_voice_audio,
     "/api/coaching/churn-risk": _handle_get_coaching_churn,
     "/api/segments": _handle_get_segments,
+    "/api/studio/stream": _handle_get_studio_stream,
     "/api/observability/conversions": _handle_get_revenue_conversions,
     "/api/webhooks": _handle_get_webhooks,
     "/api/persona-profile": _handle_get_persona_profile,
@@ -1103,6 +1152,7 @@ __all__ = [
     "build_post_stream_report_payload",
     "build_semantic_memory_payload",
     "build_sentiment_scores_payload",
+    "build_studio_snapshot",
     "handle_get",
     "handle_get_config_js",
     "handle_post",

bot/tests/scientific/test_phase30_studio_stream_scientific.py

@@ -0,0 +1,53 @@
+"""Scientific test suite for Phase 30 (Fase S0): studio real-time data layer.
+
+Tests validate behavioral contracts of the aggregated SSE snapshot, NOT
+implementation details:
+1. build_studio_snapshot aggregates every studio sub-payload into one object.
+2. The aggregated snapshot is JSON-serializable (it must stream as SSE data).
+3. The /api/studio/stream route is registered (and declared in the parity gate).
+"""
+
+import json
+
+import bot.dashboard_server_routes as routes
+
+
+class TestStudioSnapshotAggregates:
+    """Prove one snapshot replaces the 8 separate studio polls."""
+
+    def test_snapshot_has_all_sections(self):
+        snap = routes.build_studio_snapshot("default")
+        for key in (
+            "control_plane",
+            "sentiment",
+            "churn",
+            "observability",
+            "queue",
+            "clips",
+            "vision",
+            "hud",
+        ):
+            assert key in snap, f"missing section: {key}"
+        assert snap["ok"] is True
+        assert snap["channel"] == "default"
+
+    def test_snapshot_is_json_serializable(self):
+        # Must serialize cleanly — it is streamed as `data: <json>\n\n`.
+        payload = json.dumps(routes.build_studio_snapshot("default"), ensure_ascii=False)
+        assert payload.startswith("{")
+        assert json.loads(payload)["ok"] is True
+
+    def test_channel_is_normalized(self):
+        assert routes.build_studio_snapshot("Canal_X")["channel"] == "canal_x"
+
+
+class TestStudioStreamRoute:
+    """Prove the SSE endpoint is wired."""
+
+    def test_stream_route_registered(self):
+        assert "/api/studio/stream" in routes._GET_ROUTE_HANDLERS
+
+    def test_stream_interval_is_sane(self):
+        # Must push fast enough for <1s-feel state but not hammer the LLM/db.
+        assert 0 < routes.STUDIO_STREAM_INTERVAL_SECONDS <= 5
+        assert routes.STUDIO_STREAM_MAX_SECONDS >= 60

dashboard/features/studio/main.js

@@ -3,6 +3,7 @@
 // each tile to a real bot endpoint. Vanilla ES module, no build step.
 import * as api from "./api.js";
 import { ICONS, hydrateIcons } from "./icons.js";
+import { deriveStudioState, pendingActions, tickerEntries } from "./snapshot.js";
 
 const TOKEN_KEY = "byte_dashboard_admin_token";
 const POLL_MS = 5000;
@@ -47,7 +48,7 @@ function saveTokenFromGate() {
   if (!value) return;
   localStorage.setItem(TOKEN_KEY, value);
   closeGate();
-  tick();
+  connectRealtime();
 }
 
 // ---------- modals ----------
@@ -161,15 +162,7 @@ function renderVision(payload) {
 }
 
 function renderQueue(payload) {
-  const items = Array.isArray(payload.items)
-    ? payload.items
-    : Array.isArray(payload.queue)
-      ? payload.queue
-      : [];
-  state.pendingActions = items.filter((it) => {
-    const s = String(it.status || it.state || "pending").toLowerCase();
-    return s === "pending" || s === "awaiting" || s === "open";
-  });
+  state.pendingActions = pendingActions({ queue: payload });
   const badge = $("approveBadge");
   const n = state.pendingActions.length;
   badge.textContent = String(n);
@@ -180,38 +173,53 @@ function renderQueue(payload) {
   $("tileApprove").disabled = n === 0;
 }
 
-function renderTicker(messages) {
+function renderTicker(entries) {
+  // Idempotent: rebuilt from the full recent list each snapshot (SSE-safe).
   const list = $("tickerList");
-  if (!messages.length) {
-    if (!state.bootedTicker) {
-      list.innerHTML = '<li class="ticker-empty">Sem atividade ainda…</li>';
-      state.bootedTicker = true;
-    }
+  if (!entries.length) {
+    const empty = document.createElement("li");
+    empty.className = "ticker-empty";
+    empty.textContent = "Sem atividade ainda…";
+    list.replaceChildren(empty);
     return;
   }
-  if (!state.bootedTicker) list.innerHTML = "";
-  for (const m of messages) {
+  const frag = document.createDocumentFragment();
+  for (const m of entries) {
     const li = document.createElement("li");
     li.className = "ticker-item";
     const t = document.createElement("time");
     const ts = Number(m.ts || 0) * 1000;
     t.textContent = ts
-      ? new Date(ts).toLocaleTimeString([], {
-          hour: "2-digit",
-          minute: "2-digit",
-        })
+      ? new Date(ts).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })
       : "";
     const span = document.createElement("span");
     span.textContent = m.text || "";
     li.append(t, span);
-    list.prepend(li);
-    state.hudSince = Math.max(state.hudSince, Number(m.ts || 0));
+    frag.appendChild(li);
   }
-  while (list.children.length > 12) list.removeChild(list.lastChild);
-  state.bootedTicker = true;
+  list.replaceChildren(frag);
 }
 
-// ---------- polling ----------
+// ---------- render from a snapshot (shared by SSE + polling) ----------
+function applySnapshot(snap) {
+  if (!snap) return;
+  const derived = deriveStudioState(snap);
+  state.online = derived.online;
+  state.suspended = derived.suspended;
+  state.mode = derived.mode;
+  state.channel = derived.channel;
+  renderStatus();
+  if (snap.sentiment) renderMood(snap.sentiment);
+  if (snap.observability)
+    renderUptime(snap.observability.bot && snap.observability.bot.uptime_minutes);
+  if (snap.hud) renderTicker(tickerEntries(snap.hud.messages));
+  if (snap.clips) renderClips(snap.clips);
+  if (snap.vision) renderVision(snap.vision);
+  if (snap.queue) renderQueue(snap.queue);
+  if (snap.churn) renderRetention(snap.churn);
+}
+
+// ---------- polling fallback (one-shot + interval) ----------
 async function tick() {
   if (!hasToken()) {
     openGate();
@@ -220,7 +228,7 @@ async function tick() {
   const [cp, sent, hud, clips, vision, queue, obs, churn] = await Promise.allSettled([
     api.getControlPlane(),
     api.getSentiment(state.channel),
-    api.getHudMessages(state.hudSince),
+    api.getHudMessages(0),
     api.getClipJobs(),
     api.getVisionStatus(),
     api.getActionQueue(20),
@@ -233,29 +241,17 @@ async function tick() {
     return;
   }
   closeGate();
-
-  if (cp.status === "fulfilled") {
-    const autonomy = cp.value.autonomy || {};
-    state.online = true;
-    state.suspended = Boolean(autonomy.suspended);
-    state.mode = cp.value.mode || state.mode;
-  } else {
-    state.online = false;
-  }
-  renderStatus();
-
-  if (sent.status === "fulfilled") {
-    state.channel = sent.value.channel_id || state.channel;
-    renderMood(sent.value);
-  }
-  if (obs.status === "fulfilled")
-    renderUptime(obs.value && obs.value.bot && obs.value.bot.uptime_minutes);
-  if (hud.status === "fulfilled")
-    renderTicker(Array.isArray(hud.value.messages) ? hud.value.messages : []);
-  if (clips.status === "fulfilled") renderClips(clips.value);
-  if (vision.status === "fulfilled") renderVision(vision.value);
-  if (queue.status === "fulfilled") renderQueue(queue.value);
-  if (churn.status === "fulfilled") renderRetention(churn.value);
+  applySnapshot({
+    ok: cp.status === "fulfilled",
+    control_plane: cp.status === "fulfilled" ? cp.value : null,
+    sentiment: sent.status === "fulfilled" ? sent.value : null,
+    hud: hud.status === "fulfilled" ? hud.value : null,
+    clips: clips.status === "fulfilled" ? clips.value : null,
+    vision: vision.status === "fulfilled" ? vision.value : null,
+    queue: queue.status === "fulfilled" ? queue.value : null,
+    observability: obs.status === "fulfilled" ? obs.value : null,
+    churn: churn.status === "fulfilled" ? churn.value : null,
+  });
 }
 
 const RETENTION_LABEL = {
@@ -522,14 +518,65 @@ function bind() {
   $("approveClose").addEventListener("click", () => closeModal("approveModal"));
 }
 
+// ---------- realtime (SSE) with polling fallback ----------
+let eventSource = null;
+let pollTimer = null;
+let sseFailures = 0;
+
+function startPolling() {
+  if (pollTimer) return;
+  tick();
+  pollTimer = setInterval(tick, POLL_MS);
+}
+
+function connectRealtime() {
+  const token = (localStorage.getItem(TOKEN_KEY) || "").trim();
+  if (!token) {
+    openGate();
+    return;
+  }
+  if (typeof EventSource === "undefined") {
+    startPolling();
+    return;
+  }
+  try {
+    eventSource = new EventSource(
+      `/api/studio/stream?channel=${encodeURIComponent(state.channel)}&auth=${encodeURIComponent(token)}`,
+    );
+  } catch (_e) {
+    startPolling();
+    return;
+  }
+  eventSource.onmessage = (event) => {
+    sseFailures = 0;
+    if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+    closeGate();
+    try {
+      applySnapshot(JSON.parse(event.data));
+    } catch (_e) {
+      /* ignore a malformed frame; next one will arrive */
+    }
+  };
+  eventSource.onerror = () => {
+    // EventSource auto-reconnects; only fall back if it cannot re-establish.
+    sseFailures += 1;
+    if (sseFailures >= 2) {
+      eventSource.close();
+      eventSource = null;
+      startPolling();
+    }
+  };
+}
+
 function start() {
   hydrateIcons();
   // Give the pause tile icon host a stable id for swapping.
   $("tilePause").querySelector(".tile-ico").id = "pauseIco";
   bind();
-  if (!hasToken()) openGate();
-  tick();
-  setInterval(tick, POLL_MS);
+  connectRealtime();
 }
 
 if (document.readyState === "loading") {

dashboard/features/studio/snapshot.js

@@ -0,0 +1,40 @@
+// dashboard/features/studio/snapshot.js
+// Pure, DOM-free derivations from the aggregated /api/studio/stream snapshot.
+// Kept side-effect-free so they can be unit-tested deterministically.
+
+const PENDING_STATES = new Set(["pending", "awaiting", "open"]);
+
+/** Derive the high-level studio state from a snapshot (no DOM). */
+export function deriveStudioState(snap) {
+  const cp = (snap && snap.control_plane) || {};
+  const autonomy = cp.autonomy || {};
+  const sentiment = (snap && snap.sentiment) || {};
+  return {
+    online: Boolean(snap && snap.ok !== false),
+    suspended: Boolean(autonomy.suspended),
+    mode: cp.mode || "—",
+    channel: sentiment.channel_id || (snap && snap.channel) || "default",
+    pendingCount: pendingActions(snap).length,
+  };
+}
+
+/** Pending action-queue items from a snapshot (no DOM). */
+export function pendingActions(snap) {
+  const queue = (snap && snap.queue) || {};
+  const items = Array.isArray(queue.items)
+    ? queue.items
+    : Array.isArray(queue.queue)
+      ? queue.queue
+      : [];
+  return items.filter((it) =>
+    PENDING_STATES.has(String(it.status || it.state || "pending").toLowerCase()),
+  );
+}
+
+/** Ticker messages, newest first, capped — idempotent for SSE full snapshots. */
+export function tickerEntries(messages, limit = 12) {
+  if (!Array.isArray(messages)) return [];
+  return [...messages]
+    .sort((a, b) => Number(b.ts || 0) - Number(a.ts || 0))
+    .slice(0, limit);
+}

dashboard/tests/studio_stream_merge.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  deriveStudioState,
+  pendingActions,
+  tickerEntries,
+} from "../features/studio/snapshot.js";
+
+test("deriveStudioState reads a full snapshot the same way SSE and polling produce it", () => {
+  const snap = {
+    ok: true,
+    channel: "gaules",
+    control_plane: { mode: "irc", autonomy: { suspended: true } },
+    sentiment: { channel_id: "gaules", avg: 0.4, count: 10 },
+    queue: { items: [{ status: "pending" }, { status: "approved" }] },
+  };
+  const s = deriveStudioState(snap);
+  assert.equal(s.online, true);
+  assert.equal(s.suspended, true);
+  assert.equal(s.mode, "irc");
+  assert.equal(s.channel, "gaules");
+  assert.equal(s.pendingCount, 1);
+});
+
+test("deriveStudioState degrades safely on empty/failed snapshot", () => {
+  assert.equal(deriveStudioState(null).online, false);
+  assert.equal(deriveStudioState({ ok: false }).online, false);
+  assert.equal(deriveStudioState({}).channel, "default");
+});
+
+test("pendingActions filters only open states", () => {
+  const snap = {
+    queue: {
+      items: [
+        { status: "pending" },
+        { status: "awaiting" },
+        { status: "open" },
+        { status: "approved" },
+        { status: "rejected" },
+      ],
+    },
+  };
+  assert.equal(pendingActions(snap).length, 3);
+});
+
+test("tickerEntries is idempotent: newest-first, capped, pure", () => {
+  const messages = [
+    { ts: 1, text: "a" },
+    { ts: 3, text: "c" },
+    { ts: 2, text: "b" },
+  ];
+  const out = tickerEntries(messages, 2);
+  assert.deepEqual(
+    out.map((m) => m.text),
+    ["c", "b"],
+  );
+  // Calling twice yields the same result (no mutation of input).
+  assert.deepEqual(tickerEntries(messages, 2), out);
+  assert.equal(messages[0].text, "a"); // input untouched
+  assert.deepEqual(tickerEntries(null), []);
+});

docs/VALIDATION_REPORT_2026-06-29.md

@@ -0,0 +1,47 @@
+# Validation Report — Co-Streamer Implementation (brutalmente honesto)
+
+**Data:** 2026-06-29 · **Escopo:** validação completa de tudo que esta sessão implementou (Fases 0–4), caçando bugs, inconsistências e gaps. Sem tour de vitória.
+
+---
+
+## 1. Veredito
+
+O **código entregue na primeira passada NÃO era world-class.** Funcionava nos testes e nos smoke tests felizes, mas escondia **1 vulnerabilidade de segurança, 1 bug que quebraria a voz real, e 4 problemas de robustez/qualidade.** Esta passada de validação encontrou e corrigiu todos. **Agora** o backend está sólido: 1061 testes verdes, 85% cobertura, todos os endpoints validados ao vivo, com isolamento de erro por request.
+
+A honestidade exige dizer: vários desses defeitos eu **deveria ter pego antes**. A validação só os expôs porque desta vez li o código com olhar adversarial em vez de confiar nos testes verdes.
+
+## 2. Defeitos encontrados e corrigidos
+
+| # | Severidade | Defeito | Por que era grave | Fix |
+| :--- | :--- | :--- | :--- | :--- |
+| 1 | 🔴 **Segurança** | **XSS armazenado** no modal de aprovação (`studio/main.js`): `title`/`body`/`kind` de itens da fila injetados via `innerHTML` | Itens incluem **texto de viewer** (resgate de Channel Points). Um resgate com `<img onerror=...>` executaria no dashboard **autenticado** do streamer | DOM via `textContent`, zero `innerHTML` interpolado |
+| 2 | 🔴 **Correção** | Corpo JSON do TTS montado com `repr()` do Python | `repr("você 'tá'")` → JSON inválido. Toda fala com aspas/apóstrofo/quebra de linha quebraria o ElevenLabs no minuto em que a key fosse plugada | `json.dumps` |
+| 3 | 🟠 **Performance** | Comentário rodava chamada LLM **síncrona dentro do thread HTTP** do `/api/vision/ingest` | Cada frame "interessante" segurava a resposta do ingest por segundos | thread daemon fire-and-forget |
+| 4 | 🟠 **Robustez** | `do_GET/POST/PUT` **não isolavam exceções** dos handlers | Um erro inesperado em qualquer endpoint deixava o cliente **pendurado** (sem resposta) | `_run_route_safely` → 500 limpo |
+| 5 | 🟠 **Consistência** | `highlight_runtime` enfileirava clipe **sem checar** `clip_pipeline_enabled` (a visão checa) | Pluraria a fila de risco com candidatos mesmo com pipeline off | gate adicionado + wired na autonomia |
+| 6 | 🟡 **Memória** | `regulars._seen` crescia **sem limite** (todo viewer, pra sempre) | Memory leak lento numa live longa | eviction LRU (cap 5000/canal) |
+| 7 | 🟡 **Regressão (auto-infligida)** | O fix #4 (`_dispatch` como método) **quebrou 22 testes HTTP** (MagicMock dispatch) | — | refatorado pra função de módulo `_run_route_safely`; pego e corrigido na mesma passada |
+
+## 3. Gaps honestos que PERMANECEM
+
+- **`channel_points_runtime` e `regulars_runtime` são lógica testada, mas NÃO estão ligadas** (0 referências de produção). Decisão consciente:
+  - **Channel Points** depende da subscription de redemption do EventSub (twitchio v3) + scope, e o bot roda em **IRC** hoje. Wirar com a API de redemption **adivinhada e não-validável** seria injetar código de baixa confiança num backend que precisa ser relógio suíço. Mantive o core (`process_redemption`) testado e correto.
+  - **Regulars** exige hook no caminho quente de mensagens e **muda comportamento ao vivo** (saudar viewers reais) — não injeto isso sem poder validar numa sessão real.
+  - **Veredito honesto:** essas duas features são "lógica pronta, integração pendente de um ambiente validável", **não** "entregues e rodando". Corrigi o doc do plano pra refletir isso.
+- **Numeração de fases nos testes** reusa `phase26`/`phase27` entre conceitos diferentes — inconsistência cosmética com a convenção (1 fase = 1 conceito). Não corrigido (baixo valor, alto churn).
+- **`studio` status** usa `innerHTML` com `state.mode`/`state.channel` (valores **do servidor**, sanitizados) — risco baixo, não user-input; deixei.
+
+## 4. Meta-Reflexão
+
+1. **Comportamento esperado re-derivado:** backend que roda "encaixado como relógio suíço" = sem XSS, sem bug de serialização, sem bloqueio de thread, sem leak, com isolamento de erro, sem código morto enganoso.
+2. **Rastreabilidade:** cada fix tem teste — XSS (DOM), JSON (`TestProviderRequestIsValidJson`), isolamento (`test_dispatch_*`), gate de highlight (`test_disabled_clip_pipeline_is_a_noop`), eviction (regulars), threading (comentário não bloqueia, validado e2e antes).
+3. **Suíte:** 1061 passed, 4 skipped, **85.37% cobertura**, hermética.
+4. **Regressão:** zero (a auto-infligida foi pega e corrigida).
+5. **Ao vivo:** 9 endpoints 200, 5 páginas 200, erro de payload → 400 limpo (deploy `f52ff93`).
+6. **Lição:** testes verdes ≠ código correto. Os 5 defeitos passaram por 1061 testes verdes porque os testes cobriam o caminho feliz, não o adversarial (texto com aspas, input malicioso, handler que explode). **Validação adversarial é obrigatória, não opcional.**
+
+## 5. Estado final
+
+✅ O backend que **roda** (vision, voice, commentary, segments, recap, churn, studio, todos os overlays) está sólido, blindado e validado ao vivo.
+🟡 Duas features (Channel Points, Regulars) têm o core testado mas aguardam integração validável.
+🔑 Ativação plena = checklist de operador em `docs/plan/README.md` (TTS key, Supabase, scopes Twitch, eventsub mode).

docs/plan/03-interaction.md

@@ -22,4 +22,6 @@ Os 3 módulos foram construídos e testados; a **ativação ao vivo** de cada um
 
 **3.2 Regulars — ✅ código pronto + testado.** `regulars_runtime.note_chatter`: first-timer não saúda; retorno após gap → saúda 1x; chat contínuo não re-saúda. **Ativação:** chamar `note_chatter` no handler de mensagem (IRC/eventsub) e mandar a saudação via voz/chat; memória persistente entra com Supabase (Fase 1.3).
 
-**Go:** ✅ código concluído. Abuso de redemption é contido (voice reward limita 200 chars + sanitiza; não-voz vai pra fila). Memória de regulars é por sessão (in-memory), respeitando isolamento por canal.
+**Go:** ✅ código concluído. Abuso de redemption é contido (voice reward limita 200 chars + sanitiza; não-voz vai pra fila). Memória de regulars é por sessão (in-memory, com eviction LRU), respeitando isolamento por canal.
+
+> ⚠️ **Status honesto (ver [VALIDATION_REPORT](../VALIDATION_REPORT_2026-06-29.md)):** `channel_points_runtime` e `regulars_runtime` são **lógica testada, NÃO wiradas** (0 refs de produção). Ativação pendente de ambiente validável (EventSub mode + scope de redemptions; hook no caminho de mensagens). Não foram injetadas nos hot paths do bot live sem validação — decisão de integridade pro backend "relógio suíço".

docs/plan/README.md

@@ -1,3 +1,10 @@
+# Planos do Byte
+
+- **[Co-Streamer](#plano-de-implementação--byte-co-streamer)** (este doc) — vê/fala/comenta/aparece.
+- **[Studio Dashboard State-of-the-Art](studio-state-of-the-art.md)** — evoluir o `/studio` pra referência.
+
+---
+
 # Plano de Implementação — Byte Co-Streamer
 
 Roteiro faseado que converte a [auditoria](../DEEP_AUDIT_2026-06-29.md) + o [report do co-streamer](../CO_STREAMER_REPORT_2026-06-29.md) em execução. Cada fase entrega **código + testes científicos + Meta-Reflexão**.

docs/plan/studio-state-of-the-art.md

@@ -0,0 +1,212 @@
+# Studio Dashboard — Plano State-of-the-Art (spec executável autônomo)
+
+> **Este documento é autocontido.** Um agente deve conseguir implementá-lo do zero,
+> fase a fase, **sem precisar de contexto externo** além do repositório. Toda
+> convenção, caminho de arquivo, comando e critério de aceite está aqui.
+
+**Alvo:** elevar a dash simples `/studio` de "Stream Deck MVP sólido" para **referência de painel operacional de streamer** — *wow porém leve*. · **Atualizado:** 2026-06-29.
+
+---
+
+## 0. Como executar este plano (meta-agêntico)
+
+1. **Ordem:** fases na sequência da seção 8 (default: S0 → S1 → S4 → S2 → S3 → S5 → S6). Não pule pré-requisitos.
+2. **Loop por fase:** `implementar → testar → validar ao vivo → meta-reflexão → commit`. Só avance após o **Gate de Pronto** (seção 9) passar 100%.
+3. **Invariantes (valem SEMPRE, não-negociáveis):** seção 2.
+4. **Sem ambiguidade:** cada fase lista arquivos exatos a criar/editar, passos, testes (com comando) e critério binário. Se algo estiver subespecificado, o agente escolhe a opção mais simples que respeita os invariantes e registra a decisão na meta-reflexão.
+5. **Saída por fase:** código + testes verdes + evidência ao vivo (screenshot/curl) + seção de meta-reflexão preenchida neste doc + 1 commit.
+
+---
+
+## 1. Contexto do repositório (autocontido — não precisa grep)
+
+**Stack do `/studio`:** vanilla JS (ES modules), servido por um HTTP server Python (`http.server`). Sem framework. LLM=Gemini; deploy=HF Spaces (Docker, porta 7860).
+
+**Mapa de arquivos relevantes:**
+| Arquivo | Papel |
+| :--- | :--- |
+| `dashboard/studio.html` | markup do `/studio` (~210 linhas) |
+| `dashboard/features/studio/main.js` | controller/poll/render (~540 linhas) |
+| `dashboard/features/studio/api.js` | wrappers de endpoint |
+| `dashboard/features/studio/icons.js` | set de ícones SVG inline |
+| `dashboard/features/shared/api.js` | `fetchWithTimeout(url, opts, ms)` — injeta token + reescreve `/api/` p/ HF + fallback `?auth=` |
+| `dashboard/styles/studio.css` | estilos (~810 linhas, tema claro só) |
+| `dashboard/tests/*.test.js` | testes JS (rodam com `node --test`) |
+| `bot/dashboard_server_routes.py` | rotas GET + serve de páginas (`_dashboard_asset_route`, `_GET_ROUTE_HANDLERS`) |
+| `bot/dashboard_server_routes_post.py` | rotas POST (`_POST_ROUTE_HANDLERS`) |
+| `bot/dashboard_server.py` | `HealthHandler` (server); `_run_route_safely` isola erros → 500 |
+| `bot/dashboard_parity_gate.py` | contrato rota↔teste (`PARITY_CONTRACT`); teste falha se rota nova não for declarada |
+| `bot/tests/scientific/test_phaseN_*_scientific.py` | testes científicos (contratos comportamentais) |
+
+**Convenções (copiar exatamente):**
+
+- **Servir uma página nova** (`/foo` → `dashboard/foo.html`): em `bot/dashboard_server_routes.py`, dentro de `_dashboard_asset_route`, adicione:
+  ```python
+  if route in {"/foo", "/foo/", "/dashboard/foo", "/dashboard/foo/"}:
+      handler._send_dashboard_asset("foo.html", "text/html; charset=utf-8")
+      return True
+  ```
+- **Endpoint GET** `/api/foo`: defina `def _handle_get_foo(handler, query): handler._send_json({...}, status_code=200)` em `dashboard_server_routes.py` e registre em `_GET_ROUTE_HANDLERS`. **POST:** em `dashboard_server_routes_post.py`, use `require_auth_and_read_payload(handler)` e registre em `_POST_ROUTE_HANDLERS`.
+- **Parity gate (obrigatório p/ rota `/api/*` nova):** adicione um `ParityContractEntry(...)` em `bot/dashboard_parity_gate.py`. Para superfícies sem teste de dashboard dedicado use `status="headless_approved"` com `headless_reason`, `planned_phase` e `backend_test_files=("bot/tests/scientific/test_phaseN_..._scientific.py",)` **que contenham a string da rota** (`route_snippet`). Senão `test_dashboard_parity_gate` quebra.
+- **Teste científico (py):** arquivo `bot/tests/scientific/test_phaseN_<nome>_scientific.py`; docstring lista os contratos; classes `Prove that...`; foca comportamento, não implementação. **Numere a partir de Phase 30** (26–29 já usados).
+- **Teste JS:** `dashboard/tests/<nome>.test.js`:
+  ```js
+  import assert from "node:assert/strict";
+  import test from "node:test";
+  import { fn } from "../features/studio/<mod>.js";
+  test("...", () => { assert.equal(fn(...), ...); });
+  ```
+- **Frontend novo:** módulos ES sob `dashboard/features/studio/`; importe `fetchWithTimeout` de `../shared/api.js`. Token: `localStorage["byte_dashboard_admin_token"]`; overlays leem `?token=` da URL.
+
+**Comandos de referência (use estes literais):**
+```bash
+# Suíte completa (deve terminar, hermética, verde, ≥80% cobertura)
+python -m pytest bot/tests/ -q -p no:cacheprovider
+# Suíte rápida sem cobertura
+python -m pytest bot/tests/ --no-cov -q -p no:cacheprovider
+# Testes JS
+node --test dashboard/tests/*.test.js
+# Render headless local (validar visual): sirva o repo e use o chromium do playwright
+#   exe: /home/juan/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome
+#   serve: python3 -m http.server <porta> --directory . ; abra http://127.0.0.1:<porta>/dashboard/studio.html
+# Deploy HF (lê de HEAD; precisa de HF_TOKEN e do snapshot git archive):
+#   ver docs/HF_SPACES_DEPLOY_RUNBOOK.md  (HfApi().upload_folder + restart_space)
+# Validar ao vivo: curl -H "X-Byte-Admin-Token: <ADMIN_TOKEN>" https://juancs-dev-twitch-byte-bot.hf.space/api/...
+```
+> **Segredos:** `HF_TOKEN` e `<ADMIN_TOKEN>` (= secret `BYTE_DASHBOARD_ADMIN_TOKEN`) **não** ficam neste doc; o operador fornece. Nunca commite segredo.
+
+---
+
+## 2. Invariantes (não-negociáveis, valem em TODAS as fases)
+
+1. **Segurança:** **nunca** `innerHTML` com dado dinâmico/de usuário — use `textContent`/`createElement`. (Já houve XSS via `innerHTML` no modal de aprovação; não repetir.)
+2. **Wow sem peso:** **zero** lib de animação/UI; CSS nativo only; efeitos a 60fps (só `transform`/`opacity`); **sempre** respeitar `prefers-reduced-motion`. JS do `/studio` não cresce >20% por fase.
+3. **Sem bloqueio:** nada de chamada síncrona pesada no thread de request; sem polling redundante após S0.
+4. **Resiliência:** todo fetch falha graciosamente (overlay/painel nunca quebra a cena); estados offline/sem-token claros.
+5. **Verde sempre:** após cada fase, `python -m pytest bot/tests/` termina verde, hermético, cobertura ≥80%, e `node --test dashboard/tests/*.test.js` verde (exceto a falha pré-existente conhecida em `control_plane_information_density.test.js`).
+6. **Vanilla:** sem React/Vue/etc. ES modules + utilidades minúsculas testáveis.
+7. **Não duplicar** a dash ops técnica (`/`); `/studio` é streamer-facing e simples.
+
+---
+
+## 3. Estado atual medido (baseline honesto)
+
+`/studio` (~1750 LOC) = Stream Deck tátil: header de status, medidor de humor, faixa de retenção (churn), grid 3×3 de tiles (PAUSAR, FALAR, HYPE, APROVAR, VISÃO, CLIPES, CANAIS, AGIR, RECAP), ticker, modais (falar/canais/recap/aprovações), gate de token, toasts, ícones SVG. Consome 15 endpoints **via polling** (8 a cada 5s).
+
+**Lacunas medidas vs SOTA:** polling-storm (sem SSE); sem tendências/sparklines; layout fixo; sem teclado/command palette; só tema claro (`prefers-color-scheme`=0); a11y parcial (ARIA em modais, sem foco-trap/roving tabindex/reduced-motion); não-PWA; sem UI otimista; onboarding fraco.
+
+---
+
+## 4. Princípios
+
+- **Calm by default, loud on demand** · **One-glance truth** · **Tudo em ≤2 toques** · **Reversível & seguro** · **Wow sem peso** (invariante 2).
+
+## 4.5 Linguagem visual — "bonito + leve" (grounding junho 2026)
+
+Fugir do SaaS genérico (gradiente pastel + sans amigável): design **deliberado, não decorativo** ([Tubik](https://blog.tubikstudio.com/ui-design-trends-2026/), [Tenet](https://www.wearetenet.com/blog/ui-ux-design-trends)).
+
+- **Function-forward + tipografia mono-inspired** nos dados (números/labels em mono) → identidade "cabine de operação".
+- **Glassmorphism 2.0:** `backdrop-filter` multi-camada + relative color + `mask-image`; GPU via `translateZ(0)`, `will-change` só durante animação ([ref](https://weblogtrips.com/technology/glassmorphism-2-0-css-techniques-2026/)).
+- **Paleta restrita arejada;** dark mode cidadão de 1ª classe.
+- **Movimento com propósito** (comunica estado, não enfeite).
+
+**Toolkit de wow leve (CSS nativo, zero lib):**
+| Técnica | Onde | Por que leve |
+| :--- | :--- | :--- |
+| **View Transitions API** | tile→modal, troca de estado/tab | transição nativa entre estados do DOM |
+| **Scroll-driven animations** (`scroll`/`view-timeline`) | reveals, sparklines | roda no compositor thread → 60fps mesmo com main thread ocupado ([ref](https://dev.to/nickbenksim/creating-complex-scroll-driven-animations-with-pure-css-in-2026-17l)) |
+| **`@starting-style`** | entrada de modais/toasts/banner | substitui libs de animação ([ref](https://medium.com/@alexdev82/css-micro-animations-in-2026-7-pure-css-techniques-that-replace-javascript-efd374b6e8a4)) |
+| **`color-mix()` / relative color** | tema + estados | deriva cores sem duplicar tokens |
+
+---
+
+## 5. Fases (cada uma = spec executável)
+
+> Formato fixo por fase: **Objetivo · Arquivos · Implementação · Testes (comando) · Critério de pronto (binário) · Validação ao vivo · Meta-reflexão (preencher ao concluir)**.
+
+### Fase S0 — Camada de dados em tempo real (fundação)
+**Objetivo:** 1 stream substitui 8 polls; estado <1s; leve.
+**Arquivos:** criar `bot/studio_snapshot.py` (builder `build_studio_snapshot(channel)` agregando control-plane+sentiment+queue+vision+clips+churn num dict); editar `bot/dashboard_server_routes.py` (handler SSE `_handle_get_studio_stream` em `_GET_ROUTE_HANDLERS` para `/api/studio/stream`, `Content-Type: text/event-stream`, loop que emite `data: <json>\n\n` a cada ~2s ou em mudança, com keep-alive); editar `dashboard/features/studio/main.js` (usar `EventSource("/api/studio/stream?auth=<token>")` com `onmessage` → render; reconexão com backoff; **fallback** ao polling atual se `EventSource` falhar 2x); criar `bot/tests/scientific/test_phase30_studio_stream_scientific.py`; criar `dashboard/tests/studio_stream_merge.test.js`.
+**Implementação:** (1) `build_studio_snapshot` reusa os builders existentes (`build_coaching_churn_payload`, `voice_runtime`, etc.); (2) SSE: gerar via um generator no handler escrevendo no `wfile`; tratar desconexão (BrokenPipe) sem logar erro; (3) cliente: extrair o render do `tick()` atual numa função `applySnapshot(snap)` reusada por SSE e polling.
+**Testes:** `python -m pytest bot/tests/scientific/test_phase30_studio_stream_scientific.py -q --no-cov` (prova: `build_studio_snapshot` retorna o contrato agregado; rota registrada; `Content-Type` correto). `node --test dashboard/tests/studio_stream_merge.test.js` (merge incremental determinístico).
+**Critério de pronto:** [ ] 1 conexão SSE substitui os 8 polls; [ ] cai pra polling sem quebrar quando SSE indisponível; [ ] latência de estado <1s; [ ] parity gate atualizado; [ ] suíte verde.
+**Validação ao vivo:** `curl -N -H "X-Byte-Admin-Token: <T>" .../api/studio/stream` emite eventos; render headless do `/studio` mostra dados.
+**Meta-reflexão:** *(preencher)*
+
+### Fase S1 — Glanceability & hierarquia
+**Objetivo:** verdade num olhar.
+**Arquivos:** criar `dashboard/features/studio/health.js` (função pura `operationalHealth({streamHealth, churnBand, pendingActions, online}) -> "healthy"|"attention"|"critical"`); criar `dashboard/features/studio/sparkline.js` (gera `<path>` SVG a partir de N pontos — pura); editar `studio.html` (indicador-herói + 3 sparklines: humor/viewers/saúde, dados de `/api/observability/history`); editar `main.js`/`studio.css`; criar `dashboard/tests/studio_health.test.js` e `studio_sparkline.test.js`.
+**Implementação:** herói consolida sinais → 1 estado com cor/halo; atenção roteada: se `critical` ou `pendingActions>0`, herói/aprovação sobem ao topo (View Transition). **Byte copiloto:** uma dica dispensável (`#byteHint`) sugerindo a próxima ação (ex.: chat esfriando → "solte um HYPE?"), nunca agindo sozinho.
+**Testes:** node — `operationalHealth` determinístico (todas as bandas) + `sparkline` (N pontos → path válido, vazio → seguro).
+**Critério de pronto:** [ ] estado operacional legível <1s; [ ] sparklines de 3 métricas; [ ] dica de copiloto opcional; [ ] transições nativas 60fps; [ ] suíte verde.
+**Validação ao vivo:** render headless mostra herói + sparklines; forçar `critical` via dados mostra reordenação.
+**Meta-reflexão:** *(preencher)*
+
+### Fase S4 — Identidade visual & acessibilidade (o "wow leve") · *fazer cedo (quick win)*
+**Objetivo:** bonito, distintivo, acessível — sem peso.
+**Arquivos:** criar `dashboard/styles/tokens-studio.css` (design tokens em `:root` e `[data-theme="dark"]`); editar `studio.css` (consumir tokens; Glassmorphism 2.0; tipografia mono nos dados; `@starting-style` em modais/toasts/banner; scroll-driven nos reveals; tudo dentro de `@media (prefers-reduced-motion: no-preference)`); editar `studio.html` (toggle de tema persistido em `localStorage["byte_studio_theme"]`, default `auto`); criar `dashboard/tests/studio_theme.test.js` e `dashboard/tests/studio_a11y.test.js` (usar `axe-core` se disponível; senão asserts estruturais: todos os modais têm foco-trap/`aria-modal`, grid com roving tabindex).
+**Implementação:** extrair cores hardcoded do `studio.css` para tokens; adicionar `[data-theme]`; foco-trap nos 4 modais; roving tabindex no grid de tiles; live-regions corretas; `prefers-reduced-motion` desliga **todo** movimento.
+**Testes:** `node --test dashboard/tests/studio_theme.test.js dashboard/tests/studio_a11y.test.js`.
+**Critério de pronto:** [ ] dark/claro/auto; [ ] 0 violações axe críticas (ou checklist a11y manual no doc); [ ] navegável 100% por teclado; [ ] `reduced-motion` zera animações; [ ] **nenhuma lib nova**; [ ] suíte verde.
+**Validação ao vivo:** render headless em dark + claro; tab-navigation manual documentada.
+**Meta-reflexão:** *(preencher)*
+
+### Fase S2 — Poder (command palette + atalhos + otimismo)
+**Objetivo:** velocidade pro avançado.
+**Arquivos:** criar `dashboard/features/studio/commands.js` (registry puro: `{id, label, keys, run}[]` + `filterCommands(query)`); criar `dashboard/features/studio/palette.js` (UI Cmd/Ctrl+K, abre com `@starting-style`+View Transition); editar `main.js` (atalhos P/F/H/A…; optimistic update com rollback no erro); criar `dashboard/tests/studio_commands.test.js`.
+**Testes:** node — `filterCommands` determinístico; reducer otimista aplica+reverte.
+**Critério de pronto:** [ ] toda ação por teclado; [ ] palette fuzzy; [ ] feedback instantâneo com rollback; [ ] suíte verde.
+**Validação ao vivo:** render headless abre palette; executar comando reflete na hora.
+**Meta-reflexão:** *(preencher)*
+
+### Fase S3 — Customização & layout
+**Objetivo:** o painel de cada um.
+**Arquivos:** criar `dashboard/features/studio/layout.js` (modelo de layout: ordem/visibilidade/densidade; `serialize/parse` com guarda de inválido; persiste em `localStorage["byte_studio_layout"]`); editar `studio.html`/`main.js` (drag-and-drop reordenar, fixar/esconder tile, densidade compacto/confortável, perfis ex. FPS/Just Chatting); criar `dashboard/tests/studio_layout.test.js`.
+**Testes:** node — round-trip de layout; layout corrompido → fallback ao default.
+**Critério de pronto:** [ ] layout sobrevive reload; [ ] reset disponível; [ ] perfis; [ ] suíte verde.
+**Meta-reflexão:** *(preencher)*
+
+### Fase S5 — Alcance (PWA + mobile + push)
+**Objetivo:** na palma da mão.
+**Arquivos:** criar `dashboard/studio.webmanifest`; criar `dashboard/sw.js` (service worker: cache do shell, offline); rotas p/ servir ambos (`bot/dashboard_server_routes.py`); editar `studio.html` (link manifest + registro do SW); Web Push opt-in p/ alerta crítico (churn crítico/fila travada); refinements mobile (bottom-sheet nos modais, alvos de toque ≥44px).
+**Testes:** node/estrutural — manifest válido (campos obrigatórios); SW registra e cacheia shell; push é opt-in.
+**Critério de pronto:** [ ] instalável (Lighthouse PWA); [ ] shell offline; [ ] alerta crítico chega; [ ] performance ≥90; [ ] suíte verde.
+**Meta-reflexão:** *(preencher)*
+
+### Fase S6 — Delight & onboarding
+**Objetivo:** primeira impressão e acabamento.
+**Arquivos:** editar `studio.html`/`main.js` (first-run guiado: cole token → conecte canal → abra overlays; estados vazios com propósito; **avatar Byte mini** no canto reagindo ao humor, reusando `dashboard/features/avatar/expression.js`); criar `dashboard/tests/studio_onboarding.test.js`.
+**Critério de pronto:** [ ] novo streamer entende em <60s; [ ] estados vazios úteis; [ ] avatar mini; [ ] suíte verde.
+**Meta-reflexão:** *(preencher)*
+
+---
+
+## 6. Decisões técnicas (fixas — não re-decidir)
+
+- **SSE, não WebSocket** (unidirecional basta; reconecta sozinho; passa no proxy HF). Ações continuam REST POST.
+- **Store mínimo no cliente:** objeto observável simples (sem framework) que renders assinam — habilita optimistic UI + sparklines sem spaghetti.
+- **Customização:** `localStorage` primeiro; sync via `channel-config` é opcional/futuro.
+- **Tokens de tema** em CSS custom properties + `[data-theme]`.
+
+## 7. Não-objetivos
+
+Não virar editor de cena/overlay (é OBS) · não reescrever em framework · não duplicar a dash ops `/`.
+
+## 8. Sequência recomendada
+
+**S0** (fundação tempo real) cedo → **S1 + S4-dark mode** (quick wins de "uau") → **S2 → S3 → S5 → S6**.
+
+## 9. Gate de Pronto (rodar ao fim de CADA fase — todos ✅ antes de avançar)
+
+1. [ ] Critério de pronto da fase 100% (checklist binário).
+2. [ ] `python -m pytest bot/tests/ -q` → verde, hermético, cobertura ≥80%.
+3. [ ] `node --test dashboard/tests/*.test.js` → verde (exceto a falha pré-existente conhecida).
+4. [ ] Invariantes (seção 2) respeitados — em especial: sem `innerHTML` dinâmico, sem lib nova, 60fps + reduced-motion, sem regressão.
+5. [ ] Evidência ao vivo registrada (screenshot headless e/ou curl) após deploy.
+6. [ ] Seção "Meta-reflexão" da fase preenchida (comportamento↔teste, regressão, Go/No-Go).
+7. [ ] 1 commit com mensagem `feat(studio): <fase> …` + Co-Authored-By.
+
+---
+
+### Fontes (deep research — junho 2026)
+[Tubik UI 2026](https://blog.tubikstudio.com/ui-design-trends-2026/) · [Tenet UI/UX 2026](https://www.wearetenet.com/blog/ui-ux-design-trends) · [Muzli dashboards 2026](https://muz.li/blog/best-dashboard-design-examples-inspirations-for-2026/) · [Minimalist web 2026](https://www.digitalsilk.com/digital-trends/minimalist-web-design-trends/) · [Glassmorphism 2.0](https://weblogtrips.com/technology/glassmorphism-2-0-css-techniques-2026/) · [Scroll-driven CSS 2026](https://dev.to/nickbenksim/creating-complex-scroll-driven-animations-with-pure-css-in-2026-17l) · [CSS micro-animations sem JS](https://medium.com/@alexdev82/css-micro-animations-in-2026-7-pure-css-techniques-that-replace-javascript-efd374b6e8a4)