SteelXR/.lovable/plan.md

Plano: Grab nativo dos controles Touch Plus (Quest 3) para "vestir" a peça virtual

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.

1. Camada de input nova: useControllerGrab

Novo hook em src/hooks/useControllerGrab.ts que encapsula tudo que falta hoje:

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

2. Componente XRGrabbable em volta da peça

Novo arquivo src/components/three/XRGrabbable.tsx. Wrappa o <XRModel/> em um <group> controlado e implementa as três modalidades de grab:

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

3. Joystick continua, agora modulado pelo grip analógico

Em ControllerFineTuning (dentro de XRSession.tsx):

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

4. Escala no store

src/stores/useModelStore.ts: adicionar scale: number ao FineTuning (default 1). XRModel e ModelViewer aplicam scale={[s,s,s]} no <group>.

5. UI: feedback visual e ajuda

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

6. Integração e ordem de aplicação

No XRSession.tsx, a árvore vira:

<XRHitTestPlacement> (posicionamento inicial)
  <XRGrabbable> (grab 6DOF + two-hand)
    <XRModel/>

Hit-test só atua enquanto placementMode = true. Quando o usuário agarra pela primeira vez, placementMode é desligado automaticamente.

Detalhes técnicos

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

Arquivos afetados

• 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