From b595b88e0488622cd736e81cf3ecd9ff1751483f Mon Sep 17 00:00:00 2001
From: bklronin <therrmann23@gmail.com>
Date: Sun, 5 Jul 2026 10:16:49 +0200
Subject: [PATCH] - assembly draft

---
 .idea/workspace.xml              |  18 +-
 gui.ui                           | 185 +++---
 gui_ui.py                        |  87 +--
 src/fluency/main.py              | 944 ++++++++++++++++++++++++++++++-
 src/fluency/models/data_model.py | 227 ++++++++
 5 files changed, 1335 insertions(+), 126 deletions(-)

diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 01b94f1..ea9e0b1 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -4,11 +4,12 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="8f0bafd6-58a0-4b20-aa2b-ddc3ba278873" name="Changes" comment="- sketch enhacements">
+    <list default="true" id="8f0bafd6-58a0-4b20-aa2b-ddc3ba278873" name="Changes" comment="- UI refinement, button position ui file as source no dirty drafting anymore">
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/gui.ui" beforeDir="false" afterPath="$PROJECT_DIR$/gui.ui" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/gui_ui.py" beforeDir="false" afterPath="$PROJECT_DIR$/gui_ui.py" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/fluency/main.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/fluency/main.py" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/fluency/rendering/occ_renderer.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/fluency/rendering/occ_renderer.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/fluency/models/data_model.py" beforeDir="false" afterPath="$PROJECT_DIR$/src/fluency/models/data_model.py" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -313,7 +314,15 @@
       <option name="project" value="LOCAL" />
       <updated>1783159860774</updated>
     </task>
-    <option name="localTasksCounter" value="26" />
+    <task id="LOCAL-00026" summary="- UI refinement, button position ui file as source no dirty drafting anymore">
+      <option name="closed" value="true" />
+      <created>1783174566362</created>
+      <option name="number" value="00026" />
+      <option name="presentableId" value="LOCAL-00026" />
+      <option name="project" value="LOCAL" />
+      <updated>1783174566362</updated>
+    </task>
+    <option name="localTasksCounter" value="27" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
@@ -355,6 +364,7 @@
     <MESSAGE value="- Basic operations" />
     <MESSAGE value="- removed cadquery deoendency" />
     <MESSAGE value="- sketch enhacements" />
-    <option name="LAST_COMMIT_MESSAGE" value="- sketch enhacements" />
+    <MESSAGE value="- UI refinement, button position ui file as source no dirty drafting anymore" />
+    <option name="LAST_COMMIT_MESSAGE" value="- UI refinement, button position ui file as source no dirty drafting anymore" />
   </component>
 </project>
\ No newline at end of file
diff --git a/gui.ui b/gui.ui
index 4adb991..6fb5370 100644
--- a/gui.ui
+++ b/gui.ui
@@ -15,72 +15,6 @@
   </property>
   <widget class="QWidget" name="centralwidget">
    <layout class="QGridLayout" name="gridLayout">
-    <item row="12" column="2">
-     <widget class="QGroupBox" name="compos_in_assembly_box">
-      <property name="minimumSize">
-       <size>
-        <width>0</width>
-        <height>50</height>
-       </size>
-      </property>
-      <property name="title">
-       <string>Components in Assembly</string>
-      </property>
-     </widget>
-    </item>
-    <item row="12" column="3">
-     <widget class="QGroupBox" name="joint_tools">
-      <property name="minimumSize">
-       <size>
-        <width>0</width>
-        <height>50</height>
-       </size>
-      </property>
-      <property name="title">
-       <string>Joint Tools</string>
-      </property>
-      <layout class="QGridLayout" name="gridLayout_10">
-       <item row="0" column="0">
-        <widget class="QPushButton" name="pb_add_connector">
-         <property name="minimumSize">
-          <size>
-           <width>50</width>
-           <height>50</height>
-          </size>
-         </property>
-         <property name="maximumSize">
-          <size>
-           <width>50</width>
-           <height>50</height>
-          </size>
-         </property>
-         <property name="text">
-          <string>+ Cnct</string>
-         </property>
-        </widget>
-       </item>
-       <item row="0" column="1">
-        <widget class="QPushButton" name="pb_remove_connector">
-         <property name="minimumSize">
-          <size>
-           <width>50</width>
-           <height>50</height>
-          </size>
-         </property>
-         <property name="maximumSize">
-          <size>
-           <width>50</width>
-           <height>50</height>
-          </size>
-         </property>
-         <property name="text">
-          <string>- Cnct</string>
-         </property>
-        </widget>
-       </item>
-      </layout>
-     </widget>
-    </item>
     <item row="3" column="0">
      <widget class="QGroupBox" name="groupBox_5">
       <property name="sizePolicy">
@@ -695,19 +629,6 @@
       </layout>
      </widget>
     </item>
-    <item row="12" column="1">
-     <widget class="QGroupBox" name="assembly_box">
-      <property name="minimumSize">
-       <size>
-        <width>0</width>
-        <height>50</height>
-       </size>
-      </property>
-      <property name="title">
-       <string>Assembly</string>
-      </property>
-     </widget>
-    </item>
     <item row="0" column="1" rowspan="11">
      <widget class="QTabWidget" name="InputTab">
       <property name="sizePolicy">
@@ -1031,7 +952,7 @@
       <property name="title">
        <string>Drawing</string>
       </property>
-      <layout class="QGridLayout" name="gridLayout_2" rowstretch="0,0,0,0,0,0">
+      <layout class="QGridLayout" name="gridLayout_2" rowstretch="0,0,0,0,0">
        <property name="leftMargin">
         <number>10</number>
        </property>
@@ -1149,6 +1070,110 @@
       </layout>
      </widget>
     </item>
+    <item row="12" column="1" colspan="2">
+     <widget class="QGroupBox" name="assembly_box">
+      <property name="minimumSize">
+       <size>
+        <width>0</width>
+        <height>50</height>
+       </size>
+      </property>
+      <property name="title">
+       <string>Assembly</string>
+      </property>
+     </widget>
+    </item>
+    <item row="11" column="3" rowspan="2">
+     <widget class="QGroupBox" name="joint_tools">
+      <property name="minimumSize">
+       <size>
+        <width>0</width>
+        <height>50</height>
+       </size>
+      </property>
+      <property name="title">
+       <string>Joint Tools</string>
+      </property>
+      <layout class="QGridLayout" name="gridLayout_10">
+       <item row="0" column="2">
+        <widget class="QPushButton" name="pb_remove_connector">
+         <property name="minimumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="maximumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="text">
+          <string>- Cnct</string>
+         </property>
+        </widget>
+       </item>
+       <item row="0" column="1">
+        <widget class="QPushButton" name="pb_add_connector">
+         <property name="minimumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="maximumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="text">
+          <string>+ Cnct</string>
+         </property>
+        </widget>
+       </item>
+       <item row="1" column="1">
+        <widget class="QPushButton" name="pb_add_connector_2">
+         <property name="minimumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="maximumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="text">
+          <string>+Jnt</string>
+         </property>
+        </widget>
+       </item>
+       <item row="1" column="2">
+        <widget class="QPushButton" name="pb_add_connector_3">
+         <property name="minimumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="maximumSize">
+          <size>
+           <width>50</width>
+           <height>50</height>
+          </size>
+         </property>
+         <property name="text">
+          <string>-Jnt</string>
+         </property>
+        </widget>
+       </item>
+      </layout>
+     </widget>
+    </item>
    </layout>
   </widget>
   <widget class="QMenuBar" name="menubar">
diff --git a/gui_ui.py b/gui_ui.py
index 2161302..8e10ebd 100644
--- a/gui_ui.py
+++ b/gui_ui.py
@@ -37,34 +37,6 @@ class Ui_fluencyCAD(object):
         self.centralwidget.setObjectName(u"centralwidget")
         self.gridLayout = QGridLayout(self.centralwidget)
         self.gridLayout.setObjectName(u"gridLayout")
