vsdxkit 0.7.0__py3-none-any.whl

vsdx/__init__.py

@@ -0,0 +1,66 @@
+"""vsdxkit - create, edit and analyse Microsoft Visio .vsdx files.
+
+The distribution installs as ``vsdxkit``; the import namespace stays ``vsdx``
+so code written against the library this one descends from keeps working.
+"""
+
+import xml.dom.minidom as minidom  # minidom used for prettyprint
+import xml.etree.ElementTree as ET
+from xml.etree.ElementTree import Element
+
+namespace = "{http://schemas.microsoft.com/office/visio/2012/main}"  # visio file name space
+ext_prop_namespace = "{http://schemas.openxmlformats.org/officeDocument/2006/extended-properties}"
+vt_namespace = "{http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes}"
+r_namespace = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
+document_rels_namespace = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+cont_types_namespace = "{http://schemas.openxmlformats.org/package/2006/content-types}"
+
+# Ref: https://docs.microsoft.com/en-us/office/client-developer/visio/visio-file-format-reference
+
+
+def pretty_print_element(xml: Element | ET.ElementTree) -> str:
+    if isinstance(xml, ET.ElementTree):
+        root = xml.getroot()
+        return minidom.parseString(ET.tostring(root) if root is not None else b"").toprettyxml()
+    return minidom.parseString(ET.tostring(xml)).toprettyxml()
+
+
+__version__ = "0.7.0"
+
+# Issue #250/#254 review: `Shape.connects` quotes `Connect` in its annotation,
+# and `typing.get_type_hints` evaluates quoted names against the function's
+# module __dict__ (module __getattr__ is not consulted). Inject the real class
+# here, once both modules are fully initialised, so runtime introspection works.
+from . import shapes as _shapes_module  # noqa: E402
+from .connectors import Connect  # noqa: E402
+from .containers import Container  # noqa: E402
+from .formulae import calc_value  # noqa: E402
+from .geometry import Geometry, GeometryCell, GeometryRow  # noqa: E402
+from .logging_support import attach_debug_stream_handler, get_logger  # noqa: E402
+from .media import Media  # noqa: E402
+from .pages import Page, PagePosition  # noqa: E402
+from .shapes import Cell, DataProperty, Shape  # noqa: E402
+from .vsdxfile import PackageLimitError, PackageLimits, VisioFile, VisioFileNotOpen  # noqa: E402
+
+_shapes_module.Connect = Connect
+
+__all__ = [
+    "Cell",
+    "Connect",
+    "Container",
+    "DataProperty",
+    "Geometry",
+    "GeometryCell",
+    "GeometryRow",
+    "Media",
+    "PackageLimitError",
+    "PackageLimits",
+    "Page",
+    "PagePosition",
+    "Shape",
+    "VisioFile",
+    "VisioFileNotOpen",
+    "attach_debug_stream_handler",
+    "calc_value",
+    "get_logger",
+]

