# v0.7.0+ Roadmap: Full-System PPTX Intelligence

## Vision

Make pptx-mcp the most capable AI-to-PowerPoint system — not just generation, but a complete create/edit/review/improve/brand pipeline with professional design intelligence built in. Close every meaningful python-pptx gap, add designer-grade polish, and make branding a first-class workflow.

---

## Current State (v0.6.0)

- 32 SlideTypes (24 original + 8 diagram types)
- 12 ChartTypes (5 original + 7 expanded)
- 29 MCP tools, 10 prompts, 2 resources
- 12 brand presets, 27 deck archetypes
- Element editing (list/modify/add/align/group)
- Spatial validation (overlap, bounds, spacing, text overflow)
- Review engine with 8 rule categories
- Plan cache workflow (plan → inspect → render)
- Parser round-trip for all 32 slide types
- 936 tests passing

---

## Phase 1: Brand System & Designer Polish (v0.7.0)

The highest-leverage changes — close the gap between "AI-generated" and "professionally designed."

### 1A. Brand Guide from Markdown

**New tool:** `parse_brand_guide` — accepts markdown brand guide, returns BrandConfig.

```markdown
# Acme Corp Brand Guide

## Colors
- Primary: #1B2A4A
- Secondary: #2D5F8A
- Accent: #E8913A
- Background: #FFFFFF
- Surface: #F8F9FA
- Text: #1A1A2E
- Border: #E0E0E0

## Typography
- Heading: Aptos, Bold
- Body: Aptos, Regular
- Title size: 36pt
- Body size: 16pt

## Shape Style
- Corner radius: 0.08
- Shadow: subtle
- Accent bar: on
- Edge bar: left

## Spacing
- Margins: 0.75"
- Element gap: 0.3"

## Header/Footer
- Slide numbers: yes
- Company: Acme Corp
```

**Implementation:** Extend `spec_parser.py` with `parse_brand_guide()` function. Also support YAML input (trivial with `yaml.safe_load` + Pydantic).

### 1B. Extended BrandConfig Model

New fields (all optional, backward-compatible):

| Model | New Fields | Purpose |
|-------|-----------|---------|
| `ColorPalette` | `surface`, `border`, `overlay`, `overlay_opacity` | Card backgrounds, dividers, image overlays |
| `FontConfig` | `display_font`, `display_size`, `font_weight_heading`, `font_weight_body`, `paragraph_spacing` | Full typography scale |
| `ShapeStyleConfig` | `shadow_preset` (none/subtle/medium/elevated), `edge_bar` (none/left/top), `edge_bar_width`, `divider_style` (none/thin_line/dotted), `line_dash_style` | Designer-grade shape styling |
| New `LogoConfig` | `path`, `placement`, `min_clear_space`, `max_height`, `skip_on` | Logo placement rules |
| `SpacingConfig` | `base_unit_pt` | Grid-aligned spacing system |

### 1C. Visual Brand Guide Overhaul

Replace text-bullet slides in `brand_guide.py` with visual specimens:
- Color swatches as filled rectangles (not text listing hex codes)
- Typography rendered at each tier (Display → Caption with actual font rendering)
- Spacing diagram with annotated margins and gutters
- Shape/card style showcase (with/without shadow, corner radius examples)
- Accent elements showcase (edge bars, dividers, accent bars)
- Do's and Don'ts examples

### 1D. Designer Edge Features in Renderers

| Feature | Description | Impact |
|---------|-------------|--------|
| Edge bars | Left or top color strip on content slides | High visual differentiation, ~20 lines |
| Divider lines | Thin horizontal separators between content sections | Professional segmentation |
| Shadow presets | Named presets instead of raw pt values | Prevents amateur shadow configs |
| Line dash styles | Dashed/dotted borders on shapes | Essential for consulting decks (proposed vs current) |
| Content-aware text fitting | `MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE` on text frames | Eliminates #1 spatial validation issue |

### 1E. Extract Brand from Existing Deck

