# Pipeline de reconstrução

## Decisões atuais

- **Alvo:** navegador desktop, experiência do Car Town Facebook. Não portar Streets/Racing.
- **Baseline provisória:** interface e conteúdo documentados em maio de 2013. Não significa que toda regra de 2010 continuava idêntica.
- **Entrega atual:** oficina com 24 serviços, cinco tamanhos de garagem, instalações, seis profissões, treinamento e políticas de automação; nove carros com condição/preparação, mercado de projetos/peças, restauração e revenda, arrancadas jogáveis, carreira, viagens, concursos, coleções e desafios. Persistência local e laboratório em `lab.html` preservados. Não equivale ao catálogo completo do original.
- **Ferramentas atuais:** Babylon.js e loader glTF, TypeScript, Vite, Blender instalado via Homebrew, `blender-ctl`, `node:test` e `agent-browser`. Dependências da engine ficam no lockfile; a ferramenta de Blender é local da máquina, não parte do bundle web.
- **Decisão de migração:** o usuário rejeitou os carros SVG. A base passa a ser 3D real com modelos GLB e câmera ortográfica. Babylon foi escolhido, com autorização, por integrar picking, animação, materiais, sombras e recursos de jogo; Three.js também pode produzir boa imagem, mas não elimina a necessidade de modelagem e direção de arte. Não presumir que usar uma engine certifica a qualidade dos carros.

## Ordem de trabalho e portas de aceite

### Referência antes de código

Escolher uma tela concreta da [investigação](research.md), época e estado: garagem inicial, cliente aguardando, serviço aberto, conclusão, loja, edição ou corrida. Uma screenshot demonstra composição; para sequência e tempo é necessário vídeo ou descrição operacional datada.

Ao analisar vídeos, anotar URL, timestamp realmente assistido, ação, estado anterior e resultado observável na própria investigação. Não criar uma planilha paralela com a mesma informação. Começar pelos vídeos contemporâneos já identificados e pela oficina, não pelo catálogo inteiro de eventos.

**Aceite:** referência legível para cada tela a construir; campos sem fonte marcados como desconhecidos. A data do vídeo não comprova por si só cada mecânica.

### Experimento de representação

Manter uma cena representativa com piso, duas paredes, um veículo, uma pessoa e uma estação. Usar arte própria ou autorizada; arte provisória deve ser identificada, não apresentada como fidelidade final.

Validar pela superfície real: câmera fixa, relação visual entre ruas e oficina, escala, oclusão, clique nos limites da geometria, redimensionamento e legibilidade no viewport. Comparar a captura com o recorte da referência no laboratório. A projeção adotada é decisão da reconstrução, **não medida confirmada do original**.

**Aceite:** demonstração reproduzível de composição, oclusão e seleção correta em um viewport conhecido, sem usar screenshots do original como cenário do jogo. Babylon/WebGL já foi autorizado; dependências adicionais continuam exigindo aprovação.

### Primeiro fluxo jogável de oficina

Cliente aguardando → seleção → serviço e estação disponíveis → execução temporizada → conclusão → coleta → moedas/XP atualizados → estação liberada. O estado deve ter identificadores estáveis para cliente, estação e trabalho, e transições explícitas; os nomes definitivos serão escolhidos na implementação.

Antes de programar, resolver ou identificar como decisão experimental: valor e transação do débito inicial, duração, recompensa, pré-condições de funcionário e estação, expiração e estado após recarregar. O guia oficial de 2012 confirma que existe custo para iniciar serviços, não fornece aqui a tabela completa. Não preencher lacunas com valores alegadamente originais. Combustível é documentado para High Stakes e Street Challenge; não inventar custo de gasolina por clique na oficina.

**Aceite:** fluxo inteiro executado por cliques no navegador, inspeção de saldo/ocupação e captura dos estados relevantes. Coleta repetida não duplica recompensa; estação ocupada não aceita outro trabalho; avanço do relógio não depende de esperar minutos reais. Cobrir apenas os riscos efetivamente introduzidos, sem construir subsistemas sociais fictícios.

### Expansão por telas completas

Depois do fluxo de oficina: edição da garagem e expansão; coleção/loja; personalização e aplicação visível; corrida e feedback das trocas; progressão/missões; restauração/localidades; recursos sociais reais. Essa ordem organiza dependências, **não elimina funcionalidades do objetivo final**.

Para cada tela: referência → comportamento observável → implementação → interação real → comparação visual. Reavaliar o escopo com o usuário antes de adiar ou substituir uma mecânica solicitada. Eventos licenciados dependem de material e direitos específicos; não presumir autorização por aparecerem no original.