vsdx/connectors.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import copy
+import xml.etree.ElementTree as ET
+from xml.etree.ElementTree import Element
+
+import vsdx
+
+from .shapes import Shape
+
+namespace = "{http://schemas.microsoft.com/office/visio/2012/main}"
+
+
+class Connect:
+    """Connect class to represent a connection between two `Shape` objects"""
+
+    @staticmethod
+    def _parse_route(route: str) -> tuple[bool, str | None]:
+        """Return point-glue and routing choices after validating route tokens."""
+        route_parts: list[str] = route.split("|") if route else []
+        allowed_parts = {"dynamic", "point", "straight", "rightangle", "curved"}
+        unknown_parts = set(route_parts) - allowed_parts
+        if unknown_parts:
+            raise ValueError(f"unknown connector route part(s): {', '.join(sorted(unknown_parts))}")
+        routing_parts = [part for part in route_parts if part in {"straight", "rightangle", "curved"}]
+        if len(routing_parts) > 1:
+            raise ValueError("connector route may specify only one routing behaviour")
+        return "point" in route_parts, routing_parts[0] if routing_parts else None
+
+    def __init__(self, xml: Element | None = None, page: vsdx.Page | None = None):
+        if page is None:
+            raise ValueError("Connect requires the page containing the connection")
+        if xml is None:
+            raise ValueError("Connect requires the connection's XML element")
+        if type(xml) is not Element or xml.tag != f"{namespace}Connect":
+            raise ValueError(f"Connect requires a {namespace}Connect element, got {xml.tag!r}")
+        missing = [name for name in ("FromSheet", "ToSheet") if name not in xml.attrib]
+        if missing:
+            raise ValueError(f"Connect element is missing required attribute(s): {', '.join(missing)}")
+        self.xml = xml
+        self.page = page
+        self.from_id = xml.attrib["FromSheet"]  # ref to the connector shape
+        self.to_id = xml.attrib["ToSheet"]  # ref to the shape where the connector terminates
+        self.from_rel = xml.attrib.get("FromCell")  # i.e. EndX / BeginX; optional per Connect_Type
+        self.to_rel = xml.attrib.get("ToCell")  # i.e. PinX; optional per Connect_Type
+
+    @staticmethod
+    def create(
+        page: vsdx.Page | None = None,
+        from_shape: Shape | None = None,
+        to_shape: Shape | None = None,
+        route: str = "dynamic",
+        from_cp: int = 0,
+        to_cp: int = 0,
+    ) -> Shape:
+        """Create a new Connect object between from_shape and to_shape
+
+        route: 'dynamic' (shape glue, default), 'point' (connection-point glue),
+        optionally combined routing behaviour via 'straight', 'rightangle' or
+        'curved'. When route='point', from_cp/to_cp give the 0-based connection
+        point row index on the from/to shapes respectively.
+
+        :returns: a new Connect object
+        :rtype: Shape
+        """
+        if page is None:
+            raise ValueError("Connect.create() requires a page")
+        if from_shape is None or to_shape is None:
+            raise ValueError("Connect.create() requires both from_shape and to_shape")
+        Connect._parse_route(route)
+        # validate everything _apply_glue can reject BEFORE provisioning
+        # masters, copying shapes or appending records (issue #9 atomicity)
+        Connect._validate_point_glue(from_shape, to_shape, route, from_cp, to_cp)
+        if (
+            from_shape is not None and to_shape is not None
+        ):  # create new connector shape and connect items between this and the two shapes
+            # create new connect shape and get id
+            media = page.vis._shared_media()
+            media_shape = media.straight_connector
+            # state-based guard: masters provisioned if the document already
+            # carries the masters relationship (the on-disk folder only exists
+            # after save, so an os.path.exists guard double-provisioned on
+            # 2nd+ calls)
+            masters_rel_present = any(
+                r.attrib.get("Type") == "http://schemas.microsoft.com/visio/2010/relationships/masters"
+                for r in page.vis.document_rels()
+            )
+            new_master_id = None
+            if not masters_rel_present:
+                # document has no masters at all: copy the media masters folder
+                for file_name, file in media.media.zip_file_contents.items():
+                    if file_name.startswith(media.media._masters_folder):
+                        new_file_name = file_name.replace(media.media._masters_folder, page.vis._masters_folder)
+                        page.vis.zip_file_contents[new_file_name] = file
+                page.vis.load_master_pages()  # load copied master page files into VisioFile object
+                # document-level masters relationship
+                page.vis._add_document_rel(
+                    rel_type="http://schemas.microsoft.com/visio/2010/relationships/masters", target="masters/masters.xml"
+                )
+                # content-type overrides for masters.xml and master1.xml
+                page.vis._add_content_types_override(
+                    content_type="application/vnd.ms-visio.masters+xml", part_name_path="/visio/masters/masters.xml"
+                )
+                page.vis._add_content_types_override(
+                    content_type="application/vnd.ms-visio.master+xml", part_name_path="/visio/masters/master1.xml"
+                )
+                # per-page master relationship (creates + registers the page
+                # rels part so save_vsdx persists it)
+                page._ensure_page_master_rel("rId1", "master1.xml")
+            else:
+                # document has masters: import the connector master (by name)
+                # BEFORE the copy, while media_shape still points at its source
+                new_master_id = page.vis._ensure_masters_for_shape(media_shape) or None
+
+            connector_shape = media_shape.copy(page)  # default to straight connector
+            connector_shape.text = ""  # clear text used to find shape
+            if new_master_id:
+                # repoint the copied shape at this document's imported master
+                connector_shape.xml.attrib["Master"] = new_master_id
+                connector_shape.master_page_ID = new_master_id
+
+            # per-page relationship for whichever master the connector uses
+            effective_master_id = new_master_id or connector_shape.master_page_ID
+            master_page = page.vis.get_master_page_by_id(effective_master_id) if effective_master_id else None
+            if master_page is not None:
+                master_part = master_page.filename.replace(page.vis._masters_folder + "/", "")
+                page._ensure_page_master_rel(master_page.rel_id, master_part)
+
+            # TitlesOfParts entry for the master name (app.xml 'Masters' count
+            # is deliberately not written: real Visio packages omit it)
+            shape_name = connector_shape.shape_name
+            if shape_name and shape_name not in page.vis._titles_of_parts_list():
+                page.vis._add_titles_of_parts_item(shape_name)
+
+            # copy style used by new connector shape
+            master_shape = connector_shape.master_shape
+            line_style_id = master_shape.line_style_id if master_shape is not None else None
+            if line_style_id is not None and not isinstance(page.vis._get_style_by_id(line_style_id), Element):
+                # assume same if is ok, todo: use names for match and increment IDs
+                media_style = media.media._get_style_by_id(line_style_id)
+                if media_style is not None:
+                    # copy, not alias: the donor document now outlives this
+                    # call, so appending its live element would leave the two
+                    # documents sharing one mutable StyleSheet
+                    page.vis._style_sheets().append(copy.deepcopy(media_style))
+
+            # wire glue to the from/to shapes (Visio-faithful formulas, see
+            # tests/fixtures/com_reference/manifest.json for ground truth)
+            Connect._apply_glue(connector_shape, from_shape, to_shape, route=route, from_cp=from_cp, to_cp=to_cp)
+
+            # initial endpoints so the file renders sensibly even before Visio recalculates
+            connector_shape.set_start_and_finish(from_shape.center_x_y, to_shape.center_x_y)
+            return connector_shape
+        raise ValueError("Connect.create() requires both from_shape and to_shape")
+
+    @staticmethod
+    def _get_or_create_cell(shape: Shape, name: str, v: str | None = None, f: str | None = None):
+        """Set or create a cell on a shape, preserving schema cell ordering.
+
+        Delegates to the single cell-write primitive on Shape.
+        """
+        return shape.get_or_create_cell(name, v=v, f=f)
+
+    @staticmethod
+    def _connection_point_count(shape: Shape) -> int:
+        sections = shape.xml.findall(f"{vsdx.namespace}Section")
+        for section in sections:
+            if section.attrib.get("N") == "Connection":
+                return len(section.findall(f"{vsdx.namespace}Row"))
+        return 0
+
+    @staticmethod
+    def _validate_point_glue(from_shape: Shape, to_shape: Shape, route: str, from_cp: int, to_cp: int) -> None:
+        """Validate route and point-glue indices before any package mutation.
+
+        Issue #9: Connect.create() provisioned masters and appended the
+        connector, and retarget() removed existing records, before
+        _apply_glue() rejected invalid indices — a caught ValueError left the
+        package half-changed. Everything _apply_glue can reject is checked
+        here so callers can fail before their first mutation.
+        """
+        point_glue, _routing = Connect._parse_route(route)
+        if not point_glue:
+            return
+        for shape, cp in ((from_shape, from_cp), (to_shape, to_cp)):
+            cp_count = Connect._connection_point_count(shape)
+            if cp < 0 or cp >= cp_count:
+                raise ValueError(
+                    f"Shape ID {shape.ID} has {cp_count} connection point(s); cannot glue to connection point index {cp}"
+                )
+
+    @staticmethod
+    def _apply_glue(
+        connector_shape: Shape, from_shape: Shape, to_shape: Shape, route: str = "dynamic", from_cp: int = 0, to_cp: int = 0
+    ):
+        """Apply Visio-faithful glue between connector and from/to shapes.
+
+        Shape glue (default): _WALKGLUE formulas + GlueType=2, matching what
+        Visio writes for a dynamic connector glued to shape PinX.
+        Point glue (route='point'): PAR(PNT(...)) formulas referencing
+        Connections.Xn/Yn rows; raises ValueError if the shape has too few
+        connection points.
+        route may also set routing behaviour: 'straight' (ShapeRouteStyle=16),
+        'rightangle' (ShapeRouteStyle=1), 'curved' (ShapeRouteStyle=17 +
+        ConLineRouteExt=2).
+        """
+        conn_id = connector_shape.ID
+        point_glue, routing = Connect._parse_route(route)
+
+        if point_glue:
+            ends = (("Begin", "EndX", from_shape, from_cp), ("End", "BeginX", to_shape, to_cp))
+            for prefix, _opposite_cell, shape, cp in ends:
+                cp_count = Connect._connection_point_count(shape)
+                if cp >= cp_count:
+                    raise ValueError(
+                        f"Shape ID {shape.ID} has {cp_count} connection point(s); cannot glue to connection point index {cp}"
+                    )
+                k = cp + 1
+                Connect._get_or_create_cell(connector_shape, f"{prefix}Trigger", f=f"_XFTRIGGER(Sheet{shape.ID}!EventXFMod)")
+                pnt = f"PAR(PNT(Sheet{shape.ID}!Connections.X{k},Sheet{shape.ID}!Connections.Y{k}))"
+                Connect._get_or_create_cell(connector_shape, f"{prefix}X", f=pnt)
+                Connect._get_or_create_cell(connector_shape, f"{prefix}Y", f=pnt)
+            beg_connect = (
+                f'<Connect xmlns="http://schemas.microsoft.com/office/visio/2012/main" '
+                f'FromSheet="{conn_id}" FromCell="BeginX" FromPart="9" '
+                f'ToSheet="{from_shape.ID}" ToCell="Connections.X{from_cp + 1}" '
+                f'ToPart="{99 + from_cp + 1}"/>'
+            )
+            end_connect = (
+                f'<Connect xmlns="http://schemas.microsoft.com/office/visio/2012/main" '
+                f'FromSheet="{conn_id}" FromCell="EndX" FromPart="12" '
+                f'ToSheet="{to_shape.ID}" ToCell="Connections.X{to_cp + 1}" '
+                f'ToPart="{99 + to_cp + 1}"/>'
+            )
+        else:
+            # shape glue - dynamic connector behaviour, formulas as written by Visio 16
+            Connect._get_or_create_cell(connector_shape, "BegTrigger", f=f"_XFTRIGGER(Sheet{from_shape.ID}!EventXFMod)")
+            Connect._get_or_create_cell(connector_shape, "EndTrigger", f=f"_XFTRIGGER(Sheet{to_shape.ID}!EventXFMod)")
+            walkglue_begin = "_WALKGLUE(BegTrigger,EndTrigger,WalkPreference)"
+            walkglue_end = "_WALKGLUE(EndTrigger,BegTrigger,WalkPreference)"
+            Connect._get_or_create_cell(connector_shape, "BeginX", f=walkglue_begin)
+            Connect._get_or_create_cell(connector_shape, "BeginY", f=walkglue_begin)
+            Connect._get_or_create_cell(connector_shape, "EndX", f=walkglue_end)
+            Connect._get_or_create_cell(connector_shape, "EndY", f=walkglue_end)
+            Connect._get_or_create_cell(connector_shape, "GlueType", v="2")
+            Connect._get_or_create_cell(connector_shape, "ObjType", v="2")
+            # explicit dynamic routing, as written by Visio 16; overrides the
+            # template connector's inherited ShapeRouteStyle=16 (straight)
+            Connect._get_or_create_cell(connector_shape, "ShapeRouteStyle", v="0")
+            Connect._get_or_create_cell(connector_shape, "ConLineRouteExt", v="0")
+            Connect._get_or_create_cell(connector_shape, "ConFixedCode", v="6")
+            beg_connect = (
+                f'<Connect xmlns="http://schemas.microsoft.com/office/visio/2012/main" '
+                f'FromSheet="{conn_id}" FromCell="BeginX" FromPart="9" '
+                f'ToSheet="{from_shape.ID}" ToCell="PinX" ToPart="3"/>'
+            )
+            end_connect = (
+                f'<Connect xmlns="http://schemas.microsoft.com/office/visio/2012/main" '
+                f'FromSheet="{conn_id}" FromCell="EndX" FromPart="12" '
+                f'ToSheet="{to_shape.ID}" ToCell="PinX" ToPart="3"/>'
+            )
+
+        if routing == "straight":
+            Connect._get_or_create_cell(connector_shape, "ShapeRouteStyle", v="16")
+        elif routing == "rightangle":
+            Connect._get_or_create_cell(connector_shape, "ShapeRouteStyle", v="1")
+        elif routing == "curved":
+            Connect._get_or_create_cell(connector_shape, "ShapeRouteStyle", v="17")
+            Connect._get_or_create_cell(connector_shape, "ConLineRouteExt", v="2")
+
+        # Add these new connection relationships to the page
+        page = connector_shape.page
+        page.add_connect(Connect(xml=ET.fromstring(end_connect), page=page))
+        page.add_connect(Connect(xml=ET.fromstring(beg_connect), page=page))
+
+    @staticmethod
+    def retarget(
+        page: vsdx.Page,
+        connector_shape: Shape,
+        from_shape: Shape | None = None,
+        to_shape: Shape | None = None,
+        route: str = "dynamic",
+        from_cp: int = 0,
+        to_cp: int = 0,
+    ) -> Shape:
+        """Retarget an existing connector to new endpoints.
+
+        Only the ends provided are moved; the other end keeps its current
+        glue (resolved from the page's existing Connect records). Reuses
+        _apply_glue for cells and records — removal of the old records goes
+        through the page's single record-removal path.
+
+        :returns: the connector Shape
+        """
+        current_from = current_to = None
+        current_from_cp = current_to_cp = 0
+        for connect in page.connects:
+            if connect.from_id == str(connector_shape.ID):
+                # note: deliberately not named to_shape - that is the parameter
+                connected_shape = page.find_shape_by_id(connect.to_id) if connect.to_id else None
+                if connect.from_rel == "BeginX":
+                    current_from = connected_shape
+                    if connect.to_rel and connect.to_rel.startswith("Connections"):
+                        current_from_cp = int(connect.to_rel.rsplit(".", 1)[1]) - 1
+                elif connect.from_rel == "EndX":
+                    current_to = connected_shape
+                    if connect.to_rel and connect.to_rel.startswith("Connections"):
+                        current_to_cp = int(connect.to_rel.rsplit(".", 1)[1]) - 1
+        new_from = from_shape if from_shape is not None else current_from
+        new_to = to_shape if to_shape is not None else current_to
+        if new_from is None or new_to is None:
+            raise ValueError("connector has no resolvable endpoints to keep")
+
+        # validate everything _apply_glue can reject BEFORE removing the
+        # existing records (issue #9 atomicity)
+        Connect._validate_point_glue(
+            new_from,
+            new_to,
+            route,
+            from_cp if from_shape is not None else current_from_cp,
+            to_cp if to_shape is not None else current_to_cp,
+        )
+        page.remove_connect_records({str(connector_shape.ID)})
+        Connect._apply_glue(
+            connector_shape,
+            new_from,
+            new_to,
+            route=route,
+            from_cp=from_cp if from_shape is not None else current_from_cp,
+            to_cp=to_cp if to_shape is not None else current_to_cp,
+        )
+        connector_shape.set_start_and_finish(new_from.center_x_y, new_to.center_x_y)
+        return connector_shape
+
+    @property
+    def shape_id(self) -> str | None:
+        # ref to the shape where the connector terminates - convenience property
+        return self.to_id
+
+    @property
+    def shape(self) -> Shape | None:
+        return self.page.find_shape_by_id(self.shape_id) if self.shape_id else None
+
+    @property
+    def connector_shape_id(self) -> str | None:
+        # ref to the connector shape - convenience property
+        return self.from_id
+
+    @property
+    def connector_shape(self) -> Shape | None:
+        return self.page.find_shape_by_id(self.connector_shape_id) if self.connector_shape_id else None
+
+    def __repr__(self):
+        return f"Connect: from={self.from_id} to={self.to_id} connector_id={self.connector_shape_id} shape_id={self.shape_id}"