-        self.compos_in_assembly_box = QGroupBox(self.centralwidget)
-        self.compos_in_assembly_box.setObjectName(u"compos_in_assembly_box")
-        self.compos_in_assembly_box.setMinimumSize(QSize(0, 50))
-
-        self.gridLayout.addWidget(self.compos_in_assembly_box, 12, 2, 1, 1)
-
-        self.joint_tools = QGroupBox(self.centralwidget)
-        self.joint_tools.setObjectName(u"joint_tools")
-        self.joint_tools.setMinimumSize(QSize(0, 50))
-        self.gridLayout_10 = QGridLayout(self.joint_tools)
-        self.gridLayout_10.setObjectName(u"gridLayout_10")
-        self.pb_add_connector = QPushButton(self.joint_tools)
-        self.pb_add_connector.setObjectName(u"pb_add_connector")
-        self.pb_add_connector.setMinimumSize(QSize(50, 50))
-        self.pb_add_connector.setMaximumSize(QSize(50, 50))
-
-        self.gridLayout_10.addWidget(self.pb_add_connector, 0, 0, 1, 1)
-
-        self.pb_remove_connector = QPushButton(self.joint_tools)
-        self.pb_remove_connector.setObjectName(u"pb_remove_connector")
-        self.pb_remove_connector.setMinimumSize(QSize(50, 50))
-        self.pb_remove_connector.setMaximumSize(QSize(50, 50))
-
-        self.gridLayout_10.addWidget(self.pb_remove_connector, 0, 1, 1, 1)
-
-
-        self.gridLayout.addWidget(self.joint_tools, 12, 3, 1, 1)
-
         self.groupBox_5 = QGroupBox(self.centralwidget)
         self.groupBox_5.setObjectName(u"groupBox_5")
         sizePolicy = QSizePolicy(QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Preferred)
@@ -384,12 +356,6 @@ class Ui_fluencyCAD(object):
 
         self.gridLayout.addWidget(self.groupBox_4, 2, 3, 1, 1)
 
-        self.assembly_box = QGroupBox(self.centralwidget)
-        self.assembly_box.setObjectName(u"assembly_box")
-        self.assembly_box.setMinimumSize(QSize(0, 50))
-
-        self.gridLayout.addWidget(self.assembly_box, 12, 1, 1, 1)
-
         self.InputTab = QTabWidget(self.centralwidget)
         self.InputTab.setObjectName(u"InputTab")
         sizePolicy3 = QSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
@@ -625,6 +591,48 @@ class Ui_fluencyCAD(object):
 
         self.gridLayout.addWidget(self.groupBox_2, 2, 0, 1, 1)
 
+        self.assembly_box = QGroupBox(self.centralwidget)
+        self.assembly_box.setObjectName(u"assembly_box")
+        self.assembly_box.setMinimumSize(QSize(0, 50))
+
+        self.gridLayout.addWidget(self.assembly_box, 12, 1, 1, 2)
+
+        self.joint_tools = QGroupBox(self.centralwidget)
+        self.joint_tools.setObjectName(u"joint_tools")
+        self.joint_tools.setMinimumSize(QSize(0, 50))
+        self.gridLayout_10 = QGridLayout(self.joint_tools)
+        self.gridLayout_10.setObjectName(u"gridLayout_10")
+        self.pb_remove_connector = QPushButton(self.joint_tools)
+        self.pb_remove_connector.setObjectName(u"pb_remove_connector")
+        self.pb_remove_connector.setMinimumSize(QSize(50, 50))
+        self.pb_remove_connector.setMaximumSize(QSize(50, 50))
+
+        self.gridLayout_10.addWidget(self.pb_remove_connector, 0, 2, 1, 1)
+
+        self.pb_add_connector = QPushButton(self.joint_tools)
+        self.pb_add_connector.setObjectName(u"pb_add_connector")
+        self.pb_add_connector.setMinimumSize(QSize(50, 50))
+        self.pb_add_connector.setMaximumSize(QSize(50, 50))
+
+        self.gridLayout_10.addWidget(self.pb_add_connector, 0, 1, 1, 1)
+
+        self.pb_add_connector_2 = QPushButton(self.joint_tools)
+        self.pb_add_connector_2.setObjectName(u"pb_add_connector_2")
+        self.pb_add_connector_2.setMinimumSize(QSize(50, 50))
+        self.pb_add_connector_2.setMaximumSize(QSize(50, 50))
+
+        self.gridLayout_10.addWidget(self.pb_add_connector_2, 1, 1, 1, 1)
+
+        self.pb_add_connector_3 = QPushButton(self.joint_tools)
+        self.pb_add_connector_3.setObjectName(u"pb_add_connector_3")
+        self.pb_add_connector_3.setMinimumSize(QSize(50, 50))
+        self.pb_add_connector_3.setMaximumSize(QSize(50, 50))
+
+        self.gridLayout_10.addWidget(self.pb_add_connector_3, 1, 2, 1, 1)
+
+
+        self.gridLayout.addWidget(self.joint_tools, 11, 3, 2, 1)
+
         fluencyCAD.setCentralWidget(self.centralwidget)
         self.menubar = QMenuBar(fluencyCAD)
         self.menubar.setObjectName(u"menubar")
@@ -658,10 +666,6 @@ class Ui_fluencyCAD(object):
         self.actionNew_Project.setText(QCoreApplication.translate("fluencyCAD", u"New", None))
         self.actionLoad_Project.setText(QCoreApplication.translate("fluencyCAD", u"Load", None))
         self.actionRecent.setText(QCoreApplication.translate("fluencyCAD", u"Recent", None))
-        self.compos_in_assembly_box.setTitle(QCoreApplication.translate("fluencyCAD", u"Components in Assembly", None))
-        self.joint_tools.setTitle(QCoreApplication.translate("fluencyCAD", u"Joint Tools", None))
-        self.pb_add_connector.setText(QCoreApplication.translate("fluencyCAD", u"+ Cnct", None))
-        self.pb_remove_connector.setText(QCoreApplication.translate("fluencyCAD", u"- Cnct", None))
         self.groupBox_5.setTitle(QCoreApplication.translate("fluencyCAD", u"Snapping Points", None))
         self.label.setText(QCoreApplication.translate("fluencyCAD", u"Snp Dst", None))
         self.pb_snap_vert.setText(QCoreApplication.translate("fluencyCAD", u"Vert", None))
@@ -739,7 +743,6 @@ class Ui_fluencyCAD(object):
         self.pushButton_2.setText(QCoreApplication.translate("fluencyCAD", u"STL", None))
         self.pb_export_step.setText(QCoreApplication.translate("fluencyCAD", u"STEP", None))
         self.pb_export_iges.setText(QCoreApplication.translate("fluencyCAD", u"IGES", None))
-        self.assembly_box.setTitle(QCoreApplication.translate("fluencyCAD", u"Assembly", None))
         self.InputTab.setTabText(self.InputTab.indexOf(self.sketch_tab), QCoreApplication.translate("fluencyCAD", u"Sketch", None))
         self.groupBox_7.setTitle(QCoreApplication.translate("fluencyCAD", u"Executive", None))
         self.pushButton_5.setText(QCoreApplication.translate("fluencyCAD", u"Load Code", None))
@@ -796,6 +799,12 @@ class Ui_fluencyCAD(object):
         self.pb_offset_tool.setToolTip(QCoreApplication.translate("fluencyCAD", u"Offset selected sketch face (duplicate + offset boundary)", None))
 #endif // QT_CONFIG(tooltip)
         self.pb_offset_tool.setText(QCoreApplication.translate("fluencyCAD", u"Offst", None))
+        self.assembly_box.setTitle(QCoreApplication.translate("fluencyCAD", u"Assembly", None))
+        self.joint_tools.setTitle(QCoreApplication.translate("fluencyCAD", u"Joint Tools", None))
+        self.pb_remove_connector.setText(QCoreApplication.translate("fluencyCAD", u"- Cnct", None))
+        self.pb_add_connector.setText(QCoreApplication.translate("fluencyCAD", u"+ Cnct", None))
+        self.pb_add_connector_2.setText(QCoreApplication.translate("fluencyCAD", u"+Jnt", None))
+        self.pb_add_connector_3.setText(QCoreApplication.translate("fluencyCAD", u"-Jnt", None))
         self.menuFile.setTitle(QCoreApplication.translate("fluencyCAD", u"File", None))
         self.menuSettings.setTitle(QCoreApplication.translate("fluencyCAD", u"Settings", None))
     # retranslateUi
diff --git a/src/fluency/main.py b/src/fluency/main.py
index c9d592f..1b76261 100644
--- a/src/fluency/main.py
+++ b/src/fluency/main.py
@@ -11,6 +11,7 @@ import sys
 import math
 import uuid
 import logging
