Files
CenaForge/.claude/skills/cenaforge/references/panel.md
T
MateuusandClaude Opus 5.5 ed31d52df0 IA: Claude, Codex e Gemini com login, chave de API e IA reserva; Configurações em subpáginas
- Configurações → IA (/settings/ai): um cartão por IA para instalar/atualizar a CLI pelo painel, ligar,
  entrar com a conta (OAuth pela própria CLI, num terminal) ou colar a chave de API, e testar.
  Chaves cifradas com a DPAPI do Windows em data/ai/vault.bin; só vão para a CLI no ambiente da chamada.
- Gemini CLI como terceiro agente do painel (stream-json, edição automática, shell só o liberado).
- IA reserva: execução que cai por indisponibilidade (cota, 429, login, chave, rede) pausa a IA e recomeça
  a mesma tarefa na próxima pronta da ordem; migração v10 (agent_runs.fallback_of).
- Configurações viraram subpáginas (IA, Publicação, Apps das redes, Navegador, Sobre os modos), também no
  menu lateral; links antigos apontam para a subpágina certa.
- Contrato com o Clipador em doc/ia.md; skill do CenaForge atualizada até a 1.51.0.

O login gratuito do Gemini CLI para conta pessoal foi encerrado pelo Google (IneligibleTierError): para
conta pessoal, use a chave do AI Studio.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 01:51:12 -03:00