vsdx/containers.py

@@ -0,0 +1,211 @@
+"""Container and swimlane support for vsdx documents.
+
+Ground truth: tests/fixtures/com_reference/s05_swimlanes_cfflow.vsdx
+(Visio 16 cross-functional flowchart capture).
+
+Model (verified against the capture):
+- CFF shapes (CFF Container, Swimlane List, Swimlane lanes, Phase List,
+  Separator, and all flowchart shapes) live as TOP-LEVEL shapes on the page;
+  Visio keeps them flat and links them logically
+- lane membership is GEOMETRIC: a shape belongs to the lane whose vertical
+  band contains the shape's centre (PinY). No membership cells exist
+- each lane carries User-section rows: ``visHeadingText`` (label) and
+  ``SwimlaneListGUID``; the heading text also appears in the lane's heading
+  sub-shape (the child carrying ``MasterShape``)
+- lanes stack at a fixed pitch; the observed pitch is 1.1811 inches (30 mm)
+- User rows are stored as ``<Section N='User'><Row N='name'>`` which is NOT
+  the same as plain ``<Cell N='...'>`` cells; helpers here handle both
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+
+import vsdx
+
+from .shapes import Shape
+
+# observed lane pitch in the Visio 16 CFF capture (inches)
+LANE_PITCH_INCHES = 1.18110236220472
+
+# User-section row names written by Visio on lane shapes
+ROW_HEADING_TEXT = "visHeadingText"
+ROW_SWIMLANE_GUID = "SwimlaneListGUID"
+
+# top-level shape NameU values of the CFF machinery (excluded from membership)
+_CFF_MACHINERY = ("CFF Container", "Swimlane List", "Phase List", "Separator")
+
+
+def get_user_row(shape: Shape, name: str) -> ET.Element | None:
+    """Return the ``<Row N=name>`` element of the shape's User section, or None."""
+    for section in shape.xml.findall(f"{vsdx.namespace}Section"):
+        if section.attrib.get("N") == "User":
+            for row in section.findall(f"{vsdx.namespace}Row"):
+                if row.attrib.get("N") == name:
+                    return row
+    return None
+
+
+def set_user_row_value(shape: Shape, name: str, value: str) -> bool:
+    """Set the Value cell of a User-section row. Returns False if the row is
+    absent (rows are only created where Visio itself creates them)."""
+    row = get_user_row(shape, name)
+    if row is None:
+        return False
+    for cell in row.findall(f"{vsdx.namespace}Cell"):
+        if cell.attrib.get("N") == "Value":
+            cell.attrib["V"] = value
+            return True
+    return False
+
+
+class Container:
+    """Read/write view over a CFF (swimlane) diagram structure.
+
+    Membership is geometric: :meth:`lane_of` maps a shape to the lane whose
+    vertical band contains its centre, mirroring Visio's own containment
+    behaviour. There are no membership cells to write.
+    """
+
+    def __init__(self, page: vsdx.Page):
+        self.page = page
+
+    # ---- discovery -------------------------------------------------------
+
+    @staticmethod
+    def find(page: vsdx.Page) -> Container | None:
+        """Return a Container for the page, or None if this is not a CFF page."""
+        for shape in page.all_shapes:
+            if shape.shape_name == "CFF Container":
+                return Container(page)
+        return None
+
+    def _top_level_named(self, name_prefix: str) -> list[Shape]:
+        shapes_tag = self.page.xml.find(f"{vsdx.namespace}Shapes")
+        if shapes_tag is None:
+            return []
+        result = []
+        for el in shapes_tag.findall(f"{vsdx.namespace}Shape"):
+            name = el.attrib.get("NameU") or el.attrib.get("Name") or ""
+            if name.startswith(name_prefix):
+                result.append(Shape(xml=el, parent=self.page, page=self.page))
+        return result
+
+    @property
+    def container_shape(self) -> Shape | None:
+        matches = self._top_level_named("CFF Container")
+        return matches[0] if matches else None
+
+    @property
+    def swimlane_list(self) -> Shape | None:
+        matches = self._top_level_named("Swimlane List")
+        return matches[0] if matches else None
+
+    @property
+    def lanes(self) -> list[Shape]:
+        """Lane shapes in visual order, top lane first."""
+        lanes = [
+            s
+            for s in self._top_level_named("Swimlane")
+            if s.shape_name and s.shape_name.startswith("Swimlane") and not s.shape_name.startswith("Swimlane List")
+        ]
+        lanes.sort(key=lambda s: -(s.y or 0.0))  # top-to-bottom
+        return lanes
+
+    # ---- geometry --------------------------------------------------------
+
+    @staticmethod
+    def lane_band(lane: Shape) -> tuple[float, float]:
+        """(bottom, top) Y band of a lane, from its centre and height."""
+        centre = lane.y or 0.0
+        height = lane.height or LANE_PITCH_INCHES
+        return centre - height / 2, centre + height / 2
+
+    def lane_of(self, shape: Shape) -> Shape | None:
+        """The lane whose band contains the shape's centre, or None."""
+        for lane in self.lanes:
+            bottom, top = self.lane_band(lane)
+            if bottom <= (shape.y or 0.0) <= top:
+                return lane
+        return None
+
+    def members(self, lane: Shape) -> list[Shape]:
+        """Flowchart shapes whose centre lies in the lane's band."""
+        bottom, top = self.lane_band(lane)
+        result = []
+        for shape in self._top_level_named(""):  # all top-level shapes
+            name = shape.shape_name or ""
+            if name.startswith(_CFF_MACHINERY) or name.startswith("Swimlane"):
+                continue
+            if "BeginX" in shape.cells:  # connectors are not members
+                continue
+            if bottom <= (shape.y or 0.0) <= top:
+                result.append(shape)
+        return result
+
+    # ---- operations ------------------------------------------------------
+
+    def add_swimlane(self, label: str | None = None) -> Shape:
+        """Add a lane above the current top lane by cloning it and shifting
+        one lane pitch. The Swimlane List and CFF Container grow to match.
+
+        :return: the new lane Shape
+        """
+        lanes = self.lanes
+        if not lanes:
+            raise ValueError("page has no Swimlane lanes; not a CFF diagram")
+        top_lane = lanes[0]
+
+        new_xml = vsdx.ET.fromstring(vsdx.ET.tostring(top_lane.xml))
+        shapes_tag = self.page.xml.find(f"{vsdx.namespace}Shapes")
+        if shapes_tag is None:
+            raise ValueError("page has no Shapes tag")
+        self.page.set_max_ids()  # ensure max_id reflects existing shapes
+        id_map = self.page.vis.increment_shape_ids(new_xml, self.page)
+        self.page.vis.update_ids(new_xml, id_map)
+        shapes_tag.append(new_xml)
+        new_lane = Shape(xml=new_xml, parent=self.page, page=self.page)
+
+        new_lane.get_or_create_cell("PinY", v=str((top_lane.y or 0.0) + LANE_PITCH_INCHES))
+
+        # grow the list and container so the new lane sits inside them
+        pitch = LANE_PITCH_INCHES
+        lane_list = self.swimlane_list
+        if lane_list is not None:
+            lane_list.get_or_create_cell("PinY", v=str((lane_list.y or 0.0) + pitch / 2))
+            lane_list.get_or_create_cell("Height", v=str((lane_list.height or 0) + pitch))
+        container = self.container_shape
+        if container is not None:
+            container.get_or_create_cell("PinY", v=str((container.y or 0.0) + pitch / 2))
+            container.get_or_create_cell("Height", v=str((container.height or 0) + pitch))
+
+        if label:
+            self.set_lane_label(new_lane, label)
+        self.page.set_max_ids()
+        return new_lane
+
+    def set_lane_label(self, lane: Shape, label: str) -> None:
+        """Set a lane's heading label (visHeadingText row + heading text)."""
+        set_user_row_value(lane, ROW_HEADING_TEXT, label)
+        heading = self.lane_heading(lane)
+        if heading is not None:
+            heading.text = label
+        else:
+            lane.text = label
+
+    @staticmethod
+    def lane_heading(lane: Shape) -> Shape | None:
+        """The lane's heading sub-shape (child carrying MasterShape)."""
+        for child in lane.child_shapes:
+            if child.master_shape_ID is not None:
+                return child
+        return None
+
+    def add_shape_to_lane(self, shape: Shape, lane: Shape) -> None:
+        """Assign a shape to a lane by geometry: set the shape's PinY to the
+        lane's centre, keeping its PinX. Mirrors Visio's own behaviour when a
+        shape is dragged into a lane; membership stays geometric.
+        """
+        if self.lane_of(shape) is lane:
+            return
+        shape.get_or_create_cell("PinY", v=str(lane.y or 0.0))