feat(slides): add slide CRUD Phase 1 — remove, move, indexed add_slide

First slice of issue #11 (slide CRUD epic). Lands the in-deck CRUD
operations users have been asking for since 2014; full duplicate(),
cross-deck append_from(), and Sections support stay deferred to
Phases 2–4 in the epic.

New public API
--------------
- `Slides.add_slide(slide_layout, index=None)` — `index=None`
  preserves existing append behavior (backwards compatible). Integer
  `index` inserts at that zero-based position; `index=len(self)`
  is a valid append, negatives raise `IndexError`.
- `Slides.move(slide, new_index)` — reorder a slide in the
  presentation's slide sequence. Raises `ValueError` for foreign
  slides, `IndexError` for out-of-range `new_index`.
- `Slides.remove(slide)` — drop a slide from the collection. The
  presentation→slide relationship is removed; the underlying part
  falls out on save. Image and other media parts shared with
  surviving slides are preserved (covered by integration test).
- `Slide.delete()` — convenience alias for
  `prs.slides.remove(self)`.

API shape mirrors the existing `SlideLayouts.remove(slide_layout)`
shape rather than upstream PR scanny#1029's
`remove_slide(slide_id)` — instance-keyed is more Pythonic and
matches the rest of the library.

Internal additions
------------------
- `CT_SlideIdList.insert_sldId_at(rId, idx)` — index-aware sldId
  insertion, with `idx == len` allowed.
- `CT_SlideIdList.move_sldId_to(sldId, new_idx)` — reposition an
  existing sldId; no-op when the index already matches.
- `CT_SlideIdList.remove_sldId(sldId)` — bounded remove with a
  parent-of check.

Test coverage
-------------
- 32 new unit tests in `tests/test_slide_crud.py` covering oxml
  helpers, the Slides CRUD methods, the Slide.delete alias, and four
  full-pipeline round-trip integration tests (add-at-index, remove,
  delete, move). Plus a shared-image-preservation round-trip and a
  `index=len(slides)` boundary test added per advisor review.
- 5 new behave scenarios in `features/sld-crud.feature` exercising
  add-at-head, add-in-middle, move, remove, and Slide.delete.
- New UAT script (untracked) at `uat_slide_crud.py` builds a deck
  exercising every new entry-point, saves, reopens, and prints a
  per-slide read-back so the maintainer can compare in PowerPoint /
  Keynote per CLAUDE.md §6.

Tangential test-isolation fix
-----------------------------
`tests/opc/test_package.py:DescribePartFactory` mutates
`PartFactory.part_type_for[CT.PML_SLIDE]` to a class_mock and
never reverts it. The mock leaked into any later test that loaded
slides through `Presentation()` — caught here by the new
round-trip integration tests. Restored via a request finalizer;
isolated to that one test, no behavior change for the production
code path.

Verification
------------
```
$ python3 -m pytest tests/ -q | tail -3
3086 passed in 3.76s

$ ruff check src tests | tail -3
All checks passed!

$ python3 -m behave features/ --no-color | tail -3
986 scenarios passed, 0 failed, 0 skipped
2952 steps passed, 0 failed, 0 skipped
```

Refs #11

Author: Matthew Horoszowski

features/sld-crud.feature

@@ -0,0 +1,39 @@
+Feature: Slide CRUD — remove, move, indexed add
+  In order to programmatically assemble decks without lxml hacks
+  As a developer using python-pptx
+  I need to add slides at a chosen position, reorder them, and remove them
+
+
+  Scenario: Slides.add_slide(slide_layout, index=0) inserts at the head
+    Given a Slides object containing 3 slides
+     When I call slides.add_slide(slide_layout, index=0)
+     Then len(slides) is 4
+      And the new slide is at index 0
+
+
+  Scenario: Slides.add_slide(slide_layout, index=2) inserts in the middle
+    Given a Slides object containing 3 slides
+     When I call slides.add_slide(slide_layout, index=2)
+     Then len(slides) is 4
+      And the new slide is at index 2
+
+
+  Scenario: Slides.move(slide, new_index) reorders slides
+    Given a Slides object containing 3 slides
+     When I call slides.move(slides[0], 2)
+     Then len(slides) is 3
+      And the slide order matches the original [1, 2, 0]
+
+
+  Scenario: Slides.remove(slide) drops a slide and its rel
+    Given a Slides object containing 3 slides
+     When I call slides.remove(slides[1])
+     Then len(slides) is 2
+      And the surviving slide order matches the original [0, 2]
+
+
+  Scenario: Slide.delete() removes the slide from its presentation
+    Given a Slides object containing 3 slides
+     When I call slides[1].delete()
+     Then len(slides) is 2
+      And the surviving slide order matches the original [0, 2]

features/steps/slides.py

@@ -27,6 +27,8 @@ def given_a_Slides_object_containing_3_slides(context):
     prs = Presentation(test_pptx("sld-slides"))
     context.prs = prs
     context.slides = prs.slides
