From d6064be80b139bdbaf5478d61765267d8fd5d632 Mon Sep 17 00:00:00 2001
From: "gpt-engineer-app[bot]"
 <159125892+gpt-engineer-app[bot]@users.noreply.github.com>
Date: Sat, 28 Feb 2026 18:47:45 +0000
Subject: [PATCH] Save plan in Lovable

---
 .lovable/plan.md | 71 ++++++++++++++++++++++++++++--------------------
 1 file changed, 41 insertions(+), 30 deletions(-)

diff --git a/.lovable/plan.md b/.lovable/plan.md
index 06b3029..5891c4b 100644
--- a/.lovable/plan.md
+++ b/.lovable/plan.md
@@ -1,43 +1,54 @@
 
 
-## Plano: Corrigir entrada XR no Meta Quest 3
+## Plan: Help Button + Full Rotation Controls (X, Y, Z)
 
-### Problema raiz
-O codigo atual cria **duas sessoes XR em sequencia**: primeiro manualmente via `navigator.xr.requestSession('immersive-ar', ...)` (linha 242), depois via `xrStore.enterAR()` (linha 271). O Quest 3 rejeita a segunda porque ja existe uma sessao ativa. Alem disso, a primeira sessao nao esta conectada ao renderer do Three.js, entao mesmo se funcionasse, nao renderizaria nada.
+### 1. Add rotX and rotZ to the store
 
-### Correcoes
+Update `src/stores/useModelStore.ts`:
+- Add `rotX: number` and `rotZ: number` to the `FineTuning` interface
+- Set defaults to 0 in `defaultFineTuning`
 
-**1. Remover a chamada manual a `navigator.xr.requestSession`**
-- Eliminar todo o bloco `try` das linhas 239-268 que tenta criar uma sessao manualmente
-- A lib `@react-three/xr` gerencia a sessao internamente via `xrStore.enterAR()`
+### 2. Apply rotX/rotZ to the XR model
 
-**2. Usar `customSessionInit` no `createXRStore` para image tracking**
-- A lib suporta `customSessionInit` em `XRSessionInitOptions` que permite injetar opcoes extras na sessao
-- Passar `optionalFeatures: ['image-tracking']` e `trackedImages` via `customSessionInit`
-- O `createXRStore` ja adiciona `local-floor`, `hand-tracking`, `anchors`, `plane-detection` automaticamente
+Update `src/pages/XRSession.tsx` (`XRModel` component):
+- Read `rotX`, `rotZ` from fineTuning
+- Change `rotation={[0, rotYRad, 0]}` to `rotation={[rotXRad, rotYRad, rotZRad]}`
 
-**3. Condicionar o emulador**
-- `emulate: 'metaQuest3'` ativa o emulador IWER em localhost, o que pode interferir no Quest real
-- Condicionar: so emular se nao estiver em dispositivo XR real (checar `navigator.xr?.isSessionSupported`)
-- Ou mais simples: so emular em `location.hostname === 'localhost'` E quando `!navigator.xr`
+Update `ControllerFineTuning`:
+- Map additional controller inputs (e.g., A/B buttons or grip+joystick combos) to rotX/rotZ, or leave rotation to the HUD controls
 
-**4. Arquivo: `src/pages/XRSession.tsx`**
+### 3. Add rotX/rotZ controls to XRHud
 
-Mudancas:
-- Mover criacao do store para dentro do componente (ou lazy init) para poder passar o bitmap como `customSessionInit`
-- `handleEnterAR`: simplificar para apenas `await xrStore.enterAR()` com listener de `end`
-- Manter `ImageTrackingAnchor`, `ControllerFineTuning`, `XRModel` sem alteracoes
+Update `src/components/XRHud.tsx`:
+- In the fine-tuning expanded panel, add rotation rows for X° and Z° alongside the existing Y° control (same `+/−` button pattern)
 
-```text
-ANTES (bugado):
-  1. navigator.xr.requestSession('immersive-ar')  ← cria sessao A
-  2. xrStore.enterAR()                              ← tenta sessao B → REJEITADA
+### 4. Create Help panel with (?) button
 
-DEPOIS (correto):
-  1. createXRStore({ customSessionInit: { optionalFeatures: ['image-tracking'], trackedImages: [...] } })
-  2. xrStore.enterAR()                              ← unica sessao, com image tracking
-```
+Update `src/components/XRHud.tsx`:
+- Add a `HelpCircle` (?) icon button to the main toolbar
+- When pressed, open a full-height slide-out panel (same pattern as the checklist panel) containing a scrollable list of all tools and controls with descriptions:
 
-### Sem alteracoes em
-- ModelViewer, ViewerControls, SmartMeasure, checklist, medicoes, screenshots, PDF, IFC import
+Content sections:
+- **Posicionar (Hit-Test)**: Tap to place model on real surfaces
+- **Snap**: Auto-align to detected planes (floor, wall, table)
+- **Mover (Free Move)**: Use left joystick for X/Y, right joystick for Z movement
+- **Grid**: Toggle reference grid
+- **Sólido / Wire / Bordas**: Render mode switching
+- **Medir**: Tap two points to measure distance in mm
+- **Screenshot**: Capture current AR view
+- **Inspeção**: Open checklist to approve/reject items
+- **Opacidade**: Adjust model transparency
+- **Posição (mm)**: Fine-tune X/Y/Z in 1mm steps
+- **Rotação X° / Y° / Z°**: Rotate model around each axis
+- **Controladores Quest 3**: Joystick left = move X/Y, joystick right = move Z + rotate Y, grip = hold to move (when Free Move is off)
+
+### 5. Also apply rotX/rotZ in desktop ModelViewer (if used)
+
+Check `src/components/three/ModelViewer.tsx` and update rotation there too for consistency.
+
+### Files to modify
+- `src/stores/useModelStore.ts` — add rotX, rotZ fields
+- `src/pages/XRSession.tsx` — apply 3-axis rotation, update controller mapping
+- `src/components/XRHud.tsx` — add rotation controls for X/Z, add help (?) panel
+- `src/components/three/ModelViewer.tsx` — apply rotX/rotZ if fineTuning is used there