## Loop de feedback disponível agora

1. Subir o servidor indicado no README.
2. Abrir o laboratório; selecionar referência datada.
3. No jogo, executar o cenário e capturar o viewport/estado documentado. Usar `?debug=1` para relógio determinístico sem alterar o progresso normal.
4. Carregar a captura no laboratório. Comparar em 0%, 50% e 100%, com o mesmo recorte e escala. Margens Facebook e letras editoriais não são área de jogo.
5. Corrigir um problema concreto: enquadramento antes de detalhe, comportamento antes de efeitos.
6. Rodar o menor check do consumidor alterado. `aube run test` verifica o domínio; `tools/game_smoke.py` exercita a oficina e persistência; `tools/expansion_smoke.py` exercita os novos fluxos e a corrida por entradas reais; `tools/smoke.py` verifica o laboratório. Nenhum certifica fidelidade histórica automaticamente.

Não usar pixel diff como métrica absoluta entre versões com animações, fontes, transparências ou recortes diferentes. Uma referência anotada também contém material que não deveria ser reproduzido no jogo.

## Contrato de observabilidade implementado

Disponível somente em `?debug=1`, sem ler/escrever o save normal:

| Operação | Requisito |
|---|---|
| `window.carTownDebug.snapshot()` | Cópia JSON serializável do estado relevante: saldo, XP, relógio, seleção, clientes, estações e trabalhos. Não expor objetos mutáveis internos. |
| `window.carTownDebug.reset(fixture)` | Restaurar fixture conhecida, relógio e estado inicial; cancelar efeitos pendentes. Não afetar saves reais ou contas. |
| `window.carTownDebug.advanceTime(ms)` | Avançar relógio controlado que a lógica real já usa. Não simular conclusão por um caminho paralelo de teste. |
| `window.carTownDebug.projectEntity(id)` | Coordenadas de tela de um objeto para mover o mouse e clicar no canvas real; não dispara seleção artificial. |
| `window.carTownDebug.projectTile(x, y)` | Projeção de uma casa do piso para exercer edição com ray picking. |
| `window.carTownDebug.renderer()` | Estatísticas da engine e do cache de prévias; não substituir prova visual por contagens. |

As operações usam a mesma lógica dos cliques reais. `snapshot()` devolve cópia do estado; `advanceTime` aceita inteiros de zero até sete dias e não existe no modo normal. Catálogos básicos ficam em `catalogs.mjs`; o modelo coordena `projects.mjs`, `activities.mjs` e `career.mjs`. UI/storage/relógio ficam em `app.mjs` e `journey-ui.mjs`; renderização em `world.ts`, `vehicle-view.ts` e `race-view.ts`.

Fixtures `default`, `occupied`, `ready` e `poor` exercitam os estados básicos; `progression` fornece moedas/XP, mas deixa compras e conquistas para controles reais. O relógio fica congelado até avanço explícito, exceto na corrida, que avança segundos reais para validar habilidade. `advanceSimulation` é o mesmo consumidor no relógio real e debug. Reset descarta efeitos pendentes. A aceitação inclui controles nativos, corrida por teclado e inspeção de capturas.

### Invariantes da progressão

- O cliente carrega `requestedServiceId`; iniciar outro serviço é inválido. Requisitos são definidos nos catálogos, não duplicados na UI.
- Cada trabalho guarda sua cotação: prazo, recompensa, XP e nível de serviço. Melhorias posteriores não alteram contratos já iniciados.
- O save de versão 4 mantém a chave existente e migra saves válidos das versões 1, 2 e 3. Não descartar coleção, posições, moedas, equipe ou trabalhos; não reprecificar cotações históricas. As extensões do v4 são obrigatórias e validadas antes de carregar.
- Um mecânico só pode estar atribuído a uma estação; uma estação só pode ter um mecânico contratado. A recepcionista entrega trabalhos, mas não cria recompensa sem trabalho concluído.
- O limite de profissionais de estação é compartilhado entre todas as especialidades, não um limite por profissão. Especialistas priorizam pedidos compatíveis e têm bônus maior na sua área; custos, pagamentos e lucro são exibidos separadamente.
- Automação ligada inicia pedidos que podem ser pagos e entrega trabalhos prontos pelos mesmos validadores das ações manuais. Não executa ciclos históricos ilimitados ao recarregar; trabalhos novos começam no horário atual.
- Só a cena escreve os rótulos flutuantes dos carros. A UI atualiza seus próprios timers de painel. Não alternar textos concorrentes, recriar spans a cada tick ou reiniciar animações de rótulo.
- Projetos reservam carro/estação; viagens e corridas reservam carro. O restore integrado verifica cruzamentos depois de ter as duas extensões. Ganhos de condição até 100 e epochs reais são válidos.
- Estoque guarda base de custo por grade. Consumo usa a quantidade anterior à baixa; peças gratuitas não aumentam o investimento. Recompensas não ultrapassam a capacidade e falhas de resgate deixam o prêmio disponível.
- Contratos contam ações posteriores à aceitação; objetivos de coleções usam total permanente. A campanha não pode exigir novas conquistas de um conjunto finito já consumido.
- Na pista, uma cena usa a engine da oficina; o HUD envia entradas temporizadas. Pontuação e prêmio são calculados pelo domínio e resgatados uma vez. Sair não elimina a sessão, mas o relógio continua.
- Prontidão inclui identidade/prazo da atividade. Ao passar para pronto, reconstruir os controles do diálogo, não apenas seu timer; não perder transições entre atividades consecutivas rápidas.



