morph-ppt

# Morph Generate visually compelling PPTs with smooth Morph animations. **Philosophy**: Trust yourself to learn through practice. This skill provides workflow and references — you bring creativity and judgment. --- ## Use when - User wants to generate a `.pptx` --- ## What is Morph? PowerPoint's Morph transition creates smooth animations by matching shapes with **identical names** across adjacent slides. ``` Slide 1: shape name="!!circle" x=5cm width=8cm Slide 2: shape name="!!circle" x=20cm width=12cm ↓ Result: Circle smoothly moves and grows ``` **Three core concepts:** - **Scene Actors**: Persistent shapes with `!!` prefix that evolve across slides - **Ghosting**: Move shapes to `x=36cm` (off-screen) instead of deleting - **Content**: Text/data added fresh per slide, previous content ghosted first For details: `reference/pptx-design.md` --- ## Workflow ### Phase 1: Understand the Topic Ask only when topic is unclear, otherwise proceed directly. --- > **⚠️ CRITICAL KNOWN ISSUE: Name-based path selectors break after `transition=morph` is set** > After calling `officecli set '/slide[N]' --prop transition=morph`, paths like `/slide[N]/!!my-shape` return 'Element not found'. The CLI auto-prepends `!!` to shape names when morph is applied, which invalidates name-based lookups. > > **Workaround:** Always use shape INDEX paths instead of name paths when accessing shapes on morph slides: > > ```bash > # WRONG (after transition=morph set): > officecli get deck.pptx '/slide[3]/!!my-circle' --depth 1 > > # CORRECT: > officecli get deck.pptx '/slide[3]' --depth 1 # first list all shapes to find index > officecli get deck.pptx '/slide[3]/shape[2]' --depth 1 > ``` > > The build.py template should use `inspect()` + index-based access throughout. --- ### Phase 2: Plan the Story **FIRST: Read the thinking framework** → Open and read `reference/decision-rules.md` — it provides the structured approach for planning compelling presentations (Pyramid Principle, SCQA, page types). **Then create `brief.md`** with: - **Context**: Topic, audience, purpose, narrative structure (SCQA or Problem-Solution) - **Outline**: Conclusion first + slide-by-slide summary - **Page briefs**: For each slide: - Objective (what should this slide achieve?) - Content (specific text/data to include) - Page type (title | evidence | transition | conclusion) - Design notes (visual emphasis, scene actor behavior) **Morph Pair Scene Planning (REQUIRED before building)** For every morph transition, plan the slide pair BEFORE writing any code. Use a table like this in `brief.md`: | Pair | Slide A (start) | Slide B (end) | Visual narrative purpose | | ---- | ------------------------------------------- | ------------------------------------ | ------------------------ | | 1→2 | Ring centered, title appears | Ring shifts right, subtitle revealed | Attention → context | | 2→3 | Feature box large | Feature box small, metric card grows | Zoom out → detail | | 3→4 | Metric card exits (ghost), new actor enters | Actor repositions | Section transition | **Rules for the planning table:** - Determine ALL `!!` shape names during planning — the same name must be used identically across the slide pair - For each `!!` shape, decide its role: `!!scene-{desc}` (background/decoration) or `!!actor-{desc}` (content/foreground) - Mark which shapes need to be ghosted at each section transition - Do NOT start building until the naming table is complete — renaming shapes mid-build causes ghost accumulation bugs --- ### Phase 3: Design and Generate **Before generation starts, always remind the user:** - The PPT file may be rewritten multiple times during build. - Once the PPT file appears in the workspace, the user can preview the live generation progress directly in AionUi. - Do **not** click "Open with system app" during generation, to avoid file lock / write conflicts. - Use clear, direct language and make this a concrete warning, not an optional suggestion. **FIRST: Ensure latest officecli version** Follow the installation check in `reference/officecli-pptx-min.md` section 0 (checks version and upgrades only if needed). **IMPORTANT: Use morph-helpers for reliable workflow** Generate a Python script that uses `reference/morph-helpers.py` — this provides helper functions with built-in verification. Python works cross-platform (Mac / Windows / Linux). **Shape naming rules (for best results)**: Use these naming patterns for clear code and reliable verification: **Namespace prefixes for `!!` shapes — prevent scene collision:** All persistent `!!` shapes MUST use one of these two prefixes to avoid morph engine confusion when multiple morph pairs share similar shape names: - `!!scene-{desc}` — Background / decoration shapes (e.g., `!!scene-ring`, `!!scene-bg-gradient`, `!!scene-grid-line`) - These persist across the entire deck; move them for motion but rarely ghost them - `!!actor-{desc}` — Content / foreground shapes (e.g., `!!actor-feature-box`, `!!actor-metric`, `!!actor-label`) - These carry slide-specific content; ghost them at section boundaries **Rule: `!!scene-*` and `!!actor-*` names must NEVER be identical.** Bad: `!!scene-card` and `!!actor-card` in the same deck — morph engine will confuse them. Good: `!!scene-card-bg` and `!!actor-card-content` — unambiguous. 1. **Scene actors** (persistent across slides): - Format: `name=!!scene-{desc}` or `name=!!actor-{desc}` - Examples: `name=!!scene-ring`, `name=!!scene-dot`, `name=!!actor-feature-box` - Behavior: Modify position/size/color across slides — do NOT delete - **Exit strategy — two trigger scenarios**: 1. **Permanent exit** (shape no longer needed): Move it off-screen to `x=36cm`. Morph will smoothly slide it out of view. Example: `officecli set deck.pptx '/slide[N]/!!FeatureBox' --prop x=36cm --prop y=14cm` To bring it back on a later slide, simply move it back to a visible position. 2. **Scene transition exit** (entering a new topic section): When the presentation moves into a new thematic section, ALL `!!` content shapes from the previous section must also be ghosted to `x=36cm`. Only decoration actors that persist throughout the entire deck (e.g., a background ring) should remain visible. ```bash # Entering new section: ghost all previous section's !! content shapes # First, check what !! shapes are on the current slide officecli get deck.pptx '/slide[N]' --depth 1 # Then ghost each one officecli set deck.pptx '/slide[N]/!!FeatureBox' --prop x=36cm officecli set deck.pptx '/slide[N]/!!MetricCard' --prop x=36cm officecli set deck.pptx '/slide[N]/!!ChannelLabel' --prop x=36cm ``` **Rule**: Each new section's first slide should be clean — only current-section actors visible; no leftover shapes from the previous section. 2. **Content shapes** (unique per slide): - Format: `name=#sN-description` - Pattern: `#` + `s` + slide_number + `-` + description - Examples: `name=#s1-title`, `name=#s2-card1`, `name=#s3-stats` - Behavior: Ghost (x=36cm) when moving to next slide **Ghost accumulation — critical behavior to understand:** > Once a `!!`-prefixed shape appears on any slide, it persists and remains visible on **every subsequent morph slide** unless explicitly moved off-screen. This means: - A `!!actor-feature-box` introduced on slide 3 will still be visible on slides 4, 5, 6, 7 ... unless you ghost it - Ghost accumulation builds silently — visual clutter compounds across the deck - The `morph_final_check` tool does NOT catch `!!` shapes that linger in the visible area; only screenshot verification can detect this **Ghost cleanup pattern** — when a `!!actor-*` shape is no longer needed, exit it explicitly: ```bash # Pattern: after the last slide where !!actor-feature-box is needed, # on the NEXT slide's setup, move it off-screen BEFORE adding new content officecli set deck.pptx '/slide[N]/shape[X]' --prop x=36cm --prop y=10cm # If the shape served a 2-slide story arc (slides 3→4), ghost it on slide 5: helper("ghost", OUTPUT, 5, <shape_index_of_actor_feature_box>) ``` **Rule**: For every `!!actor-*` shape, its "ghost slide" (where it exits) must be planned in the Phase 2 morph pair table. Do not leave any `!!actor-*` shape without a planned exit. **Why this naming matters:** - ✅ **Better detection**: Primary method (`#sN-` pattern matching) is fastest and most accurate - ✅ **Readable code**: Anyone can tell `#s1-title` is slide 1's title - ✅ **Easy debugging**: `grep "#s1-"` finds all slide 1 content quickly - ⚠️ **Backup detection exists**: Even without `#` prefix, duplicate text detection will catch most issues (but has edge cases) **Bottom line**: Follow these patterns in your code examples, and verification will work smoothly. **Then proceed with pattern**: ```python #!/usr/bin/env python3 import subprocess, sys, os def run(*args): result = subprocess.run(list(args)) if result.returncode != 0: sys.exit(result.returncode) # Load helper functions (provides morph_clone_slide, morph_ghost_content, morph_verify_slide) SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__)) def helper(*args): run(sys.executable, os.path.join(SCRIPT_DIR, "reference", "morph-helpers.py"), *[str(a) for a in args]) OUTPUT = "deck.pptx" run("officecli", "create", OUTPUT) run("officecli", "open", OUTPUT) # Resident mode — all commands run in memory # ============ SLIDE 1 ============ print("Building Slide 1...") run("officecli", "add", OUTPUT, "/", "--type", "slide") run("officecli", "set", OUTPUT, "/slide[1]", "--prop", "background=1A1A2E") # Scene actors (!!scene-* prefix = decoration, persists entire deck) run("officecli", "add", OUTPUT, "/slide[1]", "--type", "shape", "--prop", "name=!!scene-ring", "--prop", "preset=ellipse", "--prop", "fill=E94560", "--prop", "opacity=0.3", "--prop", "x=5cm", "--prop", "y=3cm", "--prop", "width=8cm", "--prop", "height=8cm") run("officecli", "add", OUTPUT, "/slide[1]", "--type", "shape", "--prop", "name=!!scene-dot", "--prop", "preset=ellipse", "--prop", "fill=0F3460", "--prop", "x=28cm", "--prop", "y=15cm", "--prop", "width=1cm", "--prop", "height=1cm") # Content shapes (#s1- prefix, will be ghosted on next slide) # Use generous width (25-30cm for titles) to avoid text wrapping! run("officecli", "add", OUTPUT, "/slide[1]", "--type", "shape", "--prop", "name=#s1-title", "--prop", "text=Main Title", "--prop", "font=Arial Black", "--prop", "size=64", "--prop", "bold=true", "--prop", "color=FFFFFF", "--prop", "x=10cm", "--prop", "y=8cm", "--prop", "width=28cm", "--prop", "height=3cm", "--prop", "fill=none") # ============ SLIDE 2 ============ print("Building Slide 2...") # Use helper: automatically clone + set transition + list shapes + verify helper("clone", OUTPUT, 1, 2) # Use helper: ghost all content from slide 1 (shape index 3 = #s1-title) helper("ghost", OUTPUT, 2, 3) # Add new content for slide 2 run("officecli", "add", OUTPUT, "/slide[2]", "--type", "shape", "--prop", "name=#s2-title", "--prop", "text=Second Slide",