primocode 10.15.2 → 10.17.0

package/editor/modelo-projeto/compositions/cenas/LEIA.md

@@ -0,0 +1,177 @@
+# Cenas sob medida
+
+Quando nenhuma peça do catálogo serve, a cena é escrita à mão, como nos vídeos que ficaram melhores: um
+arquivo por cena nesta pasta (`compositions/cenas/s03_orcamento.html`), cada um uma sub-composição do
+HyperFrames. A pasta fica dentro de `compositions/` porque o `python3 build.py hf lint` só confere o que está
+ali (uma cena em outra pasta passaria sem lint). O `build.py` encaixa a cena no tempo certo do corte, numa faixa
+própria da linha do tempo do estúdio, tanto na `amostra` quanto no `completo`. Os arquivos soltos em
+`compositions/` (fora de `cenas/`) são as peças do catálogo que o build gera e apaga a cada build: não escreva lá.
+
+## No projeto.json
+
+```json
+"cenas_proprias": [
+  {"arquivo": "compositions/cenas/s03_orcamento.html", "de": 12.3, "ate": "cortou", "nome": "Cena · orçamento",
+   "faixa": 31, "esconde_legenda": true}
+]
+```
+
+| campo | o que é |
+|---|---|
+| `arquivo` | o arquivo da cena, a partir da pasta do projeto |
+| `de`, `ate` | segundos do `cut.mp4` ou a palavra (a cena começa ou termina quando a palavra começa); `de_depois_de` e `ate_depois_de` escolhem qual repetição da palavra |
+| `nome` | nome da faixa no estúdio (padrão: "Cena · s03 orcamento", tirado do arquivo) |
+| `faixa` | número da faixa no estúdio (padrão 30, 31, 32...; só organiza a tela, o render não lê) |
+| `esconde_legenda` | `true` quando a cena já escreve a fala (a legenda some nesse trecho) |
+| `sobre_a_pessoa` | `true` quando a cena é um cartão pequeno acima da cabeça, com a pessoa em tela cheia (`area: "acima_do_rosto"` nas cenas `k2d_medidor`, `k2d_comando`, `k2d_busca` e `k2d_notas`): a câmera viva fica em zoom 1,0 e não aproxima nesse trecho. O build avisa se um `tela_cheia` do trecho ainda aproxima |
+
+Na `amostra`, só entram as cenas que cruzam o trecho. Se a amostra começa no meio de uma cena, o build põe
+`data-playback-start` e a cena continua do ponto certo (não recomeça).
+
+## O que a cena recebe
+
+O `index.html` traz, antes de tudo, `window.__cenas["<id da cena>"]`:
+
+| chave | o que é |
+|---|---|
+| `de`, `ate`, `duracao` | onde a cena fica no corte, em segundos. Com `segura_fim`, a cena cujo `ate` cai no fim do corte (até 0,25 s antes) vai até o fim do quadro parado, e o `ate` e a `duracao` já vêm com isso |
+| `palavras` | a fala do trecho: `[{"texto": "cortou", "t": 3.68, "fim": 4.04}]`, com `t` e `fim` em segundos **da cena** (0 = o `de`). O `t` é o começo medido na onda quando a pasta `edit` tem o `palavras_onda.json` (`helpers/palavras_na_onda.py`); sem ele, o tempo do Whisper, que adianta até 0,3 s |
+| `tempo` | de onde vem o `t` das palavras: `"onda"` ou `"whisper"`. Com `"whisper"`, uma batida que precisa cair na palavra pode chegar até 0,3 s cedo: rode o helper e o build de novo |
+| `rosto` | a caixa do rosto na tela no começo da cena, em pixels: `{x0, y0, x1, y1, topo}` (`topo` = topo da cabeça estimado); `null` sem rosto |
+| `moldura` | quando a cena cruza uma moldura: `{caixa, area_livre, fechada_em}` (`fechada_em` em segundos da cena: antes disso o quadro ainda está fechando e o que aparecer passa na frente do rosto); `null` sem moldura. Cruzar é dividir pelo menos um quadro do render, com os dois trechos meio-abertos, [de, ate): a cena que começa no quadro em que a moldura acaba não recebe `moldura` (senão fica transparente em cima do vídeo em tela cheia), nem quando o tempo foi escrito com 3 casas (`4.933` contra o corte de verdade, 4,93333) ou quando o bloco encostou no corte e a cena ficou no tempo que você escreveu |
+| `seguro` | a zona segura do formato `[x0, y0, x1, y1]` (9:16: 140, 230, 940, 1530) |
+| `largura`, `altura` | 1080 x 1920, 1920 x 1080, 1080 x 1350 (4:5) ou 1080 x 1080 (1:1) |
+| `cores` | as cores do `estilo` do projeto: `papel`, `linha`, `base`, `destaque`, `tinta`, `verde`, `vermelho`. Em estilo escuro (`laranja`) a `tinta` é clara e o `papel` é escuro: letra sobre uma cor clara (o laranja) leva o `papel`, e não a `tinta` (as cenas do kit já escolhem pela luz do fundo) |
+| `fundo_css` | o fundo do estilo em CSS (grade e brilho), só nos estilos escuros com fundo próprio (`laranja`); `null` em `papelaria` e `noite`. A cena que pinta o próprio fundo em tela cheia usa ele quando existe (as cenas do kit 2D já usam), para a grade e o brilho não mudarem de um trecho para o outro |
+
+Aberta sozinha no painel Compositions do estúdio, a cena não tem esses dados: use sempre um valor padrão (o
+exemplo abaixo faz isso).
+
+A lista `palavras` vem da transcrição do corte e pode mudar quando o corte é conferido de novo (o Whisper junta
+ou separa palavras, "o tudo" vira "o" e "tudo", "ééé" vira "éééé"). Nunca conte com um número fixo de palavras:
+procure pela palavra (a função `em` do exemplo) e deixe o desenho aguentar uma a mais (linha que quebra sozinha,
+`flex-wrap`), senão a cena estoura o painel e o `check` reprova.
+
+## O contrato (o que não pode faltar)
+
+1. Tudo dentro de `<template id="<id>-template">`: o `<style>`, a raiz e o `<script>`. O que fica fora do
+   template é jogado fora.
+2. A raiz é `<div id="root" data-composition-id="<id>" data-width="1080" data-height="1920" data-duration="...">`
+   no tamanho do vídeo do projeto (1920x1080 no 16:9, 1080x1350 no 4:5, 1080x1080 no 1:1; veja "O tamanho da
+   raiz") e o estilo dela vai em `#root {...}` (nunca numa classe da raiz). O `<id>` é o nome do arquivo sem
+   `.html` (`s03_orcamento`); `main` e `peca-...` são do build.
+3. Uma timeline só, pausada, registrada com o mesmo id escrito por extenso:
+   `window.__timelines["s03_orcamento"] = tl;` dentro de uma função `(function () { ... })();`.
+4. Tempo da cena: 0 é o `de`. Nunca tempo negativo.
+5. Determinística e sem depender do seek: `fromTo` com os dois lados, `immediateRender: false` a partir do
+   segundo tween do mesmo elemento, nada de `Math.random`, `Date.now`, `repeat: -1` ou timer. Valor que muda a
+   cada quadro vai como lista de dados + laço de `tl.set`.
+6. Todo elemento nasce com `opacity: 0` no CSS e entra por tween. Anime `opacity`, `x`, `y`, `rotation` e
+   `clip-path`; nunca `left/top/width/height`, e nada de `transform` no CSS de quem o GSAP move. Nada de escala
+   (`scale`, `scaleX`): depois de um tween de escala o Chrome guarda o desenho numa escala que depende do que a
+   página já tocou e da máquina, e dois renders do mesmo projeto saem diferentes. Para "crescer", use `clip-path`
+   (`inset(...)` ou `circle(...)`) ou um deslocamento maior. Imagem do tamanho em que aparece: maior que a
+   caixa, reduzida pelo navegador, também muda a borda de um render para outro.
+7. Texto que muda nunca nasce vazio (escreva o primeiro valor no HTML); número que começa com zero leva o
+   espaço de largura zero na frente (`"​01"`).
+8. Ids com o prefixo da cena (`#s03-card`), para não bater com as peças do build.
+9. Caminho de arquivo sempre a partir da pasta do projeto (`assets/fontes/Montserrat.ttf`,
+   `assets/print.png`), nunca `../`. Fonte com `@font-face` dentro do `<style>` da cena.
+10. `<video>` dentro da cena: `muted playsinline`, com `id`, `data-start` em tempo da cena, sem `crossorigin`.
+    Som vai num `<audio id>` à parte.
+11. Espaço entre palavras em elementos separados vai como margem em px, nunca como texto: o HyperFrames
+    descarta o texto que é só espaço entre dois elementos (`<span>Não</span> <span>fui</span>` sai "NÃOFUI").
+    Use `margin-left: 14px` (em px: `.3em` num span sem `font-size` próprio mede pelos 16 px da raiz e some).
+12. Risco em cima de texto reprova o `check` (`text_occluded`), mesmo com `data-layout-allow-occlusion`. Ponha o
+    risco por baixo das letras: filho do item, com o item em `position:relative; z-index:0` e o risco em
+    `z-index:-1`. Continua parecendo riscado e o check passa.
+13. Troca de estado com os dois textos no mesmo lugar ao mesmo tempo reprova (`content_overlap`): o texto velho
+    termina de sair antes do novo entrar (ou um sai por um lado e o outro entra pelo outro, sem cruzar).
+14. Na moldura, o primeiro elemento entra depois do quadro fechar (`C.moldura.fechada_em`, uns 0,7 s depois
+    da troca). O build avisa quando a cena começa antes disso. A cena que começa quando a moldura acaba não é da
+    moldura (`moldura: null`): desenhe com fundo próprio, porque o vídeo está em tela cheia.
+
+## O tamanho da raiz
+
+O HyperFrames monta a cena com o tamanho que a raiz declara, não com o do vídeo: uma raiz 1080x1920 num projeto
+16:9, 4:5 ou 1:1 sai cortada. O build compara a raiz de cada cena com o vídeo:
+
+- a cena se desenha pelo `largura` e `altura` que recebe (lê os dois do `window.__cenas`, como as cenas do kit 2D
+  e 3D): o build põe a raiz no tamanho do vídeo no `index.html` (uma regra com `!important` no host e no filho
+  dele, que vence o tamanho que o HyperFrames escreve, no estúdio e no render) e diz numa linha só quais cenas
+  ajustou. O arquivo da cena não muda; aberta sozinha no painel Compositions, ela fica no tamanho que declara.
+- a cena tem posições fixas (não lê `largura` nem `altura`): o build não mexe e avisa `a raiz declara 1080x1920 e o
+  vídeo é 1920x1080: a cena sai cortada`. Troque `data-width` e `data-height` da raiz e refaça as posições para o
+  formato (melhor: calcule pelo `largura`, `altura` e `seguro` que a cena recebe).
+
+## Exemplo mínimo (passa no `python3 build.py hf lint` e no `hf check`)
+
+`compositions/cenas/s01_titulo.html`, com `{"arquivo": "compositions/cenas/s01_titulo.html", "de": 0.7, "ate": 5.5}` no
+projeto:
+
+```html
+<!doctype html>
+<html lang="pt-BR"><head><meta charset="UTF-8"/><title>s01 · título</title></head>
+<body>
+<template id="s01_titulo-template">
+<style>
+@font-face{font-family:Montserrat;src:url("assets/fontes/Montserrat.ttf") format("truetype");font-weight:100 900;font-display:block}
+#root{position:absolute;inset:0;font-family:Montserrat}
+#s01-card{position:absolute;left:190px;top:300px;width:700px;height:200px;border-radius:32px;background:#fffdfd;
+  display:flex;align-items:center;justify-content:center;opacity:0;box-shadow:0 12px 0 -2px #c7b7ef,0 22px 44px rgba(53,44,64,.35)}
+#s01-txt{position:relative;z-index:1;font-weight:900;font-size:64px;color:#352c40;white-space:nowrap}
+#s01-risco{position:absolute;left:60px;right:60px;top:50%;height:10px;margin-top:-5px;border-radius:5px;background:#e5484d;opacity:0}
+</style>
+<div id="root" data-composition-id="s01_titulo" data-width="1080" data-height="1920" data-duration="4.8">
+  <div id="s01-card"><span id="s01-txt">UMA VEZ SÓ</span><i id="s01-risco"></i></div>  <!-- risco por baixo das letras -->
+</div>
+<script>
+(function () {
+  // palavras do trecho em segundos da cena; aberta sozinha no estúdio a cena usa os valores padrão
+  const C = (window.__cenas || {})["s01_titulo"] || { palavras: [], duracao: 4.8 };
+  const sem = (s) => s.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]/g, "");
+  const em = (texto, depois = 0, padrao = depois) => {
+    const p = C.palavras.find((w) => w.t >= depois - 1e-3 && sem(w.texto).startsWith(sem(texto)));
+    return p ? p.t : padrao;
+  };
+  const entra = em("vez", 0, 0.8), risca = em("errei", entra, 1.5);
+  const tl = gsap.timeline({ paused: true });
+  tl.fromTo("#s01-card", { opacity: 0, y: 60 }, { opacity: 1, y: 0, duration: 0.35, ease: "back.out(2)" }, Math.max(0, entra - 0.1));
+  // o risco cresce da esquerda com clip-path (escala deixaria dois renders diferentes)
+  tl.fromTo("#s01-risco", { opacity: 1, clipPath: "inset(0% 100% 0% 0%)" }, { clipPath: "inset(0% 0% 0% 0%)", duration: 0.25, ease: "power2.out", immediateRender: false }, risca);
+  tl.to("#s01-card", { opacity: 0, y: -20, duration: 0.25, ease: "power3.in", immediateRender: false }, Math.max(risca + 0.8, (C.duracao || 4.8) - 0.3));
+  window.__timelines["s01_titulo"] = tl;
+})();
+</script>
+</template>
+</body></html>
+```
+
+## Como conferir
+
+1. `python3 build.py amostra <de> <ate>` com o trecho da cena (uns 15 s com motion).
+2. `python3 build.py hf lint` e `python3 build.py hf check` sem erro (o `hf` usa a versão do `package.json`).
+3. `python3 build.py estudio`: a cena aparece numa faixa com o nome dela; arraste a agulha pela entrada e pela
+   saída.
+4. Render só no fim (`python3 build.py hf render --quality draft --output renders/amostra.mp4`) e olhe o
+   arquivo: ele é a referência, não a prévia.
+5. Anote em `eventos.json` (na pasta do projeto) o quadro em que cada mudança de estado pousa, com o tipo do
+   som (`[{"t": 12.4, "tipo": "pop"}]`): o `plano_sfx.py --projeto` junta com os sons das peças.
+
+A cena é sua: o build nunca reescreve os arquivos desta pasta. O estúdio, sim: quando abre o projeto, carimba
+um `data-hf-id` em cada elemento das cenas (e o arquivo muda no disco). É normal. Ao editar a cena depois disso,
+procure o trecho sem contar com o texto exato das tags (uma troca de texto exata falha calada e deixa o elemento
+velho): leia o arquivo de novo antes de mudar, ou troque por expressão que ignora o `data-hf-id`.
+
+## Outras cenas prontas para adaptar
+
+- **Kit 2D**: `compositions/cenas/2d/` com oito cenas `k2d_*.html`: o arquivo de vídeo que muda de estado sem
+  sair do lugar, a conversa no celular que vira pedido confirmado, o esquema que cresce com a fala (etapas,
+  grupos ou causa e efeito), o antes e depois desenhado, a barra que digita o pedido para a IA, o medidor com
+  agulha, a barra de busca com o resultado e a chamada e o bloco de notas com a lista que se conclui. Parâmetros no topo de cada uma; quando usar: `references/animacao.md` da skill, seção Kit 2D.
+- **3D de verdade**: `compositions/cenas/3d/` (o motor `motor-three.js` e quatro cenas `k3d_*.html`, com o
+  three.js r181 em `assets/three`). Como usar e o teste de 5 s: `references/3d.md` da skill.
+- **Legenda à mão (papelaria), manchete, legenda que se escreve**: não são estilos da legenda do modelo (que
+  tem `padrao` e `discreta`). Escreva como cena própria com `"esconde_legenda": true`, usando as `palavras`.
+- **Moldura com o vídeo desfocado atrás**: não precisa de cena, é `"fundo": "desfocado"` no bloco `moldura`.
+  Cena própria só quando o arranjo é outro (vidro fosco nos painéis, dois quadros).

package/editor/modelo-projeto/ferramentas/medir_fontes.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Largura de cada letra das fontes do modelo, medida no próprio arquivo da fonte e no peso que vai para a tela.
+
+O build.py usa esta tabela (assets/fontes/larguras.json) para encaixar o lettering antes de montar a página: quebra
+por sentido, dois momentos e, só por último, letra menor. A Montserrat do modelo é variável e, sem escolher o peso,
+é medida no 100 (bem mais fina que a 900 da tela); aqui cada peso é medido de verdade.
+
+Rode com o Python da skill (tem o Pillow) quando trocar ou acrescentar uma fonte em assets/fontes:
+  uv run --directory '<SKILL>' python '<PROJETO>/ferramentas/medir_fontes.py'
+
+Saída: {"fontes": {"Montserrat": {"arquivo": "...", "pesos": {"900": {"A": 780, ...}}}}, "em": 1000}: a largura de
+cada caractere com a letra de 1000 px (sem kerning; a página com kerning fica igual ou um pouco mais estreita).
+"""
+import json
+import os
+import sys
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+FONTES = os.path.join(os.path.dirname(AQUI), 'assets', 'fontes')
+EM = 1000
+# arquivo, pesos medidos (o que o modelo usa na tela)
+MEDIR = {'Montserrat': ('Montserrat.ttf', (700, 800, 900)), 'Caveat': ('Caveat.ttf', (700,))}
+EXTRAS = '–—‘’“”…•€✓→×'
+
+
+def caracteres():
+    cs = [chr(c) for c in range(32, 127)] + [chr(c) for c in range(160, 256)]
+    return cs + list(EXTRAS)
+
+
+def main():
+    if any(a in ('-h', '--help') for a in sys.argv[1:]):
+        print(__doc__)
+        return 0
+    try:
+        from PIL import ImageFont
+    except ImportError:
+        print('erro: falta o Pillow. Rode com o Python da skill: uv run --directory <SKILL> python ...', file=sys.stderr)
+        return 2
+    saida = {'em': EM, 'fontes': {}}
+    for nome, (arq, pesos) in MEDIR.items():
+        caminho = os.path.join(FONTES, arq)
+        if not os.path.exists(caminho):
+            print(f'aviso: não achei {caminho}', file=sys.stderr)
+            continue
+        por_peso = {}
+        for peso in pesos:
+            f = ImageFont.truetype(caminho, EM)
+            try:
+                eixos = f.get_variation_axes()
+            except OSError:
+                eixos = []
+            if eixos:
+                f.set_variation_by_axes([max(eixos[0]['minimum'], min(eixos[0]['maximum'], peso))])
+            por_peso[str(peso)] = {c: round(f.getlength(c)) for c in caracteres()}
+        saida['fontes'][nome] = {'arquivo': f'assets/fontes/{arq}', 'pesos': por_peso}
+    destino = os.path.join(FONTES, 'larguras.json')
+    with open(destino, 'w', encoding='utf-8') as fh:
+        json.dump(saida, fh, ensure_ascii=False, separators=(',', ':'))
+    print(f'ok: {destino}')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/editor/modelo-projeto/ferramentas/pessoa_recortada.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Pessoa recortada (fundo transparente) no mesmo tempo do cut.mp4, para a tela verde.
+
+Usa o recorte da skill editor-video (helpers/matte.py: modelo selfie_multiclass, fluxo óptico e filtro
+guiado). O recorte é feito trecho por trecho do cut_timeline.json, então o filtro recomeça em cada corte e
+a forma da tomada anterior não vaza para a próxima. Não use o `hyperframes remove-background` para isso:
+ele deixa halo no cabelo e carrega a cor do fundo antigo na borda.
+
+  python3 ferramentas/pessoa_recortada.py --edit '<EDIT>' [--de 28 --ate 32.3]
+      [--skill PASTA_DA_SKILL] [--saida assets/pessoa.webm]
+
+--skill: a pasta da skill editor-video. Sem ele, usa a skill anotada no projeto.json ("skill", que o
+`build.py novo` escreve), depois a skill onde este modelo está (se rodar dentro dela), EDITOR_VIDEO_DIR (se
+existir) e por fim ~/.claude/skills/editor-video e ~/.codex/skills/editor-video, nessa ordem. A primeira linha da
+saída diz qual skill foi usada e de onde ela veio: confira que é a versão certa.
+
+--de/--ate montam o vídeo só desse trecho (bem mais rápido; o recorte em si é feito no corte todo e fica
+guardado). O pessoa.json anota o "inicio", e o build.py usa isso para alinhar com o cut.mp4.
+
+Saídas: assets/pessoa.webm (VP9 com alfa, mesmo tamanho, fps e duração do cut.mp4) e assets/pessoa.json
+(por trecho: onde a pessoa encosta na borda, usado pelo build.py para o lado cortado encostar na tela).
+Leva uns 3 minutos por minuto de vídeo na primeira vez; depois o recorte fica guardado em <EDIT>/renders/matte.
+Precisa do uv e da skill editor-video instalada. Só a biblioteca padrão do Python aqui.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+PROJETO = os.path.dirname(AQUI)
+
+
+def erro(msg, cod=2):
+    print(f'erro: {msg}', file=sys.stderr)
+    sys.exit(cod)
+
+
+def contar_quadros(caminho):
+    r = subprocess.run(['ffprobe', '-v', 'error', '-select_streams', 'v:0', '-count_packets', '-show_entries',
+                        'stream=nb_read_packets', '-of', 'csv=p=0', caminho], capture_output=True, text=True)
+    try:
+        return int(r.stdout.strip().split(',')[0])
+    except ValueError:
+        return -1
+
+
+def skill_padrao():
+    """A skill editor-video instalada: EDITOR_VIDEO_DIR, depois Claude Code, depois Codex."""
+    candidatas = [os.environ.get('EDITOR_VIDEO_DIR') or '',
+                  os.path.join('~', '.claude', 'skills', 'editor-video'),
+                  os.path.join('~', '.codex', 'skills', 'editor-video')]
+    for c in candidatas:
+        if c and os.path.exists(os.path.join(os.path.expanduser(c), 'helpers', 'matte.py')):
+            return os.path.expanduser(c)
+    return os.path.expanduser(candidatas[1])
+
+
+def skill_do_projeto():
+    """a skill anotada no projeto.json ("skill"), ou None"""
+    try:
+        with open(os.path.join(PROJETO, 'projeto.json'), encoding='utf-8') as f:
+            s = str(json.load(f).get('skill') or '').strip()
+    except (OSError, ValueError, AttributeError):
+        return None
+    return os.path.expanduser(s) if s else None
+
+
+def achar_skill(explicita=None):
+    """(pasta da skill, de onde veio): --skill, projeto.json, a skill onde o modelo está, a instalada"""
+    if explicita:
+        return os.path.abspath(os.path.expanduser(explicita)), '--skill'
+    s = skill_do_projeto()
+    if s:
+        return os.path.abspath(s), 'projeto.json ("skill")'
+    pai = os.path.dirname(PROJETO)
+    if os.path.basename(PROJETO) == 'modelo-projeto' and os.path.exists(os.path.join(pai, 'helpers', 'matte.py')):
+        return pai, 'a skill onde o modelo está'
+    return os.path.abspath(skill_padrao()), 'a skill instalada (o projeto.json não diz qual; anote em "skill")'
+
+
+def main():
+    ap = argparse.ArgumentParser(description='pessoa recortada para a tela verde')
+    ap.add_argument('--edit', required=True, help='pasta edit da editor-video (com cut.mp4 e cut_timeline.json)')
+    ap.add_argument('--skill', default=None,
+                    help='pasta da skill editor-video (padrão: o "skill" do projeto.json, a skill onde o modelo está, '
+                         'EDITOR_VIDEO_DIR, ~/.claude/skills/editor-video ou ~/.codex/skills/editor-video)')
+    ap.add_argument('--saida', default=os.path.join(PROJETO, 'assets', 'pessoa.webm'))
+    ap.add_argument('--crf', type=int, default=20)
+    ap.add_argument('--de', type=float, default=None, help='início do trecho (s do corte)')
+    ap.add_argument('--ate', type=float, default=None, help='fim do trecho (s do corte)')
+    a = ap.parse_args()
+    edit = os.path.abspath(os.path.expanduser(a.edit))
+    skill, origem = achar_skill(a.skill)
+    print(f'skill: {skill} ({origem})', flush=True)
+    cut = os.path.join(edit, 'cut.mp4')
+    tl_p = os.path.join(edit, 'cut_timeline.json')
+    for p in (cut, tl_p):
+        if not os.path.exists(p):
+            erro(f'falta {p}')
+    if os.path.islink(cut):
+        # o matte.py resolve o atalho, deixa de reconhecer o cut_timeline.json e recorta tudo como um trecho só
+        # (o filtro não recomeça nos cortes e a tomada anterior vaza na seguinte)
+        erro('o cut.mp4 da pasta edit é um atalho. Deixe o arquivo de verdade lá (a editor-video grava assim).')
+    if not os.path.exists(os.path.join(skill, 'helpers', 'matte.py')):
+        erro(f'não achei a skill editor-video em {skill} (use --skill, ou "skill" no projeto.json)')
+    with open(tl_p, encoding='utf-8') as f:
+        tl = json.load(f)
+    fps, W, H = tl['fps'], tl['width'], tl['height']
+
+    print('recortando a pessoa com a editor-video (a primeira vez leva uns 3 min por minuto de vídeo)...', flush=True)
+    # o progresso sai na hora (a pessoa não fica olhando uma tela parada); o resumo JSON vem no fim
+    # PrimoCode: o Python do editor (venv próprio) vem em PRIMOCODE_EDITOR_PYTHON; sem ele, o uv da skill
+    py = os.environ.get('PRIMOCODE_EDITOR_PYTHON')
+    base = [py] if py and os.path.isfile(py) else ['uv', 'run', '--directory', skill, 'python']
+    proc = subprocess.Popen(base + ['helpers/matte.py', '--edit-dir', edit, '--json'], cwd=skill,
+                            stdout=subprocess.PIPE, text=True, bufsize=1, env=dict(os.environ, PYTHONUNBUFFERED='1'))
+    corpo = []
+    for linha in proc.stdout:
+        if corpo or linha.rstrip('\n') == '{':
+            corpo.append(linha)
+        else:
+            print('  ' + linha.rstrip('\n'), flush=True)
+    if proc.wait() != 0:
+        erro('o recorte da editor-video falhou (veja a mensagem acima)', proc.returncode)
+    if not corpo:
+        erro('não entendi a resposta do matte.py')
+    rep = json.loads(''.join(corpo))
+    trechos = sorted(rep['ranges'], key=lambda x: x['start_frame'])
+    for x, y in zip(trechos, trechos[1:]):
+        if x['end_frame'] != y['start_frame']:
+            erro(f'os trechos do recorte não emendam ({x["id"]} termina em {x["end_frame"]}, {y["id"]} começa em {y["start_frame"]})')
+
+    total = trechos[-1]['end_frame'] - trechos[0]['start_frame']
+    f_ini = max(0, int(round((a.de or 0) * fps)))
+    f_fim = min(total, int(round(a.ate * fps)) if a.ate is not None else total)
+    if f_fim <= f_ini:
+        erro('--ate tem que ser maior que --de')
+    os.makedirs(os.path.dirname(os.path.abspath(a.saida)), exist_ok=True)
+    with tempfile.TemporaryDirectory() as tmp:
+        lista = os.path.join(tmp, 'mattes.txt')
+        with open(lista, 'w', encoding='utf-8') as f:
+            for x in trechos:
+                p = x['file'] if os.path.isabs(x['file']) else os.path.join(edit, x['file'])
+                f.write("file '" + p.replace("'", "'\\''") + "'\n")
+        # cor do cut.mp4 + alfa do recorte, quadro a quadro na mesma ordem (setpts alinha os dois pela contagem)
+        corte = ''
+        if a.de is not None or a.ate is not None:
+            corte = f',trim=start_frame={f_ini}:end_frame={f_fim},setpts=N/({fps}*TB)'
+        filtro = (f'[0:v]setpts=N/({fps}*TB){corte},format=rgba[c];'
+                  f'[1:v]setpts=N/({fps}*TB){corte},format=gray,scale={W}:{H}:flags=area[m];'
+                  f'[c][m]alphamerge,format=yuva420p[v]')
+        cmd = ['ffmpeg', '-v', 'error', '-y', '-i', cut, '-f', 'concat', '-safe', '0', '-i', lista,
+               '-filter_complex', filtro, '-map', '[v]', '-r', str(fps), '-c:v', 'libvpx-vp9', '-pix_fmt', 'yuva420p',
+               '-b:v', '0', '-crf', str(a.crf), '-deadline', 'good', '-cpu-used', '4', '-row-mt', '1',
+               '-auto-alt-ref', '0', '-metadata:s:v:0', 'alpha_mode=1', '-an', a.saida]
+        print('montando o vídeo com fundo transparente...', flush=True)
+        if subprocess.run(cmd).returncode != 0:
+            erro('o ffmpeg falhou ao montar o pessoa.webm', 1)
+    esperado = f_fim - f_ini
+    feito = contar_quadros(a.saida)
+    if abs(feito - esperado) > 1:
+        print(f'aviso: o pessoa.webm tem {feito} quadros e o corte tem {esperado}', file=sys.stderr)
+    info = dict(video=os.path.basename(a.saida), fps=fps, largura=W, altura=H, quadros=feito,
+                inicio=round(f_ini / fps, 4), fim=round(f_fim / fps, 4),
+                trechos=[dict(id=x['id'], de=round(x['start_frame'] / fps, 4), ate=round(x['end_frame'] / fps, 4),
+                              stats=x.get('stats') or {}) for x in trechos])
+    with open(os.path.splitext(a.saida)[0] + '.json', 'w', encoding='utf-8') as f:
+        json.dump(info, f, ensure_ascii=False, indent=1)
+    print(f'ok: {a.saida} ({feito} quadros, {len(trechos)} trechos)')
+
+
+if __name__ == '__main__':
+    main()

package/editor/modelo-projeto/ferramentas/rastrear_maos.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Rastreio das mãos no cut.mp4 (MediaPipe Hand Landmarker) -> assets/maos.json, para o "objeto preso na mão".
+
+  uv run --python 3.12 --with mediapipe==0.10.21 --with numpy python ferramentas/rastrear_maos.py \
+      --edit '<EDIT>' --de 8 --ate 13
+
+Versão fixa de propósito: o mediapipe 1.x (e o Python 3.13) aborta com "Service is unavailable". A primeira vez
+o uv baixa o Python 3.12 e o mediapipe (uns minutos, centenas de MB); avise a pessoa antes. Depois fica guardado.
+
+--de/--ate limitam ao trecho que vai ter o objeto (mais rápido). O modelo hand_landmarker.task (Apache 2.0,
+do Google) é procurado na skill do projeto (o "skill" do projeto.json, em assets/models), depois em
+~/.editor-video/modelos (e na pasta antiga, ~/.sala-de-corte/modelos, sem baixar de novo); se não tiver, é baixado
+na primeira vez para ~/.editor-video/modelos (uns 8 MB). Ou use --modelo.
+
+Regras que já custaram retrabalho:
+- Em cada corte do cut_timeline.json o rastreador recomeça: a mão de uma tomada não pode "pular" para a outra.
+- O rótulo Left/Right do MediaPipe engana (depende de o vídeo estar espelhado). Aqui a mão é nomeada pelo lado
+  da IMAGEM onde ela nasce e segue a trilha: "esquerda_da_imagem" ou "direita_da_imagem".
+- A palma muitas vezes fica perto da borda de baixo. Por isso sai também "nos" (média dos nós dos dedos,
+  pontos 5, 9, 13 e 17): o objeto fica acima deles.
+- Suavização de 3 quadros centrada (atraso zero), sem atravessar corte.
+
+Saída: {fps, largura, altura, cortes, quadros: [{t, maos: [{lado, palma, nos, pts}]}]}, coordenadas de 0 a 1.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+
+MODELO_URL = 'https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task'
+AQUI = os.path.dirname(os.path.abspath(__file__))
+PROJETO = os.path.dirname(AQUI)
+PALMA = (0, 5, 9, 13, 17)
+
+
+COMANDO = ("uv run --python 3.12 --with mediapipe==0.10.21 --with numpy python ferramentas/rastrear_maos.py "
+           "--edit '<EDIT>' --de 8 --ate 13")
+MEDIAPIPE = '0.10.21'
+
+
+def skill_do_projeto():
+    """(pasta da skill, de onde veio) pelo "skill" do projeto.json; senão a skill onde o modelo está; senão None"""
+    try:
+        with open(os.path.join(PROJETO, 'projeto.json'), encoding='utf-8') as f:
+            s = str(json.load(f).get('skill') or '').strip()
+        if s:
+            return os.path.abspath(os.path.expanduser(s)), 'projeto.json ("skill")'
+    except (OSError, ValueError, AttributeError):
+        pass
+    pai = os.path.dirname(PROJETO)
+    if os.path.basename(PROJETO) == 'modelo-projeto' and os.path.exists(os.path.join(pai, 'helpers', 'matte.py')):
+        return pai, 'a skill onde o modelo está'
+    return None, ''
+
+
+def modelo_padrao(skill=None):
+    """a skill do projeto (assets/models), depois ~/.editor-video/modelos; o arquivo baixado antes na pasta antiga
+    (~/.sala-de-corte/modelos) continua valendo"""
+    if skill:
+        na_skill = os.path.join(skill, 'assets', 'models', 'hand_landmarker.task')
+        if os.path.exists(na_skill):
+            return na_skill
+    novo = os.path.join(os.path.expanduser('~'), '.editor-video', 'modelos', 'hand_landmarker.task')
+    antigo = os.path.join(os.path.expanduser('~'), '.sala-de-corte', 'modelos', 'hand_landmarker.task')
+    if not os.path.exists(novo) and os.path.exists(antigo):
+        return antigo
+    return novo
+NOS = (5, 9, 13, 17)
+
+
+def media(pts, idx):
+    return [sum(pts[i][0] for i in idx) / len(idx), sum(pts[i][1] for i in idx) / len(idx)]
+
+
+def main():
+    ap = argparse.ArgumentParser(description='rastreio das mãos para prender um objeto na mão')
+    ap.add_argument('--edit', required=True)
+    ap.add_argument('--de', type=float, default=0.0)
+    ap.add_argument('--ate', type=float, default=None)
+    ap.add_argument('--modelo', default=None, help='hand_landmarker.task (padrão: a skill do projeto, ~/.editor-video/modelos)')
+    ap.add_argument('--saida', default=os.path.join(PROJETO, 'assets', 'maos.json'))
+    a = ap.parse_args()
+    skill, origem = skill_do_projeto()
+    print(f'skill: {skill} ({origem})' if skill else 'skill: nenhuma anotada no projeto.json ("skill"); o modelo de mãos '
+          'vem de ~/.editor-video/modelos', flush=True)
+    a.modelo = a.modelo or modelo_padrao(skill)
+    try:
+        import numpy as np
+        import mediapipe as mp
+        from mediapipe.tasks.python import BaseOptions, vision
+    except ImportError:
+        print(f'erro: falta o mediapipe. Rode assim (a primeira vez baixa uns minutos de pacotes):\n  {COMANDO}',
+              file=sys.stderr)
+        return 2
+    versao = getattr(mp, '__version__', '?')
+    if versao != MEDIAPIPE or sys.version_info[:2] != (3, 12):
+        print(f'aviso: esta ferramenta foi conferida com o mediapipe {MEDIAPIPE} no Python 3.12 (aqui: mediapipe '
+              f'{versao}, Python {sys.version_info[0]}.{sys.version_info[1]}). O mediapipe 1.x aborta com "Service is '
+              f'unavailable". Se der erro, rode:\n  {COMANDO}', file=sys.stderr, flush=True)
+    edit = os.path.abspath(os.path.expanduser(a.edit))
+    with open(os.path.join(edit, 'cut_timeline.json'), encoding='utf-8') as f:
+        tl = json.load(f)
+    fps, W, H, dur = tl['fps'], tl['width'], tl['height'], tl['duration']
+    ate = min(a.ate if a.ate is not None else dur, dur)
+    f0, f1 = int(round(a.de * fps)), int(round(ate * fps))
+    cortes = sorted(int(s['out_start_frame']) if 'out_start_frame' in s else int(round(s['out_start'] * fps))
+                    for s in tl['segments'] if s['out_start'] > 0.01)
+    if not os.path.exists(a.modelo):
+        os.makedirs(os.path.dirname(a.modelo), exist_ok=True)
+        print('baixando o modelo de mãos do MediaPipe (uns 8 MB)...', flush=True)
+        urllib.request.urlretrieve(MODELO_URL, a.modelo)
+
+    def novo():
+        op = vision.HandLandmarkerOptions(base_options=BaseOptions(model_asset_path=a.modelo), num_hands=2,
+                                          running_mode=vision.RunningMode.VIDEO, min_hand_detection_confidence=0.5,
+                                          min_hand_presence_confidence=0.5, min_tracking_confidence=0.5)
+        return vision.HandLandmarker.create_from_options(op)
+
+    # quadros exatos, em sequência, por pipe (menor lado 540 basta para as mãos; as coordenadas saem de 0 a 1)
+    esc = 540 / min(W, H)
+    w2, h2 = int(round(W * esc / 2)) * 2, int(round(H * esc / 2)) * 2
+    cmd = ['ffmpeg', '-v', 'error', '-ss', f'{f0 / fps:.4f}', '-i', os.path.join(edit, 'cut.mp4'), '-frames:v', str(f1 - f0),
+           '-vf', f'scale={w2}:{h2}', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-']
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+    lm, cruas = novo(), {}
+    n = f0
+    while n < f1:
+        buf = proc.stdout.read(w2 * h2 * 3)
+        if len(buf) < w2 * h2 * 3:
+            break
+        if n in cortes and n != f0:
+            lm.close()
+            lm = novo()
+        img = mp.Image(image_format=mp.ImageFormat.SRGB, data=np.frombuffer(buf, np.uint8).reshape(h2, w2, 3))
+        res = lm.detect_for_video(img, int(round(n * 1000 / fps)))
+        cruas[n] = [[[p.x, p.y] for p in hand] for hand in res.hand_landmarks]
+        n += 1
+    proc.stdout.close()
+    proc.wait()
+    lm.close()
+    nfim = n
+
+    # trilhas: casa cada mão com a do quadro anterior pela palma, só dentro da mesma tomada
+    trilhas, ativas, prox_id = {}, [], 0
+    for n in range(f0, nfim):
+        if n in cortes:
+            ativas = []
+        novas = []
+        livres = list(ativas)
+        for pts in cruas.get(n, []):
+            pm = media(pts, PALMA)
+            melhor = min(livres, key=lambda tr: (tr['ult'][0] - pm[0]) ** 2 + (tr['ult'][1] - pm[1]) ** 2, default=None)
+            if melhor and ((melhor['ult'][0] - pm[0]) ** 2 + (melhor['ult'][1] - pm[1]) ** 2) ** 0.5 < 0.15 and n - melhor['n'] <= 3:
+                livres.remove(melhor)
+                tr = melhor
+            else:
+                tr = dict(id=prox_id, lado='esquerda_da_imagem' if pm[0] < 0.5 else 'direita_da_imagem', q={})
+                prox_id += 1
+            tr['ult'], tr['n'] = pm, n
+            tr['q'][n] = pts
+            trilhas[tr['id']] = tr
+            novas.append(tr)
+        ativas = novas + [tr for tr in livres if n - tr['n'] <= 3]
+        lados = novas
+        if len(lados) == 2 and lados[0]['lado'] == lados[1]['lado']:
+            e, d = sorted(lados, key=lambda tr: tr['ult'][0])
+            e['lado'], d['lado'] = 'esquerda_da_imagem', 'direita_da_imagem'
+    quadros = {k: [] for k in range(f0, nfim)}
+    for tr in trilhas.values():
+        ks = sorted(tr['q'])
+        for k in ks:   # média de 3 quadros centrada; na ponta da trilha fica o quadro cru
+            viz = [tr['q'][j] for j in (k - 1, k, k + 1) if j in tr['q'] and not (j != k and (max(j, k) in cortes))]
+            pts = [[sum(v[i][0] for v in viz) / len(viz), sum(v[i][1] for v in viz) / len(viz)] for i in range(21)]
+            quadros[k].append(dict(lado=tr['lado'], palma=[round(x, 4) for x in media(pts, PALMA)],
+                                   nos=[round(x, 4) for x in media(pts, NOS)], pts=[[round(x, 4), round(y, 4)] for x, y in pts]))
+    saida = dict(fps=fps, largura=W, altura=H, cortes=[round(c / fps, 4) for c in cortes],
+                 quadros=[dict(t=round(k / fps, 4), maos=quadros[k]) for k in sorted(quadros)])
+    os.makedirs(os.path.dirname(os.path.abspath(a.saida)), exist_ok=True)
+    with open(a.saida, 'w', encoding='utf-8') as f:
+        json.dump(saida, f, separators=(',', ':'))
+    com = sum(1 for k in quadros if quadros[k])
+    print(f'ok: {a.saida} · {len(quadros)} quadros de {f0 / fps:.2f} a {nfim / fps:.2f} s · mão em {com} · {len(trilhas)} trilha(s)')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/editor/modelo-projeto/hyperframes.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
+  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
+  "paths": {
+    "blocks": "compositions",
+    "components": "compositions/components",
+    "assets": "assets"
+  },
+  "media": {
+    "autoProxy": true
+  }
+}

package/editor/modelo-projeto/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "editor-video-projeto",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npx --yes hyperframes@0.8.79 preview",
+    "lint": "npx --yes hyperframes@0.8.79 lint",
+    "check": "npx --yes hyperframes@0.8.79 check",
+    "render": "npx --yes hyperframes@0.8.79 render"
+  }
+}