automatorsplus/immersive-3d-site

O que immersive-3d-site faz?

Uma página onde o 3D é vivo, não um vídeo de 3D. A rolagem do visitante é a linha do tempo, e o cursor é uma segunda câmera. O texto real fica por cima, legível e selecionável; o canvas WebGL fica atrás dele.

O que você entrega: uma pasta de build com BRIEF.md, um index.html real, os arquivos do motor ao lado, e uma faixa de screenshots de desktop, celular e movimento reduzido, além de um breve relatório do que você verificou e do que não pôde.

O que faz essas páginas falharem

A maioria dos "sites 3D" é um único truque mantido por toda a página: um modelo girando com texto sobrepondo-se. Na terceira seção, o visitante já viu tudo e para de rolar. Quatro regras impedem isso:

1. Cada ato faz algo diferente. Use pelo menos quatro dispositivos de cena diferentes de references/scene-kit.md, nunca o mesmo duas vezes seguidas.
2. Um pico. Um ato é o momento que alguém descreve a um amigo. Ele recebe o maior espaço de rolagem, a melhor cena, e um ato mais calmo antes dele para que o impacto seja maior.
3. O 3D serve à mensagem. Cada cena mostra algo verdadeiro sobre o assunto: do que é feito, como funciona, como é sentido. Uma cena que é apenas decoração é cortada.
4. O texto permanece legível em toda posição de rolagem. Se uma linha for difícil de ler sobre a cena em qualquer quadro, a cena se move, não o texto.

Passo 0: O brief

Reutilize o que o usuário já lhe deu. Se ele deu um brief completo ou disse "use seu julgamento", escreva você mesmo BRIEF.md, marque-o como Escrito sob delegação criativa, responda você mesmo a todas as perguntas abaixo na voz da marca e vá em frente. Caso contrário, faça todas as oito em uma única mensagem, como perguntas reais, nunca um menu que você inventou:

1. O que é, para quem é e o que eles devem fazer no final? Uma ação, um rótulo usado em todos os lugares.
2. A sensação em três a cinco palavras, além de até três referências de qualquer coisa, menos sites: um filme, um jogo, uma capa de álbum, uma loja. Nomear sites é como uma página acaba copiando um.
3. A jornada nas palavras deles: o que o visitante vê primeiro, depois, por último.
4. Onde deve ser calmo e onde deve ser intenso.
5. Como alguém deve se sentir em cada etapa, e o único momento que deve lembrar. Veja references/feel.md.
6. Uma coisa que este site deve fazer que nenhum site que eles viram faz. A semente do movimento característico. Insista por uma resposta real; "ser memorável" não é uma.
7. Quão longe do premium-mínimo: ofereça o intervalo em references/structures.md.
8. Um mundo contínuo, ou cenas separadas? A maior bifurcação estrutural, e a decisão deles. Além disso: o que eles já têm (logotipo, cores, fontes, fotos de produtos, modelos 3D como .glb).

Escreva BRIEF.md na pasta de build com as respostas deles nas palavras deles, depois adicione:

• A jornada: quatro a sete batidas, cada uma uma mudança no que o visitante sabe ou sente.
• A curva de sensação: uma linha por batida, a sensação e o que na tela a causa. Nenhum dois vizinhos iguais.
• O pico: a frase que um visitante diria sobre ele, e em qual ato ele vive.
• É o site onde ___: preenchido com uma experiência, não uma técnica.
• O movimento característico: uma interação que existe apenas neste site, codificada na página. Um dispositivo do kit com números novos não conta.
• Qualquer silêncio deliberado, marcado, para que as verificações possam distingui-lo de rolagem morta.

Passo 1: Estrutura, registro e pontuação

Três coisas, nesta ordem. Todas as três antes de qualquer código.

