📚 Estudo de Bolso (antes Bio no Bolso, Natureza no Bolso e Bicho no Bolso)

Explore. Descubra. Colecione. Um catálogo interativo onde crianças exploram animais em 3D, descobrem curiosidades e comparam seus tamanhos.

Formigas e abelhas em 3D realistas, para girar e dar zoom com o dedo. Os corpos são "esculpidos" no próprio navegador ao abrir cada página (leva 1–3 segundos no iPad). Não tem build, nem servidor, nem som.

Endereço: https://bionobolso.vercel.app (antes formigas-beta.vercel.app). Cópia na VPS: estudodebolso.com.br/explorar/.

Direção do projeto (outubro de 2026)

O projeto está sendo ampliado para uma enciclopédia interativa da natureza (agora com o nome Estudo de Bolso, de Biologia; domínio, Vercel e repositório continuam os mesmos). As categorias planejadas são animais, plantas, fungos, mundo microscópico, rochas e minerais, e fenômenos naturais. Hoje o site tem só animais. Reconhecimento por foto, contas, contribuições e assinatura são planos, não recursos prontos.

• docs/product-direction.md: direção, decisões, hipóteses, pendências e etapas.
• docs/technical-audit.md: auditoria técnica do código atual (rotas, dados, armazenamento, PWA, motor 3D).
• docs/catalog-model.md: modelo de catálogo genérico, mapa de telas V2 e adaptações da home, da busca, da ficha e do Meu Bolso.
• docs/photo-identification.md: descobrir por foto (casos A/B/C) e contribuições.
• docs/backlog-3d.md: experiências 3D planejadas e a validação exigida antes de modelar.

Páginas

• index.html: splash → Quem vai explorar? (faixa etária: js/faixa.js, css/faixa.css) → Biblioteca 3D adaptada à faixa. Proposta pedagógica em docs/pedagogia.md.
• index.html: página inicial = Biblioteca 3D (veja biblioteca.html abaixo), com a abertura e as boas-vindas. biblioteca.html só redireciona para cá, mantendo o item aberto.
• bichos.html: a antiga home dos bichos. Saiu do menu: todos os bichos agora ficam na categoria Bichos da biblioteca (com 3D → tela 3D; sem 3D → ficha). Continua com Meu Bolso e a seção para adultos. Hero com busca, catálogo com categorias, experiências 3D, álbum "Minhas descobertas", missão "Pequenos do jardim" e seção para adultos.
• Identidade visual v2: docs/identidade-visual.md (símbolo do bolso com broto em img/marca/simbolo.svg, cores, Fredoka + Nunito, ícones do app).
• css/marca.css: identidade visual (variáveis --color-primary, --color-accent, --surface… e componentes: cabeçalho, logo, botões, chips, rodapé).
• css/catalogo.css: estilos da home.
• css/splash.css, js/splash.js e js/splash-bichos.js: abertura (mascote, folhas e bichos passando: aranha descendo no fio, borboleta-azul e joaninha; para trocar por imagens realistas, veja o topo de js/splash-bichos.js), "Olá, explorador!" no primeiro acesso e saudação com os bichos encontrados na volta. Toque pula; não aparece de novo na mesma sessão.
• js/home.js: lógica da home. js/icones.js: ícones SVG da interface.
• design/: referências visuais da marca (não são usadas pelo site).
• bicho3d.html?id=<bicho>: página 3D reutilizável no "Modo Explorar" (barra de formas no topo, ações na lateral, Partes, Tamanho real com arroz/moeda/régua, modo "só o bicho", selo "No meu bolso" e dicas do Curu). O motor fica em js/bicho3d.js e cada bicho tem só o seu modelo em js/modelos/<id>.js (o motor carrega só o modelo do bicho aberto):
  • cigarra (Quesada gigas): adulta, ninfa e casca (exúvia no tronco); canta (som imitado) e voa.
  • aranha (Trichonephila clavipes): fêmea e o macho pequenininho na teia dourada; anda, desce no fio e sente a teia tremer.
  • abelha (Apis mellifera): operária, rainha e zangão no jardim com flores (toque numa flor e ela voa até lá; 🌼 visita as flores sozinha; 👅 língua), Partes, a 🍯 Colmeia aberta com passeio (etiquetas + "Próxima ⏭", incluindo a própolis) e o ▶️ Como funciona? – Como nasce o mel: a criança toca na flor, vê o papo de mel encher, leva o néctar para a colmeia, faz as abelhas abanarem as asas e tampa a casinha com cera (protótipo, conteúdo em revisão científica).
  • formiga (Atta, saúva): operária (🍃 carrega folha), rainha e zangão (🪽 voo nupcial), 🚶 passear, 🦷 morder (ou toque nela), toque no chão para ela andar até lá, Partes e o 🏠 Formigueiro em corte com passeio (no Berçário aparecem ovos, larvas e pupas).
