feat(ui): Add gizmo manipulator for axis move/rotate (v0.3.0)

- New "操作器" toggle: select a file in the tree and a 3-axis gizmo
  appears at its center -- XYZ arrows (TranslateManipulator) to move
  along an axis regardless of view angle, and rotation rings
  (RotateManipulator) to rotate any angle about an axis
- Manipulators bind to a proxy ModelVisual3D; the proxy's transform
  is mirrored to all target BodyVisuals during drag (GPU-side, temp)
- On release the accumulated transform is baked into B-rep via
  TransformRoot (deferred with Dispatcher.BeginInvoke to avoid
  reentrancy with the manipulator's own mouse-up handling); the
  gizmo re-centers on the new bounds
- Temporary transforms are cleared with Transform3D.Identity, never
  null (HelixToolkit GetTransform crashes on null child.Transform)
- Selecting another file retargets the gizmo; removing the target
  hides it
- Docs updated (ARCHITECTURE Phase 10, CLAUDE.md, README)

Known limitation: gizmo handles are occluded inside solid parts
(WPF single depth buffer). Next: always-on-top overlay viewport.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -179,6 +179,7 @@ class MeasurementResult
 | 三點對齊 | 模式「三點」+ 來源檔 3 點、目標檔 3 對應點 | 旋轉+平移剛體變換（點1精確貼合、1→2 方向對齊、三點平面對齊；`RigidAlign`） |
 | 旋轉 | 樹面板選檔案 + 工具列 ↻X/↻Y/↻Z | 繞檔案中心 +90°（連按累加；方向不合時先轉正再對齊） |
 | 拖曳 | 模式「🖐 拖曳」（手形游標）+ 左鍵按住零件拖 | 沿螢幕平面移動該檔案，放開烘進 B-rep（拖曳中僅暫時 Transform，不卡） |
+| 操作器 | 「⊹ 操作器」+ 樹面板選檔案 | XYZ 箭頭沿軸移動、旋轉環繞軸轉任意角度（與視角無關）；每次放開烘進 B-rep |
 | 干涉 | 工具列「🧩 干涉」（需剛好 2 個可見檔案） | 相交→紅色交線+相交三角形對數；無相交→最小間隙 gap（≈0 即配合 match） |
 | 剖面 | 工具列「✂ 剖面」+ 軸向/位置/反向 | CPU 裁切渲染網格（原始幾何保留，量測仍精確） |
 | 單位 | 工具列 mm ⇄ in | 既有量測（清單+3D 標籤）即時換算 |
@@ -326,6 +327,14 @@ NuGet 相依（自動還原）：`CADability`、`HelixToolkit.Wpf`、`CommunityT
 > v0.2.1 修正：拖曳放開時清除暫時位移誤用 `Transform = null`，導致下次 `FindHits` 命中該檔案時
 > HelixToolkit `GetTransform` 對 null transform `Add` 而 crash。改用 `Transform3D.Identity`。
 
+### Phase 10 — Gizmo 三軸操作器（工作量：M）
+- [x] 「⊹ 操作器」toggle — 對樹面板選取的檔案顯示 Helix `TranslateManipulator` ×3（XYZ 紅綠藍箭頭）+ `RotateManipulator` ×3（旋轉環），尺寸隨檔案 Bounds 自適應
+- [x] 操作器綁定代理 `ModelVisual3D`，拖動中代理 Transform 即時套到目標所有 BodyVisual（暫時、GPU 端）；邊線暫停
+- [x] 放開滑鼠（`handledEventsToo` 捕捉）→ `Dispatcher.BeginInvoke` 延後 `TransformRoot` 烘進 B-rep、操作器歸零並移到新中心
+- [x] 換樹選取自動換目標；目標被移除自動收掉；暫時 Transform 清除用 `Identity`（非 null）
+
+**驗收：** 拖 X 箭頭零件僅沿世界 X 移動（與視角無關）；拖環任意角度旋轉；放開後量測/干涉與顯示位置一致
+
 ---
 
 ## Future Extensions（下一輪）

CLAUDE.md

@@ -44,7 +44,12 @@ dotnet publish src/STPViewer -c Release -o publish/STPViewer
   合併網格的 hit-test 走 `_mergedMap`（合併 Model → leaf）；拖曳中邊線用 `_edgesSuspended` 暫停
 - ⚠️ **`Visual3D.Transform` 永遠不要設成 `null`，清除要用 `Transform3D.Identity`**。HelixToolkit `Viewport3DHelper.GetTransform`
   對 `child.Transform` 沒做 null 檢查（`GeneralTransform3DGroup.Children.Add(null)` → 拋「無法新增空值到集合中」），
-  之後任何 `FindHits` 都會 crash。v0.2.1 修的就是拖曳放開時把 BodyVisual.Transform 設 null（拖過一次後再點擊就炸）
+  之後任何 `FindHits` 都會 crash。v0.2.1 修的就是拖曳放開時把 BodyVisual.Transform 設 null（拖過一次後再點擊就炸）。
+  Gizmo 的暫時 Transform 清除同理一律用 Identity
+- Gizmo 操作器：Helix `TranslateManipulator`/`RotateManipulator` ×6 `Bind` 到代理 `ModelVisual3D`，
+  代理 Transform 變更（`DependencyPropertyDescriptor.AddValueChanged`）即時套到目標 BodyVisual（暫時）；
+  **放開滑鼠才 `TransformRoot` 烘焙** — MouseUp 被 manipulator 標 handled，MainWindow 用 `AddHandler(..., handledEventsToo: true)` 才收得到。
+  烘焙用 `Dispatcher.BeginInvoke` 延後到 manipulator 自身事件處理完，避免 reentrancy；`_gizmoBaking` 旗標防 Transform 歸零的回呼重入
 - 干涉/面距/對齊等運算在背景執行緒；`Freeze()` 幾何後才跨執行緒
 - 匯入在背景執行緒；`Freeze()` 幾何後才跨執行緒
 - Commit 格式：Conventional Commits（`feat:` / `fix:` / `docs:` …）

README.md

@@ -22,6 +22,7 @@ STP/STEP 3D 檢視器（Windows 桌面程式，C# .NET 8 WPF）— 多檔匯入
   | 🎯 三點 | 來源檔 3 特徵點 + 目標檔 3 對應點 → 旋轉+平移一次貼合（方向不同也能對） |
 - **旋轉**：樹面板選檔案 + 工具列 ↻X/↻Y/↻Z 繞中心 +90°（擺正方向用，連按累加）
 - **拖曳** 🖐：手形游標模式，左鍵按住零件沿螢幕平面拖動、放開定位（粗定位用；精確貼合用對齊）；右鍵轉視角不受影響
+- **操作器** ⊹：樹面板選檔案 → 顯示 XYZ 三色箭頭 + 旋轉環（Fusion 360 風格）；拖箭頭沿該軸移動（與視角無關，適合沿插合軸推進）、拖環繞軸轉任意角度，放開即定位
 - **干涉檢查** 🧩：勾選剛好 2 個可見檔案 → 相交時顯示紅色干涉交線 + 相交三角形對數；無相交時回報最小間隙 gap（gap≈0 即為配合 match，共面貼合不算干涉）
 - **剖面**：✂ 開關 + X/Y/Z 軸 + 位置滑桿 + 反向；CPU 網格裁切，原始幾何保留（量測不受影響）
 - **單位**：mm ⇄ inch 一鍵切換，既有量測（清單與 3D 標籤）即時換算

src/STPViewer/MainWindow.xaml

@@ -62,6 +62,8 @@
                 <ToggleButton Style="{StaticResource ModeButton}"
                               ToolTip="拖曳模式：左鍵按住零件沿螢幕平面拖動，放開定位（深度方向先轉視角再拖）"
                               IsChecked="{Binding CurrentMode, Converter={StaticResource ModeConv}, ConverterParameter=Drag}">🖐 拖曳</ToggleButton>
+                <ToggleButton IsChecked="{Binding GizmoEnabled}" Padding="8,4" FontSize="13"
+                              ToolTip="三軸操作器：對樹面板選取的檔案顯示 XYZ 箭頭（沿軸移動）與旋轉環（繞軸轉任意角度），每次放開即定位">⊹ 操作器</ToggleButton>
                 <Button Command="{Binding CheckInterferenceCommand}" Padding="8,4" FontSize="13"
                         ToolTip="干涉檢查：檢查 2 個可見檔案是否相交（match 判定）；無相交時回報最小間隙">🧩 干涉</Button>
                 <Separator />

src/STPViewer/MainWindow.xaml.cs

@@ -16,6 +16,10 @@ public partial class MainWindow : Window
         DataContext = _vm;
         _vm.Attach(viewport);
         Loaded += MainWindow_Loaded;
+
+        // Gizmo 操作器的放開事件：manipulator 會把 MouseUp 標成 handled，需 handledEventsToo 才收得到
+        viewport.AddHandler(MouseLeftButtonUpEvent,
+            new MouseButtonEventHandler((_, _) => _vm.OnGizmoMouseUp()), handledEventsToo: true);
     }
 
     /// <summary>支援命令列帶檔開啟：STPViewer.exe a.stp b.stl …</summary>

src/STPViewer/ViewModels/MainViewModel.cs

@@ -415,6 +415,8 @@ public partial class MainViewModel : ObservableObject
     {
         if (_viewport is null || !root.IsRoot) return;
 
+        if (ReferenceEquals(root, _gizmoTarget)) GizmoEnabled = false; // 目標被移除 → 收掉操作器
+
         // 量測 overlay 可能標在此檔模型上 → 一併清除（簡化：全清）
         if (Measurements.Count > 0) ClearMeasurements();
 
@@ -954,6 +956,154 @@ public partial class MainViewModel : ObservableObject
         return true;
     }
 
+    // ─── Gizmo 三軸操作器（XYZ 箭頭 + 旋轉環；每次放開滑鼠烘進 B-rep）──
+
+    [ObservableProperty]
+    private bool gizmoEnabled;
+
+    private readonly List<HelixToolkit.Wpf.Manipulator> _gizmoParts = new();
+    private ModelVisual3D? _gizmoProxy;        // 操作器綁定的代理 visual（其 Transform = 使用者拖出的變換）
+    private ModelNodeViewModel? _gizmoTarget;
+    private bool _gizmoDragActive;             // 拖動中（邊線已暫停）
+    private bool _gizmoBaking;                 // 烘焙中，忽略 Transform 變更回呼
+
+    partial void OnGizmoEnabledChanged(bool value) => UpdateGizmo();
+
+    partial void OnSelectedNodeChanged(ModelNodeViewModel? value)
+    {
+        if (GizmoEnabled) UpdateGizmo(); // 換選取 → 操作器跟著換目標
+    }
+
+    private void UpdateGizmo()
+    {
+        RemoveGizmo();
+        if (!GizmoEnabled || _viewport is null) return;
+
+        ModelNodeViewModel? root = SelectedNode is not null ? RootContaining(SelectedNode)
+            : Roots.Count == 1 ? Roots[0] : null;
+        if (root is null || root.Bounds.IsEmpty)
+        {
+            StatusText = "操作器：請先在樹面板點選要操作的檔案";
+            GizmoEnabled = false;
+            return;
+        }
+        _gizmoTarget = root;
+
+        Rect3D b = root.Bounds;
+        var center = new Point3D(b.X + b.SizeX / 2, b.Y + b.SizeY / 2, b.Z + b.SizeZ / 2);
+        double diag = new Vector3D(b.SizeX, b.SizeY, b.SizeZ).Length;
+
+        _gizmoProxy = new ModelVisual3D();
+        _viewport.Children.Add(_gizmoProxy);
+        System.ComponentModel.DependencyPropertyDescriptor
+            .FromProperty(Visual3D.TransformProperty, typeof(Visual3D))
+            .AddValueChanged(_gizmoProxy, GizmoTransformChanged);
+
+        void AddPart(HelixToolkit.Wpf.Manipulator man)
+        {
+            man.Position = center;
+            man.Bind(_gizmoProxy);
+            _gizmoParts.Add(man);
+            _viewport!.Children.Add(man);
+        }
+        // 平移箭頭（X 紅 / Y 綠 / Z 藍 — 業界慣例）
+        AddPart(new TranslateManipulator { Direction = new Vector3D(1, 0, 0), Color = Colors.Red,   Length = diag * 0.22, Diameter = diag * 0.016 });
+        AddPart(new TranslateManipulator { Direction = new Vector3D(0, 1, 0), Color = Colors.Green, Length = diag * 0.22, Diameter = diag * 0.016 });
+        AddPart(new TranslateManipulator { Direction = new Vector3D(0, 0, 1), Color = Colors.Blue,  Length = diag * 0.22, Diameter = diag * 0.016 });
+        // 旋轉環
+        AddPart(new RotateManipulator { Axis = new Vector3D(1, 0, 0), Color = Colors.Red,   Diameter = diag * 0.34, InnerDiameter = diag * 0.30, Length = diag * 0.012 });
+        AddPart(new RotateManipulator { Axis = new Vector3D(0, 1, 0), Color = Colors.Green, Diameter = diag * 0.34, InnerDiameter = diag * 0.30, Length = diag * 0.012 });
+        AddPart(new RotateManipulator { Axis = new Vector3D(0, 0, 1), Color = Colors.Blue,  Diameter = diag * 0.34, InnerDiameter = diag * 0.30, Length = diag * 0.012 });
+
+        StatusText = $"操作器：拖箭頭沿軸移動「{root.Name}」、拖環繞軸旋轉；放開即定位";
+    }
+
+    private void RemoveGizmo()
+    {
+        if (_gizmoProxy is not null)
+        {
+            System.ComponentModel.DependencyPropertyDescriptor
+                .FromProperty(Visual3D.TransformProperty, typeof(Visual3D))
+                .RemoveValueChanged(_gizmoProxy, GizmoTransformChanged);
+            _viewport?.Children.Remove(_gizmoProxy);
+        }
+        foreach (HelixToolkit.Wpf.Manipulator man in _gizmoParts)
+        {
+            man.UnBind();
+            _viewport?.Children.Remove(man);
+        }
+        _gizmoParts.Clear();
+        _gizmoProxy = null;
+
+        if (_gizmoTarget is not null) // 清掉殘留的暫時 Transform（用 Identity，不可 null → 否則 FindHits crash）
+            foreach (ModelNodeViewModel l in _gizmoTarget.Leaves())
+                if (l.BodyVisual is not null)
+                    l.BodyVisual.Transform = Transform3D.Identity;
+        _gizmoTarget = null;
+        if (_gizmoDragActive)
+        {
+            _gizmoDragActive = false;
+            _edgesSuspended = false;
+            SetEdgesActive(true);
+        }
+    }
+
+    /// <summary>操作器拖動中：把代理的 Transform 套到目標檔案的所有 BodyVisual（暫時、GPU 端）</summary>
+    private void GizmoTransformChanged(object? sender, EventArgs e)
+    {
+        if (_gizmoBaking || _gizmoTarget is null || _gizmoProxy is null) return;
+        Transform3D t = _gizmoProxy.Transform;
+        if (!_gizmoDragActive && t is not null && !t.Value.IsIdentity)
+        {
+            _gizmoDragActive = true;
+            _edgesSuspended = true;
+            SetEdgesActive(false); // 邊線逐幀重建會卡，拖動中暫停
+        }
+        foreach (ModelNodeViewModel l in _gizmoTarget.Leaves())
+            if (l.BodyVisual is not null)
+                l.BodyVisual.Transform = t;
+    }
+
+    /// <summary>滑鼠放開（MainWindow 轉發，handledEventsToo）：把累積變換烘進 B-rep 並重置操作器</summary>
+    public void OnGizmoMouseUp()
+    {
+        if (_gizmoTarget is null || _gizmoProxy is null) return;
+        Matrix3D m = _gizmoProxy.Transform?.Value ?? Matrix3D.Identity;
+        if (m.IsIdentity) return; // 只是點一下、沒拖操作器 → 不烘焙
+
+        // 延後到 manipulator 自身的 mouse-up 處理（釋放捕捉等）完成後再烘焙，避免在其事件中改動視覺樹造成 reentrancy
+        _viewport?.Dispatcher.BeginInvoke(new Action(() => BakeGizmo(m)),
+            System.Windows.Threading.DispatcherPriority.Background);
+    }
+
+    private void BakeGizmo(Matrix3D m)
+    {
+        if (_gizmoTarget is null) return;
+        ModelNodeViewModel root = _gizmoTarget;
+
+        _gizmoBaking = true; // 防 proxy 歸零觸發 GizmoTransformChanged 重入
+        foreach (ModelNodeViewModel l in root.Leaves())
+            if (l.BodyVisual is not null)
+                l.BodyVisual.Transform = Transform3D.Identity; // 清暫時位移（用 Identity，不可 null）
+        if (_gizmoProxy is not null) _gizmoProxy.Transform = Transform3D.Identity; // 綁定 → 操作器歸零
+        _gizmoBaking = false;
+        _gizmoDragActive = false;
+        _edgesSuspended = false;
+        SetEdgesActive(true);
+
+        TransformRoot(root, RigidAlign.ToModOp(m), m); // 烘進 B-rep（量測精度不受影響）
+
+        // 操作器移到變換後的新中心
+        Rect3D b = root.Bounds;
+        if (!b.IsEmpty)
+        {
+            var center = new Point3D(b.X + b.SizeX / 2, b.Y + b.SizeY / 2, b.Z + b.SizeZ / 2);
+            foreach (HelixToolkit.Wpf.Manipulator man in _gizmoParts)
+                man.Position = center;
+        }
+        StatusText = $"已套用操作器變換「{root.Name}」（可用 🧩干涉 驗證）";
+    }
+
     // ─── 干涉檢查 ────────────────────────────────────────────────
 
     [RelayCommand]