sagadeck 1.0.0__tar.gz

sagadeck-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+python/sagadeck/engine/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/
+vitrine/
+*-revisao/

sagadeck-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Narumi Abe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sagadeck-1.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: sagadeck
+Version: 1.0.0
+Summary: Apresentações a partir de YAML: HTML animado, PowerPoint editável, PDF e roteiro — com temas, pictogramas e gráficos gerados na hora.
+Project-URL: Homepage, https://github.com/naruminho/sagadeck
+Project-URL: Repository, https://github.com/naruminho/sagadeck
+Project-URL: Issues, https://github.com/naruminho/sagadeck/issues
+Author: Narumi Abe
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: agents,deck,llm,powerpoint,pptx,presentation,slides,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Saga · sagadeck — gerador de apresentações
+
+Você (ou uma IA) escreve um arquivo `.yaml` com o conteúdo. O sagadeck gera:
+
+| saída | pra quê |
+|---|---|
+| **`.html`** | a apresentação "de verdade": animada, com cliques, enquetes, timers, jogos, modo apresentador. Um arquivo só, funciona offline, abre com duplo clique. |
+| **`.pptx`** | PowerPoint **editável** e fiel ao HTML: texto em caixas nativas com as mesmas fontes, formas nativas, figuras em PNG nítido, animações de clique e transições, notas do apresentador. |
+| **`.pdf`** | um slide por página, para mandar depois da palestra |
+| **`- roteiro.pdf`** | roteiro do apresentador: miniatura de cada slide + fala + interações + relógio planejado |
+
+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
+
+```bash
+pip install sagadeck
+```
+Requer **Node.js 18+** e **Chrome ou Edge** instalados (o motor é JavaScript e vem empacotado no pacote Python).
+
+## Como usar
+
+```bash
+sagadeck new minha-palestra.yaml --theme=editorial
+```
+```bash
+sagadeck all minha-palestra.yaml
+```
+
+Comandos:
+
+```
+sagadeck new <deck.yaml> [--theme=sinal]     cria um deck de exemplo
+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 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
+
+O caminho principal é o agente usar o **terminal**: ele lê as instruções (`sagadeck skill`, também em [`SKILL.md`](SKILL.md)), a referência (`sagadeck ref`), escreve o YAML e roda `check` → `shots` → `all`. Para Claude Code, basta copiar `SKILL.md` para `~/.claude/skills/sagadeck/SKILL.md`.
+
+Se o código de uma ferramenta em Python quiser chamar o sagadeck diretamente (sem montar comandos de terminal), há uma API mínima:
+
+```python
+import sagadeck
+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
+
+```bash
+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)
+
+| tecla | ação |
+|---|---|
+| `→` `espaço` / `←` | avança / volta (inclusive cliques dentro do slide) |
+| `P` | abre a **janela do apresentador**: slide atual, próximo, notas, relógio, cronômetro com "adiantado/atrasado" |
+| `F` | tela cheia |
+| `G` | visão geral de todos os slides |
+| `B` / `W` | tela preta / branca |
+| `L` | apontador laser |
+| `R` | zera o timer do slide |
+| `5` `Enter` | vai para o slide 5 |
+| `H` | ajuda |
+
+**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).

sagadeck-1.0.0/README.md

@@ -0,0 +1,116 @@
+# Saga · sagadeck — gerador de apresentações
+
+Você (ou uma IA) escreve um arquivo `.yaml` com o conteúdo. O sagadeck gera:
+
+| saída | pra quê |
+|---|---|
+| **`.html`** | a apresentação "de verdade": animada, com cliques, enquetes, timers, jogos, modo apresentador. Um arquivo só, funciona offline, abre com duplo clique. |
+| **`.pptx`** | PowerPoint **editável** e fiel ao HTML: texto em caixas nativas com as mesmas fontes, formas nativas, figuras em PNG nítido, animações de clique e transições, notas do apresentador. |
+| **`.pdf`** | um slide por página, para mandar depois da palestra |
+| **`- roteiro.pdf`** | roteiro do apresentador: miniatura de cada slide + fala + interações + relógio planejado |
+
+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
+
+```bash
+pip install sagadeck
+```
+Requer **Node.js 18+** e **Chrome ou Edge** instalados (o motor é JavaScript e vem empacotado no pacote Python).
+
+## Como usar
+
+```bash
+sagadeck new minha-palestra.yaml --theme=editorial
+```
+```bash
+sagadeck all minha-palestra.yaml
+```
+
+Comandos:
+
+```
+sagadeck new <deck.yaml> [--theme=sinal]     cria um deck de exemplo
+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 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
+
+O caminho principal é o agente usar o **terminal**: ele lê as instruções (`sagadeck skill`, também em [`SKILL.md`](SKILL.md)), a referência (`sagadeck ref`), escreve o YAML e roda `check` → `shots` → `all`. Para Claude Code, basta copiar `SKILL.md` para `~/.claude/skills/sagadeck/SKILL.md`.
+
+Se o código de uma ferramenta em Python quiser chamar o sagadeck diretamente (sem montar comandos de terminal), há uma API mínima:
+
+```python
+import sagadeck
+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
+
+```bash
+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)
+
+| tecla | ação |
+|---|---|
+| `→` `espaço` / `←` | avança / volta (inclusive cliques dentro do slide) |
+| `P` | abre a **janela do apresentador**: slide atual, próximo, notas, relógio, cronômetro com "adiantado/atrasado" |
+| `F` | tela cheia |
+| `G` | visão geral de todos os slides |
+| `B` / `W` | tela preta / branca |
+| `L` | apontador laser |
+| `R` | zera o timer do slide |
+| `5` `Enter` | vai para o slide 5 |
+| `H` | ajuda |
+
+**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).

