Slides and Shapes¶

Slide Actions¶

Slides always append at the end via add-blank — there is no "insert blank at position N" action; use add-blank then move-to if you need a blank slide inserted mid-deck. See deck-builder.md for planning multi-slide order.

Sections¶

Sections group contiguous ranges of slides for organizational purposes (visible in PowerPoint's slide thumbnail panel) — they do not affect slide content or rendering. A slide's section membership is purely positional (determined by where the slide sits between section boundaries), so reordering slides with move-to can move them into a different section.

slide(action: "add-section", session_id: ..., section_index: 1, section_name: "Introduction")
slide(action: "add-section", session_id: ..., section_index: 2, section_name: "Deep Dive")
  → splits the deck into two sections at the current slide count boundary

slide(action: "get-section-count", session_id: ...) → sectionCount: 2
slide(action: "rename-section", session_id: ..., section_index: 2, section_name: "Details")

Shape Actions¶

All position/size values are points (see deck-builder.md for the 960×540pt 16:9 reference).

Shape Formatting Actions¶

Finding a just-grouped shape's index: group does not return the new group shape's own shapeIndex — reading .Index off a freshly-created COM group object is unreliable in this codebase's NoPIA late-binding setup. If the shapes you grouped were the last shapes added to the slide (highest indices, nothing added after them), the resulting group occupies the new, smaller shapeCount as its index (since grouping N shapes always removes N-1 from the slide's shape list). Otherwise, call shape(action: "get-count", ...) before and after grouping and inspect via a follow-up read if you need to confirm which index now holds the group.

Hyperlinks¶

set-hyperlink/get-hyperlink/remove-hyperlink manage a shape's mouse-click action — clicking the shape at presentation time navigates to address (an absolute URL like "https://example.com", or a local file path). There is no separate mouse-hover hyperlink action, and no text-run-level hyperlink (a whole-shape hyperlink is the only granularity this tool surface exposes) — to make specific words within a text box clickable, put that text in its own shape.

address is normalized by PowerPoint itself (e.g. "https://example.com" round-trips as "https://example.com/" with a trailing slash) — compare against the returned hyperlinkAddress rather than assuming an exact byte-for-byte match of what you passed in.

shape(action: "set-hyperlink", session_id: ..., slide_index: ..., shape_index: ...,
  address: "https://example.com", screen_tip: "Visit our site")
shape(action: "get-hyperlink", session_id: ..., slide_index: ..., shape_index: ...)
  → hasHyperlink: true, hyperlinkAddress: "https://example.com/", hyperlinkScreenTip: "Visit our site"
shape(action: "remove-hyperlink", session_id: ..., slide_index: ..., shape_index: ...)
  → hasHyperlink: false

Dash Styles (dash_style for set-line)¶

Must match a real MsoLineDashStyle enum member name exactly: msoLineSolid, msoLineSquareDot, msoLineRoundDot, msoLineDash, msoLineDashDot, msoLineDashDotDot, msoLineLongDash, msoLineLongDashDot.

Z-Order Commands (z_order_command for set-z-order)¶

bring-to-front, send-to-back, bring-forward, send-backward. (PowerPoint's Word-only z-order members — bring/send relative to text — are intentionally not exposed here.)

Auto Shape Types¶

shape_type for add-auto-shape must match a real MsoAutoShapeType enum member name exactly (case-sensitive, mso-prefixed PascalCase) — this is a curated subset (not the full Office enum):

Passing an unrecognized string returns success: false — double-check spelling rather than guessing variants (e.g. star/callout shapes are not in this curated set).

For lines and connectors, connector_type (add-connector only) must be one of msoConnectorStraight, msoConnectorElbow, or msoConnectorCurve.

Shape Indexing Within a Slide¶

shape_index is 1-based and reflects the order shapes were added to that slide (and any built-in placeholders from the applied layout, if present). After adding several shapes, use shape(action: "get-count", ...) to confirm the current total before referencing an index you didn't just create yourself — don't assume index 1 is always the title.

shape(action: "add-text-box", session_id: ..., slide_index: 1, ..., text: "Title")   → shapeIndex 1 (assuming a blank slide)
shape(action: "add-rectangle", session_id: ..., slide_index: 1, ...)                  → shapeIndex 2
shape(action: "add-text-box", session_id: ..., slide_index: 1, ..., text: "Body")     → shapeIndex 3
shape(action: "get-count", session_id: ..., slide_index: 1) → 3                        → confirms the count before further edits

Building a Text Box + Table/Chart Combo Slide¶

Tables and charts are added by their own domain tools (table(action: "add-table", ...), chart(action: "add-chart", ...) — see tables.md and charts.md) but they are shapes on the slide like any other, and share the same shape_index numbering with rectangles and text boxes added on that slide. Track the returned shapeIndex from each add call (or re-check with shape(action: "get-count", ...)) so subsequent position/size/format calls target the right shape.

Repositioning and Resizing¶

Use shape(action: "set-position", ...) / shape(action: "set-size", ...) for targeted layout fixes instead of deleting and re-adding a shape:

CORRECT — nudge a shape that overlaps another after visual verification
shape(action: "set-position", session_id: ..., slide_index: ..., shape_index: ..., left: 500, top: 120)

AVOID — delete and recreate to move a shape
shape(action: "delete", session_id: ..., slide_index: ..., shape_index: ...)
shape(action: "add-rectangle", session_id: ..., slide_index: ..., left: 500, top: 120, width: ..., height: ...)

Deleting and recreating loses the shape's text content and any formatting already applied to it — prefer targeted set-position/set-size (see anti-patterns.md).