Escolha uma estrutura de references/structures.md: um mundo, capítulos, palco de produto, exposição, playground, editorial com inserções, transmissão. A navegação, a abertura e o fechamento seguem a partir dela. Escreva em BRIEF.md por que esta e não as outras.

Execute o registro de impressões digitais. Leia FINGERPRINTS.md na pasta que contém seus builds (crie se estiver faltando; começa vazio). O plano deve diferir de cada linha existente em pelo menos quatro de: estrutura, navegação, dispositivo do herói, sequência de atos, fechamento, movimento característico. Se falhar, mude o plano, não o registro.

Pontue-o. Curva de sensação primeiro, depois um dispositivo por batida, como uma tabela em BRIEF.md:

Batida	Ato	Sensação	Dispositivo	Extensão	Por que este dispositivo
Reconhecimento	herói	curiosidade	objeto de vidro + dolly	2	O produto, vivo, antes que uma palavra seja lida
Virada	morph	antecipação	morph de partículas	3	Ruído se torna uma forma que se torna o nome
Pico	trilho	admiração	trilho de câmera	3.5	Viajar através dele diz que há muito aqui
Prova	explodir	confiança	vista explodida	2.5	Mostra as peças, que é a afirmação
Compromisso	fechar	calma	calma mantida	1.5	A página para e espera pelo clique

Verificações antes de construir:

• As proibições da estrutura são válidas.
• Quatro ou mais famílias de dispositivos de references/scene-kit.md, nenhuma duas vezes seguidas.
• Nenhum dois atos vizinhos compartilham uma sensação.
• O pico tem a maior extensão por uma margem clara, e o ato antes dele é mais calmo.
• O fechamento resolve e mantém, em vez de desaparecer em um rodapé.
• Extensões estão em alturas de tela. Uma página cinematográfica fica em torno de 8 a 14; páginas editoriais e de playground podem ser mais curtas. Nunca preencha para atingir um número.

Passo 2: Construir

mkdir -p <build> && cp <skill>/engine/stage.js <skill>/engine/stage.css <build>/

Comece de templates/starter/index.html para a estrutura (mapa de importação, canvas, seções, um script de módulo), e pegue emprestado os padrões de atos que você pontuou. Nunca envie o starter ou sua cópia Orbis. Cada página é escrita a partir de seu próprio brief.

Como o motor funciona (engine/stage.js, leia o comentário do cabeçalho):

• A página é uma pilha de <section data-act="nome" data-span="2">. Cada uma contém um .frame que fica fixo pela duração da seção.
• stage.act(name, { scene, camera, update(p, s), render(renderer, s), resize(w, h) }) registra uma cena. p vai de 0 a 1 ao longo do ato. s carrega time, dt, pointer (suavizado, -1 a 1), velocity (velocidade de rolagem), width, height, reduced, coarse.
• O ato que detém o meio da tela renderiza. Atos que compartilham um objeto scene atualizam todos juntos, então um único mundo contínuo é apenas vários atos apontando para a mesma cena.
• Um ato precisa de uma extensão acima de 1 para que p se mova. p é medido sobre a distância que o frame fica fixo, então uma extensão de exatamente 1 não tem nenhum: p salta de 0 para 1 e qualquer coisa ligada a ele nunca aparece. Use 1.25 ou mais.
• Cada seção recebe --p como uma variável CSS, então títulos podem se mover na mesma linha do tempo que o 3D.
• data-reveal em qualquer elemento o faz aparecer gradualmente na entrada; escalone com style="--i:2".
• Use seg(p, a, b) para dividir um ato em batidas e ease.inOut e amigos para moldá-los.
• Sem WebGL: html.no-webgl mostra o .poster de cada ato. Dê a cada ato um poster (uma imagem ou um gradiente).

Tema com os tokens no topo de stage.css (canvas, surface, ink, ink-soft, accent, accent-ink, duas fontes). Nunca edite o motor para um projeto; comportamento personalizado vai no próprio script da página.