**New tool:** `extract_brand` — analyze a .pptx file and derive a BrandConfig from its visual properties.

Aggregate: font family distribution, color frequency analysis, spacing patterns, shape styling → best-fit BrandConfig. Enables "match the style of this client deck."

**Estimated scope:** ~15 new/modified files, ~100 new tests

---

## Phase 2: Editing Power Tools (v0.7.1)

Close all editing workflow gaps. Make the AI efficient at bulk operations.

### 2A. New Editing Tools

| Tool | Description | Difficulty |
|------|-------------|------------|
| `find_and_replace` | Search/replace text across all slides | Low |
| `batch_modify` | Apply modification to shapes matching filter (type, name, text) across slide range | Low-Med |
| `delete_element` | Remove a shape from a slide | Low |
| `copy_element` | Copy element from one slide to another | Low-Med |
| `update_plan_slide` | Modify individual slide in cached plan before rendering | Low |
| `reorder_slides` | Batch reorder with new index list | Low |
| `ungroup_elements` | Inverse of group_elements | Low |
| `create_checkpoint` / `restore_checkpoint` | Undo via file backup | Med |

### 2B. Internal Slide Hyperlinks

`click_action.target_slide` — enables agenda navigation, TOC slides, appendix links. Model change: extend hyperlink to support `slide_index` target.

### 2C. Run-Level Hyperlinks

Wire up the existing `TextRun.hyperlink` field in the generator. Currently modeled but not rendered.

**Estimated scope:** ~8 new/modified files, ~60 new tests

---

## Phase 3: Chart & Shape Completeness (v0.8.0)

Surface all high-value python-pptx capabilities.

### 3A. Chart Enhancements

| Feature | python-pptx API | Priority |
|---------|-----------------|----------|
| Axis formatting | `value_axis.minimum_scale`, `major_unit`, `tick_labels.number_format`, `axis_title` | P0 |
| Data label customization | `data_labels.position`, `number_format`, `show_percentage`, `font` | P0 |
| Legend position | `legend.position` (RIGHT/TOP/LEFT/CORNER) | P1 |
| Chart style presets | `chart.chart_style = N` (1-48) | P1 |
| Line smoothing & markers | `series.smooth`, `marker.style`, `marker.size` | P1 |
| Additional chart types | STACKED_100, EXPLODED_PIE, STOCK_HLC, LINE (no markers), AREA_STACKED, XY_SCATTER_SMOOTH | P1 |
| Invert if negative | `bar_series.invert_if_negative` | P2 |

### 3B. Shape Expansion

Add ~30 high-value shapes in 4 categories:

| Category | Shapes | Use Case |
|----------|--------|----------|
| Flowchart | PROCESS, DECISION, TERMINATOR, DATA, DOCUMENT, CONNECTOR, PREDEFINED_PROCESS | Architecture/process diagrams |
| Arrows | LEFT_RIGHT, UP_DOWN, NOTCHED_RIGHT, CURVED_RIGHT, BENT | Flow direction |
| Annotation | LEFT_BRACE, RIGHT_BRACE, LEFT_BRACKET, RIGHT_BRACKET | Callout marks |
| Common | CROSS, CLOUD, DONUT, OCTAGON, TRAPEZOID, PARALLELOGRAM, CUBE, CAN, FUNNEL, STAR_5_POINT | General purpose |

### 3C. Table Enhancements

| Feature | API | Priority |
|---------|-----|----------|
| Cell margins | `cell.margin_left/right/top/bottom` | P0 |
| Vertical alignment | `cell.vertical_anchor` (TOP/MIDDLE/BOTTOM) | P0 |
| Banding properties | `table.first_row/col`, `horz_banding`, `vert_banding` | P1 |
| Cell merge | `cell.merge(other_cell)` | P2 |

### 3D. Additional Capabilities

