rbpptx 0.1.0 → 0.2.0

data/lib/rbpptx/presentation.rb

@@ -1,18 +1,25 @@
 module Rbpptx
   # A PowerPoint presentation loaded from a +.pptx+ file.
   #
-  # Reading is the only mode wired up at present: the package is opened, the
-  # presentation part is located via +_rels/.rels+, the slide id list is read
-  # in document order, and slides are resolved through the presentation's own
-  # rels. Each {Slide} retains a handle on the underlying ZIP and parses its
-  # XML lazily.
+  # The package is opened, the presentation part is located via
+  # +_rels/.rels+, the slide id list is read in document order, and slides
+  # are resolved through the presentation's own rels. Each {Slide} parses
+  # its XML lazily.
+  #
+  # Slide-level structure edits ({#move_slide}, {#delete_slide}) rewrite
+  # only the bookkeeping parts that must change — +ppt/presentation.xml+,
+  # its rels, and +[Content_Types].xml+ — and leave every other part as-is.
   class Presentation
     P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main".freeze
     A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
     R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships".freeze
+    P14_NS = "http://schemas.microsoft.com/office/powerpoint/2010/main".freeze
     PKG_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships".freeze
     OFFICE_DOC_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument".freeze
     SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide".freeze
+    NOTES_SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide".freeze
+    NOTES_MASTER_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster".freeze
+    NOTES_SLIDE_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml".freeze
 
     LEGACY_PPT_SIGNATURE = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b.freeze
     ZIP_SIGNATURE = "PK\x03\x04".b.freeze
@@ -31,7 +38,7 @@ module Rbpptx
       @closed = false
       validate_signature!
       begin
-        @zip = Zip::File.open(@path)
+        @package = Package.new(@path)
       rescue Zip::Error => e
         raise UnsupportedFormatError, "#{@path}: not a valid .pptx (#{e.message})"
       end
@@ -44,12 +51,104 @@ module Rbpptx
       @slides ||= build_slides
     end
 