560 lines
52 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Painel: confirmação e aviso, formatos de história, leitor de roteiro, montagem documental (fotos do Commons, cenas 2D/3D e biblioteca, um clique), vertentes, votação, agentes (e mensagem durante a execução), exclusão, canais de publicação e dashboard
Fonte: código em `panel/src/lib/` e `panel/README.md`. O painel é do usuário: ele roda
`pnpm panel`; não inicie, não encerre, nada de `next build` com o dev ligado.
## Confirmação e aviso (`components/confirm-dialog.tsx`)
**Regra:** nada de `confirm()`/`alert()` nativos no painel (hoje não sobra nenhum em `panel/src/`). Use:
| Função | Uso |
|---|---|
| `askConfirm({ title, message?, confirmLabel?, cancelLabel?, tone? })` | `Promise<boolean>`; `false` em Cancelar, Esc ou clique no fundo. O handler que pergunta vira `async`: `if (!(await askConfirm({...}))) return;` |
| `showAlert({ title, message?, okLabel?, tone? })` | `Promise<void>`; um botão só (padrão "Entendi"), `role="alertdialog"` |
| `confirmSubmit(options, when?)` | `onSubmit` de `<form action={serverAction}>`: segura o envio, pergunta e, se confirmou, `form.requestSubmit(submitter)` com `data-confirmed="1"` (o 2º submit passa sem perguntar). `when()` decide se precisa perguntar. Usado em `delete-story-button.tsx` e `forms.tsx` |
- `tone: "danger"` → botão de confirmar vermelho e foco inicial em **Cancelar** (Enter não apaga por engano).
- `<ConfirmHost />` montado **uma vez** em `app/layout.tsx`; pedidos entram numa fila (um por vez; antes do host
montar, esperam num backlog). É `<dialog>` nativo com `showModal()`, então abre por cima de outros modais nativos
(ex.: `CutSettingsDialog` de `clipper-cut-settings.tsx`). Não monte um segundo host.
- `Button` (`components/ui.tsx`) tipa as props como `ComponentProps<"button">` e aceita `ref` (React 19).
## Banco (`data/cenaforge.db`, esquema v10)
- Migração em `panel/src/lib/db.ts` (lista `MIGRATIONS`). Banco com dados → cópia em `data/backups/`
antes de migrar (`cenaforge-v<atual>-<data>.db`). `foreign_keys = OFF` fora da transação e `PRAGMA
foreign_key_check` antes do `COMMIT` de cada versão.
- v3: `account_channels` (conta ↔ canal de live do Clipador; `status` `active`/`ended`). O canal
vive em `data/clipper/clipper.db`, então não há chave estrangeira para ele.
- v9: `accounts.language` (idioma e público do canal de publicação; padrão `pt-BR`; opções em `ACCOUNT_LANGUAGES` de
`panel/src/lib/languages.ts`). A v8 (última leitura dos números das redes) não está descrita aqui: ver publishing.md.
- v4: reconstrói `stories` (SQLite não altera CHECK) para `kind` aceitar `'documentary'`; mesmas
colunas e ids.
- v5: publicação real — `publish_jobs`, `app_settings`, `clip_auto_approvals`; `account_networks` e `publications`
reconstruídas (sem `mock`; `publications.clip_id`/`job_id`); colunas novas em `accounts` (`approval_mode`, `timing`,
`ai_label`, `auto_since`) e `episodes` (`approved_at`, `approved_render_id`, `publish_title`, `publish_caption`).
Detalhe em [publishing.md](publishing.md) e `doc/publicacao/PLANO.md` §4.
- v6: reconstrói `publish_jobs` (ids preservados) com `schedule_source` (`auto`/`manual`/`now`) e `cancel_reason`
`unlinked`. Banco real em v6 (`PRAGMA user_version`, conferido em 17/11/2026, antes da v7).
- v7: `publish_jobs.origin` (`link`/`manual`, padrão `link`): job criado pelo botão "Publicar" do corte. Ver publishing.md.
- v10: `agent_runs.fallback_of` (execução que continuou outra que caiu por indisponibilidade; IA reserva — [ai.md](ai.md)).
- API: toda rota `/api/**` passa por `panel/src/proxy.ts` (Host local; escrita exige `Origin` do painel) e corpo por
`readJson` (415 sem `Content-Type: application/json`) — gotchas, item 125.
- A conexão fica em `globalThis.__cenaforgeDb`; a marca de módulo `checkedThisModule` faz a 1ª chamada de `db()` depois
de recarregar o código rodar `migrate()` no banco aberto (backup em `data/backups/`) → esquema novo entra na 1ª
requisição, sem reiniciar. Só se o `db.ts` não foi recarregado é preciso reiniciar o `pnpm panel` (gotchas, itens 51 e 138).
- Testes do painel: `pnpm --filter cenaforge-panel test:panel` (`panel/src/lib/*.test.ts`, node:test via tsx). Teste que
importa algo que abre o banco precisa de `CENAFORGE_ROOT` numa pasta temporária (gotchas, item 99).
## Formatos de história (`kind`)
Lista em `STORY_FORMATS` (`components/story-formats.ts`, rótulo curto `storyFormatLabel`) + tipo
`StoryKind`/`STORY_KINDS` (`lib/types.ts`). Formato novo também exige migração do CHECK em `db.ts`.
| `kind` | O que é | Arquivos |
|---|---|---|
| `interactive` | episódios ~12 s terminando em votação A–D (2–4 vertentes) | `biblia.md`, `<file_key>.md`, `.choices.json` |
| `linear` | episódios de ficção em sequência, sem votação (`branch_count` = 1) | `biblia.md`, `epNN.md` |
| `documentary` | **vídeo único** vertical sobre tema real, nomes reais, fato com fonte, sem votação | `biblia.md` = ficha de pauta; `ep01.md` = roteiro (formatos em `doc/roteiro/documental.md`) |
- Regras de texto e formato dos arquivos: **`doc/roteiro/`**, fonte única para Claude e Codex.
`comum.md` (idioma, onde escrever, estrutura do vídeo curto, limites do overlay, produção, retorno;
tabela formato → guia) + `ficcao.md` (interativa/linear: sem cidade, marca ou pessoa real, A/B no fim,
formato de `biblia.md` e `ep<NN>.md`) ou `documental.md` (nomes reais, fato com fonte, mito × fato,
45–90 s, ficha de pauta e roteiro). 1ª linha da `biblia.md`: `Formato: interativa | linear | documental`.
- Aba Fluxo: tudo que não é `interactive` usa layout em linha (`story-flow.tsx`).
- Termos na interface: `unitTerms(kind)` (`story-formats.ts`) → `{one, One, many, Many, code(n)}`. Série =
"episódio"/`ep01`; documental = "vídeo" (`code(1)` = "vídeo", `code(n)` = "vídeo n"). Usado no console do
agente (campo "Episódio" vira "Vídeo"; `StoryOption` tem `kind`), no cartão da página inicial, na página da
história (aba, contagem, criar) e na do episódio (breadcrumb, eyebrow "Vídeo documental", metadata). Texto
novo que fale da unidade usa `unitTerms`, não "episódio" fixo. O **arquivo** continua `episodeCode` (`ep01.md`).
- `createStoryFromTextAction`: no documental o episódio nasce sem título ("Abertura" só em série).
## Leitor de roteiro (`lib/script-doc.ts` + `components/script-reader.tsx`)
- `parseScript(md)` (puro, sem servidor) → título, metadados, `facts` (pares `Chave: valor` separados por " · "),
seções com `role` deduzido do título (`hook`, `shots`, `sources`, `needs`, `cover`, `overlay`, `summary`, `ending`,
`consequences`, `other`), `shots`, `targetSeconds`, `narrationWords`. Trechos = a **primeira tabela cuja 1ª coluna
é "t (s)"/tempo**; as outras colunas são achadas pelo cabeçalho (imagem/b-roll, texto na tela, narração/diálogo).
Mudar o cabeçalho em `doc/roteiro/` (`documental.md`, `ficcao.md`) pode quebrar a leitura.
- Tempo falado = palavras / `WORDS_PER_SECOND` (2,5). Alertas: narração total > 1,1× a duração alvo; trecho com
narração > 1,15× a duração dele ("mais longa que o trecho").
- `ScriptReader` não usa HTML cru: markdown em linha próprio (negrito, itálico, código, links/URLs com
`target="_blank" rel="noopener noreferrer"`). Mostra resumo, "Copiar narração" (`components/copy-button.tsx`),
"Gerar áudio em Vozes" (só um link para `/voices`; não leva o texto), gancho, régua do vídeo com âncoras
`#trecho-N`, cartão por trecho, texto de capa com contagem de caracteres, fontes com domínio, necessidades de
produção e o .md original recolhido.
- Usado em `app/stories/[storyId]/episodes/[number]/page.tsx` e na página só de leitura `.../[number]/roteiro/page.tsx`.
Página da história: botão "Ler roteiro" → último episódio com roteiro.
- Documental na página do episódio: roteiro primeiro (`order-first`), título do roteiro, eyebrow "Vídeo documental";
sem "Montar cena" nem render da rua 3D — no lugar, o passo a passo "Como este vídeo é feito" e o card "Montagem do
vídeo" (seção abaixo).
## Montagem documental
Card "Montagem do vídeo" (`components/montage-editor.tsx`) na página do vídeo documental. Regras de texto em
`doc/roteiro/comum.md` e `documental.md` (seção "Como o vídeo é montado"). **Decisão do dono (17/11/2026): a geração
é automática, num clique; o admin só revisa e troca.**
- **Um trecho = uma linha da tabela "t (s)"** do roteiro (`parseScript`). Cada trecho tem:
- **áudio próprio**, um parágrafo por vez (decisão do dono: áudio longo deixa a voz estranha), gerado do **texto
falado**: editável, nasce de `toSpokenText(narração)` (`lib/speech-text.ts`: números até bilhões, decimais
"0,0055" → "zero vírgula zero zero cinquenta e cinco", milhar "1.500", km, m², ha, cm, kg, %, "por m²"). Texto na
tela que é pergunta e que a narração não repete entra antes da fala ("Uma cobra por metro quadrado? Não. ...");
- **visual** (`VISUAL_KINDS` em `lib/montage.ts`; rótulo da UI entre parênteses): `image` (Foto), `godot2d`
(Animação 2D), `godot3d` (Cena 3D da biblioteca), `cartoon` (Cartoon, Remotion), `video` (Clipe: envio ou render Godot já feito), `card`
(Cartela, sem arquivo). Pode misturar. `ShotVisual`: `scene` + `sceneKey` (Godot), `search {queries, pick}` (foto
da internet), `auto` (escolhido pelo automático; trocar à mão grava `auto: false`), `inset` (cartão de foto por
cima do visual; na UI, `InsetCard`: "Outra foto", "Tirar", "Pôr foto da internet").
- **Estilo do vídeo** (`style` no `.montage.json`, `PATCH {style}`; seletor "Estilo do vídeo" no topo): `"mixed"`
(padrão: foto, 2D e 3D), `"3d"` ("Tudo em 3D": todo trecho vira cena 3D da biblioteca, fotos só em cartão) ou
`"cartoon"` ("Cartoon: desenho 2D chapado": todo trecho vira cena Remotion; ver "Estilo Cartoon").
Regras de roteiro para isso: "Vídeo todo em 3D" em `doc/roteiro/documental.md` (coluna Imagem = tomada 3D,
`[foto: termos]`, cenas 3D que faltam em "Necessidades de produção").
- **Cartões de informação em sequência:** texto na tela `A; depois: B; depois: C` mostra as partes uma após a outra,
dividindo o tempo do trecho.
- Topo do card: **"Gerar vídeo automático"** (etapa do `job` + Cancelar), **"Refazer tudo do zero"** (`replan`) e
modo manual: voz pt-BR, velocidade 0,7–1,3 na UI (o servidor aceita 0,5–2), legenda, "Gerar N áudios", "Só montar".
- Por trecho: estilos em grade (3 colunas; 5 a partir de `sm`), **"Gerar de novo"** (ou "Buscar na internet" na foto
sem arquivo) e `SceneEditor`: 2D = modelo (`DOC2D_TEMPLATES`) + campos; 3D = seletor da biblioteca + formulário
gerado do manifesto + link "Peça uma nova ao agente" (`/agent?kind=godot&story=…&prompt=…`). "Prévia da cena" =
`renderShotScene` ← `POST .../montage/scene`.
- Envio de visual (multipart): **licença opcional** (padrão "não informada", decisão do dono), crédito e link
opcionais; vira asset da história (`AssetKind` `image`/`video`). Também dá para escolher da biblioteca/assets da
história ou dos renders Godot com `status = 'success'`.
- Estado: `stories/<id>/<file_key>.montage.json` (`voiceId`, `speed`, `captions`; por índice `spoken`, `visual`,
`audio{file, durationMs, key}`). Áudio: `stories/<id>/audio/<file_key>-NN.ogg`. Config de cada cena Godot:
`stories/<id>/godot/<file_key>-tNN.json`. `audioKey` = hash de voz + velocidade + texto falado; `sceneKey` = hash
de `kind` + modelo + params + duração (fala + pausa). Mudou → aparece desatualizado.
### Plano do trecho (`lib/montage-godot.ts`, sem banco, sem IA)
- `scriptEntities(md)`: nomes científicos (itálico binomial, `*Bothrops insularis*`) e lugares de `MAP_PLACES` citados.
- `planShot(shot, {species, places, library}, variant)`, nesta ordem:
1. `planScene` deu `map` ou `counter` → cena 2D;
2. 1ª oração da coluna Imagem cita animal ou objeto real (placa, pesquisador, navio, foto…) → foto; buscas = nome
científico, "Farol <ilha>" (se fala de farol), a ilha; nada achado → cena 2D de reserva;
3. `matchLibrary(coluna Imagem)` → cena 3D (`paramsFor` escolhe cada `select` pelas keywords das opções);
4. título 2D.
- `planShot3d(shot, ctx, index)` (estilo `"3d"`): cena `doc3d` por `matchLibrary` na coluna Imagem, depois na Imagem +
narração, senão a primeira da biblioteca; `params` por `paramsFor` + `variant = índice do trecho`. Cartão de foto
(`insetQueries`) só com `[foto: termos]` na coluna Imagem ou animal real (`ANIMAL`) na 1ª oração — aí busca os nomes
científicos do roteiro; barco, navio e personagem ficam na cena 3D, sem cartão. Biblioteca 3D vazia → erro pedindo
cena ao agente.
- `planScene(shot)`: ≥ 2 lugares conhecidos, ou 1 lugar + "mapa/litoral/km" → `map` com rota cidade → ilha e rótulo
"N km" (tirado do texto); número no texto na tela → `counter` (kicker = texto antes do número; rótulo completado
pela narração, ex.: "jararacas por hectare"); resto → `title`. "São Paulo" só vira marcador se o texto disser
cidade/capital ("litoral de São Paulo" é o estado).
- `MAP_PLACES` **tem de ficar igual** a `PRESETS["litoral-sp"].places` de `godot/scripts/doc/doc2d_canvas.gd` (a
Godot resolve lat/lon pelo nome).
- `renderGodotScene` grava o JSON (`kind` `doc2d`/`doc3d`, 1080×1920, 30 fps, duração da fala + pausa) e chama
`scripts/cli.ts render --config <json> --profile final` pelo `node_modules/tsx/dist/cli.mjs` (sem shell); o MP4 é
lido da linha `MP4: ...` da saída.
- Modelos 2D (`variant` muda o visual): `title` (3 layouts por `variant % 3` — centro, editorial à esquerda com
barra, embaixo com sublinhado; destaque brasa/ciano/violeta), `counter` (conta em pt-BR 1.500 / 0,0055 com anel que
fecha; `grid` opcional), `map` (voo: começa aberto, zoom 0,45 em `variant` par ou 0,62 em ímpar, desce até a rota em
1,6 s, a linha começa em 1,5 s e o destino pulsa; terra estendida 8° além dos limites; km pela haversine se faltar o
rótulo; "Mapa ilustrativo" no rodapé — a costa é aproximada).
### Fotos da internet (`lib/image-search.ts`)
- `searchCommons(q)`: API do Wikimedia Commons, sem chave, User-Agent genérico; `filetype:bitmap`, menor lado ≥ 900
px, descarta títulos com mapa/diagrama/logo/brasão/bandeira/gráfico; URL em 1600 px. `searchFirst(queries)` tenta
as buscas em ordem; `downloadImage` baixa.
- `applyInternetImage(ep, shot, queries, startPick, used, "main" | "inset")` (`lib/montage.ts`) pula imagem já usada
noutro trecho (`sourceUrl`; fotos principais e cartões juntos) e cria o asset `image` com crédito (autor), licença e
origem (página do Commons), que vão para a cartela de créditos. `"inset"` grava no cartão do trecho.
- Medido (17/11/2026, informado): "Bothrops insularis" → fotos reais da espécie (Butantan, Otavio Marques); "Ilha da
Queimada Grande" → farol e navio da Marinha; termo genérico ("aves migratórias") → lixo. Por isso as buscas usam
nomes do roteiro, nunca descrições genéricas.
### Biblioteca de cenas 3D (`godot/library/`)
- Cena = `godot/library/<id>/template.gd` (`extends Node3D`: `setup(cfg, viewport_size)`, `apply(t)`,
`state_signature()`) + `manifest.json` (`id`, `kind: "doc3d"`, `label`, `description`, `keywords`, `params` com
`type` `select`|`bool`|`number`|`text`, `default` e `options[{value, label, keywords}]`). Guia para agentes:
`doc/godot/cenas.md`.
- O painel lê sem banco (`lib/scene-library.ts`): `listLibrary()`, `matchLibrary(texto, lib)` (mais keywords
achadas), `paramsFor(cena, texto)`. Cena nova aparece sozinha no seletor, no formulário e na escolha automática.
- `island` ("Ilha costeira"): terreno FastNoiseLite com sementes fixas, 5.200 árvores em MultiMesh,
rochas, farol listrado com lanterna pulsando; mar por shader com `uniform scene_time` (determinístico), turquesa
perto da costa, plano de 16 km (horizonte sem emenda); ProceduralSky, ACES, névoa leve. Params `shot`
`orbit`|`approach`|`lighthouse`|`lowpass`, `time` `day`|`sunset`|`night` (céu escuro, lua azulada, farol forte),
`lighthouse` (bool); `variant` muda **só a câmera** (ângulo e sentido). Como cenário de outra cena: `embedded: true`
(sem câmera própria), `environment: false` (sem céu e luz), `sea_detail: true` (malha fina do mar perto da câmera);
métodos `height_at` (ruído) / `ground_at` (malha desenhada: apoio de pés e pedras) / `ground_normal`,
`sea_height(x, z, t)`, `set_sea_state(escala)`, `set_sea_focus(x, z)`, `rock_list()`, `lighthouse_position()`.
- `castaways` ("Náufragos no costão", caso real da Ilha das Cobras, 2019): `moment`
`arrival`|`sinking`|`swimming`|`waiting`|`rescue`|`boarding`|`departure` (keywords tiradas da coluna Imagem do
roteiro), `camera` `medium`|`close`|`wide`, `variant`. Peças na pasta: `shore.gd` (estende a ilha com laje de
costão), `actor.gd` (estende `person.gd`), `cast.gd` (elenco e barcos), `sky.gd` (céu por hora, mistura noite → dia),
`verify.gd` (determinismo e apoio: `Godot --headless --path godot --script res://library/castaways/verify.gd` →
`CASTAWAYS_OK 84 estados`). Feita pelo agente do painel: Claude (#7) e Codex (#8), cada um parou no limite de uso.
- **Kits** `godot/kits/` (não são cenas; o painel não lista): `person.gd` — pessoa low-poly com juntas `hips`, `spine`,
`chest`, `neck`, `head`, `shoulder|elbow|hip|knee_l/r`; `build({shirt, pants, skin, hair, shoes, vest, height,
sleeveless, shorts})`, `pose(action, t)` (`idle`, `walk`, `run`, `swim`, `sit`, `wave`, `kneel`, `lie`, `exhausted`),
`blend(a, b, t, k)`. `boat.gd` — lancha/pesqueiro ~8 m (casco SurfaceTool, cabine, mastro, luzes de navegação):
`build({hull, stripe, cabin, lights})`, `float_on(t, intensidade)`, `sink(0..1)`, `deck()` (convés). Uso, cena
dentro de outra e `.glb` por `GLTFDocument` em tempo de execução: `doc/godot/cenas.md`.
- Cena nova pelo painel: tarefa "Cena no Godot" do agente (seção "Agentes e modelos").
### Estilo Cartoon (`cartoon/`, Remotion, sem Godot)
Cada trecho vira um MP4 de desenho 2D montado por peças a partir do texto; personagens vêm da biblioteca
(`assets/characters/`). Contrato, peças, render, plano, personagens e integração em `montage.ts`: [cartoon.md](cartoon.md).
### Gerar o MP4 (`startMontageRender(id, { auto, replan })`)
- `auto: false` ("Só montar"): exige áudio atualizado e visual em todos os trechos (menos cartela); as cenas Godot
(2D e 3D) desatualizadas são renderizadas também neste modo.
- `auto: true` ("Gerar vídeo automático"): planeja com `planShot` os trechos sem visual (com `replan: true`, "Refazer
tudo do zero", também os `auto` e as cenas Godot antigas sem a marca; o que o admin escolheu fica); sem voz usa a
pt-BR padrão do serviço (`getStatus`); gera os áudios que faltam; renderiza as cenas Godot com `sceneKey` velha; monta.
- `regenerateShot(id, index, target)` (`POST .../montage/regenerate {index, target}`): `"visual"` (padrão) — cena Godot
→ `variant + 1` e re-render; foto da internet → próxima da busca (sem repetir as dos outros trechos); foto enviada →
busca; cartela e clipe → erro. `"inset"` → outra foto no cartão (busca do cartão, do `planShot3d` ou nomes
científicos; sem termos → pede `[foto: termos]`). `"remove-inset"` → tira o cartão.
- Uma montagem por vez. Progresso em memória: `montageJob(episodeId)` → `job: { renderId, progress }` no GET (não
sobrevive a reiniciar o painel). Grava em `renders` com `profile = 'documentary'`; saída
`output/documentary/<story>-<file_key>-<stamp>/<story>-<file_key>.mp4`, log `data/logs/renders/<id>.log`.
- FFmpeg em `lib/montage-ffmpeg.ts` (**sem banco**, testável sozinho: gotchas, item 99): `buildSegment`,
`buildCredits`, `concatSegments`. 1080×1920, 30 fps, H.264 CRF 20 + AAC 48 kHz estéreo.
- Foto horizontal (aspecto > 0,8): fundo = a própria foto desfocada (`boxblur=32`, brilho −0,12), foto a 118% da
largura (até 62% da altura), zoom de 8%, um pouco acima do meio. Foto vertical: cobre a tela com `zoompan`. Pares
aproximam, ímpares afastam. A entrada de áudio varia com o visual (`audioInput`). Vídeo: `-stream_loop -1` + crop.
- Texto na tela (y = 13%; na cartela, centro) e legenda (y = 74%) por `drawtext` com `textfile=` e
`expansion=none`; grafo em `-filter_complex_script`; cwd = pasta de saída (arquivos relativos). **`godot2d` não
recebe o texto na tela** (a cena já mostra); `godot3d` recebe; a legenda continua em todos. Texto na tela com
mais de 26 caracteres usa fonte 54 (senão 66); `; depois:` divide em partes sequenciais.
- Cartão de foto (`plan.inset`): foto a 62% da largura com borda branca de 12 px, topo a 21% da altura; entra em
0,3 s (fade de 0,35 s subindo 50 px) e sai 0,4 s antes do fim; crédito "Foto: autor" embaixo.
- Legenda = narração escrita em pedaços de até 30 caracteres, tempo proporcional; pedaço < 12 caracteres junta
ao anterior.
- Duração do trecho = fala real + `PAD_S` 0,35 s (último + `LAST_PAD_S` 0,9 s), não o tempo da tabela (gotchas,
item 102). Cartela final de 3,5 s (`CREDITS_S`) com créditos das imagens e domínios das fontes (só se houver).
Junção com `-c copy`.
- Rotas: `GET|PATCH /api/episodes/[id]/montage` (GET traz também `templates` e `job`), `POST .../montage/audio`
(`{index}`), `POST .../montage/scene` (`{index}`), `POST .../montage/regenerate` (`{index, target?}`),
`POST .../montage/upload` (multipart), `POST .../montage/render` (`{auto, replan}`) e
`DELETE .../montage/render?render=<id>`. `/api/files` serve também `.webm`, `.mov` e `.mkv`.
- **Provado de ponta a ponta (17/11/2026, "Tudo em 3D"):** agente `story` (Codex, #6) pesquisou e escreveu
`stories/naufragos-na-ilha-das-cobras/ep01.md` com fontes; agentes `godot` #7 (Claude) e #8 (Codex) fizeram
`castaways`; "Refazer tudo do zero" planejou 11 trechos (1–9 `castaways` nos momentos certos, 10–11 `island` orbit
com cartão da jararaca, fotos do Commons diferentes). MP4 em `output/documentary/naufragos-na-ilha-das-cobras-ep01-*/`:
101,7 s, 1080×1920, h264 + aac (ffprobe). Cenas finais 1080×1920 de 2,8–12,3 s em 9,8–89,7 s cada (`report.json`);
total ~9 min (informado). Quadros conferidos pelo agente que montou (não refeito aqui).
## Agentes e modelos (`lib/agents.ts`, `lib/prompts.ts`)
- `buildPrompt({ kind, provider, ... })` inclui `writingRules(provider, story.kind)` (guias em
`GUIDE_COMMON`/`GUIDE_BY_KIND`): no **Claude** manda delegar ao subagente `cenaforge-story-writer`
informando o formato (o subagente é uma casca que lê `doc/roteiro/`; sem WebSearch, fato sem fonte fica
"a confirmar"); no **Codex** manda ler os guias e escrever sozinho, sem usar `.claude/agents/` (mesma
regra no `AGENTS.md`).
- **Três provedores** (`claude`, `codex`, `gemini`), configurados em **Configurações → IA** (`/settings/ai`: ligar/desligar,
conta ou chave de API, ordem da reserva, instalar, entrar, testar). **IA reserva:** agente que termina com erro de
indisponibilidade é pausado e a mesma tarefa recomeça na próxima IA pronta (`agent_runs.fallback_of`; o console segue
o `followUpRunId` também nesse caso; vertentes religadas à nova execução). Contrato, API e armadilhas em
[ai.md](ai.md). Configurações são subpáginas `/settings/{ai,publishing,apps,browser,modes}` (`/settings` → IA;
`SETTINGS_SECTIONS` em `settings-shell.tsx`, também no menu lateral); link antigo `/settings?tab=apps` não existe mais.
- Lista de modelos = `models()` (não há mais constante fixa; o Gemini usa `geminiModels()` de `lib/ai.ts`):
- Codex: lê `models_cache.json` de `$CODEX_HOME` (padrão `~/.codex`), que a CLI do Codex atualiza
sozinha; filtra `visibility === "list"`, ordena por `priority`. Primeira opção "Padrão da CLI (…)"
= `model = "..."` do `config.toml`. O id vai em `codex exec -m <slug>`. Em 17/11/2026: 8 modelos
(gpt-6.1-sol, gpt-6-astra, gpt-6.1-terra, gpt-6-sol, gpt-6-luna, gpt-5.6-sol/terra/luna).
- Claude: `claude-fable-5-2`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-haiku-5-5` (via
`claude --model`); apelidos `opus`/`sonnet`/`haiku` ainda aceitos ao retomar execuções antigas.
- Padrão: `DEFAULT_MODEL` só vale no Claude (`scene` e `branches` = `claude-sonnet-5-5`; demais = padrão
da CLI); no Codex, sempre o do `config.toml`. Provedor preferido por tarefa: `PREFERRED_PROVIDER`
(story/script/branches = Codex; `godot` = Claude).
- Tarefa `godot` ("Cena no Godot", `AgentKind` em `lib/types.ts`): o prompt (`prompts.ts`) manda seguir
`doc/godot/cenas.md`, reaproveitar a biblioteca (`godot/library/island/` de referência), renderizar e olhar os
quadros, e não mexer em `godot/scripts/`, `scripts/` nem `panel/`. O console (`/agent`) aceita `?prompt=` como
pedido inicial (link "Peça uma nova ao agente" do `SceneEditor`).
- "Nova história com IA" (`components/story-composer.tsx`) tem seletor de modelo (campo `model`, lido
em `createStoryFromTextAction`, `app/actions.ts`). Por script: `POST /api/stories {text, title?, kind?, provider?,
model?}` (`app/api/stories/route.ts`; `kind` padrão `documentary`, texto 20–20.000 caracteres) cria a história + ep01
e dispara o agente `story` → `{storyId, episodeId, runId}` (cabeçalho `Origin`: gotchas, item 125).
- O agente roda dentro do processo do painel: reiniciar o `pnpm panel` o mata (gotchas, item 131). Limite de uso no
meio da tarefa: com a reserva ligada o painel recomeça sozinho na próxima IA (item 132 vale só com a reserva
desligada ou sem outra IA pronta: continue à mão no outro provedor com o contexto).
- Prompt do Codex manda ler texto no PowerShell com `Get-Content -Raw -Encoding UTF8` (gotchas, item 98).
### Mensagem com o agente rodando
- Console (`components/agent-console.tsx`): durante a execução a caixa de pedido fica liberada com dois botões —
**"Corrigir agora"** (também Ctrl+Enter: interrompe e retoma a mesma sessão com a correção) e **"Enviar ao
terminar"** (fila; envia quando o agente fechar). Uma mensagem por vez: a nova substitui a da fila.
- Rota `POST /api/agent/runs/[id]/messages` com `{text, mode: "now"|"queue"}` → `sendFollowUp(id, text, mode)`.
`ActiveRun` tem `emit`, `followUp` e `progressed` (vira `true` no 1º evento que não seja `system`, `stderr`
nem `error`). "now" exige `session_id` **e** `progressed` (senão recusa: gotchas, item 97); marca a execução
`cancelled` (error "interrompida para correção") e chama `killTree`.
- No `close`, havendo `followUp`, `startRun({..., resumeRunId: id})` roda **antes** de avisar os ouvintes, então o
"end" do SSE já leva `followUpRunId` (`followUpRunOf(id)`, `resume_of = id`) e o console troca para a
continuação, mostrando o texto do usuário como pedido. Falhou a continuação (executor ocupado, sem
`session_id`) → evento de erro pedindo para reenviar.
- A rota de events só manda `followUpRunId` no fim **ao vivo** (`finish(true)`): abrir uma execução antiga do
histórico não pula para a continuação.
## História interativa = árvore de vertentes
| Conceito | Onde |
|---|---|
| Vertentes por episódio | `stories.branch_count` (1–4; linear = 1; interativa ≥ 2, escolhido na criação, campo `branchCount` de `createStory` em `stories.ts`) |
| Arquivos do episódio | `file_key` (`ep01`, `ep02-b`) → `stories/<id>/<file_key>.md`, `stories/<id>/<file_key>.choices.json`, `config/<id>-<file_key>.json` |
| Estado do episódio | `status` `main` / `candidate` / `discarded`; `branch_label`; `branches_status` `none`/`queued`/`running`/`ready`/`error` |
| Votação A–D | `decisions.ts`: `parseVote(text, letras)`, `tally`, `leader()`, `closeDecision`; votos em `votes_json` |
| Gerar vertentes | `branches.ts`: `prepareBranches` cria as candidatas e **uma** execução de agente (tarefa `branches`; Codex preferido — modelo em "Agentes e modelos") que escreve roteiro, cena e `.choices.json` de cada vertente |
| Fila | um agente por vez; o próximo `queued` é puxado em `onAgentRunClosed` |
| Fechar votação | `closeDecision`: vencedora vira `main`, irmãs `discarded`, e o próximo nível é preparado sozinho (`prepareBranches(..., { auto: true })`) |
| Árvore na tela | `flow.ts` (`storyFlow`, layout em árvore próprio) + `components/story-flow.tsx` (`@xyflow/react` 13.0.1); aba Fluxo da história |
Regra: só o **próximo nível** é gerado — nunca a árvore inteira de uma vez.
Limitação: o overlay da Godot só tem `choiceA`/`choiceB` (`scene_config.gd`); C/D existem só no
`.choices.json` e no painel. Cores das opções: `CHOICE_STYLE` em `components/ui.tsx`, tokens
`--color-option-c`/`--color-option-d` em `app/globals.css`.
## Canais de publicação e dashboard
- Canal de publicação = tabela `accounts` (no código continua "account"; na UI, "Canal de publicação", rota
`/accounts`, `components/account-manager.tsx`): várias histórias ativas por canal, uma história em vários canais.
Redes conectadas de verdade (API oficial ou sessão logada) — tudo de publicação em [publishing.md](publishing.md).
- Dashboard (`metrics.ts`, `/dashboard`, primeiro item do menu; `metrics-view.tsx`,
`dashboard-controls.tsx`): totais, por rede/conta/história/episódio, melhores e piores.
Métricas continuam **simuladas** (`simulated = 1`; `simulateMetrics` / `clearSimulated`); publicação real grava
`publications` com `simulated = 0`. Não apresente números simulados como reais.
- Fontes do Clipador (no código `channels`): card "Fontes de corte" em `account-manager.tsx`, rotas
`POST /api/accounts/<id>/channels` (ligar) e `DELETE /api/accounts/<id>/channels/<channelId>` (encerrar). Cortes
das fontes ligadas entram na fila de publicação do canal. Veja [clipper.md](clipper.md).
- Página da história: abas Episódios | Fluxo | Contas.
## Excluir história
- `deleteStory(id)` (`lib/stories.ts`) ← `deleteStoryAction` (`app/actions.ts`, campo `storyId`, redireciona
para "/") ← `components/delete-story-button.tsx` (`confirmSubmit` com `tone: "danger"`; erro no modo `compact`
por `showAlert`). Aparece como ícone (`compact`) no canto
inferior direito do cartão em "Biblioteca · Em produção" (`app/page.tsx`, **fora** do `<Link>`: botão dentro de
`<a>` é inválido) e como "Excluir" no cabeçalho de `app/stories/[storyId]/page.tsx`.
- Recusa se houver `agent_runs` `running` da história ou `renders` `running` de algum episódio dela.
- **Arquivos primeiro, banco depois; nada é apagado de vez:** `stories/<id>/` (com `.choices.json` e
`assets/`) → `data/trash/<id>-<timestamp>/stories/`; `config/<id>-<file_key>.json` dos episódios do banco →
`.../config/`. Recuperar = mover de volta à mão (não há botão). MP4s em `output/` não são movidos.
- Depois, numa transação: apaga `assets` com `scope='story'` (sem isso ficariam órfãos, pois
`assets.story_id` é `SET NULL`) e a linha de `stories`. CASCADE leva episódios, comentários, decisões,
publicações/métricas e `account_stories`; `agent_runs.story_id` e `renders.episode_id` viram NULL (histórico fica).
- Ainda **não existe** exclusão de asset da biblioteca (`assets/library/`).
## Página `/clipper` (Clipador)
Reformulada em 18/11/2026 (`doc/clipador/REDESIGN.md`): deixou de ser uma página com 5 abas e virou **subpáginas** no
grupo de rotas `panel/src/app/clipper/(studio)/`. O `layout.tsx` monta `ClipperProvider` (`clipper-provider.tsx`: dados +
consulta periódica; `useClipper()`) e `ClipperShell` (`clipper-shell.tsx`: cabeçalho compacto com estado do serviço,
bloco "Ao vivo agora · N" com uma linha por live, sub-navegação com contadores). Sub-navegação = `CLIPPER_SECTIONS`; a
sidebar (`sidebar-nav.tsx`) mostra os mesmos subitens quando o Clipador está ativo. Seção nova = entrada em
`CLIPPER_SECTIONS` + pasta em `(studio)/`.
| Rota | Conteúdo | Arquivos |
|---|---|---|
| `/clipper` Cortes | lista `ClipTable` (uma linha por corte; ações rápidas Aprovar/Rejeitar/Publicar), filtros na URL (`?stage ?source ?session ?lang`), modal `ClipDialog` por `?clip=ID` com anterior/próximo | `clipper-clips-page.tsx`, `clipper-clip-table.tsx`, `clipper-clip-dialog.tsx`, `clipper-clip-parts.tsx`; ordenar/apagar/selecionar em utilitários de `clipper-queue.tsx` |
| `/clipper/sessions` | lista de sessões; "Gravar pelo link" em diálogo (`RecordForm`) | `clipper-sessions-page.tsx` |
| `/clipper/sessions/[id]` | saúde, resumo da IA, tiles, gráfico do chat, emotes, configuração do corte | `clipper-session-detail.tsx` |
| `/clipper/sources` | fontes em tabela, "Adicionar fonte" em diálogo, monitor ligado/**pausado** + Religar, idioma da live, canais de publicação | `clipper-channels.tsx` |
| `/clipper/games` | jogos em tabela (nome, gênero, estado, missões, última pesquisa/edição), "Adicionar jogo" em diálogo, `?game=ID` abre o modal do jogo e emotes do canal | `clipper-games-page.tsx`, `clipper-game-dialog.tsx` (modal), `clipper-game-parts.tsx` (seções, `AiChat`, editor à mão), `clipper-games.tsx` |
| `/clipper/settings` | abas Juiz (IA) / Serviço / Idiomas e públicos | `clipper-settings-page.tsx`, `clipper-judge.tsx` |
| `/clipper/edit/[clipId]` | editor em tela cheia, **fora** do grupo `(studio)` | ver "Editor de cortes" |
`clipper-studio.tsx` foi **apagado**; `clipper-queue.tsx` virou só utilitários da lista (a lista é `ClipTable`);
`clipper-sessions.tsx` virou peças compartilhadas (`PlatformIcon`, `CutNow`, `RecordForm`, relógio, `sessionHealth`).
Canal de publicação: campo "Idioma e público" em `account-manager.tsx`; aviso de idioma em `clip-publish.tsx`.
Os parágrafos abaixo descrevem o comportamento de cada peça; onde falam em "aba", "cartão" ou "fila", leia "página",
"linha" e "lista de cortes" (a reescrita deles não foi verificada no navegador).
- `clipper-cut-settings.tsx`: modal "Configuração do corte" em cinco abas — Formato e duração (com a seção
"Qualidade da gravação" e o disco por hora de cada opção, de `captureQualities`) · Câmera e layout · Legenda (com
seletor de fonte) · Gancho (estilo, cores, fonte, animação de entrada, "Ver a entrada") · Crédito — com a prévia ao
lado mudando de proporção (`frames` da rota de settings). Durações mostradas como "1:30 · 90 s", com o padrão lido
de `defaults`. Desenhar o retângulo da câmera sobre o quadro (`…/frame`),
prévia (`…/preview`), achar webcam (`…/detect-cam`), salvar na sessão ou como padrão do canal.
- `clipper-client.ts`: tipo `Aspect`, `format` em `CutSettings`, `aspect?` em `Clip`, `aspectOf()` (ausente =
vertical) e `withFormat()` (completa a resposta de um serviço antigo sem `format`). Na fila (`clipper-queue.tsx`)
o corte horizontal aparece em 16:9.
- Sessão (`clipper-sessions.tsx`, `clipper-session-detail.tsx`): cartão com cabeçalho (tempo gravado,
"gravando em L×A · fps" de `capture` e ações), frase de saúde (`sessionHealth()`), painel "o que está acontecendo" (resumo da IA + jogo), quatro blocos
(Chat, Transcrição, IA assistiu, Cortes) e barra de ferramentas. **Altura fixa por desenho**: nada pode pular na
atualização automática. "Retomar gravação" aparece em toda live que não está gravando (botão principal só em
`interrupted`). Cartão na grade leva `[contain:inline-size]` (gotchas, item 91).
- **Relógio da gravação** (`RecordingClock`): o tempo gravado corre segundo a segundo entre as consultas
(`setInterval` de `CLOCK_TICK_MS` 250 ms por cartão, só gravando e com a aba visível); ressincroniza com o
`durationS` real sem voltar. Passou `CLOCK_MAX_AHEAD_S` (45 s) além do último `durationS`: para e mostra
"aguardando o bloco" com o selo em alerta (ao voltar à aba, espera 6 s antes de acusar).
- **Cadência do resumo** (`SummaryCadence`): ao lado de "Agora na live", "atualiza a cada 3 min · próximo em m:ss";
atrasou, "gerando o próximo resumo…". O intervalo vem de `/status` → `judge.options.scanIntervalS`
(`useScanInterval`; reserva 180 = `OPTION_DEFAULTS` de `intel.py`). Existe porque o dono achou que o resumo
travava (gotchas, item 115).
- Jogos (`clipper-games-page.tsx` + `clipper-game-dialog.tsx` + `clipper-game-parts.tsx`; `clipper-games.tsx` guarda
os emotes do canal): lista em tabela; o modal tem alternância **Português (você lê) / English (vai para a IA)** e abas
Visão geral · Rende corte · Missões · Gatilhos de fim · Termos e hashtags · Fontes · Pedidos à IA, com Pesquisar de
novo, Editar, Pedir à IA (`AiChat`: atalhos por seção, "+N itens novos / −N removidos") e Apagar. Editar grava no
idioma da alternância e o serviço traduz o outro. Rotas e regras em [clipper.md](clipper.md#perfil-do-jogo-aba-jogos).
- Sidebar: os subitens do Clipador usam os mesmos ícones das abas do topo (`sidebar-nav.tsx`, `SubItem.icon`).
- `clipper-queue.tsx`: cartão do corte mostra a análise do juiz e recua/avança o início (`START_STEPS`
−30/−10/−5/−2/+2 s). `clipper-judge.tsx`: modelos do editor e do analista, varredura, visão, câmera.
- **Ordenar a fila** (`clipper-queue.tsx`, seletor "Ordenar" ao lado do filtro de sessão; `QUEUE_SORTS`, `useQueueSort`):
Mais novos (padrão, id desc), Mais antigos, Maior/Menor nota da IA (`judge.score` 0–10; corte sem nota vai sempre para
o fim), Sinal mais forte (`clip.score`), Mais longos (`durationS`); desempate: mais novo. Só reordena no navegador; a
escolha fica em `localStorage` na chave `cenaforge.clipper.queueSort`.
- `clipper-queue.tsx` também tem o botão "Editar" (ou "Continuar edição" se `edit.origin === "user"`) que abre o
editor.
- **Apagar na fila** (`clipper-queue.tsx`; regras do serviço em [clipper.md](clipper.md#apagar-cortes-clip_deletepy)):
"Apagar" em cada cartão, com confirmação no próprio cartão. Seleção **discreta** (o dono reprovou uma barra presa
no topo e pediu "bem sutil, no cantinho"; gotchas, item 116): no canto da linha das abas, "Selecionar" e o menu
"⋯" ("Apagar todos desta aba (N)", modal com a contagem e aviso do filtro de sessão); a caixa de cada cartão só
aparece no hover, no foco ou no modo de seleção; com o modo ligado, a pílula flutuante `SelectionPill` no canto de
baixo ("N selecionados · Selecionar todos · Apagar · ✕", vermelho só no hover). Esc sai do modo. Nada disso ocupa
espaço na página. Manda os ids mostrados em lotes de `CLIP_DELETE_MAX` por `POST clips/delete`; resultado em
aviso fixo (`deleteSummary`). Estados que não se apagam: `UNDELETABLE_CLIP` em `clipper-client.ts`.
- Toda rota nova do serviço precisa entrar na regex `ALLOWED` de `panel/src/lib/clipper.ts` (e, se for lenta, no
timeout por rota do mesmo arquivo; se só alguns métodos valem, em `METHODS`). Detalhes em [clipper.md](clipper.md).
## Editor de cortes
Página `/clipper/edit/[clipId]` (`panel/src/app/clipper/edit/[clipId]/page.tsx`). Projeto, rotas e render em
[clipper.md](clipper.md#editor-de-cortes-clippereditid); fonte completa em `clipper/README.md`.
- **Tela cheia sem mexer no layout raiz:** o componente cobre o rail com `nle fixed inset-0 z-[70]` e trava a rolagem
do documento só nessa página. Tudo cabe em 100vh; cada painel rola sozinho.
- **Desenho de editor de vídeo (NLE):** cores só pelos tokens `--color-nle-*` (classes `bg-nle-panel`,
`text-nle-dim`…) e pelo bloco `.nle` de `panel/src/app/globals.css`; peças prontas em `clip-editor-ui.tsx`. Não use
os tokens do resto do painel dentro do editor.
- Disposição: cabeçalho (Fila, desfazer/refazer, "Projeto da IA", descartar, título e origem, estado do salvamento,
**Salvar projeto**, botões que minimizam Camadas, Transcrição/Chat e Propriedades, "IA sugere", atalhos, status,
Exportar) · Camadas |
Transcrição/Chat | monitor "Fonte · Programa" | Propriedades · timeline na largura toda + medidor de áudio. Em
tela estreita os painéis da esquerda viram abas de um painel só.
- Trilhas da timeline, uma por camada: C1 legenda, V3 textos, V2 zoom, INS inserções, ENQ enquadramento (keyframes
do reenquadramento), CAM câmera (layout de cada trecho), V1 vídeo (miniaturas), A1 áudio da live (forma de onda;
"MUDO" no trecho mudo), A2 narração, A3 música e efeitos, CH chat.
- **Programa no formato do corte:** tamanho vem de `frames` (`frameOf`, `FALLBACK_FRAMES`; sem `W`/`H` fixos), 16:9 no
horizontal; "Formato" do corte em Propriedades › Vídeo. Aviso quando a duração sai do mínimo/máximo (a edição é livre).
- **Fontes na prévia** (`clip-editor-fonts.tsx`): as empacotadas vêm por `fetch` + `FontFace` de `/api/files`
(`fontFiles` da rota de settings); a prévia só desenha depois de carregadas. Tamanho do texto pelas métricas do
arquivo, como o libass: px = tamanho ASS × unitsPerEm / (usWinAscent + usWinDescent), passo de linha = tamanho.
(Antes a prévia saía ~40 % maior que o render.) `FontPicker` = seletor com amostra.
- **ENQ e INS** (`clip-editor-keyframes.tsx`): keyframes ◆ suave / ◇ linear / ■ segurar; arrastar, duplo clique troca
a curva, Delete, Ctrl+C/V, `[` `]` pulam de key. Na Fonte, a janela do reenquadramento tem proporção travada e
auto-key no playhead; o recorte da inserção é desenhado na Fonte e posicionado no Programa, com keyframes de
posição/tamanho, aparência e subir/descer na ordem. Interpolação em `clip-editor-model.ts` (`easeAt`,
`interpolate`, `reframeAt`, `insetAt`), alinhada a `clipper/app/reframe.py`: mudou uma, mude a outra.
- **Câmera editável na Fonte** (`clip-editor-source.tsx`, geometria em `rect-geometry.ts`, compartilhada com o modal):
alças, mover, desenhar numa área vazia, setas (Shift = tamanho). Propriedades "Câmera e layout deste trecho" separa
"Layout · só este trecho" de "Posição da câmera · corte inteiro"; "Usar esta câmera nos próximos cortes da sessão"
grava na sessão (os cortes existentes não mudam). Mudança de layout do corte passa por `editLayout(p, fn)`.
- Fluxos secundários abrem em modal (`ModalKind` = `export` | `ai` | `narration` | `keys`), não em aba.
| Arquivo (`panel/src/components/`) | Papel |
|---|---|
| `clip-editor.tsx` | estado, atalhos, autosave, cabeçalho, disposição dos painéis, som da prévia e medidor (`AudioMeters`) |
| `clip-editor-model.ts` | tipos (`EditProject`, `EditCut`, `ChatOverlay`/`CHAT_DEFAULT`, `InsetOverlay`) e operações puras do projeto (`removeRange`, `keepRange`, `resolvedMode`, `editLayout`, `frameOf`, interpolação de keys, `bannerLayout`); `useHistory` (updater puro: gotchas, item 109) |
| `clip-editor-fonts.tsx` | fontes empacotadas no navegador (`loadPackagedFonts`, `usePackagedFonts`), métricas (`fontMetrics`, `canvasFont`) e `FontPicker` |
| `clip-editor-keyframes.tsx` | trilhas/propriedades ENQ e INS (`ReframeLayer`, `ReframeKeyProps`, `InsetsLayer`, `InsetProps`, `moveInsetOrder`, `KeyGlyph`) |
| `clip-editor-source.tsx` · `rect-geometry.ts` | monitor Fonte (`SourceMonitor`: câmera, jogo, janela do reenquadramento, recorte da inserção) · geometria de retângulo 0–1 (alças, mover, setas), também usada pelo modal do corte |
| `clip-editor-ui.tsx` | peças do desenho NLE: ícones, `IconBtn`, `Btn`, `Modal` (`<dialog>` nativo), `PropSection`/`PropRow`, `Scrub`, `Keycap` |
| `clip-editor-layers.tsx` | painel Camadas: selecionar, ligar/desligar e criar no playhead |
| `clip-editor-timeline.tsx` | régua, trilhas, lâmina, ímã e todos os arrastes (`DRAG_START_PX` = 4) |
| `clip-editor-preview.tsx` | monitor Programa (canvas no formato do corte sobre o proxy, camadas arrastáveis, tarja, inserções e reenquadramento) |
| `clip-editor-transcript.tsx` | transcrição e chat: Tirar, Manter, Editar (troca o texto e reparte o tempo), Ocultar/Mostrar (só da legenda), Ênfase |
| `clip-editor-inspector.tsx` | Propriedades da seleção e os modais (`ExportModal`, `AiModal`, `NarrationModal`, `ShortcutsModal` com a lista `KEYS`) |
- Gestos (tabela "Mexer com a mão" de `clipper/README.md`): arrastar o corpo move palavra/grupo, texto, zoom,
narração e trecho (o trecho desliza sobre a gravação); bordas aparam; no Programa, arrastar muda `x`/`y` de texto,
gancho e chat e a altura da legenda; no Fonte, o alternador Câmera / Área do jogo (`SourceTargetToggle`) escolhe o
retângulo, e mover/alças/desenhar grava `settings.layout.cam`/`game` só daquele corte. O arraste de mover só começa depois de 4 px.
- Autosave 1,2 s com `rev` (409 = outro salvou); "Salvar projeto"/Ctrl+S salva na hora. Desfazer por instantâneos.
- Atalhos (fonte: `KEYS`; atalho novo entra lá e no `onKey` de `clip-editor.tsx`): Espaço tocar/pausar, K pausar,
J/L ±2 s, ←/→ um quadro (Shift = 1 s), Home/End, V seleção, C lâmina, S ou Ctrl+K dividir no playhead,
Ctrl+Shift+clique dividir onde clicar, Q/W começar/terminar o trecho no playhead, Delete, N ímã, Ctrl+roda zoom da
timeline, Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y, Ctrl+S salvar, Ctrl+E exportar, `[`/`]` keyframe anterior/seguinte,
Ctrl+C/Ctrl+V copiar/colar keyframe no playhead, Esc, ? atalhos.
- A prévia do navegador segue o render na legenda (`captionBlocks`, porte de `subtitles.py`) e no recorte de câmera/jogo
(`ffmpegCropFill`, tamanho de `session.capture`); o resto é aproximado e a exata é "Prévia real" (`preview-render`,
FFmpeg). Porte e regra de manutenção em [clipper.md](clipper.md#editor-de-cortes-clippereditid); diferença de 1–3 px:
gotchas, item 117.
- Teste automático da UI: armadilhas 85 (camadas do canvas) e 86 (não gravar no corte real) em [gotchas.md](gotchas.md).
## Evidência e lacunas (16/11/2026)
Teste ponta a ponta numa cópia do banco real (`CENAFORGE_ROOT` temporário, PATH sem CLIs de
agente), informado pelo coordenador: 10 grupos de casos passando (migração preservou 1 história,
1 episódio, 5 comentários; votos `{A:1,B:0,C:2}` → C; fluxo com 7 nós; contas; 14 publicações e
42 fotografias simuladas); typecheck limpo; `/dashboard`, `/accounts`, `?tab=flow` e APIs → 200.
Não verificado: "Preparar vertentes" com agente real; árvore no navegador com dados reais (só
com dados injetados); opções C/D no vídeo (o overlay não as desenha).
Formato documental e modelos (17/11/2026, informado pelo coordenador): `tsc --noEmit` do painel OK;
v4 aplicada numa cópia do banco v3 (stories 2→2, episodes 2→2, agent_runs 3→3, `foreign_key_check`
vazio; CHECK rejeita `kind` inválido e aceita `documentary`); `codexModels()` contra o `~/.codex` real →
9 opções; `claude -p --model claude-fable-5-2` e `claude-haiku-5-5` → "ok". Conferido pela skill: o
`data/cenaforge.db` real ainda está em `user_version` 3 (painel não reiniciado). Não verificado: história
documental criada de ponta a ponta pelo painel (Claude ou Codex) e render de um vídeo documental.
Guias `doc/roteiro/` e exclusão de história (17/11/2026, informado pelo coordenador): `tsc --noEmit` do painel OK
(reconferido pela skill); numa cópia do banco v4, excluir uma história → stories 2→1, episodes 2→1, agent_runs 3→3
(`story_id` da execução virou NULL), `foreign_key_check` vazio. Não verificado: o clique na UI (painel não
reiniciado), o `renameSync` para `data/trash/` no Windows com arquivo aberto e um roteiro real escrito pelos
guias novos (Claude ou Codex). Pela leitura do código: se um `renameSync` falhar no meio, a exceção sobe antes da
transação — a história continua no banco, mas o que já foi movido está na lixeira (devolver à mão).
Mensagem durante a execução e termos episódio × vídeo (17/11/2026, informado pelo coordenador): `tsc --noEmit` do
painel OK (reconferido pela skill); retomada do Codex 0.169 testada à parte com `gpt-6-luna`, sandbox read-only
(gotchas, item 97). Não verificado: o clique na UI (painel não reiniciado) e a retomada do Claude depois de
interrompido (o `--resume` já existia).
Leitor de roteiro (17/11/2026): `parseScript` no `stories/a-ilha-da-queimada-grande-conhecida-como/ep01.md` real →
9 trechos, 176 palavras (≈ 70 s, alvo 72 s), papéis hook/shots/cover/sources/needs (reconferido pela skill via `tsx`);
`tsc --noEmit` do painel e capturas do Chrome headless das três páginas: informados pelo coordenador.
Montagem documental (17/11/2026): `tsc --noEmit` do painel sem erros (reconferido pela skill). Informado pelo
coordenador: `numberToWords` 16/16 casos; teste isolado do `montage-ffmpeg.ts` com 3 trechos reais e
`pt-br-antonio` (Edge) → falas 6,82 / 13,16 / 13,37 s, cada segmento montado em 0,8–1,3 s, `final.mp4` de 38,48 s
(= falas + pausas + créditos, pelo ffprobe), h264 1080×1920 30 fps + aac 48 kHz estéreo, quadros conferidos (zoom,
texto, legenda, cartela, créditos); no painel ao vivo, GET da montagem do episódio 3 → 9 trechos com texto falado por
extenso, áudio do trecho 1 gerado em 3 s. Conferido pela skill: `ep01.montage.json` da Ilha da Queimada Grande com
`pt-br-antonio`, `durationMs` 4080. Não verificado: "Montar vídeo" completo pelo painel (faltam imagens) e
cancelamento (`DELETE .../montage/render`).
Cenas 2D e vídeo automático (17/11/2026). Conferido pela skill: os 9 `report.json` das cenas do episódio da Ilha
(`output/runs/20261117-0422*-ep01-t0N-final`) com `status: success`, 7,4–21,5 s cada; prévias 540×960 de mapa,
contador e título em 2,7–4,3 s (`*-teste-*-preview`, configs em `data/tmp/`). Informado: `planScene` nos 9 trechos
reais → títulos, mapa (Itanhaém → ilha, 35 km) e 2 contadores. Não verificado: cancelamento no meio de uma cena;
`godot/tests/` não tem caso de `doc2d` nem de `doc3d`.
Biblioteca 3D, fotos do Commons e "Gerar de novo" (17/11/2026). Conferido pela skill: com os nomes atuais
(`doc.tscn`, `godot/scripts/doc/`), 13 prévias `teste-ilha-*` (4 tomadas × 3 iterações + 1) com `status: success`,
540×960 × 5 s em 9,4–14,3 s no total (Godot 9–13 s); cena da ilha em final 1080×1920 de 9,1 s em 42,9 s (Godot 39,1 s;
`...-ep01-t07-final` das 04:46); `teste-inexistente` (`campo-futebol`) falha no `godotValidate` com "não existe na
biblioteca (godot/library/). Disponíveis: ["island"]"; prévias de mapa, contador e título v1/v2 em 2,9–3,9 s;
dois MP4 de `ep01` (04:46 e 04:48) h264 1080×1920 + aac, 88,33 s (ffprobe); `pnpm test` → 38 passaram;
`npx tsc --noEmit -p panel` → exit 0; `ep01.montage.json` com fotos do Commons nos trechos 1, 3, 4, 8 e 9 (licenças
CC BY, BY-SA e CC0 registradas), mapa, 2 contadores e `island`, todos `auto: true`. Informado: no painel ao vivo, "Refazer tudo do zero" no episódio 3 → fotos do
Commons diferentes nos trechos 1, 3, 4 e 9 (jararaca) e 8 (ilha + navio), mapa, 2 contadores e o farol 3D ao
entardecer, MP4 em 1 min 44 s; quadros e captura da UI conferidos. Não verificado: cena 3D criada pelo agente do painel
(execução #5, campo de futebol, em andamento), "Gerar de novo" de foto enviada e licença das fotos do Commons uma a uma.
Modal de confirmação (17/11/2026): `tsc --noEmit` do painel sem erros e nenhum `confirm(`/`alert(` nativo em
`panel/src/` (reconferidos pela skill; `askConfirm`/`showAlert`/`confirmSubmit` em 15 componentes). Informado pelo
coordenador: no navegador (http://localhost:4500/) o modal abre com título e descrição acessíveis, Esc fecha sem
excluir e Confirmar reenvia o formulário com o mesmo submitter (2º submit com `data-confirmed="1"`). Não verificado:
cada uma das 25 chamadas trocadas, uma a uma, na UI.
Editor de cortes com tarja, fontes, Programa 16:9, ENQ/INS e câmera na Fonte (17/11/2026): `npx tsc --noEmit -p panel`
→ exit 0 (reconferido pela skill). Informado: prévia da tarja a ≤ ~2 px do render; interpolação do painel ×
`reframe.py` em 41 conferências; testes de UI por CDP com as escritas interceptadas (gotchas, item 86). Render real
de um projeto do editor com enquadramento e inserção comparado com a prévia: ver o lote abaixo.
Apagar na fila, relógio da sessão e prévia igual ao render (17/11/2026): `npx tsc --noEmit -p panel` → exit 0
(reconferido pela skill). Informado pelo coordenador: porte da legenda em 22 conferências contra o Python; corte 61
montado no editor e renderizado pelo serviço com enquadramento, inserção e legenda iguais à prévia em
2/3,5/5/6,5/8 s. Não verificado: apagar pela UI contra o serviço real; relógio com movimento reduzido, aba escondida
e larguras de 1024/1280; a faixa do topo (hoje `clipper-shell.tsx`) pode ainda usar o `durationS` real.