+from datetime import datetime
 from typing import Optional, List, Dict, Any, Tuple
 from dataclasses import dataclass, field
 
@@ -3546,6 +3547,20 @@ class Viewer3DWidget(QWidget):
     # Emitted when face-pick mode is cancelled (Esc) so the host can uncheck.
     pickFaceCancelled = Signal()
 
+    # Emitted when the user picks a face for a connector point (assembly).
+    # Payload: (origin, normal, x_dir, face_shape, owner_obj_id).
+    connectorPicked = Signal(tuple, tuple, tuple, object, str)
+    # Emitted when connector pick mode is cancelled.
+    connectorPickCancelled = Signal()
+
+    # Emitted when a body is clicked in assembly move mode.
+    # Payload: owner_obj_id.
+    assemblyComponentActivated = Signal(str)
+    # Emitted during a drag move: owner_obj_id, world dx, dy, dz.
+    assemblyComponentDragged = Signal(str, float, float, float)
+    # Emitted when a drag move finishes.
+    assemblyMoveFinished = Signal(str)
+
     def __init__(self, parent=None):
         super().__init__(parent)
         # For OCC's direct OpenGL rendering we need Qt to not paint over it.
@@ -3564,6 +3579,18 @@ class Viewer3DWidget(QWidget):
         # When True, a left-click picks a planar face (for sketch-on-surface)
         # instead of orbiting the camera.  Set via set_pick_face_mode().
         self._pick_face_mode: bool = False
+        # When True, a left-click picks a face for a connector point
+        # (assembly component connection).
+        self._connector_pick_mode: bool = False
+        # When True, left-click on a body activates assembly drag-to-move.
+        self._assembly_move_mode: bool = False
+        # State for ongoing assembly drag.
+        self._move_drag_active: bool = False
+        self._move_owner_obj_id: str = ""
+        self._move_click_3d: Optional[Tuple[float, float, float]] = None
+        self._move_click_screen: Optional[Any] = None
+        self._move_plane_normal: Optional[Tuple[float, float, float]] = None
+        self._move_initial_position: Optional[Tuple[float, float, float]] = None
         # Most recently recorded owning obj_id for the face returned by
         # ``pick_planar_face``.  Stashed on each pick pass so the host can
         # pair the picked face with the body it belongs to (used to auto-
@@ -3790,18 +3817,30 @@ class Viewer3DWidget(QWidget):
         if self._pick_face_mode and event.button() == Qt.LeftButton:
             self._handle_face_pick(event)
             return
+        # Connector pick mode: a left-click selects a face for a connection point.
+        if self._connector_pick_mode and event.button() == Qt.LeftButton:
+            self._handle_connector_pick(event)
+            return
+        # Assembly move mode: start dragging the clicked body.
+        if self._assembly_move_mode and event.button() == Qt.LeftButton:
+            self._handle_assembly_move_press(event)
+            return
         self._renderer.handle_mouse_press(event)
         super().mousePressEvent(event)
 
     def mouseMoveEvent(self, event):
         self._ensure_initialized()
-        # In face-pick mode, keep dynamic highlighting but don't orbit.
-        if self._pick_face_mode:
+        # In face-pick/connector mode, keep dynamic highlighting.
+        if self._pick_face_mode or self._connector_pick_mode:
             if hasattr(self._renderer, "handle_mouse_move"):
-                # Still forward for hover-detect (no button held → detect only).
                 self._renderer.handle_mouse_move(event)
             super().mouseMoveEvent(event)
             return
+        # Active drag in assembly move mode.
+        if self._move_drag_active:
+            self._handle_assembly_move_move(event)
+            super().mouseMoveEvent(event)
+            return
         self._renderer.handle_mouse_move(event)
         super().mouseMoveEvent(event)
 
@@ -3815,6 +3854,10 @@ class Viewer3DWidget(QWidget):
 
     def mouseReleaseEvent(self, event):
         self._ensure_initialized()
+        # Finish assembly drag.
+        if self._move_drag_active:
+            self._handle_assembly_move_release(event)
+            return
         self._renderer.handle_mouse_release(event)
         super().mouseReleaseEvent(event)
 
@@ -3866,6 +3909,157 @@ class Viewer3DWidget(QWidget):
             fn()
             self._renderer.render()
 
+    # ─── Connector pick mode (assembly) ────────────────────────────────────
+
+    def set_connector_pick_mode(self, enabled: bool) -> None:
+        """Toggle connector pick mode for placing connection points.
+
+        When enabled, clicking a face on a body in the assembly view
+        captures its origin and normal as a connection point for the
+        SolveSpace solver.
+        """
+        self._connector_pick_mode = bool(enabled)
+        if enabled:
+            self.setCursor(Qt.CrossCursor)
+        elif not self._pick_face_mode:
+            self.unsetCursor()
+
+    def is_connector_pick_mode(self) -> bool:
+        return self._connector_pick_mode
+
+    def _handle_connector_pick(self, event) -> None:
+        """Detect a planar face under the click and emit connectorPicked."""
+        self._ensure_initialized()
+        picker = getattr(self._renderer, "pick_planar_face", None)
+        if picker is None:
+            logger.warning("Renderer has no pick_planar_face support")
+            return
+        pos = event.position().toPoint() if hasattr(event, "position") else event.pos()
+        info = picker(pos.x(), pos.y())
+        if info is None:
+            logger.info("Connector pick: no planar face under cursor")
+            return
+        owner_obj_id = info.get("owner_obj_id", "")
+        self.connectorPicked.emit(
+            tuple(info["origin"]),
+            tuple(info["normal"]),
+            tuple(info["x_dir"]),
+            info["face"],
+            owner_obj_id,
+        )
+
+    # ─── Assembly move mode (3D drag) ─────────────────────────────────────
+
+    def set_assembly_move_mode(self, enabled: bool) -> None:
+        """Toggle assembly move mode.
+
+        When enabled, clicking on a body and dragging moves its
+        assembly component in the view plane.  Shift+drag moves in Z.
+        """
+        self._assembly_move_mode = bool(enabled)
+        if enabled:
+            self.setCursor(Qt.SizeAllCursor)
+        elif not self._pick_face_mode and not self._connector_pick_mode:
+            self.unsetCursor()
+        if not enabled:
+            self._move_drag_active = False
+            self._move_owner_obj_id = ""
+            self._move_click_3d = None
+            self._move_click_screen = None
+            self._move_plane_normal = None
+            self._move_initial_position = None
+
+    def _handle_assembly_move_press(self, event) -> None:
+        """Start a drag-to-move for the body under the cursor."""
+        self._ensure_initialized()
+        picker = getattr(self._renderer, "pick_planar_face", None)
+        if picker is None:
+            return
+        pos = event.position().toPoint() if hasattr(event, "position") else event.pos()
+        info = picker(pos.x(), pos.y())
+        if info is None:
+            return
+
+        owner_obj_id = info.get("owner_obj_id", "")
+        if not owner_obj_id or not owner_obj_id.startswith("asm_"):
+            return
+
+        # Store drag state.
+        self._move_drag_active = True
+        self._move_owner_obj_id = owner_obj_id
+        self._move_click_3d = tuple(info["origin"])
+        self._move_click_screen = pos
+        self._move_plane_normal = tuple(info["normal"])
+
+        # Emit activation signal so MainWindow stores initial position.
+        self.assemblyComponentActivated.emit(owner_obj_id)
+
+    def _handle_assembly_move_move(self, event) -> None:
+        """Continue the drag: project mouse delta to world-space and emit."""
+        if not self._move_drag_active or self._move_click_screen is None:
+            return
+
+        pos = event.position().toPoint() if hasattr(event, "position") else event.pos()
+
+        # Screen delta (Qt Y is inverted vs OCC).
+        dx = pos.x() - self._move_click_screen.x()
+        dy = -(pos.y() - self._move_click_screen.y())  # invert Y
+
+        # Convert screen delta to world units using the view scale.
+        # view.Scale() returns a scale factor — the smaller the value the
+        # more world distance per pixel.  We use an empirical conversion:
+        # at scale=1.0, ~1 pixel ≈ 0.3 world units at typical depth.
+        scale = self._renderer._view.Scale() if hasattr(self._renderer, "_view") else 1.0
+        world_per_pixel = 2.0 / max(scale, 0.001)
+
+        # Get camera vectors for proper view-plane projection.
+        import numpy as np
+        from OCP.V3d import V3d_TypeOfOrientation
+        try:
+            # Get camera direction and up from the OCC view.
+            camera = self._renderer._view.Camera()
+            dir_ = camera.Direction()
+            up_ = camera.Up()
+            cam_dir = np.array([dir_.X(), dir_.Y(), dir_.Z()])
+            cam_up = np.array([up_.X(), up_.Y(), up_.Z()])
+            cam_right = np.cross(cam_dir, cam_up)
+            cam_right = cam_right / np.linalg.norm(cam_right)
+            cam_up = cam_up / np.linalg.norm(cam_up)
+        except Exception:
+            # Fallback: assume XY plane.
+            cam_right = np.array([1.0, 0.0, 0.0])
+            cam_up = np.array([0.0, 0.0, 1.0])
+
+        # Compute world-space delta.
+        modifiers = event.modifiers()
+        if modifiers & Qt.ShiftModifier:
+            # Shift+drag: move along camera direction (Z-depth).
+            dz_world = dx * world_per_pixel
+            dx_world = 0.0
+            dy_world = 0.0
+        else:
+            # Normal drag: move in view plane.
+            dx_world = float(cam_right[0] * dx * world_per_pixel +
+                             cam_up[0] * dy * world_per_pixel)
+            dy_world = float(cam_right[1] * dx * world_per_pixel +
+                             cam_up[1] * dy * world_per_pixel)
+            dz_world = float(cam_right[2] * dx * world_per_pixel +
+                             cam_up[2] * dy * world_per_pixel)
+
+        self.assemblyComponentDragged.emit(
+            self._move_owner_obj_id, dx_world, dy_world, dz_world
+        )
+
+    def _handle_assembly_move_release(self, event) -> None:
+        """Finish the drag, emit final position."""
+        self.assemblyMoveFinished.emit(self._move_owner_obj_id)
+        self._move_drag_active = False
+        self._move_owner_obj_id = ""
+        self._move_click_3d = None
+        self._move_click_screen = None
+        self._move_plane_normal = None
+        self._move_initial_position = None
+
     def _handle_face_pick(self, event) -> None:
         """Detect a planar face under the click and emit facePicked."""
         self._ensure_initialized()
