From 174d36e3b3f267a93d3463618c6a9bfac4354674 Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
<159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Tue, 12 May 2026 11:00:31 +0000
Subject: [PATCH 1/6] Changes
Co-authored-by: Reifonas <211114984+Reifonas@users.noreply.github.com>
---
.lovable/plan.md | 145 +++++++++++++++++++++--------------
src/devkit/fakeInputStore.ts | 48 ++++++++++++
src/devkit/useDevKit.ts | 43 +++++++++++
3 files changed, 180 insertions(+), 56 deletions(-)
create mode 100644 src/devkit/fakeInputStore.ts
create mode 100644 src/devkit/useDevKit.ts
diff --git a/.lovable/plan.md b/.lovable/plan.md
index 7b057b0..6632ae3 100644
--- a/.lovable/plan.md
+++ b/.lovable/plan.md
@@ -1,78 +1,111 @@
-## Plano: Grab nativo dos controles Touch Plus (Quest 3) para "vestir" a peça virtual
+## Objetivo
-Objetivo: permitir que o usuário **agarre a peça virtual com o grip** do Touch Plus e a movimente em 6 graus de liberdade junto com a mão (translação + rotação simultâneas), e use **as duas mãos juntas** para girar/escalar com naturalidade. Joystick atual continua existindo como ajuste fino.
+Construir uma **"giga de teste"** (DevKit) que vista o app com simulação completa de XR + instrumentação, permitindo:
-### 1. Camada de input nova: `useControllerGrab`
+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.
-Novo hook em `src/hooks/useControllerGrab.ts` que encapsula tudo que falta hoje:
+## Princípios de isolamento
-- Lê `session.inputSources` a cada frame e identifica os `XRInputSource` "left" e "right".
-- Para cada controle, expõe:
- - `gripValue` (0..1, analógico, vindo de `gamepad.buttons[2].value`).
- - `triggerValue` (0..1, `buttons[1].value`).
- - `isGrabbing` (boolean com histerese: começa em `value > 0.7`, termina em `< 0.3` — evita flicker).
- - `gripPose`: matrix4 da pose do `inputSource.gripSpace` no `referenceSpace` atual, atualizada por frame via `XRFrame.getPose()`.
-- Também escuta os eventos nativos `squeezestart` / `squeezeend` da `XRSession` como fallback caso o gamepad não exponha valor analógico.
+- 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).
-### 2. Componente `XRGrabbable` em volta da peça
+## Componentes do DevKit
-Novo arquivo `src/components/three/XRGrabbable.tsx`. Wrappa o `` em um `` controlado e implementa as três modalidades de grab:
+### 1. `devkit/DevKitFlag.ts` — detector de modo
+Hook `useDevKit()` retorna `boolean`. Lê `URLSearchParams` + `localStorage`. Se `true`, ativa todo o resto.
-- **One-hand grab**: quando `isGrabbing` de uma mão dispara, calcula matrix relativa `M_offset = gripPose⁻¹ · modelPose`. A cada frame, enquanto segura, faz `modelPose = gripPose · M_offset`. Resultado: a peça vira "extensão da mão", com translação + rotação simultâneas.
-- **Two-hand grab** (quando ambas as mãos estão segurando):
- - Pivô = ponto médio entre os dois `gripPose`.
- - Rotação = orientação do vetor entre as duas mãos (mantém o cabo da viga sempre alinhado com o eixo entre os punhos).
- - Escala = razão entre a distância atual e a distância no momento em que a 2ª mão agarrou (com clamp 0.1× a 10×). **Opcional**: pode ser desabilitada na HUD para usos onde a escala 1:1 é obrigatória (caso "vestir" sobre peça real).
-- Ao soltar (`isGrabbing` cai), grava a pose final em `useModelStore.fineTuning` (decompõe em `posX/Y/Z`, `rotX/Y/Z`, e `scale` se two-hand estiver ativo) — assim o estado fica consistente com o joystick e os controles do HUD.
+### 2. `devkit/SimXRSession.tsx` — modo "Faux-XR" pra desktop
+**Resolve seu problema #1:** validar tudo sem headset.
-### 3. Joystick continua, agora modulado pelo grip analógico
+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).
-Em `ControllerFineTuning` (dentro de `XRSession.tsx`):
+### 3. `devkit/FakeControllers.tsx` — controles virtuais com mouse/teclado
+**Resolve seu problema #2:** testar grab sem Touch Plus.
-- Mantém o mapeamento atual mas **só ativa quando NENHUM grip está apertado** (para não brigar com o grab).
-- `posStep` e `rotStep` ganham multiplicador derivado de `triggerValue` da mesma mão: trigger leve = passo fino (×0.3), trigger forte = passo rápido (×3). Resolve a queixa de "movimento mecânico".
-- Mapeamento corrigido para o padrão VR (já discutido):
- - Esquerdo: X horizontal / Z vertical (frente-trás).
- - Direito: rotY horizontal / Y altura vertical.
-- Adiciona aceleração proporcional (curva quadrática no input do thumbstick) e deadzone de 0.15.
+- 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. Escala no store
+### 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.**
-`src/stores/useModelStore.ts`: adicionar `scale: number` ao `FineTuning` (default 1). `XRModel` e `ModelViewer` aplicam `scale={[s,s,s]}` no ``.
+### 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.
-### 5. UI: feedback visual e ajuda
+### 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.
-- `XRGrabbable` mostra um halo sutil ao redor da peça quando `gripValue > 0.1` em qualquer mão (intensidade proporcional → o usuário sente a pressão analógica).
-- `src/components/XRHud.tsx`: na seção de Ajuda (?), adicionar bloco "Agarrar a peça":
- - "Aperte o grip lateral de um controle perto da peça → ela vira extensão da sua mão."
- - "Agarre com os dois grips ao mesmo tempo → rotacione girando os punhos / aproxime-afaste para escalar."
- - "Solte o grip para fixar."
- - "Trigger modula a velocidade do joystick (leve = fino, forte = rápido)."
-- Adicionar toggle "Permitir escala (two-hand)" — default OFF para preservar 1:1.
+### 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").
-### 6. Integração e ordem de aplicação
+## Pontos de injeção em `XRSession.tsx`
-No `XRSession.tsx`, a árvore vira:
+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 && }
```
- (posicionamento inicial)
- (grab 6DOF + two-hand)
-
+
+E uma linha em `useControllerGrab.ts`:
+```ts
+// DEVKIT: remove this conditional
+if (typeof window !== 'undefined' && useDevKitFake()) return fakeRef;
```
-Hit-test só atua enquanto `placementMode = true`. Quando o usuário agarra pela primeira vez, `placementMode` é desligado automaticamente.
-### Detalhes técnicos
+## Como remover o DevKit no futuro (1 minuto)
-- Tudo via WebXR Gamepad API + `XRFrame.getPose(gripSpace, referenceSpace)`. Sem dependências novas.
-- Histerese do grip evita perder o grab por tremor de mão.
-- Decomposição de matrix usa `THREE.Matrix4.decompose()` para gravar de volta no store sem perder rotação composta.
-- Plane snapping continua ativo durante o grab (snap acontece no `onRelease`, não a cada frame, para não travar o movimento).
-- Logs `[XR][grab]` para diagnóstico (start/end, qual mão, valor analógico).
+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.
-### Arquivos afetados
+## Entregas desta primeira leva (priorizadas)
-- **Novo**: `src/hooks/useControllerGrab.ts`
-- **Novo**: `src/components/three/XRGrabbable.tsx`
-- **Editado**: `src/pages/XRSession.tsx` — envolver modelo, ajustar `ControllerFineTuning` (mapeamento + modulação por trigger + bypass quando grip ativo)
-- **Editado**: `src/stores/useModelStore.ts` — campo `scale`
-- **Editado**: `src/components/three/ModelViewer.tsx` — aplicar `scale`
-- **Editado**: `src/components/XRHud.tsx` — toggle "permitir escala", ajuda nova
+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).
diff --git a/src/devkit/fakeInputStore.ts b/src/devkit/fakeInputStore.ts
new file mode 100644
index 0000000..307076f
--- /dev/null
+++ b/src/devkit/fakeInputStore.ts
@@ -0,0 +1,48 @@
+/**
+ * DEVKIT — global mutable store for fake controller inputs.
+ *
+ * Lives outside React (plain object + listeners) so useControllerGrab can
+ * read it from inside useFrame with zero re-render cost. Mirrors the shape
+ * of a real WebXR XRInputSource just enough to feed our grab logic.
+ */
+import * as THREE from 'three';
+
+export interface FakeHandState {
+ gripValue: number; // 0..1
+ triggerValue: number; // 0..1
+ hasPose: boolean; // true if controller is "tracked"
+ gripWorld: THREE.Matrix4; // world pose of the gripSpace
+}
+
+export interface FakeInputState {
+ active: boolean;
+ left: FakeHandState;
+ right: FakeHandState;
+}
+
+function makeHand(): FakeHandState {
+ return {
+ gripValue: 0,
+ triggerValue: 0,
+ hasPose: true,
+ gripWorld: new THREE.Matrix4(),
+ };
+}
+
+export const fakeInput: FakeInputState = {
+ active: false,
+ left: makeHand(),
+ right: makeHand(),
+};
+
+// Initial poses — a bit in front of the camera, hands apart at chest height
+fakeInput.left.gripWorld.makeTranslation(-0.25, 1.2, -0.5);
+fakeInput.right.gripWorld.makeTranslation(0.25, 1.2, -0.5);
+
+export function setFakeActive(on: boolean) {
+ fakeInput.active = on;
+}
+
+export function isFakeActive(): boolean {
+ return fakeInput.active;
+}
diff --git a/src/devkit/useDevKit.ts b/src/devkit/useDevKit.ts
new file mode 100644
index 0000000..a200c96
--- /dev/null
+++ b/src/devkit/useDevKit.ts
@@ -0,0 +1,43 @@
+/**
+ * DEVKIT entry point. The whole devkit is gated by this single flag.
+ *
+ * Activation: append `?devkit=1` to URL OR run in console:
+ * localStorage.setItem('devkit', '1')
+ * Deactivation: `?devkit=0` OR localStorage.removeItem('devkit')
+ *
+ * To remove DevKit from the project entirely:
+ * 1. rm -rf src/devkit/
+ * 2. Strip `// DEVKIT:` blocks in XRSession.tsx & useControllerGrab.ts
+ */
+import { useEffect, useState } from 'react';
+
+const KEY = 'devkit';
+
+function readFlag(): boolean {
+ if (typeof window === 'undefined') return false;
+ const params = new URLSearchParams(window.location.search);
+ const urlVal = params.get(KEY);
+ if (urlVal === '1') {
+ localStorage.setItem(KEY, '1');
+ return true;
+ }
+ if (urlVal === '0') {
+ localStorage.removeItem(KEY);
+ return false;
+ }
+ return localStorage.getItem(KEY) === '1';
+}
+
+export function useDevKit(): boolean {
+ const [enabled, setEnabled] = useState(readFlag);
+ useEffect(() => {
+ const onStorage = () => setEnabled(readFlag());
+ window.addEventListener('storage', onStorage);
+ return () => window.removeEventListener('storage', onStorage);
+ }, []);
+ return enabled;
+}
+
+export function isDevKit(): boolean {
+ return readFlag();
+}
From 7772630f922bbdaa567460f639ffb6f9fa82d241 Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
<159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Tue, 12 May 2026 11:01:19 +0000
Subject: [PATCH 2/6] Changes
Co-authored-by: Reifonas <211114984+Reifonas@users.noreply.github.com>
---
src/devkit/DevPanel.tsx | 166 +++++++++++++++++++++++++++++++++
src/devkit/FakeControllers.tsx | 119 +++++++++++++++++++++++
2 files changed, 285 insertions(+)
create mode 100644 src/devkit/DevPanel.tsx
create mode 100644 src/devkit/FakeControllers.tsx
diff --git a/src/devkit/DevPanel.tsx b/src/devkit/DevPanel.tsx
new file mode 100644
index 0000000..63115c3
--- /dev/null
+++ b/src/devkit/DevPanel.tsx
@@ -0,0 +1,166 @@
+/**
+ * DEVKIT — HTML overlay panel with diagnostics.
+ *
+ * Tabs:
+ * - Inputs: live grip/trigger/pose values for both controllers (real or fake)
+ * - Logs: captures last 100 console.log/warn/error entries with filter
+ *
+ * Always visible when ?devkit=1, top-right corner.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { fakeInput, isFakeActive } from './fakeInputStore';
+
+interface LogEntry {
+ ts: number;
+ level: 'log' | 'warn' | 'error';
+ msg: string;
+}
+
+const logBuffer: LogEntry[] = [];
+let installed = false;
+
+function installLogger() {
+ if (installed) return;
+ installed = true;
+ (['log', 'warn', 'error'] as const).forEach((level) => {
+ const orig = console[level].bind(console);
+ console[level] = (...args: unknown[]) => {
+ try {
+ const msg = args.map((a) => {
+ if (typeof a === 'string') return a;
+ try { return JSON.stringify(a); } catch { return String(a); }
+ }).join(' ');
+ logBuffer.push({ ts: Date.now(), level, msg });
+ if (logBuffer.length > 200) logBuffer.shift();
+ } catch { /* noop */ }
+ orig(...args);
+ };
+ });
+}
+
+type Tab = 'inputs' | 'logs';
+
+interface DevPanelProps {
+ simXR: boolean;
+ onToggleSimXR: () => void;
+}
+
+export function DevPanel({ simXR, onToggleSimXR }: DevPanelProps) {
+ const [tab, setTab] = useState('inputs');
+ const [collapsed, setCollapsed] = useState(false);
+ const [, tick] = useState(0);
+ const [logFilter, setLogFilter] = useState('');
+ const rafRef = useRef(null);
+
+ useEffect(() => { installLogger(); }, []);
+
+ useEffect(() => {
+ let last = 0;
+ const loop = (t: number) => {
+ if (t - last > 150) { tick((n) => n + 1); last = t; }
+ rafRef.current = requestAnimationFrame(loop);
+ };
+ rafRef.current = requestAnimationFrame(loop);
+ return () => { if (rafRef.current) cancelAnimationFrame(rafRef.current); };
+ }, []);
+
+ if (collapsed) {
+ return (
+
+ );
+ }
+
+ return (
+