diff --git a/.lovable/plan.md b/.lovable/plan.md index 6632ae3..1c8b568 100644 --- a/.lovable/plan.md +++ b/.lovable/plan.md @@ -1,111 +1,64 @@ ## Objetivo -Construir uma **"giga de teste"** (DevKit) que vista o app com simulação completa de XR + instrumentação, permitindo: +Eliminar a "briga de matrizes" entre `XRHitTestPlacement` (pai) e `XRGrabbable` (filho) e adicionar **Fixar/Desfixar** a peça no espaço, para o fluxo de alinhar quina-com-quina sobre o objeto real. -1. **Você (sem Quest):** validar quase 100% do fluxo direto no navegador, incluindo grab, posicionamento e medição. -2. **Testador (com Quest):** receber um build com painel de diagnóstico visível e log persistente, devolvendo feedback objetivo. -3. **Remoção limpa:** quando o app estiver maduro, apagar 1 pasta + remover 3 imports + apagar 1 flag → app puro restaurado. +## O que muda -## Princípios de isolamento +### 1. Reparent on grab/release (causa-raiz) -- Todo código do DevKit vive em **`src/devkit/`** (pasta nova). Nada de código de simulação espalhado pelo app. -- Ativação por **flag única** `?devkit=1` na URL **OU** `localStorage.setItem('devkit', '1')`. Sem flag → app roda exatamente como hoje. -- Componentes do DevKit são montados condicionalmente em **3 pontos de injeção** apenas (todos em `XRSession.tsx`). Esses pontos ficam marcados com comentário `// DEVKIT: remove this block` para facilitar a limpeza futura. -- Zero alteração de lógica de negócio. Tudo que o DevKit faz é **observar** (logger), **simular** (fake inputs) ou **adicionar UI extra** (painel). +No `XRGrabbable`, no instante em que o grab começa, o grupo do modelo é **transferido para a Scene** preservando a transform de mundo. Enquanto está "na mão", o pai (`XRHitTestPlacement`) não consegue mais influenciar a matriz — fim do drift/salto. -## Componentes do DevKit +- **Início do grab** (one-hand ou two-hand): guardar `originalParent` e chamar `scene.attach(group)`. +- **Fim do grab** (todas as mãos soltaram): `originalParent.attach(group)` para devolver, mantendo a pose final. +- Vale para os dois modos (single e dual). A captura de offset/startGroupWorld passa a acontecer **depois** do attach, garantindo math consistente. -### 1. `devkit/DevKitFlag.ts` — detector de modo -Hook `useDevKit()` retorna `boolean`. Lê `URLSearchParams` + `localStorage`. Se `true`, ativa todo o resto. +### 2. Lock / Unlock (fixar peça) -### 2. `devkit/SimXRSession.tsx` — modo "Faux-XR" pra desktop -**Resolve seu problema #1:** validar tudo sem headset. +Nova flag global `isLocked` no `useModelStore`: -Quando ativado (botão "🧪 Simular XR" no header, só aparece com `?devkit=1`): -- Não chama `store.enterAR()` (que falha sem HTTPS/headset compatível). -- Em vez disso, força `inXR=true` num estado paralelo `simXR`. -- Renderiza a árvore `XRGrabbable + XRModel` **sem** `XRHitTestPlacement` (auto-posiciona em `[0,0,-1.5]`). -- Substitui leitura de `session.inputSources` por uma fonte **fake** (ver #3). -- Câmera fica controlável por `OrbitControls` (você navega como quiser). +- Quando `true`: `useControllerGrab` ignora o grip (não inicia grab) e `XRGrabbable` mostra um halo dourado discreto sinalizando "travado". +- Quando travado, a peça **permanece reparentada na Scene** com a pose congelada — não volta para o `XRHitTestPlacement` (impede que o reticle reposicione). +- Botão "🔒 Fixar / 🔓 Liberar" no XR HUD (ao lado dos toggles existentes) e atalho `L` no DevKit (desktop). -### 3. `devkit/FakeControllers.tsx` — controles virtuais com mouse/teclado -**Resolve seu problema #2:** testar grab sem Touch Plus. +### 3. Logs DevKit -- Desenha 2 esferas coloridas (L=azul, R=vermelho) na cena, posicionáveis por **arrastar com mouse**. -- Atalhos teclado: - - `Q` / `W` → segurar grip esquerdo / direito (analógico simulado em 1.0) - - `A` / `S` → segurar trigger esquerdo / direito - - `Setas` → mover controle ativo - - `Shift + Setas` → mover controle no eixo Z -- Expõe um `FakeInputProvider` (Context) que `useControllerGrab` consome **quando em modo DevKit**. Sem DevKit, hook continua lendo `session.inputSources` real. -- **Mudança mínima em `useControllerGrab.ts`:** uma linha checando `if (devkit) return useFakeInputs()`. Removível. +- `[grab] attach→scene (hand=left|right|dual)` +- `[grab] release→` +- `[lock] ON` / `[lock] OFF` -### 4. `devkit/DevPanel.tsx` — painel de diagnóstico flutuante -Painel HTML overlay (canto direito), só visível com `?devkit=1`: -- **Aba "Inputs":** valores ao vivo de cada controle (real ou fake) — grip, trigger, axes, hasPose -- **Aba "Cena":** posição/rotação/escala do grupo grabável, contagem de meshes, bbox -- **Aba "XR":** `session?.mode`, hit-test ativo, planos detectados (count + labels), FPS -- **Aba "Logs":** últimos 100 console.logs com timestamp, filtro por tag (`[XR]`, `[grab]`, `[HitTest]`) -- Botão **"Exportar relatório"** → baixa JSON com snapshot atual + screenshot do canvas. **Você pede pro testador clicar isso e te enviar o arquivo.** +Visíveis na aba **Logs** do `DevPanel`, úteis tanto no desktop quanto refletidos no overlay quando o testador usar o Quest. -### 5. `devkit/XRDevHud.tsx` — HUD in-world expandido (substitui o `XRDebugHud` atual quando ativo) -Painel 3D maior, ancorado no pulso esquerdo (não na câmera, pra não atrapalhar). Mostra mesmas infos da aba "Inputs" + "XR" do DevPanel. Visível **dentro do headset**, essencial pro testador. +### 4. Smoke test -### 6. `devkit/SmokeTest.tsx` — roteiro automático -Rota nova `/devkit/smoke` (só roteada com `?devkit=1`): -- Sequência scriptada: carrega demo → simula grip esquerdo → move 50cm → solta → mede 2 pontos → screenshot → checklist. -- Cada passo mostra ✅/❌ + tempo. -- Você roda antes de mandar build pro testador. +Estender `src/devkit/SmokeTest.tsx` com um caso que: +1. Cria um group filho de outro group, simula attach→scene, valida que `matrixWorld` antes/depois é igual (preserve transform). +2. Toggle de lock impede `useControllerGrab` de marcar `isGrabbing=true`. -### 7. `devkit/RecordSession.tsx` — gravador de "macros" -Botão "Gravar" no DevPanel: captura por 30s todos inputs + posições da cena num JSON. Botão "Reproduzir": replay do macro. Útil pra reproduzir um bug que o testador relatou ("clico aqui, viro assim, peça desaparece"). +## Arquivos afetados -## Pontos de injeção em `XRSession.tsx` - -Apenas 3 blocos curtos, todos cercados por `{devkit && <... />}`: - -```tsx -// DEVKIT: remove this block -{devkit && } - -// DEVKIT: remove this block -{devkit && simXR && } - -// DEVKIT: remove this block -{devkit && } -``` - -E uma linha em `useControllerGrab.ts`: -```ts -// DEVKIT: remove this conditional -if (typeof window !== 'undefined' && useDevKitFake()) return fakeRef; -``` - -## Como remover o DevKit no futuro (1 minuto) - -1. `rm -rf src/devkit/` -2. Em `XRSession.tsx`: deletar 3 blocos marcados `// DEVKIT:` + import. -3. Em `useControllerGrab.ts`: deletar linha marcada `// DEVKIT:`. -4. Pronto — app puro, zero resíduo. - -## Entregas desta primeira leva (priorizadas) - -Pra não fazer tudo de uma vez, **proponho entregar nesta ordem**, validando cada etapa antes da próxima: - -**Fase 1 (essencial — destrava você hoje):** -- DevKitFlag + SimXRSession + FakeControllers + DevPanel (aba Inputs + Logs) - -**Fase 2 (essencial — instrumenta o testador):** -- XRDevHud expandido + DevPanel aba Cena/XR + Exportar relatório - -**Fase 3 (qualidade de vida):** -- SmokeTest + RecordSession - -Posso entregar a **Fase 1 inteira** agora numa única leva, e as fases 2 e 3 sob demanda quando você validar que a 1 te serve. Cabe? +- `src/components/three/XRGrabbable.tsx` — reparent on start/end, halo de lock. +- `src/hooks/useControllerGrab.ts` — respeitar `isLocked` (early return). +- `src/stores/useModelStore.ts` — `isLocked: boolean` + `setLocked`. +- `src/components/XRHud.tsx` — botão Fixar/Liberar. +- `src/devkit/FakeControllers.tsx` — atalho `L`. +- `src/devkit/SmokeTest.tsx` — novos asserts. +- `src/pages/XRSession.tsx` — passar a `Scene` para o `XRGrabbable` (via `useThree` interno; sem mudanças na árvore JSX). ## Detalhes técnicos -- **Sem novas dependências.** Tudo com Three.js, R3F, Zustand já presentes. -- **TypeScript rigoroso.** Tipos compartilhados entre real e fake (mesma interface `ControllerGrabSnapshot`). -- **Zero impacto em produção:** sem flag, bundle do DevKit nem é importado se usarmos `React.lazy()` na entrada. -- **Hot-swappable:** ligar/desligar o DevKit não recarrega a página (estado da cena preservado). +- **`THREE.Object3D.attach(child)`** preserva world-transform automaticamente (decompõe parent.matrixWorld⁻¹ × child.matrixWorld). É a primitiva certa, não `add`. +- O re-attach final usa o **parent original capturado no grab start**, não o parent atual — protege contra mudanças de árvore React entre frames. +- O `applyWorldMatrixToLocal` continua igual, mas como o parent passa a ser a `Scene` (matrixWorld = identidade), o cálculo fica trivial e estável. +- `isLocked` não persiste em localStorage por enquanto (decisão de sessão). + +## Fora de escopo (fica para depois) + +- Snap visual quina-a-quina (destacar vértice mais próximo do controlador durante o grab). +- Migração para `RayGrab` nativo. +- Persistir lock + pose entre sessões. + +## Como validar + +1. **Desktop + DevKit**: `?devkit=1` → SimXR ON → `Q` segura com a esquerda → mover → soltar. Não pode haver salto. Apertar `L` → tentar segurar → não deve agarrar. +2. **Quest 3 (testador)**: pegar peça, mover, soltar — pose final sem drift. Apertar Fixar no HUD → tentar pegar → não move. +3. Aba Logs do DevPanel mostra a sequência `attach→scene` / `release→` em todo grab. diff --git a/src/components/XRHud.tsx b/src/components/XRHud.tsx index 9bb8147..8817686 100644 --- a/src/components/XRHud.tsx +++ b/src/components/XRHud.tsx @@ -3,6 +3,7 @@ import { Eye, LayoutGrid, Grid3X3, Box, Ruler, Trash2, Camera, Move, RotateCw, RefreshCw, ChevronUp, ChevronDown, Grip, ClipboardCheck, X, Crosshair, Magnet, HelpCircle, Maximize2, + Lock, Unlock, } from 'lucide-react'; import { Button } from '@/components/ui/button'; import { Slider } from '@/components/ui/slider'; @@ -112,6 +113,7 @@ export function XRHud({ freeMove, onToggleFreeMove, placementMode = false, onTog fineTuning, setFineTuning, resetFineTuning, addScreenshot, checklist, + isLocked, setLocked, } = useModelStore(); const approved = checklist.filter(i => i.status === 'approved').length; @@ -310,6 +312,22 @@ export function XRHud({ freeMove, onToggleFreeMove, placementMode = false, onTog )} + {/* Lock / Unlock — fixa a peça no espaço */} + +