Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(pptx): add AI illustration sheet → slice spot-illustration pipeline

hugohe3f1bcbc83dde4
diff --git a/AGENTS.md b/AGENTS.md
index 3bbd08c9..4a695260 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,6 +82,8 @@ python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/
python3 skills/ppt-master/scripts/image_gen.py --render-md <project_path>/images/image_prompts.json
# Out-of-pipeline one-off / debug / single-image fixup only (no manifest, no sidecar):
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
+# Spot illustrations — slice one AI grid sheet into individual elements (see image-generator.md §4.3):
+python3 skills/ppt-master/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names a,b,c --trim --alpha
python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemon
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animation
diff --git a/CLAUDE.md b/CLAUDE.md
index 0427192d..a5837ae7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -84,6 +84,8 @@ python3 skills/ppt-master/scripts/image_gen.py --manifest <project_path>/images/
python3 skills/ppt-master/scripts/image_gen.py --render-md <project_path>/images/image_prompts.json
# Out-of-pipeline one-off / debug / single-image fixup only (no manifest, no sidecar):
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
+# Spot illustrations — slice one AI grid sheet into individual elements (see image-generator.md §4.3):
+python3 skills/ppt-master/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names a,b,c --trim --alpha
python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemon
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animation
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index d47de051..88ff55d6 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -56,6 +56,7 @@ description: >
| `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis |
| `${SKILL_DIR}/scripts/latex_render.py` | LaTeX formula rendering (manifest-driven PNG assets) |
| `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) |
+| `${SKILL_DIR}/scripts/slice_images.py` | Slice one AI illustration sheet into individual spot-illustration elements |
| `${SKILL_DIR}/scripts/svg_quality_checker.py` | SVG quality check |
| `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting |
| `${SKILL_DIR}/scripts/finalize_svg.py` | SVG post-processing (unified entry) |
@@ -335,7 +336,7 @@ Read references/strategist.md
| Tier | Confirms | Driven by |
|---|---|---|
| **1 — anchors** | canvas · audience + core message + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases)* (all §c key info) · `mode` + `visual_style` | the source + user intent |
-| **2 — realization** (re-derived from Tier 1) | page count · color · typography (font + size) · icons · formula policy · image usage + strategy · generation mode · refine-spec toggle | the confirmed Tier 1 |
+| **2 — realization** (re-derived from Tier 1) | page count · color · typography (font + size) · icons · formula policy · image usage + illustration usage + strategy · generation mode · refine-spec toggle | the confirmed Tier 1 |
> **Why two tiers.** Every realization field is anchored by the same few choices (`visual_style` anchors color / icon / typography / image; `delivery_purpose` sets the body size, page density, **and** the page-count recommendation). Confirming anchors first, then re-deriving, means Tier 2's candidates fit the user's *real* anchors instead of your originals — the coherence reconciliation below is done by construction on this path. Page count is a **derived** field (content volume × `delivery_purpose`), which is why it lives in Tier 2, not up front.
@@ -349,7 +350,7 @@ Steps:
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --daemon --wait
```
Page opens at `http://localhost:5050` — the **same port as the Step 6 live preview** (they never run at once: this page shuts down at the end of Step 4). If 5050 is held, the launcher **auto-advances** (5051, …) — read the actual URL from the launch log and report it. The page does **not** close after Tier 1: it shows a "deriving…" state and polls for Tier 2. **Launch or wait failure is non-fatal**: if it fails or times out (flask missing, port blocked, no GUI / remote / web host), do **NOT** troubleshoot — **on any non-zero exit, re-check `result.json` once** (a fresh `status: tier1-confirmed`) before dropping to the chat fallback. **On success (exit 0 with a tier-1 result), do not pause or report — go straight to step 3 in the same turn.**
-3. **Re-derive Tier 2 from the confirmed anchors, then write it — immediately, same turn (the page is polling for it).** Read the tier-1 `result.json` (`status: tier1-confirmed`). Using the user's **actual** confirmed anchors (not your originals), author the realization candidates and **overwrite** `recommendations.json` with `"tier": 2`: page count (content volume × `delivery_purpose`); color, typography, and generated-image style as **generative ≥3-candidate** fields (creative recommendations always offer real choice — same rule as h.5; fewer than 3 only on the honest-shortfall exception, with a stated reason; color: core `palette` with background/secondary_bg/primary/accent/secondary_accent/body_text; typography: CJK + Latin for `heading` and `body` with `css` preview stacks + `body_size` as the body baseline in **px** (every canvas) — **one fixed value per confirmed `delivery_purpose`** (`text` 20 / `balanced` 24 / `presentation` 32), not a range; images: `image_strategy.candidates` rendering × palette from h.5); enumerable `icons` / `formula_policy` / `generation_mode` (recommended `id`); `image_usage` (`ai` / `web` / `provided` / `placeholder` / `none`, or a custom prose plan when several sources mix — never bare `"custom"`; write `image_ai_path` only when the plan includes AI). The still-open page polls, renders Tier 2, and preserves the user's Tier 1 picks. Closed fields (`image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec`) stay finite; open fields (`icons`, `image_usage`, typography custom text) show a Custom box.
+3. **Re-derive Tier 2 from the confirmed anchors, then write it — immediately, same turn (the page is polling for it).** Read the tier-1 `result.json` (`status: tier1-confirmed`). Using the user's **actual** confirmed anchors (not your originals), author the realization candidates and **overwrite** `recommendations.json` with `"tier": 2`: page count (content volume × `delivery_purpose`); color, typography, and generated-image style as **generative ≥3-candidate** fields (creative recommendations always offer real choice — same rule as h.5; fewer than 3 only on the honest-shortfall exception, with a stated reason; color: core `palette` with background/secondary_bg/primary/accent/secondary_accent/body_text; typography: CJK + Latin for `heading` and `body` with `css` preview stacks + `body_size` as the body baseline in **px** (every canvas) — **one fixed value per confirmed `delivery_purpose`** (`text` 20 / `balanced` 24 / `presentation` 32), not a range; images: `image_strategy.candidates` rendering × palette from h.5); enumerable `icons` / `formula_policy` / `generation_mode` (recommended `id`); `image_usage` (`ai` / `web` / `provided` / `placeholder` / `none`, or a custom prose plan when several sources mix — never bare `"custom"`; write `image_ai_path` only when the plan includes AI); `illustration_usage` (closed toggle — `none` or `use`). The still-open page polls, renders Tier 2, and preserves the user's Tier 1 picks. Closed fields (`illustration_usage`, `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec`) stay finite; open fields (`icons`, `image_usage`, typography custom text) show a Custom box.
4. **Wait for the final confirmation** — attach to the already-running page, do **not** relaunch (same 600000 ms budget):
```bash
python3 ${SKILL_DIR}/scripts/confirm_ui/server.py <project_path> --wait-only
@@ -375,6 +376,15 @@ Steps:
When the confirmed `image_usage` is not `ai` (and the plan has no AI part), do **NOT** run h.5, do **NOT** write `ai` rows, and do **NOT** generate images in Step 5 — regardless of what you recommended. The same "confirmed value wins" rule applies to every field (color → §III, typography → §IV, etc.).
+**Illustration usage is a binary intent toggle, not a second source enum.** The confirmed illustration usage (`result.json.illustration_usage`, or its chat-reply equivalent — chat is the canonical channel) tells Strategist only *whether* illustrations should be part of the deck's visual language:
+
+| `result.json.illustration_usage` | Strategist behavior |
+|---|---|
+| `none` (default) | Do not intentionally add decorative illustrations; still preserve required source images |
+| `use` | Make illustrations part of the deck; **how heavily** (sparse spots vs a recurring visual language) is the Strategist's judgment from content + `visual_style` |
+
+**Intensity and source are decided downstream, not by this toggle.** Source always comes from `image_usage` (which maps to §VIII `Acquire Via`): `image_usage: none` always wins — write no decorative illustration rows even if `illustration_usage` is `use`. Otherwise, when `use` is set: an AI source may use the `ai` Illustration Sheet + `slice` workflow for ≥3 same-family spot illustrations; `provided` makes them `Type: Illustration` + `Acquire Via: user` rows; `web` makes them `web` rows only if licensing is acceptable; a deferred/copyright-sensitive plan makes them `placeholder` rows. The user never has to choose or see the internal sheet/slice implementation.
+
**Upstream override → re-derive untouched downstream (Mandatory — chat-fallback / single-pass path).** On the **two-tier page path this is already handled** (Step 3 re-derives Tier 2 from the user's actual anchors). It still applies whenever anchors and realization are confirmed **together** — the two-step chat fallback collapsed into one bundle, or a legacy single-pass `result.json`. "Confirmed value wins" governs each field's *own* value — never recompute a value the user set (a size, canvas, or palette they edited stays verbatim). But a single-pass `result.json` can carry a changed **anchor** beside downstream fields still holding your original — now incoherent — recommendation (e.g. switched to `dark-tech` while the light palette you proposed is untouched). Before writing the spec, reconcile: when the user changed an anchor, re-derive the downstream fields the user did **not** themselves edit so they realize the new anchor; fields the user pinned stay as confirmed.
| Anchor the user changed | Re-derive (only the downstream fields the user left at your recommendation) |
@@ -453,7 +463,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
🚧 **GATE**: Step 4 complete; Design Specification & Content Outline generated and user confirmed. Any formula rows already have `Acquire Via: formula` and `Status: Rendered`.
-> **Trigger**: At least one row in the resource list has `Acquire Via: ai` and/or `Acquire Via: web`. If every row is `user`, `formula`, or `placeholder`, skip to Step 6.
+> **Trigger**: At least one row in the resource list has `Acquire Via: ai`, `web`, and/or `slice`. If every row is `user`, `formula`, or `placeholder`, skip to Step 6.
**Always load the common framework**:
@@ -467,7 +477,8 @@ Then **lazy-load the path-specific reference** for each row that actually needs
|---|---|---|
| `ai` | `references/image-generator.md` | `python3 ${SKILL_DIR}/scripts/image_gen.py --manifest <project_path>/images/image_prompts.json` |
| `web` | `references/image-searcher.md` | `python3 ${SKILL_DIR}/scripts/image_search.py ...` (≥2 web rows → `--batch images/image_queries.json`) |
-| `user` / `placeholder` | (skip) | (skip) |
+| `slice` | `references/image-generator.md` §4.3 | derived — **after** the parent `ai` sheet row is `Generated`, run `python3 ${SKILL_DIR}/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names ... --trim --alpha` (see workflow step 2.5) |
+| `user` / `formula` / `placeholder` | (skip) | (skip) |
A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `web` rows never loads `image-generator.md`. A mixed deck loads both, processes each row through its own path, and writes both `image_prompts.json` and `image_sources.json`.
@@ -475,14 +486,17 @@ A deck with only `ai` rows never loads `image-searcher.md`; a deck with only `we
> ⚠️ **web path — batch multiple rows**: when ≥2 rows are `Acquire Via: web`, write all queries into `images/image_queries.json` and run `image_search.py --batch` once (concurrent acquisition, status written back), instead of one CLI call per row. A single web row may use the positional single-query form. See [image-searcher.md](references/image-searcher.md) §5.
+> 💡 **ai path — spot illustrations as one sheet**: when ≥3 same-family spot illustrations are wanted as decorative accessories, generate **one grid sheet** (a single `ai` sheet row) instead of one row per element, then slice it (workflow step 2.5 below). The sheet row is generated but not placed; each cut **element row** (`Acquire Via: slice`) is placed and must appear in `spec_lock.md images`. One generation = one coherent style across all pieces. Resource contract + the three constraints: [image-generator.md](references/image-generator.md) §4.3.
+
> ⚠️ **Honor the confirmed image source**: the `ai` generation path (Path A = `image_gen.py` API / Path B = host-native tool / Offline Manual) is **not** auto-only — a confirmed choice other than `auto` wins, whether it came from chat (canonical) or, when the page was used, `result.json.image_ai_path`. `host-native` forces Path B even when `IMAGE_BACKEND` is configured; `api` forces Path A; `manual` forces offline. The `--manifest` command above is Path A. Full selection rule: [image-generator.md](references/image-generator.md) §7 Path Selection.
Workflow:
-1. Extract all rows with `Status: Pending` and `Acquire Via ∈ {ai, web}` from the design spec
-2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](references/image-base.md) §2 dispatch table
-3. Verify every row reaches a terminal status: `Generated` (ai success), `Sourced` (web success), or `Needs-Manual`
-4. Re-derive image facts now that web / AI files are in the folder — `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` — so `analysis/image_analysis.csv` reflects every acquired image (real measured sizes) before the Executor lays them out. Image facts are regenerated on use, never a stale store (see Step 4's image-facts note).
+1. Extract all resource rows from the design spec and group them by `Acquire Via`; rows with `Status: Pending` and `Acquire Via ∈ {ai, web, slice}` must all reach a terminal state before Executor starts
+2. Generate prompts (ai rows) and/or run search (web rows) per [image-base.md](references/image-base.md) §3 dispatch table
+2.5. **Slice any spot-illustration sheets (only if `slice` rows exist).** For each generated `ai` **sheet** row, run `slice_images.py` (grid + the element `--names` matching the `slice` rows, `--trim --alpha`) so every element file lands in `images/`; mark each `slice` row `Generated`. A sheet still in `Needs-Manual` cannot be sliced — leave its `slice` rows `Needs-Manual` and surface them at the Step 7 readiness gate. Contract: [image-generator.md](references/image-generator.md) §4.3.
+3. Verify every row reaches a terminal status: `Generated` (ai success / sliced element), `Sourced` (web success), or `Needs-Manual`
+4. Re-derive image facts now that web / AI / sliced files are in the folder — `python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images` — so `analysis/image_analysis.csv` reflects every acquired image **including the sliced elements** (real measured sizes) before the Executor lays them out. Image facts are regenerated on use, never a stale store (see Step 4's image-facts note).
**✅ Checkpoint — Confirm acquisition attempted for every row**:
```markdown
@@ -490,8 +504,9 @@ Workflow:
- [x] image_prompts.json created (when any ai rows processed)
- [x] image_prompts.md sidecar rendered (when any ai rows processed)
- [x] image_sources.json created (when any web rows processed)
+- [x] Spot-illustration sheets sliced (when any `slice` rows exist); every element file present in `images/` and listed in `spec_lock.md images`
- [x] Each row: status is `Generated` / `Sourced` / `Needs-Manual` (no `Pending` remaining)
-- [x] analyze_images.py re-run so image_analysis.csv covers the acquired web / AI images
+- [x] analyze_images.py re-run so image_analysis.csv covers the acquired web / AI / sliced images
```
**Default — auto-proceed to Step 6.** Only when the user's Step 4 response explicitly opted into split mode (in chat or via Confirm UI `result.json` with `generation_mode: "split"`), output the Phase A hand-off below and stop this conversation:
@@ -577,6 +592,8 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
> If files are missing: PAUSE, list the missing filenames, point the user to `images/image_prompts.md` (each `### Image N:` block is paste-ready for ChatGPT / Gemini / Midjourney; auto-generated from `image_prompts.json`) and the required placement `project/images/<filename>`. Resume Step 7.1 only after all expected files are in place. `finalize_svg.py` and `svg_to_pptx.py` do not detect missing files at this layer — proceeding with gaps produces a deck with broken image references.
+> **Spot-illustration sheets at this gate**: `slice` element files are **derived**, not placed by the user. If a sheet was `Needs-Manual` (offline), the element files do not exist yet — list the **sheet** filename (`images/<sheet>.png`) plus its element target names, and instruct: place the sheet, then run the Step 5 `slice_images.py` command for it, then re-run `analyze_images.py`, before resuming 7.1. Never tell the user to hand-place the individual element files — they only come from slicing the sheet.
+
> ⚠️ Run the three sub-steps **one at a time** — each must complete successfully before the next.
> ❌ **NEVER** combine them into a single code block or shell invocation.
diff --git a/skills/ppt-master/references/image-base.md b/skills/ppt-master/references/image-base.md
index 7ee574f8..e640efc6 100644
--- a/skills/ppt-master/references/image-base.md
+++ b/skills/ppt-master/references/image-base.md
@@ -8,7 +8,7 @@ Shared baseline for both acquisition paths. Path-specific behavior lives in the
## 1. Trigger Condition
-Active when at least one resource list row has `Acquire Via: ai` or `Acquire Via: web`. Rows with `user` / `formula` / `placeholder` are skipped.
+Active when at least one resource list row has `Acquire Via: ai` / `web` / `slice`. Rows with `user` / `formula` / `placeholder` are skipped.
| Mode | Trigger |
|---|---|
@@ -26,6 +26,7 @@ Defined in `design_spec.md §VIII`. Status enum: see [`svg-image-embedding.md`](
| cover.png | 1280x720 | Cover background | Background | `ai` | Pending | Modern tech abstract, deep blue gradient #0A2540 |
| team.jpg | 800x600 | Team photo | Photography | `web` | Pending | Diverse engineering team in modern office |
| formula_001.png | 736x168 | Block equation on P03 | Latex Formula | `formula` | Rendered | `E = mc^2` |
+| spot_team.png | TBD after slicing | Team spot illustration | Illustration | `slice` | Pending | From `spot_sheet.png` cell 1,1 |
**Required per non-skipped row**: `Acquire Via`, `Status`, `Reference`.
@@ -39,6 +40,7 @@ For each row with `Status: Pending`:
|---|---|---|---|
| `ai` | [`image-generator.md`](./image-generator.md) | `image_gen.py` | `Generated` |
| `web` | [`image-searcher.md`](./image-searcher.md) | `image_search.py` | `Sourced` |
+| `slice` | [`image-generator.md`](./image-generator.md) §4.3 | `slice_images.py` after parent AI sheet is `Generated` | `Generated` |
| `user` | — | — | (already `Existing`) |
| `formula` | — | — | (already `Rendered`) |
| `placeholder` | — | — | (already `Placeholder`) |
@@ -62,6 +64,7 @@ Before processing any row:
After all rows reach terminal status:
- Every non-skipped row has a file at `project/images/<filename>`, or is marked `Needs-Manual`
+- Every `slice` row has a generated element file, or is marked `Needs-Manual` because its parent sheet is not available
- No `Pending` rows remain
- `image_prompts.json` exists when ≥1 ai row processed; every entry has `status ∈ {Generated, Failed, Needs-Manual}` (no `Pending` remaining)
- `image_sources.json` exists when ≥1 web row processed; every entry has `license_tier ∈ {no-attribution, attribution-required}`
@@ -77,7 +80,7 @@ After all rows reach terminal status:
1. Try once
2. On recoverable failure (network, no candidates, license rejection, rate limit), retry once with broadened parameters
3. On second failure, set `Status: Needs-Manual`, log the reason in conversation, continue
-4. After the phase completes, summarize all `Needs-Manual` rows for the user — list filenames, where prompts live (`images/image_prompts.md` paste-ready blocks for ai rows; refresh via `image_gen.py --render-md` if stale), and where to place generated files (`project/images/<filename>`)
+4. After the phase completes, summarize all `Needs-Manual` rows for the user — list filenames, where prompts live (`images/image_prompts.md` paste-ready blocks for ai rows; refresh via `image_gen.py --render-md` if stale), and where to place generated files (`project/images/<filename>`). For `slice` rows, list the parent sheet filename and target element names; the user places the sheet, then the agent reruns `slice_images.py`.
`Needs-Manual` is also the entry status for **Offline Manual Mode** (no `IMAGE_BACKEND` configured, no host-native image tool in use). Affected ai rows are marked `Needs-Manual` from the start without a failed attempt — see [`image-generator.md`](./image-generator.md) §3.2.
@@ -120,7 +123,7 @@ Executor consumes the resource list plus:
| Image files | `project/images/*.{jpg,png,webp}` | `<image>` references |
| Manifest | `project/images/image_sources.json` | `license_tier` per Sourced image |
-Executor does NOT invoke `image_gen.py` / `image_search.py`.
+Executor does NOT invoke `image_gen.py` / `image_search.py` / `slice_images.py`.
---
@@ -128,8 +131,8 @@ Executor does NOT invoke `image_gen.py` / `image_search.py`.
```markdown
## ✅ Image Acquisition Phase Complete
-- [x] {N} rows processed (`ai`: {a} / `web`: {b})
-- [x] {a} `Generated`, {b} `Sourced`, {c} `Needs-Manual`
+- [x] {N} rows processed (`ai`: {a} / `web`: {b} / `slice`: {s})
+- [x] {a} `Generated`, {b} `Sourced`, {s} sliced `Generated`, {c} `Needs-Manual`
- [x] image_prompts.json / image_sources.json written
- [ ] **Next**: Auto-proceed to Executor phase
```
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index 798bca29..c031d55d 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -2,9 +2,9 @@
# Image_Generator Reference Manual
-Role definition for the **AI image generation path**: convert each `Acquire Via: ai` row into an optimized prompt, generate the image, and save it to `project/images/`.
+Role definition for the **AI image generation path**: convert each `Acquire Via: ai` row into an optimized prompt, generate the image, and save it to `project/images/`; also defines the `slice` derivation path for AI-generated illustration sheets.
-**Trigger**: resource list rows with `Acquire Via: ai`. The role is loaded only when at least one such row exists.
+**Trigger**: resource list rows with `Acquire Via: ai` or `slice`. The role is loaded only when at least one such row exists.
---
@@ -240,6 +240,36 @@ Example opening for a triptych hero:
**When uncertain about field conventions**: read `sources/` before drafting the prompt.
+### 4.3 Illustration sheets — one generation, many spot elements
+
+When a deck wants several small **spot illustrations** scattered as decorative accessories across pages (the illustration counterpart to icons), do **not** generate them one image per slot — that multiplies generation cost and lets the style drift between calls. Generate **one sheet** that lays out all the elements in a grid, then slice it. One call buys a set of elements with an identical style, palette, and line quality — the same cross-page consistency the deck-wide `deck_rendering` / `deck_palette` lock exists to protect.
+
+**When to use**: ≥3 spot illustrations of the same family needed across the deck. For a single hero/local image, stay with the normal one-row-per-image flow (§4.1). Plan sheets sparingly — only where decorative illustration genuinely lifts the page; an unused element costs nothing, but a deck papered in decoration reads cheap.
+
+**Sheet prompt convention** (one manifest item, `page_role: local`, `text_policy: none`, `image_size` chosen from final placement size):
+
+- Lay the elements out in an explicit **R×C grid, evenly spaced with clear gutters**, each element **centered in its own cell** and isolated (no element bleeds into a neighbor).
+- One **flat single-color background** across the whole sheet, set to the deck's background/secondary HEX — this is what lets the slicer key it out cleanly and lets the cut element sit on the slide without a visible box.
+- Shared `deck_rendering` + `deck_palette` as always. NO text, labels, or numbers anywhere (§5.1, §5.3).
+
+**Resource contract — the sheet and its elements are different row kinds.** A sliced element can only be placed if it exists as a resource the Executor is allowed to reference (`spec_lock.md images`). So §VIII carries two row kinds (full rules: [`design_spec_reference.md`](../templates/design_spec_reference.md) §VIII):
+
+- **Sheet row** — `Acquire Via: ai`, `Type: Illustration Sheet`, the grid prompt, named the slice source (`Reference: 2x3 spot sheet`). It is generated in Step 5 but **never placed on a slide** — keep it **out of** `spec_lock.md images`.
+- **Element rows** — one per cell, `Acquire Via: slice`, filename matching a `--names` output, `Reference` naming the parent sheet + cell. These **are** placed — list every one in `spec_lock.md images`, usually with ` | no-crop` (a tight-trimmed transparent spot should be fit, not cover-cropped). Their dimensions are filled in after slicing (Step 5 re-runs `analyze_images.py`).
+
+**Slice** with [`slice_images.py`](../scripts/slice_images.py) — cells are cut row-major into individual files in `images/`, after which the element rows are ordinary images the Executor places like any other (§6 references, Step 7 embed). Recommended flags: `--names` (semantic per-cell filenames matching the element rows; the count **must** equal `rows*cols`), `--trim` (tight-crop each cell so imprecise placement inside a cell doesn't leave lopsided margins), `--alpha` (knock the flat background out to transparency so an element drops onto any slide color):
+
+```bash
+python3 scripts/slice_images.py <project>/images/illus_sheet.png --grid 2x3 \
+ --names team,product,customer,growth,risk,vision --trim --alpha
+```
+
+**Three constraints that decide whether it looks good**:
+
+1. **Flat background, matched to the slide.** `image_gen.py` has no transparent-background mode, so the cut element carries whatever was behind it. A flat sheet background (= deck background HEX) is what `--alpha` keys out and what makes non-keyed pieces blend.
+2. **Clean grid, or it cuts ugly.** The model will not place every element perfectly; force a clear grid with gutters, and generate **a few sheets** (re-roll the same prompt) to pick the cleanest-laid-out one before slicing. `--trim` absorbs the rest.
+3. **Generate only as large as needed.** Each cell is a fraction of the sheet. Pick the smallest sheet size that keeps each sliced cell at least **1.5-2x** the intended display size. `1K` is usually enough for small 80-160px decorative spots; use `2K` for medium 180-320px placements; reserve `4K` for large, cropped, or potentially enlarged elements.
+
---
## 5. Global Hard Rules
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 0cfd3529..72b53c9e 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -352,6 +352,8 @@ The script renders PNGs into `images/`, trying `codecogs`, `quicklatex`, `mathpa
> **Confirmed value wins.** The `image_usage` in `result.json` (or the chat reply) **overrides the recommendation here** — map it to §VIII `Acquire Via` (`ai`→`ai`, `web`→`web`, `provided`→**`user`**, `placeholder`→`placeholder`, `none`→option A, no image rows). When it is not `ai` (and the plan has no AI part), skip h.5 entirely and write no `ai` rows. See SKILL.md Step 4 for the full mapping.
+> **Illustration usage is a confirmed binary intent toggle inside Image usage, not a second source enum.** If the user confirmed an illustration usage (`result.json.illustration_usage`, or the equivalent chat reply — chat is the canonical channel), honor it: `none` = do not intentionally add decorative illustrations; `use` = make illustrations part of the deck's visual language, with **intensity** (sparse spots vs a recurring system) your own judgment from content + `visual_style`. The actual §VIII `Acquire Via` still comes from `image_usage` and available assets. `image_usage: none` wins over illustration intent and produces no decorative illustration rows. Otherwise, when `use` is set: AI-backed illustration sets may use an `ai` Illustration Sheet plus `slice` element rows, user-provided illustrations are `Type: Illustration` + `Acquire Via: user`, web illustrations are `web` only when licensing/source quality is acceptable, and deferred/copyright-sensitive ones are `placeholder`. Do not expose sheet/slice mechanics to the user in the confirmation copy.
+
**When recommending C** — surface its three implementation modes so the user knows "no API key" is a supported state:
| Mode | Trigger | Mechanism |
@@ -364,6 +366,8 @@ Selection is automatic in Step 5 (A → B → Manual). Detailed contract: [`imag
Selections may be mixed at the row level — e.g. a deck can use C for hero illustrations while sourcing D for supporting team photos.
+> **Spot illustrations → one sheet, not N rows.** When the deck wants ≥3 small same-family spot illustrations as decorative accessories across pages (the illustration counterpart to icons), do not write one `ai` row per element. Write **one `ai` sheet row** (the grid prompt — generated but never placed, kept out of `spec_lock.md images`) **plus one `slice` element row per cell** (each placed, each listed in `spec_lock.md images` so the Executor may reference it). Step 5 generates the sheet then slices it; one generation keeps the whole set on one style/palette, the way the deck-wide rendering lock intends. Plan these sparingly, only where decoration genuinely lifts the page. Full resource contract + slice command: [`image-generator.md`](./image-generator.md) §4.3.
+
#### h.5 AI Image Strategy — lock rendering + palette (only when C is selected)
When the deck includes any `ai` rows, Strategist locks a **deck-wide rendering** and **deck-wide palette** here. These two values are written into `design_spec.md §III` and `spec_lock.md colors` / `images` sections, then consumed by Image_Generator. Every AI image in the deck shares them — this is what makes multiple AI images feel like one deck.
@@ -548,7 +552,7 @@ After the user picks a candidate, scan the outline and surface any pages where t
| **Layout pattern** | **MANDATORY** — one or more `#<id> <name>` joined by ` + ` from `image-layout-patterns.md`. Combine a Primary id with optional Modifier ids when the page needs it (e.g. `#48 side-by-side comparison + #21 rounded rectangle crop + #29 two-stop scrim`). A single Primary is fine when the page calls for it. See the GATE earlier in this section. Empty cells or invented ids are invalid. |
| Purpose | e.g., `Cover background` |
| Type | Free-form category tag — `Background`, `Photography`, `Illustration`, `Diagram`, `Portrait`, `Latex Formula`, etc. Required for formula rows (`Latex Formula`). |
-| **Acquire Via** | `ai` / `web` / `user` / `formula` / `placeholder` — only `ai` and `web` drive Step 5 dispatch |
+| **Acquire Via** | `ai` / `web` / `user` / `formula` / `placeholder` / `slice` — only `ai` and `web` drive Step 5 dispatch; `slice` is derived after its `ai` sheet generates (§4.3) |
| Status | Initial status must be `Pending`, `Existing`, `Rendered`, or `Placeholder`; see [`svg-image-embedding.md`](svg-image-embedding.md) for the full status enum |
| **Reference** | Free-form **intent description** (NOT a search query); feeds Image_Generator (ai) or Image_Searcher (web) |
| `text_policy` (optional, `ai` rows only) | `none` (no text in image) or `embedded` (text is part of the artwork). Leave blank when Image_Generator should decide per row. Long body / data / lists stay in SVG. |
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index 9d471e62..c9e0e879 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -18,17 +18,19 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac
| product.png | 600x400 | Page 3 product photo | Photography | user | Existing | - |
| formula_001.png | 736x168 | Page 3 block equation | Latex Formula | formula | Rendered | `E = mc^2` |
| chart.png | 600x400 | Page 5 placeholder | Illustration | placeholder | Placeholder | Team collaboration scene to be added later |
+| spot_sheet.png | 1024x1024 | 2x2 spot illustration sheet, not placed | Illustration Sheet | ai | Pending | Four same-family spot illustrations on a clean grid |
+| spot_team.png | TBD after slicing | Page 4 team spot illustration | Illustration | slice | Pending | From `spot_sheet.png` cell 1,1 |
```
### Image Status Enum
| Status | Meaning | Executor Handling |
|--------|---------|-------------------|
-| **Pending** | Acquisition needed (`Acquire Via: ai` or `web`); not yet attempted | Image Acquisition Phase (Step 5) consumes this; must not remain after Step 5 |
-| **Generated** | AI-generated file exists at expected path | Reference from `../images/`; no on-slide credit needed |
+| **Pending** | Acquisition needed (`Acquire Via: ai` / `web`) or derivation needed (`Acquire Via: slice`); not yet attempted | Image Acquisition Phase (Step 5) consumes this; must not remain after Step 5 |
+| **Generated** | AI-generated file exists at expected path, or sliced element file exists at expected path | Reference from `../images/`; no on-slide credit needed. **Exception**: an `Illustration Sheet` row is only a slice source — it lives in §VIII but never in `spec_lock.md images`, so the Executor never places it |
| **Sourced** | Web-sourced file exists at expected path | Reference from `../images/`; check `image_sources.json` for `license_tier` — if `attribution-required`, render an inline credit element on the slide (see [executor-base.md §6](./executor-base.md) and [image-searcher.md §7](./image-searcher.md) for the visual spec) |
| **Rendered** | Deterministic formula PNG exists at expected path (`Acquire Via: formula`) | Reference from `../images/`; use `preserveAspectRatio="xMidYMid meet"` and do not crop |
-| **Needs-Manual** | Acquisition attempted once + one retry, failed | Dashed placeholder unless user has manually supplied the file |
+| **Needs-Manual** | Acquisition attempted once + one retry, failed; for `slice`, parent sheet is unavailable | Dashed placeholder unless user has manually supplied the file. For `slice` rows, place the parent sheet and rerun `slice_images.py`; do not hand-place individual element files |
| **Existing** | User already has image (`Acquire Via: user`) | Place in `images/`, reference with `<image>` |
| **Placeholder** | Intentionally not prepared yet (`Acquire Via: placeholder`) | Dashed border placeholder; replace later |
@@ -41,6 +43,7 @@ Defined in the Design Specification & Content Outline; each image carries an `Ac
2. Image Acquisition (Step 5):
- Pending + ai → Image_Generator runs image_gen.py → Generated
- Pending + web → Image_Searcher runs image_search.py → Sourced
+ - Pending + slice → after parent AI sheet is Generated, slice_images.py cuts element files → Generated
- formula / user / placeholder rows are skipped
3. Executor generates SVGs (svg_output/)
├── Existing / Generated → <image href="../images/xxx.png" .../>
diff --git a/skills/ppt-master/scripts/slice_images.py b/skills/ppt-master/scripts/slice_images.py
new file mode 100644
index 00000000..64dc117b
--- /dev/null
+++ b/skills/ppt-master/scripts/slice_images.py
@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Illustration Sheet Slicer
+
+Slice one AI-generated "illustration sheet" (a single image whose prompt laid
+out several illustration elements in a grid) into N individual element files in
+the project's `images/` folder. This is the cheap-and-consistent path for spot
+illustrations: generate one multi-element sheet with `image_gen.py` (one call,
+one coherent style/palette), then cut the cells out here so each element is a
+normal image the Executor places like any other.
+
+Two optional cleanups address the realities of cropping a raster sheet:
+ --trim tight-crop each cell to its content bounding box, so imprecise AI
+ placement inside a cell does not leave lopsided margins.
+ --alpha knock the (flat) sheet background out to transparency, so an element
+ can sit on a differently-colored slide without a visible box.
+Both need a background color; it is auto-sampled from each cell's corners unless
+you pass --bg.
+
+Usage:
+ python3 scripts/slice_images.py <sheet_image> --grid RxC [options]
+
+Examples:
+ python3 scripts/slice_images.py projects/demo/images/illus_sheet.png --grid 2x3
+ python3 scripts/slice_images.py projects/demo/images/illus_sheet.png --grid 2x3 \
+ --names team,product,customer,growth,risk,vision --trim --alpha
+ python3 scripts/slice_images.py projects/demo/images/illus_sheet.png --grid 1x4 \
+ --prefix spot_ --bg "#F8F9FA" --alpha
+
+Dependencies:
+ Pillow
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+from console_encoding import configure_utf8_stdio
+
+configure_utf8_stdio()
+
+from PIL import Image, ImageChops
+
+_GRID_RE = re.compile(r"^\s*(\d+)\s*[xX×]\s*(\d+)\s*$")
+
+
+def _log(msg: str) -> None:
+ """Print progress to stderr (stdout carries the created file paths)."""
+ print(msg, file=sys.stderr)
+
+
+def parse_grid(spec: str) -> tuple[int, int]:
+ """Parse a 'RxC' grid spec into (rows, cols)."""
+ m = _GRID_RE.match(spec)
+ if not m:
+ raise ValueError(f"--grid must look like '2x3' (rows x cols), got {spec!r}")
+ rows, cols = int(m.group(1)), int(m.group(2))
+ if rows < 1 or cols < 1:
+ raise ValueError(f"--grid rows and cols must be >= 1, got {rows}x{cols}")
+ return rows, cols
+
+
+def parse_hex(value: str) -> tuple[int, int, int]:
+ """Parse '#RRGGBB' / 'RRGGBB' into an (r, g, b) tuple."""
+ h = value.strip().lstrip("#")
+ if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
+ raise ValueError(f"--bg must be a 6-digit hex color, got {value!r}")
+ return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+
+
+def _safe_basename(name: str) -> str:
+ """Reject path components in an output name — this tool writes bare files only."""
+ base = name.strip()
+ if (not base or base in {".", ".."} or ".." in base
+ or "/" in base or "\\" in base or Path(base).is_absolute()):
+ raise ValueError(f"unsafe output name {name!r}: must be a bare filename, no path parts")
+ return base
+
+
+def _sample_bg(cell: Image.Image) -> tuple[int, int, int]:
+ """Estimate the flat background color from a cell's four corner pixels."""
+ rgb = cell.convert("RGB")
+ w, h = rgb.size
+ corners = [(0, 0), (w - 1, 0), (0, h - 1), (w - 1, h - 1)]
+ px = [rgb.getpixel(c) for c in corners]
+ return tuple(round(sum(ch) / len(px)) for ch in zip(*px)) # type: ignore[return-value]
+
+
+def _content_mask(cell: Image.Image, bg: tuple[int, int, int], tolerance: int) -> Image.Image:
+ """Build an 'L' mask: 255 where the cell differs from `bg`, 0 elsewhere."""
+ diff = ImageChops.difference(cell.convert("RGB"), Image.new("RGB", cell.size, bg))
+ gray = diff.convert("L")
+ return gray.point(lambda p: 255 if p > tolerance else 0)
+
+
+def slice_sheet(
+ sheet_path: Path,
+ rows: int,
+ cols: int,
+ output_dir: Path,
+ *,
+ names: Optional[list[str]] = None,
+ prefix: Optional[str] = None,
+ inset: float = 0.0,
+ trim: bool = False,
+ alpha: bool = False,
+ bg: Optional[tuple[int, int, int]] = None,
+ tolerance: int = 18,
+) -> list[Path]:
+ """Slice `sheet_path` into rows*cols element PNGs under `output_dir`.
+
+ Returns the list of written file paths (row-major order). When `names` is
+ given it must hold exactly rows*cols entries — a mismatch is an error so an
+ automated run never silently drops cells. Each name must be a bare filename.
+ """
+ total_cells = rows * cols
+ if names is not None and len(names) != total_cells:
+ raise ValueError(
+ f"--names has {len(names)} entries but the {rows}x{cols} grid has "
+ f"{total_cells} cells; provide exactly one name per cell"
+ )
+ safe_names = [_safe_basename(n) for n in names] if names else None
+
+ sheet = Image.open(sheet_path).convert("RGBA")
+ sw, sh = sheet.size
+ output_dir.mkdir(parents=True, exist_ok=True)
+
+ stem = sheet_path.stem
+ name_prefix = _safe_basename(prefix) if prefix else f"{stem}_"
+ written: list[Path] = []
+
+ idx = 0
+ for r in range(rows):
+ for c in range(cols):
+ # Integer cell box via per-index rounding to avoid drift.
+ x0, x1 = round(c * sw / cols), round((c + 1) * sw / cols)
+ y0, y1 = round(r * sh / rows), round((r + 1) * sh / rows)
+ if inset > 0:
+ dx = round((x1 - x0) * inset)
+ dy = round((y1 - y0) * inset)
+ x0, x1, y0, y1 = x0 + dx, x1 - dx, y0 + dy, y1 - dy
+ cell = sheet.crop((x0, y0, x1, y1))
+
+ mask: Optional[Image.Image] = None
+ bbox = None
+ if trim or alpha:
+ cell_bg = bg if bg is not None else _sample_bg(cell)
+ mask = _content_mask(cell, cell_bg, tolerance)
+ bbox = mask.getbbox()
+ if bbox is None:
+ raise ValueError(f"cell ({r},{c}) is all background; no element was sliced")
+
+ if trim and mask is not None and bbox is not None:
+ cell = cell.crop(bbox)
+ mask = mask.crop(bbox)
+
+ if alpha and mask is not None:
+ cell.putalpha(mask)
+
+ if safe_names:
+ out_name = safe_names[idx]
+ if not Path(out_name).suffix:
+ out_name += ".png"
+ else:
+ out_name = f"{name_prefix}{idx + 1:02d}.png"
+ out_path = output_dir / out_name
+ cell.save(out_path)
+ written.append(out_path)
+ _log(f"[OK] cell ({r},{c}) -> {out_path.name} ({cell.width}x{cell.height})")
+ idx += 1
+
+ if len(written) != total_cells:
+ raise ValueError(f"sliced {len(written)} elements but expected {total_cells}")
+ return written
+
+
+def build_parser() -> argparse.ArgumentParser:
+ """Build the command-line parser."""
+ parser = argparse.ArgumentParser(
+ description="Slice an AI illustration sheet into individual element images.",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog="""Examples:
+ python3 scripts/slice_images.py projects/demo/images/illus_sheet.png --grid 2x3
+ python3 scripts/slice_images.py projects/demo/images/illus_sheet.png --grid 2x3 \\
+ --names team,product,customer,growth,risk,vision --trim --alpha
+""",
+ )
+ parser.add_argument("sheet", help="Path to the generated illustration sheet image")
+ parser.add_argument("--grid", required=True, help="Grid as 'RxC' (rows x cols), e.g. 2x3")
+ parser.add_argument(
+ "-o", "--output", default=None,
+ help="Output directory (default: the sheet's own directory)",
+ )
+ parser.add_argument(
+ "--names", default=None,
+ help="Comma-separated element names, row-major (extension optional). "
+ "Must provide exactly rows*cols bare filenames.",
+ )
+ parser.add_argument(
+ "--prefix", default=None,
+ help="Filename prefix when --names is absent (default: '<sheet-stem>_')",
+ )
+ parser.add_argument(
+ "--inset", type=float, default=0.0,
+ help="Trim each cell inward by this fraction on every side (0-0.49) to drop gutters",
+ )
+ parser.add_argument(
+ "--trim", action="store_true",
+ help="Tight-crop each cell to its content bounding box",
+ )
+ parser.add_argument(
+ "--alpha", action="store_true",
+ help="Make the (flat) background transparent in each element",
+ )
+ parser.add_argument(
+ "--bg", default=None,
+ help="Background hex color for --trim/--alpha (default: auto-sample cell corners)",
+ )
+ parser.add_argument(
+ "--tolerance", type=int, default=18,
+ help="Per-pixel color distance treated as background for --trim/--alpha (default: 18)",
+ )
+ return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+ """Run the CLI entry point."""
+ parser = build_parser()
+ args = parser.parse_args(argv)
+
+ sheet_path = Path(args.sheet)
+ if not sheet_path.exists():
+ print(f"[ERROR] Sheet not found: {sheet_path}", file=sys.stderr)
+ return 1
+
+ try:
+ rows, cols = parse_grid(args.grid)
+ bg = parse_hex(args.bg) if args.bg else None
+ except ValueError as exc:
+ print(f"[ERROR] {exc}", file=sys.stderr)
+ return 1
+
+ if not 0.0 <= args.inset < 0.5:
+ print("[ERROR] --inset must be in [0, 0.5)", file=sys.stderr)
+ return 1
+
+ names = [n.strip() for n in args.names.split(",") if n.strip()] if args.names else None
+ output_dir = Path(args.output) if args.output else sheet_path.parent
+
+ try:
+ written = slice_sheet(
+ sheet_path, rows, cols, output_dir,
+ names=names, prefix=args.prefix, inset=args.inset,
+ trim=args.trim, alpha=args.alpha, bg=bg, tolerance=args.tolerance,
+ )
+ except (OSError, ValueError) as exc:
+ print(f"[ERROR] Slicing failed: {exc}", file=sys.stderr)
+ return 1
+
+ _log(f"\n[DONE] Wrote {len(written)} element(s) to {output_dir}")
+ for p in written:
+ print(p)
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index a360fc3c..9d3c35d1 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -266,6 +266,7 @@ Catalog read: 71 templates
- `Background` — cover / chapter / full-bleed atmosphere
- `Photography` — real-world photo
- `Illustration` — vector / flat / painterly art
+- `Illustration Sheet` — a grid of several spot illustrations generated as one image to be sliced (the `ai` sheet row of a `slice` set; never placed itself)
- `Diagram` — schematic / architecture / flowchart
- `Portrait` — single-subject person
- `Latex Formula` — formula PNG rendered by `latex_render.py`
@@ -284,6 +285,9 @@ Catalog read: 71 templates
- `formula` — already rendered by `latex_render.py` before this spec was written
- `user` — user-supplied
- `placeholder` — intentionally deferred
+- `slice` — a spot-illustration element derived in Step 5 by cutting it out of an `ai` sheet row (not generated on its own)
+
+> **Spot-illustration sheets (`slice`).** When the deck draws several same-family spot illustrations from one generated sheet (see [`image-generator.md`](../references/image-generator.md) §4.3), write **two kinds of rows**: one **sheet row** (`Acquire Via: ai`, `Type: Illustration Sheet`, name the grid in `Reference` e.g. `2x3 spot sheet`) that is generated but **never placed** — keep it out of `spec_lock.md images`; and one **element row per cell** (`Acquire Via: slice`, `Reference` naming the parent sheet + cell, dimensions filled after slicing) that **is** placed — list every element row in `spec_lock.md images` so the Executor may reference it. An element row with no sheet row, or a sliced file absent from `spec_lock.md images`, is an invalid spec.
**text_policy** (`ai` rows only; AI judges per row, no global default bias):