Fix #7878: Fix snapping crash with non-mesh objects

Two bugs introduced in 31b571322:
- SnapObj assumed obj.data is always a Mesh; non-mesh
  objects (empties, lights, etc.) have obj.data = None,
  causing an AttributeError on obj.data.edges.
- view3d_utils was used but never imported.

Generated with the assistance of an AI coding tool.

.github/workflows/build_osx.yml

@@ -53,7 +53,7 @@ jobs:
           python ../nix/cache_dependencies.py unpack
 
       - name: ccache
-        uses: hendrikmuhs/ccache-action@v1.2.20
+        uses: hendrikmuhs/ccache-action@v1.2.22
         with:
           key: mac-${{ matrix.arch }}
 

.github/workflows/build_pyodide.yml

@@ -29,7 +29,7 @@ jobs:
           python ../IfcOpenShell/nix/cache_dependencies.py unpack
 
       - name: ccache
-        uses: hendrikmuhs/ccache-action@v1.2.20
+        uses: hendrikmuhs/ccache-action@v1.2.22
         with:
           key: ubuntu-22.04-${{ runner.arch }}
 

.github/workflows/build_rocky.yml

@@ -48,7 +48,7 @@ jobs:
           python3 ../nix/cache_dependencies.py unpack
 
       - name: ccache
-        uses: hendrikmuhs/ccache-action@v1.2.20
+        uses: hendrikmuhs/ccache-action@v1.2.22
         with:
           key: ubuntu-22.04-${{ runner.arch }}-rockylinux9
 

.github/workflows/build_rocky_arm.yml

@@ -48,7 +48,7 @@ jobs:
           python3 ../nix/cache_dependencies.py unpack
 
       - name: ccache
-        uses: hendrikmuhs/ccache-action@v1.2.20
+        uses: hendrikmuhs/ccache-action@v1.2.22
         with:
           key: ubuntu-22.04-${{ runner.arch }}-rockylinux9
 

.github/workflows/build_win.yml

@@ -52,7 +52,7 @@ jobs:
           }
 
       - name: ccache
-        uses: hendrikmuhs/ccache-action@v1.2.20
+        uses: hendrikmuhs/ccache-action@v1.2.22
         with:
           key: win-${{ matrix.arch }}
           # Windows ccache needs ~1GB

.github/workflows/ci-ifcopenshell-conda-cleaner.yml

@@ -24,7 +24,7 @@ jobs:
     if: |
       github.repository == 'IfcOpenShell/IfcOpenShell'
     steps:
-      - uses: mamba-org/setup-micromamba@v2 # https://github.com/mamba-org/setup-micromamba
+      - uses: mamba-org/setup-micromamba@v3 # https://github.com/mamba-org/setup-micromamba
         with:
           environment-name: test-env
           create-args: >-

.github/workflows/ci-ifcopenshell-conda-daily.yml

@@ -84,7 +84,7 @@ jobs:
         run: |
           curl -L https://github.com/phracker/MacOSX-SDKs/releases/download/11.3/MacOSX10.13.sdk.tar.xz | tar -xvJf - -C /Users/runner/work/
 
-      - uses: mamba-org/setup-micromamba@v2 # https://github.com/mamba-org/setup-micromamba
+      - uses: mamba-org/setup-micromamba@v3 # https://github.com/mamba-org/setup-micromamba
         with:
           environment-name: test-env
           create-args: >-

.github/workflows/ci-ifcopenshell-docker.yml

@@ -35,7 +35,7 @@ jobs:
 
     -
       name: ccache
-      uses: hendrikmuhs/ccache-action@v1.2.20
+      uses: hendrikmuhs/ccache-action@v1.2.22
 
     - 
       name: Build ifcopenshell

.github/workflows/ci.yml

@@ -79,7 +79,7 @@ jobs:
           libhdf5-dev libcgal-dev libeigen3-dev
           
       - name: ccache
-        uses: hendrikmuhs/ccache-action@v1.2.20
+        uses: hendrikmuhs/ccache-action@v1.2.22
         with:
           key: ubuntu-22.04-${{ runner.arch }}
 

.github/workflows/publish-pyodide-demo-app.yml

@@ -31,7 +31,7 @@ jobs:
           submodules: recursive
           fetch-depth: 0
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
       - name: Upload static files as artifact
         id: deployment
         uses: actions/upload-pages-artifact@v4
@@ -47,4 +47,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -14,6 +14,7 @@
 /src/ifcmax/out/
 /src/ifcwrap/out/
 /src/qtviewer/out/
+/src/ifctester/webapp/public/pyodide/
 
 /win/BuildDepsCache*.txt
 
@@ -85,10 +86,11 @@ src/bonsai/bonsai/translations.py
 # bonsai external dependencies (cloned for just ty checks)
 src/bonsai/external_dependencies/
 
-# bonsai test temp files
+# bonsai test temp/cache files
 src/bonsai/test/files/temp
