codepawl/machine-anatomy

Anatomia de Máquina

Um kit compartilhado: uma nova máquina escreve apenas seu modelo, seu layout e desenho, seus hooks ao vivo e seus fatos. O kit possui a página, os temas e estilos, o quadro de zoom, a vista explodida, o verificador de verdade, o gravador, o som e as verificações. O exemplo prático é examples/edison-light-bulb/; copie sua estrutura.

1. Pergunte uma vez, depois construa

Antes de qualquer código, faça ao usuário as perguntas de coleta em uma rodada com a ferramenta de perguntas do anfitrião (AskUserQuestion no Claude Code), cada uma com seu valor padrão recomendado, pulando qualquer coisa que já tenham dito. Em seguida, prossiga sem novas interrupções. Perguntas, padrões e como cada resposta mapeia para configuração: references/intake.md.

2. Pesquise, depois fatos

Leia fontes reais (patente, artigos do inventor, página de museu, enciclopédia). Escreva reference/notes.md com URLs e citações, depois facts.json: uma entrada por fato com text, source, quote ou note, e status (verified ou inferred). Regras e o que o lint impõe: references/truth-control.md. Liste todas as funções da máquina e seu cenário a partir das fontes em functions.

Em seguida, colete pelo menos 3 fotos ou desenhos reais da máquina e seu cenário em reference/images/ com sources.json, e abra cada um antes de desenhar; cada montagem nomeia as imagens a partir das quais foi desenhada. O lint impõe isso e record escreve shots/reference-compare.png para conferência: references/reference-images.md.

3. Construa a pasta da máquina

node cli.mjs new <pasta> --title "..." cria a estrutura a partir do exemplo Edison. Substitua nesta ordem:

1. model.mjs — modelo puro, sem DOM; todo o comportamento e cada número exibido. test-model.mjs o testa contra valores reais ou invariantes. Testes são obrigatórios.
2. layout.mjs — tamanhos em unidades do mundo e curvas calculadas (caminhos seguem peças reais, nunca cordas).
3. figure.mjs — drawFigure(draw): desenhe as peças reais como itens de montagens numeradas com os auxiliares do kit; retorne label, defs, css, âncoras de badge, pontos de passo e o alvo do zoom.
4. live.js — createMachineHooks(kit): estado, desenho de partes móveis, controles, leitura, ações. Use kit.Motion para molas, inércia e juntas: references/motion.md.
5. machine.mjs — montagens com eixos de remoção e proveniência, todo texto visível como { text, facts }, modelos de leitura, controles, história do filme, vozes do som.

Leia os arquivos correspondentes do exemplo antes de escrever cada um; não leia arquivos *.html compilados.

4. Visualize

Tema e estilo de renderização são camadas independentes: references/themes-and-styles.md. Defina os padrões em machine.mjs (theme, style); qualquer página alterna com ?theme= e ?style=.

5. Filme e som

O filme padrão tem a forma aprovada de 30 s (funcionando primeiro, um zoom de nascimento, uma execução lenta legendada, funcionamento normal com um momento de contraste, desmontagem escalonada, remontagem, encerramento funcionando): references/film.md. O som é de toques suaves de microfone próximo, sem bipes, sem limitador: references/sound.md. Regras de legenda para publicação do filme: references/caption.md.

6. Comandos e verificações (todos obrigatórios antes de entregar)

node cli.mjs lint   <pasta>     # textos ligados a fatos, fontes, superlativos, proveniência
node cli.mjs test   <pasta>     # testes do modelo
node cli.mjs build  <pasta> [--format 16:9,9:16,square]
node cli.mjs audit  <pasta>     # ordem de pintura da vista explodida e passagem
node cli.mjs verify <pasta>     # página real no Chrome headless, cada tema e estilo
node scripts/lines.mjs <pasta>/<slug>-anatomy.html   # linhas de textura terminam em algo
node cli.mjs record <pasta> [--format 9:16] [--style dither] [--no-sound]
node cli.mjs remux  <pasta>     # alteração apenas de som nos quadros gravados
npm test                         # testes unitários do kit

Playwright não está incluído: npm install --no-save playwright, ou defina MACHINE_ANATOMY_PLAYWRIGHT para um index.mjs do Playwright existente. A gravação roda em prioridade normal e sem GPU.

Em seguida, abra shots/<variante>/video-sheet.png, três stills, as capturas de tela da verificação e shots/reference-compare.png você mesmo; corrija cortes, sobreposições, texto ilegível, padrões flutuantes e toda diferença em relação às imagens de referência que não seja uma simplificação declarada.

Regras definidas pelo proprietário (aplicadas onde há verificação)

• Nada cobre nada: uma verificação de colisão no record e verify (references/film.md); declare apenas sobreposição fisicamente real, com seu motivo, em film.overlapAllowed.
• Mostre a máquina em seu cenário real completo (pergunta de coleta 10), com fonte, com proveniência.
• O assunto ocupa pelo menos 25% da altura do quadro em cada fase e eventos-chave acontecem na tela (minimum.subject, film.onScreen); uma máquina em movimento executa uma câmera com hooks.camera().
• Padrões permanecem fixos às superfícies e não flutuam; meça com scripts/swim.mjs (references/themes-and-styles.md).
• Fogo, vapor, fumaça e brilho vêm de kit/effects.mjs, acionados pelo modelo (references/motion.md).
• Cada parte funcional é mostrada funcionando ou tem um motivo declarado; nenhum movimento sem uma causa ativa desenhada; tempo comprimido é mostrado na tela (references/completeness-and-causality.md, lint e record).

Relatório

Caminhos da página, fragmento de publicação e filmes; contagens de lint, teste, auditoria, verificação e linhas; loudness, pico verdadeiro e espectro do filme (diga que ninguém ouviu); a linha do tempo do filme; cada fato de legenda com sua fonte; o que é simplificado, inferido ou não verificado.

Crédito: construído sobre Anatomy por Ryan (github.com/wheresryan22/anatomy, MIT). Consulte THIRD_PARTY_NOTICES.md.