• Novo bicho com 3D: cadastre em js/catalogo.js com pagina: 'bicho3d.html?id=<id>' e crie js/modelos/<id>.js (veja o topo de js/bicho3d.js). Espécies do mesmo tipo (várias aranhas, várias cigarras) usam o campo tipo.
• Por Dentro do Bicho (protótipo na cigarra: "Como nasce o canto"): três modos no 3D (🐾 Por fora · 🫀 Por dentro · ▶️ Como funciona?) e o seletor 🧸 Pequeno / 🧒 Explorador. No modelo, dentro: { ligar, partes } deixa o corpo transparente e mostra os órgãos; processo: { titulo, passos, toque } cria os passos guiados, em que a criança provoca cada etapa tocando no bicho. No catálogo, porDentro: true mostra o selo "🧩 Explore por dentro". O conteúdo está marcado como "em revisão científica" (revisado: false).
• biblioteca.html: Biblioteca 3D, uma vitrine da natureza para girar, aproximar e tocar em cada parte. Tem 16 itens em 4 categorias (plantas, rochas e minerais, ninhos e rastros, fungos e micromundo), mais atalhos para os bichos que já têm tela 3D. Cada item tem partes tocáveis com texto 🧸 Pequeno ou 🧒 Explorador, uma ação própria (abrir o geodo, germinar o feijão, cortar a célula ao meio, soltar esporos…), o tamanho real e, no micromundo, um aviso de que o modelo é ampliado e tem cores de mentirinha. O endereço guarda o item aberto (biblioteca.html#geodo). Código em js/biblioteca/: visor.js (registro e palco 3D), um arquivo por categoria (plantas.js, rochas.js, ninhos.js, micro.js) e pagina.js (catálogo e visor). Para um item novo, chame Biblioteca.item({ id, nome, cat, resumo, tamanho }, construir) no arquivo da categoria. Modelos didáticos e textos em revisão científica.
• comparar.html: comparador de dois bichos (tamanho, parentesco, o que come, quanto vive, com quem vive, onde mora, situação na natureza).
• formiga.html e abelha.html: endereços antigos. Só redirecionam para bicho3d.html?id=formiga e ?id=abelha (QR codes e atalhos antigos continuam funcionando).
• qr.html: folha A4 com o QR code do site, pronta para imprimir (usa o endereço onde o site está publicado; dá para trocar no campo de cima).
• js/catalogo.js: dados de todos os animais (ficha, ciclo de vida, curiosidades, dados por casta). Para adicionar um animal ao catálogo, acrescente um item em ANIMAIS.
• js/ficha.js: gaveta ℹ️ ficha (abas Ficha, Vida, Sabia? e 📷 Real; muda conforme a casta escolhida).
• img/animais/: fotos reais de cada bicho (3 por animal), tiradas do iNaturalist, só com licenças que permitem qualquer uso (CC0, CC BY e CC BY-SA). O nome do fotógrafo e a licença aparecem no site e estão em fotos no catalogo.js. Como ficam no próprio site, aparecem sempre, mesmo sem internet.
• js/dados.js: fotos e dados reais do iNaturalist e da Wikipédia (sem chave, sem cadastro). Fica guardado no aparelho por 14 dias; sem internet, o site usa os emojis.
• js/progresso.js: álbum de descobertas, guardado só no aparelho (dá para apagar no rodapé do catálogo).
• docs/PILOTO.md: kit para testar com turmas e propor um piloto pago (roteiro de aula, perguntas para o professor, autorizações).
• docs/ESTRATEGIA.md (fase "catálogo de animais"): design comportamental, crítica de UX/UI, APIs, monetização ética e recomendações de tecnologia 3D.
• js/core3d.js: peças 3D comuns, usadas pelas telas novas.

Como usar

Em qualquer bicho 3D (bicho3d.html?id=…):

• Abas no topo: trocam a forma (operária, rainha, zangão…) ou abrem a casa (🏠 formigueiro, 🍯 colmeia), com etiquetas e o botão "Próxima ⏭" para o passeio.
• Botões do lado: ações do bicho (voar, passear, folha, língua, cantar…), 🔎 Partes, 📏 Tamanho real, 🔄 Câmera e 👁 Só o bicho.
• 🧸 Pequeno / 🧒 Explorador / 🔬 Cientista: frases curtas (até 6 anos), mais informações (7 a 10) ou nome científico e função de cada parte (anos finais, 11+). O Cientista mostra a classificação do bicho e textos próprios nas partes, no passeio e nos passos do "Como funciona?". No modelo, os textos ficam em cientista: { 'Nome da parte': { termo, texto }, passos: [...] }. Conteúdo em revisão científica. As fichas também têm o nível Cientista: botão 🔬 no topo da ficha (sincronizado com o 3D), quadro "Para cientistas" na aba Ficha, ciclo de vida com termos técnicos e curiosidades 🔬 na aba Sabia?. Os textos ficam em js/cientista.js, um por animal.
• Girar: arraste com um dedo. Zoom: pinça com dois dedos. Mover a câmera: arraste com dois dedos.

Tudo o que o site precisa está no próprio site: o Three.js e o gerador de QR ficam em vendor/ e as fotos em img/animais/. Fora do site só ficam a fonte (se não carregar, aparece a fonte do aparelho) e os dados extras da aba 📷 Real.

Domínio próprio (ex.: bichonobolso.com.br)

1. Pague o boleto do registro.br quando chegar (o domínio só funciona depois do pagamento).
2. Na Vercel: projeto › Settings › Domains › adicione SEUDOMINIO e www.SEUDOMINIO. A Vercel mostra os registros de DNS que precisa.
3. No registro.br: domínio › DNS › use os valores que a Vercel mostrou (registro A para SEUDOMINIO e CNAME para www), ou troque os servidores DNS para os da Vercel.
4. Espere a Vercel mostrar "Valid Configuration" (de minutos a algumas horas). O certificado de segurança é criado sozinho.
5. Na Vercel, faça bionobolso.vercel.app (e o antigo formigas-beta.vercel.app) redirecionar para o domínio novo.
6. Abra https://SEUDOMINIO/qr.html e imprima o QR novo (ele usa o endereço onde a página foi aberta).
7. Nos iPads: instale de novo o app pelo domínio novo (o app antigo fica preso ao endereço antigo, com as descobertas dele). Peça à TI da escola para liberar SEUDOMINIO.

Usar sem internet (app na Tela de Início)

O site funciona como um app (PWA). Na primeira vez que abre com internet, ele guarda tudo no aparelho: páginas, 3D e fotos (cerca de 4 MB). Depois abre mesmo sem internet, ou num Wi-Fi que bloqueia o endereço.

• iPad/iPhone: abra no Safari (no 4G ou em casa) › Compartilhar › Adicionar à Tela de Início. O ícone 🐜🐝 3D abre o app em tela cheia.
• No catálogo aparece "✅ Pronto para usar sem internet" quando terminou de guardar.
• Mudou ou adicionou arquivos? Rode python3 ferramentas/atualizar-cache.py antes de publicar: ele atualiza a lista do sw.js e a versão, e os aparelhos baixam a novidade na próxima abertura com internet.

"Esta Conexão Não É Privada" no iPad

Esse aviso do Safari não vem do site: a Vercel usa um certificado válido. Ele aparece quando algo na rede troca o certificado no caminho. Na escola, quase sempre é o filtro ou firewall do Wi-Fi. 0. Mais rápido: instale o app pelo 4G (veja acima). Depois disso ele abre na escola mesmo com o bloqueio.

1. Teste no 4G: abra o mesmo endereço num celular fora do Wi-Fi da escola. Se abrir, o problema é a rede.
2. Data e hora do iPad: Ajustes › Geral › Data e Hora › "Ajustar Automaticamente" ligado. Com a data errada, todo site seguro dá esse aviso.
3. Wi-Fi com página de login: conecte de novo na rede e faça o login (abra captive.apple.com para a página aparecer).
4. Peça para a TI da escola liberar *.vercel.app no filtro (ou instalar nos iPads, pelo gerenciador de dispositivos, o certificado do filtro).
5. Melhor solução a longo prazo: um domínio próprio (ex.: animais3d.com.br), ligado na Vercel em Settings › Domains. Filtros escolares costumam bloquear vercel.app inteiro, porque qualquer pessoa pode publicar ali. Depois, gere um QR novo em qr.html com o domínio novo.

Não clique em "visitar este site mesmo assim" nos iPads das crianças: o certo é corrigir a rede.

Publicar na Vercel

docs/ e design/ não vão para o site: .vercelignore as tira da publicação e vercel.json redireciona esses caminhos para a home. Ficam só no repositório.

1. Envie este repositório para o GitHub.
2. Em vercel.com, clique em Add New → Project e importe o repositório.
3. Em Framework Preset, escolha Other e deixe o Build Command vazio.
4. Clique em Deploy e abra o link no Safari do iPad.

Mudar as cores

No index.html, procure o bloco AJUSTES: lá estão as cores (COR), a velocidade e o tamanho da área por onde ela anda.

Celular

Em telas pequenas os botões se reorganizam (faixa rolável em cima e barra embaixo) e o 3D fica mais leve (menos pelos e sombras menores).

Padrão da tela 3D (vale para todo bicho)

• Cabeçalho: linha 1 = ← voltar · nome (encolhe com "…" se for longo) · 🧸 Pequeno/🧒 Explorador/🔬 Cientista; linha 2 = abas. No iPad deitado, tudo numa linha.
• Abas: primeiro as formas do bicho (operária, rainha, adulta, ninfa…), por último a casa ou o lugar (🏠 formigueiro, 🍯 colmeia). Se não couberem, rolam para o lado.
• Coluna da direita, sempre nesta ordem: até 3 ações do próprio bicho (voar, cantar, folha…) → 🔎 Partes → 📏 Tamanho → 🔄 Câmera → 👁 Só o bicho. Ações que não valem para uma forma somem (ocultar na forma).
• Embaixo: barra 🐾 Por fora · 🫀 Por dentro · ▶️ Como funciona? (só com o que existe), cartão de texto à esquerda e "No meu bolso" + ℹ️ Ficha.
• Avisos (conquista, dicas) aparecem logo abaixo do cabeçalho, um de cada vez.
• Conferido sem sobreposição em celular pequeno (375×667), celular (390×844), iPad em pé (820×1180) e deitado (1180×820).

Organização do código 3D

• bicho3d.html + css/bicho3d.css: a tela padrão do Modo Explorar.
• js/bicho3d.js: o motor (cena, câmera, botões, partes, tamanho real, passeio, Por dentro / Como funciona, ficha e bolso).
• jogo/: o primeiro MVP do Terra Codex (Vale Vivo) saiu do ar; o endereço /explorar/jogo/ leva para o Brasil Vivo, que migra o progresso salvo. O código antigo fica no histórico do git. Ver docs/terra-codex-mvp.md.
• brasilvivo/: Terra Codex · Brasil Vivo, a nova direção (Brasília/Cerrado, BioDex sem quiz, ciclos de vida), em /explorar/brasilvivo/. Ver docs/terra-codex-brasil-vivo.md.
• js/modelos/<id>.js: um arquivo por bicho (formiga, abelha, cigarra, aranha, lagartixa, escorpião), carregado só quando o bicho é aberto.
• js/core3d.js: peças 3D comuns (escultura SDF, pernas, texturas).

A separação é estática: não exige npm, build ou backend e continua adequada para deploy direto na Vercel.