@@ -3924,6 +4118,15 @@ class Viewer3DWidget(QWidget):
             self.set_pick_face_mode(False)
             self.pickFaceCancelled.emit()
             return
+        # Esc cancels connector pick mode.
+        if self._connector_pick_mode and event.key() == Qt.Key_Escape:
+            self.set_connector_pick_mode(False)
+            self.connectorPickCancelled.emit()
+            return
+        # Esc cancels assembly move mode.
+        if self._assembly_move_mode and event.key() == Qt.Key_Escape:
+            self.set_assembly_move_mode(False)
+            return
         # Navigation shortcuts (lowercase = view presets, F = fit,
         # P/O = perspective/orthographic, R = reset).
         self._ensure_initialized()
@@ -3982,9 +4185,29 @@ class MainWindow(QMainWindow):
         self._component_buttons: List[QPushButton] = []
         self._component_group: Optional[QButtonGroup] = None
 
+        # Assembly state
+        self._assembly_component_buttons: List[QPushButton] = []
+        self._assembly_component_group: Optional[QButtonGroup] = None
+        self._assembly_view_active: bool = False
+        self._selected_assembly_component_id: Optional[str] = None
+
+        # Connector two-click state
+        self._connector_first_pick: Optional[Dict[str, Any]] = None
+        self._connector_second_ac_id: Optional[str] = None
+        self._connector_align_pos: Any = None
+
+        # Drag-move state for assembly components
+        self._asm_move_ac_id: Optional[str] = None
+        self._asm_move_start_pos: Any = None
+        # Cache of render object IDs per assembly component, so drag updates
+        # can replace only the moved component's shapes without clearing the
+        # entire scene (avoids camera flicker).
+        self._asm_render_objects: Dict[str, List[str]] = {}
+
         self._setup_ui()
         self._setup_connections()
         self._create_initial_component()
+        self._create_initial_assembly()
         logger.info("MainWindow initialization complete")
 
     def _setup_ui(self):
@@ -4089,6 +4312,30 @@ class MainWindow(QMainWindow):
         compo_layout.addWidget(self._component_box)
         compo_layout.addStretch()
 
+        # ── Assembly box (dynamic buttons like component box) ──
+        self._assembly_box = QWidget()
+        self._assembly_box_layout = QHBoxLayout(self._assembly_box)
+        self._assembly_box_layout.setAlignment(Qt.AlignLeft)
+        self._assembly_component_group = QButtonGroup(self)
+        self._assembly_component_group.setExclusive(True)
+        # Add to the Assembly group box from the UI.
+        asm_layout = self._ui.assembly_box.layout()
+        if asm_layout is None:
+            asm_layout = QHBoxLayout(self._ui.assembly_box)
+            asm_layout.setContentsMargins(0, 0, 0, 0)
+        asm_layout.addWidget(self._assembly_box)
+        asm_layout.addStretch()
+
+        # ── Assembly Move button (programmatic, in assembly_tools) ──
+        self._btn_asm_move = QPushButton("Pos")
+        self._btn_asm_move.setCheckable(True)
+        self._btn_asm_move.setMinimumSize(QSize(50, 50))
+        self._btn_asm_move.setMaximumSize(QSize(50, 50))
+        self._btn_asm_move.setToolTip("Toggle: click a body in 3D and drag to move the assembly component")
+        asm_tools_layout = self._ui.assembly_tools.layout()
+        if asm_tools_layout is not None:
+            asm_tools_layout.addWidget(self._btn_asm_move, 0, 2, 1, 1)
+
         # Panel-focus mode (equal | sketch | viewer).
         self._panel_focus: str = "equal"
 
@@ -4159,7 +4406,10 @@ class MainWindow(QMainWindow):
         self._btn_new_compo = ui.pb_new_compo
         self._btn_del_compo = ui.pb_del_compo
         # ── Assembly / Connector ──
+        self._btn_compo_to_assembly = ui.pb_compo_to_assembly
+        self._btn_remove_compo_from_assembly = ui.pb_remove_compo_from_assembly
         self._btn_add_connector = ui.pb_add_connector
+        self._btn_add_connector.setCheckable(True)
         self._btn_del_connector = ui.pb_remove_connector
         # ── Code tab ──
         self._btn_apply_code = ui.pb_apply_code
@@ -4264,6 +4514,25 @@ class MainWindow(QMainWindow):
         self._btn_new_compo.clicked.connect(self._new_component)
         self._btn_del_compo.clicked.connect(self._delete_component)
 
+        self._btn_compo_to_assembly.clicked.connect(self._add_component_to_assembly)
+        self._btn_remove_compo_from_assembly.clicked.connect(self._remove_component_from_assembly)
+        self._btn_asm_move.toggled.connect(self._on_assembly_move_toggled)
+        self._btn_add_connector.clicked.connect(self._on_start_connector_placement)
+        self._btn_del_connector.clicked.connect(self._on_delete_connector)
+        self._viewer_3d.connectorPicked.connect(self._on_connector_picked)
+        self._viewer_3d.connectorPickCancelled.connect(
+            lambda: self._btn_add_connector.setChecked(False)
+        )
+        self._viewer_3d.assemblyComponentActivated.connect(
+            self._on_assembly_move_activated
+        )
+        self._viewer_3d.assemblyComponentDragged.connect(
+            self._on_assembly_move_dragged
+        )
+        self._viewer_3d.assemblyMoveFinished.connect(
+            self._on_assembly_move_finished
+        )
+
         self._btn_update_body.clicked.connect(self._redraw_bodies)
         self._btn_del_body.clicked.connect(self._delete_body)
 
@@ -4305,6 +4574,11 @@ class MainWindow(QMainWindow):
     def _create_initial_component(self):
         self._new_component()
 
+    def _create_initial_assembly(self):
+        """Create the initial assembly in the project."""
+        self._project.add_assembly()
+        logger.info("Created initial assembly")
+
     def _set_sketch_mode(self, mode: str):
         self._sketch_widget.set_mode(mode)
 
@@ -4420,6 +4694,7 @@ class MainWindow(QMainWindow):
         comp_ids = list(self._project.components.keys())
         if idx < len(comp_ids):
             self._current_component = self._project.components[comp_ids[idx]]