+    # ---capture original slide ids for CRUD ordering assertions---
+    context.original_slide_ids = [s.slide_id for s in prs.slides]
 
 
 # when ====================================================
@@ -44,6 +46,33 @@ def when_I_call_slide_layouts_remove(context):
     slide_layouts.remove(slide_layouts[1])
 
 
+@when("I call slides.add_slide(slide_layout, index=0)")
+def when_I_call_slides_add_slide_index_0(context):
+    layout = context.prs.slide_masters[0].slide_layouts[0]
+    context.new_slide = context.slides.add_slide(layout, index=0)
+
+
+@when("I call slides.add_slide(slide_layout, index=2)")
+def when_I_call_slides_add_slide_index_2(context):
+    layout = context.prs.slide_masters[0].slide_layouts[0]
+    context.new_slide = context.slides.add_slide(layout, index=2)
+
+
+@when("I call slides.move(slides[0], 2)")
+def when_I_call_slides_move(context):
+    context.slides.move(context.slides[0], 2)
+
+
+@when("I call slides.remove(slides[1])")
+def when_I_call_slides_remove(context):
+    context.slides.remove(context.slides[1])
+
+
+@when("I call slides[1].delete()")
+def when_I_call_slide_delete(context):
+    context.slides[1].delete()
+
+
 # then ====================================================
 
 
@@ -140,3 +169,26 @@ def then_slides_get_666_default_slides_2_is_slides_2(context):
 def then_slides_2_is_a_Slide_object(context):
     slides = context.slides
     assert type(slides[2]).__name__ == "Slide"
+
+
+@then("the new slide is at index {idx:d}")
+def then_the_new_slide_is_at_index(context, idx):
+    assert context.slides[idx].slide_id == context.new_slide.slide_id, (
+        "expected new slide at index %d, got slide_id mismatch" % idx
+    )
+
+
+@then("the slide order matches the original [1, 2, 0]")
+def then_slide_order_matches_1_2_0(context):
+    o = context.original_slide_ids
+    expected = [o[1], o[2], o[0]]
+    actual = [s.slide_id for s in context.slides]
+    assert actual == expected, "expected %r, got %r" % (expected, actual)
+
+
+@then("the surviving slide order matches the original [0, 2]")
+def then_surviving_slide_order_matches_0_2(context):
+    o = context.original_slide_ids
+    expected = [o[0], o[2]]
+    actual = [s.slide_id for s in context.slides]
+    assert actual == expected, "expected %r, got %r" % (expected, actual)

src/pptx/oxml/presentation.py

@@ -64,6 +64,50 @@ def add_sldId(self, rId: str) -> CT_SlideId:
         """
         return self._add_sldId(id=self._next_id, rId=rId)
 
+    def insert_sldId_at(self, rId: str, idx: int) -> CT_SlideId:
+        """Insert a new `p:sldId` child element at position `idx`.
+
+        The new `p:sldId` element has its `r:id` attribute set to `rId` and
+        receives the next available `id` value. `idx` may equal the current
+        length to append. Raises `IndexError` if `idx` is out of range.
+        """
+        if idx < 0 or idx > len(self.sldId_lst):
+            raise IndexError("slide index out of range")
+        new_sldId = self.add_sldId(rId)
+        if idx < len(self.sldId_lst) - 1:
+            target = self.sldId_lst[idx]
+            target.addprevious(new_sldId)
+        return new_sldId
+
+    def move_sldId_to(self, sldId: CT_SlideId, new_idx: int) -> None:
+        """Reposition `sldId` to zero-based position `new_idx` in this list.
+
+        `sldId` must already be a child of this element. Raises `IndexError`
+        if `new_idx` is out of range.
+        """
+        sldId_lst = self.sldId_lst
+        if new_idx < 0 or new_idx >= len(sldId_lst):
+            raise IndexError("slide index out of range")
+        if sldId_lst[new_idx] is sldId:
+            return
+        # -- detach from current position --
+        self.remove(sldId)
+        # -- re-fetch list so index reflects post-removal state --
+        sldId_lst = self.sldId_lst
+        if new_idx >= len(sldId_lst):
+            self.append(sldId)
+        else:
+            sldId_lst[new_idx].addprevious(sldId)
+
+    def remove_sldId(self, sldId: CT_SlideId) -> None:
+        """Remove `sldId` child element from this list.
+
+        Raises `ValueError` if `sldId` is not a child of this element.
+        """
+        if sldId.getparent() is not self:
+            raise ValueError("sldId is not a child of this sldIdLst")
+        self.remove(sldId)
+
     @property
     def _next_id(self) -> int:
         """The next available slide ID as an `int`.

src/pptx/slide.py

@@ -246,6 +246,19 @@ def slide_layout(self) -> SlideLayout:
         """|SlideLayout| object this slide inherits appearance from."""
         return self.part.slide_layout
 
