Sachin-pro-dev/PITCHFRAME-push-to-prod

Geração de código e renderização

Você está transformando um briefing em plan.json e renderizando-o. O projeto de referência já implementa a gramática do vídeo de lançamento — você está fornecendo os dados, não escrevendo um vídeo do zero.

O nível de polimento do projeto de referência é o nível de polimento de todo vídeo que esta ferramenta produzirá. Portanto, o padrão forte é: escreva plan.json, não mude mais nada. Cada linha de animação personalizada que você adiciona a uma execução é polimento que nunca chega ao próximo vídeo e uma nova maneira de a renderização quebrar.

O mapa de arquivos

pitchframe/
├── plan.json               ← o plano de cenas. Este é o vídeo.
├── palette.json            ← cores extraídas. Dados, nunca prosa.
├── public/assets/*.png     ← capturas de tela.
├── scripts/
│   ├── extract-palette.mjs ← tailwind → variáveis CSS → URL ativa
│   ├── apply-palette.mjs   ← escreve src/theme.ts a partir de palette.json
│   └── capture.mjs         ← servidor de desenvolvimento + captura Playwright
├── src/
│   ├── Root.tsx            ← registra a composição LaunchVideo
│   ├── LaunchVideo.tsx     ← mapeia batidas para Sequences. Gerencia o cross-dissolve.
│   ├── theme.ts            ← GERADO. Todas as cores são resolvidas aqui.
│   ├── lib/
│   │   ├── types.ts        ← o contrato do plano
│   │   └── motion.ts       ← easing, fades, pulso de clique, drift sustentado
│   ├── components/         ← Background, Cursor, FocusOverlay, Zoom, Panel, …
│   └── scenes/
│       ├── TypographyBeat.tsx
│       ├── InteractionBeat.tsx   ← o momento principal
│       ├── UIBeat.tsx
│       └── CTABeat.tsx
└── output.mp4

Escrevendo o plano

Carregue pitchframe-launch-video para a estrutura e esquema. A versão resumida:

• Quatro partes — configuração, momento principal, retorno, CTA. Nessa ordem. Sempre.
• Exatamente uma batida de interaction, e ela recebe pelo menos 30% dos quadros.
• A duração vem de thesis_weight no briefing, não de um padrão.
• Copie video_thesis e hero_moment para o plano para que a passagem de crítica possa verificar o vídeo em relação à afirmação.

Acertar a aritmética antes de renderizar

Uma renderização falha custa dois minutos; um plano cujas batidas se desviam custa uma re-renderização mais o tempo para perceber. Verifique manualmente, toda vez:

• Batidas contíguas — cada frames[0] é igual ao frames[1] anterior.
• A primeira batida começa em 0; a última batida termina exatamente em total_frames.
• total_frames === duration_seconds * fps.
• Nenhuma batida de tipografia com menos de 45 quadros.
• Batida de interação ≥ 30% de total_frames.

Raciocinar sobre coordenadas, não adivinhá-las

target_element.coordinates e zoom_target são porcentagens da captura de tela. Elas são afirmações sobre onde estão os pixels interessantes, e um ponto focal 10% fora do centro centraliza a tomada principal em um chrome vazio.

Abra a captura de tela, encontre o elemento, converta para porcentagens e verifique se o resultado está de acordo com o que a batida deve mostrar. Quando a consequência de uma ação ocorre em outro lugar que não o alvo — o destino de um arrasto, um campo que é atualizado em outro lugar — aponte zoom_target para a consequência, não para a coisa que o cursor tocou.

Cores: nunca no plano, nunca em um componente

theme.ts é gerado por apply-palette.mjs a partir de palette.json. É o único lugar onde uma cor é registrada.

node pitchframe/scripts/extract-palette.mjs      # → palette.json
node pitchframe/scripts/apply-palette.mjs        # → src/theme.ts

Regras que decorrem disso:

• Nunca coloque uma cor em plan.json. O plano diz qual palavra é destacada; o tema diz qual é o destaque.
• Nunca coloque um literal de cor em um componente. Se você precisar de um tom que o tema não expõe, adicione um token derivado ao gerador para que todo vídeo futuro também o receba.
• Nunca edite manualmente theme.ts. Ele é sobrescrito na próxima geração.

Se os vídeos de dois produtos parecerem com cores idênticas, theme.ts não foi regenerado. Isso é a primeira coisa a verificar, antes de tocar em qualquer outra coisa.

A renderização

cd pitchframe && npx remotion render LaunchVideo output.mp4

Três verificações primeiro, custando um segundo e economizando uma renderização falha de dois minutos:

1. plan.json é analisado; a aritmética acima é válida.
2. Cada captura de tela nomeada no plano existe em public/assets/. Uma batida de interação precisa tanto de before_screenshot quanto de after_screenshot.
3. node_modules existe em pitchframe/. Se não, execute npm install lá primeiro.

Espere de 20 a 60 segundos para um vídeo de 20 segundos.

Quando a renderização falha

Leia o erro real antes de mudar qualquer coisa.

Sintoma	Causa	Correção
Cannot find module '../plan.json'	Scaffold incompleto	Reexecute npx pitchframe install
Cannot find name 'ACCENT' etc.	theme.ts não gerado	Execute apply-palette.mjs
Tempo limite de renderização de fontes atrasado	Off-line, ou uma fonte não no Google Fonts	Defina fonts.sans como Inter em palette.json e regenere
Erro de decodificação de imagem	Captura de tela corrompida ou parcial	Recapture essa imagem
Incompatibilidade de duração da composição	total_frames discorda das batidas	Corrija a aritmética
OOM / falha do Chrome	Capturas de tela enormes	Reduza tudo acima de ~4000px de largura; --concurrency=2

Nunca responda a uma falha de renderização reescrevendo a composição. Corrija os dados.

Se a renderização falhar duas vezes, pare e preserve as evidências. Deixe plan.json, palette.json e os assets no lugar e diga qual arquivo examinar. Uma renderização falha com um plano inspecionável é recuperável; uma que foi "corrigida" por uma reescrita não é.

Quando você precisa mexer nos componentes

Apenas quando um plano precisar de algo que os componentes de batida realmente não conseguem expressar. Três regras se você chegar lá:

1. Adicione, nunca reescreva. Um novo movimento de câmera é uma entrada em SHOTS em lib/camera.ts, não um componente reestruturado — e deve estar listado em pitchframe-motion-language ou nada nunca o escolherá.
2. Use lib/motion.ts e lib/camera.ts. EASE, EASE_OUT, clickPulse, heldDrift, entranceBlur são o gênero. Easing feito à mão é como uma batida acaba parecendo que veio de um vídeo diferente. Molas, saltos e curvas elásticas são proibidos. Existe exatamente um sistema de câmera. Não adicione perspective ou uma transformação 3D fora de Stage.tsx; este repositório já teve dois, eles se desviaram e as tomadas pararam de parecer que foram filmadas pela mesma pessoa.
3. Mantenha orientado a dados. Qualquer coisa que você adicionar deve ser acionável a partir de um campo em plan.json. Se a única maneira de acioná-lo é editando o componente, é algo único e não pertence à referência.

Sempre errado aqui: um literal de cor; o nome ou cópia do produto codificado em um componente; uma nova composição de nível superior; alterar o contrato 1920×1080 / 30fps; importar uma biblioteca de animação.

Adicionar um tipo de batida é quase sempre a resposta errada. O esquema tem quatro porque um vídeo de lançamento precisa de quatro. Um novo tipo de batida é geralmente uma batida de recurso disfarçada, e no momento em que o esquema pode expressar uma lista de recursos, os planos começam a conter uma.

Após uma renderização bem-sucedida

Informe o caminho e a capacidade de edição:

Pronto. Vídeo disponível em ./pitchframe/output.mp4

Para editar, basta pedir:
  "segure o momento principal por mais tempo"
  "zoom no campo que mudou em vez disso"

A edição é tratada por pitchframe-editing, não pela reexecução do pipeline.