solidworks-mcp-python 1.5.0__py3-none-any.whl

solidworks_mcp/adapters/solidworks/documentation.py

@@ -0,0 +1,1476 @@
+"""Model-data mixin for PyWin32 SolidWorks operations.
+
+Covers the engineering data a drawing or BOM is built from: model dimensions,
+measurements, material, custom properties and sheet-metal flat patterns.
+
+Every method name, argument order and enum value below was read from the
+SOLIDWORKS 2025 type libraries (``sldworks.tlb`` via gen_py, ``swconst.tlb``
+via ``pythoncom.LoadTypeLib``), not from memory. Live behaviour is covered by
+``tests/live/test_live_sw_documentation_tools.py``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, cast
+
+import defusedxml.ElementTree as ET
+from defusedxml import DefusedXmlException
+
+from ..base import AdapterResult, AdapterResultStatus
+from . import dimension_layout as _layout
+from .features import _null_callout, _parse_edge_spec, _select_edge_by_coord
+from .io import (
+    _as_com,
+    _byref_bstr,
+    _doc_type,
+    _resolve_drawing_view,
+    _sw_type_info,
+    _view_names,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# swUserPreferenceStringValue_e
+_SW_PREF_MATERIAL_DATABASES = 28
+# swCustomInfoType_e / swCustomPropertyAddOption_e
+_SW_CUSTOM_INFO_TEXT = 30
+_SW_CUSTOM_PROPERTY_REPLACE_VALUE = 2
+# swExportToDWG_e
+_SW_EXPORT_SHEET_METAL = 1
+# swBodyType_e
+_SW_SOLID_BODY = 0
+# swInsertAnnotation_e
+_SW_INSERT_DIMENSIONS = 8
+_SW_INSERT_DIMENSIONS_MARKED_FOR_DRAWING = 32768
+_SW_INSERT_HOLE_WIZARD_LOCATION_DIMS = 131072
+# swImportModelItemsSource_e
+_SW_IMPORT_FROM_ENTIRE_MODEL = 0
+# swAutodimEntities_e / swAutodimScheme_e / placements
+_SW_AUTODIM_ENTITIES_ALL = 1
+_SW_AUTODIM_SCHEME_BASELINE = 1
+_SW_AUTODIM_HORIZONTAL_BELOW = -1
+_SW_AUTODIM_VERTICAL_LEFT = -1
+_SW_AUTODIM_STATUS_SUCCESS = 0
+# swAnnotationType_e
+_SW_ANNOTATION_DISPLAY_DIMENSION = 4
+
+
+def _overlap_summary(result: dict[str, Any]) -> str:
+    """Describe the overlaps ``arrange_dimensions`` could not clear.
+
+    Args:
+        result: The layout result, carrying ``remaining_overlaps``.
+
+    Returns:
+        str: How many overlaps remain, their kinds, the first five, and what
+        to try next.
+    """
+    overlaps = result.get("remaining_overlaps", [])
+    kinds = sorted({o["kind"] for o in overlaps})
+    sample = "; ".join(
+        f"{o['dimension']} vs {o['conflicts_with']} ({o['kind']})" for o in overlaps[:5]
+    )
+    return (
+        f"{result['overlaps_after']} dimension overlap(s) remain after arranging "
+        f"{result['dimensions']} dimension(s) ({', '.join(kinds)}): {sample}. "
+        "Try a smaller sheet scale or a larger sheet so the views have room."
+    )
+
+
+_DEFAULT_MATERIAL_DATABASE = "SOLIDWORKS Materials"
+
+# SelectByID2 entity types accepted by measure_entities, keyed by spec prefix.
+_MEASURE_PREFIXES = {"face": "FACE", "edge": "EDGE", "vertex": "VERTEX"}
+#: Layout passes: one full plan, then re-plans of what is still in conflict.
+_LAYOUT_PASSES = 3
+
+
+def _parse_measure_spec(spec: str) -> tuple[str, float, float, float, str]:
+    """Parse a ``measure_entities`` entity spec into SelectByID2 arguments.
+
+    Accepts the same ``"face:x,y,z"`` / ``"x,y,z"`` / ``"Edge<1>"`` forms as
+    ``add_fillet`` (via :func:`_parse_edge_spec`), plus ``"edge:x,y,z"`` and
+    ``"vertex:x,y,z"``. Coordinates are in metres.
+
+    Args:
+        spec: The entity spec.
+
+    Returns:
+        tuple[str, float, float, float, str]: name, x, y, z and entity type.
+    """
+    prefix, sep, rest = spec.partition(":")
+    kind = _MEASURE_PREFIXES.get(prefix.strip().lower()) if sep else None
+    if kind in {"EDGE", "VERTEX"}:
+        parts = rest.split(",")
+        if len(parts) == 3:
+            try:
+                return "", float(parts[0]), float(parts[1]), float(parts[2]), kind
+            except ValueError:
+                pass
+        return rest, 0.0, 0.0, 0.0, kind
+    return _parse_edge_spec(spec)
+
+
+def _parse_material_library(path: str) -> list[dict[str, str]]:
+    """Read material names and classifications from one ``.sldmat`` file.
+
+    ``.sldmat`` is XML: ``<classification name=...>`` elements hold
+    ``<material name=...>`` children. Tags are matched by local name because
+    the root element carries a namespace. Parsed with ``defusedxml``: library
+    folders can be user-configured, so entity-expansion and external-entity
+    payloads are refused rather than expanded.
+
+    Args:
+        path: Path to the ``.sldmat`` file.
+
+    Returns:
+        list[dict[str, str]]: ``name``, ``classification`` and ``database``
+        for each material; empty when the file cannot be parsed or is refused.
+    """
+    try:
+        root = ET.parse(path).getroot()
+    except (ET.ParseError, OSError, DefusedXmlException):
+        return []
+    database = os.path.splitext(os.path.basename(path))[0]
+    materials: list[dict[str, str]] = []
+    for classification in root.iter():
+        if classification.tag.rsplit("}", 1)[-1] != "classification":
+            continue
+        class_name = classification.get("name", "")
+        for child in classification:
+            if child.tag.rsplit("}", 1)[-1] == "material" and child.get("name"):
+                materials.append(
+                    {
+                        "name": child.get("name", ""),
+                        "classification": class_name,
+                        "database": database,
+                    }
+                )
+    return materials
+
+
+def _unpack_custom_property(raw: Any) -> tuple[str, str]:
+    """Pull (value, resolved value) out of an ``ICustomPropertyManager::Get6`` result.
+
+    Under late binding the out-parameters come back as a tuple that may or may
+    not lead with the integer return code, depending on the pywin32 build.
+
+    Args:
+        raw: Whatever ``Get6`` returned.
+
+    Returns:
+        tuple[str, str]: The raw (possibly ``$PRP:`` linked) value and the
+        resolved value; empty strings when the shape is unrecognised.
+    """
+    if not isinstance(raw, (list, tuple)):
+        return ("", "")
+    items = list(raw)
+    if items and isinstance(items[0], int) and not isinstance(items[0], bool):
+        items = items[1:]
+    strings = [str(item) for item in items if isinstance(item, str)]
+    if not strings:
+        return ("", "")
+    value = strings[0]
+    resolved = strings[1] if len(strings) > 1 else value
+    return (value, resolved)
+
+
+def _read_custom_property(adapter: Any, manager: Any, name: str) -> tuple[str, str]:
+    """Read one custom property's (value, resolved value).
+
+    Tries ``Get6`` (value and resolved value) first; under late binding on
+    SW 2025 its out-parameters raise ``Parameter not optional``, so it falls
+    back to ``Get(name)``, which returns the stored text only.
+
+    Args:
+        adapter: The adapter, for its ``_attempt`` helper.
+        manager: The document's ``ICustomPropertyManager``.
+        name: Property name.
+
+    Returns:
+        tuple[str, str]: The stored value and the resolved value; empty
+        strings when the property cannot be read.
+    """
+    value, resolved = _unpack_custom_property(
+        adapter._attempt(lambda: manager.Get6(name, False), default=None)
+    )
+    if value:
+        return value, resolved
+    plain = adapter._attempt(lambda: manager.Get(name), default=None)
+    text = str(plain) if isinstance(plain, str) else ""
+    return text, text
+
+
+def _read_material(part: Any, configuration: str | None) -> tuple[str, str]:
+    """Read ``(material, database)`` from ``IPartDoc::GetMaterialPropertyName2``.
+
+    ``Database`` is a ``String`` out-parameter: under late binding on SW 2026
+    omitting it raises "Parameter not optional", so it is passed as a byref
+    BSTR and read back from ``.value``. Older pywin32 builds may instead return
+    ``(name, database)`` as a tuple; both shapes are accepted.
+
+    Args:
+        part: The active ``IPartDoc``.
+        configuration: Configuration name; the active one when ``None``.
+
+    Returns:
+        tuple[str, str]: Material name and library; empty strings when unset.
+    """
+    database = _byref_bstr()
+    raw = part.GetMaterialPropertyName2(configuration or "", database)
+    if isinstance(raw, (list, tuple)):
+        strings = [str(s) for s in raw if isinstance(s, str)]
+        name = strings[0] if strings else ""
+        library = strings[1] if len(strings) > 1 else ""
+    else:
+        name = raw if isinstance(raw, str) else ""
+        library = ""
+    stored = getattr(database, "value", "")
+    return name, library or (stored if isinstance(stored, str) else "")
+
+
+def _strip_document_suffix(full_name: Any) -> str | None:
+    """Turn ``"D1@Sketch1@Part10.Part"`` into ``"D1@Sketch1"``.
+
+    Live SW 2025 appends ``@<document title>`` to ``IDimension::FullName``;
+    ``IModelDoc2::Parameter`` (behind ``set_dimension``) takes the short form.
+
+    Args:
+        full_name: ``IDimension::FullName`` as read.
+
+    Returns:
+        str | None: The name without the document suffix; ``None`` when
+        ``full_name`` is not text.
+    """
+    if not isinstance(full_name, str):
+        return None
+    parts = full_name.split("@")
+    if len(parts) >= 3 and "." in parts[-1]:
+        return "@".join(parts[:-1])
+    return full_name
+
+
+def _sequence(raw: Any) -> list[Any]:
+    """Normalise a COM array return (``None``, scalar or tuple) into a list.
+
+    Args:
+        raw: What the COM call returned.
+
+    Returns:
+        list[Any]: The non-``None`` items.
+    """
+    if raw is None:
+        return []
+    if isinstance(raw, (list, tuple)):
+        return [item for item in raw if item is not None]
+    return [raw]
+
+
+class SolidWorksDocumentationMixin:
+    """Expose model-data and drawing-documentation methods through a mixin."""
+
+    if TYPE_CHECKING:
+        currentModel: Any
+        swApp: Any
+
+        def _handle_com_operation(
+            self, operation_name: str, operation: Callable[..., Any], *args: Any
+        ) -> AdapterResult[Any]: ...
+
+        def _attempt(
+            self, operation: Callable[[], Any], default: Any = None
+        ) -> Any: ...
+
+        def _get_attr_or_call(self, obj: Any, name: str) -> Any: ...
+
+        def _require_drawing(self) -> AdapterResult[Any] | None: ...
+
+    def _require_doc_type(
+        self, allowed: set[int], operation: str
+    ) -> AdapterResult[Any] | None:
+        """Return an error result unless the active document type is allowed.
+
+        Args:
+            allowed: Accepted ``swDocumentTypes_e`` values (1 part, 2 assembly,
+                3 drawing).
+            operation: Operation name for the error message.
+
+        Returns:
+            AdapterResult[Any] | None: ``None`` when allowed, else the error.
+        """
+        if not self.currentModel:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR, error="No active model"
+            )
+        names = {1: "part", 2: "assembly", 3: "drawing"}
+        doc_type = _doc_type(self)
+        if doc_type not in allowed:
+            wanted = " or ".join(names[t] for t in sorted(allowed))
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR,
+                error=(
+                    f"{operation} needs an active {wanted} document "
+                    f"(active document is {names.get(doc_type or 0, 'unknown')})."
+                ),
+            )
+        return None
+
+    # ------------------------------------------------------------------
+    # Model data
+    # ------------------------------------------------------------------
+
+    async def list_model_dimensions(
+        self, feature_name: str | None = None
+    ) -> AdapterResult[list[dict[str, Any]]]:
+        """List every dimension in the active part or assembly.
+
+        Walks ``IModelDoc2::FirstFeature`` / ``IFeature::GetNextFeature`` and
+        each feature's ``GetFirstDisplayDimension`` chain. ``full_name`` (e.g.
+        ``"D1@Sketch1"``) is the name ``set_dimension`` accepts, so the pair
+        gives edit-by-name access to every driving parameter in the model.
+
+        Args:
+            feature_name: Only list dimensions of this feature (case-insensitive).
+
+        Returns:
+            AdapterResult[list[dict[str, Any]]]: ``full_name``, ``feature``,
+            ``value`` (document units), ``system_value`` (metres / radians)
+            and ``read_only`` per dimension.
+        """
+        guard = self._require_doc_type({1, 2}, "list_model_dimensions")
+        if guard is not None:
+            return cast("AdapterResult[list[dict[str, Any]]]", guard)
+        target = (feature_name or "").strip().lower()
+
+        def _list() -> list[dict[str, Any]]:
+            model = self.currentModel
+            dims: list[dict[str, Any]] = []
+            feature = self._attempt(lambda: model.FirstFeature(), default=None)
+            guard_count = 0
+            while feature is not None and guard_count < 20000:
+                guard_count += 1
+                feat = _sw_type_info.flagged(feature, "IFeature")
+                name = str(self._attempt(lambda f=feat: f.Name, default="") or "")
+                if not target or name.lower() == target:
+                    display = self._attempt(
+                        lambda f=feat: f.GetFirstDisplayDimension(), default=None
+                    )
+                    while display is not None:
+                        disp = _sw_type_info.flagged(display, "IDisplayDimension")
+                        dim = self._attempt(
+                            lambda d=disp: d.GetDimension2(0), default=None
+                        )
+                        if dim is not None:
+                            dim = _sw_type_info.flagged(dim, "IDimension")
+                            dims.append(
+                                {
+                                    "full_name": _strip_document_suffix(
+                                        self._attempt(
+                                            lambda d=dim: d.FullName, default=None
+                                        )
+                                    ),
+                                    "feature": name,
+                                    "value": self._attempt(
+                                        lambda d=dim: d.Value, default=None
+                                    ),
+                                    "system_value": self._attempt(
+                                        lambda d=dim: d.SystemValue, default=None
+                                    ),
+                                    "read_only": bool(
+                                        self._attempt(
+                                            lambda d=dim: d.ReadOnly, default=False
+                                        )
+                                    ),
+                                }
+                            )
+                        display = self._attempt(
+                            lambda f=feat, d=display: f.GetNextDisplayDimension(d),
+                            default=None,
+                        )
+                feature = self._attempt(lambda f=feat: f.GetNextFeature(), default=None)
+            if target and not dims:
+                raise LookupError(
+                    f"No dimensions found on feature {feature_name!r}; list "
+                    "the feature tree with list_features for exact names"
+                )
+            return dims
+
+        return cast(
+            "AdapterResult[list[dict[str, Any]]]",
+            self._handle_com_operation("list_model_dimensions", _list),
+        )
+
+    async def measure_entities(
+        self, entities: list[str]
+    ) -> AdapterResult[dict[str, Any]]:
+        """Measure one or more entities with SolidWorks' Measure tool.
+
+        Selects each entity by spec (see :func:`_parse_measure_spec`), then runs
+        ``IModelDocExtension::CreateMeasure`` + ``IMeasure::Calculate(None)``,
+        which measures the current selection. Values SolidWorks reports as
+        ``-1`` (not applicable to the selection) are dropped.
+
+        Args:
+            entities: One or two entity specs, e.g. ``["face:0,0.01,0"]`` for a
+                face area, or two edge/face specs for distance and angle.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: Measured values in metres, square
+            metres and radians, plus ``selected``; ``is_parallel`` only for
+            two entities.
+        """
+        guard = self._require_doc_type({1, 2}, "measure_entities")
+        if guard is not None:
+            return cast("AdapterResult[dict[str, Any]]", guard)
+        if not entities or len(entities) > 2:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR,
+                error="measure_entities takes one or two entity specs",
+            )
+
+        def _measure() -> dict[str, Any]:
+            model = self.currentModel
+            self._attempt(lambda: model.ClearSelection2(True), default=None)
+            for index, spec in enumerate(entities):
+                name, x, y, z, kind = _parse_measure_spec(spec)
+                append = index > 0
+                if name:
+                    ok = bool(
+                        self._attempt(
+                            lambda n=name, k=kind, a=append: (
+                                model.Extension.SelectByID2(
+                                    n, k, 0.0, 0.0, 0.0, a, 0, _null_callout(), 0
+                                )
+                            ),
+                            default=False,
+                        )
+                    )
+                else:
+                    ok = _select_edge_by_coord(self, x, y, z, append, 0, kind)
+                if not ok:
+                    raise LookupError(
+                        f"No entity found for {spec!r}; check the name or the "
+                        "coordinates (metres)"
+                    )
+
+            # CreateMeasure is a zero-arg method; unflagged, late binding asks
+            # for it as a property and SW 2026 answers "Member not found".
+            # Not wrapped in _attempt: a COM error surfaces with its message.
+            extension = _sw_type_info.flagged(model.Extension, "IModelDocExtension")
+            measure = extension.CreateMeasure()
+            if measure is None:
+                raise Exception("CreateMeasure returned nothing")
+            measure = _sw_type_info.flagged(measure, "IMeasure")
+            if not measure.Calculate(None):
+                raise Exception("IMeasure.Calculate failed for this selection")
+
+            result: dict[str, Any] = {"selected": list(entities)}
+            for prop, key in (
+                ("Distance", "distance_m"),
+                ("CenterDistance", "center_distance_m"),
+                ("Angle", "angle_rad"),
+                ("Radius", "radius_m"),
+                ("Diameter", "diameter_m"),
+                ("Length", "length_m"),
+                ("ArcLength", "arc_length_m"),
+                ("Area", "area_m2"),
+                ("Perimeter", "perimeter_m"),
+                ("DeltaX", "delta_x_m"),
+                ("DeltaY", "delta_y_m"),
+                ("DeltaZ", "delta_z_m"),
+            ):
+                value = self._attempt(lambda p=prop: getattr(measure, p), default=None)
+                if isinstance(value, (int, float)) and value != -1:
+                    result[key] = float(value)
+            if len(entities) == 2:
+                # Parallelism only means something between two entities.
+                parallel = self._attempt(lambda: measure.IsParallel, default=None)
+                if isinstance(parallel, bool):
+                    result["is_parallel"] = parallel
+            self._attempt(lambda: model.ClearSelection2(True), default=None)
+            return result
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("measure_entities", _measure),
+        )
+
+    async def get_material(
+        self, configuration: str | None = None
+    ) -> AdapterResult[dict[str, Any]]:
+        """Read the material assigned to the active part.
+
+        Wraps ``IPartDoc::GetMaterialPropertyName2``; see
+        :func:`_read_material` for its ``Database`` out-parameter.
+
+        Args:
+            configuration: Configuration name; the active one when omitted.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: ``material`` (``None`` when unset)
+            and ``database``.
+        """
+        guard = self._require_doc_type({1}, "get_material")
+        if guard is not None:
+            return cast("AdapterResult[dict[str, Any]]", guard)
+
+        def _get() -> dict[str, Any]:
+            part = _sw_type_info.flagged(self.currentModel, "IPartDoc")
+            name, database = _read_material(part, configuration)
+            return {
+                "material": name or None,
+                "database": database or None,
+                "configuration": configuration,
+            }
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("get_material", _get),
+        )
+
+    async def set_material(
+        self,
+        material_name: str,
+        database: str | None = None,
+        configuration: str | None = None,
+    ) -> AdapterResult[dict[str, Any]]:
+        """Assign a material to the active part.
+
+        Wraps ``IPartDoc::SetMaterialPropertyName2`` (a ``void`` call), then
+        reads the material back - the read-back is the only proof it applied.
+        A name the library does not hold leaves the part unchanged and is
+        reported as not found.
+
+        Args:
+            material_name: Material name exactly as in the library, e.g.
+                ``"AISI 1020"`` or ``"6061-T6 (SS)"``.
+            database: Library name; ``"SOLIDWORKS Materials"`` when omitted.
+            configuration: Configuration name; ``""`` (all) when omitted.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: Requested and applied material.
+        """
+        guard = self._require_doc_type({1}, "set_material")
+        if guard is not None:
+            return cast("AdapterResult[dict[str, Any]]", guard)
+        if not material_name.strip():
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR, error="material_name is required"
+            )
+        library = database or _DEFAULT_MATERIAL_DATABASE
+
+        def _set() -> dict[str, Any]:
+            part = _sw_type_info.flagged(self.currentModel, "IPartDoc")
+            part.SetMaterialPropertyName2(configuration or "", library, material_name)
+            self._attempt(lambda: self.currentModel.EditRebuild3(), default=None)
+            applied, _library = _read_material(part, configuration)
+            if applied.lower() != material_name.lower():
+                # SolidWorks ignores a name its library does not hold.
+                raise LookupError(
+                    f"Material {material_name!r} not found in {library!r}; the "
+                    f"part still reports {applied or 'no material'}. Use "
+                    "list_available_materials for the exact name and library."
+                )
+            return {
+                "material": applied,
+                "database": library,
+                "configuration": configuration,
+            }
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("set_material", _set),
+        )
+
+    async def list_available_materials(
+        self, search: str | None = None
+    ) -> AdapterResult[list[dict[str, str]]]:
+        """List materials from the configured SolidWorks material libraries.
+
+        Reads the custom library folders from
+        ``swFileLocationsMaterialDatabases`` (a ``;``-separated list) plus the
+        install's built-in ``sldmaterials`` folder, and parses every
+        ``.sldmat`` file in them.
+
+        Args:
+            search: Case-insensitive substring filter on name or classification.
+
+        Returns:
+            AdapterResult[list[dict[str, str]]]: ``name``, ``classification``
+            and ``database`` per material. ``metadata`` gives the ``folders``
+            read and the ``total`` before filtering, so an empty search can be
+            told apart from an unexpected library location.
+        """
+        app = getattr(self, "swApp", None)
+        if app is None:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR, error="Not connected to SolidWorks"
+            )
+        needle = (search or "").strip().lower()
+        searched: dict[str, Any] = {}
+
+        def _list() -> list[dict[str, str]]:
+            configured = str(
+                self._attempt(
+                    lambda: app.GetUserPreferenceStringValue(
+                        _SW_PREF_MATERIAL_DATABASES
+                    ),
+                    default="",
+                )
+                or ""
+            )
+            # swFileLocationsMaterialDatabases lists only the folders the user
+            # added: "" on a fresh SW 2025 install, just "Custom Materials" on
+            # SW 2026 (both measured live). SolidWorks always shows its
+            # built-in <install>\lang\<language>\sldmaterials library as
+            # well, so read that too.
+            exe_dir = str(
+                self._attempt(lambda: app.GetExecutablePath(), default="") or ""
+            )
+            language = str(
+                self._attempt(lambda: app.GetCurrentLanguage(), default="") or "english"
+            )
+            if exe_dir.lower().endswith(".exe"):
+                exe_dir = os.path.dirname(exe_dir)
+            built_in = os.path.join(exe_dir, "lang", language, "sldmaterials")
+            folder_list = [f.strip() for f in configured.split(";") if f.strip()]
+            if os.path.normcase(built_in) not in map(os.path.normcase, folder_list):
+                folder_list.append(built_in)
+            folders = ";".join(folder_list)
+            materials: list[dict[str, str]] = []
+            for folder in folder_list:
+                if not os.path.isdir(folder):
+                    continue
+                for entry in sorted(os.listdir(folder)):
+                    if entry.lower().endswith(".sldmat"):
+                        materials.extend(
+                            _parse_material_library(os.path.join(folder, entry))
+                        )
+            searched["folders"] = folder_list
+            searched["total"] = len(materials)
+            if not materials:
+                raise LookupError(f"No .sldmat libraries found in: {folders}")
+            if needle:
+                materials = [
+                    m
+                    for m in materials
+                    if needle in m["name"].lower()
+                    or needle in m["classification"].lower()
+                ]
+            return materials
+
+        result = cast(
+            "AdapterResult[list[dict[str, str]]]",
+            self._handle_com_operation("list_available_materials", _list),
+        )
+        if result.is_success:
+            result.metadata = dict(searched)
+        return result
+
+    async def get_custom_properties(
+        self, configuration: str | None = None
+    ) -> AdapterResult[dict[str, Any]]:
+        """Read the custom properties of the active document.
+
+        Wraps ``IModelDocExtension::CustomPropertyManager(config)`` with
+        ``GetNames`` + ``Get6``. ``""`` reads the file-level properties a
+        drawing title block usually links to.
+
+        Args:
+            configuration: Configuration name; file-level when omitted.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: ``properties`` mapping name to
+            ``{"value", "resolved"}``.
+        """
+        if not self.currentModel:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR, error="No active model"
+            )
+
+        def _get() -> dict[str, Any]:
+            manager = _sw_type_info.flagged(
+                self.currentModel.Extension.CustomPropertyManager(configuration or ""),
+                "ICustomPropertyManager",
+            )
+            props: dict[str, dict[str, str]] = {}
+            names = self._attempt(
+                lambda: self._get_attr_or_call(manager, "GetNames"), default=None
+            )
+            for name in _sequence(names):
+                value, resolved = _read_custom_property(self, manager, str(name))
+                props[str(name)] = {"value": value, "resolved": resolved}
+            return {"configuration": configuration or "", "properties": props}
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("get_custom_properties", _get),
+        )
+
+    async def set_custom_property(
+        self, name: str, value: str, configuration: str | None = None
+    ) -> AdapterResult[dict[str, Any]]:
+        """Create or overwrite one text custom property on the active document.
+
+        Wraps ``ICustomPropertyManager::Add3(name, swCustomInfoText, value,
+        swCustomPropertyReplaceValue)`` and reads the value back.
+
+        Args:
+            name: Property name, e.g. ``"PartNo"`` or ``"DrawnBy"``.
+            value: Text value; may be a ``$PRP:"..."`` link.
+            configuration: Configuration name; file-level when omitted.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: The stored and resolved value.
+        """
+        if not self.currentModel:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR, error="No active model"
+            )
+        if not name.strip():
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR, error="name is required"
+            )
+
+        def _set() -> dict[str, Any]:
+            manager = _sw_type_info.flagged(
+                self.currentModel.Extension.CustomPropertyManager(configuration or ""),
+                "ICustomPropertyManager",
+            )
+            code = manager.Add3(
+                name,
+                _SW_CUSTOM_INFO_TEXT,
+                str(value),
+                _SW_CUSTOM_PROPERTY_REPLACE_VALUE,
+            )
+            stored, resolved = _read_custom_property(self, manager, name)
+            if stored != str(value):
+                raise Exception(
+                    f"Custom property {name!r} was not stored (Add3 returned {code!r}, "
+                    f"read back {stored!r})."
+                )
+            return {
+                "name": name,
+                "value": stored,
+                "resolved": resolved,
+                "configuration": configuration or "",
+            }
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("set_custom_property", _set),
+        )
+
+    async def export_flat_pattern(
+        self, file_path: str
+    ) -> AdapterResult[dict[str, Any]]:
+        """Export the active sheet-metal part's flat pattern to DXF or DWG.
+
+        Wraps ``IPartDoc::ExportToDWG2`` with ``swExportToDWG_ExportSheetMetal``.
+        SheetMetalOptions ``1`` exports the flat-pattern geometry only (no bend
+        lines or sketches).
+
+        Args:
+            file_path: Output ``.dxf`` or ``.dwg`` path.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: The written path and its size.
+        """
+        guard = self._require_doc_type({1}, "export_flat_pattern")
+        if guard is not None:
+            return cast("AdapterResult[dict[str, Any]]", guard)
+        out = os.path.abspath(file_path)
+        if os.path.splitext(out)[1].lower() not in {".dxf", ".dwg"}:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR,
+                error="file_path must end in .dxf or .dwg",
+            )
+
+        def _export() -> dict[str, Any]:
+            model = self.currentModel
+            part = _sw_type_info.flagged(model, "IPartDoc")
+            bodies = _sequence(
+                self._attempt(
+                    lambda: part.GetBodies2(_SW_SOLID_BODY, True), default=None
+                )
+            )
+            if not any(
+                self._attempt(
+                    lambda b=b: _as_com(self, b, "IBody2").IsSheetMetal(), default=False
+                )
+                for b in bodies
+            ):
+                raise LookupError(
+                    "The active part has no sheet-metal body, so it has no flat "
+                    "pattern to export"
+                )
+            os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+            model_path = str(
+                self._attempt(lambda: model.GetPathName(), default="") or ""
+            )
+            ok = part.ExportToDWG2(
+                out,
+                model_path,
+                _SW_EXPORT_SHEET_METAL,
+                True,
+                None,
+                False,
+                False,
+                1,
+                None,
+            )
+            if not ok or not os.path.exists(out):
+                raise Exception(f"ExportToDWG2 did not write {out} (returned {ok!r})")
+            return {"file_path": out, "size_bytes": os.path.getsize(out)}
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("export_flat_pattern", _export),
+        )
+
+    # ------------------------------------------------------------------
+    # Drawing documentation
+    # ------------------------------------------------------------------
+
+    def _view_dimension_count(self, view: Any) -> int:
+        """Count the display dimensions on a drawing view.
+
+        Args:
+            view: The ``IView``.
+
+        Returns:
+            int: ``IView::GetDisplayDimensionCount``; 0 when unreadable.
+        """
+        count = self._attempt(lambda: view.GetDisplayDimensionCount(), default=0)
+        return int(count) if isinstance(count, (int, float)) else 0
+
+    def _pictorial(self, view: Any) -> bool:
+        """True for isometric/dimetric/trimetric views, which are not dimensioned.
+
+        Args:
+            view: The ``IView``.
+
+        Returns:
+            bool: Whether the view's orientation name is pictorial.
+        """
+        name = str(self._attempt(lambda: view.GetOrientationName(), default="") or "")
+        return any(k in name.lower() for k in ("isometric", "dimetric", "trimetric"))
+
+    def _delete_display_dimension(self, model: Any, an: Any) -> bool:
+        """Delete one drawing dimension.
+
+        ``IAnnotation::Select3`` selects nothing under late binding (False with
+        a null dispatch, type mismatch with ``None``); selecting by
+        ``IDisplayDimension::GetNameForSelection`` with type ``DIMENSION`` and
+        ``DeleteSelection2`` works - measured live on SW 2025 (pitfall #30).
+
+        Args:
+            model: The drawing document.
+            an: The dimension's ``IAnnotation``.
+
+        Returns:
+            bool: Whether it was selected and deleted.
+        """
+        selected = self._select_display_dimension(model, an)
+        deleted = selected and bool(
+            self._attempt(lambda: model.Extension.DeleteSelection2(0), default=False)
+        )
+        self._attempt(lambda: model.ClearSelection2(True), default=None)
+        return deleted
+
+    def _select_display_dimension(self, model: Any, an: Any) -> bool:
+        """Select one drawing dimension, alone (pitfall #30: by its selection name).
+
+        Args:
+            model: The drawing document.
+            an: The dimension's ``IAnnotation``.
+
+        Returns:
+            bool: Whether it is now the selection.
+        """
+        specific = self._attempt(lambda: an.GetSpecificAnnotation(), default=None)
+        disp = (
+            _as_com(self, specific, "IDisplayDimension")
+            if specific is not None
+            else None
+        )
+        sel_name = (
+            self._attempt(lambda: disp.GetNameForSelection(), default=None)
+            if disp
+            else None
+        )
+        if not sel_name:
+            return False
+        self._attempt(lambda: model.ClearSelection2(True), default=None)
+        return bool(
+            self._attempt(
+                lambda: model.Extension.SelectByID2(
+                    sel_name, "DIMENSION", 0.0, 0.0, 0.0, False, 0, _null_callout(), 0
+                ),
+                default=False,
+            )
+        )
+
+    def _dimension_annotations(self, view: Any) -> list[tuple[Any, str | None]]:
+        """List the display dimensions in a view with their model names.
+
+        Args:
+            view: The ``IView``.
+
+        Returns:
+            list[tuple[Any, str | None]]: ``(IAnnotation, "D1@Sketch1")`` per
+            dimension; the name is ``None`` when it cannot be read.
+        """
+        found: list[tuple[Any, str | None]] = []
+        ann = self._attempt(lambda: view.GetFirstAnnotation3(), default=None)
+        guard = 0
+        while ann is not None and guard < 2000:
+            guard += 1
+            an = _sw_type_info.flagged(ann, "IAnnotation")
+            if self._attempt(lambda a=an: a.GetType(), default=None) == (
+                _SW_ANNOTATION_DISPLAY_DIMENSION
+            ):
+                specific = self._attempt(
+                    lambda a=an: a.GetSpecificAnnotation(), default=None
+                )
+                name = None
+                if specific is not None:
+                    disp = _sw_type_info.flagged(specific, "IDisplayDimension")
+                    dim = self._attempt(lambda d=disp: d.GetDimension2(0), default=None)
+                    if dim is not None:
+                        name = _strip_document_suffix(
+                            self._attempt(
+                                lambda d=dim: (
+                                    _sw_type_info.flagged(d, "IDimension").FullName
+                                ),
+                                default=None,
+                            )
+                        )
+                found.append((an, name))
+            ann = self._attempt(lambda a=an: a.GetNext3(), default=None)
+        return found
+
+    def _import_dimensions(
+        self,
+        view_name: str | None = None,
+        include_hole_wizard: bool = True,
+        only_views: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Import model dimensions into views; the body of insert_model_dimensions.
+
+        Args:
+            view_name: One view; every orthographic view when ``None``.
+            include_hole_wizard: Also import Hole Wizard location dimensions.
+            only_views: Exactly these views (the standard drawing's layout).
+
+        Returns:
+            dict[str, Any]: Per-view counts and what was done; see
+            :meth:`insert_model_dimensions`.
+
+        Raises:
+            LookupError: ``view_name`` is not on the drawing, or there is no
+                view to dimension.
+            Exception: Nothing could be imported or auto-dimensioned.
+        """
+        model = self.currentModel
+        drawing = _sw_type_info.flagged(model, "IDrawingDoc")
+        all_names = _view_names(self, drawing)
+        if view_name and view_name not in all_names:
+            raise LookupError(
+                f"No view named {view_name!r}. Views: {', '.join(all_names) or 'none'}"
+            )
+        views = {n: _resolve_drawing_view(self, drawing, n) for n in all_names}
+        skipped = (
+            [] if view_name else [n for n, v in views.items() if self._pictorial(v)]
+        )
+        names = [view_name] if view_name else [n for n in all_names if n not in skipped]
+        if only_views:
+            names = [n for n in only_views if n in all_names]
+        if not names:
+            raise LookupError(
+                "No drawing views found to dimension (pictorial views are skipped "
+                "unless named); add views with create_technical_drawing or "
+                "create_drawing_view"
+            )
+        before = {n: self._view_dimension_count(views[n]) for n in names}
+
+        types = _SW_INSERT_DIMENSIONS_MARKED_FOR_DRAWING
+        if include_hole_wizard:
+            types |= _SW_INSERT_HOLE_WIZARD_LOCATION_DIMS
+        # Dimensions already on the sheet (any view) count as shown.
+        shown: set[str] = set()
+        for name in all_names:
+            if name in names:
+                continue
+            shown.update(n for _, n in self._dimension_annotations(views[name]) if n)
+        removed: dict[str, int] = {}
+        method = "insert_model_annotations"
+        imported: dict[str, list[tuple[Any, str | None]]] = {}
+        for name in names:
+            self._attempt(lambda n=name: drawing.ActivateView(n), default=None)
+            self._attempt(lambda: model.ClearSelection2(True), default=None)
+            self._attempt(
+                lambda n=name: model.Extension.SelectByID2(
+                    n, "DRAWINGVIEW", 0.0, 0.0, 0.0, False, 0, _null_callout(), 0
+                ),
+                default=None,
+            )
+            self._attempt(
+                lambda: drawing.InsertModelAnnotations3(
+                    _SW_IMPORT_FROM_ENTIRE_MODEL, types, False, False, False, False
+                ),
+                default=None,
+            )
+            self._attempt(lambda: model.ClearSelection2(True), default=None)
+            imported[name] = self._dimension_annotations(views[name])
+        # Each dimension stays in the view that took the most dimensions: the
+        # one that shows the sketch's true shape (a sketch on the Top plane is
+        # dimensioned in the plan, not projected edge-on into the front view,
+        # where holes stack up). Ties keep the view order.
+        for name in sorted(names, key=lambda n: -len(imported[n])):
+            removed[name] = 0
+            for an, dim_name in imported[name]:
+                if dim_name and dim_name in shown:
+                    if self._delete_display_dimension(model, an):
+                        removed[name] += 1
+                elif dim_name:
+                    shown.add(dim_name)
+        self._attempt(lambda: model.ClearSelection2(True), default=None)
+        self._attempt(lambda: model.EditRebuild3(), default=None)
+
+        autodim_status: Any = None
+        if not shown and all(self._view_dimension_count(views[n]) == 0 for n in names):
+            method = "auto_dimension"
+            for name in names:
+                self._attempt(lambda: model.ClearSelection2(True), default=None)
+                self._attempt(
+                    lambda n=name: model.Extension.SelectByID2(
+                        n,
+                        "DRAWINGVIEW",
+                        0.0,
+                        0.0,
+                        0.0,
+                        False,
+                        0,
+                        _null_callout(),
+                        0,
+                    ),
+                    default=None,
+                )
+                autodim_status = self._attempt(
+                    lambda: drawing.AutoDimension(
+                        _SW_AUTODIM_ENTITIES_ALL,
+                        _SW_AUTODIM_SCHEME_BASELINE,
+                        _SW_AUTODIM_HORIZONTAL_BELOW,
+                        _SW_AUTODIM_SCHEME_BASELINE,
+                        _SW_AUTODIM_VERTICAL_LEFT,
+                    ),
+                    default=None,
+                )
+            self._attempt(lambda: model.ClearSelection2(True), default=None)
+            self._attempt(lambda: model.EditRebuild3(), default=None)
+
+        per_view = []
+        for name in names:
+            after = self._view_dimension_count(views[name])
+            per_view.append(
+                {
+                    "view": name,
+                    "dimensions_before": before[name],
+                    "dimensions_after": after,
+                    "dimensions_added": after - before[name],
+                    "duplicates_removed": removed.get(name, 0),
+                }
+            )
+        total = sum(v["dimensions_added"] for v in per_view)
+        on_sheet = sum(v["dimensions_after"] for v in per_view)
+        if on_sheet == 0:
+            raise Exception(
+                "No dimensions were added to any view: InsertModelAnnotations3 "
+                f"imported nothing and AutoDimension returned {autodim_status!r} "
+                "(0 = success). See com-api-pitfalls #18."
+            )
+        return {
+            "views": per_view,
+            "dimensions_added": total,
+            "unique_dimensions": len(shown),
+            "skipped_pictorial_views": skipped,
+            "method": method,
+            "autodimension_status": autodim_status,
+        }
+
+    async def insert_model_dimensions(
+        self, view_name: str | None = None, include_hole_wizard: bool = True
+    ) -> AdapterResult[dict[str, Any]]:
+        """Bring model dimensions into drawing views, each dimension shown once.
+
+        Imports the model's "marked for drawing" dimensions view by view with
+        ``IDrawingDoc::InsertModelAnnotations3`` (``UsePlacementInSketch`` off,
+        so SolidWorks places them rather than copying sketch positions).
+        Drafting rules applied:
+
+        * pictorial views (isometric, dimetric, trimetric) are not dimensioned
+          unless named explicitly;
+        * a model dimension already shown in an earlier view is deleted from
+          later views, so each dimension appears exactly once on the sheet.
+
+        Falls back to ``IDrawingDoc::AutoDimension`` only when nothing at all
+        could be imported. Placement is then made overlap-free by
+        :meth:`arrange_dimensions`.
+
+        Args:
+            view_name: One view to dimension; every orthographic view when omitted.
+            include_hole_wizard: Also import Hole Wizard location dimensions.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: Per-view counts, duplicates removed,
+            skipped pictorial views and the ``method`` used.
+        """
+        guard = self._require_drawing()
+        if guard is not None:
+            return cast("AdapterResult[dict[str, Any]]", guard)
+
+        def _insert() -> dict[str, Any]:
+            return self._import_dimensions(view_name, include_hole_wizard)
+
+        return cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("insert_model_dimensions", _insert),
+        )
+
+    # ------------------------------------------------------------------
+    # Dimension layout: no dimension may overlap another
+    # ------------------------------------------------------------------
+
+    def _read_view_dimensions(self, view: Any, view_name: str) -> list[tuple[Any, Any]]:
+        """Return ``(annotation, DimensionGeometry)`` for every dimension in a view.
+
+        Geometry comes from ``IAnnotation::GetDisplayData``: text boxes from
+        ``GetTextPositionAtIndex`` (lower-left) with the larger of
+        ``GetTextInBoxWidthAtIndex`` and a width estimated from the text and
+        ``GetTextHeightAtIndex``, turned by ``GetTextAngleAtIndex`` (a vertical
+        dimension's text runs up the sheet); lines from ``GetLineAtIndex3``, whose
+        endpoints are elements 4-5 and 7-8 of the returned tuple (measured
+        live on SW 2025).
+
+        Args:
+            view: The ``IView``.
+            view_name: Its name, used in each dimension's key.
+
+        Returns:
+            list[tuple[Any, Any]]: ``(IAnnotation, DimensionGeometry)`` pairs.
+        """
+        found: list[tuple[Any, Any]] = []
+        ann = self._attempt(lambda: view.GetFirstAnnotation3(), default=None)
+        index = 0
+        while ann is not None and index < 2000:
+            an = _sw_type_info.flagged(ann, "IAnnotation")
+            kind = self._attempt(lambda a=an: a.GetType(), default=None)
+            if kind == _SW_ANNOTATION_DISPLAY_DIMENSION:
+                geometry = self._dimension_geometry(
+                    an, f"{view_name}#{index}", view_name
+                )
+                if geometry is not None:
+                    found.append((an, geometry))
+                index += 1
+            ann = self._attempt(lambda a=an: a.GetNext3(), default=None)
+        return found
+
+    def _dimension_geometry(self, an: Any, key: str, view_name: str) -> Any:
+        """Read one dimension's text box and lines from its display data.
+
+        Args:
+            an: The dimension's ``IAnnotation``.
+            key: Stable key for the layout (view name + index).
+            view_name: The owning view.
+
+        Returns:
+            Any: A ``DimensionGeometry``, or ``None`` when the position or any
+            text cannot be read.
+        """
+        position = self._attempt(lambda: an.GetPosition(), default=None)
+        data = self._attempt(lambda: an.GetDisplayData(), default=None)
+        if not isinstance(position, (list, tuple)) or data is None:
+            return None
+        dd = _sw_type_info.flagged(data, "IDisplayData")
+        boxes: list[tuple[float, float, float, float]] = []
+        for i in range(int(self._attempt(lambda: dd.GetTextCount(), default=0) or 0)):
+            pos = self._attempt(lambda i=i: dd.GetTextPositionAtIndex(i), default=None)
+            if not isinstance(pos, (list, tuple)) or len(pos) < 2:
+                continue
+            text = str(
+                self._attempt(lambda i=i: dd.GetTextAtIndex(i), default="") or ""
+            )
+            height = float(
+                self._attempt(lambda i=i: dd.GetTextHeightAtIndex(i), default=0.0)
+                or 0.0
+            )
+            box_w = float(
+                self._attempt(lambda i=i: dd.GetTextInBoxWidthAtIndex(i), default=0.0)
+                or 0.0
+            )
+            angle = float(
+                self._attempt(lambda i=i: dd.GetTextAngleAtIndex(i), default=0.0) or 0.0
+            )
+            width = max(box_w, _layout.shown_length(text) * height * 0.62)
+            boxes.append(
+                _layout.text_box(pos[0], pos[1], width, max(height, 0.001), angle)
+            )
+        if not boxes:
+            return None
+        text_box = (
+            min(b[0] for b in boxes),
+            min(b[1] for b in boxes),
+            max(b[2] for b in boxes),
+            max(b[3] for b in boxes),
+        )
+        lines = []
+        for i in range(int(self._attempt(lambda: dd.GetLineCount(), default=0) or 0)):
+            raw = self._attempt(lambda i=i: dd.GetLineAtIndex3(i), default=None)
+            if isinstance(raw, (list, tuple)) and len(raw) >= 9:
+                lines.append(
+                    (float(raw[4]), float(raw[5]), float(raw[7]), float(raw[8]))
+                )
+        return _layout.DimensionGeometry(
+            key=key,
+            view=view_name,
+            text_box=text_box,
+            position=(float(position[0]), float(position[1])),
+            lines=lines,
+        )
+
+    def _sheet_bounds(self, drawing: Any) -> Any:
+        """Sheet rectangle from ``ISheet::GetProperties2`` (width/height at 5, 6).
+
+        Args:
+            drawing: The ``IDrawingDoc``.
+
+        Returns:
+            Any: ``(0, 0, width, height)`` in metres, or ``None`` when unreadable.
+        """
+        sheet = self._attempt(lambda: drawing.GetCurrentSheet(), default=None)
+        if sheet is None:
+            return None
+        props = self._attempt(
+            lambda: _sw_type_info.flagged(sheet, "ISheet").GetProperties2(),
+            default=None,
+        )
+        if isinstance(props, (list, tuple)) and len(props) >= 7:
+            width, height = props[5], props[6]
+            if (
+                isinstance(width, (int, float))
+                and isinstance(height, (int, float))
+                and width > 0
+            ):
+                return (0.0, 0.0, float(width), float(height))
+        return None
+
+    def _collect_layout(
+        self, drawing: Any, names: list[str]
+    ) -> tuple[dict, list, dict]:
+        """Read every named view's outline and dimension geometry.
+
+        Args:
+            drawing: The ``IDrawingDoc``.
+            names: View names to read.
+
+        Returns:
+            tuple[dict, list, dict]: View outlines by name, every
+            ``DimensionGeometry``, and each geometry key's ``IAnnotation``.
+        """
+        outlines: dict[str, tuple[float, float, float, float]] = {}
+        annotations: dict[str, Any] = {}
+        geometries: list[Any] = []
+        for name in names:
+            view = _resolve_drawing_view(self, drawing, name)
+            if view is None:
+                continue
+            outline = self._attempt(lambda v=view: v.GetOutline(), default=None)
+            if isinstance(outline, (list, tuple)) and len(outline) >= 4:
+                outlines[name] = tuple(float(c) for c in outline[:4])
+            for an, geometry in self._read_view_dimensions(view, name):
+                annotations[geometry.key] = an
+                geometries.append(geometry)
+        return outlines, geometries, annotations
+
+    def _arrange_layout(
+        self,
+        view_name: str | None = None,
+        obstacles: dict[str, Any] | None = None,
+        work_area: Any = None,
+        move: bool = True,
+        attached: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Plan, apply and verify the dimension layout; arrange_dimensions' body.
+
+        Args:
+            view_name: Only move this view's dimensions; all when ``None``.
+            obstacles: Named boxes nothing may touch (title block, captions).
+            work_area: The frame's working area; the sheet when ``None``.
+            move: ``False`` only checks the current layout.
+            attached: Dimension key -> box hanging off it (a GD&T frame),
+                relative to its position; counted as part of its text.
+
+        Returns:
+            dict[str, Any]: ``dimensions``, ``moved``, ``unplaced``,
+            ``passes``, ``trace`` (each pass's plan, moves and overlaps),
+            ``overlaps_before``/``overlaps_after``, ``remaining_overlaps`` and
+            ``sheet_size_m``. Remaining overlaps are reported, not raised.
+
+        Raises:
+            LookupError: ``view_name`` is not on the drawing.
+        """
+        model = self.currentModel
+        drawing = _sw_type_info.flagged(model, "IDrawingDoc")
+        all_views = _view_names(self, drawing)
+        if view_name and view_name not in all_views:
+            raise LookupError(
+                f"No view named {view_name!r}. Views: {', '.join(all_views) or 'none'}"
+            )
+        sheet = work_area or self._sheet_bounds(drawing)
+        outlines, geometries, annotations = self._collect_layout(drawing, all_views)
+        _layout.attach_boxes(geometries, attached or {})
+        before = _layout.find_overlaps(geometries, outlines, sheet, obstacles)
+        after = before
+        moved, unplaced, passes, trace = 0, [], 0, []
+        # The first pass plans every movable dimension from where it was
+        # imported. SolidWorks does not always draw a dimension where the
+        # plan put it, so later passes re-plan only the dimensions still in
+        # conflict, from the real read-back geometry, with the rest fixed.
+        retry: set[str] | None = None
+        while move and passes < _LAYOUT_PASSES and (retry is None or retry):
+            passes += 1
+            allowed = {
+                g.key for g in geometries if not view_name or g.view == view_name
+            }
+            movable = allowed if retry is None else allowed & retry
+            fixed = {g.key for g in geometries} - movable
+            moves, unplaced = _layout.plan_layout(
+                geometries,
+                outlines,
+                sheet,
+                obstacles,
+                fixed=fixed,
+                inside_first=set(attached or {}),
+            )
+            applied = self._apply_moves(geometries, annotations, moves, movable)
+            moved += applied
+            self._attempt(lambda: model.ClearSelection2(True), default=None)
+            self._attempt(lambda: model.EditRebuild3(), default=None)
+            self._attempt(lambda: model.GraphicsRedraw2(), default=None)
+            outlines, geometries, annotations = self._collect_layout(drawing, all_views)
+            _layout.attach_boxes(geometries, attached or {})
+            after = _layout.find_overlaps(geometries, outlines, sheet, obstacles)
+            # Both sides of a conflict are re-planned: a leader that grazes a
+            # dimension's text is as likely the one to move as the text.
+            keys = {g.key for g in geometries}
+            retry = {
+                k
+                for p in after
+                for k in (p["dimension"], p["conflicts_with"])
+                if k in keys
+            }
+            trace.append(
+                {
+                    "pass": passes,
+                    "movable": sorted(movable),
+                    "planned": {k: [round(d, 5) for d in v] for k, v in moves.items()},
+                    "moved": applied,
+                    "unplaced": unplaced,
+                    "overlaps": after[:50],
+                }
+            )
+        result = {
+            "dimensions": len(geometries),
+            "moved": moved,
+            "unplaced": unplaced,
+            "passes": passes,
+            "trace": trace,
+            "overlaps_before": len(before),
+            "overlaps_after": len(after),
+            "remaining_overlaps": after[:50],
+            "sheet_size_m": [sheet[2], sheet[3]] if sheet else None,
+        }
+        return result
+
+    def _apply_moves(
+        self,
+        geometries: list[Any],
+        annotations: dict[str, Any],
+        moves: dict[str, tuple[float, float]],
+        movable: set[str],
+    ) -> int:
+        """Move each movable dimension by its planned offset; return how many moved.
+
+        Args:
+            geometries: Every dimension's geometry, as read.
+            annotations: Geometry key -> ``IAnnotation``.
+            moves: Planned ``(dx, dy)`` per key.
+            movable: Keys this pass may move.
+
+        Returns:
+            int: Dimensions ``SetPosition`` accepted.
+        """
+        moved = 0
+        for geometry in geometries:
+            delta = moves.get(geometry.key)
+            if geometry.key not in movable or not delta:
+                continue
+            if abs(delta[0]) < 1e-9 and abs(delta[1]) < 1e-9:
+                continue
+            an = annotations[geometry.key]
+            x, y = geometry.position[0] + delta[0], geometry.position[1] + delta[1]
+            current = self._attempt(lambda a=an: a.GetPosition(), default=None)
+            z = (
+                float(current[2])
+                if isinstance(current, (list, tuple)) and len(current) > 2
+                else 0.0
+            )
+            if self._attempt(
+                lambda a=an, x=x, y=y, z=z: a.SetPosition(x, y, z), default=False
+            ):
+                moved += 1
+        return moved
+
+    async def arrange_dimensions(
+        self, view_name: str | None = None
+    ) -> AdapterResult[dict[str, Any]]:
+        """Move drawing dimensions so none overlaps another, then verify.
+
+        Reads every dimension's text box and lines, plans positions outside
+        the views with :func:`dimension_layout.plan_layout`, applies them with
+        ``IAnnotation::SetPosition``, rebuilds, then **re-reads the real
+        geometry** and checks the rule with :func:`dimension_layout.find_overlaps`.
+        The check covers every view on the sheet, even when only one view is
+        rearranged, because neighbouring views' dimensions can collide.
+
+        Args:
+            view_name: Only move this view's dimensions; all views when omitted.
+
+        Returns:
+            AdapterResult[dict[str, Any]]: ``overlaps_before``, ``overlaps_after``
+            (each violation listed), ``moved`` and ``unplaced``. ERROR when any
+            overlap remains - the rule is not met - with the same data, so the
+            caller can see which dimensions still collide.
+        """
+        guard = self._require_drawing()
+        if guard is not None:
+            return cast("AdapterResult[dict[str, Any]]", guard)
+
+        def _arrange() -> dict[str, Any]:
+            return self._arrange_layout(view_name)
+
+        result = cast(
+            "AdapterResult[dict[str, Any]]",
+            self._handle_com_operation("arrange_dimensions", _arrange),
+        )
+        if result.is_success and result.data and result.data["overlaps_after"]:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR,
+                error=_overlap_summary(result.data),
+                data=result.data,
+                execution_time=result.execution_time,
+            )
+        return result