| Feature | API | Priority |
|---------|-----|----------|
| Theme colors | `color.theme_color = MSO_THEME_COLOR.ACCENT_1` | P1 |
| Pattern fill | `fill.patterned()`, `fill.pattern` | P2 |
| Curved connectors | `MSO_CONNECTOR_TYPE.CURVE` | P2 |
| Shape-glued connectors | `connector.begin_connect(shape, idx)` | P2 |
| Core properties | `keywords`, `comments`, `content_status`, `language` | P2 |
| Freeform shapes | `build_freeform()` | P3 |
| Video embedding | `add_movie()` | P3 |
| Slide name | `slide.name` | P3 |

**Estimated scope:** ~12 modified files, ~120 new tests

---

## Phase 4: Review Intelligence (v0.8.1)

Activate the dead review categories and add designer intelligence.

### 4A. Activate Dead Review Categories

Currently `ACCESSIBILITY`, `BRAND`, `TYPOGRAPHY`, `COLOR` exist as enums but have zero implementing rules.

| Category | Rules to Add |
|----------|-------------|
| `ACCESSIBILITY` | Contrast ratio (WCAG AA: 4.5:1 for body, 3:1 for large text), alt text on images, reading order analysis, minimum font size (14pt) |
| `BRAND` | Font compliance (only brand-approved fonts), color compliance (only palette colors used), accent bar consistency, logo presence where required |
| `TYPOGRAPHY` | Font size hierarchy enforcement (title > heading > body > caption), max 2 font families per slide, `min_font_size` enforcement from LayoutRules, heading weight consistency |
| `COLOR` | Max distinct colors per slide (<=5), 60/30/10 ratio estimation, accent not used for large areas, consistent chart color usage |

### 4B. Designer Intelligence Rules

| Rule | Category | Description |
|------|----------|-------------|
| `check_whitespace_ratio` | `LAYOUT` | Title/quote/big_number > 50% whitespace, content > 30%, data-heavy > 20% |
| `check_visual_hierarchy` | `LAYOUT` | Most important element (title, big number, CTA) has largest visual weight |
| `check_visual_rhythm` | `NARRATIVE` | No more than 3 consecutive same-category slides |
| `check_spacing_grid` | `LAYOUT` | Spacing values approximate multiples of `base_unit_pt` |
| `check_shadow_border_conflict` | `CONSISTENCY` | Warn if both thick border AND shadow on same shape |

### 4C. Expanded Auto-Fix (IterationAgent)

Currently only 3 fix patterns. Add:
- Spatial issue auto-fix (reposition overlapping elements)
- Consistency auto-fix (normalize title casing)
- Typography auto-fix (enforce min font size)
- Color auto-fix (replace off-brand colors with nearest brand color)
- Bullet-to-visual promotion for: COMPARISON, PROCESS, TABLE, CARD_GRID patterns

**Estimated scope:** ~6 modified files, ~80 new tests

---

## Phase 5: Template System (v0.9.0)

Enable the `template_path` field that's been dead since v0.1.

### 5A. Template Import

Wire up `BrandConfig.template_path`:
- Read slide master and layouts from template .pptx
- Map layout placeholders to generator's rendering pipeline
- Populate placeholders instead of blank-slide positioning
- Fall back to current layout engine when placeholders don't match

### 5B. Layout Variant Generation

**New tool:** `generate_layout_variants` — for a given slide definition, produce 2-3 alternative SlideType renderings.

Example: "Show me this content as TWO_COLUMN vs ICON_GRID vs CARD_GRID" → returns 3 plan variants, user picks one.

### 5C. Reference Deck Style Transfer

Enhanced version of `extract_brand`: analyze not just colors/fonts but layout patterns, spacing rhythms, shape styling preferences from a reference deck. Apply as a complete visual style.

**Estimated scope:** ~10 new/modified files, ~60 new tests

---

## Priority Matrix