+    # @param index [Integer] zero-based; negative counts from the end
+    # @return [Slide]
+    # @raise [SlideNotFoundError] if +index+ is out of range
+    def slide(index)
+      slides.fetch(index)
+    rescue IndexError
+      raise SlideNotFoundError, "#{@path}: no slide at index #{index} (#{slides.size} slides)"
+    end
+
+    # Moves a slide to a new position in the presentation order. Only
+    # +<p:sldIdLst>+ in +ppt/presentation.xml+ is rewritten.
+    #
+    # @param slide_or_index [Slide, Integer] the slide to move
+    # @param new_index [Integer] zero-based destination; negative counts from
+    #   the end (+-1+ moves to the last position)
+    # @return [Array<Slide>] slides in the new order
+    # @raise [SlideNotFoundError] if either argument is out of range
+    def move_slide(slide_or_index, new_index)
+      target = resolve_slide(slide_or_index)
+      size = slides.size
+      to = new_index.negative? ? new_index + size : new_index
+      raise SlideNotFoundError, "#{@path}: destination index #{new_index} out of range (#{size} slides)" unless (0...size).cover?(to)
+      return slides if slides.index(target) == to
+
+      others = slides - [target]
+      node = @sld_id_nodes.fetch(target)
+      node.unlink
+      if to.zero?
+        @sld_id_nodes.fetch(others.first).add_previous_sibling(node)
+      else
+        @sld_id_nodes.fetch(others[to - 1]).add_next_sibling(node)
+      end
+
+      @slides = others.insert(to, target)
+      @package.touch(@presentation_part)
+      @slides
+    end
+
+    # Removes a slide from the presentation, together with its notes page.
+    #
+    # The slide's +<p:sldId>+, its relationship from the presentation, its
+    # entries in custom shows and sections, its content-type override, and
+    # the slide/notes parts themselves are dropped. Shared parts (layouts,
+    # media) stay in the package even if no other slide uses them.
+    #
+    # Other parts may still point at the slide — typically "jump to slide"
+    # hyperlinks on an agenda slide. By default deletion is then refused,
+    # because removing the slide would leave a dangling reference that
+    # PowerPoint reports as a corrupt file. Pass +unlink: true+ to remove
+    # those hyperlinks (+<a:hlinkClick>+ / +<a:hlinkHover>+; the link text
+    # stays) and their relationships first. References that are not
+    # hyperlinks always cause a refusal.
+    #
+    # @param slide_or_index [Slide, Integer]
+    # @param unlink [Boolean] remove hyperlinks on other parts that target
+    #   this slide
+    # @return [Slide] the removed slide (detached; do not use it further)
+    # @raise [SlideNotFoundError] if the index is out of range
+    # @raise [Rbpptx::Error] if another part references the slide and the
+    #   reference cannot be removed
+    def delete_slide(slide_or_index, unlink: false)
+      target = resolve_slide(slide_or_index)
+      part = target.part_name
+      notes_part = @package.related(part, NOTES_SLIDE_REL_TYPE).first
+
+      referrers = @package.referrers_of(part) - [@presentation_part, part, notes_part]
+      unless referrers.empty?
+        unless unlink
+          raise Error, "#{@path}: cannot delete #{part}; it is still referenced by #{referrers.join(', ')} " \
+                       "(pass unlink: true to remove hyperlinks pointing at it)"
+        end
+        unlink_references!(referrers, part)
+      end
+
+      node = @sld_id_nodes.delete(target)
+      sld_id = node["id"]
+      rid = node.attribute_with_ns("id", R_NS)&.value
+      node.remove
+
+      pres_doc = @package.xml(@presentation_part)
+      pres_doc.xpath("//p14:sldId[@id=$id]", { "p14" => P14_NS }, { "id" => sld_id }).each(&:remove)
+      pres_doc.xpath("//p:custShow/p:sldLst/p:sld[@r:id=$rid]", { "p" => P_NS, "r" => R_NS }, { "rid" => rid }).each(&:remove)
+      @package.touch(@presentation_part)
+
+      @package.remove_relationship(@presentation_part, rid)
+      @package.delete(part)
+      @package.delete(notes_part) if notes_part
+
+      @slides.delete(target)
+      target
+    end
+
     # Writes the presentation out to +path+, preserving every part that has
-    # not been mutated byte-for-byte. Slides whose shapes have been edited are
-    # re-serialized from their in-memory Nokogiri document; all other entries
-    # (themes, masters, layouts, media, fonts, rels) are streamed straight
-    # from the source ZIP without re-parsing, so unknown PowerPoint features
-    # round-trip unchanged.
+    # not been mutated byte-for-byte. Edited parts are re-serialized from
+    # their in-memory Nokogiri documents; all other entries (themes, masters,
+    # layouts, media, fonts) are streamed straight from the source ZIP
+    # without re-parsing, so unknown PowerPoint features round-trip
+    # unchanged.
     #
     # +path+ may equal the original load path; the new file is written to a
     # temp file in the same directory and atomically renamed into place. On
@@ -59,31 +158,7 @@ module Rbpptx
     # @return [String] the path that was written
     def save(path)
       ensure_open!
-      out_path = path.to_s
-      overrides = (@slides || []).each_with_object({}) do |slide, h|
-        h[slide.part_name] = slide.to_xml if slide.dirty?
-      end
-
-      tmp_path = "#{out_path}.rbpptx-tmp.#{Process.pid}.#{rand(1 << 32).to_s(16)}"
-      begin
-        Zip::OutputStream.open(tmp_path) do |out|
-          @zip.each do |entry|
-            next if entry.directory?
-
-            if (override_xml = overrides[entry.name])
-              out.put_next_entry(entry.name)
-              out.write(override_xml)
-            else
-              out.copy_raw_entry(entry)
-            end
-          end
-        end
-        File.rename(tmp_path, out_path)
-      rescue StandardError
-        File.unlink(tmp_path) if File.exist?(tmp_path)
-        raise
-      end
-
+      out_path = @package.save(path.to_s)
       (@slides || []).each(&:clear_dirty!)
       out_path
     end
