Saga · sagadeck — gerador de apresentações

Você (ou uma IA) escreve um arquivo .yaml com o conteúdo. O sagadeck gera:

Ele vem com 6 temas, 21 layouts, 2.100+ ícones, pictogramas e cenas geradas na hora, diagramas, 7 tipos de gráfico, e um fiscal automático que detecta texto estourado, sobreposição, contraste baixo e slides com texto demais ("anti-sono").

Instalação

pip install sagadeck

Requer Node.js 18+ e Chrome ou Edge instalados (o motor é JavaScript e vem empacotado no pacote Python).

Como usar

sagadeck new minha-palestra.yaml --theme=editorial

sagadeck all minha-palestra.yaml

Comandos:

sagadeck new <deck.yaml> [--theme=sinal]     cria um deck de exemplo
sagadeck studio [deck.yaml] [--port=3000]    abre o estúdio web visual estilo PowerPoint com chat lateral IA
sagadeck autofix <deck.yaml> [--out=pasta]   auto-corrige sobreposições, margens e excesso de texto no YAML
sagadeck build <deck.yaml>                   gera o .html
sagadeck watch <deck.yaml>                   recompila o .html a cada vez que você salva o YAML
sagadeck check <deck.yaml>                   fiscal: estouro de texto, sobreposição, contraste, excesso de texto
sagadeck shots <deck.yaml> [--steps]         PNG de cada slide + folhas de contato (para revisar)
sagadeck pptx <deck.yaml> [--native-charts]  PowerPoint editável
sagadeck pdf <deck.yaml>                     PDF
sagadeck roteiro <deck.yaml>                 roteiro do apresentador em PDF
sagadeck all <deck.yaml>                     tudo acima
sagadeck mcp                                 servidor MCP para IDEs agênticos (Cursor, Claude Code, Cline)
sagadeck themes                              vitrine com os 6 temas
sagadeck icons [filtro]                      lista os ícones (ex.: sagadeck icons car)
sagadeck ref                                 referência completa do YAML
sagadeck skill                               instruções para agentes de IA

Opção --out=pasta muda onde os arquivos são salvos.

Com agentes de IA e IDEs Agênticos

O sagadeck foi projetado para ser usado por humanos e por agentes de IA:

1. Pelo Terminal / Skill: O agente lê as instruções (sagadeck skill, também em SKILL.md), a referência (sagadeck ref), escreve o YAML e roda autofix → check → all. Para Claude Code, basta copiar SKILL.md para ~/.claude/skills/sagadeck/SKILL.md.
2. Pelo Estúdio Visual: Execute sagadeck studio palestra.yaml para abrir a interface web estilo PowerPoint, onde você pode editar visualmente no canvas 16:9 e conversar com a IA no chat lateral. A IA se auto-corrige e nunca deixa elementos sobrepostos ou fora das margens.
3. Pelo Protocolo MCP: Execute sagadeck mcp para que IDEs agênticos (Cursor, Windsurf, Cline, Roo Code) descubram e invoquem diretamente as ferramentas de criação, leitura, fiscalização e auto-cura de apresentações.

Se o código de uma ferramenta em Python quiser chamar o sagadeck diretamente (sem montar comandos de terminal), há uma API mínima:

import sagadeck
sagadeck.autofix("palestra.yaml")               # corrige sobreposições e margens automaticamente
sagadeck.studio("palestra.yaml", port=3000)     # abre o estúdio PowerPoint interativo
sagadeck.export("palestra.yaml", out="saida")   # {'html': …, 'pptx': …, 'pdf': …, 'roteiro': …}
print(sagadeck.check("palestra.yaml"))           # relatório do fiscal em texto
contexto = sagadeck.reference()                  # referência do YAML para colocar no prompt

Desenvolvimento

npm install
node bin/sagadeck.js build templates/exemplo.yaml
npm run bundle          # empacota o motor em python/sagadeck/engine
npm run build:py        # gera dist/*.whl e dist/*.tar.gz

Publicação: crie uma release vX.Y.Z no GitHub (o workflow .github/workflows/publish.yml publica no PyPI via trusted publishing). A versão fica em package.json e python/sagadeck/__init__.py (o bundle confere se são iguais).

Apresentando (HTML)

No Teams: compartilhe só a janela do deck (a janela do apresentador fica com você). Se tiver um monitor só, deixe a janela do apresentador ao lado e compartilhe a janela do deck. Para vídeos com som, compartilhe com "incluir som do computador".

Temas

sinal (sinalização, DIN condensada, amarelo de aviso) · editorial (revista, serifada, vermelho-tomate) · noite (escuro elegante, latão) · bauhaus (geométrico, cores primárias) · terminal (dados, monoespaçada, âmbar — sem neon) · jornal (manchete, Franklin Gothic, azul-tinta). Veja todos lado a lado com sagadeck themes. Dá para criar o seu estendendo um tema — veja docs/REFERENCIA.md.

Arquivos

bin/sagadeck.js            linha de comando
src/themes.js           temas (cores, tons, fontes para navegador e PowerPoint)
src/layouts.js          os 21 layouts
src/elements.js         elementos (texto, contador, timer, enquete, cartões…)
src/figures/            pictogramas, diagramas, gráficos, ícones — tudo gerado em SVG
src/runtime/            o motor que roda no navegador (navegação, cliques, apresentador, widgets)
src/export/             PowerPoint, PDF, imagens, roteiro e o fiscal
templates/exemplo.yaml  deck de exemplo com todos os layouts
docs/REFERENCIA.md      referência completa do YAML
SKILL.md                instruções para IAs gerarem decks com o sagadeck
python/sagadeck/        pacote Python (CLI + API) que carrega o motor empacotado
scripts/bundle.mjs      empacota o motor para o pip
tools/ppt-render.ps1    renderiza um .pptx pelo PowerPoint (para conferir fidelidade)
tools/test-live.mjs     teste automático do modo apresentação e dos widgets

Limitações conhecidas

• O PPTX usa as fontes do Windows/Office dos temas. Aberto num Mac sem essas fontes, o PowerPoint troca a fonte (o HTML e o PDF continuam iguais).
• Widgets interativos (jogos, simuladores) viram imagem do estado final no PowerPoint e no PDF — a interação existe só no HTML.
• Gráficos entram como imagem nítida no PPTX; com --native-charts, barras/colunas/linhas/rosca viram gráficos nativos editáveis (com visual mais simples).