Added lock system & reparent

X-Lovable-Edit-ID: edt-7f9adc17-9459-49fc-97ab-592e923504cd
Co-authored-by: Reifonas <211114984+Reifonas@users.noreply.github.com>

.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→<parentName>`
+- `[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 && <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?
+- `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→<parent>` em todo grab.

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
                 </Button>
               )}
 
+              {/* Lock / Unlock — fixa a peça no espaço */}
+              <Button
+                variant={isLocked ? 'default' : 'outline'}
+                size="sm" className="h-8 gap-1.5 text-[10px] font-mono"
+                onClick={() => {
+                  const next = !isLocked;
+                  setLocked(next);
+                  console.log(`[lock] ${next ? 'ON' : 'OFF'}`);
+                  toast[next ? 'success' : 'message'](next ? 'Peça fixada no espaço 🔒' : 'Peça liberada 🔓');
+                }}
+                title="Fixa/libera a peça no espaço (ignora Grip enquanto travada)"
+              >
+                {isLocked ? <Lock className="h-3.5 w-3.5" /> : <Unlock className="h-3.5 w-3.5" />}
+                {isLocked ? 'Fixada' : 'Fixar'}
+              </Button>
+
               <Button
                 variant={freeMove ? 'default' : 'outline'}
                 size="sm" className="h-8 gap-1.5 text-[10px] font-mono"

src/components/three/XRGrabbable.tsx

@@ -1,7 +1,8 @@
 import { useRef, ReactNode } from 'react';