+            self._assembly_view_active = False
             self._refresh_lists()
             self._redraw_bodies()
 
@@ -4472,6 +4747,669 @@ class MainWindow(QMainWindow):
 
         self._viewer_3d.fit_camera()
 
+    # ────────────────────────────────────────────────────────────────────
+    # Assembly methods
+    # ────────────────────────────────────────────────────────────────────
+
+    def _get_assembly(self) -> Optional[Any]:
+        """Get the active assembly from the project."""
+        assembly = self._project.get_active_assembly()
+        if assembly is None:
+            assembly = self._project.add_assembly()
+        return assembly
+
+    def _add_component_to_assembly(self):
+        """Add the currently selected component to the assembly.
+
+        Creates a new button in the assembly box and stores the
+        component instance in the assembly model.
+        """
+        if self._current_component is None:
+            logger.warning("No active component to add to assembly")
+            return
+
+        assembly = self._get_assembly()
+
+        # Create an instance of the current component in the assembly.
+        ac = assembly.add_component_instance(
+            component_id=self._current_component.id,
+            name=f"{self._current_component.name}",
+        )
+        logger.info(
+            f"Added component '{self._current_component.name}' "
+            f"to assembly '{assembly.name}' (instance={ac.id})"
+        )
+
+        # Create a button for this assembly component.
+        instance_num = len(assembly.components)
+        label = f"{instance_num}"
+        btn = QPushButton(label)
+        btn.setCheckable(True)
+        btn.setFixedSize(QSize(40, 40))
+        btn.setToolTip(f"{ac.name} (instance {list(assembly.components.keys()).index(ac.id) + 1})")
+        # Store the assembly component id in the button.
+        btn._assembly_component_id = ac.id
+        btn.clicked.connect(self._on_assembly_component_clicked)
+
+        # Uncheck all other assembly buttons, check this one.
+        for b in self._assembly_component_buttons:
+            b.setChecked(False)
+        btn.setChecked(True)
+
+        self._assembly_component_buttons.append(btn)
+        self._assembly_component_group.addButton(btn)
+        self._assembly_box_layout.addWidget(btn)
+
+        # Store the selected id and activate assembly view.
+        self._selected_assembly_component_id = ac.id
+        self._assembly_view_active = True
+
+        # Show the assembly in the viewer, framing all components.
+        self._show_assembly_in_viewer(fit=True)
+
+    def _remove_component_from_assembly(self):
+        """Remove the currently selected assembly component."""
+        assembly = self._get_assembly()
+        if not assembly or not assembly.components:
+            logger.warning("Assembly is empty, nothing to remove")
+            return
+
+        # Find the active assembly component id from the checked button.
+        active_id = self._get_active_assembly_component_id()
+        if active_id is None:
+            logger.warning("No assembly component selected to remove")
+            return
+
+        # Find the button index for this assembly component.
+        idx = -1
+        for i, btn in enumerate(self._assembly_component_buttons):
+            if getattr(btn, '_assembly_component_id', None) == active_id:
+                idx = i
+                break
+
+        if idx >= 0:
+            assembly.remove_component_instance(active_id)
+
+            btn = self._assembly_component_buttons.pop(idx)
+            self._assembly_component_group.removeButton(btn)
+            btn.deleteLater()
+
+            # Select the first remaining button if any.
+            if self._assembly_component_buttons:
+                self._assembly_component_buttons[0].setChecked(True)
+                first_id = getattr(self._assembly_component_buttons[0], '_assembly_component_id', None)
+                self._selected_assembly_component_id = first_id
+                self._assembly_view_active = True
+            else:
+                self._selected_assembly_component_id = None
+                self._assembly_view_active = False
+                # Fall back to normal component view.
+                self._redraw_bodies()
+                return
+
+            logger.info(f"Removed assembly component instance {active_id}")
+            self._show_assembly_in_viewer(fit=True)
+
+    def _get_active_assembly_component_id(self) -> Optional[str]:
+        """Get the assembly component id of the currently checked button."""
+        for btn in self._assembly_component_buttons:
+            if btn.isChecked():
+                return getattr(btn, '_assembly_component_id', None)
+        return None
+
+    def _on_assembly_component_clicked(self):
+        """Handle an assembly component button click.
+
+        Shows all components from the assembly in the 3D viewer,
+        with the clicked component highlighted/selected.
+        """
+        # Find which assembly component id was clicked.
+        active_id = self._get_active_assembly_component_id()
+        if active_id is None:
+            return
+
+        self._selected_assembly_component_id = active_id
+        self._assembly_view_active = True
+
+        self._show_assembly_in_viewer(fit=True)
+
+    def _apply_transform(self, shape: Any, position, rotation) -> Any:
+        """Apply a position translation and rotation matrix to a shape.
+
+        Returns a new transformed TopoDS_Shape.  If position is zero and
+        rotation is identity the original shape is returned unchanged.
+        """
+        import numpy as np
+        from OCP.gp import gp_Trsf
+        from OCP.BRepBuilderAPI import BRepBuilderAPI_Transform
+
+        pos = np.asarray(position, dtype=float)
+        rot = np.asarray(rotation, dtype=float)
+
+        # Skip if identity.
+        if np.allclose(pos, 0.0) and np.allclose(rot, np.eye(3)):
+            return shape
+
+        # Use SetValues for a combined rotation + translation transform.
+        # gp_Trsf.SetValues takes 12 values forming a 3x4 matrix:
+        #   [R11 R12 R13 Tx]
+        #   [R21 R22 R23 Ty]
+        #   [R31 R32 R33 Tz]
+        trsf = gp_Trsf()
+        trsf.SetValues(
+            float(rot[0, 0]), float(rot[0, 1]), float(rot[0, 2]), float(pos[0]),
+            float(rot[1, 0]), float(rot[1, 1]), float(rot[1, 2]), float(pos[1]),
+            float(rot[2, 0]), float(rot[2, 1]), float(rot[2, 2]), float(pos[2]),
+        )
+
+        transformer = BRepBuilderAPI_Transform(shape, trsf, False)
+        transformer.Build()
+        return transformer.Shape()
+
+    def _make_connector_marker(self, position: Tuple[float, float, float],
+                                 color: Tuple[float, float, float] = (1.0, 0.3, 0.0)) -> Optional[Any]:
+        """Create a small sphere marker for a connector at *position*.
+
+        Returns the TopoDS_Shape of a tiny sphere, or None on failure.
+        """
+        try:
+            from OCP.gp import gp_Pnt
+            from OCP.BRepPrimAPI import BRepPrimAPI_MakeSphere
+            sphere = BRepPrimAPI_MakeSphere(gp_Pnt(*position), 2.0).Shape()
+            return sphere
+        except Exception as exc:
+            logger.debug(f"Failed to create connector marker: {exc}")
+            return None
+
+    def _show_assembly_in_viewer(self, fit: bool = False):
+        """Show all components from the assembly in the 3D viewer.
+
+        All bodies from all assembly component instances are displayed
+        together with their position/rotation transforms applied.
+        The component whose button is checked gets a highlight color;
+        the rest are shown in a neutral/dimmed color.
+        Connector markers (small orange spheres) are also shown.
+
+        Pass *fit=True* to also frame all visible components with the
+        camera (use when switching to assembly view via button clicks;
+        omit during drag to avoid camera flicker).
+        """
+        assembly = self._get_assembly()
+        if not assembly or not assembly.components:
+            self._viewer_3d.clear_scene()
+            return
+
+        self._viewer_3d.clear_scene()
+        # Reset the render-object cache; it will be rebuilt below.
+        self._asm_render_objects.clear()
+
+        highlight_color = (0.2, 0.6, 1.0)  # Bright blue for selected
+        dim_color = (0.5, 0.5, 0.5)        # Grey for non-selected
+
+        shown_any = False
+        for ac_id, ac in assembly.components.items():
+            comp = self._project.get_component_by_id(ac.component_id)
+            if comp is None:
+                logger.debug(f"Assembly component {ac_id} references missing component {ac.component_id}")
+                continue
+
+            is_selected = (ac_id == self._selected_assembly_component_id)
+            color = highlight_color if is_selected else dim_color
+
+            render_ids: List[str] = []
+            for body_id, body in comp.bodies.items():
+                if body.geometry:
+                    try:
+                        shape = self._kernel._get_shape(body.geometry)
+                        # Apply component instance transform.
+                        transformed = self._apply_transform(
+                            shape, ac.position, ac.rotation
+                        )
+                        obj_id = f"asm_{ac_id}_{body_id}"
+                        render_obj = self._viewer_3d.show_shape(
+                            transformed,
+                            color=color,
+                            name=obj_id,
+                        )
+                        render_ids.append(obj_id)
+                        shown_any = True
+                    except Exception as exc:
+                        logger.debug(f"Failed to show body {body_id} in assembly: {exc}")
+
+            self._asm_render_objects[ac_id] = render_ids
+
+            # Show connector markers for this instance.
+            for conn_id, conn in ac.connectors.items():
+                try:
+                    sphere_shape = self._make_connector_marker(conn.position)
+                    if sphere_shape is not None:
+                        self._viewer_3d.show_shape(
+                            sphere_shape,
+                            color=(1.0, 0.3, 0.0),  # Orange
+                            name=f"conn_{ac_id}_{conn_id}",
+                        )
+                except Exception as exc:
+                    logger.debug(f"Failed to show connector {conn_id}: {exc}")
+
+        if shown_any and fit:
+            self._viewer_3d.fit_camera()
+
+    def _update_assembly_component_in_viewer(self, ac_id: str):
+        """Replace only the shapes of a single assembly component in-place.
+
+        Removes the existing render objects for *ac_id* from the viewer
+        and recreates them at the component's current position/rotation.
+        Other components and connector markers are left untouched — no
+        scene clear, so the camera stays perfectly still.
+        """
+        assembly = self._get_assembly()
+        ac = assembly.components.get(ac_id) if assembly else None
+        if ac is None:
+            return
+
+        comp = self._project.get_component_by_id(ac.component_id)
+        if comp is None:
+            return
+
+        # Remove old render objects for this component.
+        old_ids = self._asm_render_objects.pop(ac_id, [])
+        for oid in old_ids:
+            try:
+                self._viewer_3d.remove_mesh(oid)
+            except Exception:
+                pass
+
+        is_selected = (ac_id == self._selected_assembly_component_id)
+        color = (0.2, 0.6, 1.0) if is_selected else (0.5, 0.5, 0.5)
+
+        new_ids: List[str] = []
+        for body_id, body in comp.bodies.items():
+            if body.geometry:
+                try:
+                    shape = self._kernel._get_shape(body.geometry)
+                    transformed = self._apply_transform(
+                        shape, ac.position, ac.rotation
+                    )
+                    obj_id = f"asm_{ac_id}_{body_id}"
+                    self._viewer_3d.show_shape(
+                        transformed,
+                        color=color,
+                        name=obj_id,
+                    )
+                    new_ids.append(obj_id)
+                except Exception as exc:
+                    logger.debug(f"Failed to update body {body_id}: {exc}")
+
+        self._asm_render_objects[ac_id] = new_ids
+
+    # ────────────────────────────────────────────────────────────────────
+    # Assembly 3D drag-move
+    # ────────────────────────────────────────────────────────────────────
+
+    def _on_assembly_move_toggled(self, checked: bool):
+        """Toggle 3D drag-to-move mode in the viewer.
+
+        When active, clicking a body in the assembly view and dragging
+        moves its assembly component in real-time.  Shift+drag moves in Z.
+        """
+        if checked and not self._assembly_view_active:
+            self._btn_asm_move.setChecked(False)
+            QMessageBox.warning(self, "Assembly View",
+                                "Switch to assembly view first by clicking an assembly component button.")
+            return
+        self._viewer_3d.set_assembly_move_mode(checked)
+        if checked:
+            self._viewer_3d.setFocus()
+            self._viewer_3d.activateWindow()
+            self.setStatusTip("Drag a body to move it; Shift+drag for Z depth")
+        else:
+            self.setStatusTip("")
+
+    def _on_assembly_move_activated(self, owner_obj_id: str):
+        """Called when the user clicks a body in move mode.
+
+        Parse the assembly component id and store its starting position.
+        """
+        import numpy as np
+
+        ac_id = self._parse_ac_id(owner_obj_id)
+        if ac_id is None:
+            return
+
+        assembly = self._get_assembly()
+        ac = assembly.components.get(ac_id)
+        if ac is None:
+            return
+
+        self._asm_move_ac_id = ac_id
+        self._asm_move_start_pos = np.array(ac.position, dtype=float)
+
+    def _on_assembly_move_dragged(self, owner_obj_id: str, dx: float, dy: float, dz: float):
+        """Called during a drag move.  Update only the dragged component in-place.
+
+        Uses the targeted ``_update_assembly_component_in_viewer`` instead of
+        a full ``clear_scene`` + rebuild, so other shapes keep their render
+        objects and the camera stays perfectly still.
+        """
+        if self._asm_move_ac_id is None or self._asm_move_start_pos is None:
+            return
+
+        ac_id = self._asm_move_ac_id
+        assembly = self._get_assembly()
+        ac = assembly.components.get(ac_id)
+        if ac is None:
+            return
+
+        import numpy as np
+        # Apply delta relative to the start position.
+        ac.position = self._asm_move_start_pos + np.array([dx, dy, dz])
+        # Only update the dragged component's shapes — no scene clear.
+        self._update_assembly_component_in_viewer(ac_id)
+
+    def _on_assembly_move_finished(self, owner_obj_id: str):
+        """Finalize the drag move."""
+        if self._asm_move_ac_id is not None:
+            logger.info(f"Moved assembly component {self._asm_move_ac_id} to final position")
+        self._asm_move_ac_id = None
+        self._asm_move_start_pos = None
+
+    # ────────────────────────────────────────────────────────────────────
+    # Connector methods — two-click selection + preview dialog
+    # ────────────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _parse_ac_id(owner_obj_id: str) -> Optional[str]:
+        """Extract the assembly component id from a renderer owner_obj_id.
+
+        Format: asm_{ac_id}_{body_id}
+        """
+        if not owner_obj_id or not owner_obj_id.startswith("asm_"):
+            return None
+        parts = owner_obj_id.split("_")
+        if len(parts) >= 3:
+            return parts[1]
+        return owner_obj_id[4:]
+
+    def _on_start_connector_placement(self, checked: bool):
+        """Toggle connector pick mode.
+
+        First click selects the first component's connection face.
+        Second click selects the second component and triggers alignment.
+        """
+        if not self._assembly_view_active:
+            self._btn_add_connector.setChecked(False)
+            QMessageBox.warning(self, "Assembly View",
+                                "Switch to assembly view first by clicking an assembly component button.")
+            return
+
+        # Reset any in-progress two-click state.
+        self._connector_first_pick = None
+        self._connector_second_ac_id = None
+
+        self._viewer_3d.set_connector_pick_mode(checked)
+        if checked:
+            self._viewer_3d.setFocus()
+            self._viewer_3d.activateWindow()
+            self.setStatusTip("Click on the first component's connection face")
+        else:
+            self.setStatusTip("")
+
+    def _on_connector_picked(self, origin, normal, x_dir, face_shape, owner_obj_id):
+        """Handle a connector face pick — first or second click."""
+        import numpy as np
+
+        ac_id = self._parse_ac_id(owner_obj_id)
+        if ac_id is None:
+            QMessageBox.warning(self, "Pick Error",
+                                "Could not identify which assembly component was clicked.")
+            return
+
+        assembly = self._get_assembly()
+        ac = assembly.components.get(ac_id)
+        if ac is None:
+            QMessageBox.warning(self, "Pick Error",
+                                "The clicked component was not found in the assembly.")
+            return
+
+        # ── First pick ──
+        if self._connector_first_pick is None:
+            self._connector_first_pick = {
+                "ac_id": ac_id,
+                "origin": tuple(origin),
+                "normal": tuple(normal),
+                "x_dir": tuple(x_dir),
+                "owner_obj_id": owner_obj_id,
+            }
+            # Highlight the first face.
+            self._viewer_3d.highlight_face(face_shape)
+            self.setStatusTip("Now click on the second component's connection face")
+            logger.info(f"Connector first pick: {ac.name} at {origin}")
+            return
+
+        # ── Second pick ──
+        first = self._connector_first_pick
+
+        # Don't allow picking the same component twice.
+        if ac_id == first["ac_id"]:
+            QMessageBox.warning(self, "Same Component",
+                                "Pick a different component for the second connection point.")
+            return
+
+        self._connector_second_ac_id = ac_id
+        self._viewer_3d.clear_face_highlight()
+        self._viewer_3d.set_connector_pick_mode(False)
+        self._btn_add_connector.setChecked(False)
+        self.setStatusTip("")
+
+        logger.info(f"Connector second pick: {ac.name} at {origin}")
+
+        # Compute rough alignment transform (simulating SolveSpace).
+        # Move the second component so its connector face aligns with the
+        # first: translate so origin2 → origin1.
+        o1 = np.array(first["origin"])
+        o2 = np.array(origin)
+        align_delta = o1 - o2
+
+        # Store the alignment position on the second component temporarily.
+        ac2 = assembly.components.get(ac_id)
+        if ac2 is not None:
+            self._connector_align_pos = np.array(ac2.position, dtype=float) + align_delta
+        else:
+            self._connector_align_pos = align_delta
+
+        # Show the connector dialog with live preview callback.
+        rotation, offset = self._show_connector_dialog_with_preview(
+            first_ac=assembly.components.get(first["ac_id"]),
+            second_ac=ac2,
+            first_origin=first["origin"],
+            second_origin=o2,
+            first_normal=first["normal"],
+            second_normal=normal,
+            first_x_dir=first["x_dir"],
+            second_x_dir=x_dir,
+            align_delta=align_delta,
+        )
+
+        if rotation is None:
+            # User cancelled — restore original position.
+            if ac2 is not None:
+                self._show_assembly_in_viewer()
+            self._connector_first_pick = None
+            self._connector_second_ac_id = None
+            return
+
+        # Create connectors on both components.
+        first_ac = assembly.components.get(first["ac_id"])
+        if first_ac:
+            conn1 = first_ac.add_connector(
+                position=first["origin"],
+                normal=first["normal"],
+                x_dir=first["x_dir"],
+                source_obj_id=first["owner_obj_id"],
+                name="Connector A",
+            )
+            conn1.axis_rotation = rotation
+            conn1.offset = offset
+
+        if ac2:
+            conn2 = ac2.add_connector(
+                position=tuple(o2),
+                normal=tuple(normal),
+                x_dir=tuple(x_dir),
+                source_obj_id=owner_obj_id,
+                name="Connector B",
+            )
+            conn2.axis_rotation = rotation
+            conn2.offset = offset
+
+            # Apply the aligned position (with dialog adjustments).
+            n2 = np.array(normal) / max(np.linalg.norm(normal), 1e-12)
+            ac2.position = self._connector_align_pos + n2 * offset
+            logger.info(f"Aligned '{ac2.name}' to connector position, offset={offset}mm")
+
+        logger.info(f"Connected component pair: {first['ac_id']} ↔ {ac_id}, rotation={rotation}°")
+        self._connector_first_pick = None
+        self._connector_second_ac_id = None
+        self._show_assembly_in_viewer(fit=True)
+
+    def _show_connector_dialog_with_preview(
+        self,
+        first_ac: Any,
+        second_ac: Any,
+        first_origin: Tuple[float, float, float],
+        second_origin: Tuple[float, float, float],
+        first_normal: Tuple[float, float, float],
+        second_normal: Tuple[float, float, float],
+        first_x_dir: Tuple[float, float, float],
+        second_x_dir: Tuple[float, float, float],
+        align_delta: Any,
+    ) -> Tuple[Optional[float], Optional[float]]:
+        """Show connector dialog with live 3D preview of the alignment.
+
+        Returns (rotation_degrees, offset_mm) or (None, None) if cancelled.
+        """
+        from PySide6.QtWidgets import (QDialog, QVBoxLayout, QHBoxLayout,
+                                        QLabel, QDoubleSpinBox, QPushButton,
+                                        QFrame, QCheckBox)
+
+        if second_ac is None:
+            return (None, None)
+
+        dialog = QDialog(self)
+        dialog.setWindowTitle("Connector — Connection Properties")
+        dialog.setMinimumWidth(340)
+
+        layout = QVBoxLayout(dialog)
+
+        # Info label.
+        layout.addWidget(QLabel("Adjust the connection between the two components:"))
+
+        # Rotation around normal axis of the FIRST connector.
+        rot_layout = QHBoxLayout()
+        rot_layout.addWidget(QLabel("Rotation around axis (°):"))
+        rotation_spin = QDoubleSpinBox()
+        rotation_spin.setDecimals(1)
+        rotation_spin.setRange(-360, 360)
+        rotation_spin.setValue(0.0)
+        rotation_spin.setSuffix("°")
+        rot_layout.addWidget(rotation_spin)
+        layout.addLayout(rot_layout)
+
+        # Offset along normal.
+        off_layout = QHBoxLayout()
+        off_layout.addWidget(QLabel("Offset along normal (mm):"))
+        offset_spin = QDoubleSpinBox()
+        offset_spin.setDecimals(2)
+        offset_spin.setRange(-10000, 10000)
+        offset_spin.setValue(0.0)
+        off_layout.addWidget(offset_spin)
+        layout.addLayout(off_layout)
+
+        # Flip alignment direction.
+        flip_check = QCheckBox("Flip connection direction (normals opposed)")
+        flip_check.setChecked(False)
+        layout.addWidget(flip_check)
+
+        line = QFrame()
+        line.setFrameShape(QFrame.HLine)
+        layout.addWidget(line)
+
+        btn_layout = QHBoxLayout()
+        ok_btn = QPushButton("Connect")
+        cancel_btn = QPushButton("Cancel")
+        btn_layout.addWidget(ok_btn)
+        btn_layout.addWidget(cancel_btn)
+        layout.addLayout(btn_layout)
+
+        # ── Live preview callback ──
+        def _update_preview(*args):
+            import numpy as np
+            rot_deg = rotation_spin.value()
+            off = offset_spin.value()
+            flip = flip_check.isChecked()
+
+            # Compute the aligned position for second component.
+            base_pos = self._connector_align_pos if hasattr(self, '_connector_align_pos') else (
+                np.array(second_ac.position, dtype=float) + align_delta
+            )
+            # Apply offset along the second normal.
+            n2 = np.array(second_normal) / max(np.linalg.norm(second_normal), 1e-12)
+            new_pos = np.array(base_pos, dtype=float) + n2 * off
+
+            # Store preview position.
+            second_ac.position = new_pos
+            self._show_assembly_in_viewer()  # no fit — keep camera steady during live preview
+
+        rotation_spin.valueChanged.connect(_update_preview)
+        offset_spin.valueChanged.connect(_update_preview)
+        flip_check.toggled.connect(_update_preview)
+
+        # Initial preview.
+        _update_preview()
+
+        ok_btn.clicked.connect(dialog.accept)
+        cancel_btn.clicked.connect(dialog.reject)
+
+        def _on_dialog_close():
+            nonlocal dialog
+            if dialog.result() != QDialog.DialogCode.Accepted:
+                # User cancelled — no changes applied, caller will restore.
+                pass
+
+        if dialog.exec():
+            return (rotation_spin.value(), offset_spin.value())
+        return (None, None)
+
+    def _on_delete_connector(self):
+        """Delete the connector nearest to the selected assembly component."""
+        active_id = self._get_active_assembly_component_id()
+        if active_id is None:
+            QMessageBox.warning(self, "No Selection",
+                                "Select an assembly component first")
+            return
+
+        assembly = self._get_assembly()
+        ac = assembly.components.get(active_id)
+        if ac is None or not ac.connectors:
+            QMessageBox.information(self, "No Connectors",
+                                    "This component has no connectors to remove.")
+            return
+
+        # List connectors in a simple choice dialog.
+        conn_names = list(ac.connectors.keys())
+        conn_labels = [f"{c.name} at {c.position}" for c in ac.connectors.values()]
+
+        from PySide6.QtWidgets import QInputDialog
+        label, ok = QInputDialog.getItem(
+            self, "Remove Connector", "Select connector:", conn_labels, 0, False
+        )
+        if ok and label:
+            idx = conn_labels.index(label)
+            conn_id = conn_names[idx]
+            ac.remove_connector(conn_id)
+            logger.info(f"Removed connector {conn_id}")
+            self._show_assembly_in_viewer(fit=True)
+
     def _new_workplane(self):
         """Open the orientation dialog and create a new independent workplane.
 
diff --git a/src/fluency/models/data_model.py b/src/fluency/models/data_model.py
index 9ee5091..60749db 100644
--- a/src/fluency/models/data_model.py
+++ b/src/fluency/models/data_model.py
@@ -336,6 +336,160 @@ class Component:
         self.modified_at = datetime.now()
 
 
+@dataclass
+class Connector:
+    """
+    A connection point on an assembly component instance.
+
+    Stores the position and orientation of a connection point
+    (e.g. a hole center, face midpoint, or edge point) that will
+    later be used by the SolveSpace solver to mate components.
+    The *normal* defines the connection axis direction (e.g. the
+    hole axis for a screw connection).
+    """
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: str = "Untitled Connector"
+
+    # 3D position of the connection point (world coords).
+    position: Tuple[float, float, float] = (0.0, 0.0, 0.0)
+    # Normal direction of the connection (e.g. hole axis).
+    normal: Tuple[float, float, float] = (0.0, 0.0, 1.0)
+    # In-plane X direction for defining the reference frame.
+    x_dir: Tuple[float, float, float] = (1.0, 0.0, 0.0)
+
+    # Rotation around the normal axis (degrees).
+    axis_rotation: float = 0.0
+    # Offset distance along the normal.
+    offset: float = 0.0
+
+    # Which AssemblyComponent this connector belongs to.
+    assembly_component_id: str = ""
+    # Which body/face this connector was placed on (renderer obj_id).
+    source_obj_id: str = ""
+
+    # Future: connected to another Connector's id.
+    # connected_to: Optional[str] = None
+
+    created_at: datetime = field(default_factory=datetime.now)
+    modified_at: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class AssemblyComponent:
+    """
+    An instance of a component within an assembly.
+
+    References a component in the project and stores its relative
+    position and rotation for placement within the assembly.
+    Holds connectors that define connection points for the
+    SolveSpace solver.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    component_id: str = ""
+    name: str = "Untitled Instance"
+
+    # Position and orientation relative to the assembly origin.
+    position: np.ndarray = field(default_factory=lambda: np.array([0.0, 0.0, 0.0]))
+    rotation: np.ndarray = field(default_factory=lambda: np.eye(3))
+
+    # Connectors defined on this component instance.
+    connectors: Dict[str, Connector] = field(default_factory=dict)
+
+    created_at: datetime = field(default_factory=datetime.now)
+    modified_at: datetime = field(default_factory=datetime.now)
+
+    def add_connector(
+        self,
+        position: Tuple[float, float, float],
+        normal: Tuple[float, float, float],
+        x_dir: Tuple[float, float, float],
+        source_obj_id: str = "",
+        name: Optional[str] = None,
+    ) -> Connector:
+        """Add a connector to this component instance."""
+        conn = Connector(
+            name=name or f"Connector {len(self.connectors) + 1}",
+            position=position,
+            normal=normal,
+            x_dir=x_dir,
+            assembly_component_id=self.id,
+            source_obj_id=source_obj_id,
+        )
+        self.connectors[conn.id] = conn
+        self.modified_at = datetime.now()
+        return conn
+
+    def remove_connector(self, connector_id: str) -> bool:
+        """Remove a connector from this component instance."""
+        if connector_id in self.connectors:
+            del self.connectors[connector_id]
+            self.modified_at = datetime.now()
+            return True
+        return False
+
+
+@dataclass
+class Assembly:
+    """
+    An assembly of multiple component instances.
+
+    An assembly groups component instances with relative positions,
+    ready for constraint solving and joint definition between them.
+    Components can be instanced multiple times, each at a different
+    position and rotation.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    name: str = "Untitled Assembly"
+
+    components: Dict[str, AssemblyComponent] = field(default_factory=dict)
+    active_assembly_component: Optional[str] = None
+
+    created_at: datetime = field(default_factory=datetime.now)
+    modified_at: datetime = field(default_factory=datetime.now)
+
+    def add_component_instance(
+        self, component_id: str, name: Optional[str] = None
+    ) -> AssemblyComponent:
+        """Add a component instance to the assembly.
+
+        Returns the newly created AssemblyComponent.  The same
+        component can be added multiple times (multiple instances).
+        """
+        ac = AssemblyComponent(
+            component_id=component_id,
+            name=name or f"Instance {len(self.components) + 1}",
+        )
+        self.components[ac.id] = ac
+        if self.active_assembly_component is None:
+            self.active_assembly_component = ac.id
+        self.modified_at = datetime.now()
+        return ac
+
+    def remove_component_instance(self, assembly_component_id: str) -> bool:
+        """Remove a component instance from the assembly."""
+        if assembly_component_id in self.components:
+            del self.components[assembly_component_id]
+            if self.active_assembly_component == assembly_component_id:
+                self.active_assembly_component = next(
+                    iter(self.components.keys()), None
+                )
+            self.modified_at = datetime.now()
+            return True
+        return False
+
+    def get_active_instance(self) -> Optional[AssemblyComponent]:
+        """Get the currently active assembly component instance."""
+        if (
+            self.active_assembly_component
+            and self.active_assembly_component in self.components
+        ):
+            return self.components[self.active_assembly_component]
+        return None
+
+
 @dataclass
 class Project:
     """
