fix(comments): use PowerPoint's real modern-comment contract — parent threads now render (issue #25)

Threaded comments were invisible in PowerPoint's Comments pane despite a
green trinity and clean script UAT. Root-caused by diffing our OOXML
against a threaded comment PowerPoint for Mac itself authored+saved
(ground truth, captured this session) — three string axes and one
element were inferred wrong in Waves 1-2:

  - comment-part content type: was application/vnd.ms-powerpoint.threadedComments+xml
    -> application/vnd.ms-powerpoint.comments+xml
  - slide -> comment-part reltype: was .../2018/10/relationships/threadedComment
    -> .../2018/10/relationships/comments
  - presentation -> authors reltype: was .../2018/10/relationships/threadedCommentAuthors
    -> .../2018/10/relationships/authors
  - every <p188:cm> now emits its required first child
    <pc:sldMkLst><pc:docMk/><pc:sldMk cId="0" sldId="{p:sldId}"/></pc:sldMkLst>
    (ns .../2013/main/command) — the slide binding PowerPoint needs;
    omitting it (or the fork-private extLst anchor) leaves the comment
    unbound.

PowerPoint resolves the comment part by the slide relationship type; an
unrecognized reltype meant the part was never loaded -> empty pane.

Files: opc/constants.py (3 values; symbols unchanged so the PartFactory
registry + producer move in lockstep — Cato-audited), oxml/ns.py (+pc),
oxml/comments.py (sldMkLst ZeroOrOne + set_slide_marker), comments.py
(Comments.add binds the slide). 6 regression assertions in
DescribeThreadedCommentPowerPointContract lock all four axes
(red->green proven by stashing src) plus set_slide_marker idempotency.

Verification: pytest 3759 passed; ruff check + format clean; behave
1062 scenarios / 3215 steps 0 failed. Regenerated UAT deck opened in
real PowerPoint via Interceptor — Comments pane renders 3 threads,
correct author/text, resolved status persisted (uat/FIXED_comments_rendering.png
vs uat/REPRO_no_comments_pane.png). Cato cross-vendor audit: pass.

KNOWN-INCOMPLETE: PowerPoint still drops every <p188:reply> (replies do
not render; only parent comments do). This is a logically independent
reply-level contract defect, deliberately NOT inference-fixed — it needs
its own PowerPoint-authored <p188:reply> ground-truth diff. Tracked as a
scoped follow-up in the session ISA.

UAT script runs clean — pending maintainer visual signoff in
PowerPoint/Keynote. No push/PR per repo §6a. Refs #25.

Author: MHoroszowski

src/pptx/comments.py

@@ -393,6 +393,11 @@ def add(self, text: str, author: str, anchor=None) -> Comment:
         part = self._slide.part.modern_comments_part
         author_guid = self._slide._get_or_add_author_guid(author)
         cm = part.add_comment(_new_guid(), author_guid, _now_iso(), text)
+        # GROUND TRUTH (2026-05-17): PowerPoint binds a modern comment to its
+        # slide via a `<pc:sldMkLst>` carrying the slide's `<p:sldId>/@id`.
+        # Without it the comment never renders in the Comments pane (issue
+        # #25 root cause). slide_id is the integer sldId from presentation.xml.
+        cm.set_slide_marker(self._slide.slide_id)
         if anchor is not None and getattr(anchor, "shape_id", None) is not None:
             cm.anchorShapeId = anchor.shape_id
         return Comment(cm, self._slide)

src/pptx/opc/constants.py

@@ -88,10 +88,13 @@ class CONTENT_TYPE:
     PML_TABLE_STYLES = (
         "application/vnd.openxmlformats-officedocument.presentationml.tableStyles+xml"
     )