@@ -94,8 +169,8 @@ module Rbpptx
     def close
       return false if @closed
 
-      @zip&.close
-      @zip = nil
+      @package&.close
+      @package = nil
       @closed = true
       true
     end
@@ -105,6 +180,33 @@ module Rbpptx
       @closed
     end
 
+    # Creates an empty notes page for +slide+ from the notes master.
+    #
+    # @api private
+    # @return [NotesSlide]
+    # @raise [Rbpptx::Error] if the presentation has no notes master
+    def create_notes_slide_for(slide)
+      ensure_open!
+      slides # ensures @presentation_part is resolved
+      master = @package.related(@presentation_part, NOTES_MASTER_REL_TYPE).first
+      unless master
+        raise Error, "#{@path}: presentation has no notes master; cannot create a notes slide " \
+                     "(add speaker notes to any slide in PowerPoint once to create one)"
+      end
+
+      n = 1
+      n += 1 while @package.part?("ppt/notesSlides/notesSlide#{n}.xml")
+      part = "ppt/notesSlides/notesSlide#{n}.xml"
+
+      @package.add(part, Nokogiri::XML(new_notes_slide_xml))
+      @package.add_relationship(part, NOTES_MASTER_REL_TYPE, master)
+      @package.add_relationship(part, SLIDE_REL_TYPE, slide.part_name)
+      @package.add_relationship(slide.part_name, NOTES_SLIDE_REL_TYPE, part)
+      @package.add_content_type_override(part, NOTES_SLIDE_CONTENT_TYPE)
+
+      NotesSlide.new(package: @package, part_name: part)
+    end
+
     private
 
     def ensure_open!
@@ -126,23 +228,70 @@ module Rbpptx
       end
     end
 
+    def resolve_slide(slide_or_index)
+      case slide_or_index
+      when Integer then slide(slide_or_index)
+      when Slide
+        slides.find { |s| s.equal?(slide_or_index) } or
+          raise SlideNotFoundError, "#{@path}: slide #{slide_or_index.part_name} is not part of this presentation"
+      else
+        raise TypeError, "expected Rbpptx::Slide or Integer, got #{slide_or_index.class}"
+      end
+    end
+
+    HYPERLINK_ELEMENTS = %w[hlinkClick hlinkHover].freeze
+    private_constant :HYPERLINK_ELEMENTS
+
+    # Removes hyperlinks in +referrers+ that target +part+. Everything is
+    # validated before anything is mutated, so a refusal leaves the package
+    # untouched.
+    def unlink_references!(referrers, part)
+      plan = referrers.map do |source|
+        doc = @package.xml(source)
+        rels = @package.relationships(source).select { |r| r.part == part }
+        uses = rels.to_h do |rel|
+          attrs = doc.xpath("//@*[namespace-uri()=$ns and .=$rid]", nil, { "ns" => R_NS, "rid" => rel.id })
+          foreign = attrs.reject { |a| a.parent.namespace&.href == A_NS && HYPERLINK_ELEMENTS.include?(a.parent.name) }
+          unless foreign.empty?
+            raise Error, "#{@path}: cannot delete #{part}; #{source} references it from " \
+                         "<#{foreign.first.parent.name}>, which is not a hyperlink"
+          end
+          [rel.id, attrs.map(&:parent)]
+        end
+        [source, uses]
+      end
+
+      plan.each do |source, uses|
+        uses.each do |rid, elements|
+          elements.each(&:remove)
+          @package.remove_relationship(source, rid)
+        end
+        owner = slides.find { |s| s.part_name == source }
+        owner ? owner.mark_dirty! : @package.touch(source)
+      end
+    end
+
     def build_slides
-      pres_part = locate_presentation_part
-      pres_rels = parse_rels(rels_path_for(pres_part))
-      pres_dir = File.dirname(pres_part)
+      @presentation_part = locate_presentation_part
+      pres_rels = @package.relationships(@presentation_part).to_h { |r| [r.id, r] }
 