-import { useFrame } from '@react-three/fiber';
+import { useFrame, useThree } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useControllerGrab, ControllerGrabSnapshot } from '@/hooks/useControllerGrab';
+import { useModelStore } from '@/stores/useModelStore';
 
 interface XRGrabbableProps {
   /** Allow uniform scaling via two-hand grab (distance between hands) */
@@ -42,18 +43,57 @@ const _tmpQuat = new THREE.Quaternion();
  *  • Two-hand grab: midpoint = pivot, axis between hands = rotation,
  *    distance ratio = uniform scale (if allowScale).
  *
- * On release the group keeps its last pose (we don't write to the store —
- * the manual fine-tuning sliders remain available as additional offsets).
+ * Parent re-attach strategy:
+ *  At grab start the group is attached to the Scene root (preserving
+ *  world-transform). At grab end it is re-attached to its original parent
+ *  (typically XRHitTestPlacement), unless `isLocked` is true — in which case
+ *  it stays anchored in world space and the original parent can no longer
+ *  influence its matrix.
  */
 export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGrabbableProps) {
   const groupRef = useRef<THREE.Group>(null);
   const grab = useControllerGrab();
+  const { scene } = useThree();
 
   const single = useRef<SingleGrabRecord | null>(null);
   const dual = useRef<DualGrabRecord | null>(null);
+  /** Parent the group belonged to before the active grab started. */
+  const originalParent = useRef<THREE.Object3D | null>(null);
   const haloRef = useRef<THREE.Mesh>(null);
+  const lockHaloRef = useRef<THREE.Mesh>(null);
   const everGrabbed = useRef(false);
 
+  const beginGrab = (mode: 'single' | 'dual', hand: 'left' | 'right' | 'dual') => {
+    const group = groupRef.current;
+    if (!group) return;
+    // Reparent to scene root preserving world-transform.
+    if (group.parent && group.parent !== scene) {
+      originalParent.current = group.parent;
+      scene.attach(group);
+      console.log(`[XR][grab] attach→scene (mode=${mode} hand=${hand})`);
+    } else if (!originalParent.current) {
+      originalParent.current = group.parent ?? scene;
+    }
+    if (!everGrabbed.current) { everGrabbed.current = true; onGrabStart?.(); }
+  };
+
+  const endGrab = () => {
+    const group = groupRef.current;
+    if (!group) return;
+    const locked = useModelStore.getState().isLocked;
+    if (locked) {
+      console.log('[XR][grab] release→scene (locked, staying anchored)');
+      return;
+    }
+    const target = originalParent.current;
+    originalParent.current = null;
+    if (target && target !== group.parent) {
+      const name = target === scene ? 'scene' : (target.name || target.type);
+      target.attach(group);
+      console.log(`[XR][grab] release→${name}`);
+    }
+  };
+
   useFrame(() => {
     const group = groupRef.current;
     if (!group) return;
@@ -63,14 +103,20 @@ export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGra
 
     const lActive = L.isGrabbing && L.hasPose;
     const rActive = R.isGrabbing && R.hasPose;
+    const isLocked = useModelStore.getState().isLocked;
 
     // ─── Halo intensity (visual feedback for analog grip) ────────
     if (haloRef.current) {
-      const maxGrip = Math.max(L.gripValue, R.gripValue);
+      const maxGrip = isLocked ? 0 : Math.max(L.gripValue, R.gripValue);
       const mat = haloRef.current.material as THREE.MeshBasicMaterial;
       mat.opacity = maxGrip * 0.25;
       haloRef.current.visible = maxGrip > 0.05;
     }
+    if (lockHaloRef.current) {
+      const mat = lockHaloRef.current.material as THREE.MeshBasicMaterial;
+      mat.opacity = 0.18;
+      lockHaloRef.current.visible = isLocked;
+    }
 
     // ─── Two-hand mode ───────────────────────────────────────────
     if (lActive && rActive) {
@@ -83,7 +129,9 @@ export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGra
       axisNow.divideScalar(distNow);
 
       if (!dual.current) {
-        // Capture
+        // Capture — reparent BEFORE snapshotting matrixWorld so subsequent
+        // applyWorldMatrixToLocal math is consistent.
+        beginGrab('dual', 'dual');
         group.updateMatrixWorld();
         dual.current = {
           startGroupWorld: group.matrixWorld.clone(),
@@ -93,7 +141,6 @@ export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGra
           startScale: group.scale.x,
         };
         single.current = null; // dual takes over
-        if (!everGrabbed.current) { everGrabbed.current = true; onGrabStart?.(); }
         console.log('[XR][grab] ◆ TWO-HAND start');
       }
 
@@ -123,6 +170,7 @@ export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGra
     } else if (dual.current) {
       console.log('[XR][grab] ◆ TWO-HAND end');
       dual.current = null;
+      if (!lActive && !rActive) endGrab();
     }
 
     // ─── One-hand mode ───────────────────────────────────────────
@@ -130,18 +178,19 @@ export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGra
     if (activeHand) {
       const slot = activeHand === 'left' ? L : R;
       if (!single.current || single.current.hand !== activeHand) {
+        beginGrab('single', activeHand);
         group.updateMatrixWorld();
         const offset = new THREE.Matrix4()
           .copy(slot.gripWorld).invert()
           .multiply(group.matrixWorld);
         single.current = { hand: activeHand, offset };
-        if (!everGrabbed.current) { everGrabbed.current = true; onGrabStart?.(); }
         console.log(`[XR][grab] ● ONE-HAND start (${activeHand})`);
       }
       _tmpMat.multiplyMatrices(slot.gripWorld, single.current.offset);
       applyWorldMatrixToLocal(group, _tmpMat);
     } else if (single.current) {
       single.current = null;
+      endGrab();
     }
   });
 
@@ -152,6 +201,11 @@ export function XRGrabbable({ allowScale = false, onGrabStart, children }: XRGra
         <sphereGeometry args={[0.5, 16, 12]} />
         <meshBasicMaterial color="#22c55e" transparent opacity={0} depthWrite={false} />
       </mesh>
+      {/* Lock halo — golden, visible while isLocked is true */}
+      <mesh ref={lockHaloRef} visible={false}>
+        <sphereGeometry args={[0.55, 16, 12]} />
+        <meshBasicMaterial color="#f59e0b" transparent opacity={0} depthWrite={false} wireframe />
+      </mesh>
       {children}
     </group>
   );

src/devkit/DevPanel.tsx

@@ -161,6 +161,7 @@ export function DevPanel({ simXR, onToggleSimXR }: DevPanelProps) {
               <div>Q/W = grip L/R · A/S = trigger L/R</div>
               <div>1/2 = ativar mão · setas = mover</div>
               <div>Shift+↑/↓ = Z (frente/trás) · R = reset</div>
+              <div>L = fixar/liberar peça (lock)</div>
             </div>
           </div>
         )}

src/devkit/FakeControllers.tsx

@@ -18,6 +18,7 @@ import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
 import { fakeInput, setFakeActive } from './fakeInputStore';
 import { isPlaybackActive } from './macroStore';
+import { useModelStore } from '@/stores/useModelStore';
 
 const STEP = 0.03; // m per keypress
 
@@ -71,6 +72,12 @@ export function FakeControllers() {
         fakeInput.right.gripWorld.makeTranslation(0.25, 1.2, -0.5);
         force((n) => n + 1);
         return;
+      } else if (k === 'l' || k === 'L') {
+        const s = useModelStore.getState();
+        const next = !s.isLocked;
+        s.setLocked(next);
+        console.log(`[lock] ${next ? 'ON' : 'OFF'} (keyboard)`);
+        return;
       }
       apply();
     };

src/devkit/SmokeTest.tsx

@@ -6,6 +6,7 @@
  */
 import { useState } from 'react';
 import { Link, Navigate } from 'react-router-dom';
+import * as THREE from 'three';
 import { useModelStore } from '@/stores/useModelStore';
 import { generateDemoBeamGLB } from '@/lib/generateDemoBeam';
 import { useDevKit } from './useDevKit';
@@ -105,6 +106,50 @@ function buildSteps(): Step[] {
         return location.protocol;
       },
     },