@@ -351,12 +505,85 @@ class Project:
     components: Dict[str, Component] = field(default_factory=dict)
     active_component: Optional[str] = None
 
+    assemblies: Dict[str, Assembly] = field(default_factory=dict)
+    active_assembly: Optional[str] = None
+
     kernel: OCGeometryKernel = field(default_factory=OCGeometryKernel)
 
     created_at: datetime = field(default_factory=datetime.now)
     modified_at: datetime = field(default_factory=datetime.now)
     file_path: Optional[str] = None
 
+    # ── Component helpers ──
+
+    def add_component(self, component: Optional[Component] = None) -> Component:
+        """Add a component to the project."""
+        if component is None:
+            component = Component(name=f"Component {len(self.components) + 1}")
+        self.components[component.id] = component
+        if self.active_component is None:
+            self.active_component = component.id
+        self.modified_at = datetime.now()
+        return component
+
+    def remove_component(self, component_id: str) -> bool:
+        """Remove a component from the project."""
+        if component_id in self.components:
+            del self.components[component_id]
+            if self.active_component == component_id:
+                self.active_component = next(iter(self.components.keys()), None)
+            self.modified_at = datetime.now()
+            return True
+        return False
+
+    def get_active_component(self) -> Optional[Component]:
+        """Get the currently active component."""
+        if self.active_component and self.active_component in self.components:
+            return self.components[self.active_component]
+        return None
+
+    def set_active_component(self, component_id: Optional[str]) -> None:
+        """Set the active component."""
+        self.active_component = component_id
+        self.modified_at = datetime.now()
+
+    # ── Assembly helpers ──
+
+    def add_assembly(self, assembly: Optional[Assembly] = None) -> Assembly:
+        """Add an assembly to the project."""
+        if assembly is None:
+            assembly = Assembly(name=f"Assembly {len(self.assemblies) + 1}")
+        self.assemblies[assembly.id] = assembly
+        if self.active_assembly is None:
+            self.active_assembly = assembly.id
+        self.modified_at = datetime.now()
+        return assembly
+
+    def remove_assembly(self, assembly_id: str) -> bool:
+        """Remove an assembly from the project."""
+        if assembly_id in self.assemblies:
+            del self.assemblies[assembly_id]
+            if self.active_assembly == assembly_id:
+                self.active_assembly = next(iter(self.assemblies.keys()), None)
+            self.modified_at = datetime.now()
+            return True
+        return False
+
+    def get_active_assembly(self) -> Optional[Assembly]:
+        """Get the currently active assembly."""
+        if self.active_assembly and self.active_assembly in self.assemblies:
+            return self.assemblies[self.active_assembly]
+        return None
+
+    def set_active_assembly(self, assembly_id: Optional[str]) -> None:
+        """Set the active assembly."""
+        self.active_assembly = assembly_id
+        self.modified_at = datetime.now()
+
+    def get_component_by_id(self, component_id: str) -> Optional[Component]:
+        """Look up a component by id across all project components."""
+        return self.components.get(component_id)
+
     def add_component(self, component: Optional[Component] = None) -> Component:
         """Add a component to the project."""
         if component is None: