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.mdindex 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 --alphapython3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemonpython3 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 animationdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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 --alphapython3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemonpython3 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 animationdiff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 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):```bashpython3 ${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.mdindex 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 once2. On recoverable failure (network, no candidates, license rejection, rate limit), retry once with broadened parameters3. 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.mdindex 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 Rulesdiff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.mdindex 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: [`imagSelections 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.mdindex 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 `Ac2. 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 skipped3. 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.pynew file mode 100644index 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.mdindex 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):