feat(shapes): Shape Effects, 3-D, Arrowheads & Connectors — issue #18 epic (#58)

Resolves the genuinely-missing surface of the issue #18 epic and adds
issue-named convenience API over the sub-features this fork already
shipped. One branch; nine sub-features.

Investigation finding (recorded so the delta is auditable): issue #18 is
written against upstream scanny/python-pptx, which is behind this fork.
Arrowhead ends (full MSO_LINE_END_TYPE enum + LineFormat.begin/end_
arrowhead_* + oxml + 42 tests) and the experimental connector connect
API were ALREADY shipped here; for those, scope was verify-no-regression
plus thin issue-named aliases, not a rebuild.

New (genuinely missing):
- ShadowFormat.glow_effect / .reflection_effect / .soft_edge_effect —
  CT_GlowEffect / CT_ReflectionEffect / CT_SoftEdgesEffect mirroring the
  proven a:outerShdw pattern; wired into CT_EffectList in ECMA-376
  schema order (blur,fillOverlay,glow,innerShdw,outerShdw,prstShdw,
  reflection,softEdge). softEdge/@RaD is RequiredAttribute per schema;
  glow always emits its mandatory EG_ColorChoice child.
- Shape.scene_3d / Shape.shape_3d — CT_Scene3D / CT_Camera / CT_LightRig
  / CT_Shape3D. scene3d default emits BOTH the schema-required camera
  AND lightRig (camera-only → PowerPoint repair). Wired into spPr after
  effectLst, before extLst.
- Shape.flip_horizontal / Shape.flip_vertical — delegate to the existing
  oxml flipH/flipV (creates a:xfrm in schema-safe order).