-    # -- modern (2018) threaded-comments part. There is no ECMA-376 content
-    # -- type for threaded comments; PowerPoint stamps the part with this
-    # -- vendor MIME type (`[MS-PPTX]`, threaded-comments extension).
-    PML_THREADED_COMMENTS = "application/vnd.ms-powerpoint.threadedComments+xml"
+    # -- modern (2018) threaded-comments part. GROUND TRUTH (2026-05-17):
+    # -- captured from a comment PowerPoint for Mac itself authored+saved —
+    # -- the part is stamped `application/vnd.ms-powerpoint.comments+xml`
+    # -- (NOT `...threadedComments+xml`, which was an inference and is the
+    # -- string PowerPoint silently fails to recognize → empty Comments
+    # -- pane, issue #25). Symbol name kept for blast-radius; value fixed.
+    PML_THREADED_COMMENTS = "application/vnd.ms-powerpoint.comments+xml"
     # -- modern (2018) threaded-comment AUTHORS part. Distinct from the legacy
     # -- `commentAuthors.xml` (ECMA-376 §19.5, integer ids): the modern
     # -- `<p188:cm>/@authorId` is a GUID and must resolve to a
@@ -311,20 +314,20 @@ class RELATIONSHIP_TYPE:
     SLIDE_UPDATE_INFO = (
         "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideUpdateInfo"
     )