Three.js vem de uma versão CDN fixada no mapa de importação ([email protected] no jsdelivr). Mantenha a fixação. Se precisar de uma versão mais nova, escolha uma com pelo menos duas semanas de idade e reexecute as verificações.

Leia references/design.md antes de escrever marcação e references/performance.md antes de adicionar a segunda cena.

Passo 3: Prove

cd <build> && npm i playwright-core          # uma vez por pasta de build; precisa do Google Chrome instalado
node <skill>/scripts/serve.mjs --root . --port 4600 &
node <skill>/scripts/shoot.mjs --url http://localhost:4600 --out shots/desktop
node <skill>/scripts/shoot.mjs --url http://localhost:4600 --out shots/phone --width 390 --height 844 --touch
node <skill>/scripts/shoot.mjs --url http://localhost:4600 --out shots/reduced --reduced-motion --positions 0,1

O script rola cada ato para cinco posições, espera a suavização estabilizar, captura a tela de cada um e escreve sheet.png. Ele falha em: erros de página, requisições falhas, sem WebGL, um ato que não desenha nada e rolagem lateral. Uma aprovação significa que ele roda, não que é bom.

Depois abra cada sheet.png e olhe. Para cada ato em cada posição: cada linha pode ser lida? A cena mostra o que a batida diz? No celular, algo está cortado, coberto ou minúsculo? O pico parece o pico? O fechamento resolve? Corrija, fotografe novamente, olhe novamente.

Depois a verificação de sensação (references/feel.md): role frio, uma palavra por ato para o que você sentiu, depois compare com a curva em BRIEF.md. Onde discordarem, corrija a página.

Diga claramente o que não foi coberto: o Chrome headless desenha WebGL em software, então a taxa de quadros que ele reporta não é a de um dispositivo real, e ele não pode dizer como a rolagem se sente em um telefone real. Peça ao usuário para abri-lo no telefone antes de considerá-lo finalizado.

Regras rígidas

Nunca	Em vez disso
Um dispositivo de cena para a página inteira	Quatro ou mais famílias, nenhuma duas vezes seguidas
Texto cozido em uma textura ou imagem	HTML real sobre o canvas
Uma seta de rolagem, ícone de mouse ou "rolar para explorar"	Nada. O herói é suficiente
Contadores de seção como 01 / 05	Delete-os
Cópia centralizada em cada ato	Varie: esquerda, direita, centro, dividido, topo, base
Uma sobreposição escura em tela cheia para contraste	.scrim atrás do bloco de texto apenas
Texto gradiente, brilho de néon no tipo	Peso e tamanho fazem a ênfase
Números ou estatísticas inventadas	Apenas figuras reais do usuário
Travessões em cópia visível	Ponto final, vírgula, dois-pontos
Coisas girando que nunca param	O movimento segue a rolagem ou o ponteiro; movimento ocioso é lento e pequeno
Um novo renderizador WebGL por seção	Um canvas, um renderizador, muitas cenas (o motor faz isso)
Enviar a página inicial (starter)	Escreva a página a partir de seu próprio brief
Construir antes da estrutura, registro e pontuação existirem	Passo 1, todos os três
Dois picos, ou nenhum	Um, com mais espaço e um ato calmo antes dele
Um plano que corresponde a um build anterior em três ou mais colunas do registro	Mude o plano, nunca o registro
Chamar de finalizado sem o Passo 3	Execute o Passo 3, olhe as folhas, faça a verificação de sensação

Saída

A pasta de build, depois um breve relatório: a estrutura e por quê, o resultado da impressão digital contra cada linha, a jornada, a curva de sensação e o pico, a tabela de pontuação, o movimento característico, o que shoot.mjs relatou em todas as três execuções, o que você viu nas folhas e corrigiu, a verificação de sensação (intencional contra sentido), e o que você não pôde verificar. Forneça a URL local. Depois adicione a linha do build a FINGERPRINTS.md.