| Priority | Feature | Phase | Impact | Effort |
|----------|---------|-------|--------|--------|
| **P0** | Brand guide from markdown | 1A | High | Low |
| **P0** | Extended BrandConfig model | 1B | High | Low |
| **P0** | Content-aware text fitting | 1D | High | Low |
| **P0** | Edge bars + dividers | 1D | High | Low |
| **P0** | find_and_replace | 2A | High | Low |
| **P0** | batch_modify | 2A | High | Low-Med |
| **P0** | delete_element | 2A | Med | Low |
| **P0** | update_plan_slide | 2A | High | Low |
| **P0** | Chart axis formatting | 3A | High | Med |
| **P0** | Data label customization | 3A | High | Med |
| **P0** | Table cell margins/alignment | 3C | Med-High | Low |
| **P1** | Visual brand guide overhaul | 1C | Med-High | Med |
| **P1** | Extract brand from deck | 1E | Med-High | Med |
| **P1** | Shadow presets + dash styles | 1D | Med | Low |
| **P1** | Internal slide hyperlinks | 2B | High | Low-Med |
| **P1** | Accessibility review rules | 4A | High | Med |
| **P1** | Brand compliance rules | 4A | High | Med |
| **P1** | Typography/color rules | 4A | Med | Low-Med |
| **P1** | Flowchart shapes (7 types) | 3B | High | Low |
| **P1** | Legend position + chart styles | 3A | Med | Low |
| **P1** | Line smoothing + markers | 3A | Med | Low |
| **P1** | Additional chart types (6+) | 3A | Med | Med |
| **P2** | copy_element + reorder_slides | 2A | Med | Low |
| **P2** | Whitespace + visual hierarchy rules | 4B | Med | Med |
| **P2** | Expanded auto-fix handlers | 4C | Med-High | Med |
| **P2** | Theme colors | 3D | Med | Med |
| **P2** | Pattern fill | 3D | Med | Low |
| **P2** | Checkpoint/undo system | 2A | Med | Med |
| **P2** | Annotation shapes (braces/brackets) | 3B | Med | Low |
| **P2** | Common shapes (~12 types) | 3B | Med | Low |
| **P3** | Template import system | 5A | Med | High |
| **P3** | Layout variant generation | 5B | Med | Med |
| **P3** | Reference deck style transfer | 5C | Med | High |
| **P3** | Freeform shapes | 3D | Med | Med |
| **P3** | Video embedding | 3D | Low-Med | Med |

---

## Competitive Positioning

| Capability | Beautiful.ai | Gamma | Pitch | pptx-mcp (current) | pptx-mcp (target) |
|-----------|-------------|-------|-------|--------------------|--------------------|
| AI generation | Yes | Yes | Yes | Yes | Yes |
| Brand system | Brand kit | Custom themes | Brand kits | 12 presets | Markdown brand guides + extract from deck |
| Chart types | ~8 | ~6 | ~8 | 12 | 20+ |
| Diagram types | SmartArt-like | Basic | None | 8 | 8 |
| Element editing | GUI | GUI | GUI | MCP tools | Bulk + batch tools |
| Design review | None | None | None | 8-rule engine | 20+ rules with auto-fix |
| Accessibility | None | None | None | None | WCAG contrast + alt text |
| Template import | Yes | No | Yes | No | Yes (Phase 5) |
| Internal links | Yes | N/A | Yes | No | Yes (Phase 2) |
| Auto-layout | Constraint-based | Content-aware | Manual | Grid-computed | Text-fitting + grid |
| Output format | Web/PDF/PPTX | Web/PDF | Web/PDF/PPTX | .pptx native | .pptx native |

**Key differentiator:** pptx-mcp is the only tool that produces native .pptx with programmatic design review, AI-driven improvement, and MCP-based workflow integration. No other tool offers review intelligence or brand compliance checking.

---

## Estimated Test Counts

| Phase | New Tests | Cumulative |
|-------|-----------|------------|
| Current (v0.6.0) | — | 936 |
| Phase 1 (Brand + Designer) | ~100 | ~1,036 |
| Phase 2 (Editing) | ~60 | ~1,096 |
| Phase 3 (Charts + Shapes) | ~120 | ~1,216 |
| Phase 4 (Review Intel) | ~80 | ~1,296 |
| Phase 5 (Templates) | ~60 | ~1,356 |