+    def delete(self) -> None:
+        """Remove this slide from its presentation.
+
+        Convenience alias for :meth:`Slides.remove`. After this call, the slide
+        is no longer reachable via the presentation's `slides` collection and
+        its part is dropped from the package on save.
+
+        Raises |ValueError| if this slide is not part of a presentation (e.g.
+        the parent collection cannot be located).
+        """
+        prs = self.part.package.presentation_part.presentation
+        prs.slides.remove(self)
+
 
 class Slides(ParentedElementProxy):
     """Sequence of slides belonging to an instance of |Presentation|.
@@ -277,11 +290,30 @@ def __len__(self) -> int:
         """Support len() built-in function, e.g. `len(slides) == 4`."""
         return len(self._sldIdLst)
 
-    def add_slide(self, slide_layout: SlideLayout) -> Slide:
-        """Return a newly added slide that inherits layout from `slide_layout`."""
+    def add_slide(self, slide_layout: SlideLayout, index: int | None = None) -> Slide:
+        """Return a newly added slide that inherits layout from `slide_layout`.
+
+        When `index` is |None| (the default), the new slide is appended to the
+        end of the slide sequence — matching prior behavior. When `index` is
+        an integer, the new slide is inserted at that zero-based position;
+        `index` may equal `len(self)` to append explicitly. Negative indices
+        are not supported; pass an explicit position. Raises |IndexError| if
+        `index` is out of range (negative, or greater than `len(self)`).
+
+        Companion operations: :meth:`remove`, :meth:`move`. Cross-deck copy
+        (``Presentation.append_from``) and ``Slide.duplicate`` are tracked
+        under issue #11 (Phase 2/3) and not yet implemented.
+        """
+        # ---validate index BEFORE creating the new SlidePart so a bad index
+        #    does not leak a partial part into the package---
+        if index is not None and (index < 0 or index > len(self._sldIdLst)):
+            raise IndexError("slide index out of range")
         rId, slide = self.part.add_slide(slide_layout)
         slide.shapes.clone_layout_placeholders(slide_layout)
-        self._sldIdLst.add_sldId(rId)
+        if index is None:
+            self._sldIdLst.add_sldId(rId)
+        else:
+            self._sldIdLst.insert_sldId_at(rId, index)
         return slide
 
     def get(self, slide_id: int, default: Slide | None = None) -> Slide | None:
@@ -304,6 +336,38 @@ def index(self, slide: Slide) -> int:
                 return idx
         raise ValueError("%s is not in slide collection" % slide)
 
+    def move(self, slide: Slide, new_index: int) -> None:
+        """Reposition `slide` to zero-based position `new_index`.
+
+        Raises |ValueError| if `slide` is not a member of this collection,
+        and |IndexError| if `new_index` is out of range (negative or
+        ``>= len(self)``). Section membership (`p14:sectionLst`) references
+        slides by id, not position, so reordering is invisible to sections.
+        """
+        if new_index < 0 or new_index >= len(self):
+            raise IndexError("slide index out of range")
+        idx = self.index(slide)
+        sldId = self._sldIdLst.sldId_lst[idx]
+        self._sldIdLst.move_sldId_to(sldId, new_index)
+
+    def remove(self, slide: Slide) -> None:
+        """Remove `slide` from this collection.
+
+        The slide's relationship is dropped from the presentation part. The
+        underlying slide part falls out of the package on the next save.
+        Image and other media parts referenced only by the removed slide
+        likewise drop out — but image parts shared with surviving slides
+        (e.g. the same picture inserted on two slides) are preserved.
+        Raises |ValueError| if `slide` is not a member of this collection.
+        After this call, references to `slide` are stale; behavior of method
+        calls on the removed `Slide` instance is undefined.
+        """
+        idx = self.index(slide)
+        sldId = self._sldIdLst.sldId_lst[idx]
+        target_rId = sldId.rId
+        self._sldIdLst.remove_sldId(sldId)
+        self.part.drop_rel(target_rId)
+
 
 class SlideLayout(_BaseSlide):
     """Slide layout object.

tests/opc/test_package.py

@@ -514,6 +514,17 @@ def it_constructs_custom_part_type_for_registered_content_types(self, request, p
         SlidePart_ = class_mock(request, "pptx.opc.package.XmlPart")
         SlidePart_.load.return_value = part_
         partname = PackURI("/ppt/slides/slide7.xml")
+        # ---restore the original PartFactory mapping after the test so the
+        #    mock does not leak into subsequent tests that load slides
+        original = PartFactory.part_type_for.get(CT.PML_SLIDE)
+
+        def _restore():
+            if original is None:
+                PartFactory.part_type_for.pop(CT.PML_SLIDE, None)
+            else:
+                PartFactory.part_type_for[CT.PML_SLIDE] = original
+
+        request.addfinalizer(_restore)
         PartFactory.part_type_for[CT.PML_SLIDE] = SlidePart_
 
         part = PartFactory(partname, CT.PML_SLIDE, package_, b"blob")