sagadeck-1.0.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,13 @@
+# Componentes de terceiros
+
+O pacote Python `sagadeck` distribui o motor JavaScript empacotado, que inclui:
+
+| componente | licença | uso |
+|---|---|---|
+| [pptxgenjs](https://github.com/gitbrent/PptxGenJS) | MIT | escrita de arquivos .pptx |
+| [jszip](https://github.com/Stuk/jszip) | MIT (dual MIT/GPLv3; usado sob MIT) | pós-processamento do .pptx |
+| [yaml](https://github.com/eemeli/yaml) | ISC | leitura dos decks |
+| [lucide-static](https://github.com/lucide-icons/lucide) | ISC | ícones |
+| [playwright-core](https://github.com/microsoft/playwright) | Apache-2.0 (LICENSE e NOTICE em `engine/node_modules/playwright-core/`) | controle do Chrome/Edge para exportar PNG/PDF/PPTX |
+
+Os avisos de licença de cada componente embutido no arquivo único estão no fim de `engine/sagadeck.mjs`.

sagadeck-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sagadeck"
+dynamic = ["version"]
+description = "Apresentações a partir de YAML: HTML animado, PowerPoint editável, PDF e roteiro — com temas, pictogramas e gráficos gerados na hora."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{ name = "Narumi Abe" }]
+keywords = ["slides", "presentation", "pptx", "powerpoint", "yaml", "deck", "llm", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Education",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: JavaScript",
+  "Topic :: Multimedia :: Graphics :: Presentation",
+  "Topic :: Office/Business :: Office Suites",
+]
+
+[project.urls]
+Homepage = "https://github.com/naruminho/sagadeck"
+Repository = "https://github.com/naruminho/sagadeck"
+Issues = "https://github.com/naruminho/sagadeck/issues"
+
+[project.scripts]
+sagadeck = "sagadeck.cli:main"
+
+[tool.hatch.version]
+path = "python/sagadeck/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/sagadeck"]
+# o motor é gerado por `npm run bundle` e fica fora do git, então precisa ser incluído explicitamente
+artifacts = ["python/sagadeck/engine/**"]
+
+[tool.hatch.build.targets.sdist]
+include = ["python/sagadeck", "README.md", "LICENSE", "THIRD_PARTY_NOTICES.md", "pyproject.toml"]
+artifacts = ["python/sagadeck/engine/**"]

sagadeck-1.0.0/python/sagadeck/__init__.py

@@ -0,0 +1,17 @@
+"""sagadeck — apresentações a partir de YAML: HTML animado, PowerPoint editável, PDF e roteiro.
+
+O motor é JavaScript (Node 18+) e vem empacotado dentro deste pacote; este módulo só o localiza e chama.
+
+Uso na linha de comando:
+    sagadeck all minha-palestra.yaml
+
+Uso em Python (ex.: para uma IDE/agente coordenar):
+    import sagadeck
+    sagadeck.run("all", "minha-palestra.yaml", out="saida")
+    print(sagadeck.reference())      # referência completa do YAML, para passar a um LLM
+"""
+
+from .api import run, build, check, export, reference, skill, engine_path, node_path
+
+__version__ = "1.0.0"
+__all__ = ["run", "build", "check", "export", "reference", "skill", "engine_path", "node_path", "__version__"]

sagadeck-1.0.0/python/sagadeck/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

sagadeck-1.0.0/python/sagadeck/api.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Sequence
+
+ENGINE = Path(__file__).resolve().parent / "engine"
+MIN_NODE = (18, 0)
+
+
+class SagadeckError(RuntimeError):
+    pass
+
+
+def engine_path() -> Path:
+    """Caminho do motor JavaScript empacotado."""
+    entry = ENGINE / "sagadeck.mjs"
+    if not entry.exists():
+        raise SagadeckError(
+            "Motor não encontrado em %s. Em um clone do repositório, rode antes: npm install && npm run bundle" % entry
+        )
+    return entry
+
+
+def node_path() -> str:
+    """Localiza o Node.js (>= 18). Pode ser forçado com a variável SAGADECK_NODE."""
+    node = os.environ.get("SAGADECK_NODE") or shutil.which("node")
+    if not node:
+        raise SagadeckError(
+            "O sagadeck precisa do Node.js 18+ instalado (https://nodejs.org) "
+            "e de Chrome ou Edge para exportar PPTX/PDF."
+        )
+    out = subprocess.run([node, "--version"], capture_output=True, text=True).stdout.strip()
+    m = re.match(r"v(\d+)\.(\d+)", out)
+    if not m or (int(m.group(1)), int(m.group(2))) < MIN_NODE:
+        raise SagadeckError(f"Node.js {out or '?'} é antigo demais; o sagadeck precisa do 18 ou mais novo.")
+    return node
+
+
+def run(command: str, *args: str, out: str | os.PathLike | None = None, check: bool = True,
+        capture: bool = False, extra: Sequence[str] = ()) -> subprocess.CompletedProcess:
+    """Executa um comando do sagadeck: build, check, shots, pptx, pdf, roteiro, all, themes, icons, ref, skill…"""
+    cmd = [node_path(), str(engine_path()), command, *map(str, args), *extra]
+    if out is not None:
+        cmd.append(f"--out={out}")
+    proc = subprocess.run(cmd, capture_output=capture, text=True, encoding="utf-8" if capture else None)
+    if check and proc.returncode != 0:
+        raise SagadeckError(f"sagadeck {command} falhou (código {proc.returncode})" + (f":\n{proc.stderr}" if capture else ""))
+    return proc
+
+
+def build(deck: str | os.PathLike, out=None) -> Path:
+    """Gera o .html do deck e devolve o caminho."""
+    run("build", str(deck), out=out)
+    d = Path(deck)
+    return Path(out or d.parent) / (d.stem + ".html")
+
+
+def check(deck: str | os.PathLike, out=None) -> str:
+    """Roda o fiscal de layout e devolve o relatório em texto (útil para um agente corrigir o YAML)."""
+    return run("check", str(deck), out=out, capture=True, check=False).stdout
+
+
+def export(deck: str | os.PathLike, out=None, native_charts: bool = False) -> dict:
+    """Gera html, pptx, pdf e roteiro. Devolve os caminhos."""
+    run("all", str(deck), out=out, extra=["--native-charts"] if native_charts else [])
+    d = Path(deck)
+    base = Path(out or d.parent) / d.stem
+    return {k: Path(str(base) + ext) for k, ext in
+            {"html": ".html", "pptx": ".pptx", "pdf": ".pdf", "roteiro": " - roteiro.pdf"}.items()}
+
+
+def reference() -> str:
+    """Referência completa do formato YAML (Markdown) — ideal para colocar no contexto de um LLM."""
+    return (ENGINE / "docs" / "REFERENCIA.md").read_text(encoding="utf-8")
+
+
+def skill() -> str:
+    """Instruções para agentes de IA gerarem decks com o sagadeck (formato SKILL.md)."""
+    return (ENGINE / "docs" / "SKILL.md").read_text(encoding="utf-8")

sagadeck-1.0.0/python/sagadeck/cli.py

@@ -0,0 +1,20 @@
+import subprocess
+import sys
+
+from .api import SagadeckError, engine_path, node_path
+
+
+def main() -> int:
+    try:
+        cmd = [node_path(), str(engine_path()), *sys.argv[1:]]
+    except SagadeckError as e:
+        print(f"✗ {e}", file=sys.stderr)
+        return 1
+    try:
+        return subprocess.call(cmd)
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sagadeck-1.0.0/python/sagadeck/engine/docs/REFERENCIA.md

@@ -0,0 +1,163 @@
+# Referência do formato `.yaml` do sagadeck
+
+Um deck é um arquivo YAML com cabeçalho + lista de `slides`. Cada slide escolhe um **layout** e preenche os campos dele.
+Tudo que é texto aceita a **marcação inline** (abaixo). Qualquer slide aceita `notes`, `time`, `tone`.
+
+```yaml
+title: Nome da palestra          # obrigatório (vira rodapé e título da janela)
+author: Seu Nome · Cargo
+theme: sinal                     # sinal | editorial | noite | bauhaus | terminal | jornal  (ou tema customizado, ver fim)
+duration: 50                     # minutos — o modo apresentador mostra se você está adiantado/atrasado
+footer: texto do rodapé          # opcional; false desliga
+tone: light                      # tom padrão dos slides (light | dark | accent | alert)
+maxWords: 40                     # alerta "anti-sono" quando um slide passa disso
+css: [estilo.css]                # CSS extra (opcional)
+widgets: [widgets/jogo.js]       # widgets interativos próprios (opcional, ver fim)
+slides:
+  - layout: cover
+    title: …
+```
+
+## Campos comuns a todo slide
+
+| campo | o que faz |
+|---|---|
+| `layout` | um dos layouts abaixo (se omitido, o sagadeck adivinha pelo conteúdo) |
+| `tone` | `light` (padrão), `dark`, `accent` (cor forte do tema), `alert` |
+| `kicker` | linha pequena acima do título (rótulo) |
+| `title` / `titleSize` / `titleAs` | título; tamanho em px; papel tipográfico (`title`, `h2`, `h3`) |
+| `source` | fonte/nota de rodapé do slide |
+| `add` | elemento(s) extra(s) no fim da área útil |
+| `notes` | roteiro do apresentador (Markdown simples, ver abaixo) |
+| `time` | minutos planejados para o slide (soma no cronômetro) |
+| `build: true` | revela os itens (lista, cards, linha do tempo, matriz…) **um por clique** |
+| `steps: N` | força N cliques no slide (útil para widgets) |
+| `background` | figura de fundo atrás do conteúdo |
+| `bg` / `fg` | cor de fundo / texto (hex) só neste slide |
+| `transition` | `fade` (padrão) ou `cut` |
+| `footer: false` | esconde o rodapé neste slide |
+
+## Marcação inline (qualquer texto)
+
+`**negrito**` · `*itálico*` · `==marca-texto==` (animado) · `^^cor de ênfase^^` · `~~riscado~~` · `` `código` `` · `[link](https://…)` · quebra de linha = nova linha no YAML (`|`).
+
+## Layouts
+
+| layout | campos principais | uso |
+|---|---|---|
+| `cover` | `kicker, title, subtitle, author, role, figure` | capa |
+| `section` | `number, kicker, title, subtitle, figure` | abertura de ato/capítulo (tom `accent` por padrão) |
+| `statement` | `text` **ou** `lines: [ {text, as, color, step} ]`, `by`, `center` | uma frase de impacto; `lines` + `build` revelam linha a linha |
+| `quote` | `quote, by, role, after, afterStep` | citação; `after` aparece num clique |
+| `number` | `value, prefix, suffix, decimals, from, label, context, side, valueColor` | número gigante animado (conta de `from` até `value`) |
+| `split` | `title, body, bullets, content, figure, ratio: "1.2:1", reverse, build` | texto + figura |
+| `cards` | `title, items: [{icon, picto, number, title, text, foot, hl}], cols, build` | 2–4 cartões |
+| `list` | `title, items: [texto ou {text, sub}], numbered, size, build` | lista numerada grande |
+| `timeline` | `title, events: [{when, title, text, tag}], highlight, after, build` | linha do tempo |
+| `chart` | `title, chart: {…}, side (texto ou elemento), chartHeight` | gráfico + comentário |
+| `compare` | `title, left: {label, value, title, text, items, figure, hl}, right: {…}, vs, after, build` | A × B |
+| `matrix` | `title, x: [esq, dir], y: [cima, baixo], cells: [4 × {title, text, example, hl}], build` | matriz 2×2 |
+| `question` | `question, options: [texto ou {key, text, sub}], keys, cols, timer, hint, optionSize` | pergunta para a plateia (com timer) |
+| `poll` | `question, id, options, compare: outroId, hint` | enquete: o apresentador digita os resultados e o slide anima as barras; `compare` mostra a diferença para outra enquete |
+| `video` | `title, url, label, figure, caption` | cartão que abre um vídeo |
+| `code` | `title, code, highlight: [linhas], note` | código com linhas destacadas |
+| `image` | `image` ou `figure`, `title, caption` | imagem/figura em tela cheia |
+| `blocks` | `title, content: [elementos]` | layout livre em fluxo (linhas/colunas) |
+| `canvas` | `elements: [{…, x, y, w, h}]` | posicionamento absoluto em 1920 × 1080 |
+| `end` | `title, subtitle, contacts, figure` | encerramento |
+| `references` | `title, items` | fontes (2 colunas) |
+
+## Elementos (dentro de `content`, `side`, `add`, `figure`, `elements`…)
+
+Todo elemento aceita: `step` (clique em que aparece), `exit` (clique em que some), `anim` (`up` padrão, `fade`, `pop`, `left`, `right`, `down`, `zoom`, `none`), `w`, `h`, `flex`, `color`, `bg`, `align`, `pad`, `card: true|hi`, `class`, `style` e, no `canvas`, `x`, `y`.
+
+| elemento | exemplo |
+|---|---|
+| texto | `{ h2: "Título" }` · `{ lead: "…" }` · `{ body: "…" }` · `{ label: "…" }` · `{ quote: "…" }` · `{ number: "65%" }` — ou `{ text: "…", as: h3, size: 60 }` |
+| linha / coluna | `{ row: [ … ], gap: 40, valign: center }` · `{ col: [ … ], gap: 20 }` |
+| contador | `{ counter: 79, suffix: "%", from: 0, decimals: 0, size: 240 }` |
+| timer | `{ timer: 30, size: 200, label: "segundos", auto: true }` (clique pausa; tecla R zera) |
+| enquete | `{ poll: id, options: [...], compare: outroId }` |
+| lista | `{ list: [...], numbered: true, build: true }` |
+| cartões | `{ cards: [...], cols: 3 }` |
+| código | `{ code: "…", highlight: [2] }` |
+| forma | `{ shape: rect|rounded|circle|pill|line, fill: hi, stroke: fg, w, h }` |
+| selo | `{ badge: "NOVO" }` |
+| vídeo | `{ video: "https://…", label: "Assistir" }` |
+| HTML livre | `{ html: "<div>…</div>" }` |
+| widget | `{ widget: nome, …opções }` |
+| espaço | `{ spacer: true }` (empurra) ou `{ spacer: 40 }` |
+
+## Figuras geradas na hora
+
+**Ícones** (2.100+ do Lucide — veja `sagadeck icons carro`): `{ icon: gavel, size: 200, stroke: 1.5, color: em }`
+
+**Pictogramas** (estilo sinalização):
+- `{ picto: human, pose: walk, sign: circle }` — poses: `stand walk run sit drive phone watch point raise shrug think stamp cheer sleep`; `sign`: `circle | square | triangle` (placa atrás)
+- `{ picto: machine }` — a "máquina"
+- `{ picto: crowd, count: 20, highlight: 3 }` — bonequinhos, os primeiros destacados
+- `{ picto: scene, name: … }` — cenas prontas:
+  - `console` (`screen: "TEXTO"`, `alarm: true`) · `desk` (`papers: true`) · `pair` · `judge` · `elevator` (`button: false`)
+  - `car-top` — carro visto de cima: `driver` / `passenger`: `human | human-watch | human-phone | machine`, `back: sleep | human`, `button: true`
+
+**Diagramas**: `{ diagram: loop, nodes: [a, b, c, d], actor: in|on|out, at: 2 }` · `{ diagram: spectrum, stops: [...], at: 1, left, right }` · `{ diagram: flow, steps: [...], highlight: 1 }` · `{ diagram: venn, a, b, both }`
+
+**Gráficos** (animados no HTML; com `--native-charts` viram gráficos nativos editáveis no PowerPoint):
+```yaml
+{ chart: bar,    data: [{label: A, value: 10}, …], suffix: "%", highlight: [2] }
+{ chart: column, data: […], max: 100 }
+{ chart: line,   labels: [...], series: [{name, values: [..., null, ...]}], bands: [{at: 6, text: LANCHE}], annotations: [{at: 3, text: "pico"}], min: 0, max: 100, axis: false, markers: false, area: true }
+{ chart: donut,  value: 65, center: "65%" }            # ou parts: [{label, value, color}]
+{ chart: waffle, total: 100, cols: 10, groups: [{count: 21, label: "…", color: em}, {count: 79, label: "…"}] }
+{ chart: isotype, total: 20, highlight: 4, icon: car }
+{ chart: stacked, data: [{label, value}, …] }
+```
+`null` numa série quebra a linha (ex.: sessões diferentes). Cores aceitam papéis do tema (`fg`, `hi`, `em`, `muted`, `line`) ou hex.
+
+**SVG próprio**: `{ svg: "<svg viewBox='0 0 100 100'>…</svg>" }` — use `style="fill:var(--fg)"`, `var(--hi)`, `var(--em)` para seguir o tema.
+**Imagem**: `{ image: foto.jpg, fit: cover }` (caminho relativo ao YAML; é embutida no HTML).
+
+## Notas / roteiro (`notes`)
+
+Markdown simples, pensado para ler em voz alta:
+
+```yaml
+notes: |
+  ## Título de bloco
+  > Frase para falar (aparece destacada)
+  CLIQUE: o que acontece no próximo clique
+  INTERAÇÃO: o que pedir para a plateia
+  PLANO B: o que fazer se ninguém participar
+  - item de lista
+```
+Linhas que começam com PALAVRAS EM MAIÚSCULAS seguidas de `:` viram etiquetas coloridas.
+
+## Tema customizado
+
+```yaml
+theme:
+  extends: editorial
+  colors: { accent: "2F6BFF", alert: "2F6BFF" }
+  tones: { accent: { bg: accent, fg: "FFFFFF" } }
+  faces:
+    display: { css: "font-family: 'Rockwell Extra Bold', serif; line-height: .95;", pptx: { face: "Rockwell Extra Bold" } }
+```
+Cada face tem `css` (navegador) e `pptx` (nome exato da fonte no PowerPoint). Use fontes instaladas no Windows/Office para o PPTX sair idêntico.
+
+## Widgets próprios
+
+```js
+// widgets/contador.js
+Sagadeck.widget("contador", {
+  mount(el, opts, api) {
+    let n = 0;
+    el.innerHTML = `<button style="font-size:60px">${opts.rotulo}: 0</button>`;
+    el.firstChild.onclick = () => (el.firstChild.textContent = `${opts.rotulo}: ${++n}`);
+    api.onStep((k) => {});            // chamado a cada clique do slide
+    api.onEnter(() => {}); api.onLeave(() => {});
+    api.onKey((tecla) => {});         // teclas livres (ex.: [ ] + -)
+    api.store.set("x", 1);            // guarda no navegador (sobrevive a recarregar)
+  },
+});
+```
+No YAML: `widgets: [widgets/contador.js]` e `{ widget: contador, rotulo: "Votos" }`. No PowerPoint o widget vira uma imagem do estado final.