-      doc = parse_xml(pres_part)
-      sld_ids = doc.xpath("/p:presentation/p:sldIdLst/p:sldId", "p" => P_NS)
+      doc = @package.xml(@presentation_part)
+      raise PresentationFormatError, "#{@path}: #{@presentation_part} has no root element" unless doc.root
 
-      sld_ids.map do |sld_id|
+      @sld_id_nodes = {}.compare_by_identity
+      doc.xpath("/p:presentation/p:sldIdLst/p:sldId", "p" => P_NS).map do |sld_id|
         rid = sld_id.attribute_with_ns("id", R_NS)&.value
-        target = pres_rels[rid] or raise PresentationFormatError, "#{@path}: rId #{rid.inspect} not found in presentation rels"
-        Slide.new(zip: @zip, part_name: resolve_relative(pres_dir, target))
+        rel = pres_rels[rid]
+        raise PresentationFormatError, "#{@path}: rId #{rid.inspect} not found in presentation rels" unless rel&.part
+
+        slide = Slide.new(package: @package, part_name: rel.part, presentation: self)
+        @sld_id_nodes[slide] = sld_id
+        slide
       end
     end
 
     def locate_presentation_part
-      doc = parse_xml("_rels/.rels")
+      doc = @package.xml("_rels/.rels")
       rel = doc.at_xpath(
         "/pkg:Relationships/pkg:Relationship[@Type=$type]",
         { "pkg" => PKG_REL_NS },
@@ -154,34 +303,11 @@ module Rbpptx
       target.sub(%r{\A/}, "")
     end
 
-    def parse_rels(rels_part)
-      entry = @zip.find_entry(rels_part)
-      return {} unless entry
-
-      doc = Nokogiri::XML(entry.get_input_stream.read)
-      doc.xpath("/pkg:Relationships/pkg:Relationship", "pkg" => PKG_REL_NS).each_with_object({}) do |r, h|
-        h[r["Id"]] = r["Target"]
-      end
-    end
-
-    def parse_xml(part_name)
-      entry = @zip.find_entry(part_name) or raise PresentationFormatError, "#{@path}: missing part #{part_name}"
-      doc = Nokogiri::XML(entry.get_input_stream.read)
-      raise PresentationFormatError, "#{@path}: #{part_name}: #{doc.errors.first}" unless doc.errors.empty?
-
-      doc
-    end
-
-    def rels_path_for(part_name)
-      dir = File.dirname(part_name)
-      base = File.basename(part_name)
-      dir == "." ? "_rels/#{base}.rels" : "#{dir}/_rels/#{base}.rels"
-    end
-
-    def resolve_relative(base_dir, target)
-      return target.sub(%r{\A/}, "") if target.start_with?("/")
-
-      File.expand_path(target, "/#{base_dir}").sub(%r{\A/}, "")
+    def new_notes_slide_xml
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+        <p:notes xmlns:a="#{A_NS}" xmlns:r="#{R_NS}" xmlns:p="#{P_NS}"><p:cSld><p:spTree><p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr><p:sp><p:nvSpPr><p:cNvPr id="2" name="Slide Image Placeholder 1"/><p:cNvSpPr><a:spLocks noGrp="1" noRot="1" noChangeAspect="1"/></p:cNvSpPr><p:nvPr><p:ph type="sldImg"/></p:nvPr></p:nvSpPr><p:spPr/></p:sp><p:sp><p:nvSpPr><p:cNvPr id="3" name="Notes Placeholder 2"/><p:cNvSpPr><a:spLocks noGrp="1"/></p:cNvSpPr><p:nvPr><p:ph type="body" idx="1"/></p:nvPr></p:nvSpPr><p:spPr/><p:txBody><a:bodyPr/><a:lstStyle/><a:p/></p:txBody></p:sp></p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:notes>
+      XML
     end
   end
 end

data/lib/rbpptx/shape.rb

@@ -1,9 +1,7 @@
-require "cgi"
-
 module Rbpptx
-  # A single shape (+<p:sp>+) on a slide.
+  # A single shape (+<p:sp>+) on a slide or notes slide.
   #
-  # Two layers of text access are exposed:
+  # Two layers of text access are exposed (see {TextBody}):
   #
   # * {#text} / {#text=} — bulldozer-level: read the entire concatenated
   #   text body, or replace it wholesale. The setter cleans the text body's
@@ -15,17 +13,19 @@ module Rbpptx
   #   breaks, paragraph properties, and any unknown OOXML extensions on the
   #   shape are preserved.
   #
-  # In addition, {#placeholder_type} reads the shape's placeholder role from
-  # +<p:nvSpPr>/<p:nvPr>/<p:ph type="...">+ so callers can target shapes by
-  # semantic role (e.g. +:ctrTitle+, +:subTitle+, +:body+) instead of by
-  # index.
+  # In addition, {#placeholder_type} and {#placeholder_idx} read the shape's
+  # placeholder role from +<p:nvSpPr>/<p:nvPr>/<p:ph>+ so callers can target
+  # shapes by semantic role (e.g. +:ctrTitle+, +:subTitle+, +:body+) instead
+  # of by index. See also {Slide#placeholders} and {Slide#title}.
   class Shape
+    include TextBody
+
     P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main".freeze
     A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
 
     # @param node [Nokogiri::XML::Element] the +<p:sp>+ element
-    # @param slide [Slide, nil] back-reference used to mark the slide dirty
-    #   when this shape is mutated
+    # @param slide [Slide, NotesSlide, nil] back-reference used to mark the
+    #   owning part dirty when this shape is mutated
     def initialize(node:, slide: nil)
       @node = node
       @slide = slide
@@ -37,91 +37,47 @@ module Rbpptx
       @node.at_xpath("./p:nvSpPr/p:cNvPr/@name", "p" => P_NS)&.value
     end
 
+    # @return [Boolean] whether the shape is a placeholder
+    def placeholder?
+      !placeholder_node.nil?
+    end
+
     # @return [Symbol, nil] the placeholder type as a Symbol (e.g.
     #   +:ctrTitle+, +:subTitle+, +:title+, +:body+, +:obj+, +:ftr+,
     #   +:dt+, +:sldNum+, +:pic+), or +nil+ if the shape is not a
     #   placeholder. Returns +:body+ when the shape has a +<p:ph>+ element
     #   with no +type+ attribute, matching the OOXML default.
     def placeholder_type
-      ph = @node.at_xpath("./p:nvSpPr/p:nvPr/p:ph", "p" => P_NS)
+      ph = placeholder_node
       return nil unless ph
 
       type = ph["type"]
       type ? type.to_sym : :body
     end
 
-    # @return [Array<Paragraph>] paragraphs in the shape's text body, in
-    #   document order. Returns +[]+ if the shape has no +<p:txBody>+ (e.g.
-    #   picture or group shapes).
-    def paragraphs
-      txbody = @node.at_xpath("./p:txBody", "p" => P_NS)
-      return [] unless txbody
+    # @return [Integer, nil] the placeholder index (+<p:ph idx="...">+) that
+    #   links the shape to its layout placeholder, or +nil+ if the shape is
+    #   not a placeholder. Returns +0+ when +idx+ is omitted, matching the
+    #   OOXML default.
+    def placeholder_idx
+      ph = placeholder_node
+      return nil unless ph
 
-      txbody.xpath("./a:p", "a" => A_NS).map { |p| Paragraph.new(node: p, slide: @slide) }
+      ph["idx"] ? Integer(ph["idx"], 10) : 0
     end
 
-    # @return [Array<Run>] all runs in the shape's text body, flattened
-    #   across paragraphs in document order
-    def runs
-      paragraphs.flat_map(&:runs)
-    end
+    private
 
-    # Concatenated text of the shape's text body. Paragraphs are joined with
-    # +"\n"+; soft line breaks (+<a:br>+) inside a paragraph are also
-    # rendered as +"\n"+.
-    #
-    # @return [String]
-    def text
-      paragraphs.map(&:text).join("\n")
+    def placeholder_node
+      @node.at_xpath("./p:nvSpPr/p:nvPr/p:ph", "p" => P_NS)
     end
 
-    # Replaces the shape's text body. Lines (separated by +"\n"+) become
-    # individual +<a:p>+ paragraphs. Run properties from the first existing
-    # +<a:rPr>+ (font, size, color, language) are cloned onto each new run
-    # so template formatting carries through.
-    #
-    # This is the bulldozer-level setter; for edits that need to preserve
-    # individual run formatting (e.g. replacing a placeholder inside a
-    # multi-run paragraph), use {#runs} or {#paragraphs} and {Run#text=}
-    # instead.
-    #
-    # Shapes without a +<p:txBody>+ (e.g. picture or group shapes) cannot
-    # accept text and will raise.
-    #
-    # @param new_text [String]
-    # @return [String] the value that was set
-    # @raise [Rbpptx::Error] if the shape has no text body
-    def text=(new_text)
-      txbody = @node.at_xpath("./p:txBody", "p" => P_NS)
-      raise Error, "shape has no <p:txBody>; cannot set text" unless txbody
-
-      template_rpr = txbody.at_xpath(".//a:r/a:rPr", "a" => A_NS)
-      txbody.xpath("./a:p", "a" => A_NS).each(&:remove)
-
-      lines = new_text.to_s.empty? ? [""] : new_text.to_s.split("\n", -1)
-      txbody.add_child(build_paragraphs_xml(lines))
-
-      if template_rpr
-        txbody.xpath("./a:p/a:r", "a" => A_NS).each do |run|
-          first_child = run.children.first
-          first_child ? first_child.add_previous_sibling(template_rpr.dup) : run.add_child(template_rpr.dup)
-        end
-      end
-
-      @slide&.mark_dirty!
-      new_text
+    def text_body_node
+      @node.at_xpath("./p:txBody", "p" => P_NS)
     end
 
-    private
-
-    def build_paragraphs_xml(lines)
-      lines.map do |line|
-        if line.empty?
-          "<a:p/>"
-        else
-          "<a:p><a:r><a:t>#{CGI.escapeHTML(line)}</a:t></a:r></a:p>"
-        end
-      end.join
+    def text_body_label
+      "shape has no <p:txBody>"
     end
   end
 end

data/lib/rbpptx/shape_container.rb

@@ -0,0 +1,161 @@
+module Rbpptx
+  # Shape-tree navigation shared by {Slide}, {NotesSlide} and {GroupShape}.
+  #
+  # Including classes provide a private +shape_tree_node+ returning the
+  # element whose children are the shapes (+<p:spTree>+ or +<p:grpSp>+),
+  # and a private +owner_part+ returning the part to mark dirty on edits.
+  #
+  # Only the element kinds rbpptx understands are surfaced: +<p:sp>+,
+  # +<p:grpSp>+, and +<p:graphicFrame>+ holding an +<a:tbl>+. Pictures,
+  # connectors, charts, SmartArt and +<mc:AlternateContent>+ wrappers are
+  # skipped and left untouched.
+  module ShapeContainer
+    P_NS = "http://schemas.openxmlformats.org/presentationml/2006/main".freeze
+    A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main".freeze
+
+    # @return [Array<Shape>] direct +<p:sp>+ children, in document order
+    def shapes
+      direct_children("sp").map { |n| Shape.new(node: n, slide: owner_part) }
+    end
+
+    # @return [Array<GroupShape>] direct +<p:grpSp>+ children, in document
+    #   order
+    def groups
+      direct_children("grpSp").map { |n| GroupShape.new(node: n, slide: owner_part) }
+    end
+
+    # @return [Array<Table>] direct +<p:graphicFrame>+ children that hold a
+    #   table, in document order
+    def tables
+      direct_children("graphicFrame").filter_map { |n| build_table(n) }
+    end
+
+    # @return [Array<Shape>] every +<p:sp>+ in the tree, descending into
+    #   groups (nested to any depth), in document order
+    def all_shapes
+      walk_tree(shape_tree_node, [], [])[0]
+    end
+
+    # @return [Array<Table>] every table in the tree, descending into groups,
+    #   in document order
+    def all_tables
+      walk_tree(shape_tree_node, [], [])[1]
+    end
+
+    private
+
+    def direct_children(local_name)
+      node = shape_tree_node
+      return [] unless node
+
+      node.xpath("./p:#{local_name}", "p" => P_NS)
+    end
+
+    def build_table(frame)
+      return nil unless frame.at_xpath("./a:graphic/a:graphicData/a:tbl", "a" => A_NS)
+
+      Table.new(node: frame, slide: owner_part)
+    end
+
+    def walk_tree(node, shapes, tables)
+      return [shapes, tables] unless node
+
+      node.element_children.each do |child|
+        next unless child.namespace&.href == P_NS
+
+        case child.name
+        when "sp" then shapes << Shape.new(node: child, slide: owner_part)
+        when "grpSp" then walk_tree(child, shapes, tables)
+        when "graphicFrame"
+          table = build_table(child)
+          tables << table if table
+        end
+      end
+      [shapes, tables]
+    end
+  end
+
+  # A group shape (+<p:grpSp>+). Groups nest; use {#shapes} for direct
+  # children or {#all_shapes} to flatten the whole subtree.
+  class GroupShape
+    include ShapeContainer
+
+    # @param node [Nokogiri::XML::Element] the +<p:grpSp>+ element
+    # @param slide [Slide, NotesSlide, nil] owning part
+    def initialize(node:, slide: nil)
+      @node = node
+      @slide = slide
+    end
+
+    # @return [String, nil] value of +<p:nvGrpSpPr>/<p:cNvPr name="...">+
+    def name
+      @node.at_xpath("./p:nvGrpSpPr/p:cNvPr/@name", "p" => P_NS)&.value
+    end
+
+    # @return [String] text of every shape in the group (see {#all_shapes}),
+    #   one shape per line, empty shapes skipped. Read-only convenience.
+    def text
+      all_shapes.map(&:text).reject(&:empty?).join("\n")
+    end
+
+    private
+
+    def shape_tree_node
+      @node
+    end
+
+    def owner_part
+      @slide
+    end
+  end
+
+  # The placeholders of a slide, addressable by type or by index.
+  #
+  #   slide.placeholders[:title]   # first placeholder of type :title
+  #   slide.placeholders[1]        # placeholder with <p:ph idx="1">
+  #
+  # Integer keys follow python-pptx: they match the placeholder's +idx+
+  # attribute (see {Shape#placeholder_idx}), *not* its position in the list.
+  class Placeholders
+    include Enumerable
+
+    # @param shapes [Array<Shape>]
+    def initialize(shapes)
+      @shapes = shapes.select(&:placeholder?)
+    end
+
+    # @yieldparam shape [Shape]
+    def each(&block)
+      return enum_for(:each) { size } unless block
+
+      @shapes.each(&block)
+      self
+    end
+
+    # @param key [Symbol, Integer] placeholder type, or placeholder +idx+
+    # @return [Shape, nil]
+    def [](key)
+      case key
+      when Symbol then @shapes.find { |s| s.placeholder_type == key }
+      when Integer then @shapes.find { |s| s.placeholder_idx == key }
+      else raise TypeError, "placeholder key must be a Symbol (type) or Integer (idx), got #{key.class}"
+      end
+    end
+
+    # @return [Integer]
+    def size
+      @shapes.size
+    end
+    alias length size
+
+    # @return [Boolean]
+    def empty?
+      @shapes.empty?
+    end
+
+    # @return [Array<Shape>]
+    def to_a
+      @shapes.dup
+    end
+  end
+end