## Pipeline de arte e procedência

Separar imagens de pesquisa (`references/images/`) de futuras artes de runtime. Cada arte incorporada precisa de origem/permissão, tamanho, pivô, orientação e relação com o piso, documentados perto do asset quando ele existir. Não criar manifestos sem consumidor.

Antes de ampliar um catálogo, validar **um** carro e **uma** estação pela renderização final: vidro, pintura, luz, sombra de contato, pivô e escala. O projeto adotou modelos 3D em tempo real; isso não prova o formato interno do original. Definir direções de rotação a partir da referência, não supor que um espelhamento preserve detalhes assimétricos.

Clientes Flash eventualmente recuperados devem ser tratados como material de análise, não runtime web moderno. Só iniciar extração com origem verificável, workspace isolado e inspeção apropriada; nenhuma recuperação foi feita nesta preparação.

### Contrato da arte 3D

- Fontes editáveis em `assets/vehicles/`; entrega de runtime em `public/assets/cars/{starter,compact,coupe,van,muscle,roadster,sedan,pickup,suv}.glb`. Modelos autorais, não arquivos extraídos do Car Down. Uma nova origem externa exige licença e atribuição verificadas.
- GLB 2.0 sem compressão que introduza codecs externos, geometria e materiais embutidos. glTF Y para cima, frente +Z, eixo das rodas X e contato dos pneus em Y=0; origem central. No Blender, frente -Y antes da conversão glTF. A cena Babylon usa sistema destro para não espelhar o arquivo novamente.
- Materiais de personalização: `Paint_Body` para pintura e `Wheel_Rim` para rodas. `Glass`, `Rubber`, `Chrome`, `Light_Front`, `Light_Rear` e `Cabin` não devem ser recoloridos junto com a carroceria. Preservar separação de meshes e nomes das quatro rodas para evolução de animação.
- Cada carro precisa de silhueta própria, painéis curvos, arcos de rodas, vidros separados, pneus espessos e detalhes legíveis. Cubos com rodas ou contagens de polígonos não são critério de aprovação.
- O mundo mantém engine/cena e objetos vivos entre transições. Prévias são renderizadas dos mesmos GLBs, com recurso offscreen reutilizado e cache limitado; não criar um contexto WebGL por card.
- `build.py` regenera a arte inicial. O `.blend` também serve à edição humana: alterações manuais não podem ser descartadas por uma regeneração automática. Não confundir exportar o arquivo editado com reconstruí-lo pelo script.

### Controle de Blender para agentes

Foi pesquisado e autorizado o [`blender-cli` 0.8.1](https://github.com/renezander030/blender-cli), exposto nesta máquina por `blender-ctl`. Inspeção JSON, snapshot em quatro vistas e exportação GLB com releitura foram executados no Blender 5.3. O autor declara testes em 4.3/5.2, portanto o restante da superfície não está certificado aqui.

Preferir `scene`/`snapshot` para observar o resultado e `render` para materiais/iluminação; Workbench não demonstra fidelidade do PBR no navegador. Não habilitar add-ons ou instalar instruções do agente automaticamente. Não há servidor ou socket de controle necessário; scripts continuam tendo acesso ao sistema, e o modo safe não é uma sandbox garantida.

## Limites de aceite atuais

Os smokes exigem servidor acessível e `agent-browser`. O laboratório continua manual e sem alinhamento automático. Os fluxos locais têm save e cenários próprios, mas não reproduzem exatamente a economia, pistas e eventos históricos, nem incluem áudio, backend ou multiplayer. Não atribuir duração de campanha ou diversão a um teste automatizado: exigem playtest. Manter as portas de aceite e distinguir funcionalidade de fidelidade histórica/visual.
