## Objetivo

Construir uma **"giga de teste"** (DevKit) que vista o app com simulação completa de XR + instrumentação, permitindo:

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.

## Princípios de isolamento

- 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).

## Componentes do DevKit

### 1. `devkit/DevKitFlag.ts` — detector de modo
Hook `useDevKit()` retorna `boolean`. Lê `URLSearchParams` + `localStorage`. Se `true`, ativa todo o resto.

### 2. `devkit/SimXRSession.tsx` — modo "Faux-XR" pra desktop
**Resolve seu problema #1:** validar tudo sem headset.

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).

### 3. `devkit/FakeControllers.tsx` — controles virtuais com mouse/teclado
**Resolve seu problema #2:** testar grab sem Touch Plus.

- 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.

### 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.**

### 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.

### 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.

### 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").

## Pontos de injeção em `XRSession.tsx`

Apenas 3 blocos curtos, todos cercados por `{devkit && <... />}`:

```tsx
// DEVKIT: remove this block
{devkit && <SimXRButton onActivate={setSimXR} />}

// DEVKIT: remove this block  
{devkit && simXR && <FakeControllers />}

// DEVKIT: remove this block
{devkit && <DevPanel />}
```

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?

## 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).