- Shape.duplicate(insert_at_z=None) — deep-copy with sequential unique
  cNvPr id reassignment (max_shape_id+1+i, so a duplicated *group*'s
  children don't collide → no repair) and unique name; z-clamped so the
  clone never lands before grpSpPr. Pure-XML copy; relationship-backed
  shapes share the part (documented limitation).
- Shape.slide_left/_top/_width/_height — additive, read-only world-space
  coordinates composing every enclosing p:grpSp affine outward (one
  recursion handles arbitrary nesting); identity fallback on degenerate
  chExt; never mutates stored xfrm; existing left/top semantics
  unchanged. Group rotation/flip intentionally not folded (matches COM
  Shape.Left).

Issue-named aliases over shipped API (additive, no signature change):
- LineFormat.head_end / .tail_end (.type/.width/.length)
- Connector.start_connection / .end_connection

Tests: 38 new unit tests in tests/test_issue18_shape_effects.py
(glow 4, reflection 4, soft-edge 4, 3-D 4, head/tail 3, start/end 2,
group-coords 5, flip 4, duplicate 8) + 10 behave scenarios in
features/iss-18-shape-effects.feature. Per-class save→reopen round-trip
coverage included.

Trinity (verbatim):
  python3 -m pytest tests/ -q            -> 3925 passed (3887 + 38)
  ruff check src tests                   -> All checks passed!
  python3 -m behave features/ --no-color -> 1119 scenarios, 0 failed
                                            (1109 + 10)

UAT: uat/uat_issue18_shape_effects.py runs clean, 16/16 round-trip
checks, exit 0. Interceptor screenshots of slides 1/2/4 in real
PowerPoint show glow/reflection/soft-edge, a 3-D extruded box, and a
flipped+duplicated arrow rendering with NO repair dialog
(sheets_on_w1=0). Visual sign-off is the maintainer's call per §6a —
not claimed here.

Closes #18

Author: MHoroszowski

features/iss-18-shape-effects.feature

@@ -0,0 +1,55 @@
+Feature: Issue #18 — shape effects, 3-D, arrowheads, flip, duplicate
+  In order to author rich PowerPoint shapes that open without repair
+  As a developer using python-pptx-extended
+  I need glow / reflection / soft-edge effects, preset 3-D, flip,
+  shape duplication, and the issue-named arrowhead / connector API
+
+  Scenario: Author and read back a glow color and radius
+    Given a blank slide with one rectangle
+     When I set the glow color to FF0000 and radius to 20pt
+     Then the rectangle reports glow radius 20pt and color FF0000
+
+  Scenario: Author and read back a reflection
+    Given a blank slide with one rectangle
+     When I set the reflection blur radius to 3pt and distance to 7pt
+     Then the rectangle reports reflection blur radius 3pt
+
+  Scenario: Author and read back a soft edge
+    Given a blank slide with one rectangle
+     When I set the soft edge radius to 5pt
+     Then the rectangle reports soft edge radius 5pt
+
+  Scenario: Author and read back a preset 3-D camera
+    Given a blank slide with one rectangle
+     When I set the 3-D camera preset to orthographicFront
+     Then the rectangle reports camera preset orthographicFront
+      And the scene has a light rig
+
+  Scenario: Author and read back a 3-D extrusion
+    Given a blank slide with one rectangle
+     When I set the extrusion height to 18pt
+     Then the rectangle reports extrusion height 18pt
+
+  Scenario: Flip a shape vertically and read it back after round-trip
+    Given a blank slide with one rectangle
+     When I flip the rectangle vertically and round-trip the file
+     Then the reopened rectangle is flipped vertically
+
+  Scenario: Flip a shape horizontally
+    Given a blank slide with one rectangle
+     When I flip the rectangle horizontally
+     Then the rectangle is flipped horizontally
+
+  Scenario: Duplicate a shape produces two distinct shapes
+    Given a blank slide with one rectangle
+     When I duplicate the rectangle
+     Then the slide has two rectangles with distinct shape ids
+
+  Scenario: Arrow-ended connector via the head_end API round-trips
+    Given a blank slide with one connector
+     When I set the tail end arrowhead to a triangle and round-trip the file
+     Then the reopened connector tail end is a triangle
+
+  Scenario: Group child reports correct world-space coordinates
+    Given a group scaled two-to-one containing one rectangle
+     Then the rectangle slide_width is double its local width

features/steps/iss18.py

@@ -0,0 +1,176 @@
+"""Step implementations for features/iss-18-shape-effects.feature (issue #18).
+
+Self-contained: every scenario builds an in-memory blank presentation, so no
+fixture .pptx files are needed.
+"""
+
+import io
+
+from behave import given, then, when
+
+from pptx import Presentation
+from pptx.dml.color import RGBColor
+from pptx.enum.dml import MSO_LINE_END_TYPE
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.util import Emu, Inches, Pt
+
+
+def _blank():
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[6])
+    return prs, slide
+
+
+@given("a blank slide with one rectangle")
+def given_blank_slide_one_rectangle(context):
+    context.prs, slide = _blank()
+    context.shape = slide.shapes.add_shape(
+        MSO_SHAPE.RECTANGLE, Inches(1), Inches(1), Inches(2), Inches(1)
+    )
+    context.slide = slide
+
+
+@given("a blank slide with one connector")
+def given_blank_slide_one_connector(context):
+    context.prs, slide = _blank()
+    context.shape = slide.shapes.add_connector(2, Inches(1), Inches(1), Inches(4), Inches(1))
+    context.slide = slide
+
+
+@given("a group scaled two-to-one containing one rectangle")
+def given_group_scaled_two_to_one(context):
+    context.prs, slide = _blank()
+    group = slide.shapes.add_group_shape()
+    context.shape = group.shapes.add_shape(
+        MSO_SHAPE.RECTANGLE, Inches(1), Inches(1), Inches(1), Inches(1)
+    )
+    x = group._element.grpSpPr.get_or_add_xfrm()
+    x.get_or_add_off().x = Emu(0)
+    x.get_or_add_off().y = Emu(0)
+    x.get_or_add_ext().cx = Emu(Inches(4))
+    x.get_or_add_ext().cy = Emu(Inches(4))
+    x.get_or_add_chOff().x = Emu(0)
+    x.get_or_add_chOff().y = Emu(0)
+    x.get_or_add_chExt().cx = Emu(Inches(2))
+    x.get_or_add_chExt().cy = Emu(Inches(2))
+
+
+@when("I set the glow color to FF0000 and radius to 20pt")
+def when_set_glow(context):
+    context.shape.shadow.glow_effect.color.rgb = RGBColor(0xFF, 0, 0)
+    context.shape.shadow.glow_effect.radius = Pt(20)
+
+
+@then("the rectangle reports glow radius 20pt and color FF0000")
+def then_glow(context):
+    assert context.shape.shadow.glow_effect.radius == Emu(Pt(20))
+    assert context.shape.shadow.glow_effect.color.rgb == RGBColor(0xFF, 0, 0)
+
+
+@when("I set the reflection blur radius to 3pt and distance to 7pt")
+def when_set_reflection(context):
+    context.shape.shadow.reflection_effect.blur_radius = Pt(3)
+    context.shape.shadow.reflection_effect.distance = Pt(7)
+
+
+@then("the rectangle reports reflection blur radius 3pt")
+def then_reflection(context):
+    assert context.shape.shadow.reflection_effect.blur_radius == Emu(Pt(3))
+
+
+@when("I set the soft edge radius to 5pt")
+def when_set_soft_edge(context):
+    context.shape.shadow.soft_edge_effect.radius = Pt(5)
+
+
+@then("the rectangle reports soft edge radius 5pt")
+def then_soft_edge(context):
+    assert context.shape.shadow.soft_edge_effect.radius == Emu(Pt(5))
+
+
+@when("I set the 3-D camera preset to orthographicFront")
+def when_set_camera(context):
+    context.shape.scene_3d.camera_preset = "orthographicFront"
+
+
+@then("the rectangle reports camera preset orthographicFront")
+def then_camera(context):
+    assert context.shape.scene_3d.camera_preset == "orthographicFront"
+
+
+@then("the scene has a light rig")
+def then_lightrig(context):
+    a = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+    s3d = context.shape._element.spPr.find(f"{a}scene3d")
+    assert s3d.find(f"{a}lightRig") is not None
+
+
+@when("I set the extrusion height to 18pt")
+def when_set_extrusion(context):
+    context.shape.shape_3d.extrusion_height = Pt(18)
+
+
+@then("the rectangle reports extrusion height 18pt")
+def then_extrusion(context):
+    assert context.shape.shape_3d.extrusion_height == Emu(Pt(18))
+
+
+@when("I flip the rectangle vertically and round-trip the file")
+def when_flip_v_roundtrip(context):
+    context.shape.flip_vertical = True
+    buf = io.BytesIO()
+    context.prs.save(buf)
+    buf.seek(0)
+    context.prs2 = Presentation(buf)
+
+
+@then("the reopened rectangle is flipped vertically")
+def then_flipped_v(context):
+    shp = [
+        s
+        for s in context.prs2.slides[0].shapes
+        if s.shape_type is not None and "AUTO_SHAPE" in str(s.shape_type)
+    ][0]
+    assert shp.flip_vertical is True
+
+
+@when("I flip the rectangle horizontally")
+def when_flip_h(context):
+    context.shape.flip_horizontal = True
+
+
+@then("the rectangle is flipped horizontally")
+def then_flipped_h(context):
+    assert context.shape.flip_horizontal is True
+
+
+@when("I duplicate the rectangle")
+def when_duplicate(context):
+    context.dup = context.shape.duplicate()
+
+
+@then("the slide has two rectangles with distinct shape ids")
+def then_two_rectangles(context):
+    ids = [s.shape_id for s in context.slide.shapes]
+    assert len(ids) == 2
+    assert len(set(ids)) == 2
+
+
+@when("I set the tail end arrowhead to a triangle and round-trip the file")
+def when_tail_triangle_roundtrip(context):
+    context.shape.line.tail_end.type = MSO_LINE_END_TYPE.TRIANGLE
+    buf = io.BytesIO()
+    context.prs.save(buf)
+    buf.seek(0)
+    context.prs2 = Presentation(buf)
+
+
+@then("the reopened connector tail end is a triangle")
+def then_tail_triangle(context):
+    conn = list(context.prs2.slides[0].shapes)[0]
+    assert conn.line.tail_end.type == MSO_LINE_END_TYPE.TRIANGLE
+
+
+@then("the rectangle slide_width is double its local width")
+def then_world_width_double(context):
+    assert context.shape.slide_width == Emu(context.shape.width * 2)