-src/bonsai/test/files/basic.ifc.cache.blend
-src/bonsai/test/files/basic.ifc.cache.sqlite
+src/bonsai/test/files/*.cache.blend
+src/bonsai/test/files/*.cache.json
+src/bonsai/test/files/*.cache.sqlite
 
 # bonsai data
 src/bonsai/bonsai/bim/data/build/

pyproject.toml

@@ -3,7 +3,7 @@ name = "IfcOpenShell"
 version = "0.0.0"
 dependencies = [
     "black==26.3.1",
-    "ruff==0.15.6",
+    "ruff==0.15.8",
     "poethepoet",
     "gersemi==0.26.1",
 ]

src/bonsai/bonsai/bim/handler.py

@@ -45,16 +45,19 @@ from bonsai.bim.module.nest.decorator import NestDecorator
 
 cwd = os.path.dirname(os.path.realpath(__file__))
 global_subscription_owner = object()
+# Separate owner for per-object msgbus subscriptions (name, active_material_index).
+# Using a dedicated owner allows clearing all per-object subscriptions at once
+# during undo/redo without affecting other global subscriptions.
+object_subscription_owner = object()
 
 
 def name_callback(obj: Union[bpy.types.Object, bpy.types.Material], data: str) -> None:
     try:
         obj.name
     except:
-        # The object is invalid but somehow still has a callback. Clear all
-        # msgbus subscriptions to prevent useless further triggers.
-        bpy.msgbus.clear_by_owner(obj)
-        return  # In case the object RNA is gone during an undo / redo operation
+        # The object is invalid but somehow still has a callback.
+        # This can occur during undo/redo when the Python wrapper is stale.
+        return
     # Blender names are up to 63 UTF-8 bytes
     if len(bytes(obj.name, "utf-8")) >= 63:
         return
@@ -189,7 +192,7 @@ def subscribe_to(obj: bpy.types.ID, data_path: str, callback: Callable[[bpy.type
         return
     bpy.msgbus.subscribe_rna(
         key=subscribe_to,
-        owner=obj,
+        owner=object_subscription_owner,
         args=(
             obj,
             data_path,

src/bonsai/bonsai/bim/ifc.py

@@ -316,11 +316,8 @@ class IfcStore:
         del IfcStore.id_map[data["id"]]
         if "guid" in data:
             del IfcStore.guid_map[data["guid"]]
-        obj = IfcStore.get_object_by_name(data["obj"])
-        if obj is None:
-            # obj was just created during this step and didn't existed before.
-            return
-        bpy.msgbus.clear_by_owner(obj)
+        # Note: msgbus subscriptions are cleared globally during
+        # rebuild_element_maps which runs after every undo/redo.
 
     @staticmethod
     def commit_link_element(data: OperationData) -> None:
@@ -367,10 +364,8 @@ class IfcStore:
         del IfcStore.id_map[data["id"]]
         if "guid" in data:
             del IfcStore.guid_map[data["guid"]]
-        obj = IfcStore.get_object_by_name(data["obj"])
-        # obj might be removed after unlink.
-        if not obj:
-            bpy.msgbus.clear_by_owner(obj)
+        # Note: msgbus subscriptions are cleared globally during
+        # rebuild_element_maps which runs after every undo/redo.
 
     @staticmethod
     def unlink_element(

src/bonsai/bonsai/bim/import_ifc.py

@@ -64,8 +64,8 @@ class MaterialCreator:
         mesh: Union[OBJECT_DATA_TYPE, None],
         shape_has_openings: bool,
     ) -> None:
-        if ((rep := getattr(element, "Representation", ...) is not ...) and not rep) or (
-            (rep := getattr(element, "RepresentationMaps", ...) is not ...) and not rep
+        if (((rep := getattr(element, "Representation", ...)) is not ... and not rep) or
+            ((rep := getattr(element, "RepresentationMaps", ...)) is not ... and not rep)
         ):
             return
 

src/bonsai/bonsai/bim/module/drawing/decoration.py

@@ -1898,23 +1898,14 @@ class CutDecorator:
             no = tool.Drawing.get_extrusion_vector(element).normalized()
             no = Vector([1.0, 0.0, 0.0])
         no *= sense_factor
-        # Detect non-conformant exports (e.g. Revit) where DirectionSense=POSITIVE
-        # but the geometry extrudes in the negative direction. If the mesh centroid
-        # in object local space is on the wrong side of the starting plane, flip no.
-        bb = [Vector(v) for v in obj.bound_box]
-        mesh_centroid = sum(bb, Vector((0.0, 0.0, 0.0))) / 8
-        layers = list(layer_set.MaterialLayers)
-        if (mesh_centroid - co).dot(no) < 0:
-            no = -no
-            layers = list(reversed(layers))
-        last_i = len(layers) - 1
+        last_i = len(layer_set.MaterialLayers) - 1
 
         vert_map = {}
         verts = []
         edges = []
         j = 0
 
-        for i, layer in enumerate(layers):
+        for i, layer in enumerate(layer_set.MaterialLayers):
             prev_co = co.copy()
             co += no * layer.LayerThickness * self.unit_scale
             if i != last_i:

src/bonsai/bonsai/bim/module/drawing/operator.py

@@ -729,17 +729,8 @@ class CreateDrawing(bpy.types.Operator):
                 no = tool.Drawing.get_extrusion_vector(element).normalized()
                 no = Vector([1.0, 0.0, 0.0])
             no *= sense_factor
-            # Detect non-conformant exports (e.g. Revit) where DirectionSense=POSITIVE
-            # but the geometry extrudes in the negative direction. If the mesh centroid
-            # in object local space is on the wrong side of the starting plane, flip no.
-            bb = [Vector(v) for v in obj.bound_box]
-            mesh_centroid = sum(bb, Vector((0.0, 0.0, 0.0))) / 8
-            layers = list(layer_set.MaterialLayers)
-            if (mesh_centroid - co).dot(no) < 0:
-                no = -no
-                layers = list(reversed(layers))
-            last_i = len(layers) - 1
-            for i, layer in enumerate(layers):
+            last_i = len(layer_set.MaterialLayers) - 1
+            for i, layer in enumerate(layer_set.MaterialLayers):
                 prev_co = co.copy()
                 co += no * layer.LayerThickness * self.unit_scale
 
@@ -1435,6 +1426,7 @@ class CreateDrawing(bpy.types.Operator):
                 "/Pset_.*Common/.Status",
                 "EPset_Status.Status",
                 "EPset_Status.UserDefinedStatus",
+                "Material.Name",
             ]
 
         group = root.find("{http://www.w3.org/2000/svg}g")

src/bonsai/bonsai/bim/module/geometry/operator.py

@@ -2289,7 +2289,7 @@ class OverrideModeSetEdit(bpy.types.Operator, tool.Ifc.Operator):
         elif obj in pprops.clipping_planes_objs:
             self.report({"ERROR"}, "Clipping planes cannot be edited")
         elif element:
-            if not obj.data:
+            if not obj.data or obj.type not in ("MESH", "CURVE"):
                 self.report({"INFO"}, "No geometry to edit")
             elif tool.Geometry.is_locked(element):
                 self.report({"ERROR"}, lock_error_message(obj.name))

src/bonsai/bonsai/bim/module/model/opening.py

@@ -540,6 +540,16 @@ class AddBoolean(Operator, tool.Ifc.Operator):
         booleans = ifcopenshell.api.geometry.add_boolean(tool.Ifc.get(), first_item, second_items, props.operator)
 
         rep_obj = tool.Geometry.get_geometry_props().representation_obj
+        if booleans:
+            # Users typically select two top-level items and expect the
+            # operand to be absorbed into the boolean, not remain as a
+            # standalone item alongside it.
+            representation = tool.Geometry.get_active_representation(rep_obj)
+            representation = ifcopenshell.util.representation.resolve_representation(representation)
+            second_items_set = set(second_items)
+            new_items = [i for i in representation.Items if i not in second_items_set]
+            if new_items:
+                representation.Items = new_items
         rep_element = tool.Ifc.get_entity(rep_obj)
         tool.Model.mark_manual_booleans(rep_element, booleans)
         tool.Geometry.reload_representation(rep_obj)

src/bonsai/bonsai/bim/module/model/polyline.py

@@ -421,7 +421,7 @@ class PolylineOperator:
                     tool.Polyline.calculate_x_y_and_z(context, self.input_ui, self.tool_state)
 
                 tool.Blender.update_viewport()
-                return {"RUNNING_MODAL"}
+            return {"RUNNING_MODAL"}
 
     def set_offset(self, context: bpy.types.Context, relating_type: ifcopenshell.entity_instance) -> None:
         props = tool.Model.get_model_props()
@@ -461,6 +461,7 @@ class PolylineOperator:
         self.tool_state.axis_method = None
         self.tool_state.plane_method = None
         self.tool_state.mode = "Mouse"
+        tool.Raycast.clear_snap_objs()
         self.visible_objs = tool.Raycast.get_visible_objects(context)
         for obj in self.visible_objs:
             if bbox_2d := tool.Raycast.get_on_screen_2d_bounding_boxes(context, obj):

src/bonsai/bonsai/bim/module/model/slab.py

@@ -248,8 +248,7 @@ class DumbSlabPlaner:
 
     def change_thickness(self, element: ifcopenshell.entity_instance, thickness: float) -> None:
         self.unit_scale = ifcopenshell.util.unit.calculate_unit_scale(tool.Ifc.get())
-        usage_type = tool.Model.get_usage_type(element)
-        if usage_type != "LAYER3":
+        if tool.Model.get_usage_type(element) != "LAYER3":
             return
         layer_params = tool.Model.get_material_layer_parameters(element)
         ifc_file = tool.Ifc.get()
@@ -305,15 +304,11 @@ class DumbSlabPlaner:
                 ifc_position = extrusion.Position
                 position = offset_direction * perpendicular_offset
                 material = ifcopenshell.util.element.get_material(element)
+                if material:
+                    if material.is_a("IfcMaterialLayerSetUsage"):
+                        material.OffsetFromReferenceLine = position.z
                 if ifc_position:
-                    orig = Vector(ifc_position.Location.Coordinates)
-                    layer_normal = offset_direction.normalized()
-                    perp = orig - orig.dot(layer_normal) * layer_normal
-                    new_coords = perp + layer_normal * perpendicular_offset
-                    ifc_position.Location.Coordinates = new_coords
-                    if material:
-                        if material.is_a("IfcMaterialLayerSetUsage"):
-                            material.OffsetFromReferenceLine = new_coords.z
+                    ifc_position.Location.Coordinates = position
                 else:
                     tool.Model.add_extrusion_position(extrusion, position)
 

src/bonsai/bonsai/bim/module/model/workspace.py

@@ -943,7 +943,7 @@ class EditObjectUI:
             if "LAYER2" in AuthoringData.data["selected_material_usages"]:
                 row = cls.layout.row(align=True) if ui_context != "TOOL_HEADER" else row
                 add_layout_hotkey_operator(
-                    cls.layout, "Extend To Underside", "S_E", bpy.ops.bim.extend_to_underside.__doc__, ui_context
+                    cls.layout, "Extend To Underside", "S_E", bpy.ops.bim.extend_walls_to_underside.__doc__, ui_context
                 )
 
         if AuthoringData.data["is_flippable_element"]:

src/bonsai/bonsai/core/covering.py

@@ -51,21 +51,11 @@ def add_instance_flooring_covering_from_cursor(
     if isinstance(space_polygon, str):
         return
 
-    bm = spatial.get_bmesh_from_polygon(space_polygon, h=0, polygon_is_si=True)
-    name = "Covering"
-    mesh = spatial.get_named_mesh_from_bmesh(name=name, bmesh=bm)
-
-    obj = spatial.get_named_obj_from_mesh(name, mesh)
-
+    obj = spatial.create_object("Covering")
     spatial.set_obj_origin_to_cursor_position_and_zero_elevation(obj)
     spatial.translate_obj_to_z_location(obj, z)
-    points = spatial.get_2d_vertices_from_obj(obj)
-    points = spatial.get_scaled_2d_vertices(points)
     spatial.assign_type_to_obj(obj)
-
-    spatial.assign_swept_area_outer_curve_from_2d_vertices(obj, vertices=points)
-    body = spatial.get_body_representation(obj)
-    spatial.regen_obj_representation(obj, body)
+    spatial.set_covering_representation_from_polygon(obj, space_polygon, polygon_is_si=True)
 
 
 def add_instance_ceiling_covering_from_cursor(
@@ -95,21 +85,11 @@ def add_instance_ceiling_covering_from_cursor(
     if isinstance(space_polygon, str):
         return
 
-    bm = spatial.get_bmesh_from_polygon(space_polygon, h=0, polygon_is_si=True)
-    name = "Covering"
-    mesh = spatial.get_named_mesh_from_bmesh(name=name, bmesh=bm)
-
-    obj = spatial.get_named_obj_from_mesh(name, mesh)
-
+    obj = spatial.create_object("Covering")
     spatial.set_obj_origin_to_cursor_position_and_zero_elevation(obj)
     spatial.translate_obj_to_z_location(obj, z + ceiling_height)
-    points = spatial.get_2d_vertices_from_obj(obj)
-    points = spatial.get_scaled_2d_vertices(points)
     spatial.assign_type_to_obj(obj)
-
-    spatial.assign_swept_area_outer_curve_from_2d_vertices(obj, vertices=points)
-    body = spatial.get_body_representation(obj)
-    spatial.regen_obj_representation(obj, body)
+    spatial.set_covering_representation_from_polygon(obj, space_polygon, polygon_is_si=True)
 
 
 def regen_selected_covering_object(root: type[tool.Root], spatial: type[tool.Spatial]) -> None:
@@ -127,19 +107,7 @@ def regen_selected_covering_object(root: type[tool.Root], spatial: type[tool.Spa
     if isinstance(space_polygon, str):
         return
 
-    bm = spatial.get_bmesh_from_polygon(space_polygon, h=0, polygon_is_si=True)
-
-    name = "Aux"
-    mesh = spatial.get_named_mesh_from_bmesh(name=name, bmesh=bm)
-    mesh = spatial.get_transformed_mesh_from_local_to_global(mesh)
-    obj = spatial.get_named_obj_from_mesh(name, mesh)
-
-    points = spatial.get_2d_vertices_from_obj(obj)
-    points = spatial.get_scaled_2d_vertices(points)
-
-    spatial.assign_swept_area_outer_curve_from_2d_vertices(active_obj, vertices=points)
-    body = spatial.get_body_representation(active_obj)
-    spatial.regen_obj_representation(active_obj, body)
+    spatial.set_covering_representation_from_polygon(active_obj, space_polygon, polygon_is_si=True)
 
 
 # TODO CHECK IF IT IS POSSIBLE TO CREATE ONLY ONE CORE FUNCTION FOR _FROM_WALLS
@@ -151,22 +119,13 @@ def add_instance_flooring_coverings_from_walls(root: type[tool.Root], spatial: t
     union = spatial.get_union_shape_from_selected_objects()
     for i, linear_ring in enumerate(union.interiors):
         poly = spatial.get_buffered_poly_from_linear_ring(linear_ring)
-        bm = spatial.get_bmesh_from_polygon(poly, h=0, polygon_is_si=False)
 
         name = "Covering" + str(i)
-        obj = spatial.get_named_obj_from_bmesh(name, bmesh=bm)
-
-        spatial.set_obj_origin_to_bboxcenter(obj)
+        obj = spatial.create_object(name)
+        spatial.set_obj_origin_to_polygon_center(obj, poly, polygon_is_si=False)
         spatial.translate_obj_to_z_location(obj, z)
-
-        points = spatial.get_2d_vertices_from_obj(obj)
-        points = spatial.get_scaled_2d_vertices(points)
-
         spatial.assign_type_to_obj(obj)
-
-        spatial.assign_swept_area_outer_curve_from_2d_vertices(obj, vertices=points)
-        body = spatial.get_body_representation(obj)
-        spatial.regen_obj_representation(obj, body)
+        spatial.set_covering_representation_from_polygon(obj, poly, polygon_is_si=False)
 
 
 def add_instance_ceiling_coverings_from_walls(
@@ -179,22 +138,13 @@ def add_instance_ceiling_coverings_from_walls(
     union = spatial.get_union_shape_from_selected_objects()
     for i, linear_ring in enumerate(union.interiors):
         poly = spatial.get_buffered_poly_from_linear_ring(linear_ring)
-        bm = spatial.get_bmesh_from_polygon(poly, h=0, polygon_is_si=False)
 
         name = "Covering" + str(i)
-        obj = spatial.get_named_obj_from_bmesh(name, bmesh=bm)
-
-        spatial.set_obj_origin_to_bboxcenter(obj)
+        obj = spatial.create_object(name)
+        spatial.set_obj_origin_to_polygon_center(obj, poly, polygon_is_si=False)
         spatial.translate_obj_to_z_location(obj, z)
-
-        points = spatial.get_2d_vertices_from_obj(obj)
-        points = spatial.get_scaled_2d_vertices(points)
-
         spatial.assign_type_to_obj(obj)
-
-        spatial.assign_swept_area_outer_curve_from_2d_vertices(obj, vertices=points)
-        body = spatial.get_body_representation(obj)
-        spatial.regen_obj_representation(obj, body)
+        spatial.set_covering_representation_from_polygon(obj, poly, polygon_is_si=False)
 
 
 class NoDefaultContainer(Exception):

src/bonsai/bonsai/core/spatial.py

@@ -219,13 +219,8 @@ def generate_space(
         else:
             assert space_polygon
 
-    bm = spatial.get_bmesh_from_polygon(space_polygon, h=h, polygon_is_si=True)
-
-    mesh = spatial.get_named_mesh_from_bmesh(name="Space", bmesh=bm)
-
     if element and element.is_a("IfcSpace"):
-        mesh = spatial.get_transformed_mesh_from_local_to_global(mesh)
-        spatial.edit_active_space_obj_from_mesh(mesh)
+        spatial.set_space_representation_from_polygon(active_obj, element, space_polygon, h, polygon_is_si=True)
         spatial.translate_obj_to_z_location(active_obj, z)
     else:
         if relating_type:
@@ -233,12 +228,13 @@ def generate_space(
         else:
             name = "Space"
 
-        obj = spatial.get_named_obj_from_mesh(name, mesh)
+        obj = spatial.create_object(name)
         spatial.set_obj_origin_to_cursor_position_and_zero_elevation(obj)
         spatial.translate_obj_to_z_location(obj, z)
         spatial.assign_ifcspace_class_to_obj(obj)
 
         element = ifc.get_entity(obj)
+        spatial.set_space_representation_from_polygon(obj, element, space_polygon, h, polygon_is_si=True)
 
         if relating_type:
             spatial.assign_relating_type_to_element(ifc, type, element, relating_type)
@@ -257,16 +253,16 @@ def generate_spaces_from_walls(
     for i, linear_ring in enumerate(union.interiors):
         poly = spatial.get_buffered_poly_from_linear_ring(linear_ring)
 
-        bm = spatial.get_bmesh_from_polygon(poly, h, polygon_is_si=False)
-
         name = "Space" + str(i)
 
-        obj = spatial.get_named_obj_from_bmesh(name, bmesh=bm)
-
-        spatial.set_obj_origin_to_bboxcenter_and_zero_elevation(obj)
+        obj = spatial.create_object(name)
+        spatial.set_obj_origin_to_polygon_center(obj, poly, polygon_is_si=False)
         spatial.translate_obj_to_z_location(obj, z)
         spatial.assign_ifcspace_class_to_obj(obj)
 
+        element = ifc.get_entity(obj)
+        spatial.set_space_representation_from_polygon(obj, element, poly, h, polygon_is_si=False)
+
 
 def toggle_space_visibility(ifc: type[tool.Ifc], spatial: type[tool.Spatial]) -> None:
     model = ifc.get()

src/bonsai/bonsai/core/tool.py

@@ -999,14 +999,12 @@ class Spatial:
     def get_purged_inner_holes_poly(cls, union_geom, min_area): pass
     def get_poly_valid_interior_list(cls, poly, min_area, interiors_list): pass
     def get_buffered_poly_from_linear_ring(cls, linear_ring): pass
-    def get_bmesh_from_polygon(cls, poly, h, polygon_is_si=False): pass
-    def get_named_obj_from_bmesh(cls, name, bmesh): pass
-    def get_named_obj_from_mesh(cls, name, mesh): pass
-    def get_named_mesh_from_bmesh(cls, name, bmesh): pass
-    def get_transformed_mesh_from_local_to_global(cls, mesh): pass
-    def edit_active_space_obj_from_mesh(cls, mesh): pass
-    def set_obj_origin_to_bboxcenter(cls, obj): pass
-    def set_obj_origin_to_bboxcenter_and_zero_elevation(cls, obj): pass
+    def get_2d_vertices_from_polygon(cls, poly, obj, polygon_is_si=True): pass
+    def set_extrusion_representation_from_polygon(cls, obj, element, poly, depth_ifc, polygon_is_si=True): pass
+    def set_space_representation_from_polygon(cls, obj, element, poly, h, polygon_is_si=True): pass
+    def set_covering_representation_from_polygon(cls, obj, poly, polygon_is_si=True): pass
+    def create_object(cls, name): pass
+    def set_obj_origin_to_polygon_center(cls, obj, poly, polygon_is_si=True): pass
     def set_obj_origin_to_cursor_position_and_zero_elevation(cls, obj): pass
     def get_selected_objects(cls): pass
     def get_active_obj(cls): pass
@@ -1014,14 +1012,9 @@ class Spatial:
     def get_active_obj_height(cls): pass
     def get_relating_type_id(cls): pass
     def translate_obj_to_z_location(cls, obj, z): pass
-    def get_2d_vertices_from_obj(cls, obj): pass
-    def get_scaled_2d_vertices(cls, points): pass
-    def assign_swept_area_outer_curve_from_2d_vertices(cls, obj, vertices): pass
-    def get_body_representation(cls, obj): pass
     def assign_ifcspace_class_to_obj(cls, obj): pass
     def assign_type_to_obj(cls, obj): pass
     def assign_relating_type_to_element(cls, ifc, type, element, relating_type): pass
-    def regen_obj_representation(cls, obj, body): pass
     def toggle_spaces_visibility_wired_and_textured(cls, spaces): pass
     def toggle_hide_spaces(cls, spaces): pass
     def set_default_container(cls, container): pass

src/bonsai/bonsai/tool/aggregate.py

@@ -49,21 +49,40 @@ class Aggregate(bonsai.core.tool.Aggregate):
         related_object = tool.Ifc.get_entity(related_obj)
         if not relating_object or not related_object:
             return False
+        if relating_object == related_object:
+            return False
+
+        is_compatible_class = False
         if (relating_object.is_a("IfcElement") or relating_object.is_a("IfcElementType")) and related_object.is_a(
             "IfcElement"
         ):
-            return True
-        if tool.Ifc.get_schema() == "IFC2X3":
+            is_compatible_class = True
+        elif tool.Ifc.get_schema() == "IFC2X3":
             if relating_object.is_a("IfcSpatialStructureElement") and related_object.is_a("IfcSpatialStructureElement"):
-                return True
-            if relating_object.is_a("IfcProject") and related_object.is_a("IfcSpatialStructureElement"):
-                return True
+                is_compatible_class = True
+            elif relating_object.is_a("IfcProject") and related_object.is_a("IfcSpatialStructureElement"):
+                is_compatible_class = True
         else:
             if relating_object.is_a("IfcSpatialElement") and related_object.is_a("IfcSpatialElement"):
-                return True
-            if relating_object.is_a("IfcProject") and related_object.is_a("IfcSpatialElement"):
-                return True
-        return False
+                is_compatible_class = True
+            elif relating_object.is_a("IfcProject") and related_object.is_a("IfcSpatialElement"):
+                is_compatible_class = True
+
+        if not is_compatible_class:
+            return False
+
+        # Prevent cyclic references: walk up the full hierarchy from the
+        # proposed parent and reject if we encounter the proposed child.
+        ancestor = ifcopenshell.util.element.get_parent(relating_object)
+        seen = {relating_object}
+        while ancestor:
+            if ancestor == related_object:
+                return False
+            if ancestor in seen:
+                break
+            seen.add(ancestor)
+            ancestor = ifcopenshell.util.element.get_parent(ancestor)
+        return True
 
     @classmethod
     def has_physical_body_representation(cls, element: ifcopenshell.entity_instance) -> bool:

src/bonsai/bonsai/tool/drawing.py

@@ -857,6 +857,8 @@ class Drawing(bonsai.core.tool.Drawing):
 
     @classmethod
     def edit_text_literals(cls, obj: bpy.types.Object, literal_attributes: dict) -> None:
+        if not literal_attributes:
+            return
         assert (element := tool.Ifc.get_entity(obj))
         assert (rep := cls.get_annotation_representation(element))
         to_remove = [i for i in rep.Items if i.is_a("IfcTextLiteral")]

src/bonsai/bonsai/tool/geometry.py

@@ -1407,8 +1407,6 @@ class Geometry(bonsai.core.tool.Geometry):
         :param representation_item: item to remove.
         :param element: item's element. Is used to unmark manual booleans.
         """
-        # NOTE: we assume it's not the last representation item
-        # otherwise we probably would need to remove representation too
         # NOTE: a lot of shared code with `geometry.remove_representation`
         ifc_file = tool.Ifc.get()
         shape_aspects: list[ifcopenshell.entity_instance] = []
@@ -1467,7 +1465,10 @@ class Geometry(bonsai.core.tool.Geometry):
             cls.remove_representation_items_from_shape_aspect([representation_item], shape_aspect)
 
         if representation:
-            representation.Items = tuple(set(representation.Items) - {representation_item})
+            new_items = tuple(set(representation.Items) - {representation_item})
+            if not new_items:
+                return
+            representation.Items = new_items
         also_consider = list(consider_inverses)
         ifcopenshell.util.element.remove_deep2(ifc_file, representation_item, also_consider=also_consider)
 

src/bonsai/bonsai/tool/ifc.py

@@ -197,12 +197,16 @@ class Ifc(bonsai.core.tool.Ifc):
         if not cls.get():
             return
 
+        # Clear all per-object msgbus subscriptions at once using the dedicated
+        # owner.  After undo/redo, per-object Python wrappers have new
+        # identities so clearing by individual obj would miss stale
+        # subscriptions registered with the old wrappers.
+        bpy.msgbus.clear_by_owner(bonsai.bim.handler.object_subscription_owner)
+
         for obj in bpy.data.objects:
             if obj.library:
                 continue
 
-            bpy.msgbus.clear_by_owner(obj)
-
             element = cls.get_entity(obj)
             if not element:
                 continue
@@ -217,8 +221,6 @@ class Ifc(bonsai.core.tool.Ifc):
             if obj.library:
                 continue
 
-            bpy.msgbus.clear_by_owner(obj)
-
             style = cls.get_entity(obj)
             if not style:
                 continue

src/bonsai/bonsai/tool/loader.py

@@ -1090,15 +1090,6 @@ class Loader(bonsai.core.tool.Loader):
             no = cls.get_extrusion_vector(element).normalized()
             no = Vector([1.0, 0.0, 0.0])
         no *= sense_factor
-        # Detect non-conformant exports (e.g. Revit) where DirectionSense=POSITIVE
-        # but the geometry extrudes in the negative direction. If the mesh centroid
-        # in object local space is on the wrong side of the starting plane, flip no.
-        layers = list(layer_set.MaterialLayers)
-        if bm.verts:
-            mesh_centroid = sum((v.co for v in bm.verts), Vector((0.0, 0.0, 0.0))) / len(bm.verts)
-            if (mesh_centroid - co).dot(no) < 0:
-                no = -no
-                layers = list(reversed(layers))
         # Cache this
         body = ifcopenshell.util.representation.get_context(tool.Ifc.get(), "Model", "Body", "MODEL_VIEW")
         styles = {}
@@ -1106,8 +1097,8 @@ class Loader(bonsai.core.tool.Loader):
         for i, material in enumerate(mesh.materials):
             if style := tool.Ifc.get_entity(material):
                 styles[style] = i
-        last_i = len(layers) - 1
-        for i, layer in enumerate(layers):
+        last_i = len(layer_set.MaterialLayers) - 1
+        for i, layer in enumerate(layer_set.MaterialLayers):
             if i != last_i:
                 prev_co = co.copy()
                 co += no * layer.LayerThickness * cls.unit_scale

src/bonsai/bonsai/tool/nest.py

@@ -45,9 +45,23 @@ class Nest(bonsai.core.tool.Nest):
         related_object = tool.Ifc.get_entity(related_obj)
         if not relating_object or not related_object:
             return False
-        if relating_object.is_a("IfcElement") and related_object.is_a("IfcElement"):
-            return True
-        return False
+        if relating_object == related_object:
+            return False
+        is_compatible_class = relating_object.is_a("IfcElement") and related_object.is_a("IfcElement")
+        if not is_compatible_class:
+            return False
+        # Prevent cyclic references: walk up the full hierarchy from the
+        # proposed parent and reject if we encounter the proposed child.
+        ancestor = ifcopenshell.util.element.get_parent(relating_object)
+        seen = {relating_object}
+        while ancestor:
+            if ancestor == related_object:
+                return False
+            if ancestor in seen:
+                break
+            seen.add(ancestor)
+            ancestor = ifcopenshell.util.element.get_parent(ancestor)
+        return True
 
     @classmethod
     def disable_editing(cls, obj: bpy.types.Object) -> None:

src/bonsai/bonsai/tool/raycast.py

@@ -16,6 +16,9 @@
 # You should have received a copy of the GNU General Public License
 # along with Bonsai.  If not, see <http://www.gnu.org/licenses/>.
 
+from __future__ import annotations
+
+import math
 from typing import Union
 
 import bmesh
@@ -24,6 +27,8 @@ import mathutils
 import numpy as np
 from mathutils import Vector
 
+from bpy_extras import view3d_utils
+
 import bonsai.core.tool
 import bonsai.tool as tool
 
@@ -41,6 +46,7 @@ class Raycast(bonsai.core.tool.Raycast):
         (0, -offset),
         (offset, -offset),
     )
+    snap_objs = []
 
     @classmethod
     def get_visible_objects(cls, context: bpy.types.Context):
@@ -69,8 +75,14 @@ class Raycast(bonsai.core.tool.Raycast):
         rv3d = context.region_data
         assert rv3d
         view_location = rv3d.view_matrix.inverted().translation
+        view_normal = rv3d.view_rotation @ mathutils.Vector((0.0, 0.0, -1.0))
         obj_matrix = obj.matrix_world.copy()
         bbox = [obj_matrix @ Vector(v) for v in obj.bound_box]
+        bbox_edges = [
+            (0,1),(1,2),(2,3),(3,0),
+            (4,5),(5,6),(6,7),(7,4),
+            (0,4),(1,5),(2,6),(3,7)
+        ]
 
         transposed_bbox: list[Vector] = []
         bbox_2d: list[float] = []
@@ -94,8 +106,23 @@ class Raycast(bonsai.core.tool.Raycast):
 
         for v in bbox:
             coord_2d = tool.Cad.location_3d_to_region_2d_np(context.region, context.space_data.region_3d, v)
-            if coord_2d is not None:
-                transposed_bbox.append(coord_2d)
+            transposed_bbox.append(coord_2d)
+
+        if not any(transposed_bbox):
+            transposed_bbox = []
+        # If there are None values in transposed_bbox it means that there are vertices behind the camera
+        # so we get the intersection of the edge with the region border
+        # new_bbox = []
+        if any(transposed_bbox) and not all(transposed_bbox):
+            new_bbox = transposed_bbox.copy()
+            new_bbox = [x for x in new_bbox if x is not None]
+            for edge in bbox_edges:
+                if (transposed_bbox[edge[0]] is None) ^ (transposed_bbox[edge[1]] is None):
+                    point, _ = cls.intersect_edge_region_border(context.region, context.space_data, rv3d, bbox[edge[0]], bbox[edge[1]])
+                    if point:
+                        new_bbox.append(point)
+            if new_bbox:
+                transposed_bbox = new_bbox
 
         region = context.region
         borders = (0, region.width, 0, region.height)
@@ -117,6 +144,99 @@ class Raycast(bonsai.core.tool.Raycast):
             return (obj, bbox_2d)
         return None
 
+    def intersect_edge_region_border(region, space, rv3d, v1, v2):
+        def segment_intersect_near_plane(view_matrix, clip_start, p_world_a, p_world_b):
+            a_view = view_matrix @ p_world_a
+            b_view = view_matrix @ p_world_b
+            z_near = -clip_start
+            za = a_view.z
+            zb = b_view.z
+            denom = (zb - za)
+            if denom == 0.0:
+                return None, None
+            t = (z_near - za) / denom
+            if t < 0.0 or t > 1.0:
+                return None, None
+            p_view = a_view.lerp(b_view, t)
+            cam_world = view_matrix.inverted()
+            p_world = cam_world @ p_view
+            return p_world, t
+
+        def is_inside_region(pt2d, region):
+            return 0.0 <= pt2d.x <= region.width and 0.0 <= pt2d.y <= region.height
+
+        def clamp_to_region_border(point2d, region):
+            x, y = point2d
+            x_clamped = max(0.0, min(region.width, x))
+            y_clamped = max(0.0, min(region.height, y))
+            return Vector((x_clamped, y_clamped))
+
+        def find_nearby_onscreen_point(region, rv3d, p1, p2, initial_t_on_segment, max_iters=40, step=0.05):
+            """
+            Use iterative approach: move t toward 0. Returns the first point that is inside region border
+            """
+            t = initial_t_on_segment
+            for i in range(max_iters):
+                test_3d = p1.lerp(p2, t)
+                test_2d = view3d_utils.location_3d_to_region_2d(region, rv3d, test_3d)
+                if test_2d is not None and is_inside_region(test_2d, region):
+                    return test_3d, test_2d, t
+                # move t toward 0 by reducing it by a fraction of its current value
+                t -= step
+                # if t is already very small, break
+                if t <= 1e-6:
+                    break
+
+            return None, None, None
+
+        # Ensures that all the calculation uses the same direction based on which point is on the screen
+        if view3d_utils.location_3d_to_region_2d(region, rv3d, v1):
+            onscreen_vert = v1
+            offscreen_vert = v2
+        else:
+            onscreen_vert = v2
+            offscreen_vert = v1
+            # v2, v1 = v1, v2
+
+        clip_start = space.clip_start
+        view_mat = rv3d.view_matrix
+        inter_world, t_on_ab = segment_intersect_near_plane(view_mat, clip_start, onscreen_vert, offscreen_vert)
+
+        if inter_world is None:
+            print("No intersection with viewport near plane found for the segment.")
+            return
+
+        init_2d = view3d_utils.location_3d_to_region_2d(region, rv3d, inter_world)
+
+        if init_2d is not None and is_inside_region(init_2d, region):
+            final_world = inter_world
+            final_2d = init_2d
+            final_t = initial_t
+        else:
+            found_world, found_2d, found_t = find_nearby_onscreen_point(
+                region, rv3d,
+                onscreen_vert, offscreen_vert,
+                t_on_ab,
+                max_iters=600, step=0.01
+            )
+            if found_world is None:
+                if init_2d is None:
+                    print("Initial projection invalid and iterative search failed.")
+                    return
+                # fallback: clamp projected point to border via manual mapping
+                final_2d = clamp_to_region_border(init_2d, region)
+                final_world = None
+                final_t = None
+                # print("Iterative search failed; using clamped 2D:", final_2d)
+            else:
+                final_world = found_world
+                final_2d = found_2d
+                final_t = found_t
+                # print(f"Found onscreen point at t={final_t:.4f}")
+
+        # print("Final 2D:", final_2d)
+        return final_2d, v2
+
     @classmethod
     def intersect_mouse_2d_bounding_box(cls, mouse_pos: tuple[int, int], bbox: list[float, float, float, float]):
         x, y = mouse_pos
@@ -232,6 +352,161 @@ class Raycast(bonsai.core.tool.Raycast):
         else:
             return None, None, None
 
+    @classmethod
+    def ray_cast_by_proximity_2d(
+        cls,
+        context: bpy.types.Context,
+        event: bpy.types.Event,
+        snap_obj: SnapObj,
+    ):
+
+        def divide_vector(start, end, n):
+            points = []
+            delta = (end - start) / n
+            for i in range(1, n):
+                point = start + i * delta
+                points.append(point)
+            return points
+
+        region = context.region
+        rv3d = context.region_data
+        mouse_pos = event.mouse_region_x, event.mouse_region_y
+        ray_origin, ray_target, ray_direction = cls.get_viewport_ray_data(context, event)
+        points = []
+
+        try:
+            loc = tool.Cad.region_2d_to_location_3d_np(region, rv3d, mouse_pos, ray_direction)
+        except:
+            loc = Vector((0, 0, 0))
+
+        verts_2d = [
+            view3d_utils.location_3d_to_region_2d(region, rv3d, v) for v in snap_obj.verts_3d
+        ]  # Numpy version is worst in performance
+
+        intersected = snap_obj.raycast_boxes(
+            context, event, snap_obj.root, intersected=[], rays=(ray_origin, ray_direction)
+        )
+        edges = []
+        for it in intersected:
+            edges.extend(it.edges)
+        edges = set(edges)
+
+        edge_verts = {}
+        for e in edges:
+            verts_idx = tuple(snap_obj.obj.data.edges[e].vertices)
+            verts = snap_obj.obj.data.vertices
+            v1 = snap_obj.obj.matrix_world @ verts[verts_idx[0]].co
+            v1_2d = verts_2d[verts_idx[0]]
+            v2 = snap_obj.obj.matrix_world @ verts[verts_idx[1]].co
+            v2_2d = verts_2d[verts_idx[1]]
+            if (v1_2d is None) ^ (v2_2d is None):
+                point, _ = cls.intersect_edge_region_border(region, context.space_data, rv3d, v1, v2)
+                if v1_2d is None:
+                    edge_verts[e] = (point, v2_2d)
+                else:
+                    edge_verts[e] = (v1_2d, point)
+            else:
+                edge_verts[e] = (v1_2d, v2_2d)
+            
+        snap_threshold = 10.0
+
+        for i, point in enumerate(verts_2d):
+            if not point:
+                continue
+            distance = (Vector(mouse_pos) - point).length
+            if distance <= snap_threshold:
+                snap_point = {
+                    "object": snap_obj.obj,
+                    "type": "Vertex",
+                    "point": snap_obj.verts_3d[i],
+                    "distance": distance / 10,
+                }
+                points.append(snap_point)
+
+        count = 0
+        selected_edges = {}
+        for e in edges:
+            p0, p1 = edge_verts[e]
+            p0x, p0y = p0
+            p1x, p1y = p1
+            px, py = mouse_pos
+
+            # segment vector = p1 - p0
+            sx = p1x - p0x
+            sy = p1y - p0y
+
+            # seg length squared
+            seg_len_sq = sx * sx + sy * sy
+
+            if seg_len_sq == 0.0:
+                # degenerate segment: return distance to p0
+                dx = px - p0x
+                dy = py - p0y
+                dist = math.hypot(dx, dy)
+                return dist, (p0x, p0y), 0.0
+
+            # project (p - p0) onto seg: t = dot(p-p0, seg) / |seg|^2
+            apx = px - p0x
+            apy = py - p0y
+            t = (apx * sx + apy * sy) / seg_len_sq
+
+            # clamp to segment
+            if t <= 0.0:
+                t_clamped = 0.0
+                cx, cy = p0x, p0y
+            elif t >= 1.0:
+                t_clamped = 1.0
+                cx, cy = p1x, p1y
+            else:
+                t_clamped = t
+                cx = p0x + sx * t_clamped
+                cy = p0y + sy * t_clamped
+
+            dx = px - cx
+            dy = py - cy
+            dist = math.hypot(dx, dy)
+            if dist <= snap_threshold:
+                selected_edges[dist] = e
+
+        if selected_edges:
+            min_dist = float("inf")
+            for key in selected_edges:
+                if key < min_dist:
+                    min_dist = key
+
+            idx = snap_obj.obj.data.edges[selected_edges[min_dist]].vertices
+            edge_verts = (snap_obj.verts_3d[idx[0]], snap_obj.verts_3d[idx[1]])
+            division_points = divide_vector(
+                edge_verts[0], edge_verts[1], 2
+            )  # TODO Make it work for different divisions
+            for division_point in division_points:
+                intersection = tool.Cad.point_on_edge(division_point, (ray_target, loc))
+                distance = (division_point - intersection).length
+                if distance < snap_threshold:
+                    snap_point = {
+                        "object": snap_obj.obj,
+                        "type": "Edge Center",
+                        "point": division_point.copy(),
+                        "distance": distance,
+                    }
+                    points.append(snap_point)
+
+            intersection = tool.Cad.intersect_edges_v2((ray_target, loc), edge_verts)
+            if intersection[0]:
+                if tool.Cad.is_point_on_edge(intersection[1], edge_verts):
+                    distance = (intersection[1] - intersection[0]).length
+                    if distance < snap_threshold:
+                        snap_point = {
+                            "object": snap_obj.obj,
+                            "type": "Edge",
+                            "point": intersection[1].copy(),
+                            "edge_verts": edge_verts,
+                            "distance": distance,
+                        }
+                        points.append(snap_point)
+
+        return points
+
     @classmethod
     def ray_cast_by_proximity(
         cls,
@@ -457,7 +732,9 @@ class Raycast(bonsai.core.tool.Raycast):
             if bbox_2d:
                 if tool.Raycast.intersect_mouse_2d_bounding_box(mouse_pos, bbox_2d):
                     if tool.Raycast.object_is_visible_in_clipping_plane(obj):
-                        objs_to_raycast.append(obj)
+                        snap_obj = cls.create_snap_obj(obj)
+                        if snap_obj is not None:
+                            objs_to_raycast.append(snap_obj)
 
         return objs_to_raycast
 
@@ -474,12 +751,6 @@ class Raycast(bonsai.core.tool.Raycast):
         face_index = None
         # Wireframes
         if obj.type in {"EMPTY", "CURVE"} or (hasattr(obj.data, "polygons") and len(obj.data.polygons) == 0):
-            snap_points = tool.Raycast.ray_cast_by_proximity(context, event, obj)
-            if snap_points:
-                hit = sorted(snap_points, key=lambda x: x["distance"])[0]["point"]
-                if hit:
-                    hit_world = obj.original.matrix_world @ hit
-                    return obj, hit_world, face_index
             return None, None, None
         # Meshes
         else:
@@ -514,19 +785,20 @@ class Raycast(bonsai.core.tool.Raycast):
 
         ray_origin, ray_target, ray_direction = cls.get_viewport_ray_data(context, event)
 
-        for obj in objs_to_raycast:
+        for snap_obj in objs_to_raycast:
             if not include_wireframes and (
-                obj.type in {"EMPTY", "CURVE"} or (hasattr(obj.data, "polygons") and len(obj.data.polygons) == 0)
+                snap_obj.obj.type in {"EMPTY", "CURVE"}
+                or (hasattr(snap_obj.obj.data, "polygons") and len(snap_obj.obj.data.polygons) == 0)
             ):
                 continue
 
-            snap_obj, hit, face_index = cls.cast_rays_to_single_object(context, event, obj)
+            hit_obj, hit, face_index = cls.cast_rays_to_single_object(context, event, snap_obj.obj)
 
             if hit is not None:
                 length_squared = (hit - ray_origin).length_squared
                 if best_obj is None or length_squared < best_length_squared:
                     best_length_squared = length_squared
-                    best_obj = snap_obj
+                    best_obj = hit_obj
                     best_hit = hit
                     best_face_index = face_index
 
@@ -536,6 +808,81 @@ class Raycast(bonsai.core.tool.Raycast):
         else:
             return None, None, None
 
+    @classmethod
+    def ray_cast_and_get_closest_to_camera_snaps(
+        cls,
+        context: bpy.types.Context,
+        event: bpy.types.Event,
+        objs_to_raycast: list[bpy.types.Object],
+    ) -> Union[tuple[bpy.types.Object, Vector, int], tuple[None, None, None]]:
+        closest_length_squared = 1.0
+        closest_obj = None
+        closest_hit = None
+        closest_face_index = None
+
+        ray_origin, ray_target, ray_direction = cls.get_viewport_ray_data(context, event)
+
+        closest_snaps = []
+        hit = None
+
+        for snap_obj in objs_to_raycast:
+            if (snap_obj.obj.type in {"EMPTY", "CURVE"}
+                or (hasattr(snap_obj.obj.data, "polygons") and len(snap_obj.obj.data.polygons) == 0)
+            ):
+                # For wireframe objects we have to test all the snaps to see which is closer
+                snap_points = tool.Raycast.ray_cast_by_proximity_2d(context, event, snap_obj)
+                closest_wf_hit = None
+                closest_wf_length_squared = 1.0
+                closest_wf_point = None
+                if snap_points:
+                    for point in snap_points:
+                        point["group"] = "Wireframe"
+                        closest_snaps.append(point)
+                        length = (point["point"] - ray_origin).length_squared
+                        if closest_wf_hit is None or length < closest_wf_length_squared:
+                            closest_wf_length_squared = length
+                            closest_wf_hit = point["point"]
+                            closest_wf_point = point
+
+                    if closest_wf_point:
+                        hit_obj = closest_wf_point["object"]
+                        hit = closest_wf_point["point"]
+                        face_index = None
+
+
+            else:
+                # Solid objects
+                hit_obj, hit, face_index = cls.cast_rays_to_single_object(context, event, snap_obj.obj)
+
+                if hit:
+                    snap_point = {
+                        "point": hit,
+                        "type": "Face",
+                        "group": "Object",
+                        "object": hit_obj,
+                        "face_index": face_index,
+                        "distance": 9,  # High value so it has low priority
+                    }
+                    closest_snaps.append(snap_point)
+            
+
+            # Here we test which is closer, including wireframe and solid objects
+            if hit is not None:
+                length_squared = (hit - ray_origin).length_squared
+                if closest_obj is None or length_squared < closest_length_squared:
+                    closest_length_squared = length_squared
+                    closest_obj = hit_obj
+                    closest_hit = hit
+                    closest_face_index = face_index
+
+        # Label snaps from the closest object
+        if closest_obj is not None:
+            for snap in closest_snaps:
+                if snap["object"] == closest_obj:
+                    snap["is_closest_to_camera"] = True
+
+        return closest_snaps
+
     @classmethod
     def calculate_snap_threshold(cls, view_distance):
         snap_threshold = view_distance / 100
@@ -547,3 +894,262 @@ class Raycast(bonsai.core.tool.Raycast):
         if lens < 50:
             snap_threshold *= value
         return snap_threshold
+
+    @classmethod
+    def create_snap_obj(cls, obj):
+        if obj.data is None or not isinstance(obj.data, bpy.types.Mesh):
+            return None
+        for snap_obj in cls.snap_objs:
+            if obj.name == snap_obj.obj.name:
+                return snap_obj
+        snap_obj = SnapObj(obj)
+        cls.snap_objs.append(snap_obj)
+        return snap_obj
+
+    @classmethod
+    def clear_snap_objs(cls):
+        TreeNode.__clear_all__()
+        SnapObj.__clear_all__()
+        cls.snap_objs.clear()
+
+
+class TreeNode:
+    all = []
+
+    def __init__(self, box: tuple):
+        self.__class__.all.append(self)
+        self.box = box
+        self.child_a = None
+        self.child_b = None
+        self.edges = []
+
+    def __clear_all__():
+        for instance in TreeNode.all:
+            del instance
+        TreeNode.all.clear()
+
+
+class SnapObj:
+    max_depth = 9
+    all = []
+
+    def __init__(self, obj: bpy.types.Object):
+        self.__class__.all.append(self)
+        self.obj = obj
+        self.root = self._create_root_node()
+        self.root.edges = [e.index for e in obj.data.edges]
+        self.split_box(self.root, 0)
+        self.verts_3d = [obj.matrix_world @ v.co for v in obj.data.vertices]
+        self.snap_points = []
+
+    def __clear_all__():
+        for instance in SnapObj.all:
+            del instance
+        SnapObj.all.clear()
+
+    def _create_root_node(self) -> TreeNode:
+        bbox = tool.Blender.get_object_bounding_box(self.obj)
+        min_point = self.obj.matrix_world @ bbox["min_point"]
+        max_point = self.obj.matrix_world @ bbox["max_point"]
+        new_bbox = self.expand_bounding_box((min_point, max_point))
+        return TreeNode(new_bbox)
+
+    def divide_bounding_box_along_longest_axis(
+        self, min_pt: Vector, max_pt: Vector
+    ) -> Union[tuple[Vector, Vector], tuple[Vector, Vector]]:
+        """
+        Divide a bounding box into two equal parts along the axis with the longest dimension.
+
+        Args:
+            min_pt: The minimum point of the bounding box.
+            max_pt: The maximum point of the bounding box.
+
+        Returns:
+            list: A list of two tuples, each containing the minimum and maximum points of the divided boxes.
+        """
+
+        # Calculate the dimensions of the box
+        dx = max_pt.x - min_pt.x
+        dy = max_pt.y - min_pt.y
+        dz = max_pt.z - min_pt.z
+
+        # Determine the axis with the longest dimension
+        if dx >= dy and dx >= dz:
+            # Divide along the x-axis
+            mid_x = min_pt.x + dx / 2
+            box1 = (min_pt, Vector((mid_x, max_pt.y, max_pt.z)))
+            box2 = (Vector((mid_x, min_pt.y, min_pt.z)), max_pt)
+        elif dy >= dx and dy >= dz:
+            # Divide along the y-axis
+            mid_y = min_pt.y + dy / 2
+            box1 = (min_pt, Vector((max_pt.x, mid_y, max_pt.z)))
+            box2 = (Vector((min_pt.x, mid_y, min_pt.z)), max_pt)
+        else:
+            # Divide along the z-axis
+            mid_z = min_pt.z + dz / 2
+            box1 = (min_pt, Vector((max_pt.x, max_pt.y, mid_z)))
+            box2 = (Vector((min_pt.x, min_pt.y, mid_z)), max_pt)
+
+        return [box1, box2]
+
+    def expand_bounding_box(self, box: tuple[Vector, Vector], offset: float = 0.1) -> tuple[Vector, Vector]:
+        """
+        Expand a 3D bounding box by a given offset.
+
+        Args:
+            min_pt: The minimum point of the bounding box.
+            max_pt: The maximum point of the bounding box.
+            offset: The offset to expand the bounding box by.
+
+        Returns:
+            tuple: A tuple containing the new minimum and maximum points of the expanded bounding box.
+        """
+
+        min_pt, max_pt = box
+        # Calculate the new minimum and maximum points
+        new_min_pt = Vector((min_pt.x - offset, min_pt.y - offset, min_pt.z - offset))
+        new_max_pt = Vector((max_pt.x + offset, max_pt.y + offset, max_pt.z + offset))
+
+        return new_min_pt, new_max_pt
+
+    def split_box(self, parent: TreeNode, depth: int):
+        """
+        Splits the bounding box creating two child nodes to compose a BVH Tree recursively.
+
+        Args:
+            parent: the TreeNode instance that represents the parent node of a BVH Tree.
+            depth: the depth of the BVH Tree no be used in recursion.
+        """
+        if depth > self.max_depth:
+            return
+        box_a, box_b = self.divide_bounding_box_along_longest_axis(parent.box[0], parent.box[1])
+        parent.child_a = TreeNode(box_a)
+        parent.child_b = TreeNode(box_b)
+        edges_a = []
+        edges_b = []
+        for e in parent.edges:
+            verts_idx = [v for v in self.obj.data.edges[e].vertices]
+            verts_coords = []
+            for idx in verts_idx:
+                if idx < len(self.obj.data.vertices):
+                    verts_coords.append(self.obj.matrix_world @ self.obj.data.vertices[idx].co)
+            if self.line_intersects_box(verts_coords[0], verts_coords[1], parent.child_a.box):
+                edges_a.append(e)
+            if self.line_intersects_box(verts_coords[0], verts_coords[1], parent.child_b.box):
+                edges_b.append(e)
+        parent.child_a.edges = edges_a
+        parent.child_b.edges = edges_b
+        self.split_box(parent.child_a, depth + 1)
+        self.split_box(parent.child_b, depth + 1)
+
+    def raycast_box(
+        self, context: bpy.types.Context, event: bpy.types.Event, node: TreeNode, rays: tuple[Vector, Vector]
+    ) -> bool:
+        """
+        Raycast bounding box.
+
+        Args:
+            context: Blender context.
+            event: Blender event.
+            node: a TreeNode instance.
+            rays: tuple containing ray origin and ray direction
+
+        Returns:
+            True if hits the box or False otherwise.
+        """
+        box = node.box
+        min_v = box[0]
+        max_v = box[1]
+        t_min = 0.0
+        t_max = float("inf")
+        ray_origin, ray_dir = rays
+        inv_dir = Vector((1.0 / r if r != 0.0 else 1e32) for r in (ray_dir.x, ray_dir.y, ray_dir.z))
+        # X
+        tx1 = (min_v.x - ray_origin.x) * inv_dir[0]
+        tx2 = (max_v.x - ray_origin.x) * inv_dir[0]
+        tmin = min(tx1, tx2)
+        tmax = max(tx1, tx2)
+        # Y
+        ty1 = (min_v.y - ray_origin.y) * inv_dir[1]
+        ty2 = (max_v.y - ray_origin.y) * inv_dir[1]
+        tmin = max(tmin, min(ty1, ty2))
+        tmax = min(tmax, max(ty1, ty2))
+        # Z
+        tz1 = (min_v.z - ray_origin.z) * inv_dir[2]
+        tz2 = (max_v.z - ray_origin.z) * inv_dir[2]
+        tmin = max(tmin, min(tz1, tz2))
+        tmax = min(tmax, max(tz1, tz2))
+        return (tmax >= max(tmin, t_min)) and (tmin <= t_max)
+
+    def line_intersects_box(self, v1: mathutils.Vector, v2: mathutils.Vector, box: tuple) -> bool:
+        """
+        Check if a line segment intersects an axis-aligned bounding box (AABB).
+
+        Args:
+            v1: The first endpoint of the line segment as a mathutils.Vector.
+            v2: The second endpoint of the line segment as a mathutils.Vector.
+            box: A tuple containing the minimum and maximum points of the AABB, where each point is a mathutils.Vector.
+
+        Returns:
+            bool: True if the segment [v1, v2] intersects the AABB; otherwise, False.
+        """
+        bmin, bmax = box
+        dir = v2 - v1
+        tmin = 0.0
+        tmax = 1.0
+
+        for i in range(3):
+            if abs(dir[i]) < 1e-12:
+                # Line is parallel to slab. If origin not within slab -> no hit.
+                if v1[i] < bmin[i] or v1[i] > bmax[i]:
+                    return False
+            else:
+                ood = 1.0 / dir[i]
+                t1 = (bmin[i] - v1[i]) * ood
+                t2 = (bmax[i] - v1[i]) * ood
+                if t1 > t2:
+                    t1, t2 = t2, t1
+                if t1 > tmin:
+                    tmin = t1
+                if t2 < tmax:
+                    tmax = t2
+                if tmin > tmax:
+                    return False
+
+        # If any overlap in [0,1] exists, there's intersection
+        return (tmax >= 0.0) and (tmin <= 1.0)
+
+    def raycast_boxes(
+        self,
+        context: bpy.types.Context,
+        event: bpy.Types.Event,
+        node: TreeNode,
+        intersected: Union[TreeNode] = [],
+        rays: tuple[Vector, Vector] = (),
+    ) -> Union[TreeNode]:
+        """
+        Raycast bounding box subdivisions recursively.
+
+        Args:
+            context: Blender context.
+            event: Blender event.
+            node: a TreeNode instance.
+            intersected: list of intersected boxes to use in recursion.
+            rays: tuple containing ray origin and ray direction
+
+        Returns:
+            tuple: a list of TreeNode instances that represent the subdivided boxes hit by the ray cast.
+        """
+        if not node.child_a:
+            intersected.append(node)
+            return intersected
+
+        intersects_a = self.raycast_box(context, event, node.child_a, rays)
+        intersects_b = self.raycast_box(context, event, node.child_b, rays)
+        if intersects_a:
+            intersected = self.raycast_boxes(context, event, node.child_a, intersected, rays)
+
+        if intersects_b:
+            intersected = self.raycast_boxes(context, event, node.child_b, intersected, rays)
+
+        return intersected

src/bonsai/bonsai/tool/snap.py

@@ -360,6 +360,7 @@ class Snap(bonsai.core.tool.Snap):
             plane_normal = tool.Polyline.use_transform_orientations(plane_normal)
             return plane_origin, plane_normal
 
+
         # Polyline
         polyline_props = tool.Model.get_polyline_props()
         try:
@@ -388,58 +389,31 @@ class Snap(bonsai.core.tool.Snap):
 
         # Objects
         objs_to_raycast = tool.Raycast.filter_objects_to_raycast(context, event, objs_2d_bbox)
-        # Wireframes
-        # For wireframe we have to get all the objects so we can further calculate edge intersection
+        closest_snaps = tool.Raycast.ray_cast_and_get_closest_to_camera_snaps(context, event, objs_to_raycast)
+        detected_snaps.extend(closest_snaps)
+
+        xray_mode = (space.shading.type == "SOLID" and space.shading.show_xray) or (space.shading.type == "WIREFRAME" and space.shading.show_xray_wireframe)
+
         for snap_obj in objs_to_raycast:
-            if snap_obj.type in {"EMPTY", "CURVE"} or (snap_obj.type == "MESH" and len(snap_obj.data.polygons) == 0):
-                snap_points = tool.Raycast.ray_cast_by_proximity(context, event, snap_obj)
-                if snap_points:
-                    for point in snap_points:
-                        point["group"] = "Wireframe"
-                        detected_snaps.append(point)
-
-        if (space.shading.type == "SOLID" and space.shading.show_xray) or (
-            space.shading.type == "WIREFRAME" and space.shading.show_xray_wireframe
-        ):
-            results = []
-            for obj in objs_to_raycast:
-                results.append(tool.Raycast.cast_rays_to_single_object(context, event, obj))
-        else:
-            results = []
-            results.append(tool.Raycast.cast_rays_and_get_best_object(context, event, objs_to_raycast))
-
-        for result in results:
-            snap_obj = result[0]
-            hit = result[1]
-            face_index = result[2]
-            if hit is not None:
-                # Wireframes
-                if snap_obj.type in {"EMPTY", "CURVE"} or (
-                    snap_obj.type == "MESH" and len(snap_obj.data.polygons) == 0
-                ):
-                    continue
-                # Meshes
-                else:
-                    # Add face snap
-                    snap_point = {
-                        "point": hit,
-                        "type": "Face",
-                        "group": "Object",
-                        "object": snap_obj,
-                        "face_index": face_index,
-                        "distance": 9,  # High value so it has low priority
-                    }
-                    detected_snaps.append(snap_point)
-
-                    # Add vertex and edge snap
-                    snap_points = tool.Raycast.ray_cast_by_proximity(
-                        context, event, snap_obj, snap_obj.data.polygons[face_index]
-                    )
-                    if snap_points:
-                        for point in snap_points:
-                            point["group"] = "Object"
-                            detected_snaps.append(point)
-
+            for snap in closest_snaps:
+                if snap_obj.obj == snap["object"]:
+                    if xray_mode:
+                        if "face_index" in snap and snap["face_index"] is not None:
+                            snap_points = tool.Raycast.ray_cast_by_proximity_2d(context, event, snap_obj)
+                            for point in snap_points:
+                                point["group"] = "Object"
+                                detected_snaps.append(point)
+                    else:
+                        # If it is a solid object that is closest to camera it ignores all the rest
+                        if "is_closest_to_camera" in snap and snap["is_closest_to_camera"] and snap["group"] == "Object":
+                            closest_snap = [snap] # discards objects that aren't the closest
+                            if "face_index" in snap and snap["face_index"] is not None:
+                                snap_points = tool.Raycast.ray_cast_by_proximity_2d(context, event, snap_obj)
+                                for point in snap_points:
+                                    point["group"] = "Object"
+                                    closest_snap.append(point)
+                            detected_snaps = closest_snap
+                        
         # snap to cut geometry (e.g. in plan view)
         if CutDecorator.installed:
             cut_snaps = []

src/bonsai/bonsai/tool/spatial.py

@@ -21,13 +21,13 @@ from __future__ import annotations
 import json
 from collections import defaultdict
 from collections.abc import Generator, Iterable
-from math import pi
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
 import bmesh
 import bpy
 import ifcopenshell
 import ifcopenshell.api.attribute
+import ifcopenshell.api.geometry
 import ifcopenshell.api.type
 import ifcopenshell.geom
 import ifcopenshell.util.classification
@@ -991,114 +991,107 @@ class Spatial(bonsai.core.tool.Spatial):
         return poly
 
     @classmethod
-    def get_bmesh_from_polygon(cls, poly: Polygon, h: float, polygon_is_si: bool = False) -> bmesh.types.BMesh:
-        """
-        :param h: Height, in meters.
-        :param polygon_is_si: Should be True if `poly` is defined in meters.
-        """
-        mat = Matrix()
-        bm = bmesh.new()
-        bm.verts.index_update()
-        bm.edges.index_update()
-
-        mat_invert = mat.inverted()
-        si_conversion = 1.0 if polygon_is_si else ifcopenshell.util.unit.calculate_unit_scale(tool.Ifc.get())
-        new_verts = [
-            # bm.verts.new(mat_invert @ (Vector([v[0], v[1], 0]) * si_conversion)) for v in poly.exterior.coords[0:-1]
-            bm.verts.new(mat_invert @ (Vector([v[0], v[1], 0]) * si_conversion))
-            for v in shapely.get_exterior_ring(poly).coords[0:-1]
-        ]
-        [bm.edges.new((new_verts[i], new_verts[i + 1])) for i in range(len(new_verts) - 1)]
-        bm.edges.new((new_verts[len(new_verts) - 1], new_verts[0]))
-
-        bm.verts.index_update()
-        bm.edges.index_update()
-
-        bmesh.ops.remove_doubles(bm, verts=bm.verts, dist=1e-5)
-        bmesh.ops.triangle_fill(bm, edges=bm.edges)
-        bmesh.ops.dissolve_limit(bm, angle_limit=pi / 180 * 5, verts=bm.verts, edges=bm.edges)
-
-        if h != 0:
-            extrusion = bmesh.ops.extrude_face_region(bm, geom=bm.faces)
-            extruded_verts = [g for g in extrusion["geom"] if isinstance(g, bmesh.types.BMVert)]
-            bmesh.ops.translate(bm, vec=[0.0, 0.0, h], verts=extruded_verts)
-
-        bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
-
-        return bm
-
-    @classmethod
-    def get_named_obj_from_bmesh(cls, name: str, bmesh: bmesh.types.BMesh) -> bpy.types.Object:
-        mesh = cls.get_named_mesh_from_bmesh(name, bmesh)
-        obj = cls.get_named_obj_from_mesh(name, mesh)
-        return obj
-
-    @classmethod
-    def get_named_obj_from_mesh(cls, name: str, mesh: bpy.types.Mesh) -> bpy.types.Object:
+    def create_object(cls, name: str) -> bpy.types.Object:
+        mesh = bpy.data.meshes.new(name=name)
         obj = bpy.data.objects.new(name, mesh)
         return obj
 
     @classmethod
-    def get_named_mesh_from_bmesh(cls, name: str, bmesh: bmesh.types.BMesh) -> bpy.types.Mesh:
-        mesh = bpy.data.meshes.new(name=name)
-        bmesh.to_mesh(mesh)
-        bmesh.free()
-        return mesh
+    def set_obj_origin_to_polygon_center(
+        cls, obj: bpy.types.Object, poly: Polygon, polygon_is_si: bool = True
+    ) -> None:
+        unit_scale = ifcopenshell.util.unit.calculate_unit_scale(tool.Ifc.get())
+        centroid = poly.centroid
+        if polygon_is_si:
+            obj.location = Vector((centroid.x, centroid.y, 0))
+        else:
+            obj.location = Vector((centroid.x * unit_scale, centroid.y * unit_scale, 0))
+
 
     @classmethod
-    def get_transformed_mesh_from_local_to_global(cls, mesh: bpy.types.Mesh) -> bpy.types.Mesh:
-        active_obj = cls.get_active_obj()
-        mat = active_obj.matrix_world
-        mesh.transform(mat.inverted())
-        mesh.update()
-        return mesh
+    def get_2d_vertices_from_polygon(
+        cls,
+        poly: Polygon,
+        obj: bpy.types.Object,
+        polygon_is_si: bool = True,
+    ) -> list[list[float]]:
+        """Convert a world-space shapely polygon to 2D vertices in obj's local space, in IFC file units.
+
+        :param poly: The polygon in world space.
+        :param obj: The Blender object whose local space is used.
+        :param polygon_is_si: True if polygon coords are in SI, False if in IFC file units.
+        :return: List of [x, y] coordinates (not closed).
+        """
+        ifc_file = tool.Ifc.get()
+        unit_scale = ifcopenshell.util.unit.calculate_unit_scale(ifc_file)
+        bpy.context.view_layer.update()
+        mat_inv = obj.matrix_world.inverted()
+        coords_2d = []
+        for v in shapely.get_exterior_ring(poly).coords[:-1]:
+            world_si = Vector((v[0], v[1], 0))
+            if not polygon_is_si:
+                world_si = world_si * unit_scale
+            local_si = mat_inv @ world_si
+            coords_2d.append([local_si.x / unit_scale, local_si.y / unit_scale])
+        return coords_2d
 
     @classmethod
-    def edit_active_space_obj_from_mesh(cls, mesh: bpy.types.Mesh) -> None:
-        active_obj = bpy.context.active_object
-        old_mesh = active_obj.data
-        old_mesh_name = old_mesh.name
-        assert active_obj and isinstance(old_mesh, bpy.types.Mesh)
-        tool.Geometry.get_mesh_props(mesh).ifc_definition_id = tool.Geometry.get_mesh_props(old_mesh).ifc_definition_id
-        tool.Geometry.change_object_data(active_obj, mesh, is_global=True)
-        tool.Ifc.edit(active_obj)
-        tool.Blender.remove_data_block(old_mesh)
-        # Rename after old mesh is removed to avoid .001 suffix.
-        mesh.name = old_mesh_name
+    def set_extrusion_representation_from_polygon(
+        cls,
+        obj: bpy.types.Object,
+        element: ifcopenshell.entity_instance,
+        poly: Polygon,
+        depth_ifc: float,
+        polygon_is_si: bool = True,
+    ) -> None:
+        """Create or replace the IFC body representation from a polygon extrusion.
+
+        :param obj: The Blender object.
+        :param element: The IFC product entity.
+        :param poly: The polygon in world space.
+        :param depth_ifc: The extrusion depth in IFC file units.
+        :param polygon_is_si: True if polygon coords are in SI, False if in IFC file units.
+        """
+        ifc_file = tool.Ifc.get()
+        builder = ifcopenshell.util.shape_builder.ShapeBuilder(ifc_file)
+
+        coords_2d = cls.get_2d_vertices_from_polygon(poly, obj, polygon_is_si)
+
+        curve = builder.polyline(coords_2d, closed=True)
+        item = builder.extrude(curve, magnitude=depth_ifc)
+
+        old_body = ifcopenshell.util.representation.get_representation(element, "Model", "Body", "MODEL_VIEW")
+        if old_body:
+            context = old_body.ContextOfItems
+            ifcopenshell.api.geometry.unassign_representation(ifc_file, product=element, representation=old_body)
+            ifcopenshell.api.geometry.remove_representation(ifc_file, representation=old_body)
+        else:
+            context = ifcopenshell.util.representation.get_context(ifc_file, "Model", "Body", "MODEL_VIEW")
+
+        new_body = builder.get_representation(context, item)
+        ifcopenshell.api.geometry.assign_representation(ifc_file, product=element, representation=new_body)
+        bonsai.core.geometry.switch_representation(
+            tool.Ifc,
+            tool.Geometry,
+            obj=obj,
+            representation=new_body,
+        )
 
     @classmethod
-    def set_obj_origin_to_bboxcenter(cls, obj: bpy.types.Object) -> None:
-        mat = obj.matrix_world
-        inverted = mat.inverted()
-        local_bbox_center = 0.125 * sum((Vector(b) for b in obj.bound_box), Vector())
-        global_bbox_center = mat @ local_bbox_center
+    def set_space_representation_from_polygon(
+        cls,
+        obj: bpy.types.Object,
+        element: ifcopenshell.entity_instance,
+        poly: Polygon,
+        h: float,
+        polygon_is_si: bool = True,
+    ) -> None:
+        """Create or replace the IFC body representation of a space from a polygon.
 
-        oldLoc = obj.location
-        newLoc = global_bbox_center
-        diff = newLoc - oldLoc
-        for vert in obj.data.vertices:
-            aux_vector = mat @ vert.co
-            aux_vector = aux_vector - diff
-            vert.co = inverted @ aux_vector
-        obj.location = newLoc
-
-    @classmethod
-    def set_obj_origin_to_bboxcenter_and_zero_elevation(cls, obj: bpy.types.Object) -> None:
-        mat = obj.matrix_world
-        inverted = mat.inverted()
-        local_bbox_center = 0.125 * sum((Vector(b) for b in obj.bound_box), Vector())
-        global_bbox_center = mat @ local_bbox_center
-        global_obj_origin = global_bbox_center
-        global_obj_origin.z = 0
-
-        oldLoc = obj.location
-        newLoc = global_obj_origin
-        diff = newLoc - oldLoc
-        for vert in obj.data.vertices:
-            aux_vector = mat @ vert.co
-            aux_vector = aux_vector - diff
-            vert.co = inverted @ aux_vector
-        obj.location = newLoc
+        :param h: The height in SI (meters).
+        """
+        unit_scale = ifcopenshell.util.unit.calculate_unit_scale(tool.Ifc.get())
+        cls.set_extrusion_representation_from_polygon(obj, element, poly, h / unit_scale, polygon_is_si)
 
     @classmethod
     def set_obj_origin_to_cursor_position_and_zero_elevation(cls, obj: bpy.types.Object) -> None:
@@ -1145,65 +1138,53 @@ class Spatial(bonsai.core.tool.Spatial):
         if z != 0:
             obj.location = obj.location + Vector((0, 0, z))
 
-    @classmethod
-    def get_2d_vertices_from_obj(cls, obj: bpy.types.Object) -> list[tuple]:
-        points = []
-        vectors = [v.co for v in obj.data.vertices.values()]
-        for vector in vectors:
-            points.append(vector.xy)
-
-        points.append(vectors[0].xy)
-        return points
-
-    @classmethod
-    def get_scaled_2d_vertices(cls, points: list[Vector]) -> list[tuple[float, float]]:
-        model = tool.Ifc.get()
-        unit_scale = ifcopenshell.util.unit.calculate_unit_scale(model)
-        _points = []
-        for p in points:
-            _p = list(p)
-            _p[0] /= unit_scale
-            _p[1] /= unit_scale
-            _points.append(_p)
-        return _points
-
-    @classmethod
-    def assign_swept_area_outer_curve_from_2d_vertices(cls, obj: bpy.types.Object, vertices: list[Vector]) -> None:
-        body = cls.get_body_representation(obj)
-        model = tool.Ifc.get()
-        extrusion = tool.Model.get_extrusion(body)
-        area = extrusion.SweptArea
-        old_area = area.OuterCurve
-
-        builder = ifcopenshell.util.shape_builder.ShapeBuilder(model)
-        outer_curve = builder.polyline(vertices, closed=True)
-
-        area.OuterCurve = outer_curve
-        ifcopenshell.util.element.remove_deep2(tool.Ifc.get(), old_area)
-
-    @classmethod
-    def get_body_representation(cls, obj: bpy.types.Object) -> Union[ifcopenshell.entity_instance, None]:
-        element = tool.Ifc.get_entity(obj)
-        return ifcopenshell.util.representation.get_representation(element, "Model", "Body", "MODEL_VIEW")
-
     @classmethod
     def assign_ifcspace_class_to_obj(cls, obj: bpy.types.Object) -> None:
-        bpy.ops.bim.assign_class(obj=obj.name, ifc_class="IfcSpace")
+        bonsai.core.root.assign_class(
+            tool.Ifc,
+            tool.Collector,
+            tool.Root,
+            obj=obj,
+            ifc_class="IfcSpace",
+            should_add_representation=False,
+        )
 
     @classmethod
     def assign_type_to_obj(cls, obj: bpy.types.Object) -> None:
-        # TODO this code looks in the wrong spot and suspicious
         props = tool.Model.get_model_props()
         ifc_file = tool.Ifc.get()
         relating_type_id = props.relating_type_id
-        relating_type = tool.Ifc.get().by_id(int(relating_type_id))
+        relating_type = ifc_file.by_id(int(relating_type_id))
         ifc_class = relating_type.is_a()
         instance_class = ifcopenshell.util.type.get_applicable_entities(ifc_class, ifc_file.schema)[0]
-        bpy.ops.bim.assign_class(obj=obj.name, ifc_class=instance_class)
+        bonsai.core.root.assign_class(
+            tool.Ifc,
+            tool.Collector,
+            tool.Root,
+            obj=obj,
+            ifc_class=instance_class,
+            should_add_representation=False,
+        )
         element = tool.Ifc.get_entity(obj)
         assert element
         ifcopenshell.api.type.assign_type(ifc_file, related_objects=[element], relating_type=relating_type)
 
+    @classmethod
+    def set_covering_representation_from_polygon(
+        cls,
+        obj: bpy.types.Object,
+        poly: Polygon,
+        polygon_is_si: bool = True,
+    ) -> None:
+        """Create the covering body representation from a polygon, extruded by the type's material layer thickness."""
+        element = tool.Ifc.get_entity(obj)
+        relating_type = ifcopenshell.util.element.get_type(element)
+        material = ifcopenshell.util.element.get_material(relating_type, should_skip_usage=True)
+        depth = 0.0
+        if material and material.is_a("IfcMaterialLayerSet"):
+            depth = sum(layer.LayerThickness for layer in material.MaterialLayers)
+        cls.set_extrusion_representation_from_polygon(obj, element, poly, depth, polygon_is_si)
+
     @classmethod
     def assign_relating_type_to_element(
         cls,
@@ -1214,14 +1195,6 @@ class Spatial(bonsai.core.tool.Spatial):
     ) -> None:
         bonsai.core.type.assign_type(ifc, tool.Model, type, element=element, type=relating_type)
 
-    @classmethod
-    def regen_obj_representation(cls, obj: bpy.types.Object, body: ifcopenshell.entity_instance) -> None:
-        bonsai.core.geometry.switch_representation(
-            tool.Ifc,
-            tool.Geometry,
-            obj=obj,
-            representation=body,
-        )
 
     @classmethod
     def set_space_visibility(cls, is_visible: bool) -> None:

src/bonsai/test/bim/feature/covering.feature

@@ -2,7 +2,7 @@
 Feature: Covering
     Covers covering tool.
 
-Scenario: Execute generate flooring coverings from walls
+Scenario: Add flooring from walls
     Given an empty IFC project
     And I load the demo construction library
     And I set "scene.BIMModelProperties.ifc_class" to "IfcWallType"
@@ -24,9 +24,9 @@ Scenario: Execute generate flooring coverings from walls
     And the cursor is at "0,2.0,0"
     And I set "scene.BIMModelProperties.length" to "1.9"
     And I press "bim.add_occurrence"
-    # add_instance_flooring_coverings_from_walls is expecting FLOORING predefined type.
+    # Set COV30 predefined type to FLOORING.
     And the object "IfcCoveringType/COV30" is selected
-    And I look at the "Attributes" panel
+    And I look at the "Object Attributes" panel
     And I click "Edit"
     And I set the "PredefinedType" property to "FLOORING"
     And I click "Save Attributes"
@@ -42,3 +42,108 @@ Scenario: Execute generate flooring coverings from walls
     Then the object "IfcCovering/Covering0" exists
     And the object "IfcCovering/Covering0" is at "1.8,1.05,0.0"
     And the object "IfcCovering/Covering0" dimensions are "3.4,1.9,0.03"
+
+Scenario: Add ceiling from walls
+    Given an empty IFC project
+    And I load the demo construction library
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcWallType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcWallType') if e.Name == 'WAL100'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_occurrence"
+    And the object "IfcWall/Wall" is selected
+    And I press "bim.change_layer_length(length=3.6)"
+    And the cursor is at "3.6,0.1,3"
+    And I set "scene.BIMModelProperties.length" to "2.0"
+    And I press "bim.add_occurrence"
+    And the cursor is at "3.5,2.1,3"
+    And I set "scene.BIMModelProperties.length" to "3.5"
+    And I press "bim.add_occurrence"
+    And the cursor is at "0,2.0,0"
+    And I set "scene.BIMModelProperties.length" to "1.9"
+    And I press "bim.add_occurrence"
+    # Set COV30 predefined type to CEILING.
+    And the object "IfcCoveringType/COV30" is selected
+    And I look at the "Object Attributes" panel
+    And I click "Edit"
+    And I set the "PredefinedType" property to "CEILING"
+    And I click "Save Attributes"
+    # Run the operator with ceiling height = 2.7 (default).
+    When the object "IfcWall/Wall" is selected
+    And additionally the object "IfcWall/Wall.001" is selected
+    And additionally the object "IfcWall/Wall.002" is selected
+    And additionally the object "IfcWall/Wall.003" is selected
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcCoveringType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcCoveringType') if e.Name == 'COV30'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_instance_ceiling_coverings_from_walls"
+    Then the object "IfcCovering/Covering0" exists
+    And the object "IfcCovering/Covering0" is at "1.8,1.05,2.7"
+    And the object "IfcCovering/Covering0" dimensions are "3.4,1.9,0.03"
+
+Scenario: Add flooring from cursor
+    Given an empty IFC project
+    And I load the demo construction library
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcWallType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcWallType') if e.Name == 'WAL100'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_occurrence"
+    And the cursor is at "1.1,0,0"
+    And I press "bim.add_occurrence"
+    And the object "IfcWall/Wall.001" is selected
+    And I press "bim.hotkey(hotkey='S_R')"
+    And the cursor is at "0,.9,0"
+    And I press "bim.add_occurrence"
+    And the cursor is at "-1,0,0"
+    And I press "bim.add_occurrence"
+    And the object "IfcWall/Wall.003" is selected
+    And I press "bim.hotkey(hotkey='S_R')"
+    And the object "IfcWall/Wall.003" is moved to "0,0,0"
+    # Set COV30 predefined type to FLOORING.
+    And the object "IfcCoveringType/COV30" is selected
+    And I look at the "Object Attributes" panel
+    And I click "Edit"
+    And I set the "PredefinedType" property to "FLOORING"
+    And I click "Save Attributes"
+    # Generate covering from cursor inside the room.
+    When the cursor is at "0.5,0.5,0"
+    And I deselect all objects
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcCoveringType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcCoveringType') if e.Name == 'COV30'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_instance_flooring_covering_from_cursor"
+    Then the object "IfcCovering/Covering" exists
+    And the object "IfcCovering/Covering" dimensions are "1,0.8,0.03"
+
+Scenario: Add ceiling from cursor
+    Given an empty IFC project
+    And I load the demo construction library
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcWallType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcWallType') if e.Name == 'WAL100'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_occurrence"
+    And the cursor is at "1.1,0,0"
+    And I press "bim.add_occurrence"
+    And the object "IfcWall/Wall.001" is selected
+    And I press "bim.hotkey(hotkey='S_R')"
+    And the cursor is at "0,.9,0"
+    And I press "bim.add_occurrence"
+    And the cursor is at "-1,0,0"
+    And I press "bim.add_occurrence"
+    And the object "IfcWall/Wall.003" is selected
+    And I press "bim.hotkey(hotkey='S_R')"
+    And the object "IfcWall/Wall.003" is moved to "0,0,0"
+    # Set COV30 predefined type to CEILING.
+    And the object "IfcCoveringType/COV30" is selected
+    And I look at the "Object Attributes" panel
+    And I click "Edit"
+    And I set the "PredefinedType" property to "CEILING"
+    And I click "Save Attributes"
+    # Generate covering from cursor inside the room.
+    When the cursor is at "0.5,0.5,0"
+    And I deselect all objects
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcCoveringType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcCoveringType') if e.Name == 'COV30'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_instance_ceiling_covering_from_cursor"
+    Then the object "IfcCovering/Covering" exists
+    And the object "IfcCovering/Covering" dimensions are "1,0.8,0.03"

src/bonsai/test/bim/feature/model.feature

@@ -396,6 +396,44 @@ Scenario: Add a slab
     And the object "IfcSlab/Slab" bottom left corner is at "0,0,0"
     And the object "IfcSlab/Slab" top right corner is at "1,1,0.2"
 
+Scenario: Extend walls to underside
+    Given an empty IFC project
+    And I load the demo construction library
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcWallType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcWallType') if e.Name == 'WAL100'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_occurrence"
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcSlabType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcSlabType') if e.Name == 'FLR200'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_occurrence"
+    And the object "IfcSlab/Slab" is moved to "0,0,2.5"
+    When the object "IfcWall/Wall" is selected
+    And additionally the object "IfcSlab/Slab" is selected
+    And I look at the tool header
+    And I click "Extend To Underside"
+    Then the object "IfcWall/Wall" dimensions are "1,0.1,2.5"
+
+Scenario: Extend walls to underside - extending to a tessellated gable roof
+    Given an empty IFC project
+    And I load the demo construction library
+    And I set "scene.BIMModelProperties.ifc_class" to "IfcWallType"
+    And the variable "element_type" is "[e for e in {ifc}.by_type('IfcWallType') if e.Name == 'WAL100'][0].id()"
+    And I set "scene.BIMModelProperties.relating_type_id" to "{element_type}"
+    And I press "bim.add_occurrence"
+    # Create gable roof: a cube turned into a prism with a ridge.
+    And I add a cube of size "1" at "0.5,0.05,3"
+    And the object "Cube" is selected
+    And I evaluate expression "obj = bpy.context.active_object; [setattr(v.co, 'y', 0) for v in obj.data.vertices if v.co.z > 0]"
+    And I set "scene.BIMRootProperties.ifc_product" to "IfcElement"
+    And I set "scene.BIMRootProperties.ifc_class" to "IfcRoof"
+    And I press "bim.assign_class"
+    When the object "IfcWall/Wall" is selected
+    And additionally the object "IfcRoof/Cube" is selected
+    And I look at the tool header
+    And I click "Extend To Underside"
+    Then the object "IfcWall/Wall" dimensions are "1,0.1,2.5"
+
 Scenario: Enable editing a slab profile
     Given an empty IFC project
     And I load the demo construction library

src/bonsai/test/bim/test_feature.py

@@ -133,7 +133,11 @@ class PanelSpy:
             self.spied_labels.append(kwargs["text"])
             return self
         elif self.spied_attr == "prop":
-            props, name = args
+            if args:
+                props, name = args
+            else:
+                props = kwargs.get("data")
+                name = kwargs.get("property")
             props: bpy.types.bpy_struct
             text = kwargs.get("text", props.bl_rna.properties[name].name)
             icon = kwargs.get("icon", None)
@@ -390,6 +394,32 @@ def i_look_at_the_panel_panel(panel: str) -> None:
     panel_spy.refresh_spy()
 
 
+@given(parsers.parse("I look at the tool header"))
+@when(parsers.parse("I look at the tool header"))
+@then(parsers.parse("I look at the tool header"))
+def i_look_at_the_tool_header() -> None:
+    from bonsai.bim.module.model.workspace import EditObjectUI
+
+    class MockRegion:
+        type = "UI"
+
+    class MockContext:
+        def __getattr__(self, name):
+            if name == "region":
+                return MockRegion()
+            return getattr(bpy.context, name)
+
+    global panel_spy
+    panel_spy = PanelSpy(EditObjectUI)
+    panel_spy.is_spy_dirty = False
+    panel_spy.spied_attr = None
+    panel_spy.spied_labels = []
+    panel_spy.spied_props = []
+    panel_spy.spied_operators = []
+    panel_spy.spied_lists = []
+    EditObjectUI.draw(MockContext(), panel_spy)
+
+
 @given(parsers.parse('I open the "{name}" menu'))
 @when(parsers.parse('I open the "{name}" menu'))
 @then(parsers.parse('I open the "{name}" menu'))

src/bonsai/test/tool/test_aggregate.py

@@ -18,6 +18,7 @@
 
 import bpy
 import ifcopenshell
+import ifcopenshell.api.aggregate
 import ifcopenshell.api.context
 import ifcopenshell.api.geometry
 import ifcopenshell.api.root
@@ -99,6 +100,42 @@ class TestCanAggregate(NewFile):
         subelement_obj = bpy.data.objects.new("Object", None)
         assert subject.can_aggregate(element_obj, subelement_obj) is False
 
+    def test_element_cannot_aggregate_to_itself(self):
+        ifc = ifcopenshell.file()
+        tool.Ifc.set(ifc)
+        element = ifc.createIfcElementAssembly()
+        element_obj = bpy.data.objects.new("Object", None)
+        tool.Ifc.link(element, element_obj)
+        assert subject.can_aggregate(element_obj, element_obj) is False
+
+    def test_cyclic_aggregation_is_prevented(self):
+        ifc = ifcopenshell.file()
+        tool.Ifc.set(ifc)
+        assembly_a = ifc.createIfcElementAssembly()
+        assembly_a_obj = bpy.data.objects.new("AssemblyA", None)
+        tool.Ifc.link(assembly_a, assembly_a_obj)
+        beam = ifc.createIfcBeam()
+        beam_obj = bpy.data.objects.new("Beam", None)
+        tool.Ifc.link(beam, beam_obj)
+        ifcopenshell.api.aggregate.assign_object(ifc, products=[beam], relating_object=assembly_a)
+        assert subject.can_aggregate(beam_obj, assembly_a_obj) is False
+
+    def test_deep_cyclic_aggregation_is_prevented(self):
+        ifc = ifcopenshell.file()
+        tool.Ifc.set(ifc)
+        assembly_a = ifc.createIfcElementAssembly()
+        assembly_a_obj = bpy.data.objects.new("AssemblyA", None)
+        tool.Ifc.link(assembly_a, assembly_a_obj)
+        assembly_b = ifc.createIfcElementAssembly()
+        assembly_b_obj = bpy.data.objects.new("AssemblyB", None)
+        tool.Ifc.link(assembly_b, assembly_b_obj)
+        beam = ifc.createIfcBeam()
+        beam_obj = bpy.data.objects.new("Beam", None)
+        tool.Ifc.link(beam, beam_obj)
+        ifcopenshell.api.aggregate.assign_object(ifc, products=[assembly_b], relating_object=assembly_a)
+        ifcopenshell.api.aggregate.assign_object(ifc, products=[beam], relating_object=assembly_b)
+        assert subject.can_aggregate(beam_obj, assembly_a_obj) is False
+
 
 class TestHasPhysicalBodyRepresentation(NewFile):
     def test_run(self):

src/bonsai/test/tool/test_nest.py

@@ -19,6 +19,7 @@
 import bpy
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.api.nest
 import ifcopenshell.api.spatial
 
 import bonsai.core.tool
@@ -51,6 +52,42 @@ class TestCanNest(NewFile):
         subelement_obj = bpy.data.objects.new("Object", None)
         assert subject.can_nest(element_obj, subelement_obj) is False
 
+    def test_element_cannot_nest_to_itself(self):
+        ifc = ifcopenshell.file()
+        tool.Ifc.set(ifc)
+        element = ifc.createIfcWall()
+        element_obj = bpy.data.objects.new("Object", None)
+        tool.Ifc.link(element, element_obj)
+        assert subject.can_nest(element_obj, element_obj) is False
+
+    def test_cyclic_nesting_is_prevented(self):
+        ifc = ifcopenshell.file()
+        tool.Ifc.set(ifc)
+        wall_a = ifc.createIfcWall()
+        wall_a_obj = bpy.data.objects.new("WallA", None)
+        tool.Ifc.link(wall_a, wall_a_obj)
+        wall_b = ifc.createIfcWall()
+        wall_b_obj = bpy.data.objects.new("WallB", None)
+        tool.Ifc.link(wall_b, wall_b_obj)
+        ifcopenshell.api.nest.assign_object(ifc, related_objects=[wall_b], relating_object=wall_a)
+        assert subject.can_nest(wall_b_obj, wall_a_obj) is False
+
+    def test_deep_cyclic_nesting_is_prevented(self):
+        ifc = ifcopenshell.file()
+        tool.Ifc.set(ifc)
+        wall_a = ifc.createIfcWall()
+        wall_a_obj = bpy.data.objects.new("WallA", None)
+        tool.Ifc.link(wall_a, wall_a_obj)
+        wall_b = ifc.createIfcWall()
+        wall_b_obj = bpy.data.objects.new("WallB", None)
+        tool.Ifc.link(wall_b, wall_b_obj)
+        wall_c = ifc.createIfcWall()
+        wall_c_obj = bpy.data.objects.new("WallC", None)
+        tool.Ifc.link(wall_c, wall_c_obj)
+        ifcopenshell.api.nest.assign_object(ifc, related_objects=[wall_b], relating_object=wall_a)
+        ifcopenshell.api.nest.assign_object(ifc, related_objects=[wall_c], relating_object=wall_b)
+        assert subject.can_nest(wall_c_obj, wall_a_obj) is False
+
 
 class TestDisableEditing(NewFile):
     def test_run(self):

src/common.mk

@@ -28,6 +28,7 @@ dist:
 	mkdir -p dist
 	cp -r $(PACKAGE_NAME) build/
 	cp pyproject.toml build/
+	if [ -f README.md ]; then cp README.md build/; fi
 ifeq ($(IS_STABLE), TRUE)
 	$(SED) 's/version = "0.0.0"/version = "$(VERSION)"/' build/pyproject.toml
 ifdef IS_MODULE

src/ifcedit/README.md

@@ -0,0 +1,248 @@
+<!-- This file was generated with the assistance of an AI coding tool. -->
+# ifcedit
+
+A CLI wrapper that exposes all 350+ `ifcopenshell.api` mutation functions as
+shell commands. Functions are auto-discovered at runtime via introspection --
+no hardcoded list to maintain.
+
+## Installation
+
+```bash
+pip install ifcedit
+```
+
+Requires `ifcopenshell`.
+
+## Usage
+
+```
+ifcedit <command> [options] [--format json|text]
+```
+
+Three subcommands: `list` to discover functions, `docs` to read their
+documentation, and `run` to execute them.
+
+## Subcommands
+
+### list
+
+Discover available API modules and their functions.
+
+**List all modules:**
+
+```bash
+ifcedit list
+```
+
+```json
+[
+  {
+    "module": "root",
+    "description": "Functions for creating project-level entities",
+    "functions": ["create_entity", "remove_product", "copy_class"],
+    "count": 3
+  },
+  {
+    "module": "spatial",
+    "description": "Functions for managing spatial relationships",
+    "functions": ["assign_container", "unassign_container"],
+    "count": 2
+  }
+]
+```
+
+**List functions in a module:**
+
+```bash
+ifcedit list root
+```
+
+```json
+[
+  {
+    "name": "create_entity",
+    "description": "Create an IFC entity with optional initial attributes",
+    "params": [
+      {"name": "ifc_class", "type": "str", "required": true},
+      {"name": "name", "type": "Optional[str]"}
+    ]
+  }
+]
+```
+
+### docs
+
+Show full documentation for a specific function, including parameter
+descriptions from docstrings and return type.
+
+```bash
+ifcedit docs root.create_entity
+```
+
+```json
+{
+  "module": "root",
+  "function": "create_entity",
+  "description": "Create an IFC entity with optional initial attributes",
+  "long_description": "This function creates a new entity instance...",
+  "params": [
+    {
+      "name": "ifc_class",
+      "type": "str",
+      "required": true,
+      "description": "The IFC class name (e.g. 'IfcWall', 'IfcProject')"
+    },
+    {
+      "name": "name",
+      "type": "Optional[str]",
+      "description": "Optional name attribute"
+    }
+  ],
+  "return_type": "ifcopenshell.entity_instance",
+  "return_description": "The newly created entity instance"
+}
+```
+
+### run
+
+Execute an API function against an IFC file. Parameters are passed as
+`--key value` pairs after the function name.
+
+```bash
+ifcedit run model.ifc root.create_entity --ifc_class IfcWall --name "My Wall"
+```
+
+```json
+{
+  "ok": true,
+  "result": {"id": 42, "type": "IfcWall", "name": "My Wall"}
+}
+```
+
+**Options:**
+
+- `-o, --output <path>` -- write to a different file instead of overwriting the input
+- `--dry-run` -- validate parameters without executing or saving
+
+```bash
+# Save to a new file
+ifcedit run model.ifc root.create_entity -o out.ifc --ifc_class IfcWall
+
+# Validate without executing
+ifcedit run model.ifc root.create_entity --dry-run --ifc_class IfcWall
+```
+
+Dry-run output shows the resolved parameters:
+
+```json
+{
+  "ok": true,
+  "dry_run": true,
+  "module": "root",
+  "function": "create_entity",
+  "args": {"ifc_class": "IfcWall", "name": "My Wall"}
+}
+```
+
+## Parameter type coercion
+
+CLI strings are automatically converted to the types expected by each API
+function, using the function's type annotations:
+
+| Type | CLI input | Python value |
+|------|-----------|--------------|
+| `str` | `"hello"` | `"hello"` |
+| `int` | `"42"` or `"#42"` | `42` |
+| `float` | `"3.14"` | `3.14` |
+| `bool` | `"true"`, `"1"`, `"yes"` | `True` |
+| `Optional[X]` | `"none"` | `None` |
+| `entity_instance` | `"42"` or `"#42"` | resolved from model by step ID |
+| `list[entity_instance]` | `"5,6,7"` or `"[5, 6, 7]"` | list of resolved entities |
+| `dict` | `'{"key": "val"}'` | parsed JSON object |
+| `Literal["A", "B"]` | `"A"` | validated against allowed values |
+
+## Examples
+
+```bash
+# Create a project
+ifcedit run model.ifc root.create_entity --ifc_class IfcProject --name "My Project"
+
+# Assign an element to a storey
+ifcedit run model.ifc spatial.assign_container --products 10 --relating_structure 4
+
+# Assign multiple elements at once
+ifcedit run model.ifc aggregate.assign_object --products "5,6,7" --relating_object 1
+
+# Add a property set
+ifcedit run model.ifc pset.add_pset --product 10 --name "Pset_WallCommon"
+
+# Edit properties
+ifcedit run model.ifc pset.edit_pset --pset 15 \
+    --properties '{"IsExternal": true, "FireRating": "2HR"}'
+```
+
+### quantify
+
+Run quantity take-off (QTO) on an IFC file, computing physical measurements
+(volume, area, length, count, weight) and writing them back as
+`IfcElementQuantity` property sets. Uses `ifc5d` rules.
+
+**List available rules:**
+
+```bash
+ifcedit quantify list
+```
+
+```json
+[
+  {"name": "IFC4QtoBaseQuantities"},
+  {"name": "IFC4X3QtoBaseQuantities"}
+]
+```
+
+**Run QTO on a file:**
+
+```bash
+ifcedit quantify run model.ifc IFC4QtoBaseQuantities
+ifcedit quantify run model.ifc IFC4QtoBaseQuantities --selector IfcWall
+ifcedit quantify run model.ifc IFC4QtoBaseQuantities -o model_qto.ifc
+```
+
+```json
+{"ok": true, "rule": "IFC4QtoBaseQuantities", "elements_quantified": 42}
+```
+
+Options:
+
+- `--selector <query>` -- ifcopenshell selector to restrict elements (default: all `IfcElement`)
+- `-o, --output <path>` -- write to a different file instead of overwriting the input
+
+Note: `quantify run` writes geometry-based measurements and requires the
+IfcOpenShell C++ geometry bindings for elements with computed quantities.
+
+## Error handling
+
+Errors are reported in the JSON response:
+
+```json
+{
+  "ok": false,
+  "error": "Entity #999 not found in model"
+}
+```
+
+Exit code is 0 on success, 1 on error.
+
+## Relationship to ifcquery
+
+`ifcedit` and `ifcquery` are complementary tools:
+
+- **ifcquery** reads and inspects IFC models (summary, tree, info, select, relations, clash, validate, schedule, cost, schema, contexts, materials, plot, render)
+- **ifcedit** modifies IFC models by wrapping `ifcopenshell.api` functions, and runs QTO via `quantify`
+
+A typical workflow: inspect with `ifcquery`, look up the right API function
+with `ifcedit docs`, then apply changes with `ifcedit run`.
+
+## License
+
+LGPLv3+ -- see the IfcOpenShell project license.

src/ifcedit/ifcedit/__init__.py

@@ -0,0 +1,20 @@
+# This file was generated with the assistance of an AI coding tool.
+# IfcEdit - CLI wrapper for ifcopenshell.api mutation functions
+# Copyright (C) 2026 Bruno Postle <bruno@postle.net>
+#
+# This file is part of IfcEdit.
+#
+# IfcEdit is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcEdit is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcEdit.  If not, see <http://www.gnu.org/licenses/>.
+
+__version__ = version = "0.0.0"

src/ifcedit/ifcedit/__main__.py

@@ -0,0 +1,217 @@
+# This file was generated with the assistance of an AI coding tool.
+# IfcEdit - CLI wrapper for ifcopenshell.api mutation functions
+# Copyright (C) 2026 Bruno Postle <bruno@postle.net>
+#
+# This file is part of IfcEdit.
+#
+# IfcEdit is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcEdit is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcEdit.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+import ifcopenshell
+
+from ifcedit.discover import function_docs, list_functions, list_modules
+from ifcedit.quantify import list_rules, run_quantify
+from ifcedit.run import run_api
+
+
+def format_output(data, fmt: str) -> str:
+    if fmt == "json":
+        return json.dumps(data, indent=2, ensure_ascii=False)
+    elif fmt == "text":
+        return _format_text(data)
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+def _format_text(data, indent: int = 0) -> str:
+    prefix = "  " * indent
+    lines = []
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, (dict, list)):
+                lines.append(f"{prefix}{key}:")
+                lines.append(_format_text(value, indent + 1))
+            else:
+                lines.append(f"{prefix}{key}: {value}")
+    elif isinstance(data, list):
+        for item in data:
+            if isinstance(item, dict):
+                lines.append(_format_text(item, indent))
+                lines.append("")
+            else:
+                lines.append(f"{prefix}- {item}")
+    else:
+        lines.append(f"{prefix}{data}")
+    return "\n".join(lines)
+
+
+def cmd_list(args):
+    if args.module:
+        try:
+            functions = list_functions(args.module)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+        print(format_output(functions, args.output_format))
+    else:
+        modules = list_modules()
+        print(format_output(modules, args.output_format))
+
+
+def cmd_docs(args):
+    parts = args.function_path.split(".")
+    if len(parts) != 2:
+        print("Error: function path must be 'module.function' (e.g. root.create_entity)", file=sys.stderr)
+        sys.exit(1)
+    module, function = parts
+    try:
+        docs = function_docs(module, function)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    print(format_output(docs, args.output_format))
+
+
+def cmd_run(args, extra_args):
+    try:
+        model = ifcopenshell.open(args.ifc_file)
+    except Exception as e:
+        print(f"Error: Could not open IFC file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    parts = args.function_path.split(".")
+    if len(parts) != 2:
+        print("Error: function path must be 'module.function' (e.g. root.create_entity)", file=sys.stderr)
+        sys.exit(1)
+    module, function = parts
+
+    # Parse extra --key value arguments into a dict
+    raw_kwargs = _parse_extra_args(extra_args)
+
+    if args.dry_run:
+        result = {"ok": True, "dry_run": True, "module": module, "function": function, "args": raw_kwargs}
+    else:
+        result = run_api(model, module, function, raw_kwargs)
+
+        if result["ok"]:
+            output_path = args.output or args.ifc_file
+            model.write(output_path)
+
+    print(format_output(result, args.output_format))
+    if not result["ok"]:
+        sys.exit(1)
+
+
+def _parse_extra_args(extra: list[str]) -> dict[str, str]:
+    """Parse a list of ['--key', 'value', ...] into a dict."""
+    kwargs = {}
+    i = 0
+    while i < len(extra):
+        arg = extra[i]
+        if arg.startswith("--"):
+            key = arg[2:]
+            if i + 1 < len(extra) and not extra[i + 1].startswith("--"):
+                kwargs[key] = extra[i + 1]
+                i += 2
+            else:
+                # Flag without value — treat as "true"
+                kwargs[key] = "true"
+                i += 1
+        else:
+            print(f"Error: Unexpected argument: {arg}", file=sys.stderr)
+            sys.exit(1)
+    return kwargs
+
+
+def cmd_quantify(args, extra_args):
+    if args.quantify_command == "list":
+        result = list_rules()
+        print(format_output(result, args.output_format))
+    elif args.quantify_command == "run":
+        try:
+            model = ifcopenshell.open(args.ifc_file)
+        except Exception as e:
+            print(f"Error: Could not open IFC file: {e}", file=sys.stderr)
+            sys.exit(1)
+        selector = args.selector or None
+        result = run_quantify(model, args.rule_name, selector=selector)
+        if result["ok"]:
+            output_path = args.output or args.ifc_file
+            model.write(output_path)
+        print(format_output(result, args.output_format))
+        if not result["ok"]:
+            sys.exit(1)
+    else:
+        print("Error: quantify requires a subcommand: list or run", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="ifcedit",
+        description="CLI wrapper for ifcopenshell.api IFC model mutation functions",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["json", "text"],
+        default="json",
+        dest="output_format",
+        help="Output format (default: json)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # list
+    list_parser = subparsers.add_parser("list", help="List API modules or functions in a module")
+    list_parser.add_argument("module", nargs="?", help="Module name (omit to list all modules)")
+
+    # docs
+    docs_parser = subparsers.add_parser("docs", help="Show full documentation for an API function")
+    docs_parser.add_argument("function_path", help="module.function (e.g. root.create_entity)")
+
+    # run
+    run_parser = subparsers.add_parser("run", help="Execute an API function on an IFC file")
+    run_parser.add_argument("ifc_file", help="Path to the IFC file")
+    run_parser.add_argument("function_path", help="module.function (e.g. root.create_entity)")
+    run_parser.add_argument("-o", "--output", help="Output file path (default: overwrite input)")
+    run_parser.add_argument("--dry-run", action="store_true", help="Validate without executing or saving")
+
+    # quantify
+    quantify_parser = subparsers.add_parser("quantify", help="Quantity take-off (QTO) using ifc5d rules")
+    quantify_sub = quantify_parser.add_subparsers(dest="quantify_command")
+    quantify_sub.add_parser("list", help="List available QTO rule names")
+    qrun_parser = quantify_sub.add_parser("run", help="Run QTO on an IFC file")
+    qrun_parser.add_argument("ifc_file", help="Path to the IFC file")
+    qrun_parser.add_argument("rule_name", help="QTO rule name (e.g. IFC4QtoBaseQuantities)")
+    qrun_parser.add_argument("--selector", help="ifcopenshell selector to restrict elements (default: all IfcElement)")
+    qrun_parser.add_argument("-o", "--output", help="Output file path (default: overwrite input)")
+
+    args, extra = parser.parse_known_args()
+
+    if args.command == "list":
+        cmd_list(args)
+    elif args.command == "docs":
+        cmd_docs(args)
+    elif args.command == "run":
+        cmd_run(args, extra)
+    elif args.command == "quantify":
+        cmd_quantify(args, extra)
+
+
+if __name__ == "__main__":
+    main()

src/ifcedit/ifcedit/coerce.py

@@ -0,0 +1,180 @@
+# This file was generated with the assistance of an AI coding tool.
+# IfcEdit - CLI wrapper for ifcopenshell.api mutation functions
+# Copyright (C) 2026 Bruno Postle <bruno@postle.net>
+#
+# This file is part of IfcEdit.
+#
+# IfcEdit is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcEdit is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcEdit.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import json
+import typing
+
+import ifcopenshell
+
+
+def coerce_value(
+    value_str: str,
+    type_hint,
+    model: ifcopenshell.file | None = None,
+    lookup_file: ifcopenshell.file | None = None,
+):
+    """Convert a CLI string argument to the proper Python type based on a type hint.
+
+    Args:
+        value_str: The raw string from the CLI.
+        type_hint: The type annotation from the function signature.
+        model: The main open IFC model, needed to resolve entity instance references by ID.
+        lookup_file: Override file for entity resolution (e.g. a library file for
+            project.append_asset). When provided, entity IDs are looked up here instead
+            of in model.
+
+    Returns:
+        The converted Python value.
+
+    Raises:
+        ValueError: If the value cannot be converted.
+        TypeError: If the type hint is not supported.
+    """
+    # When a library file has been opened, entity IDs are resolved from it, not the main model.
+    effective_lookup = lookup_file if lookup_file is not None else model
+
+    if type_hint is None:
+        return value_str
+
+    origin = typing.get_origin(type_hint)
+    args = typing.get_args(type_hint)
+
+    # Union / Optional
+    if origin is typing.Union:
+        non_none_types = [a for a in args if a is not type(None)]
+        if value_str.lower() == "none":
+            if type(None) in args:
+                return None
+        # Try each non-None type in order
+        for t in non_none_types:
+            try:
+                return coerce_value(value_str, t, model, lookup_file)
+            except (ValueError, TypeError):
+                continue
+        raise ValueError(f"Cannot convert '{value_str}' to any of {non_none_types}")
+
+    # Literal
+    if origin is typing.Literal:
+        allowed = args
+        if value_str in [str(a) for a in allowed]:
+            # return the actual literal value with proper type
+            for a in allowed:
+                if str(a) == value_str:
+                    return a
+        raise ValueError(f"'{value_str}' is not one of: {', '.join(repr(a) for a in allowed)}")
+
+    # list types
+    if origin is list:
+        if args and _is_entity_type(args[0]):
+            return _coerce_entity_list(value_str, effective_lookup)
+        if args:
+            items = _split_list(value_str)
+            return [coerce_value(item.strip(), args[0], model, lookup_file) for item in items]
+        return _split_list(value_str)
+
+    # dict types
+    if origin is dict:
+        return _floatify_numeric_lists(json.loads(value_str))
+
+    # Simple types
+    if type_hint is str:
+        return value_str
+    if type_hint is int:
+        return int(value_str.lstrip("#"))
+    if type_hint is float:
+        return float(value_str)
+    if type_hint is bool:
+        return value_str.lower() in ("true", "1", "yes")
+
+    # ifcopenshell.file — open from path string
+    if type_hint is ifcopenshell.file:
+        return ifcopenshell.open(value_str)
+
+    # entity_instance
+    if _is_entity_type(type_hint):
+        return _coerce_entity(value_str, effective_lookup)
+
+    # Fallback: try json.loads for complex types, then plain string
+    try:
+        return json.loads(value_str)
+    except (json.JSONDecodeError, TypeError):
+        return value_str
+
+
+def _is_entity_type(hint) -> bool:
+    """Check if a type hint refers to ifcopenshell.entity_instance."""
+    if hint is ifcopenshell.entity_instance:
+        return True
+    if isinstance(hint, type) and issubclass(hint, ifcopenshell.entity_instance):
+        return True
+    return False
+
+
+def _coerce_entity(value_str: str | int, lookup_file: ifcopenshell.file | None) -> ifcopenshell.entity_instance:
+    """Resolve a step ID string like '123' or '#123' to an entity instance."""
+    if lookup_file is None:
+        raise ValueError("Cannot resolve entity reference without an IFC model")
+    if isinstance(value_str, int):
+        entity_id = value_str
+    else:
+        entity_id = int(value_str.strip().lstrip("#"))
+    try:
+        return lookup_file.by_id(entity_id)
+    except RuntimeError:
+        raise ValueError(f"Entity #{entity_id} not found in model")
+
+
+def _coerce_entity_list(value_str: str, lookup_file: ifcopenshell.file | None) -> list[ifcopenshell.entity_instance]:
+    """Resolve a comma-separated list of step IDs to entity instances."""
+    items = _split_list(value_str)
+    return [_coerce_entity(item.strip(), lookup_file) for item in items]
+
+
+def _floatify_numeric_lists(obj):
+    """Recursively convert lists of numbers to lists of floats.
+
+    IFC C++ bindings require Python floats (not ints) for AGGREGATE OF DOUBLE
+    attributes (e.g. DirectionRatios, Coordinates). JSON parsing produces ints
+    for whole numbers like 0, which causes a TypeError at the binding level.
+    """
+    if isinstance(obj, dict):
+        return {k: _floatify_numeric_lists(v) for k, v in obj.items()}
+    if (
+        isinstance(obj, list)
+        and obj
+        and all(isinstance(v, (int, float)) for v in obj)
+        and any(isinstance(v, float) for v in obj)
+    ):
+        return [float(v) for v in obj]
+    return obj
+
+
+def _split_list(value_str: str) -> list[str]:
+    """Split a comma-separated string, handling JSON arrays too."""
+    value_str = value_str.strip()
+    if value_str.startswith("["):
+        try:
+            parsed = json.loads(value_str)
+            if isinstance(parsed, list):
+                return [json.dumps(item) if isinstance(item, (dict, list)) else str(item) for item in parsed]
+        except json.JSONDecodeError:
+            pass
+    return [item.strip() for item in value_str.split(",") if item.strip()]

src/ifcedit/ifcedit/discover.py

@@ -0,0 +1,282 @@
+# This file was generated with the assistance of an AI coding tool.
+# IfcEdit - CLI wrapper for ifcopenshell.api mutation functions
+# Copyright (C) 2026 Bruno Postle <bruno@postle.net>
+#
+# This file is part of IfcEdit.
+#
+# IfcEdit is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcEdit is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcEdit.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import re
+import typing
+from pathlib import Path
+
+
+def _api_package_path() -> Path:
+    """Return the filesystem path to the ifcopenshell.api package."""
+    import ifcopenshell.api
+
+    return Path(ifcopenshell.api.__file__).parent
+
+
+def list_modules() -> list[dict]:
+    """List all API modules with their function counts and descriptions.
+
+    Returns a list of dicts: [{"module": "root", "description": "...", "functions": [...], "count": 4}, ...]
+    """
+    api_path = _api_package_path()
+    modules = []
+    for child in sorted(api_path.iterdir()):
+        if not child.is_dir() or child.name.startswith("_"):
+            continue
+        init_file = child / "__init__.py"
+        if not init_file.exists():
+            continue
+        try:
+            mod = importlib.import_module(f"ifcopenshell.api.{child.name}")
+        except Exception:
+            continue
+        all_names = getattr(mod, "__all__", [])
+        if not all_names:
+            continue
+        description = ""
+        if mod.__doc__:
+            description = mod.__doc__.strip().split("\n")[0]
+        modules.append(
+            {
+                "module": child.name,
+                "description": description,
+                "functions": list(all_names),
+                "count": len(all_names),
+            }
+        )
+    return modules
+
+
+def list_functions(module: str) -> list[dict]:
+    """List functions in an API module with one-line descriptions and parameter info.
+
+    Returns a list of dicts: [{"name": "create_entity", "description": "...", "params": [...]}]
+    """
+    mod = importlib.import_module(f"ifcopenshell.api.{module}")
+    all_names = getattr(mod, "__all__", [])
+    functions = []
+    for name in all_names:
+        fn = _get_underlying_function(module, name)
+        if fn is None:
+            continue
+        description = ""
+        if fn.__doc__:
+            description = fn.__doc__.strip().split("\n")[0]
+        params = _extract_params(fn)
+        functions.append(
+            {
+                "name": name,
+                "description": description,
+                "params": params,
+            }
+        )
+    return functions
+
+
+def function_docs(module: str, function: str) -> dict:
+    """Full documentation for a single API function.
+
+    Returns a dict with: module, function, description, params (with types/defaults/descriptions), return_type
+    """
+    fn = _get_underlying_function(module, function)
+    if fn is None:
+        raise ValueError(f"Function '{module}.{function}' not found")
+
+    description = ""
+    long_description = ""
+    if fn.__doc__:
+        description, long_description = _parse_docstring_body(fn.__doc__)
+
+    params = _extract_params(fn)
+    param_descriptions = _parse_param_docs(fn.__doc__ or "")
+    for param in params:
+        if param["name"] in param_descriptions:
+            param["description"] = param_descriptions[param["name"]]
+
+    return_type = _format_type_hint(typing.get_type_hints(fn).get("return"))
+    return_description = _parse_return_doc(fn.__doc__ or "")
+
+    result = {
+        "module": module,
+        "function": function,
+        "description": description,
+        "long_description": long_description,
+        "params": params,
+    }
+    if return_type:
+        result["return_type"] = return_type
+    if return_description:
+        result["return_description"] = return_description
+    return result
+
+
+def _get_underlying_function(module: str, function: str):
+    """Get the actual function object (unwrapping the listener wrapper if needed)."""
+    try:
+        fn_module = importlib.import_module(f"ifcopenshell.api.{module}.{function}")
+        fn = getattr(fn_module, function, None)
+        return fn
+    except (ImportError, AttributeError):
+        return None
+
+
+def _extract_params(fn) -> list[dict]:
+    """Extract parameter info from a function's signature and type hints."""
+    sig = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    params = []
+    for name, param in sig.parameters.items():
+        if name == "file" or name == "self":
+            continue
+        info = {"name": name}
+        if name in hints:
+            info["type"] = _format_type_hint(hints[name])
+        if param.default is not inspect.Parameter.empty:
+            info["default"] = _serialize_default(param.default)
+        else:
+            info["required"] = True
+        params.append(info)
+    return params
+
+
+def _format_type_hint(hint) -> str | None:
+    """Format a type hint to a readable string."""
+    import ifcopenshell
+
+    if hint is None:
+        return None
+    if hint is type(None):
+        return "None"
+    # ifcopenshell.file params are passed as a file path string
+    if hint is ifcopenshell.file:
+        return "file_path"
+    origin = typing.get_origin(hint)
+    args = typing.get_args(hint)
+
+    # Union (including Optional)
+    if origin is typing.Union:
+        formatted = [_format_type_hint(a) for a in args]
+        # Optional[X] is Union[X, None] — render as "Optional[X]"
+        if len(formatted) == 2 and "None" in formatted:
+            inner = next(f for f in formatted if f != "None")
+            return f"Optional[{inner}]"
+        return " | ".join(formatted)
+
+    # Literal
+    if origin is typing.Literal:
+        values = ", ".join(repr(a) for a in args)
+        return f"Literal[{values}]"
+
+    # Generic types (list, dict, etc.)
+    if origin is not None:
+        origin_name = getattr(origin, "__name__", str(origin))
+        if args:
+            inner = ", ".join(_format_type_hint(a) for a in args)
+            return f"{origin_name}[{inner}]"
+        return origin_name
+
+    # Simple types
+    return getattr(hint, "__name__", str(hint))
+
+
+def _serialize_default(value):
+    """Serialize a default value to something JSON-friendly."""
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    return repr(value)
+
+
+def _parse_docstring_body(docstring: str) -> tuple[str, str]:
+    """Parse the summary and long description from a docstring."""
+    lines = docstring.strip().split("\n")
+    summary = lines[0].strip() if lines else ""
+    body_lines = []
+    in_body = False
+    for line in lines[1:]:
+        stripped = line.strip()
+        if stripped.startswith(":param") or stripped.startswith(":return"):
+            break
+        if stripped.startswith("Example"):
+            break
+        if not in_body and not stripped:
+            in_body = True
+            continue
+        if in_body:
+            body_lines.append(stripped)
+
+    long_description = " ".join(body_lines).strip()
+    # collapse multiple spaces
+    long_description = re.sub(r"\s+", " ", long_description)
+    return summary, long_description
+
+
+_FIELD_MARKER = re.compile(r":(?:param|returns?|rtype|type|raises?)\b")
+
+
+def _parse_param_docs(docstring: str) -> dict[str, str]:
+    """Extract :param name: description lines from a docstring."""
+    params = {}
+    current_param = None
+    current_lines = []
+    for line in docstring.split("\n"):
+        stripped = line.strip()
+        match = re.match(r":param\s+(\w+):\s*(.*)", stripped)
+        if match:
+            if current_param:
+                params[current_param] = " ".join(current_lines).strip()
+            current_param = match.group(1)
+            current_lines = [match.group(2)]
+        elif current_param and stripped and not _FIELD_MARKER.match(stripped):
+            current_lines.append(stripped)
+        elif _FIELD_MARKER.match(stripped) or (stripped == "" and current_param):
+            if current_param:
+                params[current_param] = " ".join(current_lines).strip()
+                current_param = None
+                current_lines = []
+    if current_param:
+        params[current_param] = " ".join(current_lines).strip()
+    # collapse whitespace
+    return {k: re.sub(r"\s+", " ", v) for k, v in params.items()}
+
+
+def _parse_return_doc(docstring: str) -> str:
+    """Extract :return: description from a docstring."""
+    lines = []
+    in_return = False
+    for line in docstring.split("\n"):
+        stripped = line.strip()
+        match = re.match(r":return:\s*(.*)", stripped)
+        if match:
+            in_return = True
+            lines = [match.group(1)]
+        elif in_return:
+            if _FIELD_MARKER.match(stripped) or stripped == "":
+                break
+            lines.append(stripped)
+    return re.sub(r"\s+", " ", " ".join(lines).strip())

src/ifcedit/ifcedit/quantify.py

@@ -0,0 +1,37 @@
+# This file was generated with the assistance of an AI coding tool.
+from __future__ import annotations
+
+from typing import Any
+
+import ifcopenshell
+
+AVAILABLE_RULES = ["IFC4QtoBaseQuantities", "IFC4X3QtoBaseQuantities"]
+
+
+def list_rules() -> list[dict[str, str]]:
+    """Return a list of available quantification rule names."""
+    return [{"name": name} for name in AVAILABLE_RULES]
+
+
+def run_quantify(model: ifcopenshell.file, rule: str, selector: str | None = None) -> dict[str, Any]:
+    """Run quantity take-off on the model using the named rule.
+
+    Modifies the model in-place by adding/updating IfcElementQuantity psets.
+    Returns a summary dict with ok, rule, and elements_quantified.
+    """
+    from ifc5d.qto import edit_qtos, quantify
+    from ifc5d.qto import rules as rule_sets
+
+    if rule not in rule_sets:
+        return {"ok": False, "error": f"Unknown rule: {rule}. Available: {list(rule_sets.keys())}"}
+
+    import ifcopenshell.util.selector
+
+    if selector:
+        elements = set(ifcopenshell.util.selector.filter_elements(model, selector))
+    else:
+        elements = set(model.by_type("IfcElement"))
+
+    results = quantify(model, elements, rule_sets[rule])
+    edit_qtos(model, results)
+    return {"ok": True, "rule": rule, "elements_quantified": len(results)}

src/ifcedit/ifcedit/run.py

@@ -0,0 +1,148 @@
+# This file was generated with the assistance of an AI coding tool.
+# IfcEdit - CLI wrapper for ifcopenshell.api mutation functions
+# Copyright (C) 2026 Bruno Postle <bruno@postle.net>
+#
+# This file is part of IfcEdit.
+#
+# IfcEdit is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcEdit is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcEdit.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import typing
+
+import ifcopenshell
+
+from ifcedit.coerce import coerce_value
+
+
+def _is_file_type(hint) -> bool:
+    """Check if a type hint refers to ifcopenshell.file (or Optional[ifcopenshell.file])."""
+    if hint is ifcopenshell.file:
+        return True
+    origin = typing.get_origin(hint)
+    args = typing.get_args(hint)
+    if origin is typing.Union and ifcopenshell.file in args:
+        return True
+    return False
+
+
+def run_api(
+    model: ifcopenshell.file,
+    module: str,
+    function: str,
+    raw_kwargs: dict[str, str],
+) -> dict:
+    """Execute an ifcopenshell.api function with CLI-provided string arguments.
+
+    Args:
+        model: The open IFC model.
+        module: API module name (e.g. "root").
+        function: Function name (e.g. "create_entity").
+        raw_kwargs: String keyword arguments from the CLI.
+
+    Returns:
+        A dict with {"ok": True, "result": ...} on success,
+        or {"ok": False, "error": "..."} on failure.
+    """
+    try:
+        fn = _import_function(module, function)
+    except (ImportError, AttributeError) as e:
+        return {"ok": False, "error": f"Cannot find function '{module}.{function}': {e}"}
+
+    try:
+        hints = typing.get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    sig = inspect.signature(fn)
+    coerced_kwargs = {}
+
+    # Pass 1: coerce ifcopenshell.file-typed params first (e.g. library= in append_asset).
+    # The opened file is then used as the lookup file for entity resolution in pass 2.
+    opened_files: list[ifcopenshell.file] = []
+    for name, value_str in raw_kwargs.items():
+        if name not in sig.parameters:
+            return {"ok": False, "error": f"Unknown parameter '{name}' for {module}.{function}"}
+        hint = hints.get(name)
+        if not _is_file_type(hint):
+            continue
+        try:
+            coerced = coerce_value(value_str, hint, model)
+            coerced_kwargs[name] = coerced
+            if isinstance(coerced, ifcopenshell.file):
+                opened_files.append(coerced)
+        except (ValueError, TypeError) as e:
+            return {"ok": False, "error": f"Cannot convert parameter '{name}': {e}"}
+
+    # Pass 2: coerce remaining params. Entity instance IDs are resolved from the opened
+    # library file (if any), since you are always appending from another file, never
+    # from the current model.
+    lookup_file = opened_files[0] if opened_files else None
+    for name, value_str in raw_kwargs.items():
+        if name in coerced_kwargs:
+            continue
+        if name not in sig.parameters:
+            return {"ok": False, "error": f"Unknown parameter '{name}' for {module}.{function}"}
+        hint = hints.get(name)
+        try:
+            coerced_kwargs[name] = coerce_value(value_str, hint, model, lookup_file=lookup_file)
+        except (ValueError, TypeError) as e:
+            return {"ok": False, "error": f"Cannot convert parameter '{name}': {e}"}
+
+    # Determine if the function takes 'file' as its first parameter
+    first_param = next(iter(sig.parameters), None)
+    try:
+        if first_param == "file":
+            result = fn(model, **coerced_kwargs)
+        else:
+            result = fn(**coerced_kwargs)
+    except Exception as e:
+        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+    return {"ok": True, "result": serialize_result(result)}
+
+
+def _import_function(module: str, function: str):
+    """Import and return the underlying function from ifcopenshell.api."""
+    fn_module = importlib.import_module(f"ifcopenshell.api.{module}.{function}")
+    fn = getattr(fn_module, function)
+    return fn
+
+
+def serialize_result(value) -> object:
+    """Serialize an API result to a JSON-friendly structure."""
+    if value is None:
+        return None
+    if isinstance(value, ifcopenshell.entity_instance):
+        return _serialize_entity(value)
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [serialize_result(item) for item in value]
+    if isinstance(value, dict):
+        return {str(k): serialize_result(v) for k, v in value.items()}
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    return str(value)
+
+
+def _serialize_entity(entity: ifcopenshell.entity_instance) -> dict:
+    """Serialize an entity instance to a summary dict."""
+    result = {
+        "id": entity.id(),
+        "type": entity.is_a(),
+    }
+    if hasattr(entity, "Name") and entity.Name:
+        result["name"] = entity.Name
+    return result

src/ifcedit/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ifcedit"
+version = "0.0.0"
+authors = [
+  { name="Bruno Postle", email="bruno@postle.net" },
+]
+description = "CLI wrapper for ifcopenshell.api IFC model mutation functions"
+readme = "README.md"
+keywords = ["IFC", "BIM", "API"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)",
+]
+dependencies = ["ifcopenshell", "ifc5d"]
+
+[project.scripts]
+ifcedit = "ifcedit.__main__:main"
+
+[project.urls]
+Homepage = "http://ifcopenshell.org"
+Documentation = "https://docs.ifcopenshell.org"
+Issues = "https://github.com/IfcOpenShell/IfcOpenShell/issues"
+
+[tool.setuptools.packages.find]
+include = ["ifcedit*"]
+exclude = ["test*"]
+
+[tool.ruff]
+extend = "../../pyproject.toml"

src/ifcedit/tests/__init__.py

@@ -0,0 +1 @@
+# This file was generated with the assistance of an AI coding tool.

src/ifcedit/tests/conftest.py

@@ -0,0 +1,63 @@
+# This file was generated with the assistance of an AI coding tool.
+import ifcopenshell
+import ifcopenshell.api.aggregate
+import ifcopenshell.api.material
+import ifcopenshell.api.owner.settings
+import ifcopenshell.api.project
+import ifcopenshell.api.pset
+import ifcopenshell.api.root
+import ifcopenshell.api.spatial
+import ifcopenshell.api.unit
+import pytest
+
+
+@pytest.fixture
+def model():
+    """Create an IFC4 model with a spatial hierarchy and a wall."""
+    f = ifcopenshell.api.project.create_file()
+    ifcopenshell.api.owner.settings.get_user = lambda ifc: (ifc.by_type("IfcPersonAndOrganization") or [None])[0]
+    ifcopenshell.api.owner.settings.get_application = lambda ifc: (ifc.by_type("IfcApplication") or [None])[0]
+
+    project = ifcopenshell.api.root.create_entity(f, ifc_class="IfcProject", name="TestProject")
+    ifcopenshell.api.unit.assign_unit(f)
+
+    site = ifcopenshell.api.root.create_entity(f, ifc_class="IfcSite", name="TestSite")
+    building = ifcopenshell.api.root.create_entity(f, ifc_class="IfcBuilding", name="TestBuilding")
+    storey = ifcopenshell.api.root.create_entity(f, ifc_class="IfcBuildingStorey", name="Ground Floor")
+
+    ifcopenshell.api.aggregate.assign_object(f, products=[site], relating_object=project)
+    ifcopenshell.api.aggregate.assign_object(f, products=[building], relating_object=site)
+    ifcopenshell.api.aggregate.assign_object(f, products=[storey], relating_object=building)
+
+    wall = ifcopenshell.api.root.create_entity(f, ifc_class="IfcWall", name="Wall001")
+    ifcopenshell.api.spatial.assign_container(f, products=[wall], relating_structure=storey)
+
+    return f
+
+
+@pytest.fixture
+def model_file(model, tmp_path):
+    """Write the model fixture to a temp file and return the path."""
+    path = tmp_path / "test.ifc"
+    model.write(str(path))
+    return str(path)
+
+
+@pytest.fixture
+def library():
+    """Create an IFC4 library with a single IfcWallType asset."""
+    lib = ifcopenshell.api.project.create_file()
+    ifcopenshell.api.owner.settings.get_user = lambda ifc: (ifc.by_type("IfcPersonAndOrganization") or [None])[0]
+    ifcopenshell.api.owner.settings.get_application = lambda ifc: (ifc.by_type("IfcApplication") or [None])[0]
+    ifcopenshell.api.root.create_entity(lib, ifc_class="IfcProject", name="TestLibrary")
+    ifcopenshell.api.unit.assign_unit(lib)
+    ifcopenshell.api.root.create_entity(lib, ifc_class="IfcWallType", name="WAL01")
+    return lib
+
+
+@pytest.fixture
+def library_file(library, tmp_path):
+    """Write the library fixture to a temp file and return the path."""
+    path = tmp_path / "library.ifc"
+    library.write(str(path))
+    return str(path)

src/ifcedit/tests/test_coerce.py

@@ -0,0 +1,158 @@
+# This file was generated with the assistance of an AI coding tool.
+import json
+from typing import Literal, Optional, Union
+
+import ifcopenshell
+import ifcopenshell.api.project
+import pytest
+
+from ifcedit.coerce import coerce_value
+
+
+class TestStringCoercion:
+    def test_plain_string(self):
+        assert coerce_value("hello", str) == "hello"
+
+    def test_empty_string(self):
+        assert coerce_value("", str) == ""
+
+
+class TestIntCoercion:
+    def test_plain_int(self):
+        assert coerce_value("42", int) == 42
+
+    def test_hash_prefix(self):
+        assert coerce_value("#42", int) == 42
+
+    def test_negative(self):
+        assert coerce_value("-5", int) == -5
+
+
+class TestFloatCoercion:
+    def test_plain_float(self):
+        assert coerce_value("3.14", float) == pytest.approx(3.14)
+
+    def test_integer_as_float(self):
+        assert coerce_value("5", float) == 5.0
+
+
+class TestBoolCoercion:
+    def test_true_values(self):
+        for val in ("true", "True", "TRUE", "1", "yes"):
+            assert coerce_value(val, bool) is True
+
+    def test_false_values(self):
+        for val in ("false", "False", "0", "no"):
+            assert coerce_value(val, bool) is False
+
+
+class TestOptionalCoercion:
+    def test_optional_string(self):
+        assert coerce_value("hello", Optional[str]) == "hello"
+
+    def test_optional_none(self):
+        assert coerce_value("none", Optional[str]) is None
+        assert coerce_value("None", Optional[str]) is None
+
+    def test_optional_int(self):
+        assert coerce_value("42", Optional[int]) == 42
+
+
+class TestUnionCoercion:
+    def test_union_str_int(self):
+        # Tries str first (or int first depending on order), both work
+        result = coerce_value("hello", Union[str, int])
+        assert result == "hello"
+
+    def test_union_int_none(self):
+        result = coerce_value("42", Union[int, None])
+        assert result == 42
+
+
+class TestLiteralCoercion:
+    def test_valid_literal(self):
+        assert coerce_value("IFC4", Literal["IFC2X3", "IFC4", "IFC4X3"]) == "IFC4"
+
+    def test_invalid_literal(self):
+        with pytest.raises(ValueError, match="not one of"):
+            coerce_value("IFC5", Literal["IFC2X3", "IFC4", "IFC4X3"])
+
+
+class TestDictCoercion:
+    def test_json_dict(self):
+        result = coerce_value('{"IsExternal": true, "FireRating": "2HR"}', dict[str, object])
+        assert result == {"IsExternal": True, "FireRating": "2HR"}
+
+    def test_mixed_float_int_list_coerced_to_float(self):
+        # [0.419, 0, 0.908] — JSON integer 0 mixed with floats must become float
+        # so ifcopenshell AGGREGATE OF DOUBLE attributes (e.g. DirectionRatios) don't reject the list
+        result = coerce_value('{"DirectionRatios": [0.419, 0, 0.908]}', dict[str, object])
+        assert result["DirectionRatios"] == pytest.approx([0.419, 0.0, 0.908])
+        assert all(isinstance(v, float) for v in result["DirectionRatios"])
+
+    def test_pure_int_list_not_coerced(self):
+        # All-integer lists (e.g. face indices) must stay as ints
+        result = coerce_value('{"CoordIndex": [0, 1, 2]}', dict[str, object])
+        assert result["CoordIndex"] == [0, 1, 2]
+        assert all(isinstance(v, int) for v in result["CoordIndex"])
+
+
+class TestListCoercion:
+    def test_comma_separated(self):
+        result = coerce_value("a,b,c", list[str])
+        assert result == ["a", "b", "c"]
+
+    def test_json_array(self):
+        result = coerce_value("[1, 2, 3]", list[int])
+        assert result == [1, 2, 3]
+
+
+class TestEntityCoercion:
+    def test_entity_by_id(self, model):
+        wall = model.by_type("IfcWall")[0]
+        result = coerce_value(str(wall.id()), ifcopenshell.entity_instance, model)
+        assert result == wall
+
+    def test_entity_with_hash(self, model):
+        wall = model.by_type("IfcWall")[0]
+        result = coerce_value(f"#{wall.id()}", ifcopenshell.entity_instance, model)
+        assert result == wall
+
+    def test_entity_not_found(self, model):
+        with pytest.raises(ValueError, match="not found"):
+            coerce_value("999999", ifcopenshell.entity_instance, model)
+
+    def test_entity_list(self, model):
+        wall = model.by_type("IfcWall")[0]
+        result = coerce_value(str(wall.id()), list[ifcopenshell.entity_instance], model)
+        assert len(result) == 1
+        assert result[0] == wall
+
+    def test_entity_list_multiple(self, model):
+        wall = model.by_type("IfcWall")[0]
+        storey = model.by_type("IfcBuildingStorey")[0]
+        result = coerce_value(f"{wall.id()},{storey.id()}", list[ifcopenshell.entity_instance], model)
+        assert len(result) == 2
+
+    def test_entity_no_model(self):
+        with pytest.raises(ValueError, match="without an IFC model"):
+            coerce_value("42", ifcopenshell.entity_instance, None)
+
+
+class TestFileCoercion:
+    def test_opens_file_from_path(self, model_file):
+        result = coerce_value(model_file, ifcopenshell.file)
+        assert isinstance(result, ifcopenshell.file)
+
+    def test_entity_from_lookup_file(self, model_file):
+        lib = ifcopenshell.open(model_file)
+        wall = lib.by_type("IfcWall")[0]
+        empty_model = ifcopenshell.api.project.create_file()
+        result = coerce_value(str(wall.id()), ifcopenshell.entity_instance, empty_model, lookup_file=lib)
+        assert result.id() == wall.id()
+        assert result.is_a("IfcWall")
+
+
+class TestFallback:
+    def test_no_type_hint(self):
+        assert coerce_value("hello", None) == "hello"

src/ifcedit/tests/test_discover.py

@@ -0,0 +1,104 @@
+# This file was generated with the assistance of an AI coding tool.
+from ifcedit.discover import function_docs, list_functions, list_modules
+
+
+class TestListModules:
+    def test_returns_list(self):
+        result = list_modules()
+        assert isinstance(result, list)
+        assert len(result) > 0
+
+    def test_module_structure(self):
+        result = list_modules()
+        for entry in result:
+            assert "module" in entry
+            assert "description" in entry
+            assert "functions" in entry
+            assert "count" in entry
+            assert isinstance(entry["functions"], list)
+            assert entry["count"] == len(entry["functions"])
+
+    def test_known_modules_present(self):
+        result = list_modules()
+        module_names = [m["module"] for m in result]
+        for expected in ("root", "spatial", "pset", "aggregate", "unit"):
+            assert expected in module_names
+
+    def test_root_module_has_functions(self):
+        result = list_modules()
+        root = next(m for m in result if m["module"] == "root")
+        assert "create_entity" in root["functions"]
+        assert root["count"] >= 3
+
+
+class TestListFunctions:
+    def test_root_functions(self):
+        result = list_functions("root")
+        assert isinstance(result, list)
+        names = [f["name"] for f in result]
+        assert "create_entity" in names
+
+    def test_function_structure(self):
+        result = list_functions("root")
+        for fn in result:
+            assert "name" in fn
+            assert "description" in fn
+            assert "params" in fn
+
+    def test_create_entity_params(self):
+        result = list_functions("root")
+        create = next(f for f in result if f["name"] == "create_entity")
+        param_names = [p["name"] for p in create["params"]]
+        assert "ifc_class" in param_names
+        assert "name" in param_names
+
+    def test_pset_functions(self):
+        result = list_functions("pset")
+        names = [f["name"] for f in result]
+        assert "add_pset" in names
+        assert "edit_pset" in names
+
+
+class TestFunctionDocs:
+    def test_create_entity_docs(self):
+        result = function_docs("root", "create_entity")
+        assert result["module"] == "root"
+        assert result["function"] == "create_entity"
+        assert result["description"]
+        assert isinstance(result["params"], list)
+        assert len(result["params"]) > 0
+
+    def test_params_have_types(self):
+        result = function_docs("root", "create_entity")
+        for param in result["params"]:
+            assert "name" in param
+            assert "type" in param
+
+    def test_params_have_descriptions(self):
+        result = function_docs("root", "create_entity")
+        ifc_class = next(p for p in result["params"] if p["name"] == "ifc_class")
+        assert "description" in ifc_class
+        assert len(ifc_class["description"]) > 0
+
+    def test_return_type(self):
+        result = function_docs("root", "create_entity")
+        assert "return_type" in result
+
+    def test_assign_container_docs(self):
+        result = function_docs("spatial", "assign_container")
+        assert result["module"] == "spatial"
+        param_names = [p["name"] for p in result["params"]]
+        assert "products" in param_names
+        assert "relating_structure" in param_names
+
+    def test_unknown_function_raises(self):
+        import pytest
+
+        with pytest.raises(ValueError, match="not found"):
+            function_docs("root", "nonexistent_function")
+
+    def test_edit_pset_docs(self):
+        result = function_docs("pset", "edit_pset")
+        param_names = [p["name"] for p in result["params"]]
+        assert "pset" in param_names
+        assert "properties" in param_names

src/ifcedit/tests/test_main.py

@@ -0,0 +1,100 @@
+# This file was generated with the assistance of an AI coding tool.
+import json
+import subprocess
+import sys
+
+import pytest
+
+
+def run_ifcedit(*args):
+    """Run ifcedit as a subprocess and return (stdout, stderr, returncode)."""
+    result = subprocess.run(
+        [sys.executable, "-m", "ifcedit", *args],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout, result.stderr, result.returncode
+
+
+class TestListCommand:
+    def test_list_all_modules(self):
+        stdout, stderr, rc = run_ifcedit("list")
+        assert rc == 0
+        data = json.loads(stdout)
+        assert isinstance(data, list)
+        module_names = [m["module"] for m in data]
+        assert "root" in module_names
+        assert "spatial" in module_names
+
+    def test_list_module_functions(self):
+        stdout, stderr, rc = run_ifcedit("list", "root")
+        assert rc == 0
+        data = json.loads(stdout)
+        assert isinstance(data, list)
+        names = [f["name"] for f in data]
+        assert "create_entity" in names
+
+    def test_list_text_format(self):
+        stdout, stderr, rc = run_ifcedit("--format", "text", "list")
+        assert rc == 0
+        assert "root" in stdout
+
+
+class TestDocsCommand:
+    def test_docs_create_entity(self):
+        stdout, stderr, rc = run_ifcedit("docs", "root.create_entity")
+        assert rc == 0
+        data = json.loads(stdout)
+        assert data["module"] == "root"
+        assert data["function"] == "create_entity"
+        assert "params" in data
+
+    def test_docs_invalid_path(self):
+        stdout, stderr, rc = run_ifcedit("docs", "invalid_path")
+        assert rc != 0
+        assert "module.function" in stderr
+
+    def test_docs_unknown_function(self):
+        stdout, stderr, rc = run_ifcedit("docs", "root.nonexistent")
+        assert rc != 0
+
+
+class TestRunCommand:
+    def test_create_entity(self, model_file):
+        stdout, stderr, rc = run_ifcedit(
+            "run", model_file, "root.create_entity", "--ifc_class", "IfcWall", "--name", "CLIWall"
+        )
+        assert rc == 0, f"stderr: {stderr}"
+        data = json.loads(stdout)
+        assert data["ok"] is True
+        assert data["result"]["type"] == "IfcWall"
+        assert data["result"]["name"] == "CLIWall"
+
+    def test_dry_run(self, model_file):
+        stdout, stderr, rc = run_ifcedit("run", model_file, "root.create_entity", "--dry-run", "--ifc_class", "IfcWall")
+        assert rc == 0
+        data = json.loads(stdout)
+        assert data["ok"] is True
+        assert data["dry_run"] is True
+
+    def test_output_to_different_file(self, model_file, tmp_path):
+        output = str(tmp_path / "output.ifc")
+        stdout, stderr, rc = run_ifcedit(
+            "run", model_file, "root.create_entity", "-o", output, "--ifc_class", "IfcSlab"
+        )
+        assert rc == 0, f"stderr: {stderr}"
+        data = json.loads(stdout)
+        assert data["ok"] is True
+
+        import os
+
+        assert os.path.exists(output)
+
+    def test_run_error_bad_function(self, model_file):
+        stdout, stderr, rc = run_ifcedit("run", model_file, "root.nonexistent")
+        assert rc != 0
+
+    def test_run_invalid_function_path(self, model_file):
+        stdout, stderr, rc = run_ifcedit("run", model_file, "invalid_path")
+        assert rc != 0
+        assert "module.function" in stderr

src/ifcedit/tests/test_quantify.py

@@ -0,0 +1,87 @@
+# This file was generated with the assistance of an AI coding tool.
+from __future__ import annotations
+
+import ifcopenshell
+import ifcopenshell.api.aggregate
+import ifcopenshell.api.owner.settings
+import ifcopenshell.api.project
+import ifcopenshell.api.root
+import ifcopenshell.api.spatial
+import ifcopenshell.api.unit
+import pytest
+
+from ifcedit.quantify import AVAILABLE_RULES, list_rules, run_quantify
+
+
+class TestListRules:
+    def test_returns_list(self):
+        result = list_rules()
+        assert isinstance(result, list)
+
+    def test_each_entry_has_name(self):
+        result = list_rules()
+        for entry in result:
+            assert "name" in entry
+
+    def test_ifc4_rule_present(self):
+        result = list_rules()
+        names = [r["name"] for r in result]
+        assert "IFC4QtoBaseQuantities" in names
+
+    def test_ifc4x3_rule_present(self):
+        result = list_rules()
+        names = [r["name"] for r in result]
+        assert "IFC4X3QtoBaseQuantities" in names
+
+
+@pytest.fixture
+def quantify_model():
+    """Create an IFC4 model with a wall element."""
+    f = ifcopenshell.api.project.create_file()
+    ifcopenshell.api.owner.settings.get_user = lambda ifc: (ifc.by_type("IfcPersonAndOrganization") or [None])[0]
+    ifcopenshell.api.owner.settings.get_application = lambda ifc: (ifc.by_type("IfcApplication") or [None])[0]
+
+    project = ifcopenshell.api.root.create_entity(f, ifc_class="IfcProject", name="TestProject")
+    ifcopenshell.api.unit.assign_unit(f)
+
+    site = ifcopenshell.api.root.create_entity(f, ifc_class="IfcSite", name="TestSite")
+    building = ifcopenshell.api.root.create_entity(f, ifc_class="IfcBuilding", name="TestBuilding")
+    storey = ifcopenshell.api.root.create_entity(f, ifc_class="IfcBuildingStorey", name="Ground Floor")
+
+    ifcopenshell.api.aggregate.assign_object(f, products=[site], relating_object=project)
+    ifcopenshell.api.aggregate.assign_object(f, products=[building], relating_object=site)
+    ifcopenshell.api.aggregate.assign_object(f, products=[storey], relating_object=building)
+
+    wall = ifcopenshell.api.root.create_entity(f, ifc_class="IfcWall", name="Wall001")
+    ifcopenshell.api.spatial.assign_container(f, products=[wall], relating_structure=storey)
+
+    return f
+
+
+class TestRunQuantify:
+    def test_returns_ok_true(self, quantify_model):
+        result = run_quantify(quantify_model, "IFC4QtoBaseQuantities")
+        assert result["ok"] is True
+
+    def test_returns_rule_name(self, quantify_model):
+        result = run_quantify(quantify_model, "IFC4QtoBaseQuantities")
+        assert result["rule"] == "IFC4QtoBaseQuantities"
+
+    def test_returns_elements_quantified(self, quantify_model):
+        result = run_quantify(quantify_model, "IFC4QtoBaseQuantities")
+        assert "elements_quantified" in result
+        assert isinstance(result["elements_quantified"], int)
+
+    def test_unknown_rule_returns_error(self, quantify_model):
+        result = run_quantify(quantify_model, "NonExistentRule")
+        assert result["ok"] is False
+        assert "error" in result
+
+    def test_selector_restricts_elements(self, quantify_model):
+        result = run_quantify(quantify_model, "IFC4QtoBaseQuantities", selector="IfcWall")
+        assert result["ok"] is True
+        assert result["rule"] == "IFC4QtoBaseQuantities"
+
+    def test_empty_selector_runs_on_all(self, quantify_model):
+        result = run_quantify(quantify_model, "IFC4QtoBaseQuantities", selector=None)
+        assert result["ok"] is True

src/ifcedit/tests/test_run.py

@@ -0,0 +1,97 @@
+# This file was generated with the assistance of an AI coding tool.
+import ifcopenshell
+import ifcopenshell.api.project
+import ifcopenshell.api.pset
+import ifcopenshell.api.root
+
+from ifcedit.run import run_api, serialize_result
+
+
+class TestRunApi:
+    def test_create_entity(self, model):
+        result = run_api(model, "root", "create_entity", {"ifc_class": "IfcWall", "name": "NewWall"})
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcWall"
+        assert result["result"]["name"] == "NewWall"
+        assert isinstance(result["result"]["id"], int)
+
+    def test_create_entity_default_class(self, model):
+        result = run_api(model, "root", "create_entity", {})
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcBuildingElementProxy"
+
+    def test_assign_container(self, model):
+        wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall", name="TestWall2")
+        storey = model.by_type("IfcBuildingStorey")[0]
+        result = run_api(
+            model,
+            "spatial",
+            "assign_container",
+            {"products": str(wall.id()), "relating_structure": str(storey.id())},
+        )
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcRelContainedInSpatialStructure"
+
+    def test_add_pset(self, model):
+        wall = model.by_type("IfcWall")[0]
+        result = run_api(model, "pset", "add_pset", {"product": str(wall.id()), "name": "Pset_WallCommon"})
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcPropertySet"
+
+    def test_unknown_function(self, model):
+        result = run_api(model, "root", "nonexistent", {})
+        assert result["ok"] is False
+        assert "Cannot find" in result["error"]
+
+    def test_unknown_parameter(self, model):
+        result = run_api(model, "root", "create_entity", {"bogus_param": "value"})
+        assert result["ok"] is False
+        assert "Unknown parameter" in result["error"]
+
+    def test_bad_entity_reference(self, model):
+        result = run_api(model, "pset", "add_pset", {"product": "999999", "name": "Pset_WallCommon"})
+        assert result["ok"] is False
+        assert "not found" in result["error"]
+
+
+class TestAppendAsset:
+    def test_append_asset_from_library(self, model, library_file):
+        lib = ifcopenshell.open(library_file)
+        wall_type = lib.by_type("IfcWallType")[0]
+        result = run_api(
+            model,
+            "project",
+            "append_asset",
+            {"library": library_file, "element": str(wall_type.id())},
+        )
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcWallType"
+        assert model.by_type("IfcWallType"), "wall type should have been appended to the model"
+
+
+class TestSerializeResult:
+    def test_none(self):
+        assert serialize_result(None) is None
+
+    def test_string(self):
+        assert serialize_result("hello") == "hello"
+
+    def test_int(self):
+        assert serialize_result(42) == 42
+
+    def test_entity(self, model):
+        wall = model.by_type("IfcWall")[0]
+        result = serialize_result(wall)
+        assert result["id"] == wall.id()
+        assert result["type"] == "IfcWall"
+        assert result["name"] == "Wall001"
+
+    def test_list(self, model):
+        walls = model.by_type("IfcWall")
+        result = serialize_result(walls)
+        assert isinstance(result, list)
+        assert all(isinstance(r, dict) for r in result)
+
+    def test_dict(self):
+        result = serialize_result({"key": "value"})
+        assert result == {"key": "value"}

src/ifcmcp/README.md

@@ -0,0 +1,401 @@
+<!-- This file was generated with the assistance of an AI coding tool. -->
+# ifcmcp
+
+An MCP (Model Context Protocol) server that wraps `ifcquery` and `ifcedit`,
+holding the IFC model in memory across tool calls for fast interactive editing
+sessions.
+
+## Installation
+
+```bash
+pip install ifcmcp
+```
+
+Requires `ifcopenshell`, `ifcquery`, and `ifcedit`. The `mcp` package is an optional dependency needed to run the server; install it with `pip install ifcmcp[mcp]` or add `mcp` separately.
+
+## Running the server
+
+```bash
+python3 -m ifcmcp
+```
+
+This starts the server on stdio transport, suitable for use with Claude Code
+or any MCP client.
+
+### Claude Code configuration
+
+Use the `claude mcp add` command:
+
+```bash
+claude mcp add --transport stdio ifc -- python3 -m ifcmcp
+```
+
+Or create a `.mcp.json` file in your project root:
+
+```json
+{
+  "mcpServers": {
+    "ifc": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["-m", "ifcmcp"]
+    }
+  }
+}
+```
+
+After adding the server, restart Claude Code for the tools to become available.
+Then load a model by asking Claude to use `ifc_load`:
+
+```
+load model.ifc using ifc_load
+```
+
+## Tools
+
+### Session
+
+#### ifc_new
+
+Create a new empty IFC model in memory, replacing any currently loaded model.
+
+```
+ifc_new()
+ifc_new(schema="IFC4X3")
+```
+
+Default schema is `IFC4`.
+
+#### ifc_load
+
+Open an IFC file into memory.
+
+```
+ifc_load(path="/path/to/model.ifc")
+-> "Loaded /path/to/model.ifc: schema IFC4, 1847 entities"
+```
+
+#### ifc_reset
+
+Unload the current model from memory, freeing all session state.
+
+```
+ifc_reset()
+```
+
+#### ifc_save
+
+Write the in-memory model to disk. Empty path overwrites the original file.
+
+```
+ifc_save()
+ifc_save(path="/path/to/output.ifc")
+```
+
+### Query tools
+
+All query tools require a model to be loaded first via `ifc_load`.
+
+#### ifc_summary
+
+Model overview: schema, entity counts, project info.
+
+```json
+{
+  "schema": "IFC4",
+  "total_entities": 1847,
+  "project": {"id": 1, "name": "Office Building"},
+  "types": {"IfcWall": 42, "IfcSlab": 12, "IfcWindow": 36}
+}
+```
+
+#### ifc_tree
+
+Full spatial hierarchy from IfcProject down through sites, buildings, storeys,
+and contained elements.
+
+```json
+{
+  "id": 1,
+  "type": "IfcProject",
+  "name": "Office Building",
+  "children": [
+    {
+      "id": 2,
+      "type": "IfcSite",
+      "children": [{"id": 3, "type": "IfcBuilding", "children": ["..."]}]
+    }
+  ]
+}
+```
+
+#### ifc_info
+
+Deep inspection of an entity by step ID: attributes, property sets, type,
+material, container, and 4x4 placement matrix.
+
+```
+ifc_info(element_id=10)
+```
+
+#### ifc_select
+
+Filter elements using ifcopenshell selector syntax.
+
+```
+ifc_select(query="IfcWall")
+ifc_select(query="IfcWindow")
+```
+
+Returns a sorted list of `{"id", "type", "name"}` references.
+
+#### ifc_relations
+
+Show all relationships for an element: hierarchy, children, type, groups,
+systems, material, connections.
+
+```
+ifc_relations(element_id=10)
+ifc_relations(element_id=10, traverse="up")
+```
+
+With `traverse="up"`, walks the hierarchy from element up to IfcProject.
+
+#### ifc_contexts
+
+List all geometric representation contexts and subcontexts in the loaded model.
+
+```
+ifc_contexts()
+```
+
+#### ifc_materials
+
+List all materials and material sets in the loaded model, with their assigned elements.
+
+```
+ifc_materials()
+```
+
+#### ifc_clash
+
+Check an element for geometric intersections and clearance violations.
+
+```
+ifc_clash(element_id=10)
+ifc_clash(element_id=10, clearance=0.5, scope="all")
+```
+
+Parameters:
+
+- `clearance` -- minimum clearance distance in meters (0.0 = no clearance check)
+- `tolerance` -- intersection tolerance in meters (default: 0.002)
+- `scope` -- `"storey"` or `"all"` (default: `"storey"`)
+
+#### ifc_validate
+
+Check the model for schema and constraint violations.
+
+```
+ifc_validate()
+ifc_validate(express_rules=True)
+```
+
+Returns `{"valid": true, "issues": []}` or `{"valid": false, "issues": [{"level": "ERROR", "message": "..."}]}`.
+
+#### ifc_schedule
+
+List all work schedules and their nested task trees.
+
+```
+ifc_schedule()
+ifc_schedule(max_depth=1)   # top-level phases only
+```
+
+`max_depth` limits subtask expansion. At the cutoff, `subtasks` is replaced
+with `{"truncated": true, "count": N}` so you know children exist without
+fetching them all. Omit for unlimited depth.
+
+#### ifc_cost
+
+List all cost schedules and their nested cost item trees.
+
+```
+ifc_cost()
+ifc_cost(max_depth=2)   # top two levels of the BoQ
+```
+
+`max_depth` limits cost item expansion, same truncation convention as
+`ifc_schedule`.
+
+#### ifc_schema
+
+Return IFC class documentation for any entity type, using the loaded model's
+schema version.
+
+```
+ifc_schema(entity_type="IfcWall")
+ifc_schema(entity_type="IfcBuildingStorey")
+```
+
+Returns description, predefined types, spec URL, and attribute descriptions.
+Returns `{"error": "Unknown entity: Foo"}` for unrecognised types.
+
+#### ifc_quantify
+
+Run quantity take-off (QTO) on the loaded model using an `ifc5d` rule.
+Computes physical measurements (volume, area, length, count, weight) and
+writes them back as `IfcElementQuantity` property sets. Modifies the model
+in-place -- call `ifc_save()` when done.
+
+```
+ifc_quantify(rule="IFC4QtoBaseQuantities")
+ifc_quantify(rule="IFC4QtoBaseQuantities", selector="IfcWall")
+```
+
+Available rules: `IFC4QtoBaseQuantities`, `IFC4X3QtoBaseQuantities`.
+
+`selector` is an optional ifcopenshell selector to restrict which elements
+are quantified (default: all `IfcElement`).
+
+Returns `{"ok": true, "rule": "...", "elements_quantified": 42}`.
+
+### Drawing and rendering tools
+
+#### ifc_plot
+
+Generate a 2D technical drawing of the loaded model and return it as an inline image.
+
+```
+ifc_plot()
+ifc_plot(selector="IfcWall", view="floorplan", scale=0.01, output_path="/tmp/plan.svg")
+ifc_plot(element_ids=[10, 11], view="floorplan")
+```
+
+Parameters:
+
+- `selector` -- ifcopenshell selector to restrict plotted elements
+- `element_ids` -- step IDs of elements to highlight; others are faded
+- `view` -- `"floorplan"` (default), `"elevation"`, `"section"`, or `"auto"`
+- `width_mm`, `height_mm` -- paper size in mm (default: 297 x 420)
+- `scale` -- model-to-paper ratio (default: 0.01 = 1:100)
+- `png_width`, `png_height` -- raster output size in pixels (default: 1024 x 1024)
+- `output_path` -- optional path to also save to disk (`.svg` for vector, otherwise PNG)
+
+Returns an inline PNG the LLM can inspect. Requires `ifcopenshell.draw`.
+
+#### ifc_render
+
+Render the loaded model to a 3D PNG image.
+
+```
+ifc_render()
+ifc_render(selector="IfcWall", view="iso", output_path="/tmp/model.png")
+ifc_render(element_ids=[10, 11], view="south")
+```
+
+Parameters:
+
+- `selector` -- ifcopenshell selector to restrict rendered elements
+- `element_ids` -- step IDs of elements to highlight; others are shown translucent
+- `view` -- `"iso"` (default), `"top"`, `"south"`, `"north"`, `"east"`, or `"west"`
+- `output_path` -- optional path to save the PNG to disk
+
+Returns an inline PNG. Requires `pyvista` and the IfcOpenShell C++ geometry bindings.
+
+### Shape builder tools
+
+#### ifc_shape_list
+
+List all available `ShapeBuilder` methods with brief descriptions.
+
+```
+ifc_shape_list()
+```
+
+#### ifc_shape_docs
+
+Show full documentation for a specific `ShapeBuilder` method.
+
+```
+ifc_shape_docs(method="extrude")
+ifc_shape_docs(method="create_ellipse")
+```
+
+#### ifc_shape
+
+Execute a `ShapeBuilder` method on the loaded model.
+
+```
+ifc_shape(method="extrude", params='{"profile": "42", "magnitude": 3.0}')
+```
+
+`params` is a JSON string; entity references are resolved by step ID (same coercion as `ifc_edit`).
+
+### Edit discovery tools
+
+#### ifc_list
+
+List all API modules, or functions within a specific module.
+
+```
+ifc_list()              # all modules
+ifc_list(module="root") # functions in the root module
+```
+
+#### ifc_docs
+
+Show full documentation for an API function including parameters, types,
+defaults, and descriptions.
+
+```
+ifc_docs(function_path="root.create_entity")
+```
+
+### Edit execution
+
+#### ifc_edit
+
+Execute an `ifcopenshell.api` mutation function. Parameters are passed as a
+JSON string with string values that get coerced by ifcedit's type system.
+
+```
+ifc_edit(
+    function_path="root.create_entity",
+    params='{"ifc_class": "IfcWall", "name": "My Wall"}'
+)
+```
+
+Returns `{"ok": true, "result": ...}` or `{"ok": false, "error": "..."}`.
+
+Does NOT auto-save -- call `ifc_save()` when ready to write changes to disk.
+
+**Parameter coercion:**
+
+| Type | JSON value | Python value |
+|------|------------|--------------|
+| `entity_instance` | `"42"` | resolved from model by step ID |
+| `list[entity_instance]` | `"5,6,7"` | list of resolved entities |
+| `dict` | `'{"key": "val"}'` | parsed JSON object |
+| `bool` | `"true"` | `True` |
+| `Optional[X]` | `"none"` | `None` |
+
+## Typical workflow
+
+1. **Load** a model: `ifc_load`
+2. **Inspect** with query tools: `ifc_summary`, `ifc_tree`, `ifc_select`, `ifc_info`, `ifc_relations`
+3. **Validate** if needed: `ifc_validate`
+4. **Browse schedules / costs**: `ifc_schedule`, `ifc_cost` (use `max_depth=1` first on large projects)
+5. **Look up IFC classes**: `ifc_schema`
+6. **Find** the right API function: `ifc_list`, `ifc_docs`
+7. **Edit** the model: `ifc_edit`
+8. **Quantify** elements: `ifc_quantify` (writes QTO psets in-place)
+9. **Verify** changes with query tools
+10. **Save** when satisfied: `ifc_save`
+
+The model stays in memory across all calls, so multi-step editing sessions
+are fast -- no file I/O between operations.
+
+## License
+
+LGPLv3+ -- see the IfcOpenShell project license.

src/ifcmcp/ifcmcp/__init__.py

@@ -0,0 +1,20 @@
+# This file was generated with the assistance of an AI coding tool.
+# IfcMCP - MCP server for IFC building models
+# Copyright (C) 2026 Bruno Postle <bruno@postle.net>
+#
+# This file is part of IfcMCP.
+#
+# IfcMCP is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcMCP is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcMCP.  If not, see <http://www.gnu.org/licenses/>.
+
+__version__ = version = "0.0.0"

src/ifcmcp/ifcmcp/__main__.py

@@ -0,0 +1,48 @@
+# This file was generated with the assistance of an AI coding tool.
+import argparse
+
+from ifcmcp import __version__
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="python3 -m ifcmcp",
+        description=(
+            "ifcmcp — MCP server for IFC building models.\n\n"
+            "Runs a Model Context Protocol server over stdio so that MCP clients\n"
+            "can query and edit IFC files without writing them to disk between\n"
+            "operations.\n\n"
+            "Add to .mcp.json to configure:\n"
+            '  {"mcpServers": {"ifc": {"type": "stdio", "command": "python3", "args": ["-m", "ifcmcp"]}}}'
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"ifcmcp {__version__}")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="MCP transport to use (default: stdio)",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        from mcp.server.fastmcp import FastMCP  # noqa: F401
+    except ImportError:
+        import sys
+        print(
+            "error: the 'mcp' package is required to run the server.\n"
+            "Install it with:  pip install mcp",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    from ifcmcp.server import build_server
+
+    server = build_server()
+    server.run(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()

src/ifcmcp/ifcmcp/core.py

@@ -0,0 +1,731 @@
+# This file was generated with the assistance of an AI coding tool.
+from __future__ import annotations
+
+# inside ifcmcp/core.py
+import json
+from collections.abc import Callable  # noqa: F401 — Callable used in helpers below
+from dataclasses import dataclass
+from typing import Any
+
+import ifcopenshell
+from ifcedit.discover import function_docs, list_functions, list_modules
+from ifcedit.quantify import run_quantify
+from ifcedit.run import run_api
+from ifcquery import clash as clash_mod
+from ifcquery import contexts as contexts_mod
+from ifcquery import cost as cost_mod
+from ifcquery import (
+    info,
+    relations,
+    schedule,
+    schema,
+    select,
+    summary,
+    tree,
+)
+from ifcquery import (
+    materials as materials_mod,
+)
+from ifcquery import (
+    plot as plot_mod,
+)
+from ifcquery import (
+    render as render_mod,
+)
+from ifcquery import validate as validate_mod
+
+
+def _jsonify(x: Any) -> Any:
+    """Convert IfcOpenShell objects / iterables into JSON-safe primitives."""
+    if x is None or isinstance(x, (str, int, float, bool)):
+        return x
+
+    # numpy arrays (and any array-like with tolist)
+    if hasattr(x, "tolist"):
+        return x.tolist()
+
+    # IfcOpenShell entity instances: normalize
+    if isinstance(x, ifcopenshell.entity_instance):
+        return {
+            "id": int(x.id()),
+            "type": x.is_a(),
+            "repr": str(x),
+            "name": getattr(x, "Name", None),
+        }
+
+    if isinstance(x, dict):
+        return {str(k): _jsonify(v) for k, v in x.items()}
+
+    if isinstance(x, (list, tuple, set)):
+        return [_jsonify(v) for v in x]
+
+    # Try JSON as-is, else fallback to string
+    try:
+        json.dumps(x)
+        return x
+    except Exception:
+        return str(x)
+
+
+# ---------------------------------------------------------------------------
+# Shape builder helpers
+# ---------------------------------------------------------------------------
+
+
+def _list_shape_methods() -> list[dict]:
+    """Introspect ShapeBuilder and return a summary of all public methods."""
+    import inspect
+
+    from ifcedit.discover import _extract_params
+    from ifcopenshell.util.shape_builder import ShapeBuilder
+
+    results = []
+    for name, fn in inspect.getmembers(ShapeBuilder, predicate=inspect.isfunction):
+        if name.startswith("_"):
+            continue
+        doc = fn.__doc__ or ""
+        description = doc.strip().split("\n")[0] if doc.strip() else ""
+        results.append({"method": name, "description": description, "params": _extract_params(fn)})
+    return results
+
+
+def _shape_method_docs(method_name: str) -> dict:
+    """Return full documentation for a single ShapeBuilder method."""
+    import typing
+
+    from ifcedit.discover import (
+        _extract_params,
+        _format_type_hint,
+        _parse_docstring_body,
+        _parse_param_docs,
+        _parse_return_doc,
+    )
+    from ifcopenshell.util.shape_builder import ShapeBuilder
+
+    if method_name.startswith("_"):
+        raise ValueError(f"ShapeBuilder has no method '{method_name}'")
+    fn = getattr(ShapeBuilder, method_name, None)
+    if fn is None:
+        raise ValueError(f"ShapeBuilder has no method '{method_name}'")
+
+    doc = fn.__doc__ or ""
+    description, long_description = _parse_docstring_body(doc)
+    params = _extract_params(fn)
+    for param in params:
+        param_desc = _parse_param_docs(doc)
+        if param["name"] in param_desc:
+            param["description"] = param_desc[param["name"]]
+
+    try:
+        hints = typing.get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    result: dict[str, Any] = {
+        "method": method_name,
+        "description": description,
+        "long_description": long_description,
+        "params": params,
+    }
+    return_type = _format_type_hint(hints.get("return"))
+    if return_type:
+        result["return_type"] = return_type
+    return_description = _parse_return_doc(doc)
+    if return_description:
+        result["return_description"] = return_description
+    return result
+
+
+def _coerce_shape_params(fn: Callable, raw_kwargs: dict, model: ifcopenshell.file) -> dict:
+    """Coerce JSON-parsed kwargs to proper Python types for a ShapeBuilder method."""
+    import inspect
+    import typing
+
+    sig = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    return {
+        key: _coerce_shape_value(value, hints.get(key), model)
+        for key, value in raw_kwargs.items()
+        if key in sig.parameters and key != "self"
+    }
+
+
+def _coerce_shape_value(value: Any, hint: Any, model: ifcopenshell.file) -> Any:
+    """Convert a single JSON-parsed value to the correct Python type."""
+    import typing
+
+    if hint is None or value is None:
+        return value
+
+    origin = typing.get_origin(hint)
+    args = typing.get_args(hint)
+
+    # Optional[X] / Union — try each non-None branch in order
+    if origin is typing.Union:
+        if value is None:
+            return None
+        for t in (a for a in args if a is not type(None)):
+            try:
+                return _coerce_shape_value(value, t, model)
+            except (ValueError, TypeError):
+                continue
+        return value
+
+    # entity_instance: resolve integer or "#N" string step ID
+    if hint is ifcopenshell.entity_instance or (
+        isinstance(hint, type) and issubclass(hint, ifcopenshell.entity_instance)
+    ):
+        entity_id = int(str(value).lstrip("#"))
+        entity = model.by_id(entity_id)
+        if entity is None:
+            raise ValueError(f"Entity #{entity_id} not found in model")
+        return entity
+
+    # Sequence[entity_instance]: resolve each element in the list
+    import collections.abc
+
+    if origin is not None and issubclass(origin, collections.abc.Sequence) and not isinstance(value, str):
+        if args and (
+            args[0] is ifcopenshell.entity_instance
+            or (isinstance(args[0], type) and issubclass(args[0], ifcopenshell.entity_instance))
+        ):
+            if isinstance(value, (list, tuple)):
+                return [_coerce_shape_value(v, args[0], model) for v in value]
+
+    # bool: JSON gives actual bools; also accept string representations
+    if hint is bool:
+        if isinstance(value, bool):
+            return value
+        return str(value).lower() in ("true", "1", "yes")
+
+    # Everything else (float, int, VectorType lists, dicts, Literals) passes through
+    return value
+
+
+class IfcSessionError(RuntimeError):
+    pass
+
+
+@dataclass
+class IfcSession:
+    """In-memory IFC session (no FastMCP dependency).
+
+    Designed to work in:
+      - FastMCP server (single global session)
+      - Embedded runtimes like Pyodide (one session per browser tab/worker)
+    """
+
+    model: ifcopenshell.file | None = None
+    model_path: str | None = None
+
+    # -----------------
+    # Session lifecycle
+    # -----------------
+    def _require_model(self) -> ifcopenshell.file:
+        if self.model is None:
+            raise IfcSessionError("No model loaded. Call ifc_load() or ifc_new() first.")
+        return self.model
+
+    def ifc_new(self, schema: str = "IFC4") -> dict[str, Any]:
+        """Create a new empty IFC model in memory."""
+        self.model = ifcopenshell.file(schema=schema)
+        self.model_path = None
+        return {"ok": True, "schema": self.model.schema, "entities": sum(1 for _ in self.model)}
+
+    def ifc_load(self, path: str) -> str:
+        """Open an IFC file into memory. Returns confirmation string."""
+        self.model = ifcopenshell.open(path)
+        self.model_path = path
+        count = sum(1 for _ in self.model)
+        return f"Loaded {path}: schema {self.model.schema}, {count} entities"
+
+    def ifc_save(self, path: str = "") -> str:
+        """Write the in-memory model to disk. Empty path overwrites the original file."""
+        model = self._require_model()
+        target = path if path else self.model_path
+        if not target:
+            raise IfcSessionError("No path specified and no original path available.")
+        model.write(target)
+        return f"Saved to {target}"
+
+    def ifc_reset(self) -> dict[str, Any]:
+        """Drop the in-memory model."""
+        self.model = None
+        self.model_path = None
+        return {"ok": True}
+
+    # -------------
+    # Query tools
+    # -------------
+    def ifc_summary(self) -> dict[str, Any]:
+        """Model overview: schema, entity counts, project info."""
+        return summary.summary(self._require_model())
+
+    def ifc_tree(self) -> dict[str, Any] | list[dict[str, Any]]:
+        """Full spatial hierarchy tree (Project -> Site -> Building -> Storeys -> Elements)."""
+        return tree.tree(self._require_model())
+
+    def ifc_info(self, element_id: int) -> dict[str, Any]:
+        """Deep inspection of an entity by step ID (attributes, psets, placement, type, material)."""
+        model = self._require_model()
+        element = model.by_id(element_id)
+        if element is None:
+            raise IfcSessionError(f"Element #{element_id} not found.")
+        return info.info(model, element)
+
+    def ifc_select(self, query: str) -> list[dict[str, Any]]:
+        """Filter elements using ifcopenshell selector syntax (e.g. 'IfcWall', 'IfcWindow')."""
+        return select.select(self._require_model(), query)
+
+    def ifc_relations(self, element_id: int, traverse: str = "") -> dict[str, Any] | list[dict[str, Any]]:
+        """Show relationships for an element. Set traverse='up' to walk hierarchy to IfcProject."""
+        model = self._require_model()
+        element = model.by_id(element_id)
+        if element is None:
+            raise IfcSessionError(f"Element #{element_id} not found.")
+        return relations.relations(model, element, traverse=traverse if traverse else None)
+
+    def ifc_clash(
+        self,
+        element_id: int,
+        clearance: float = 0.0,
+        tolerance: float = 0.002,
+        scope: str = "storey",
+    ) -> dict[str, Any]:
+        """Check element for geometric clashes. clearance=0.0 means no clearance check."""
+        model = self._require_model()
+        element = model.by_id(element_id)
+        if element is None:
+            raise IfcSessionError(f"Element #{element_id} not found.")
+        return clash_mod.clash(
+            model,
+            element,
+            clearance=clearance if clearance and clearance > 0.0 else None,
+            tolerance=tolerance,
+            scope=scope,
+        )
+
+    def ifc_contexts(self) -> list[dict[str, Any]]:
+        """List all geometric representation contexts and subcontexts with their step IDs."""
+        return contexts_mod.contexts(self._require_model())
+
+    def ifc_materials(self) -> list[dict[str, Any]]:
+        """List all materials and material sets (layers, constituents, profiles)."""
+        return materials_mod.materials(self._require_model())
+
+    # ------------------------
+    # Edit discovery + execute
+    # ------------------------
+    def ifc_list(self, module: str = "") -> list[dict]:
+        """List all API modules, or functions within a module. Empty module = all modules."""
+        return list_functions(module) if module else list_modules()
+
+    def ifc_docs(self, function_path: str) -> dict:
+        """Show full documentation for an API function. Input format: 'module.function'."""
+        module, function = function_path.split(".", 1)
+        return function_docs(module, function)
+
+    def ifc_edit(self, function_path: str, params: Any = "{}") -> dict:
+        """Execute an ifcopenshell.api mutation.
+
+        params may be:
+        - JSON string
+        - dict (from tool calling / JS)
+        - JsProxy (handled upstream in embedded.py)
+        """
+        model = self._require_model()
+        module, function = function_path.split(".", 1)
+
+        if isinstance(params, str):
+            raw_kwargs = json.loads(params) if params.strip() else {}
+        elif isinstance(params, dict):
+            raw_kwargs = params
+        else:
+            # e.g. list/None/etc
+            raw_kwargs = dict(params) if params is not None else {}
+
+        res = run_api(model, module, function, raw_kwargs)
+        return _jsonify(res)
+
+    # ------------------------
+    # Extended query + edit tools
+    # ------------------------
+    def ifc_validate(self, express_rules: bool = False) -> dict[str, Any]:
+        """Validate the loaded model. Returns {'valid': bool, 'issues': [...]}."""
+        return validate_mod.validate(self._require_model(), express_rules=express_rules)
+
+    def ifc_schedule(self, max_depth: int | None = None) -> list[dict[str, Any]]:
+        """List work schedules and nested tasks from the model.
+
+        max_depth limits subtask expansion (None = unlimited). At the cutoff,
+        subtasks is replaced with {"truncated": True, "count": N}.
+        """
+        return schedule.schedule(self._require_model(), max_depth=max_depth)
+
+    def ifc_cost(self, max_depth: int | None = None) -> list[dict[str, Any]]:
+        """List cost schedules and nested cost items from the model.
+
+        max_depth limits cost item expansion (None = unlimited). At the cutoff,
+        subitems is replaced with {"truncated": True, "count": N}.
+        """
+        return cost_mod.cost(self._require_model(), max_depth=max_depth)
+
+    def ifc_schema(self, entity_type: str) -> dict[str, Any]:
+        """Return IFC class documentation for entity_type using the model's schema version."""
+        return schema.schema(self._require_model(), entity_type)
+
+    def ifc_plot(
+        self,
+        selector: str = "",
+        element_ids: list[int] | None = None,
+        view: str = "floorplan",
+        width_mm: float = 297.0,
+        height_mm: float = 420.0,
+        scale: float = 1.0 / 100.0,
+        png_width: int = 1024,
+        png_height: int = 1024,
+        output_format: str = "png",
+    ) -> bytes:
+        """Generate a 2D technical drawing (floor plan, elevation, or section) and return image bytes.
+
+        Uses ifcopenshell.draw to produce SVG output which is rasterised to PNG via CairoSVG
+        when output_format is 'png'.
+
+        :param selector: ifcopenshell selector to restrict plotted elements
+            (e.g. ``'IfcWall'``). Omit to plot the whole model.
+        :param element_ids: Step IDs of elements to highlight. Other elements
+            are faded to 10% opacity so the subject stands out.
+        :param view: Drawing view — ``floorplan`` (default), ``elevation``,
+            ``section``, or ``auto``.
+        :param width_mm: Paper width in mm (default 297 = A4).
+        :param height_mm: Paper height in mm (default 420 = A4).
+        :param scale: Model-to-paper scale ratio (default 0.01 = 1:100).
+        :param png_width: Raster output width in pixels (default 1024).
+        :param png_height: Raster output height in pixels (default 1024).
+        :param output_format: ``'svg'`` or ``'png'`` (default ``'png'``).
+        :return: SVG or PNG bytes depending on output_format.
+        """
+        model = self._require_model()
+        return plot_mod.plot(
+            model,
+            output_format=output_format,
+            selector=selector if selector else None,
+            element_ids=element_ids,
+            view=view,
+            width_mm=width_mm,
+            height_mm=height_mm,
+            scale=scale,
+            png_width=png_width,
+            png_height=png_height,
+        )
+
+    def ifc_render(
+        self,
+        selector: str = "",
+        element_ids: list[int] | None = None,
+        view: str = "iso",
+    ) -> bytes:
+        """Render the loaded model to a PNG image and return raw bytes.
+
+        :param selector: ifcopenshell selector to restrict rendered elements
+            (e.g. ``'IfcWall'``). Omit to render the whole model.
+        :param element_ids: Step IDs of elements to highlight. Other elements
+            are rendered in translucent grey.
+        :param view: Camera angle: ``iso``, ``top``, ``south``, ``north``,
+            ``east``, or ``west``.
+        :return: PNG image as raw bytes.
+        """
+        model = self._require_model()
+        return render_mod.render(
+            model,
+            selector=selector if selector else None,
+            element_ids=element_ids,
+            view=view,
+        )
+
+    # ------------------------
+    # Shape builder tools
+    # ------------------------
+    def ifc_shape_list(self) -> list[dict]:
+        """List all ShapeBuilder geometry methods with one-line descriptions and parameter names."""
+        return _list_shape_methods()
+
+    def ifc_shape_docs(self, method: str) -> dict:
+        """Full documentation for a ShapeBuilder method: params, types, return value."""
+        return _shape_method_docs(method)
+
+    def ifc_shape(self, method: str, params: Any = "{}") -> dict:
+        """Call a ShapeBuilder method by name. Returns the created entity's step ID.
+
+        params is a JSON string of keyword arguments. Pass entity references as integer
+        step IDs; vectors as JSON arrays (e.g. [1.0, 0.0, 0.0]).
+        """
+        model = self._require_model()
+
+        from ifcopenshell.util.shape_builder import ShapeBuilder
+
+        if method.startswith("_"):
+            raise IfcSessionError(f"Private method '{method}' is not accessible")
+        fn = getattr(ShapeBuilder, method, None)
+        if fn is None:
+            return {"ok": False, "error": f"ShapeBuilder has no method '{method}'"}
+
+        if isinstance(params, str):
+            raw_kwargs = json.loads(params) if params.strip() else {}
+        elif isinstance(params, dict):
+            raw_kwargs = params
+        else:
+            raw_kwargs = {}
+
+        try:
+            coerced = _coerce_shape_params(fn, raw_kwargs, model)
+            result = fn(ShapeBuilder(model), **coerced)
+            return {"ok": True, "result": _jsonify(result)}
+        except Exception as e:
+            return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+    def ifc_quantify(self, rule: str, selector: str = "") -> dict[str, Any]:
+        """Run quantity take-off on the model using the named rule.
+
+        Modifies the model in-place; call ifc_save() after.
+        """
+        model = self._require_model()
+        return run_quantify(model, rule, selector=selector if selector else None)
+
+    # ------------------------
+    # Generic dispatcher + tool specs for LLMs
+    # ------------------------
+    def dispatch(self, name: str, args: dict[str, Any] | None = None) -> Any:
+        args = args or {}
+        fn = getattr(self, name, None)
+        if not callable(fn):
+            raise IfcSessionError(f"Unknown tool: {name}")
+        return _jsonify(fn(**args))
+
+    def openai_tools(self) -> list[dict[str, Any]]:
+        """Tool schemas in the OpenAI 'Responses API' format (type=function)."""
+        # Keep schemas tight so the model calls tools correctly.
+        return [
+            {
+                "type": "function",
+                "name": "ifc_new",
+                "description": "Create a new empty IFC model in memory.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"schema": {"type": "string", "description": "IFC schema, e.g. IFC4"}},
+                    "required": [],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_summary",
+                "description": "Get a concise overview of the loaded IFC model.",
+                "parameters": {"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+            },
+            {
+                "type": "function",
+                "name": "ifc_tree",
+                "description": "Get the full spatial hierarchy tree.",
+                "parameters": {"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+            },
+            {
+                "type": "function",
+                "name": "ifc_select",
+                "description": "Select elements using ifcopenshell selector syntax (e.g. 'IfcWall').",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"query": {"type": "string"}},
+                    "required": ["query"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_info",
+                "description": "Inspect an entity by STEP id.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"element_id": {"type": "integer"}},
+                    "required": ["element_id"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_relations",
+                "description": "Get relationships for an element. traverse='up' walks to IfcProject.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"element_id": {"type": "integer"}, "traverse": {"type": "string"}},
+                    "required": ["element_id"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_clash",
+                "description": "Run clash/clearance checks for an element.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "element_id": {"type": "integer"},
+                        "clearance": {"type": "number"},
+                        "tolerance": {"type": "number"},
+                        "scope": {"type": "string", "description": "storey or all"},
+                    },
+                    "required": ["element_id"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_contexts",
+                "description": "List all geometric representation contexts and subcontexts with their step IDs, context type, identifier, and target view. Use this to find the context ID required for geometry-creation API calls.",
+                "parameters": {"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+            },
+            {
+                "type": "function",
+                "name": "ifc_materials",
+                "description": "List all materials and material sets (IfcMaterial, IfcMaterialLayerSet, IfcMaterialConstituentSet, IfcMaterialProfileSet) with their layers, constituents, or profiles.",
+                "parameters": {"type": "object", "properties": {}, "required": [], "additionalProperties": False},
+            },
+            {
+                "type": "function",
+                "name": "ifc_list",
+                "description": "List ifcopenshell.api modules or functions within a module.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"module": {"type": "string"}},
+                    "required": [],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_docs",
+                "description": "Get documentation for an ifcopenshell.api function, 'module.function'.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"function_path": {"type": "string"}},
+                    "required": ["function_path"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_edit",
+                "description": "Execute an ifcopenshell.api mutation; params is a JSON string of stringly-typed kwargs.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"function_path": {"type": "string"}, "params": {"type": "string"}},
+                    "required": ["function_path"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_validate",
+                "description": "Validate the loaded model. Returns valid bool and list of issues.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "express_rules": {"type": "boolean", "description": "Also check EXPRESS rules (slower)"}
+                    },
+                    "required": [],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_schedule",
+                "description": "List work schedules and nested tasks. Use max_depth=1 for top-level phases only on large projects.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "max_depth": {
+                            "type": "integer",
+                            "description": "Max levels of subtask expansion (omit for unlimited)",
+                        }
+                    },
+                    "required": [],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_cost",
+                "description": "List cost schedules and nested cost items. Use max_depth=1 for top-level sections only on large BoQs.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "max_depth": {
+                            "type": "integer",
+                            "description": "Max levels of cost item expansion (omit for unlimited)",
+                        }
+                    },
+                    "required": [],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_schema",
+                "description": "Return IFC class documentation for an entity type.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"entity_type": {"type": "string", "description": "IFC entity type, e.g. IfcWall"}},
+                    "required": ["entity_type"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_quantify",
+                "description": "Run quantity take-off (QTO) on the model. Modifies model in-place; call ifc_save() after.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "rule": {"type": "string", "description": "QTO rule name, e.g. IFC4QtoBaseQuantities"},
+                        "selector": {
+                            "type": "string",
+                            "description": "ifcopenshell selector to restrict elements (default: all IfcElement)",
+                        },
+                    },
+                    "required": ["rule"],
+                    "additionalProperties": False,
+                },
+            },
+            {
+                "type": "function",
+                "name": "ifc_render",
+                "description": (
+                    "Render the loaded IFC model to a PNG image for visual inspection. "
+                    "Use selector to restrict which elements are rendered (e.g. a single storey). "
+                    "Use element_ids to highlight elements against a greyed-out background. "
+                    "Returns base64-encoded PNG bytes."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "selector": {"type": "string", "description": "ifcopenshell selector (default: whole model)"},
+                        "element_ids": {
+                            "type": "array",
+                            "items": {"type": "integer"},
+                            "description": "Step IDs of elements to highlight",
+                        },
+                        "view": {
+                            "type": "string",
+                            "enum": ["iso", "top", "south", "north", "east", "west"],
+                            "description": "Camera angle (default: iso)",
+                        },
+                    },
+                    "required": [],
+                    "additionalProperties": False,
+                },
+            },
+        ]

src/ifcmcp/ifcmcp/embedded.py

@@ -0,0 +1,60 @@
+# This file was generated with the assistance of an AI coding tool.
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ifcmcp.core import IfcSession
+
+session = IfcSession()
+
+# Optional imports only available under Pyodide
+try:
+    from pyodide.ffi import JsProxy, to_py  # type: ignore
+except Exception:  # pragma: no cover
+    JsProxy = None  # type: ignore
+    to_py = None  # type: ignore
+
+
+def _coerce_args(args: Any) -> dict[str, Any]:
+    """Convert JS objects / JsProxy / mappings into a real Python dict."""
+    if args is None:
+        return {}
+
+    # Pyodide: JS object arrives as JsProxy; convert recursively to Python.
+    if JsProxy is not None and isinstance(args, JsProxy):
+        # dict_converter=dict ensures JS object -> Python dict (not Map)
+        return to_py(args, dict_converter=dict)
+
+    # Already a Python dict
+    if isinstance(args, dict):
+        return args
+
+    # Any Mapping-like object
+    if isinstance(args, Mapping):
+        return dict(args)
+
+    # Last resort: try dict() coercion
+    try:
+        return dict(args)
+    except Exception as e:
+        raise TypeError(f"Tool args must be a mapping/dict; got {type(args)}") from e
+
+
+def tools_openai() -> list[dict[str, Any]]:
+    return session.openai_tools()
+
+
+def call_tool(name: str, args: Any = None) -> dict[str, Any]:
+    """
+    Non-throwing tool dispatcher.
+    Always returns: {"ok": bool, "data": ...} or {"ok": false, "error": "...", "error_type": "...", ...}
+    """
+    try:
+        py_args = _coerce_args(args)
+        data = session.dispatch(name, py_args)
+        return {"ok": True, "data": data}
+
+    except Exception as e:
+        # Keep it short; avoid full tracebacks in tool output unless debugging.
+        return {"ok": False, "error_type": type(e).__name__, "error": str(e)}

src/ifcmcp/ifcmcp/server.py

@@ -0,0 +1,231 @@
+# This file was generated with the assistance of an AI coding tool.
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from ifcmcp.core import IfcSession
+
+try:
+    from mcp.server.fastmcp import FastMCP  # type: ignore
+    from mcp.types import ImageContent  # type: ignore
+except Exception:  # pragma: no cover
+    FastMCP = None  # type: ignore
+    ImageContent = None  # type: ignore
+
+
+def build_server() -> Any:
+    """Create the FastMCP server if the dependency is available."""
+    if FastMCP is None:
+        raise ImportError(
+            "FastMCP is not installed. Install with: pip install ifcmcp[mcp] " "(or add 'mcp' to your environment)."
+        )
+
+    session = IfcSession()
+
+    server = FastMCP(
+        name="ifc-mcp",
+        instructions=(
+            "MCP server for querying and editing IFC building models. "
+            "Load a file first with ifc_load, then use query/edit tools. "
+            "Save changes with ifc_save."
+        ),
+    )
+
+    # ---- Lifecycle ----
+    @server.tool()
+    def ifc_new(schema: str = "IFC4") -> dict[str, Any]:
+        return session.ifc_new(schema=schema)
+
+    @server.tool()
+    def ifc_load(path: str) -> str:
+        return session.ifc_load(path)
+
+    @server.tool()
+    def ifc_save(path: str = "") -> str:
+        return session.ifc_save(path)
+
+    @server.tool()
+    def ifc_reset() -> dict[str, Any]:
+        return session.ifc_reset()
+
+    # ---- Query ----
+    @server.tool()
+    def ifc_summary() -> dict[str, Any]:
+        return session.ifc_summary()
+
+    @server.tool()
+    def ifc_tree() -> dict[str, Any] | list[dict[str, Any]]:
+        return session.ifc_tree()
+
+    @server.tool()
+    def ifc_info(element_id: int) -> dict[str, Any]:
+        return session.ifc_info(element_id)
+
+    @server.tool()
+    def ifc_select(query: str) -> list[dict[str, Any]]:
+        return session.ifc_select(query)
+
+    @server.tool()
+    def ifc_relations(element_id: int, traverse: str = "") -> dict[str, Any] | list[dict[str, Any]]:
+        return session.ifc_relations(element_id, traverse=traverse)
+
+    @server.tool()
+    def ifc_clash(
+        element_id: int,
+        clearance: float = 0.0,
+        tolerance: float = 0.002,
+        scope: str = "storey",
+    ) -> dict[str, Any]:
+        return session.ifc_clash(
+            element_id=element_id,
+            clearance=clearance,
+            tolerance=tolerance,
+            scope=scope,
+        )
+
+    @server.tool()
+    def ifc_contexts() -> list[dict[str, Any]]:
+        return session.ifc_contexts()
+
+    @server.tool()
+    def ifc_materials() -> list[dict[str, Any]]:
+        return session.ifc_materials()
+
+    # ---- Edit ----
+    @server.tool()
+    def ifc_list(module: str = "") -> list[dict]:
+        return session.ifc_list(module=module)
+
+    @server.tool()
+    def ifc_docs(function_path: str) -> dict:
+        return session.ifc_docs(function_path=function_path)
+
+    @server.tool()
+    def ifc_edit(function_path: str, params: str = "{}") -> dict:
+        return session.ifc_edit(function_path=function_path, params=params)
+
+    # ---- Extended query + edit ----
+    @server.tool()
+    def ifc_validate(express_rules: bool = False) -> dict[str, Any]:
+        return session.ifc_validate(express_rules=express_rules)
+
+    @server.tool()
+    def ifc_schedule(max_depth: int | None = None) -> list[dict[str, Any]]:
+        return session.ifc_schedule(max_depth=max_depth)
+
+    @server.tool()
+    def ifc_cost(max_depth: int | None = None) -> list[dict[str, Any]]:
+        return session.ifc_cost(max_depth=max_depth)
+
+    @server.tool()
+    def ifc_schema(entity_type: str) -> dict[str, Any]:
+        return session.ifc_schema(entity_type=entity_type)
+
+    @server.tool()
+    def ifc_quantify(rule: str, selector: str = "") -> dict[str, Any]:
+        return session.ifc_quantify(rule=rule, selector=selector)
+
+    # ---- Shape builder ----
+    @server.tool()
+    def ifc_shape_list() -> list[dict]:
+        return session.ifc_shape_list()
+
+    @server.tool()
+    def ifc_shape_docs(method: str) -> dict:
+        return session.ifc_shape_docs(method=method)
+
+    @server.tool()
+    def ifc_shape(method: str, params: str = "{}") -> dict:
+        return session.ifc_shape(method=method, params=params)
+
+    @server.tool(structured_output=False)
+    def ifc_plot(
+        selector: str = "",
+        element_ids: list[int] | None = None,
+        view: str = "floorplan",
+        width_mm: float = 297.0,
+        height_mm: float = 420.0,
+        scale: float = 1.0 / 100.0,
+        png_width: int = 1024,
+        png_height: int = 1024,
+        output_path: str = "",
+    ) -> list[ImageContent]:
+        """Generate a 2D technical drawing of the loaded IFC model.
+
+        Returns an inline PNG image (floor plan, elevation, or section) that the
+        LLM can inspect to understand the 2D layout of the model.  If
+        ``output_path`` is provided the drawing is also saved to disk — as SVG
+        when the path ends in ``.svg``, otherwise as PNG.
+
+        :param selector: ifcopenshell selector to restrict plotted elements
+            (e.g. ``'IfcWall'``). Omit to plot the whole model.
+        :param element_ids: Step IDs of elements to highlight. Other elements
+            are faded so the subject stands out.
+        :param view: Drawing view — ``floorplan`` (default), ``elevation``,
+            ``section``, or ``auto``.
+        :param width_mm: Paper width in mm (default 297 = A4 landscape width).
+        :param height_mm: Paper height in mm (default 420 = A4 landscape height).
+        :param scale: Model-to-paper scale ratio (default 0.01 = 1:100).
+        :param png_width: Raster output width in pixels (default 1024).
+        :param png_height: Raster output height in pixels (default 1024).
+        :param output_path: Optional file path to save the drawing to disk.
+        """
+        png_bytes = session.ifc_plot(
+            selector=selector,
+            element_ids=element_ids,
+            view=view,
+            width_mm=width_mm,
+            height_mm=height_mm,
+            scale=scale,
+            png_width=png_width,
+            png_height=png_height,
+            output_format="png",
+        )
+        if output_path:
+            if output_path.endswith(".svg"):
+                svg_bytes = session.ifc_plot(
+                    selector=selector,
+                    element_ids=element_ids,
+                    view=view,
+                    width_mm=width_mm,
+                    height_mm=height_mm,
+                    scale=scale,
+                    output_format="svg",
+                )
+                with open(output_path, "wb") as f:
+                    f.write(svg_bytes)
+            else:
+                with open(output_path, "wb") as f:
+                    f.write(png_bytes)
+        return [ImageContent(type="image", data=base64.b64encode(png_bytes).decode(), mimeType="image/png")]
+
+    @server.tool(structured_output=False)
+    def ifc_render(
+        selector: str = "",
+        element_ids: list[int] | None = None,
+        view: str = "iso",
+        output_path: str = "",
+    ) -> list[ImageContent]:
+        """Render the loaded IFC model to a PNG image.
+
+        Returns an inline image the LLM can inspect to understand the spatial
+        layout of the model or a specific element in context.  If
+        ``output_path`` is provided the PNG is also saved to that file path.
+
+        :param selector: ifcopenshell selector to restrict rendered elements
+            (e.g. ``'IfcWall'``, ``'IfcBuildingStorey[Name="0"]'``).
+            Omit to render the whole model.
+        :param element_ids: Step IDs of elements to highlight. Other elements
+            are rendered in translucent grey so the subject stands out.
+        :param view: Camera angle — ``iso`` (default), ``top``, ``south``,
+            ``north``, ``east``, or ``west``.
+        :param output_path: Optional file path to save the PNG to disk.
+        """
+        png_bytes = session.ifc_render(selector=selector, element_ids=element_ids, view=view)
+        if output_path:
+            with open(output_path, "wb") as f:
+                f.write(png_bytes)
+        return [ImageContent(type="image", data=base64.b64encode(png_bytes).decode(), mimeType="image/png")]
+
+    return server

src/ifcmcp/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ifcmcp"
+version = "0.0.0"
+authors = [
+  { name="Bruno Postle", email="bruno@postle.net" },
+]
+description = "MCP server for querying and editing IFC building models"
+readme = "README.md"
+keywords = ["IFC", "BIM", "MCP"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)",
+]
+dependencies = ["ifcopenshell", "ifcquery", "ifcedit"]
+
+[project.optional-dependencies]
+mcp = ["mcp"]
+
+[project.scripts]
+ifcmcp = "ifcmcp.__main__:main"
+
+[project.urls]
+Homepage = "http://ifcopenshell.org"
+Documentation = "https://docs.ifcopenshell.org"
+Issues = "https://github.com/IfcOpenShell/IfcOpenShell/issues"
+
+[tool.setuptools.packages.find]
+include = ["ifcmcp*"]
+exclude = ["test*"]
+
+[tool.ruff]
+extend = "../../pyproject.toml"

src/ifcmcp/tests/__init__.py

@@ -0,0 +1 @@
+# This file was generated with the assistance of an AI coding tool.

src/ifcmcp/tests/conftest.py

@@ -0,0 +1,59 @@
+# This file was generated with the assistance of an AI coding tool.
+import ifcopenshell
+import ifcopenshell.api.aggregate
+import ifcopenshell.api.owner.settings
+import ifcopenshell.api.project
+import ifcopenshell.api.root
+import ifcopenshell.api.spatial
+import ifcopenshell.api.unit
+import pytest
+
+from ifcmcp.core import IfcSession
+
+
+@pytest.fixture
+def session():
+    return IfcSession()
+
+
+@pytest.fixture
+def model():
+    """IFC4 model with a spatial hierarchy, a wall, and a slab."""
+    f = ifcopenshell.api.project.create_file()
+    ifcopenshell.api.owner.settings.get_user = lambda ifc: (ifc.by_type("IfcPersonAndOrganization") or [None])[0]
+    ifcopenshell.api.owner.settings.get_application = lambda ifc: (ifc.by_type("IfcApplication") or [None])[0]
+
+    project = ifcopenshell.api.root.create_entity(f, ifc_class="IfcProject", name="TestProject")
+    ifcopenshell.api.unit.assign_unit(f)
+
+    site = ifcopenshell.api.root.create_entity(f, ifc_class="IfcSite", name="TestSite")
+    building = ifcopenshell.api.root.create_entity(f, ifc_class="IfcBuilding", name="TestBuilding")
+    storey = ifcopenshell.api.root.create_entity(f, ifc_class="IfcBuildingStorey", name="Ground Floor")
+
+    ifcopenshell.api.aggregate.assign_object(f, products=[site], relating_object=project)
+    ifcopenshell.api.aggregate.assign_object(f, products=[building], relating_object=site)
+    ifcopenshell.api.aggregate.assign_object(f, products=[storey], relating_object=building)
+
+    wall = ifcopenshell.api.root.create_entity(f, ifc_class="IfcWall", name="Wall001")
+    ifcopenshell.api.spatial.assign_container(f, products=[wall], relating_structure=storey)
+
+    slab = ifcopenshell.api.root.create_entity(f, ifc_class="IfcSlab", name="Slab001")
+    ifcopenshell.api.spatial.assign_container(f, products=[slab], relating_structure=storey)
+
+    return f
+
+
+@pytest.fixture
+def model_file(model, tmp_path):
+    """Write the model fixture to a temp file and return the path."""
+    path = tmp_path / "test.ifc"
+    model.write(str(path))
+    return str(path)
+
+
+@pytest.fixture
+def loaded_session(model):
+    """An IfcSession with an in-memory model already loaded (no file path)."""
+    s = IfcSession()
+    s.model = model
+    return s

src/ifcmcp/tests/test_edit.py

@@ -0,0 +1,96 @@
+# This file was generated with the assistance of an AI coding tool.
+import json
+
+import ifcopenshell
+import pytest
+
+from ifcmcp.core import IfcSession, IfcSessionError
+
+
+class TestNoModel:
+    def test_edit_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_edit("root.create_entity")
+
+
+class TestList:
+    def test_list_all_modules(self, loaded_session):
+        result = loaded_session.ifc_list()
+        assert isinstance(result, list)
+        assert len(result) > 0
+        modules = [m["module"] for m in result]
+        assert "root" in modules
+        assert "spatial" in modules
+
+    def test_list_module_functions(self, loaded_session):
+        result = loaded_session.ifc_list(module="root")
+        assert isinstance(result, list)
+        names = [f["name"] for f in result]
+        assert "create_entity" in names
+
+    def test_list_empty_string_returns_modules(self, loaded_session):
+        result = loaded_session.ifc_list(module="")
+        assert isinstance(result, list)
+        assert any(m["module"] == "root" for m in result)
+
+
+class TestDocs:
+    def test_docs_create_entity(self, loaded_session):
+        result = loaded_session.ifc_docs("root.create_entity")
+        assert result["module"] == "root"
+        assert result["function"] == "create_entity"
+        assert "params" in result
+
+    def test_docs_bad_format(self, loaded_session):
+        with pytest.raises(ValueError):
+            loaded_session.ifc_docs("no_dot_here")
+
+
+class TestEdit:
+    def test_create_entity(self, loaded_session):
+        result = loaded_session.ifc_edit("root.create_entity", json.dumps({"ifc_class": "IfcWall", "name": "NewWall"}))
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcWall"
+        assert result["result"]["name"] == "NewWall"
+
+    def test_create_entity_default_params(self, loaded_session):
+        result = loaded_session.ifc_edit("root.create_entity", "{}")
+        assert result["ok"] is True
+
+    def test_unknown_function(self, loaded_session):
+        result = loaded_session.ifc_edit("root.nonexistent", "{}")
+        assert result["ok"] is False
+        assert "Cannot find" in result["error"]
+
+    def test_unknown_parameter(self, loaded_session):
+        result = loaded_session.ifc_edit("root.create_entity", json.dumps({"bogus": "value"}))
+        assert result["ok"] is False
+        assert "Unknown parameter" in result["error"]
+
+    def test_bad_json(self, loaded_session):
+        with pytest.raises(json.JSONDecodeError):
+            loaded_session.ifc_edit("root.create_entity", "not json")
+
+    def test_edit_does_not_save(self, loaded_session, tmp_path):
+        """Verify that ifc_edit mutates the in-memory model but does not write to disk."""
+        path = str(tmp_path / "test.ifc")
+        loaded_session.model.write(path)
+        loaded_session.model_path = path
+
+        before_count = sum(1 for _ in loaded_session.model)
+        loaded_session.ifc_edit("root.create_entity", json.dumps({"ifc_class": "IfcWall", "name": "Unsaved"}))
+        after_count = sum(1 for _ in loaded_session.model)
+        assert after_count == before_count + 1
+
+        on_disk = ifcopenshell.open(path)
+        disk_count = sum(1 for _ in on_disk)
+        assert disk_count == before_count
+
+    def test_assign_container(self, loaded_session):
+        wall = loaded_session.model.by_type("IfcWall")[0]
+        storey = loaded_session.model.by_type("IfcBuildingStorey")[0]
+        result = loaded_session.ifc_edit(
+            "spatial.assign_container",
+            json.dumps({"products": str(wall.id()), "relating_structure": str(storey.id())}),
+        )
+        assert result["ok"] is True

src/ifcmcp/tests/test_query.py

@@ -0,0 +1,113 @@
+# This file was generated with the assistance of an AI coding tool.
+import pytest
+
+from ifcmcp.core import IfcSessionError
+
+
+class TestNoModel:
+    """All query tools should fail when no model is loaded."""
+
+    def test_summary_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_summary()
+
+    def test_tree_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_tree()
+
+    def test_info_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_info(1)
+
+    def test_select_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_select("IfcWall")
+
+    def test_relations_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_relations(1)
+
+
+class TestSummary:
+    def test_schema(self, loaded_session):
+        result = loaded_session.ifc_summary()
+        assert result["schema"] == "IFC4"
+
+    def test_total_entities(self, loaded_session):
+        result = loaded_session.ifc_summary()
+        assert result["total_entities"] > 0
+
+    def test_project_name(self, loaded_session):
+        result = loaded_session.ifc_summary()
+        assert result["project"]["name"] == "TestProject"
+
+    def test_type_counts(self, loaded_session):
+        result = loaded_session.ifc_summary()
+        assert result["types"]["IfcWall"] == 1
+        assert result["types"]["IfcSlab"] == 1
+
+
+class TestTree:
+    def test_root_is_project(self, loaded_session):
+        result = loaded_session.ifc_tree()
+        assert result["type"] == "IfcProject"
+        assert result["name"] == "TestProject"
+
+    def test_hierarchy_depth(self, loaded_session):
+        result = loaded_session.ifc_tree()
+        site = result["children"][0]
+        assert site["type"] == "IfcSite"
+        building = site["children"][0]
+        assert building["type"] == "IfcBuilding"
+        storey = building["children"][0]
+        assert storey["type"] == "IfcBuildingStorey"
+
+
+class TestInfo:
+    def test_wall_info(self, loaded_session):
+        wall = loaded_session.model.by_type("IfcWall")[0]
+        result = loaded_session.ifc_info(wall.id())
+        assert result["id"] == wall.id()
+        assert result["type"] == "IfcWall"
+
+    def test_invalid_id(self, loaded_session):
+        with pytest.raises(Exception):
+            loaded_session.ifc_info(999999)
+
+
+class TestSelect:
+    def test_select_walls(self, loaded_session):
+        result = loaded_session.ifc_select("IfcWall")
+        assert len(result) == 1
+        assert result[0]["type"] == "IfcWall"
+        assert result[0]["name"] == "Wall001"
+
+    def test_select_slabs(self, loaded_session):
+        result = loaded_session.ifc_select("IfcSlab")
+        assert len(result) == 1
+        assert result[0]["name"] == "Slab001"
+
+    def test_select_no_match(self, loaded_session):
+        result = loaded_session.ifc_select("IfcWindow")
+        assert result == []
+
+
+class TestRelations:
+    def test_wall_relations(self, loaded_session):
+        wall = loaded_session.model.by_type("IfcWall")[0]
+        result = loaded_session.ifc_relations(wall.id())
+        assert result["id"] == wall.id()
+        assert result["type"] == "IfcWall"
+        assert "hierarchy" in result
+
+    def test_traverse_up(self, loaded_session):
+        wall = loaded_session.model.by_type("IfcWall")[0]
+        result = loaded_session.ifc_relations(wall.id(), traverse="up")
+        assert isinstance(result, list)
+        assert result[0]["type"] == "IfcWall"
+        assert result[-1]["type"] == "IfcProject"
+
+    def test_traverse_empty_string_means_no_traverse(self, loaded_session):
+        wall = loaded_session.model.by_type("IfcWall")[0]
+        result = loaded_session.ifc_relations(wall.id(), traverse="")
+        assert isinstance(result, dict)

src/ifcmcp/tests/test_server.py

@@ -0,0 +1,106 @@
+# This file was generated with the assistance of an AI coding tool.
+from unittest.mock import patch
+
+import pytest
+
+from ifcmcp.server import build_server
+
+
+class TestServerRegistration:
+    def test_server_name(self):
+        server = build_server()
+        assert server.name == "ifc-mcp"
+
+    def test_all_tools_registered(self):
+        server = build_server()
+        tools = [t.name for t in server._tool_manager.list_tools()]
+        expected = [
+            "ifc_load",
+            "ifc_save",
+            "ifc_summary",
+            "ifc_tree",
+            "ifc_info",
+            "ifc_select",
+            "ifc_relations",
+            "ifc_clash",
+            "ifc_list",
+            "ifc_docs",
+            "ifc_edit",
+        ]
+        for name in expected:
+            assert name in tools, f"Tool {name} not registered"
+
+
+@pytest.fixture
+def tool_fns():
+    """Return a dict of tool name → raw function from a freshly built server."""
+    server = build_server()
+    return {t.name: t.fn for t in server._tool_manager.list_tools()}
+
+
+PNG_FAKE = b"\x89PNG\r\n\x1a\nFAKE"
+SVG_FAKE = b"<svg>FAKE</svg>"
+
+
+class TestRenderOutputPath:
+    def test_no_output_path_no_file_written(self, tool_fns, tmp_path):
+        with patch("ifcmcp.core.IfcSession.ifc_render", return_value=PNG_FAKE):
+            tool_fns["ifc_render"](selector="", element_ids=None, view="iso", output_path="")
+        assert list(tmp_path.iterdir()) == []
+
+    def test_png_output_path_writes_file(self, tool_fns, tmp_path):
+        out = str(tmp_path / "render.png")
+        with patch("ifcmcp.core.IfcSession.ifc_render", return_value=PNG_FAKE):
+            tool_fns["ifc_render"](selector="", element_ids=None, view="iso", output_path=out)
+        assert open(out, "rb").read() == PNG_FAKE
+
+
+class TestPlotOutputPath:
+    def test_no_output_path_no_file_written(self, tool_fns, tmp_path):
+        with patch("ifcmcp.core.IfcSession.ifc_plot", return_value=PNG_FAKE):
+            tool_fns["ifc_plot"](
+                selector="",
+                element_ids=None,
+                view="floorplan",
+                width_mm=297.0,
+                height_mm=420.0,
+                scale=0.01,
+                png_width=1024,
+                png_height=1024,
+                output_path="",
+            )
+        assert list(tmp_path.iterdir()) == []
+
+    def test_png_output_path_writes_png(self, tool_fns, tmp_path):
+        out = str(tmp_path / "plot.png")
+        with patch("ifcmcp.core.IfcSession.ifc_plot", return_value=PNG_FAKE):
+            tool_fns["ifc_plot"](
+                selector="",
+                element_ids=None,
+                view="floorplan",
+                width_mm=297.0,
+                height_mm=420.0,
+                scale=0.01,
+                png_width=1024,
+                png_height=1024,
+                output_path=out,
+            )
+        assert open(out, "rb").read() == PNG_FAKE
+
+    def test_svg_output_path_writes_svg(self, tool_fns, tmp_path):
+        out = str(tmp_path / "plot.svg")
+        # ifc_plot is called twice: once with "png" for the inline image,
+        # once with "svg" for the file.
+        with patch("ifcmcp.core.IfcSession.ifc_plot", side_effect=[PNG_FAKE, SVG_FAKE]):
+            tool_fns["ifc_plot"](
+                selector="",
+                element_ids=None,
+                view="floorplan",
+                width_mm=297.0,
+                height_mm=420.0,
+                scale=0.01,
+                png_width=1024,
+                png_height=1024,
+                output_path=out,
+            )
+        assert open(out, "rb").read() == SVG_FAKE

src/ifcmcp/tests/test_session.py

@@ -0,0 +1,62 @@
+# This file was generated with the assistance of an AI coding tool.
+from unittest.mock import patch
+
+import ifcopenshell
+import pytest
+
+from ifcmcp.core import IfcSession, IfcSessionError
+
+
+class TestLoad:
+    def test_load_file(self, session, model_file):
+        result = session.ifc_load(model_file)
+        assert "IFC4" in result
+        assert session.model is not None
+        assert session.model_path == model_file
+
+    def test_load_sets_entity_count(self, session, model_file):
+        result = session.ifc_load(model_file)
+        assert "entities" in result
+
+    def test_load_nonexistent_file(self, session):
+        with pytest.raises(Exception):
+            session.ifc_load("/nonexistent/path/model.ifc")
+
+
+class TestSave:
+    def test_save_no_model(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_save()
+
+    def test_save_overwrites_original(self, session, model_file):
+        session.ifc_load(model_file)
+        result = session.ifc_save()
+        assert model_file in result
+
+    def test_save_to_new_path(self, session, model_file, tmp_path):
+        session.ifc_load(model_file)
+        new_path = str(tmp_path / "output.ifc")
+        result = session.ifc_save(new_path)
+        assert new_path in result
+        reloaded = ifcopenshell.open(new_path)
+        assert reloaded.schema == "IFC4"
+
+    def test_save_no_path_no_original(self, loaded_session):
+        with pytest.raises(IfcSessionError, match="No path specified"):
+            loaded_session.ifc_save()
+
+
+class TestIfcPlotOutputFormat:
+    """ifc_plot should pass output_format through to the underlying plot function."""
+
+    def test_default_output_format_is_png(self, loaded_session):
+        with patch("ifcmcp.core.plot_mod.plot", return_value=b"PNG_FAKE") as mock_plot:
+            loaded_session.ifc_plot()
+            mock_plot.assert_called_once()
+            assert mock_plot.call_args.kwargs["output_format"] == "png"
+
+    def test_svg_output_format(self, loaded_session):
+        with patch("ifcmcp.core.plot_mod.plot", return_value=b"SVG_FAKE") as mock_plot:
+            result = loaded_session.ifc_plot(output_format="svg")
+            assert result == b"SVG_FAKE"
+            assert mock_plot.call_args.kwargs["output_format"] == "svg"

src/ifcmcp/tests/test_shape.py

@@ -0,0 +1,141 @@
+# This file was generated with the assistance of an AI coding tool.
+import json
+
+import pytest
+
+from ifcmcp.core import IfcSessionError
+
+
+class TestShapeList:
+    def test_returns_list(self, loaded_session):
+        result = loaded_session.ifc_shape_list()
+        assert isinstance(result, list)
+        assert len(result) > 0
+
+    def test_has_expected_methods(self, loaded_session):
+        result = loaded_session.ifc_shape_list()
+        names = [m["method"] for m in result]
+        assert "polyline" in names
+        assert "rectangle" in names
+        assert "extrude" in names
+        assert "profile" in names
+        assert "get_representation" in names
+
+    def test_well_documented_methods_have_descriptions(self, loaded_session):
+        result = loaded_session.ifc_shape_list()
+        by_name = {m["method"]: m for m in result}
+        # These methods have detailed docstrings
+        for name in ("polyline", "extrude", "rectangle", "profile", "get_representation"):
+            assert by_name[name]["description"], f"'{name}' has no description"
+
+    def test_no_private_methods(self, loaded_session):
+        result = loaded_session.ifc_shape_list()
+        assert not any(m["method"].startswith("_") for m in result)
+
+    def test_does_not_require_model(self, session):
+        # ifc_shape_list is pure introspection — no model needed
+        result = session.ifc_shape_list()
+        assert isinstance(result, list)
+
+
+class TestShapeDocs:
+    def test_extrude_docs(self, loaded_session):
+        result = loaded_session.ifc_shape_docs("extrude")
+        assert result["method"] == "extrude"
+        assert result["description"]
+        assert "params" in result
+        param_names = [p["name"] for p in result["params"]]
+        assert "profile_or_curve" in param_names
+        assert "magnitude" in param_names
+
+    def test_has_return_type(self, loaded_session):
+        result = loaded_session.ifc_shape_docs("rectangle")
+        assert "return_type" in result
+
+    def test_has_param_descriptions(self, loaded_session):
+        result = loaded_session.ifc_shape_docs("polyline")
+        params_with_desc = [p for p in result["params"] if "description" in p]
+        assert len(params_with_desc) > 0
+
+    def test_unknown_method(self, loaded_session):
+        with pytest.raises(ValueError, match="no method"):
+            loaded_session.ifc_shape_docs("nonexistent_method")
+
+    def test_private_method_rejected(self, loaded_session):
+        with pytest.raises(ValueError):
+            loaded_session.ifc_shape_docs("__init__")
+
+    def test_does_not_require_model(self, session):
+        result = session.ifc_shape_docs("circle")
+        assert result["method"] == "circle"
+
+
+class TestShapeExecute:
+    def test_rectangle(self, loaded_session):
+        result = loaded_session.ifc_shape("rectangle", json.dumps({"size": [4.0, 0.2]}))
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcIndexedPolyCurve"
+
+    def test_circle(self, loaded_session):
+        result = loaded_session.ifc_shape("circle", json.dumps({"center": [0.0, 0.0], "radius": 0.5}))
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcCircle"
+
+    def test_extrude_chained_from_rectangle(self, loaded_session):
+        rect = loaded_session.ifc_shape("rectangle", json.dumps({"size": [4.0, 0.2]}))
+        rect_id = rect["result"]["id"]
+        result = loaded_session.ifc_shape("extrude", json.dumps({"profile_or_curve": rect_id, "magnitude": 3.0}))
+        assert result["ok"] is True
+        assert result["result"]["type"] == "IfcExtrudedAreaSolid"
+
+    def test_entity_id_as_integer(self, loaded_session):
+        """Entity IDs should be accepted as plain integers (from JSON)."""
+        rect = loaded_session.ifc_shape("rectangle", json.dumps({"size": [1.0, 1.0]}))
+        rect_id = rect["result"]["id"]
+        # Pass as int, not string
+        result = loaded_session.ifc_shape("extrude", json.dumps({"profile_or_curve": rect_id, "magnitude": 1.0}))
+        assert result["ok"] is True
+
+    def test_rotate_2d_point_returns_list(self, loaded_session):
+        """Methods returning numpy arrays should give back plain lists."""
+        result = loaded_session.ifc_shape(
+            "rotate_2d_point", json.dumps({"point_2d": [1.0, 0.0], "angle": 90.0, "counter_clockwise": True})
+        )
+        assert result["ok"] is True
+        assert isinstance(result["result"], list)
+        assert len(result["result"]) == 2
+
+    def test_set_polyline_coords_returns_none(self, loaded_session):
+        """In-place methods that return None should give ok=True, result=None."""
+        rect = loaded_session.ifc_shape("rectangle", json.dumps({"size": [2.0, 2.0]}))
+        rect_id = rect["result"]["id"]
+        result = loaded_session.ifc_shape(
+            "set_polyline_coords",
+            json.dumps({"polyline": rect_id, "coords": [[0.0, 0.0], [3.0, 0.0], [3.0, 3.0], [0.0, 3.0]]}),
+        )
+        assert result["ok"] is True
+        assert result["result"] is None
+
+    def test_unknown_method(self, loaded_session):
+        result = loaded_session.ifc_shape("nonexistent_method", "{}")
+        assert result["ok"] is False
+        assert "error" in result
+
+    def test_private_method_rejected(self, loaded_session):
+        with pytest.raises(IfcSessionError):
+            loaded_session.ifc_shape("__init__", "{}")
+
+    def test_no_model_raises(self, session):
+        with pytest.raises(IfcSessionError, match="No model loaded"):
+            session.ifc_shape("rectangle", "{}")
+
+    def test_params_as_dict(self, loaded_session):
+        """params can be passed as a dict (not just a JSON string)."""
+        result = loaded_session.ifc_shape("rectangle", {"size": [2.0, 1.0]})
+        assert result["ok"] is True
+
+    def test_error_on_bad_params(self, loaded_session):
+        """Bad parameters should give ok=False with an error message."""
+        result = loaded_session.ifc_shape("extrude", json.dumps({"profile_or_curve": 999999, "magnitude": 1.0}))
+        assert result["ok"] is False
+        assert "error" in result

src/ifcopenshell-python/docs/ifcopenshell-python/geometry_creation.rst

@@ -775,3 +775,52 @@ responsibility to make sure the geometry is correct.
 
     # Assign our new body geometry back to our beam
     ifcopenshell.api.geometry.assign_representation(model, product=beam, representation=representation)
+
+Moving assemblies
+-----------------
+
+When moving an assembly and you want all children to follow, pass
+``should_transform_children=True``. The default (``False``) rewrites each
+child's local placement to preserve its world position, so the parent moves
+but the children stay where they are.
+
+.. code-block:: python
+
+    matrix = numpy.eye(4)
+    matrix[:,3][0:3] = (0, 0, 6)
+
+    # Move the assembly; children travel with it.
+    ifcopenshell.api.geometry.edit_object_placement(model,
+        product=assembly, matrix=matrix, is_si=True,
+        should_transform_children=True)
+
+Clipping normals convention
+---------------------------
+
+The ``normal`` passed to :func:`geometry.clip_solid`,
+:func:`geometry.clip_solid_bounded`, and the ``clippings`` parameter of
+:func:`geometry.add_wall_representation` points toward the **removed**
+material (the discarded side), not toward the kept material.
+
+.. code-block:: python
+
+    # Clip the top of a wall to a lean-to slope.
+    # normal points upward into the wedge that will be removed.
+    bcr = ifcopenshell.api.geometry.clip_solid(model,
+        item=extrusion,
+        location=[0.0, 0.0, 3.26],
+        normal=[0.419, 0.0, 0.908])
+    shape_representation.RepresentationType = "Clipping"
+
+Opening lifecycle
+-----------------
+
+``feature.remove_feature`` permanently deletes the feature entity from the
+model. Any fillings (windows, doors) that occupied the opening become
+orphaned and must be separately removed via ``root.remove_product``.
+
+.. code-block:: python
+
+    # Remove a window and its opening from a wall.
+    ifcopenshell.api.root.remove_product(model, product=window)
+    ifcopenshell.api.feature.remove_feature(model, feature=opening)

src/ifcopenshell-python/ifcopenshell/api/context/remove_context.py

@@ -51,8 +51,10 @@ def remove_context(file: ifcopenshell.file, context: ifcopenshell.entity_instanc
         new = context.ParentContext
         for inverse in file.get_inverse(context):
             if inverse.is_a("IfcCoordinateOperation"):
+                # Trick to make sure the coordinate operation is not referenced
+                # by a context so we can delete it safely
                 inverse.SourceCRS = inverse.TargetCRS
-                ifcopenshell.util.element.remove_deep(file, inverse)
+                ifcopenshell.util.element.remove_deep2(file, inverse)
             else:
                 ifcopenshell.util.element.replace_attribute(inverse, context, new)
         file.remove(context)

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_value.py

@@ -59,6 +59,6 @@ def edit_cost_value(
                     value["ValueComponent"],
                 )
                 value = file.create_entity("IfcMeasureWithUnit", value_component, value["UnitComponent"])
-            if old_unit_basis and file.get_total_inverses(old_unit_basis) == 0:
-                ifcopenshell.util.element.remove_deep(file, old_unit_basis)
+            if old_unit_basis:
+                ifcopenshell.util.element.remove_deep2(file, old_unit_basis)
         setattr(cost_value, name, value)

src/ifcopenshell-python/ifcopenshell/api/feature/remove_feature.py

@@ -22,11 +22,13 @@ import ifcopenshell.util.element
 
 
 def remove_feature(file: ifcopenshell.file, feature: ifcopenshell.entity_instance) -> None:
-    """Remove a feature
+    """Permanently delete a feature element and its void or projection relationship.
 
-    Fillings are retained as orphans. Featured elements remain. Features
-    cannot exist by themselves, so not only is the relationship removed, the
-    feature is also removed.
+    The feature entity (e.g. IfcOpeningElement) is removed from the model
+    along with its IfcRelVoidsElement or IfcRelProjectsElement relationship.
+    The host element (wall, slab, etc.) is unaffected. Any fillings (windows,
+    doors) that occupied the opening become orphaned and must be separately
+    deleted via root.remove_product.
 
     :param feature: The IfcFeatureElement to remove.
 

src/ifcopenshell-python/ifcopenshell/api/geometry/__init__.py

@@ -26,6 +26,8 @@ geometry extrusions).
 from .. import wrap_usecases
 from .add_axis_representation import add_axis_representation
 from .add_boolean import add_boolean
+from .clip_solid import clip_solid
+from .clip_solid_bounded import clip_solid_bounded
 from .add_door_representation import add_door_representation
 from .add_footprint_representation import add_footprint_representation
 from .add_mesh_representation import add_mesh_representation
@@ -50,6 +52,7 @@ from .disconnect_element import disconnect_element
 from .disconnect_path import disconnect_path
 from .edit_object_placement import edit_object_placement
 from .map_representation import map_representation
+from .copy_representation import copy_representation
 from .regenerate_wall_representation import regenerate_wall_representation
 from .remove_boolean import remove_boolean
 from .remove_representation import remove_representation
@@ -61,6 +64,9 @@ wrap_usecases(__path__, __name__)
 __all__ = [
     "add_axis_representation",
     "add_boolean",
+    "clip_solid",
+    "clip_solid_bounded",
+    "copy_representation",
     "add_door_representation",
     "add_footprint_representation",
     "add_mesh_representation",

src/ifcopenshell-python/ifcopenshell/api/geometry/add_boolean.py

@@ -31,17 +31,6 @@ def add_boolean(
 ) -> list[ifcopenshell.entity_instance]:
     """Adds a boolean operation to two or more representation items
 
-    If an IfcBooleanOperand is part of the top level items in an
-    IfcShapeRepresentation, it will be removed from that level whilst being
-    added to the IfcBooleanResult. This is because it is generally intuitive
-    that an item is either participating in a boolean operation, or being an
-    item in its own right, but not both.
-
-    However, if an IfcBooleanOperand is part of another boolean operation
-    already, it will not be removed from the existing operation. A new
-    operation will be created, and therefore it will participate in two
-    operations.
-
     This function protects against recursive booleans.
 
     After a boolean operation is made, since the items of
@@ -101,9 +90,6 @@ def add_boolean(
 
     booleans = []
     for second_item in second_items:
-        for inverse in file.get_inverse(second_item):
-            if inverse.is_a("IfcShapeRepresentation"):
-                inverse.Items = list(set(inverse.Items) - {second_item})
         if first.is_a("IfcTesselatedFaceSet"):
             first.Closed = True  # For now, trust the user to do the right thing.
         if second_item.is_a("IfcTesselatedFaceSet"):

src/ifcopenshell-python/ifcopenshell/api/geometry/add_wall_representation.py

@@ -47,7 +47,9 @@ def add_wall_representation(
     :param thickness: The thickness of the wall in meters.
     :param x_angle: The slope angle along the wall's X-axis, in radians.
     :param clippings: List of clipping definitions. Clippings can be `Clipping` objects
-        or dictionaries of arguments for `Clipping.parse`.
+        or dictionaries of arguments for `Clipping.parse`. Each clipping has a
+        ``normal`` that points toward the removed material (the discarded side),
+        not toward the kept material; see :func:`clip_solid` for details.
     :param booleans: List of any existing IfcBooleanResults.
     :return: IfcShapeRepresentation.
     """

src/ifcopenshell-python/ifcopenshell/api/geometry/clip_solid.py

@@ -0,0 +1,86 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2026 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import json
+from typing import Optional, Sequence
+
+import ifcopenshell.api.pset
+import ifcopenshell.util.element
+import ifcopenshell.util.unit
+from ifcopenshell.util.data import Clipping
+
+
+def clip_solid(
+    file: ifcopenshell.file,
+    item: ifcopenshell.entity_instance,
+    location: Sequence[float],
+    normal: Sequence[float],
+    element: Optional[ifcopenshell.entity_instance] = None,
+) -> ifcopenshell.entity_instance:
+    """Clip a solid with a half-space plane, returning an IfcBooleanClippingResult.
+
+    Convenience wrapper around :class:`ifcopenshell.util.data.Clipping` for
+    use with any solid.  This is the same convention used by the ``clippings``
+    parameter of :func:`add_wall_representation`.
+
+    .. warning::
+
+        The ``normal`` points toward the **removed** material (the discarded
+        side), not toward the kept material.  For a slope clip the normal
+        points upward into the removed wedge above the slope line.  For a
+        side mitre the normal points outward away from the wall body.
+
+    After clipping, set the parent ``IfcShapeRepresentation``
+    ``RepresentationType`` to ``"Clipping"``.
+
+    Example — trim an extruded solid to a lean-to slope (removed material is
+    above the slope)::
+
+        bcr = ifcopenshell.api.run(
+            "geometry.clip_solid", model,
+            item=extrusion,
+            location=[0.0, 0.0, 3.26],
+            normal=[0.419, 0.0, 0.908],  # points UP toward removed material
+        )
+
+    :param item: The solid to clip (``IfcSweptAreaSolid``, ``IfcSweptDiskSolid``,
+        or ``IfcBooleanClippingResult``).
+    :param location: A point on the clipping plane in the representation's
+        local coordinate system.
+    :param normal: Plane normal pointing toward the material to be removed
+        (see warning above).
+    :param element: If provided, the resulting ``IfcBooleanClippingResult`` is
+        registered in the element's ``BBIM_Boolean`` property set so that
+        :func:`regenerate_wall_representation` preserves it during regeneration.
+    :return: The resulting ``IfcBooleanClippingResult``.
+    """
+    unit_scale = ifcopenshell.util.unit.calculate_unit_scale(file)
+    clipping = Clipping(location=tuple(location), normal=tuple(normal))
+    result = clipping.apply(file, item, unit_scale)
+    if element is not None:
+        pset_data = ifcopenshell.util.element.get_pset(element, "BBIM_Boolean")
+        if pset_data:
+            pset = file.by_id(pset_data["id"])
+            data = list(set(json.loads(pset_data["Data"]) + [result.id()]))
+        else:
+            pset = ifcopenshell.api.pset.add_pset(file, product=element, name="BBIM_Boolean")
+            data = [result.id()]
+        ifcopenshell.api.pset.edit_pset(file, pset=pset, properties={"Data": json.dumps(data)})
+    return result

src/ifcopenshell-python/ifcopenshell/api/geometry/clip_solid_bounded.py

@@ -0,0 +1,116 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2026 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+import json
+from typing import Optional, Sequence
+
+import numpy as np
+
+import ifcopenshell.api.pset
+import ifcopenshell.util.element
+import ifcopenshell.util.unit
+from ifcopenshell.util.shape_builder import ShapeBuilder
+
+
+def clip_solid_bounded(
+    file: ifcopenshell.file,
+    item: ifcopenshell.entity_instance,
+    location: Sequence[float],
+    normal: Sequence[float],
+    boundary_points: Sequence[Sequence[float]],
+    boundary_position: Sequence[float] = (0.0, 0.0, 0.0),
+    element: Optional[ifcopenshell.entity_instance] = None,
+) -> ifcopenshell.entity_instance:
+    """Clip a solid with a polygonally bounded half-space, returning an IfcBooleanClippingResult.
+
+    Like :func:`clip_solid`, but the boolean subtraction is restricted to the
+    region enclosed by ``boundary_points`` rather than extending across the
+    entire half-space.  The clipping plane is still infinite, but material is
+    only removed within the extruded footprint of the polygon.
+
+    The ``normal`` convention is the same as :func:`clip_solid`: it points
+    toward the **removed** material.
+
+    After clipping, set the parent ``IfcShapeRepresentation``
+    ``RepresentationType`` to ``"Clipping"``.
+
+    Example::
+
+        bcr = ifcopenshell.api.run(
+            "geometry.clip_solid_bounded", model,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+
+    :param item: The solid to clip (``IfcSweptAreaSolid``, ``IfcSweptDiskSolid``,
+        or ``IfcBooleanClippingResult``).
+    :param location: A point on the clipping plane in the representation's
+        local coordinate system.
+    :param normal: Plane normal pointing toward the material to be removed.
+    :param boundary_points: 2D ``[x, y]`` points defining the closed polygonal
+        boundary in the coordinate system of ``boundary_position``.  The polygon
+        is automatically closed — do not repeat the first point.
+    :param boundary_position: 3D origin of the boundary coordinate system
+        (axes default to the global X/Y/Z directions).  Defaults to the origin.
+    :param element: If provided, the resulting ``IfcBooleanClippingResult`` is
+        registered in the element's ``BBIM_Boolean`` property set so that
+        :func:`regenerate_wall_representation` preserves it during regeneration.
+    :return: The resulting ``IfcBooleanClippingResult``.
+    """
+    unit_scale = ifcopenshell.util.unit.calculate_unit_scale(file)
+    builder = ShapeBuilder(file)
+
+    normal_arr = np.array(normal)
+    if np.allclose(normal_arr, [0.0, 0.0, 1.0], atol=1e-2) or np.allclose(normal_arr, [0.0, 0.0, -1.0], atol=1e-2):
+        arbitrary_vector = np.array([0.0, 1.0, 0.0])
+    else:
+        arbitrary_vector = np.array([0.0, 0.0, 1.0])
+    x_axis = np.cross(normal_arr, arbitrary_vector)
+    x_axis /= np.linalg.norm(x_axis)
+
+    scaled_location = [i / unit_scale for i in location]
+    plane_placement = builder.create_axis2_placement_3d(scaled_location, normal, x_axis)
+    plane = file.create_entity("IfcPlane", plane_placement)
+
+    scaled_boundary_position = [i / unit_scale for i in boundary_position]
+    boundary_pos_entity = file.create_entity(
+        "IfcAxis2Placement3D",
+        file.create_entity("IfcCartesianPoint", scaled_boundary_position),
+    )
+
+    scaled_pts = [[p[0] / unit_scale, p[1] / unit_scale] for p in boundary_points]
+    scaled_pts.append(scaled_pts[0])  # close the polygon
+    ifc_pts = [file.create_entity("IfcCartesianPoint", p) for p in scaled_pts]
+    boundary = file.createIfcPolyline(ifc_pts)
+
+    half_space = file.create_entity("IfcPolygonalBoundedHalfSpace", plane, False, boundary_pos_entity, boundary)
+    result = file.create_entity("IfcBooleanClippingResult", "DIFFERENCE", item, half_space)
+    if element is not None:
+        pset_data = ifcopenshell.util.element.get_pset(element, "BBIM_Boolean")
+        if pset_data:
+            pset = file.by_id(pset_data["id"])
+            data = list(set(json.loads(pset_data["Data"]) + [result.id()]))
+        else:
+            pset = ifcopenshell.api.pset.add_pset(file, product=element, name="BBIM_Boolean")
+            data = [result.id()]
+        ifcopenshell.api.pset.edit_pset(file, pset=pset, properties={"Data": json.dumps(data)})
+    return result

src/ifcopenshell-python/ifcopenshell/api/geometry/copy_representation.py

@@ -0,0 +1,76 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2026 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+from __future__ import annotations
+
+from typing import Optional
+
+import ifcopenshell.api.geometry
+import ifcopenshell.util.element
+import ifcopenshell.util.representation
+
+
+def copy_representation(
+    file: ifcopenshell.file,
+    source: ifcopenshell.entity_instance,
+    target: ifcopenshell.entity_instance,
+    context_identifier: str = "Body",
+) -> Optional[ifcopenshell.entity_instance]:
+    """Copy a geometric representation from one element to another.
+
+    Finds the named representation on ``source``, deep-copies its entity
+    graph (geometry items, profiles, placements, etc.), and assigns the copy
+    to ``target``.  Representation contexts are shared rather than copied.
+    If ``target`` already has a matching representation it is removed and
+    replaced.
+
+    If no matching representation is found on ``source``, returns ``None``
+    and leaves ``target`` unchanged.
+
+    :param source: The element to copy the representation from.
+    :param target: The element to assign the copied representation to.
+    :param context_identifier: The RepresentationIdentifier to look up on
+        ``source`` (e.g. ``"Body"``, ``"Axis"``, ``"Box"``).
+        Defaults to ``"Body"``.
+    :return: The newly created IfcShapeRepresentation, or None if no
+        matching representation was found on ``source``.
+
+    Example:
+
+    .. code:: python
+
+        wall_a = model.by_id(1)
+        wall_b = model.by_id(2)
+
+        # Give wall_b the same body geometry as wall_a.
+        ifcopenshell.api.geometry.copy_representation(model,
+            source=wall_a, target=wall_b)
+    """
+    source_rep = ifcopenshell.util.representation.get_representation(source, "Model", context_identifier)
+    if source_rep is None:
+        return None
+
+    new_rep = ifcopenshell.util.element.copy_deep(file, source_rep, exclude=["IfcGeometricRepresentationContext"])
+
+    existing_rep = ifcopenshell.util.representation.get_representation(target, "Model", context_identifier)
+    if existing_rep:
+        ifcopenshell.api.geometry.unassign_representation(file, product=target, representation=existing_rep)
+        ifcopenshell.api.geometry.remove_representation(file, representation=existing_rep)
+
+    ifcopenshell.api.geometry.assign_representation(file, product=target, representation=new_rep)
+    return new_rep

src/ifcopenshell-python/ifcopenshell/api/geometry/edit_object_placement.py

@@ -52,10 +52,11 @@ def edit_object_placement(
     :param is_si: If True, the matrix is given in SI units. If false, in
         project units.
     :param should_transform_children: A child element is a nested element,
-        opening, filling, etc. If true, child elements will move along with the
-        parent. If false, child elements will stay where they are. Because most
-        placements in IFC are relative, this means that if a child moves, we
-        actually don't change their placement.
+        opening, filling, etc. If True, child elements move along with the
+        parent; pass True when moving an assembly (roof, furniture group, etc.)
+        and you want all children to follow. If False (default), child elements
+        keep their current world positions; their local placements are rewritten
+        to compensate for the parent move.
     :return: The new or updated IfcLocalPlacement entity
     """
     usecase = Usecase()

src/ifcopenshell-python/ifcopenshell/api/geometry/regenerate_wall_representation.py

@@ -69,6 +69,12 @@ def regenerate_wall_representation(
     additional extrusions are generated for each connection that boolean
     difference the base extrusion.
 
+    Clippings applied via :func:`geometry.clip_solid` or
+    :func:`geometry.clip_solid_bounded` are preserved only if the ``element``
+    parameter was passed when creating them, which registers the result in the
+    ``BBIM_Boolean`` property set.  Clippings created without that parameter
+    are silently discarded during regeneration.
+
     This will also update the axis line representation (e.g. trim the axis line
     to any connections).
 

src/ifcopenshell-python/ifcopenshell/api/geometry/validate_type.py

@@ -83,6 +83,7 @@ def validate_type(
 
     if remaining_items:
         ifcopenshell.api.geometry.add_boolean(file, preferred_item, remaining_items, "UNION")
+        representation.Items = [i for i in representation.Items if i not in remaining_items]
 
     representation.RepresentationType = ifcopenshell.util.representation.guess_type(representation.Items)
     if representation.RepresentationType == "CSG":

src/ifcopenshell-python/ifcopenshell/api/georeference/add_georeferencing.py

@@ -17,6 +17,7 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.api.georeference
 import ifcopenshell.api.pset
 import ifcopenshell.util.element
 
@@ -63,8 +64,13 @@ def add_georeferencing(file: ifcopenshell.file, ifc_class: str = "IfcMapConversi
             },
         )
         return
-    if file.by_type("IfcProjectedCRS"):
+    has_crs = bool(file.by_type("IfcProjectedCRS"))
+    has_conversion = bool(file.by_type("IfcCoordinateOperation"))
+    if has_crs and has_conversion:
         return
+    if has_crs or has_conversion:
+        # This is technically invalid, but we shall forgive the industry here if they are wrong ...
+        ifcopenshell.api.georeference.remove_georeferencing(file)
     source_crs = None
     for context in file.by_type("IfcGeometricRepresentationContext", include_subtypes=False):
         if context.ContextType == "Model":

src/ifcopenshell-python/ifcopenshell/api/grid/remove_grid_axis.py

@@ -42,7 +42,5 @@ def remove_grid_axis(file: ifcopenshell.file, axis: ifcopenshell.entity_instance
         ifcopenshell.api.grid.remove_grid_axis(model, axis=axis_2)
     """
     axis_curve = axis.AxisCurve
-    if file.get_total_inverses(axis_curve) == 1:
-        ifcopenshell.util.element.remove_deep(file, axis_curve)
-        file.remove(axis_curve)
     file.remove(axis)
+    ifcopenshell.util.element.remove_deep2(file, axis_curve)

src/ifcopenshell-python/ifcopenshell/api/nest/assign_object.py

@@ -19,7 +19,9 @@
 from typing import Union
 
 import ifcopenshell
+import ifcopenshell.api.aggregate
 import ifcopenshell.api.owner
+import ifcopenshell.api.spatial
 import ifcopenshell.guid
 import ifcopenshell.util.element
 
@@ -137,7 +139,10 @@ def assign_object(
     if not objects_to_change:
         return is_nested_by
 
-    # NOTE: An object can both be nested and assigned to a container or an aggregate.
+    # Can be either only nested, aggregated, or contained at the same time.
+    possibly_contained = [o for o in objects_without_nests if hasattr(o, "ContainedInStructure")]
+    ifcopenshell.api.spatial.unassign_container(file, products=possibly_contained)
+    ifcopenshell.api.aggregate.unassign_object(file, products=objects_without_nests)
 
     # unassign elements from previous nests
     for nests in previous_nests_rels:

src/ifcopenshell-python/ifcopenshell/api/pset_template/remove_prop_template.py

@@ -22,9 +22,9 @@ import ifcopenshell.util.element
 def remove_prop_template(file: ifcopenshell.file, prop_template: ifcopenshell.entity_instance) -> None:
     """Removes a property template
 
-    Note that a property set template should always have at least one
-    property template to be valid, so take care when removing property
-    templates.
+    Note that a property set template should always have at least one property
+    template to be valid. So a property set template will not be removed if it
+    is the only template ina a property ste template.
 
     :param prop_template: The IfcSimplePropertyTemplate to remove.
     :return: None
@@ -43,10 +43,8 @@ def remove_prop_template(file: ifcopenshell.file, prop_template: ifcopenshell.en
         ifcopenshell.api.pset_template.remove_prop_template(model, prop_template=prop2)
     """
     for inverse in file.get_inverse(prop_template):
-        if len(inverse.HasPropertyTemplates) == 1:
-            inverse.HasPropertyTemplates = []
-        else:
+        if len(inverse.HasPropertyTemplates) > 1:
             has_property_templates = list(inverse.HasPropertyTemplates)
             has_property_templates.remove(prop_template)
             inverse.HasPropertyTemplates = has_property_templates
-    ifcopenshell.util.element.remove_deep(file, prop_template)
+    ifcopenshell.util.element.remove_deep2(file, prop_template)

src/ifcopenshell-python/ifcopenshell/api/pset_template/remove_pset_template.py

@@ -38,4 +38,4 @@ def remove_pset_template(file: ifcopenshell.file, pset_template: ifcopenshell.en
         # Let's remove the template.
         ifcopenshell.api.pset_template.remove_pset_template(model, pset_template=template)
     """
-    ifcopenshell.util.element.remove_deep(file, pset_template)
+    ifcopenshell.util.element.remove_deep2(file, pset_template)

src/ifcopenshell-python/ifcopenshell/api/resource/add_resource_quantity.py

@@ -79,5 +79,5 @@ def add_resource_quantity(
     old_quantity = resource.BaseQuantity
     resource.BaseQuantity = quantity
     if old_quantity:
-        ifcopenshell.util.element.remove_deep(file, old_quantity)
+        ifcopenshell.util.element.remove_deep2(file, old_quantity)
     return quantity

src/ifcopenshell-python/ifcopenshell/api/resource/remove_resource_quantity.py

@@ -47,4 +47,4 @@ def remove_resource_quantity(file: ifcopenshell.file, resource: ifcopenshell.ent
     old_quantity = resource.BaseQuantity
     resource.BaseQuantity = None
     if old_quantity:
-        ifcopenshell.util.element.remove_deep(file, old_quantity)
+        ifcopenshell.util.element.remove_deep2(file, old_quantity)

src/ifcopenshell-python/ifcopenshell/api/sequence/assign_process.py

@@ -26,7 +26,7 @@ def assign_process(
     relating_process: ifcopenshell.entity_instance,
     related_object: ifcopenshell.entity_instance,
 ) -> ifcopenshell.entity_instance:
-    """Assigns an object to be related to a process, typically a construction task
+    """Assigns an object as an input, control, or resource of a process
 
     Processes work using the ICOM (Input, Controls, Outputs, Mechanisms)
     paradigm in IFC. This process model is commonly used in modeling
@@ -63,6 +63,17 @@ def assign_process(
 
     For resources, any construction resource may be assigned to a task.
 
+    .. warning::
+
+        This function creates an **Input** relationship
+        (``IfcRelAssignsToProcess``), meaning the product is *consumed* or
+        *operated on* by the task — the typical case is demolition or
+        maintenance.
+
+        If the task *constructs or installs* a product (e.g. erecting a wall
+        or fitting a window), use :func:`assign_product` instead, which
+        creates an **Output** relationship (``IfcRelAssignsToProduct``).
+
     :param relating_process: The IfcProcess (typically IfcTask) that the
         input, control, or resource is related to.
     :param related_object: The IfcProduct (for input), IfcCostItem (for
@@ -77,7 +88,7 @@ def assign_process(
         # need to be part of a work schedule.
         schedule = ifcopenshell.api.sequence.add_work_schedule(model, name="Construction Schedule A")
 
-        # Let's create a construction task. Note that the predefined type is
+        # Let's create a demolition task. Note that the predefined type is
         # important to distinguish types of tasks.
         task = ifcopenshell.api.sequence.add_task(model,
             work_schedule=schedule, name="Demolish existing", identification="A", predefined_type="DEMOLITION")
@@ -85,8 +96,12 @@ def assign_process(
         # Let's say we have a wall somewhere.
         wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")
 
-        # Let's demolish that wall!
+        # The wall is an INPUT to the demolition task (it will be consumed).
         ifcopenshell.api.sequence.assign_process(model, relating_process=task, related_object=wall)
+
+        # For a construction task that BUILDS a wall, use assign_product instead:
+        # build_task = ifcopenshell.api.sequence.add_task(model, ..., predefined_type="CONSTRUCTION")
+        # ifcopenshell.api.sequence.assign_product(model, relating_product=wall, related_object=build_task)
     """
     if related_object.HasAssignments:
         for assignment in related_object.HasAssignments:

src/ifcopenshell-python/ifcopenshell/api/unit/remove_unit.py

@@ -47,4 +47,5 @@ def remove_unit(file: ifcopenshell.file, unit: ifcopenshell.entity_instance) ->
             unit_assignment.Units = units
         else:
             file.remove(unit_assignment)
-    ifcopenshell.util.element.remove_deep(file, unit)
+    # TODO handle other possible unit inverses
+    ifcopenshell.util.element.remove_deep2(file, unit)

src/ifcopenshell-python/ifcopenshell/util/shape_builder.py

@@ -517,11 +517,18 @@ class ShapeBuilder:
         trim_points_mask: Sequence[int],
         position_offset: Optional[VectorType] = None,
     ) -> np.ndarray:
-        """Handy way to get edge points of the ellipse like shape of a given radiuses.
+        """Get cardinal-point coordinates of an ellipse by index mask.
 
-        Mask points are numerated from 0 to 3 ccw starting from (x_axis_radius/2; 0).
+        The four cardinal points are numbered 0–3 counter-clockwise starting from the
+        positive X axis: 0 → ``(x, 0)``, 1 → ``(0, y)``, 2 → ``(-x, 0)``, 3 → ``(0, -y)``.
 
-        Example: mask (0, 1, 2, 3) will return points (x, 0), (0, y), (-x, 0), (0, -y)
+        Example: mask ``(0, 1, 2, 3)`` returns all four points in order.
+
+        :param x_axis_radius: Radius (semi-axis length) along the X axis.
+        :param y_axis_radius: Radius (semi-axis length) along the Y axis.
+        :param trim_points_mask: Sequence of cardinal-point indices (0–3) to select.
+        :param position_offset: Optional 2D offset added to all returned points.
+        :return: Numpy array of the selected 2D points.
         """
         points = np.array(
             (
@@ -546,15 +553,23 @@ class ShapeBuilder:
         ref_x_direction: VectorType = (1.0, 0.0),
         trim_points_mask: Sequence[int] = (),
     ) -> ifcopenshell.entity_instance:
-        """
-        Ellipse trimming points should be specified in counter clockwise order.
+        """Create an IfcEllipse, optionally trimmed to an arc.
 
-        For example, if you need to get the part of the ellipse ABOVE y-axis, you need to use mask (0,2). Below y-axis - (2,0)
+        If neither ``trim_points`` nor ``trim_points_mask`` is provided, a full IfcEllipse is returned.
+        Trimming points must be given in counter-clockwise order. For example, to get the arc
+        above the Y-axis use mask ``(0, 2)``; below the Y-axis use ``(2, 0)``.
 
-        For more information about trim_points_mask check builder.get_trim_points_from_mask
+        A trimmed result (IfcTrimmedCurve) includes a closing segment between the trim points,
+        making it suitable for use as a profile in :meth:`extrude`.
 
-        Notion: trimmed ellipse also contains polyline between trim points, meaning IfcTrimmedCurve could be used
-        for further extrusion.
+        :param x_axis_radius: Semi-axis length along the local X axis.
+        :param y_axis_radius: Semi-axis length along the local Y axis.
+        :param position: 2D centre of the ellipse.
+        :param trim_points: Explicit pair of 2D trim points. Takes precedence over ``trim_points_mask``.
+        :param ref_x_direction: Direction of the local X axis.
+        :param trim_points_mask: Pair of cardinal-point indices (0–3) used when ``trim_points`` is empty.
+            See :meth:`get_trim_points_from_mask` for index definitions.
+        :return: IfcEllipse (untrimmed) or IfcTrimmedCurve (trimmed).
         """
         ifc_position = self.create_axis2_placement_2d(position, ref_x_direction)
         ifc_ellipse = self.file.createIfcEllipse(
@@ -685,6 +700,14 @@ class ShapeBuilder:
         pivot_point: VectorType = (0.0, 0.0),
         counter_clockwise: bool = False,
     ) -> np.ndarray:
+        """Rotate a single 2D point around a pivot.
+
+        :param point_2d: The 2D point to rotate.
+        :param angle: Rotation angle, in degrees. Defaults to 90.
+        :param pivot_point: The point to rotate around.
+        :param counter_clockwise: If True, rotate counter-clockwise. Defaults to clockwise.
+        :return: Rotated 2D point as a numpy array.
+        """
         angle_rad = radians(angle) * (1 if counter_clockwise else -1)
         relative_point = np.array(point_2d) - pivot_point
         relative_point = np_rotation_matrix(angle_rad, 2) @ relative_point
@@ -752,7 +775,16 @@ class ShapeBuilder:
         mirror_axes: VectorType = (1.0, 1.0),
         mirror_point: VectorType = (0.0, 0.0),
     ) -> np.ndarray:
-        """mirror_axes - along which axes mirror will be applied"""
+        """Mirror a single 2D point across the specified axes.
+
+        :param point_2d: The 2D point to mirror.
+        :param mirror_axes: Indicates which axes to mirror across. A positive value in a
+            component means that axis is mirrored (negated relative to ``mirror_point``).
+            Example: ``(1, 0)`` mirrors across the Y-axis (negates X only),
+            ``(1, 1)`` mirrors across both axes.
+        :param mirror_point: Origin of the mirror operation.
+        :return: Mirrored 2D point as a numpy array.
+        """
         mirror_axes: np.ndarray = np.where(np.array(mirror_axes) > 0, -1, 1)
         mirror_point: np.ndarray = np.array(mirror_point)
         relative_point = point_2d - mirror_point
@@ -798,7 +830,13 @@ class ShapeBuilder:
     def create_axis2_placement_2d(
         self, position: VectorType = (0.0, 0.0), x_direction: Optional[VectorType] = None
     ) -> ifcopenshell.entity_instance:
-        """Create IfcAxis2Placement2D."""
+        """Create IfcAxis2Placement2D.
+
+        :param position: 2D origin of the placement.
+        :param x_direction: Direction of the local X axis. If not provided, defaults to
+            the global X axis ``(1, 0)``.
+        :return: IfcAxis2Placement2D
+        """
         ref_direction = (
             self.file.create_entity("IfcDirection", ifc_safe_vector_type(x_direction)) if x_direction else None
         )
@@ -1000,7 +1038,7 @@ class ShapeBuilder:
     ) -> ifcopenshell.entity_instance:
         """
         :param plane: The IfcPlane representing the half space.
-        :param agreement_flag: False if +Z represents the void
+        :param agreement_flag: If False (default), the plane normal points toward the **removed** material (the void). The kept region is on the opposite side from the normal.
         :return: IfcHalfSpaceSolid
         """
         return self.file.createIfcHalfSpaceSolid(plane, AgreementFlag=agreement_flag)
@@ -1053,7 +1091,14 @@ class ShapeBuilder:
     def create_swept_disk_solid(
         self, path_curve: ifcopenshell.entity_instance, radius: float
     ) -> ifcopenshell.entity_instance:
-        """Create IfcSweptDiskSolid from `path_curve` (must be 3D) and `radius`"""
+        """Create an IfcSweptDiskSolid — a circular cross-section swept along a 3D path.
+
+        Useful for modelling round pipes, conduits, and cables.
+
+        :param path_curve: A 3D curve entity defining the centreline path. Must have ``Dim == 3``.
+        :param radius: Radius of the circular disk cross-section.
+        :return: IfcSweptDiskSolid
+        """
         if path_curve.Dim != 3:
             raise Exception(
                 f"Path curve for IfcSweptDiskSolid should be 3D to be valid, currently it has {path_curve.Dim} dimensions.\n"
@@ -1071,10 +1116,22 @@ class ShapeBuilder:
     ) -> ifcopenshell.entity_instance:
         """Create IFC representation for the specified context and items.
 
+        **All items must belong to the same geometry category.** IFC prohibits
+        mixing incompatible item types in one representation (e.g.
+        ``IfcExtrudedAreaSolid`` with ``IfcBlock``, or solids with curves).
+        When ``representation_type`` is omitted the type is inferred via
+        :func:`ifcopenshell.util.representation.guess_type`; if the items are
+        heterogeneous ``guess_type`` returns ``None`` and the representation is
+        written with no ``RepresentationType``, which fails IFC validation.
+        Avoid mixing swept-solid primitives (``IfcExtrudedAreaSolid``,
+        ``IfcRevolvedAreaSolid``) with CSG primitives (``IfcBlock``,
+        ``IfcSphere``, etc.) or any other category in a single call.
+
         :param context: IfcGeometricRepresentationSubContext
-        :param items: could be a list or single curve/IfcExtrudedAreaSolid
+        :param items: A single item or list of items, all of the same geometry
+            category (e.g. all ``IfcExtrudedAreaSolid``, all ``IfcIndexedPolyCurve``)
         :param representation_type: Explicitly specified RepresentationType.
-            If not provided it will be guessed from the items types
+            If not provided it will be guessed from the items types.
         :return: IfcShapeRepresentation
         """
         if not isinstance(items, collections.abc.Iterable):
@@ -1096,18 +1153,26 @@ class ShapeBuilder:
         )
 
     def deep_copy(self, element: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
+        """Create a deep copy of an IFC element and all its referenced entities.
+
+        :param element: The IFC entity to copy.
+        :return: A new independent copy of the element.
+        """
         return ifcopenshell.util.element.copy_deep(self.file, element)
 
     # UTILITIES
     def extrude_kwargs(self, axis: Literal["Y", "X", "Z"]) -> dict[str, tuple[float, float, float]]:
-        """Shortcut to get kwargs for `ShapeBuilder.extrude` to extrude by some axis.
+        """Shortcut to get kwargs for :meth:`extrude` to extrude along a principal axis.
 
-        It assumes you have 2D profile in:
-            XZ plane for Y axis extrusion, \n
-            YZ plane for X axis extrusion, \n
-            XY plane for Z axis extrusion, \n
+        Assumes the 2D profile lies in the plane perpendicular to the extrusion axis:
+        XZ plane for Y-axis extrusion, YZ plane for X-axis extrusion, XY plane for Z-axis extrusion.
 
-        Extruding by X/Y using other kwargs might break ValidExtrusionDirection."""
+        Extruding along X or Y with other kwargs may violate the IFC ValidExtrusionDirection constraint.
+
+        :param axis: The extrusion axis: ``'X'``, ``'Y'``, or ``'Z'``.
+        :return: A dict with keys ``position_x_axis``, ``position_z_axis``, and ``extrusion_vector``
+            suitable for passing as ``**kwargs`` to :meth:`extrude`.
+        """
 
         if axis == "Y":
             return {
@@ -1131,13 +1196,16 @@ class ShapeBuilder:
     def rotate_extrusion_kwargs_by_z(
         self, kwargs: dict[str, Any], angle: float, counter_clockwise: bool = False
     ) -> dict[str, VectorType]:
-        """shortcut to rotate extrusion kwargs by z axis
+        """Rotate extrusion kwargs around the Z axis.
 
-        `kwargs` expected to have `position_x_axis` and `position_z_axis` keys
+        A shortcut to rotate the ``position_x_axis`` and ``position_z_axis`` values returned by
+        :meth:`extrude_kwargs` around the Z axis before passing them to :meth:`extrude`.
 
-        `angle` is a rotation value in radians
-
-        by default rotation is clockwise, to make it counter clockwise use `counter_clockwise` flag
+        :param kwargs: A dict with ``position_x_axis`` and ``position_z_axis`` keys,
+            as returned by :meth:`extrude_kwargs`. The original dict is not mutated.
+        :param angle: Rotation angle, in radians.
+        :param counter_clockwise: If True, rotate counter-clockwise. Defaults to clockwise.
+        :return: A new dict with ``position_x_axis`` and ``position_z_axis`` rotated around Z.
         """
         rot = np_rotation_matrix(-angle, 3, "Z")
         kwargs = kwargs.copy()  # prevent mutation of original kwargs
@@ -1146,7 +1214,11 @@ class ShapeBuilder:
         return kwargs
 
     def get_polyline_coords(self, polyline: ifcopenshell.entity_instance) -> np.ndarray:
-        """polyline should be either `IfcIndexedPolyCurve` or `IfcPolyline`"""
+        """Extract the coordinate array from a polyline entity.
+
+        :param polyline: An ``IfcIndexedPolyCurve`` or ``IfcPolyline`` entity.
+        :return: Numpy array of the polyline's point coordinates.
+        """
         coords = None
         if polyline.is_a("IfcIndexedPolyCurve"):
             coords = np.array(polyline.Points.CoordList)
@@ -1157,7 +1229,12 @@ class ShapeBuilder:
         return coords
 
     def set_polyline_coords(self, polyline: ifcopenshell.entity_instance, coords: SequenceOfVectors) -> None:
-        """polyline should be either `IfcIndexedPolyCurve` or `IfcPolyline`"""
+        """Update the coordinates of a polyline entity in-place.
+
+        :param polyline: An ``IfcIndexedPolyCurve`` or ``IfcPolyline`` entity.
+        :param coords: New sequence of point coordinates. Must contain the same number of
+            points as the original polyline.
+        """
         if polyline.is_a("IfcIndexedPolyCurve"):
             polyline.Points.CoordList = ifc_safe_vector_type(coords)
         elif polyline.is_a("IfcPolyline"):
@@ -1296,6 +1373,18 @@ class ShapeBuilder:
         WallThickness: float,
         FilletRadius: float,
     ) -> ifcopenshell.entity_instance:
+        """Create a Z-profile (cold-formed steel section) outline curve with lips and fillets.
+
+        All dimensions are in the IFC project's length units.
+
+        :param FirstFlangeWidth: Width of the first (top) flange, measured from the web centreline.
+        :param SecondFlangeWidth: Width of the second (bottom) flange, measured from the web centreline.
+        :param Depth: Total depth of the section (web height).
+        :param Girth: Length of the return lips on each flange.
+        :param WallThickness: Uniform material thickness.
+        :param FilletRadius: Inner bend radius at each corner.
+        :return: IfcIndexedPolyCurve representing the closed Z-profile outline.
+        """
         x1 = FirstFlangeWidth
         x2 = SecondFlangeWidth
         y = Depth / 2
@@ -1337,10 +1426,17 @@ class ShapeBuilder:
     def create_transition_arc_ifc(
         self, width: float, height: float, create_ifc_curve: bool = False
     ) -> tuple[SequenceOfVectors, list[list[int]], Union[ifcopenshell.entity_instance, None]]:
-        """Create an arc in the rectangle with specified width and height.
+        """Create an arc fitting inside a rectangle of the given width and height.
 
-        If it's not possible to make a complete arc, create an arc with longest radius possible
-        and straight segment in the middle.
+        If a single arc cannot span the full width, the longest possible radius is used and
+        a straight segment is inserted in the middle.
+
+        :param width: Width of the bounding rectangle.
+        :param height: Height of the bounding rectangle (also the maximum arc radius).
+        :param create_ifc_curve: If True, also create and return an ``IfcIndexedPolyCurve``.
+            If False, only return the raw point and segment data.
+        :return: A tuple ``(points, segments, ifc_curve)`` where ``ifc_curve`` is an
+            ``IfcIndexedPolyCurve`` when ``create_ifc_curve=True``, otherwise ``None``.
         """
         fillet_size = (width / 2) / height
         if fillet_size <= 1:
@@ -1370,6 +1466,14 @@ class ShapeBuilder:
         return points, segments, transition_arc
 
     def mesh(self, points: SequenceOfVectors, faces: Sequence[Sequence[int]]) -> ifcopenshell.entity_instance:
+        """Create a tessellated mesh from points and face indices.
+
+        Delegates to :meth:`faceted_brep` for IFC2X3, or :meth:`polygonal_face_set` for IFC4 and later.
+
+        :param points: List of 3D coordinates.
+        :param faces: List of faces, each face a sequence of zero-based point indices.
+        :return: IfcFacetedBrep (IFC2X3) or IfcPolygonalFaceSet (IFC4+).
+        """
         if self.file.schema == "IFC2X3":
             return self.faceted_brep(points, faces)
         return self.polygonal_face_set(points, faces)
@@ -1723,11 +1827,20 @@ class ShapeBuilder:
         angle: float,
         profile_offset: VectorType = (0.0, 0.0),
         verbose: bool = True,
-    ):
-        """get the final transition length for two profiles dimensions, angle and XY offset between them,
+    ) -> Optional[float]:
+        """Get the transition length for two profile half-dimensions, an angle, and an XY offset.
 
-        the difference from `calculate_transition` - `get_transition_length` is making sure
-        that length will fit both sides of the transition
+        Unlike :meth:`mep_transition_calculate`, this method checks that the resulting length
+        satisfies the angle constraint from both the start and end profile perspectives.
+
+        :param start_half_dim: Half-dimensions of the start profile as a 3-element array
+            ``[half_x, half_y, depth]``. For circular profiles ``half_x == half_y == radius``.
+        :param end_half_dim: Half-dimensions of the end profile in the same format.
+        :param angle: Maximum allowed transition angle, in degrees.
+        :param profile_offset: 2D XY offset between the centrelines of the start and end profiles.
+        :param verbose: If True, print diagnostic values during calculation.
+        :return: Transition length in project length units, or ``None`` if no valid length exists
+            for the given angle and offset.
         """
         print = lambda *args, **kwargs: __builtins__["print"](*args, **kwargs) if verbose else None
         np_X, np_Y = 0, 1
@@ -1788,9 +1901,23 @@ class ShapeBuilder:
         angle: Optional[float] = None,
         verbose: bool = True,
     ) -> Union[float, None]:
-        """will return transition length based on the profile dimension differences and offset.
+        """Calculate MEP transition length from angle, or transition angle from length.
 
-        If `length` is provided will return transition angle"""
+        Low-level calculation kernel used by :meth:`mep_transition_length`. Provide either
+        ``angle`` or ``length`` (not both); the other value is computed and returned.
+
+        :param start_half_dim: Half-dimensions of the start profile ``[half_x, half_y, depth]``.
+        :param end_half_dim: Half-dimensions of the end profile ``[half_x, half_y, depth]``.
+        :param offset: 2D XY offset between profile centrelines.
+        :param diff: Pre-computed absolute difference of start and end half-dimensions (XY only).
+            Computed from ``start_half_dim`` and ``end_half_dim`` if not provided.
+        :param end_profile: If True, swap X and Y axes to compute from the end-profile perspective.
+        :param length: Known transition length. If provided, the corresponding angle is returned.
+        :param angle: Known transition angle, in degrees. If provided, the corresponding length is returned.
+        :param verbose: If True, print diagnostic values during calculation.
+        :return: Transition length (if ``angle`` was given) or transition angle in degrees
+            (if ``length`` was given), or ``None`` if the geometry is not feasible.
+        """
 
         print = lambda *args, **kwargs: __builtins__["print"](*args, **kwargs) if verbose else None
 

src/ifcopenshell-python/test/api/cost/test_edit_cost_value.py

@@ -0,0 +1,72 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2021 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import ifcopenshell.api.cost
+import ifcopenshell.api.unit
+import test.bootstrap
+
+
+class TestEditCostValue(test.bootstrap.IFC4):
+    def test_editing_applied_value(self):
+        schedule = ifcopenshell.api.cost.add_cost_schedule(self.file)
+        item = ifcopenshell.api.cost.add_cost_item(self.file, cost_schedule=schedule)
+        value = ifcopenshell.api.cost.add_cost_value(self.file, parent=item)
+        ifcopenshell.api.cost.edit_cost_value(self.file, cost_value=value, attributes={"AppliedValue": 42.0})
+        assert value.AppliedValue.wrappedValue == 42.0
+
+    def test_editing_unit_basis_removes_old_deeply(self):
+        schedule = ifcopenshell.api.cost.add_cost_schedule(self.file)
+        item = ifcopenshell.api.cost.add_cost_item(self.file, cost_schedule=schedule)
+        value = ifcopenshell.api.cost.add_cost_value(self.file, parent=item)
+        unit = ifcopenshell.api.unit.add_si_unit(self.file, unit_type="LENGTHUNIT")
+        ifcopenshell.api.cost.edit_cost_value(
+            self.file,
+            cost_value=value,
+            attributes={"UnitBasis": {"ValueComponent": 1.0, "UnitComponent": unit}},
+        )
+        old_basis = value.UnitBasis
+        assert old_basis is not None
+        old_basis_id = old_basis.id()
+        # Now change to a new unit basis — the old one should be deeply removed.
+        ifcopenshell.api.cost.edit_cost_value(
+            self.file,
+            cost_value=value,
+            attributes={"UnitBasis": {"ValueComponent": 2.0, "UnitComponent": unit}},
+        )
+        assert value.UnitBasis is not None
+        assert value.UnitBasis.id() != old_basis_id
+
+    def test_clearing_unit_basis(self):
+        schedule = ifcopenshell.api.cost.add_cost_schedule(self.file)
+        item = ifcopenshell.api.cost.add_cost_item(self.file, cost_schedule=schedule)
+        value = ifcopenshell.api.cost.add_cost_value(self.file, parent=item)
+        unit = ifcopenshell.api.unit.add_si_unit(self.file, unit_type="LENGTHUNIT")
+        ifcopenshell.api.cost.edit_cost_value(
+            self.file,
+            cost_value=value,
+            attributes={"UnitBasis": {"ValueComponent": 1.0, "UnitComponent": unit}},
+        )
+        assert value.UnitBasis is not None
+        ifcopenshell.api.cost.edit_cost_value(
+            self.file, cost_value=value, attributes={"UnitBasis": None}
+        )
+        assert value.UnitBasis is None
+
+
+class TestEditCostValueIFC4X3(test.bootstrap.IFC4X3, TestEditCostValue):
+    pass

src/ifcopenshell-python/test/api/geometry/test_add_boolean.py

@@ -42,7 +42,7 @@ class TestAddBoolean(test.bootstrap.IFC4):
         assert boolean.FirstOperand == first
         assert boolean.SecondOperand == second
         assert boolean.Operator == "DIFFERENCE"
-        assert set(rep.Items) == {boolean}
+        assert set(rep.Items) == {boolean, second}
 
     def test_adding_multiple_booleans_from_three_top_level_items(self):
         ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcProject")
@@ -58,13 +58,14 @@ class TestAddBoolean(test.bootstrap.IFC4):
 
         booleans = ifcopenshell.api.geometry.add_boolean(self.file, first, [second1, second2])
         assert len(booleans) == 2
-        assert len(rep.Items) == 1
-        assert rep.Items[0].FirstOperand.is_a("IfcBooleanResult")
-        assert rep.Items[0].SecondOperand == second2
-        assert rep.Items[0].Operator == "DIFFERENCE"
-        assert rep.Items[0].FirstOperand.FirstOperand == first
-        assert rep.Items[0].FirstOperand.SecondOperand == second1
-        assert rep.Items[0].FirstOperand.Operator == "DIFFERENCE"
+        final_boolean = booleans[-1]
+        assert final_boolean.FirstOperand.is_a("IfcBooleanResult")
+        assert final_boolean.SecondOperand == second2
+        assert final_boolean.Operator == "DIFFERENCE"
+        assert final_boolean.FirstOperand.FirstOperand == first
+        assert final_boolean.FirstOperand.SecondOperand == second1
+        assert final_boolean.FirstOperand.Operator == "DIFFERENCE"
+        assert set(rep.Items) == {final_boolean, second1, second2}
 
     def test_adding_a_boolean_to_an_existing_operand_from_a_top_level_item(self):
         ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcProject")
@@ -78,14 +79,16 @@ class TestAddBoolean(test.bootstrap.IFC4):
         second2 = builder.block()
         rep = builder.get_representation(body, [first, second1])
         booleans = ifcopenshell.api.geometry.add_boolean(self.file, first, [second1])
+        # second1 stays in Items, add second2 as well
         rep.Items = list(rep.Items) + [second2]
         booleans = ifcopenshell.api.geometry.add_boolean(self.file, first, [second2])
         assert len(booleans) == 1
-        assert len(rep.Items) == 1
-        assert rep.Items[0].FirstOperand.is_a("IfcBooleanResult")
-        assert rep.Items[0].SecondOperand == second2
-        assert rep.Items[0].FirstOperand.FirstOperand == first
-        assert rep.Items[0].FirstOperand.SecondOperand == second1
+        final_boolean = booleans[0]
+        assert final_boolean.FirstOperand.is_a("IfcBooleanResult")
+        assert final_boolean.SecondOperand == second2
+        assert final_boolean.FirstOperand.FirstOperand == first
+        assert final_boolean.FirstOperand.SecondOperand == second1
+        assert set(rep.Items) == {final_boolean, second1, second2}
 
     def test_adding_a_boolean_to_an_existing_operand_from_another_operand(self):
         ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcProject")
@@ -104,7 +107,7 @@ class TestAddBoolean(test.bootstrap.IFC4):
         booleans = ifcopenshell.api.geometry.add_boolean(self.file, first1, [second2])
 
         assert len(booleans) == 1
-        assert len(rep.Items) == 2
+        assert len(rep.Items) == 4
 
         assert self.file.get_total_inverses(first1) == 1
         result = next(iter(self.file.get_inverse(first1)))
@@ -132,14 +135,15 @@ class TestAddBoolean(test.bootstrap.IFC4):
         rep = builder.get_representation(body, [first, second])
         ifcopenshell.api.geometry.add_boolean(self.file, first, [second])
         ifcopenshell.api.geometry.add_boolean(self.file, first, [second])
-        assert len(rep.Items) == 1
-        assert rep.Items[0].FirstOperand == first
-        assert rep.Items[0].SecondOperand == second
+        assert set(rep.Items) == {self.file.by_type("IfcBooleanResult")[0], second}
+        boolean = self.file.by_type("IfcBooleanResult")[0]
+        assert boolean.FirstOperand == first
+        assert boolean.SecondOperand == second
         ifcopenshell.api.geometry.add_boolean(self.file, second, [second])
         ifcopenshell.api.geometry.add_boolean(self.file, second, [first])
-        assert len(rep.Items) == 1
-        assert rep.Items[0].FirstOperand == first
-        assert rep.Items[0].SecondOperand == second
+        assert set(rep.Items) == {boolean, second}
+        assert boolean.FirstOperand == first
+        assert boolean.SecondOperand == second
         assert len(self.file.by_type("IfcBooleanResult")) == 1
 
 

src/ifcopenshell-python/test/api/geometry/test_clip_solid.py

@@ -0,0 +1,154 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2026 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import json
+
+import ifcopenshell.api.geometry
+import ifcopenshell.util.element
+import ifcopenshell.util.shape_builder
+import test.bootstrap
+
+
+class TestClipSolid(test.bootstrap.IFC4):
+    def make_extrusion(self):
+        builder = ifcopenshell.util.shape_builder.ShapeBuilder(self.file)
+        rect = builder.rectangle(size=(1.0, 1.0))
+        return builder.extrude(rect, magnitude=4.0)
+
+    def test_returns_boolean_clipping_result(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        assert result.is_a("IfcBooleanClippingResult")
+        assert result.Operator == "DIFFERENCE"
+
+    def test_first_operand_is_the_item(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        assert result.FirstOperand == extrusion
+
+    def test_second_operand_is_half_space_solid(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        assert result.SecondOperand.is_a("IfcHalfSpaceSolid")
+
+    def test_clip_plane_location_matches(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        plane = result.SecondOperand.BaseSurface
+        coords = plane.Position.Location.Coordinates
+        assert list(coords) == [0.0, 0.0, 3.0]
+
+    def test_chaining_two_clips(self):
+        extrusion = self.make_extrusion()
+        first_clip = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        second_clip = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=first_clip,
+            location=[0.0, 0.0, 1.0],
+            normal=[0.0, 0.0, -1.0],
+        )
+        assert second_clip.is_a("IfcBooleanClippingResult")
+        assert second_clip.FirstOperand == first_clip
+        assert first_clip.FirstOperand == extrusion
+
+    def test_angled_clip_plane(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.26],
+            normal=[0.419, 0.0, 0.908],
+        )
+        assert result.is_a("IfcBooleanClippingResult")
+        assert result.SecondOperand.is_a("IfcHalfSpaceSolid")
+
+    def test_element_registers_result_in_bbim_boolean(self):
+        extrusion = self.make_extrusion()
+        wall = self.file.createIfcWall()
+        result = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+            element=wall,
+        )
+        pset = ifcopenshell.util.element.get_pset(wall, "BBIM_Boolean")
+        assert pset is not None
+        assert result.id() in json.loads(pset["Data"])
+
+    def test_element_appends_to_existing_bbim_boolean(self):
+        extrusion = self.make_extrusion()
+        wall = self.file.createIfcWall()
+        first = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+            element=wall,
+        )
+        second = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=first,
+            location=[0.0, 0.0, 1.0],
+            normal=[0.0, 0.0, -1.0],
+            element=wall,
+        )
+        pset = ifcopenshell.util.element.get_pset(wall, "BBIM_Boolean")
+        ids = json.loads(pset["Data"])
+        assert first.id() in ids
+        assert second.id() in ids
+
+    def test_no_element_does_not_create_pset(self):
+        extrusion = self.make_extrusion()
+        wall = self.file.createIfcWall()
+        ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        assert ifcopenshell.util.element.get_pset(wall, "BBIM_Boolean") is None
+
+
+class TestClipSolidIFC2X3(test.bootstrap.IFC2X3, TestClipSolid):
+    pass

src/ifcopenshell-python/test/api/geometry/test_clip_solid_bounded.py

@@ -0,0 +1,179 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2026 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import json
+
+import ifcopenshell.api.geometry
+import ifcopenshell.util.element
+import ifcopenshell.util.shape_builder
+import test.bootstrap
+
+
+class TestClipSolidBounded(test.bootstrap.IFC4):
+    def make_extrusion(self):
+        builder = ifcopenshell.util.shape_builder.ShapeBuilder(self.file)
+        rect = builder.rectangle(size=(4.0, 1.0))
+        return builder.extrude(rect, magnitude=3.0)
+
+    def test_returns_boolean_clipping_result(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        assert result.is_a("IfcBooleanClippingResult")
+        assert result.Operator == "DIFFERENCE"
+
+    def test_first_operand_is_the_item(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        assert result.FirstOperand == extrusion
+
+    def test_second_operand_is_polygonal_bounded_half_space(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        assert result.SecondOperand.is_a("IfcPolygonalBoundedHalfSpace")
+
+    def test_agreement_flag_is_false(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        assert result.SecondOperand.AgreementFlag is False
+
+    def test_clip_plane_location_matches(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        plane = result.SecondOperand.BaseSurface
+        coords = plane.Position.Location.Coordinates
+        assert list(coords) == [2.5, 0.0, 2.0]
+
+    def test_boundary_is_closed_polyline(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        boundary = result.SecondOperand.PolygonalBoundary
+        assert boundary.is_a("IfcPolyline")
+        pts = [list(p.Coordinates) for p in boundary.Points]
+        assert pts[0] == pts[-1], "polygon should be closed"
+        assert len(pts) == 5  # 4 unique + closing repeat
+
+    def test_boundary_position_defaults_to_origin(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        pos = result.SecondOperand.Position
+        assert list(pos.Location.Coordinates) == [0.0, 0.0, 0.0]
+
+    def test_custom_boundary_position(self):
+        extrusion = self.make_extrusion()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+            boundary_position=[1.0, 2.0, 3.0],
+        )
+        pos = result.SecondOperand.Position
+        assert list(pos.Location.Coordinates) == [1.0, 2.0, 3.0]
+
+    def test_chaining_with_clip_solid(self):
+        extrusion = self.make_extrusion()
+        first_clip = ifcopenshell.api.geometry.clip_solid(
+            self.file,
+            item=extrusion,
+            location=[0.0, 0.0, 3.0],
+            normal=[0.0, 0.0, 1.0],
+        )
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=first_clip,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        assert result.is_a("IfcBooleanClippingResult")
+        assert result.FirstOperand == first_clip
+        assert first_clip.FirstOperand == extrusion
+
+    def test_element_registers_result_in_bbim_boolean(self):
+        extrusion = self.make_extrusion()
+        wall = self.file.createIfcWall()
+        result = ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+            element=wall,
+        )
+        pset = ifcopenshell.util.element.get_pset(wall, "BBIM_Boolean")
+        assert pset is not None
+        assert result.id() in json.loads(pset["Data"])
+
+    def test_no_element_does_not_create_pset(self):
+        extrusion = self.make_extrusion()
+        wall = self.file.createIfcWall()
+        ifcopenshell.api.geometry.clip_solid_bounded(
+            self.file,
+            item=extrusion,
+            location=[2.5, 0.0, 2.0],
+            normal=[0.6, 0.0, 0.8],
+            boundary_points=[[2.0, 0.0], [3.0, 0.0], [3.0, 2.0], [2.0, 2.0]],
+        )
+        assert ifcopenshell.util.element.get_pset(wall, "BBIM_Boolean") is None
+
+
+class TestClipSolidBoundedIFC2X3(test.bootstrap.IFC2X3, TestClipSolidBounded):
+    pass

src/ifcopenshell-python/test/api/geometry/test_copy_representation.py

@@ -0,0 +1,134 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2026 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import ifcopenshell.api.geometry
+import ifcopenshell.api.root
+import ifcopenshell.util.representation
+import ifcopenshell.util.shape_builder
+import test.bootstrap
+
+
+class TestCopyRepresentation(test.bootstrap.IFC4):
+    def _body_context(self):
+        body = ifcopenshell.util.representation.get_context(self.file, "Model", "Body", "MODEL_VIEW")
+        if body is None:
+            model = self.file.createIfcGeometricRepresentationContext(
+                ContextType="Model",
+                CoordinateSpaceDimension=3,
+                Precision=1e-5,
+                WorldCoordinateSystem=self.file.createIfcAxis2Placement3D(
+                    self.file.createIfcCartesianPoint((0.0, 0.0, 0.0))
+                ),
+            )
+            body = self.file.createIfcGeometricRepresentationSubContext(
+                ContextIdentifier="Body",
+                ContextType="Model",
+                TargetView="MODEL_VIEW",
+                ParentContext=model,
+            )
+        return body
+
+    def _add_body_rep(self, element):
+        body = self._body_context()
+        rep = ifcopenshell.api.geometry.add_wall_representation(
+            self.file, context=body, length=5.0, height=3.0, thickness=0.2
+        )
+        ifcopenshell.api.geometry.assign_representation(self.file, product=element, representation=rep)
+        return rep
+
+    def test_copy_to_empty_target(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        self._add_body_rep(wall_a)
+
+        result = ifcopenshell.api.geometry.copy_representation(self.file, source=wall_a, target=wall_b)
+
+        assert result is not None
+        assert result.is_a("IfcShapeRepresentation")
+        target_rep = ifcopenshell.util.representation.get_representation(wall_b, "Model", "Body")
+        assert target_rep is not None
+        assert target_rep == result
+
+    def test_source_rep_entities_are_distinct(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        source_rep = self._add_body_rep(wall_a)
+
+        new_rep = ifcopenshell.api.geometry.copy_representation(self.file, source=wall_a, target=wall_b)
+
+        assert new_rep.id() != source_rep.id()
+        assert new_rep.Items[0].id() != source_rep.Items[0].id()
+
+    def test_context_is_shared_not_copied(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        source_rep = self._add_body_rep(wall_a)
+
+        new_rep = ifcopenshell.api.geometry.copy_representation(self.file, source=wall_a, target=wall_b)
+
+        assert new_rep.ContextOfItems.id() == source_rep.ContextOfItems.id()
+
+    def test_replaces_existing_target_rep(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        self._add_body_rep(wall_a)
+        old_rep = self._add_body_rep(wall_b)
+        old_rep_id = old_rep.id()
+
+        ifcopenshell.api.geometry.copy_representation(self.file, source=wall_a, target=wall_b)
+
+        try:
+            self.file.by_id(old_rep_id)
+            assert False, "old representation still exists"
+        except RuntimeError:
+            pass  # entity was removed, as expected
+
+    def test_source_unchanged_after_copy(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        source_rep = self._add_body_rep(wall_a)
+        source_rep_id = source_rep.id()
+
+        ifcopenshell.api.geometry.copy_representation(self.file, source=wall_a, target=wall_b)
+
+        assert self.file.by_id(source_rep_id) is not None  # source must still exist
+        assert ifcopenshell.util.representation.get_representation(wall_a, "Model", "Body") is not None
+
+    def test_returns_none_when_no_matching_rep(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+
+        result = ifcopenshell.api.geometry.copy_representation(self.file, source=wall_a, target=wall_b)
+
+        assert result is None
+
+    def test_custom_context_identifier(self):
+        wall_a = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        wall_b = ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcWall")
+        self._add_body_rep(wall_a)
+
+        # "Axis" doesn't exist on wall_a, so should return None
+        result = ifcopenshell.api.geometry.copy_representation(
+            self.file, source=wall_a, target=wall_b, context_identifier="Axis"
+        )
+
+        assert result is None
+
+
+class TestCopyRepresentationIFC2X3(test.bootstrap.IFC2X3, TestCopyRepresentation):
+    pass

src/ifcopenshell-python/test/api/geometry/test_validate_type.py

@@ -76,7 +76,7 @@ class TestValidateType(test.bootstrap.IFC4):
 
         booleans = ifcopenshell.api.geometry.add_boolean(self.file, first, [second1])
         assert len(booleans) == 1
-        assert len(rep.Items) == 3
+        assert len(rep.Items) == 4
         assert ifcopenshell.api.geometry.validate_type(self.file, rep) is True
         assert len(rep.Items) == 1
         assert rep.RepresentationType == "CSG"
@@ -96,9 +96,9 @@ class TestValidateType(test.bootstrap.IFC4):
 
         booleans = ifcopenshell.api.geometry.add_boolean(self.file, first, [second1])
         assert len(booleans) == 1
-        assert len(rep.Items) == 2
+        assert len(rep.Items) == 3  # boolean replaced first, but second1 stays in Items
         assert ifcopenshell.api.geometry.validate_type(self.file, rep) is False
-        assert len(rep.Items) == 2
+        assert len(rep.Items) == 2  # validate_type unioned second1 into the boolean
         assert rep.RepresentationType is None
 
 

src/ifcopenshell-python/test/api/georeference/test_add_georeferencing.py

@@ -51,6 +51,30 @@ class TestAddGeoreferencing(test.bootstrap.IFC4):
         assert len(self.file.by_type("IfcMapConversion")) == 1
         assert len(self.file.by_type("IfcProjectedCRS")) == 1
 
+    def test_recovering_from_orphan_projected_crs(self):
+        ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcProject")
+        ifcopenshell.api.context.add_context(self.file, "Model")
+        self.file.create_entity("IfcProjectedCRS", Name="EPSG:1234")
+        assert len(self.file.by_type("IfcProjectedCRS")) == 1
+        assert len(self.file.by_type("IfcCoordinateOperation")) == 0
+        ifcopenshell.api.georeference.add_georeferencing(self.file)
+        assert len(self.file.by_type("IfcMapConversion")) == 1
+        assert len(self.file.by_type("IfcProjectedCRS")) == 1
+
+    def test_recovering_from_orphan_coordinate_operation(self):
+        ifcopenshell.api.root.create_entity(self.file, ifc_class="IfcProject")
+        context = ifcopenshell.api.context.add_context(self.file, "Model")
+        self.file.create_entity("IfcMapConversion", SourceCRS=context, TargetCRS=self.file.create_entity("IfcProjectedCRS", Name="EPSG:1234"))
+        ifcopenshell.api.georeference.remove_georeferencing(self.file)
+        # Simulate orphan by re-adding just a conversion without CRS
+        self.file.create_entity("IfcMapConversion", SourceCRS=context, TargetCRS=self.file.create_entity("IfcProjectedCRS", Name="EPSG:1234"))
+        self.file.remove(self.file.by_type("IfcProjectedCRS")[0])
+        assert len(self.file.by_type("IfcProjectedCRS")) == 0
+        assert len(self.file.by_type("IfcCoordinateOperation")) == 1
+        ifcopenshell.api.georeference.add_georeferencing(self.file)
+        assert len(self.file.by_type("IfcMapConversion")) == 1
+        assert len(self.file.by_type("IfcProjectedCRS")) == 1
+
 
 class TestAddGeoreferencingIFC2X3(test.bootstrap.IFC2X3):
     def test_adding_georeferencing(self):

src/ifcopenshell-python/test/api/grid/test_remove_grid_axis.py

@@ -0,0 +1,59 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2021 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import ifcopenshell.api.grid
+import test.bootstrap
+
+
+class TestRemoveGridAxis(test.bootstrap.IFC4):
+    def test_removing_an_axis_removes_its_curve(self):
+        grid = self.file.createIfcGrid()
+        axis = ifcopenshell.api.grid.create_grid_axis(
+            self.file, axis_tag="A", same_sense=True, uvw_axes="UAxes", grid=grid
+        )
+        axis.AxisCurve = self.file.createIfcPolyline([self.file.createIfcCartesianPoint((0.0, 0.0, 0.0))])
+        axis2 = ifcopenshell.api.grid.create_grid_axis(
+            self.file, axis_tag="B", same_sense=True, uvw_axes="UAxes", grid=grid
+        )
+        axis2.AxisCurve = self.file.createIfcPolyline([self.file.createIfcCartesianPoint((1.0, 0.0, 0.0))])
+        ifcopenshell.api.grid.remove_grid_axis(self.file, axis=axis2)
+        assert grid.UAxes == (axis,)
+        assert len(self.file.by_type("IfcGridAxis")) == 1
+        # The curve should be removed since it was only used by the removed axis.
+        assert len(self.file.by_type("IfcPolyline")) == 1
+
+    def test_removing_an_axis_preserves_shared_curve(self):
+        grid = self.file.createIfcGrid()
+        shared_curve = self.file.createIfcPolyline([self.file.createIfcCartesianPoint((0.0, 0.0, 0.0))])
+        axis = ifcopenshell.api.grid.create_grid_axis(
+            self.file, axis_tag="A", same_sense=True, uvw_axes="UAxes", grid=grid
+        )
+        axis.AxisCurve = shared_curve
+        axis2 = ifcopenshell.api.grid.create_grid_axis(
+            self.file, axis_tag="B", same_sense=True, uvw_axes="UAxes", grid=grid
+        )
+        axis2.AxisCurve = shared_curve
+        ifcopenshell.api.grid.remove_grid_axis(self.file, axis=axis2)
+        assert grid.UAxes == (axis,)
+        # The shared curve should be preserved since it's still used by axis.
+        assert shared_curve in self.file
+        assert axis.AxisCurve == shared_curve
+
+
+class TestRemoveGridAxisIFC2X3(test.bootstrap.IFC2X3, TestRemoveGridAxis):
+    pass