-    # -- modern (2018) threaded-comments slide→part relationship. Vendor
-    # -- reltype from the MS threaded-comments extension; the slide relates
-    # -- to its modernComment_*.xml part with this type (Wave 2 wiring).
-    THREADED_COMMENT = "http://schemas.microsoft.com/office/2018/10/relationships/threadedComment"
-    # -- modern (2018) threaded-comment AUTHORS relationship. Sibling reltype
-    # -- in the same `2018/10/relationships/` family as THREADED_COMMENT; the
-    # -- PRESENTATION part (not the slide) relates to the single
-    # -- `/ppt/authors.xml` modern-authors part with this type. This is the
-    # -- `threadedCommentAuthors` member of the [MS-PPTX] threaded-comments
-    # -- extension (the relationship PowerPoint stamps from presentation.xml
-    # -- to authors.xml) — its name mirrors the THREADED_COMMENT sibling and
-    # -- is what real PowerPoint emits/expects; the bare `.../authors` form is
-    # -- not the one PowerPoint resolves `<p188:cm>/@authorId` GUIDs through.
-    AUTHORS = "http://schemas.microsoft.com/office/2018/10/relationships/threadedCommentAuthors"
+    # -- modern (2018) threaded-comments slide→part relationship. GROUND
+    # -- TRUTH (2026-05-17, PowerPoint-authored capture): the slide relates
+    # -- to its modern-comments part with `.../2018/10/relationships/comments`
+    # -- (NOT `.../threadedComment`). PowerPoint locates the comment part by
+    # -- THIS reltype off the slide; the prior `threadedComment` form is
+    # -- unrecognized → the part is never loaded → empty Comments pane.
+    THREADED_COMMENT = "http://schemas.microsoft.com/office/2018/10/relationships/comments"
+    # -- modern (2018) threaded-comment AUTHORS relationship. GROUND TRUTH
+    # -- (2026-05-17, PowerPoint-authored capture): the PRESENTATION part
+    # -- relates to `/ppt/authors.xml` with `.../2018/10/relationships/authors`
+    # -- (NOT `.../threadedCommentAuthors`). The bare `.../authors` form IS
+    # -- the one PowerPoint emits and resolves `<p188:cm>/@authorId` GUIDs
+    # -- through — the earlier `threadedCommentAuthors` was an inference.
+    AUTHORS = "http://schemas.microsoft.com/office/2018/10/relationships/authors"
     STYLES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles"
     TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table"
     TABLE_SINGLE_CELLS = (

src/pptx/oxml/comments.py

@@ -322,8 +322,19 @@ class CT_ThreadedComment(BaseOxmlElement):
     ``<p188:txBody>`` rich-text body, and an optional ``<p188:replyLst>``
     holding the reply thread. ``status`` (e.g. ``"resolved"``) marks a
     closed thread.
+
+    GROUND TRUTH (2026-05-17, captured from a comment PowerPoint for Mac
+    authored+saved): the FIRST child of every top-level ``<p188:cm>`` is a
+    ``<pc:sldMkLst>`` slide-binding marker
+    (``<pc:docMk/><pc:sldMk cId=".." sldId=".."/>``, ns
+    ``http://schemas.microsoft.com/office/powerpoint/2013/main/command``).
+    This is how PowerPoint binds a comment to its slide — NOT the per-slide
+    relationship and NOT the fork-private ``extLst`` anchor. Omitting it
+    leaves the comment unbound and PowerPoint does not render it (issue #25
+    empty-Comments-pane root cause). Replies do not carry their own marker.
     """
 
+    sldMkLst = ZeroOrOne("pc:sldMkLst", successors=("p188:txBody", "p188:replyLst", "p188:extLst"))
     txBody = ZeroOrOne("p188:txBody", successors=("p188:replyLst", "p188:extLst"))
     replyLst: "CT_ThreadedCommentReplyList | None" = ZeroOrOne(  # pyright: ignore
         "p188:replyLst", successors=("p188:extLst",)
@@ -386,6 +397,28 @@ def anchorShapeId(self, shape_id: int) -> None:
         ext.append(anchor)
         extLst.append(ext)
 
+    def set_slide_marker(self, slide_id: int, c_id: int = 0) -> None:
+        """Set the ``<pc:sldMkLst>`` binding this comment to slide `slide_id`.
+
+        Builds ``<pc:sldMkLst><pc:docMk/><pc:sldMk cId=c_id sldId=slide_id/>
+        </pc:sldMkLst>`` and places it as the FIRST child of this
+        ``<p188:cm>`` (before ``<p188:txBody>``), matching the structure
+        PowerPoint itself emits. ``slide_id`` is the slide's
+        ``<p:sldId>/@id`` (e.g. 256 for the first slide); ``c_id`` is the
+        collaboration/change id PowerPoint stamps ``0`` for a locally
+        authored comment. Replaces any pre-existing marker (idempotent).
+        """
+        existing = self.sldMkLst
+        if existing is not None:
+            self.remove(existing)
+        self.insert(
+            0,
+            parse_xml(
+                "<pc:sldMkLst %s><pc:docMk/><pc:sldMk "
+                'cId="%d" sldId="%d"/></pc:sldMkLst>' % (nsdecls("pc"), c_id, slide_id)
+            ),
+        )
+
     @classmethod
     def new(cls, comment_id: str, author_id: str, created: str) -> CT_ThreadedComment:
         """Return a minimal-valid ``<p188:cm>`` with an empty text body."""

src/pptx/oxml/ns.py

@@ -23,6 +23,7 @@
     "p": "http://schemas.openxmlformats.org/presentationml/2006/main",
     "p14": "http://schemas.microsoft.com/office/powerpoint/2010/main",
     "p188": "http://schemas.microsoft.com/office/powerpoint/2018/8/main",
+    "pc": "http://schemas.microsoft.com/office/powerpoint/2013/main/command",
     "pd": "http://schemas.openxmlformats.org/drawingml/2006/presentationDrawing",
     "pic": "http://schemas.openxmlformats.org/drawingml/2006/picture",
     "pr": "http://schemas.openxmlformats.org/package/2006/relationships",

tests/test_issue25_comments.py

@@ -674,5 +674,90 @@ def it_places_bodyPr_before_the_paragraph(self):
         )
 
 
+class DescribeThreadedCommentPowerPointContract:
+    """Regression: the modern-comment OOXML must match PowerPoint ground truth.
+
+    Captured 2026-05-17 from a threaded comment PowerPoint for Mac itself
+    authored+saved. Three string axes plus a slide-binding element were
+    inferred wrong in Waves 1-2 (content type ``threadedComments+xml``,
+    reltypes ``threadedComment``/``threadedCommentAuthors``, and a missing
+    ``<pc:sldMkLst>``). With any of them wrong PowerPoint silently fails to
+    load/bind the part → empty Comments pane while the test trinity is
+    green. This locks every axis to the PowerPoint-emitted contract.
+    """
+
+    def it_uses_the_powerpoint_content_type_and_reltypes(self):
+        assert CT.PML_THREADED_COMMENTS == "application/vnd.ms-powerpoint.comments+xml"
+        assert RT.THREADED_COMMENT == (
+            "http://schemas.microsoft.com/office/2018/10/relationships/comments"
+        )
+        assert RT.AUTHORS == "http://schemas.microsoft.com/office/2018/10/relationships/authors"
+
+    def _round_trip_zip(self):
+        prs = Presentation()
+        s = prs.slides.add_slide(prs.slide_layouts[1])
+        s.comments.add("Looks great! Ship it.", author="Alex Reviewer")
+        buf = io.BytesIO()
+        prs.save(buf)
+        buf.seek(0)
+        import zipfile
+
+        return zipfile.ZipFile(buf), s.slide_id
+
+    def it_stamps_the_powerpoint_content_type_in_content_types(self):
+        z, _ = self._round_trip_zip()
+        ctypes = z.read("[Content_Types].xml").decode()
+        assert "application/vnd.ms-powerpoint.comments+xml" in ctypes
+        assert "threadedComments+xml" not in ctypes
+
+    def it_relates_slide_to_part_and_presentation_to_authors_by_pp_reltype(self):
+        z, _ = self._round_trip_zip()
+        slide_rels = z.read("ppt/slides/_rels/slide1.xml.rels").decode()
+        prs_rels = z.read("ppt/_rels/presentation.xml.rels").decode()
+        assert "/2018/10/relationships/comments" in slide_rels
+        assert "/2018/10/relationships/threadedComment" not in slide_rels
+        assert "/2018/10/relationships/authors" in prs_rels
+        assert "threadedCommentAuthors" not in prs_rels
+
+    def it_binds_each_comment_to_its_slide_via_sldMkLst(self):
+        import re
+
+        z, slide_id = self._round_trip_zip()
+        name = next(n for n in z.namelist() if "modernComment" in n)
+        xml = z.read(name).decode()
+        # <pc:sldMkLst> present with <pc:docMk/> and <pc:sldMk sldId=...>
+        assert "sldMkLst" in xml, "every <p188:cm> needs a <pc:sldMkLst> slide binding"
+        assert "docMk" in xml
+        assert "sldMk" in xml
+        m = re.search(r'<pc:sldMk[^>]*sldId="(\d+)"', xml)
+        assert m is not None, "<pc:sldMk> must carry the slide's sldId"
+        assert int(m.group(1)) == slide_id, (
+            "sldMk/@sldId must equal the slide's <p:sldId>/@id (%d) so "
+            "PowerPoint binds the comment to the right slide" % slide_id
+        )
+
+    def it_places_sldMkLst_before_txBody_in_child_order(self):
+        z, _ = self._round_trip_zip()
+        name = next(n for n in z.namelist() if "modernComment" in n)
+        xml = z.read(name).decode()
+        assert xml.index("sldMkLst") < xml.index("txBody"), (
+            "<pc:sldMkLst> must precede <p188:txBody> (PowerPoint child order)"
+        )
+
+    def it_keeps_exactly_one_sldMkLst_when_set_twice(self):
+        # Cato low-finding lock: set_slide_marker must REPLACE, not prepend a
+        # second <pc:sldMkLst>, if invoked again on the same comment element.
+        prs = Presentation()
+        s = prs.slides.add_slide(prs.slide_layouts[1])
+        c = s.comments.add("once", author="Rev")
+        c._cm.set_slide_marker(s.slide_id)
+        c._cm.set_slide_marker(s.slide_id)
+        from pptx.oxml.ns import qn
+
+        assert len(c._cm.findall(qn("pc:sldMkLst"))) == 1, (
+            "set_slide_marker must be idempotent (exactly one <pc:sldMkLst>)"
+        )
+
+
 if __name__ == "__main__":
     raise SystemExit(pytest.main([__file__, "-q"]))