WebAR · Arte Expandida

App web (sem instalar nada): a pessoa cadastra a própria obra (foto ou galeria), a IA (Claude) entende a imagem e configura a experiência, e ao apontar a câmera do celular para a obra física surgem efeitos 3D gerados da própria pintura — camadas que saltam em relevo, partículas nas cores da obra, aura de reconhecimento e, opcionalmente, um objeto 3D. Acesso por link/QR Code, HTTPS.

Como funciona

1. Cadastrar: foto ou imagem da galeria → detecção automática dos cantos da obra + correção de perspectiva (ajustável à mão) → alvo de reconhecimento compilado no próprio celular.
2. Analisar: nota de reconhecimento (0–100) calculada a partir dos pontos reais que o motor usa, com dicas concretas; paleta, ponto de interesse e clima da obra. Com IA ligada, Claude sugere título, descrição acessível, legenda e efeitos (api/analyze.ts).
3. Apontar: reconhece qualquer uma das obras cadastradas (até 8) e mostra a legenda; enquanto procura, a câmera analisa o vídeo localmente e avisa sobre escuro, reflexo, tremor, desfoque e mostra quais obras está procurando.

As obras ficam no IndexedDB do aparelho. Só a imagem da obra (nunca a câmera) vai para a IA, e só se a pessoa permitir.

Demo publicada: https://webar-arte-expandida.vercel.app · folha para imprimir: https://webar-arte-expandida.vercel.app/imprimir.html

Status: POC implementada e validada em navegador automatizado (ver Validação). QA em iPhone e Android reais: PENDENTE — ver tests/smoke-checklist.md.

Como testar no celular

1. Abra /imprimir.html no site publicado (folha A4 com a obra + QR Code da experiência) e imprima em papel fosco, escala 100%. Ou imprima public/images/obra-original.png em A4 ou maior, sem cortar bordas. (Também funciona apontando para a imagem aberta numa tela, com menos estabilidade por causa de reflexo/moiré.)
2. Abra a URL HTTPS publicada (ou leia o QR Code) no Safari (iPhone) ou Chrome (Android).
3. Toque em Iniciar experiência, permita a câmera e enquadre a obra inteira a ~30–60 cm.
4. Sem câmera? Ver demonstração sem câmera mostra os efeitos sobre a obra em 3D.

No computador, a tela inicial mostra um QR Code para continuar no celular.

Adicione ?debug=1 à URL para ver FPS e o contorno de registro do alvo (útil para avaliar jitter).

IA (Claude)

A análise usa a função serverless api/analyze.ts (modelo claude-opus-5-5, saída estruturada validada com Zod, fallback de recusa do servidor). Para ativar, defina ANTHROPIC_API_KEY nas variáveis de ambiente do projeto na Vercel (Settings › Environment Variables) e refaça o deploy. Sem a chave, o app funciona normalmente com a análise local e avisa que a IA não está configurada.

Rodar localmente

Requisitos: Node 22.12+ (testado com Node 22.22.0 / npm 10.9.4).

npm ci
npm run dev          # http://localhost:5173 (localhost já é contexto seguro p/ câmera no desktop)
npm run dev:https    # https://<ip-da-rede>:5173 com certificado autoassinado, para abrir no celular
npm run build        # typecheck + build de produção em dist/
npm run preview      # serve dist/ com os mesmos cabeçalhos (CSP) de produção

No celular via dev:https, aceite o aviso de certificado (iOS: "Mostrar detalhes › visitar este site").

Scripts

Comando	O que faz
npm run typecheck	tsc --noEmit (modo strict)
npm test	testes unitários (Vitest)
npm run build	typecheck + vite build
npm run art	regenera a arte original (determinística, seed 2026) em public/images/
npm run target	compila a imagem em public/targets/obra-original.mind com o compilador do próprio MindAR (Chromium headless)
npm run test:e2e	E2E com câmera simulada: rastreamento da obra de exemplo + cadastro de obra nova (detecção de cantos, compilação, IA simulada) e reconhecimento de 2 obras (requer npm run build, ffmpeg, Playwright e python3 tests/fixtures/make-fixtures.py)

art, target e test:e2e usam Playwright (Chromium). Se não estiver instalado: npm i -D playwright && npx playwright install chromium.

Estrutura

public/
  images/obra-original.{svg,png,jpg}   arte-alvo original (CC BY 4.0, ver ART_LICENSE.md)
  targets/obra-original.mind           alvo compilado (MindAR 1.2.5)
  models/                              reservado para GLB/GLTF (efeitos atuais são procedurais)
src/
  ar/engine.ts            interface do motor de rastreamento (troca futura de SDK)
  ar/mindarEngine.ts      implementação com MindAR Controller
  ar/camera.ts            getUserMedia, classificação de erros, encerramento de tracks
  ar/trackingState.ts     máquina de estados (loading/scanning/found/lost/error)
  ar/frameAdvisor.ts      análise local do vídeo: escuro, reflexo, tremor, desfoque
  ar/createExperience.ts  cena Three.js, várias âncoras, loop, resize/rotação, desmontagem; prévia 3D
  artworks/               cadastro: recorte/perspectiva, análise, compilação, IA, IndexedDB, catálogo
  effects/sceneEffects.ts efeitos gerados da obra: camadas, partículas, aura, objeto 3D
  scene/types.ts          configuração de cena (compartilhada com a API)
api/analyze.ts            função serverless: Claude analisa a obra
  ui/StatusOverlay.ts     HUD, dicas, loading, telas de erro
  ui/qr.ts                QR Code (carregado sob demanda)
  styles/main.css, print.css
  main.ts                 telas e fluxo
  print.ts                página imprimir.html (obra + QR em A4)
scripts/   generate-art.mjs, compile-target.mjs, compile-target.md
tests/     smoke-checklist.md (QA físico), e2e/tracking.e2e.mjs (automatizado)
docs/      ARQUITETURA.md (decisões, riscos, compatibilidade), BACKLOG.md

This is the beginning of the README. Read the rest at the original. Read the full README ↗