- 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>
560 lines
52 KiB
Markdown
560 lines
52 KiB
Markdown
# 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.
|