feat(multiplayer): entrada após o início vira espectador — congela a lista da rodada (#64)

[caioross]

Contexto

A lista de participantes ficava aberta durante toda a partida: quem entrasse com a
corrida já em racing passava a compor a mesma rodada, e todos que já tinham terminado
ficavam presos esperando o retardatário terminar/desistir — quebrando o ritmo da sala
(issue #64). A regra passa a ser: uma partida é composta por quem estava presente
quando ela começou (o instante start_at); quem chega depois assiste e entra na próxima.

O que mudou

Arquivo	O quê
src/lib/room.ts	isSpectatorJoin(joinedAt, startMs, status) — puro/determinístico; LivePlayer.spectator
src/lib/useRoom.ts	spectator no roster; gate de fim ignora espectadores; expõe isSpectator
src/components/RoomView.tsx	filtra espectadores do roster de competidores; roteia para SpectatorView
src/components/SpectatorView.tsx	banner "Partida em andamento" + pista ao vivo + chat
src/lib/room.test.ts	6 casos de classificação

Determinismo (por que é seguro sem tocar o servidor): joinedAt (presence) e
start_at (linha da sala) são compartilhados por todos os clientes, então todos
classificam o mesmo jogador igual. Espectador = rodada em andamento (racing/finished)
e joinedAt > startMs. Em lobby/countdown ninguém é espectador — quem está antes do
start compõe a corrida.

O ponto de maior risco (e o que este PR conserta): o gate de fim de corrida era
players.every(p => p.finishedAt). Um retardatário sem finishedAt prendia a sala em
racing para sempre. Agora o líder finaliza quando todos os RACERS (!spectator)
terminaram; espectadores nunca entram no gate nem no results (não têm finishedAt, então
já eram naturalmente excluídos do ranking — nenhum caminho novo para o leaderboard).

Próxima rodada: quando o líder reinicia, start_at muda; o antigo espectador passa a ter
joinedAt < novo startMs → vira competidor automaticamente (AC atendido).

Como foi validado (resultado real)

pnpm install --frozen-lockfile   OK
pnpm typecheck                   OK
pnpm build                       OK
pnpm test                        OK — 40 testes (6 novos de isSpectatorJoin)
validate-metrics.mjs             OK — 37 passaram
validate-persistence.mjs         OK — 22 passaram
pnpm lint                        N/A — sem config ESLint no repo

Smoke test (next dev na worktree): /, /practice e /room/<code> renderizam sem erro
de console; o name-gate da sala aparece normal.

Limitação de verificação: a SpectatorView só aparece para um jogador que entra numa
sala com corrida em andamento — exige dois clientes simultâneos num canal Realtime real,
inviável de forma confiável headless nesta rodada. A classificação (o núcleo da mudança) está
coberta por unit tests determinísticos; a troca de view e o filtro do roster estão cobertos
por typecheck + build. Recomendo ao PR Doctor um teste manual com duas abas se quiser
confirmação visual.

Riscos

• Relógio: joinedAt é Date.now() do cliente que entra; startMs é Date.parse(start_at)
  do servidor. Skew de segundos só afeta quem entra na fronteira exata do start (durante o
  countdown de 4s) — no pior caso vira espectador e compete na rodada seguinte (degradação
  suave, nunca trava). Quem entra claramente no meio da corrida é sempre classificado certo.
• Área sagrada intacta: nada no caminho de digitação/textarea foi tocado.
• Player (types.ts) não mudou — espectadores são filtrados antes da conversão LivePlayer→Player.

Solicito quórum (HANDBOOK §7)

Closes #64

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
code-racer	Ready	Preview, Comment	Jul 26, 2026 8:13pm

[caioross]

Rebase nota: o PR #60 (issue #58, liveness) mergeou na main enquanto eu trabalhava, tocando os mesmos 3 arquivos. Rebasei em cima de origin/main e integrei a exclusão de espectadores na nova lógica de fim de corrida do #60 em vez de reescrevê-la:

• O gate agora é o maybeFinish do fix(multiplayer): corrida encerra por inatividade e por teto de duração — fim da sala presa em "racing" (#58) #60 (shouldFinishRace + tick do líder), mas filtrando espectadores antes de decidir: const racers = playersRef.current.filter(p => !p.spectator) alimenta tanto shouldFinishRace quanto toResults. Ou seja, os critérios de inatividade/teto de duração do fix(multiplayer): corrida encerra por inatividade e por teto de duração — fim da sala presa em "racing" (#58) #60 seguem valendo, só que sem contar quem entrou depois do start.
• Conflitos resolvidos em room.ts (blocos liveness + espectador coexistem), useRoom.ts (imports + maybeFinish) e room.test.ts (as duas suítes).
• Gate re-rodado sobre a base nova: typecheck · build · test 60 (liveness do fix(multiplayer): corrida encerra por inatividade e por teto de duração — fim da sala presa em "racing" (#58) #60 + 6 de isSpectatorJoin + existentes) · validate-metrics (37) · validate-persistence (22) — todos verdes. mergeable: MERGEABLE.

[caioross]

🔧 PR Doctor — CONFLITANTE, reparo por união antes de avaliar

A #80 (espectador ao entrar depois do início) está CONFLICTING (DIRTY) — toca room.ts/useRoom.ts/RoomView.tsx/room.test.ts, os mesmos arquivos mexidos por #60 (liveness) e #79 (kick moderation) já mergeados. Ação (§5.D): na branch auto/issue-64-spectator, git merge origin/main (união, nunca --force/rebase), resolver mantendo as três mudanças, rodar o gate (typecheck+build+test+validate-persistence) e push. Depois entra na fila de quórum §7.2 (estado multiplayer). Não mergeada nesta rodada por causa do conflito.

[caioross]

🔧 PR Doctor — ainda CONFLITANTE; reparo por união + re-quórum

A #80 (espectador ao entrar depois do início) segue CONFLICTING: toca room.ts/useRoom.ts/RoomView.tsx/room.test.ts, os mesmos arquivos reescritos por #60 (liveness), #79 (kick), #89 (votação) e #96 (writes honestos) — todos já na main.

Ação (§5.D): resetar a branch ao head da PR, git merge origin/main (união, nunca --force), resolver mantendo o fluxo de espectador junto de tudo que entrou (liveness/kick/vote/writes), rodar o gate completo e push. Depois quórum §7.2 (estado multiplayer: garantir que congelar a lista da rodada não conflita com o roster de presença nem com shouldFinishRace). Não mergeada nesta rodada — o conflito é grande e precisa de rebase cuidadoso + revisão adversarial fresca.

[caioross]

🏛️ Quórum §7.2 — reparada e APROVADA (2 lentes)

• Ofensiva — APROVA: o flag spectator é client-side mas nunca foi a fronteira do servidor; toResults filtra finishedAt && !abandoned independente do flag (espectador não tem editor, finishedAt fica null → some). O PR até melhora a resistência a DoS (filtra espectadores do maybeFinish). O buraco de finish sem gate é pré-existente (Anti-cheat: finish sem coerência temporal — leaderboard forjável em 1 request e corrida alheia encerrável #34), fora do escopo.
• Domínio — vetou e foi RESOLVIDO: congelar a lista reintroduzia sala presa — se todos os competidores saem e só resta um espectador, racers fica [] e shouldFinishRace([]) nunca encerra. Reparo (commit b186a87): o líder detecta racers.length === 0 em racing e encerra com results vazios (cai na tela de Results vazia da feat(dev): harness só-de-dev das telas pós-corrida (Results/pódio) com fixtures (#37) #63), com guarda de countdown. Re-verificação: RESOLVIDO, sem defeito novo (finishPostedRef evita dupla postagem; líder-espectador consegue resetar).

isSpectatorJoin puro/determinístico (usa start_at do servidor), coberto por teste. União com main (#55/#60/#79/#89/#96) resolvida (spectator + kick + vote coexistem). Gate: typecheck ✓, test 109 ✓, build ✓, validate-persistence 72/0 ✓. CI + Vercel verdes. Closes #64. Squash-merge.