+    {
+      name: 'reparent preserva world-transform (Object3D.attach)',
+      run: async () => {
+        const scene = new THREE.Scene();
+        const parent = new THREE.Group();
+        parent.position.set(1, 2, 3);
+        parent.rotation.set(0, Math.PI / 4, 0);
+        scene.add(parent);
+        const child = new THREE.Group();
+        child.position.set(0.5, 0, 0);
+        parent.add(child);
+        scene.updateMatrixWorld(true);
+        const beforeWorld = child.matrixWorld.clone();
+        scene.attach(child);
+        scene.updateMatrixWorld(true);
+        const afterWorld = child.matrixWorld.clone();
+        for (let i = 0; i < 16; i++) {
+          if (Math.abs(beforeWorld.elements[i] - afterWorld.elements[i]) > 1e-5) {
+            throw new Error(`world drift no índice ${i}`);
+          }
+        }
+        // re-attach back
+        parent.attach(child);
+        scene.updateMatrixWorld(true);
+        const restored = child.matrixWorld.clone();
+        for (let i = 0; i < 16; i++) {
+          if (Math.abs(beforeWorld.elements[i] - restored.elements[i]) > 1e-5) {
+            throw new Error(`world drift restore ${i}`);
+          }
+        }
+        return 'world preserved';
+      },
+    },
+    {
+      name: 'lock toggle persiste no store',
+      run: async () => {
+        store().setLocked(false);
+        if (store().isLocked) throw new Error('isLocked deveria ser false');
+        store().setLocked(true);
+        if (!store().isLocked) throw new Error('setLocked(true) falhou');
+        store().setLocked(false);
+        return 'ok';
+      },
+    },
   ];
 }
 

src/hooks/useControllerGrab.ts

@@ -1,6 +1,7 @@
 import { useRef } from 'react';
 import { useFrame, useThree } from '@react-three/fiber';
 import * as THREE from 'three';
+import { useModelStore } from '@/stores/useModelStore';
 // DEVKIT: remove this import + the fake-input block in useFrame to strip devkit
 import { fakeInput, isFakeActive } from '@/devkit/fakeInputStore';
 
@@ -52,6 +53,8 @@ export function useControllerGrab() {
   const { gl } = useThree();
 
   useFrame((_state, _delta, frame: XRFrame | undefined) => {
+    const locked = useModelStore.getState().isLocked;
+
     // DEVKIT: fake-input branch — bypasses real WebXR when SimXR is active.
     if (isFakeActive()) {
       for (const hand of ['left', 'right'] as const) {
@@ -61,6 +64,13 @@ export function useControllerGrab() {
         slot.triggerValue = fake.triggerValue;
         slot.hasPose = fake.hasPose;
         slot.gripWorld.copy(fake.gripWorld);
+        if (locked) {
+          if (slot.isGrabbing) {
+            slot.isGrabbing = false;
+            console.log(`[XR][grab] ◼ ${hand} END (locked)`);
+          }
+          continue;
+        }
         if (!slot.isGrabbing && fake.gripValue > GRAB_ON) {
           slot.isGrabbing = true;
           console.log(`[XR][grab] ▶ ${hand} START (fake v=${fake.gripValue.toFixed(2)})`);
@@ -93,8 +103,12 @@ export function useControllerGrab() {
         const trigValue = trigBtn ? (trigBtn.value || (trigBtn.pressed ? 1 : 0)) : 0;
         slot.gripValue = gripValue;
         slot.triggerValue = trigValue;
-        // Hysteresis
-        if (!slot.isGrabbing && gripValue > GRAB_ON) {
+        if (locked) {
+          if (slot.isGrabbing) {
+            slot.isGrabbing = false;
+            console.log(`[XR][grab] ◼ ${source.handedness} END (locked)`);
+          }
+        } else if (!slot.isGrabbing && gripValue > GRAB_ON) {
           slot.isGrabbing = true;
           console.log(`[XR][grab] ▶ ${source.handedness} START (v=${gripValue.toFixed(2)})`);
         } else if (slot.isGrabbing && gripValue < GRAB_OFF) {

src/stores/useModelStore.ts

@@ -118,6 +118,10 @@ interface ModelStore {
   addScreenshot: (dataUrl: string) => void;
   removeScreenshot: (index: number) => void;
   clearScreenshots: () => void;
+
+  /** When true, the grabbed model stays frozen in world space (grip is ignored). */
+  isLocked: boolean;
+  setLocked: (locked: boolean) => void;
 }
 
 const defaultFineTuning: FineTuning = { posX: 0, posY: 0, posZ: 0, rotX: 0, rotY: 0, rotZ: 0, scale: 1 };
@@ -219,4 +223,7 @@ export const useModelStore = create<ModelStore>((set) => ({
     screenshots: state.screenshots.filter((_, i) => i !== index),
   })),
   clearScreenshots: () => set({ screenshots: [] }),
+
+  isLocked: false,
+  setLocked: (isLocked) => set({ isLocked }),
 }));