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(confirm-ui): add selectable illustration strategies

hugohe329d09fdf4d76
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 88ff55d6..17cfc878 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -85,6 +85,7 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
| `topic-research` | `workflows/topic-research.md` | Pre-pipeline — gather web sources when the user supplies only a topic with no source files |
| `template-fill` | `workflows/template-fill-pptx.md` | Give a native PPTX template deck plus source material; select fitting pages (a page may be reused for several output slides) and fill text back without SVG conversion |
| `beautify` | `workflows/beautify-pptx.md` | Re-layout an existing PPTX through the SVG pipeline — preserve its text verbatim, inherit its palette/fonts as truth, redo only layout; mirror of `template-fill` |
+| `svg-remix` | `workflows/svg-remix.md` | Use project-local `svg-flat` prototypes from PPTX intake, remix them for new content, then export PPTX without registering a template |
| `create-template` | `workflows/create-template.md` | Standalone layout template creation workflow |
| `create-brand` | `workflows/create-brand.md` | Standalone brand-only template creation (identity preset; no SVG page roster) |
| `resume-execute` | `workflows/resume-execute.md` | Phase B entry — resume execution in a fresh chat after Phase A (Step 1–5) completed in another session (split mode) |
@@ -104,6 +105,7 @@ When the user provides an existing `.pptx`, route by the role of the source deck
| Preserve the deck's page split, page order, and per-slide wording; improve layout / hierarchy / whitespace | `beautify` | Source page count and order are 1:1; text and data values are frozen; visual identity is inherited after confirmation |
| Treat the deck as source material; rethink the story, merge / split / drop / reorder pages, or change page count | Main pipeline | `ppt_to_md` + PPTX intake provide content facts and candidates; Strategist may re-architect freely |
| Reuse the deck's native design with new material | `template-fill` | Clone selected source slides and replace text / table / chart data directly in OOXML; no SVG generation |
+| Reuse the deck's SVG layout language with new material | `svg-remix` | Use flat SVG intake only to capture project-local `svg-flat` prototypes, then hand-author new `svg_output/` pages under an approved remix-freedom level; no native OOXML fill, no forced page-by-page mirror replication, and no template-library registration |
| Harvest the deck as a reusable future template | `create-template` | Build a template package, not a one-off generated deck |
| Keep the finished deck visually stable and append native optimizations such as notes / narration audio / automatic playback | `native-enhance-pptx` | Archive the source PPTX into the project (`projects/` sources move; external sources copy) and patch enhancement metadata/media directly in OOXML; no SVG generation |
@@ -336,7 +338,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 + illustration 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 + illustration strategy + generated-image style · 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.
@@ -350,7 +352,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); `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.
+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`); when `illustration_usage: use`, write `recommend.illustration_strategy` as a recommended **array** with one or more ids from `hero-only` / `sparse-spots` / `recurring-motif` / `image-as-canvas`. The still-open page polls, renders Tier 2, and preserves the user's Tier 1 picks. Closed fields (`illustration_usage`, `illustration_strategy`, `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec`) stay finite; `illustration_strategy` is a finite multi-select with no Custom box; 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
@@ -381,9 +383,11 @@ When the confirmed `image_usage` is not `ai` (and the plan has no AI part), do *
| `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` |
+| `use` | Make illustrations part of the deck; the confirmed `illustration_strategy` controls how they are used |
-**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.
+**Strategy and source are separate.** `illustration_strategy` controls role and intensity; 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 chooses what role illustrations play, but never has to choose or see the internal sheet/slice implementation.
+
+**Illustration strategy is user-facing and multi-select when illustrations are used.** Confirm UI writes `result.json.illustration_strategy` as an array containing one or more of `hero-only` / `sparse-spots` / `recurring-motif` / `image-as-canvas`; honor it exactly. If chat fallback or a legacy result omits the array while `illustration_usage: use`, choose a conservative default from content + `visual_style` and record that it was inferred. Strategist writes `design_spec.md §VIII Illustration System` with the selected strategies, a motif family, reuse rule, do-not-use pages, and boundary against icons / charts / photos. If the selected strategies include `sparse-spots` or `recurring-motif` and the plan needs ≥3 same-family small illustrations, use the `ai` Illustration Sheet + `slice` workflow by default; do not generate one AI image per spot.
**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.
@@ -486,7 +490,7 @@ 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.
+> 💡 **ai path — spot illustrations as one sheet**: when `design_spec.md §VIII Illustration System` uses `sparse-spots` or `recurring-motif` and ≥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.
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index e3ebecde..43e780fa 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -244,7 +244,9 @@ Example opening for a triptych hero:
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.
+**When to use**: `design_spec.md §VIII Illustration System` has a Strategy including `sparse-spots` or `recurring-motif` and ≥3 spot illustrations of the same family are 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.
+
+**Hard rule**: a spot sheet is a generation source, not a slide asset. The sheet row is never listed in `spec_lock.md images` and never referenced from SVG. Only the sliced element rows are placed.
**Sheet prompt convention** (one manifest item, `page_role: local`, `text_policy: none`, `image_size` chosen from final placement size):
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 72b53c9e..660bbde7 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -352,7 +352,28 @@ 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.
+> **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. When `use` is set, also honor `result.json.illustration_strategy` as the user's multi-select choice for how illustrations are used. 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.
+
+**Mandatory — honor the illustration strategy multi-select when `illustration_usage: use`.** Write the result in `design_spec.md §VIII Illustration System`. Use the confirmed `result.json.illustration_strategy` array when present; if chat fallback or a legacy result omits it, infer a conservative array from content + `visual_style` and state that it was inferred. Valid ids:
+
+| Strategy | Behavior |
+|---|---|
+| `hero-only` | Illustrations appear only as cover / chapter / closing hero imagery; no decorative spots. |
+| `sparse-spots` | 3-6 same-family spot illustrations support selected pages as small margin / edge / behind-text accents. |
+| `recurring-motif` | One repeated visual motif family recurs across sections and becomes a deck identity cue. |
+| `image-as-canvas` | Large illustration/photo scenes become canvases for native SVG annotations, KPI cards, routes, or architecture overlays. |
+
+**Default — strategy recommendation (may combine when content demands):**
+
+| Signal | Strategy |
+|---|---|
+| Cover / chapter atmosphere only; dense report body | `hero-only` |
+| Educational / onboarding / cultural / lifestyle deck with repeated concepts | `sparse-spots` |
+| Brand story / product narrative / event deck needing identity cues | `recurring-motif` |
+| Technical / operational / product / data pages where image can carry context behind editable overlays | `image-as-canvas` |
+| Deck has both expressive dividers and content-rich image pages | combine `hero-only` + `image-as-canvas` |
+
+**Hard rule**: `illustration_strategy` is a planning contract, not a source. `image_usage` still decides `Acquire Via`; the strategy decides role, placement, reuse, and where not to use illustrations.
**When recommending C** — surface its three implementation modes so the user knows "no API key" is a supported state:
@@ -558,6 +579,8 @@ After the user picks a candidate, scan the outline and surface any pages where t
| `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. |
| `page_role` (optional, `ai` rows only) | `local` (image is a region block on an SVG page) or `hero_page` (image is the page's main voice). Leave blank when Image_Generator should decide per row. |
+**Mandatory — Illustration System block**: when `illustration_usage: use`, fill the `design_spec.md §VIII Illustration System` table before the resource list. The block must state `Strategy`, `Motif family`, `Reuse rule`, `Do not use on`, and `Boundary`. Use `none` / `not applicable` only when the confirmed image usage is `none` or no intentional illustrations are used.
+
**No-crop flag (exception only)**: most images are croppable — Executor defaults to `preserveAspectRatio="xMidYMid slice"`. When an image must NOT lose pixels (data screenshots, charts, certificates, contracts, dense diagrams), append `no-crop` to its `spec_lock.md images` entry. Executor will then size the container to the native ratio and use `meet`. Don't tag the rest.
**Formula rows**: rendered LaTeX PNGs are image rows with `Acquire Via: formula`, `Status: Rendered`, and `Type: Latex Formula`. Always append `no-crop` in `spec_lock.md images`. They are not AI images and never go through Step 5.
diff --git a/skills/ppt-master/scripts/confirm_ui/static/app.js b/skills/ppt-master/scripts/confirm_ui/static/app.js
index 5a12c95f..00829f9e 100644
--- a/skills/ppt-master/scripts/confirm_ui/static/app.js
+++ b/skills/ppt-master/scripts/confirm_ui/static/app.js
@@ -1,6 +1,6 @@
/* PPT Master - Eight Confirmations UI
* Finite/enumerable fields (canvas, mode, visual style, icons, image usage,
- * illustration usage, AI source, formula policy, generation mode) list ALL options from
+ * illustration usage, illustration strategy, AI source, formula policy, generation mode) list ALL options from
* /static/catalogs.json with the AI's recommendation marked. Open/generative
* fields (color, typography, generated-image style) show >=3 AI candidates. Open fields also expose
* Custom controls. On confirm the page saves result.json and closes.
@@ -53,6 +53,7 @@
image_strategy_mood: "Mood",
image_usage_custom_required: "Describe the custom image plan before confirming.",
illustration_usage: "Illustration usage",
+ illustration_strategy: "How to use illustrations (choose one or more)",
font_heading: "Heading",
font_body: "Body",
font_body_size: "Body baseline size",
@@ -134,6 +135,7 @@
image_strategy_mood: "情绪",
image_usage_custom_required: "请先写清楚自定义图片方案。",
illustration_usage: "插图使用",
+ illustration_strategy: "插图怎么用(可多选)",
font_heading: "标题",
font_body: "正文",
font_body_size: "正文基准字号",
@@ -279,6 +281,7 @@
}
function normalizeRecId(field, value) {
+ if (Array.isArray(value)) return normalizeRecId(field, value[0]);
if (value == null || value === "") return value;
var aliases = REC_ALIASES[field] || {};
return aliases[value] || value;
@@ -291,6 +294,7 @@
if (field === "icons") return REC.icons && REC.icons.value;
if (field === "image_usage") return REC.images && REC.images.value;
if (field === "illustration_usage") return REC.illustrations && REC.illustrations.value;
+ if (field === "illustration_strategy") return REC.illustration_strategy && REC.illustration_strategy.value;
if (field === "image_ai_path") return REC.image_ai_path || (REC.images && REC.images.ai_path);
if (field === "formula_policy") return REC.typography && REC.typography.formula_policy && REC.typography.formula_policy.value;
if (field === "generation_mode") return REC.generation_mode && REC.generation_mode.value;
@@ -301,6 +305,11 @@
var value = (REC && REC.recommend && REC.recommend[field]) || legacyRecId(field);
return normalizeRecId(field, value || null);
}
+ function recIds(field) {
+ var value = (REC && REC.recommend && REC.recommend[field]) || legacyRecId(field);
+ var values = Array.isArray(value) ? value : (value == null || value === "" ? [] : [value]);
+ return values.map(function (v) { return normalizeRecId(field, v); }).filter(Boolean);
+ }
// Guaranteed recommendation: the AI's pick, or the first catalog option as a
// fallback so an enumerable field ALWAYS shows a badged recommendation.
function recOrFirst(field, list) {
@@ -308,6 +317,12 @@
if (r != null && r !== "") return r;
return firstId(list);
}
+ function recOrFirstIds(field, list) {
+ var values = recIds(field);
+ if (values.length) return values;
+ var first = firstId(list);
+ return first ? [first] : [];
+ }
// Render an enumerable field: ALL options from the catalog, recommended one
// badged, current selection from STATE, plus a trailing Custom box.
@@ -419,6 +434,67 @@
customInput.addEventListener("input", function () { setVal(customInput.value || customSentinel); });
}
+ function enumMultiField(parent, list, recommendedIds, getVal, setVal) {
+ list = list || [];
+ recommendedIds = recommendedIds || [];
+ var grouped = list.length && list[0] && list[0].items;
+ var flat = grouped ? list.reduce(function (a, g) { return a.concat(g.items || []); }, []) : list;
+ var ids = flat.map(function (o) { return o.id; });
+ var recommendedSet = {};
+ recommendedIds.forEach(function (id) { recommendedSet[id] = true; });
+ var selected = getVal();
+ selected = Array.isArray(selected) ? selected.slice() : (selected ? [selected] : []);
+ selected = selected.filter(function (id) { return ids.indexOf(id) >= 0; });
+ if (!selected.length) {
+ selected = recommendedIds.filter(function (id) { return ids.indexOf(id) >= 0; });
+ }
+ if (!selected.length && ids.length) selected = [ids[0]];
+ setVal(selected);
+
+ var chipById = {};
+ function paint() {
+ Object.keys(chipById).forEach(function (id) {
+ chipById[id].classList.toggle("selected", selected.indexOf(id) >= 0);
+ });
+ }
+ function makeChip(o) {
+ var label = optionLabel(o);
+ var desc = optionDesc(o);
+ if (desc) label += (LANG === "zh" ? ":" : " — ") + desc;
+ var chip = el("div", "chip");
+ chip.appendChild(el("span", "chip-text", label));
+ if (recommendedSet[o.id]) {
+ chip.classList.add("recommended");
+ chip.appendChild(el("span", "rec-badge", "★ " + t("recommended")));
+ }
+ chip.addEventListener("click", function () {
+ var idx = selected.indexOf(o.id);
+ if (idx >= 0) {
+ if (selected.length > 1) selected.splice(idx, 1);
+ } else {
+ selected.push(o.id);
+ }
+ setVal(selected.slice());
+ paint();
+ });
+ chipById[o.id] = chip;
+ return chip;
+ }
+ if (grouped) {
+ list.forEach(function (g) {
+ if (groupLabel(g)) parent.appendChild(el("div", "group-label", groupLabel(g)));
+ var row = el("div", "chips");
+ (g.items || []).forEach(function (o) { row.appendChild(makeChip(o)); });
+ parent.appendChild(row);
+ });
+ } else {
+ var wrap = el("div", "chips");
+ flat.forEach(function (o) { wrap.appendChild(makeChip(o)); });
+ parent.appendChild(wrap);
+ }
+ paint();
+ }
+
function textField(parent, getVal, setVal, placeholderKey, numeric) {
var input = el("input", numeric ? "num-input" : "text-input");
input.type = "text";
@@ -1202,16 +1278,29 @@
});
var illusSub = el("div", "subfield");
illusSub.appendChild(el("div", "subfield-label", t("illustration_usage")));
+ var illusStrategySub = el("div", "subfield");
+ illusStrategySub.appendChild(el("div", "subfield-label", t("illustration_strategy")));
+ function refreshIllustrationControls() {
+ illusStrategySub.style.display = STATE.illustration_usage === "use" ? "block" : "none";
+ }
enumField(illusSub, CAT.illustration_usage, recOrFirst("illustration_usage", CAT.illustration_usage),
function () { return STATE.illustration_usage; },
- function (v) { STATE.illustration_usage = v; });
+ function (v) {
+ STATE.illustration_usage = v;
+ refreshIllustrationControls();
+ });
+ enumMultiField(illusStrategySub, CAT.illustration_strategy, recOrFirstIds("illustration_strategy", CAT.illustration_strategy),
+ function () { return STATE.illustration_strategy; },
+ function (v) { STATE.illustration_strategy = v; });
enumField(sub, CAT.image_ai_path, recOrFirst("image_ai_path", CAT.image_ai_path),
function () { return STATE.image_ai_path; }, function (v) { STATE.image_ai_path = v; });
sec.appendChild(illusSub);
+ sec.appendChild(illusStrategySub);
sec.appendChild(sub);
sec.appendChild(strategySub);
if (strategyCands.length) selectImageStrategy(imageStrategySelectedIndex());
refreshAiControls();
+ refreshIllustrationControls();
host.appendChild(sec);
}
@@ -1342,6 +1431,7 @@
STATE.image_usage = pick("image_usage", CAT.image_usage);
STATE.illustration_usage = pick("illustration_usage", CAT.illustration_usage);
+ STATE.illustration_strategy = pick("illustration_strategy", CAT.illustration_strategy);
STATE.image_ai_path = pick("image_ai_path", CAT.image_ai_path);
STATE.generation_mode = pick("generation_mode", CAT.generation_mode);
@@ -1451,6 +1541,9 @@
delete payload.image_ai_path;
delete payload.image_strategy;
}
+ if (payload.illustration_usage !== "use") {
+ delete payload.illustration_strategy;
+ }
btn.disabled = true;
fetch("/api/confirm", {
method: "POST",
diff --git a/skills/ppt-master/scripts/confirm_ui/static/catalogs.json b/skills/ppt-master/scripts/confirm_ui/static/catalogs.json
index 210156ba..73686c48 100644
--- a/skills/ppt-master/scripts/confirm_ui/static/catalogs.json
+++ b/skills/ppt-master/scripts/confirm_ui/static/catalogs.json
@@ -383,16 +383,50 @@
"label": "不刻意使用插图",
"label_zh": "不刻意使用插图",
"label_en": "No intentional illustrations",
- "desc_zh": "默认选项;仅在内容本身需要时使用图片。",
- "desc_en": "Default. Use images only when the content itself needs them."
+ "desc_zh": "默认选项;仅在内容本身需要时使用图片,不额外建立插图系统。",
+ "desc_en": "Default. Use images only when the content itself needs them; no separate illustration system."
},
{
"id": "use",
"label": "使用插图",
"label_zh": "使用插图",
"label_en": "Use illustrations",
- "desc_zh": "让插图成为版面的一部分;用多用少由系统按内容与视觉风格判断。",
- "desc_en": "Let illustrations be part of the design; how heavily is decided by content and visual style."
+ "desc_zh": "让插图成为版面的一部分;强度与来源由系统按内容、视觉风格和图片策略判断。",
+ "desc_en": "Let illustrations be part of the design; intensity and source are decided from content, visual style, and image strategy."
+ }
+ ],
+ "illustration_strategy": [
+ {
+ "id": "hero-only",
+ "label": "封面 / 章节主视觉",
+ "label_zh": "封面 / 章节主视觉",
+ "label_en": "Hero visuals",
+ "desc_zh": "只在封面、章节页或关键转场页使用大插图,正文页保持克制。",
+ "desc_en": "Use large illustrations only on covers, section openers, or key transitions; keep body pages restrained."
+ },
+ {
+ "id": "sparse-spots",
+ "label": "少量点状插图",
+ "label_zh": "少量点状插图",
+ "label_en": "Sparse spot illustrations",
+ "desc_zh": "在少数正文页放小插图点题,避免每页都有装饰。",
+ "desc_en": "Place small spot illustrations on selected body pages; avoid decorating every slide."
+ },
+ {
+ "id": "recurring-motif",
+ "label": "重复视觉母题",
+ "label_zh": "重复视觉母题",
+ "label_en": "Recurring motif",
+ "desc_zh": "用同一组角色、物件或符号贯穿全稿,建立统一识别。",
+ "desc_en": "Repeat a consistent family of characters, objects, or symbols across the deck."
+ },
+ {
+ "id": "image-as-canvas",
+ "label": "插图作为版面背景",
+ "label_zh": "插图作为版面背景",
+ "label_en": "Image as canvas",
+ "desc_zh": "让插图承担页面空间、背景或场景,文字浮在其上或嵌入其中。",
+ "desc_en": "Let illustrations carry page space, background, or scene structure with text overlaid or embedded."
}
],
"image_ai_path": [
diff --git a/skills/ppt-master/scripts/docs/confirm_ui.md b/skills/ppt-master/scripts/docs/confirm_ui.md
index b3810ee1..9ad99efb 100644
--- a/skills/ppt-master/scripts/docs/confirm_ui.md
+++ b/skills/ppt-master/scripts/docs/confirm_ui.md
@@ -1,6 +1,6 @@
# Confirm UI — Eight Confirmations Page
-> The interactive, visual surface for SKILL.md Step 4 (the Eight Confirmations). Enumerable fields list **all** options from a catalog with the AI's recommendation badged; generative fields (color, typography, generated-image style) show **≥3** AI candidates (creative recommendations always offer real choice — same rule as the h.5 image strategy; fewer only on the honest-shortfall exception, with a stated reason). Fields whose universe is open (canvas, mode, visual style, icons, image usage) also get a **Custom** box; fully closed fields (illustration usage, AI source when applicable, formula policy, generation mode, refine spec) do not. The AI writes its recommendation to `recommendations.json`; the user's final choices are written back to `result.json` for the AI to read. On confirm the page saves the result and shuts the server down (auto-close). The chat path is always a valid fallback — if the browser cannot open (remote / headless / web host), the AI presents the same confirmations in chat.
+> The interactive, visual surface for SKILL.md Step 4 (the Eight Confirmations). Enumerable fields list **all** options from a catalog with the AI's recommendation badged; generative fields (color, typography, generated-image style) show **≥3** AI candidates (creative recommendations always offer real choice — same rule as the h.5 image strategy; fewer only on the honest-shortfall exception, with a stated reason). Fields whose universe is open (canvas, mode, visual style, icons, image usage) also get a **Custom** box; fully closed fields (illustration usage, illustration strategy, AI source when applicable, formula policy, generation mode, refine spec) do not. The AI writes its recommendation to `recommendations.json`; the user's final choices are written back to `result.json` for the AI to read. On confirm the page saves the result and shuts the server down (auto-close). The chat path is always a valid fallback — if the browser cannot open (remote / headless / web host), the AI presents the same confirmations in chat.
## `confirm_ui/server.py`
@@ -32,16 +32,16 @@ pip install flask
## Two kinds of field
- **Enumerable + custom** — canvas / mode / visual_style / icons / image usage. The page lists common options from `static/catalogs.json`, badges the AI's recommendation, and still offers a Custom box for edge cases (custom canvas size, bespoke narrative mode, mixed image plan, self-provided icon system, etc.). `visual_style` additionally honors an optional `visual_style_spectrum` that badges a 3-pick personality spectrum (safe / shifted / bold, each with a temperament tag + analogy) in place of the single recommendation — see the schema below.
-- **Closed enumerable** — illustration usage / formula policy / generation mode / refine spec, plus AI source only when image usage may include `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option. Use pipeline vocabulary: icon ids are actual library ids such as `tabler-outline`, or `emoji` for system emoji; image usage labels mirror Strategist terminology: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. Use image-usage custom prose only when several sources are mixed. `illustration_usage` is a closed two-option intent toggle (`none` / `use`) — how heavily illustrations are used and where they are sourced are decided downstream by Strategist + `image_usage`, not here.
+- **Closed enumerable** — illustration usage / illustration strategy / formula policy / generation mode / refine spec, plus AI source only when image usage may include `ai`. These have no Custom box; out-of-catalog values snap back to the recommended option. Use pipeline vocabulary: icon ids are actual library ids such as `tabler-outline`, or `emoji` for system emoji; image usage labels mirror Strategist terminology: `ai` = AI-generated, `web` = Web-sourced, `provided` = User-provided, `placeholder` = Placeholder, `none` = No images. Use image-usage custom prose only when several sources are mixed. `illustration_usage` is a closed two-option intent toggle (`none` / `use`). `illustration_strategy` is a closed multi-select shown only when `illustration_usage: use`; it writes an array of one or more ids.
- **Generative (open)** — color, typography, generated-image style. No finite catalog; the AI authors **≥3 candidates** the page renders as cards (never a single option — creative fields must offer real choice; fewer than 3 only on the honest-shortfall exception). `page_count`, `audience`, and `content_divergence` are free inputs (`content_divergence` is a free-text intent shown under audience in §c, not a fixed-option field).
-**Custom box** appears only on fields whose universe is genuinely open — `canvas`, `mode`, `visual_style`, `icons`, and `image_usage`. Fully closed sets — `illustration_usage`, `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec` — have **no** Custom box; an out-of-catalog value there is snapped back to the recommended option.
+**Custom box** appears only on fields whose universe is genuinely open — `canvas`, `mode`, `visual_style`, `icons`, and `image_usage`. Fully closed sets — `illustration_usage`, `illustration_strategy`, `image_ai_path`, `formula_policy`, `generation_mode`, `refine_spec` — have **no** Custom box; an out-of-catalog value there is snapped back to the recommended option.
`image_ai_path` is conditional: the page shows it and writes it to `result.json` only when `image_usage` is `ai` or a custom image plan that may include AI. Web-sourced / User-provided / Placeholder / No images paths do not carry an AI backend choice.
## Catalogs — `static/catalogs.json` (the finite option universe)
-The front-end loads `/api/catalogs` (served by the confirm server) and falls back to the static `/static/catalogs.json` if that route is unavailable. `/api/catalogs` returns the static file **with the `canvas` list synced live from `config.py CANVAS_FORMATS`** — the set of formats and their `dim` come from config (single source of truth, zero drift), while bilingual labels / use text stay in catalogs.json (a plain fallback label is synthesized for any new id config adds). Keys: `canvas`, `modes`, `visual_styles` (grouped), `icons`, `image_usage`, `illustration_usage`, `image_ai_path`, `formula_policy`, `generation_mode`, `delivery_purpose`. Each entry is `{ "id", "label", "label_zh", "label_en", ... }`; descriptions use `desc_zh` / `desc_en`, and `visual_styles` groups use `group_zh` / `group_en`. The front-end falls back to legacy `label` / `desc` / `group`, so old catalogs still load, but new user-facing catalog text must be bilingual. English labels should mirror canonical reference names (`pyramid`, `swiss-minimal`, `Path A`, `mixed`, etc.); Chinese labels should be translated for users. Descriptions render inline after the option title, not as a separate selected-option line. `visual_styles` is `[{ "group", "group_zh", "group_en", "items": [...] }]`. For `canvas` you only need to maintain the bilingual labels in catalogs.json; the format set and dimensions are authoritative in `config.py CANVAS_FORMATS`.
+The front-end loads `/api/catalogs` (served by the confirm server) and falls back to the static `/static/catalogs.json` if that route is unavailable. `/api/catalogs` returns the static file **with the `canvas` list synced live from `config.py CANVAS_FORMATS`** — the set of formats and their `dim` come from config (single source of truth, zero drift), while bilingual labels / use text stay in catalogs.json (a plain fallback label is synthesized for any new id config adds). Keys: `canvas`, `modes`, `visual_styles` (grouped), `icons`, `image_usage`, `illustration_usage`, `illustration_strategy`, `image_ai_path`, `formula_policy`, `generation_mode`, `delivery_purpose`. Each entry is `{ "id", "label", "label_zh", "label_en", ... }`; descriptions use `desc_zh` / `desc_en`, and `visual_styles` groups use `group_zh` / `group_en`. The front-end falls back to legacy `label` / `desc` / `group`, so old catalogs still load, but new user-facing catalog text must be bilingual. English labels should mirror canonical reference names (`pyramid`, `swiss-minimal`, `Path A`, `mixed`, etc.); Chinese labels should be translated for users. Descriptions render inline after the option title, not as a separate selected-option line. `visual_styles` is `[{ "group", "group_zh", "group_en", "items": [...] }]`. For `canvas` you only need to maintain the bilingual labels in catalogs.json; the format set and dimensions are authoritative in `config.py CANVAS_FORMATS`.
## Round-trip data contract
@@ -54,7 +54,7 @@ The page runs as a **two-tier wizard in one browser session**. `recommendations.
| `tier` | Page renders | Button | On submit |
|---|---|---|---|
| `1` | anchors — canvas, audience + `content_divergence` + `delivery_purpose` *(PPT only — omitted on non-PPT canvases, not written to the result)* (all in the §c key-info area), mode + visual_style | **Next** | writes `result.json` `{ stage: "tier1", status: "tier1-confirmed", <anchors> }`; the page does **not** close — it shows a "deriving…" state and polls `GET /api/recommendations` |
-| `2` | realization — page count, color, typography, icons, formula, image usage + illustration usage + strategy, generation mode, refine spec | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
+| `2` | realization — page count, color, typography, icons, formula, image usage + illustration usage + illustration strategy + generated-image style, generation mode, refine spec | **Confirm** | writes `result.json` `{ stage: "final", status: "confirmed", <all fields> }`, then shuts the page down |
| *(absent)* | legacy single-pass — every section on one page | **Confirm** | single final write (`status: "confirmed"`) — backward-compatible |
The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derives** the realization candidates from the user's actual anchors, overwrites `recommendations.json` with `"tier": 2` (realization fields only — it need not echo the anchors), and re-attaches with `--wait-only`. The page preserves the user's Tier 1 selections across the transition (single JS session). `GET /api/recommendations` is served `no-store` so the poll sees the tier-2 overwrite, and when `tier == 2` the server **folds the confirmed anchors from `result.json` back into the payload** (`recommend.canvas` / `mode` / `visual_style` / `delivery_purpose`, plus `audience` / `content_divergence` values) — so a **page refresh / reopen on Tier 2 re-initializes the anchors from the user's choices** instead of catalog defaults, even though those sections are not rendered on the Tier-2 page.
@@ -72,6 +72,7 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
"image_usage": "ai",
"image_ai_path": "auto",
"illustration_usage": "use",
+ "illustration_strategy": ["hero-only", "sparse-spots"],
"formula_policy": "mixed",
"generation_mode": "continuous",
"delivery_purpose": "balanced"
@@ -126,8 +127,8 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
> Each `candidates` array above shows **one** entry for brevity — the creative fields (`color`, `typography`, `image_strategy`) must each carry **≥3** in a real file (see the rule above); `selected` indexes the recommended default.
-- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids. For `recommend.image_usage`, do not write bare `"custom"`; if several image sources are mixed, write the concrete prose plan directly, such as `"封面用 AI 生成,产品页用用户素材,行业页用网络来源"` / `"AI cover + user product assets + web industry images"`.
-- `recommend.illustration_usage` is the user's illustration intent toggle inside the image section, not a second image-source enum. It is a closed two-option field — `none` (don't intentionally add illustrations) or `use` (make illustrations part of the deck). How heavily (sparse vs pervasive) and from where are decided downstream by Strategist + `image_usage`, which maps to §VIII rows using the normal source vocabulary (`ai` / `web` / `user` / `placeholder` / `slice`).
+- `recommend.*` names the recommended `id` for each enumerable field (must match a `catalogs.json` id, or be a free string for a recommended custom value). The page badges and pre-selects it. **Guarantee**: if a `recommend.*` is omitted, the page falls back to the first catalog option so every enumerable field always shows one badged recommendation — but the AI should still set them for a meaningful default. `recommend.illustration_strategy` is the one closed multi-select exception: write an array of ids. Legacy aliases are accepted for old files (`line` → `tabler-outline`, `filled` → `tabler-filled`, `monochrome` → `chunk-filled`, `search` → `web`, `default` → `auto`, `builtin` → `host-native`), but new files should write canonical ids. For `recommend.image_usage`, do not write bare `"custom"`; if several image sources are mixed, write the concrete prose plan directly, such as `"封面用 AI 生成,产品页用用户素材,行业页用网络来源"` / `"AI cover + user product assets + web industry images"`.
+- `recommend.illustration_usage` is the user's illustration intent toggle inside the image section, not a second image-source enum. It is a closed two-option field — `none` (don't intentionally add illustrations) or `use` (make illustrations part of the deck). When it is `use`, `recommend.illustration_strategy` supplies the default checked strategies from `hero-only` / `sparse-spots` / `recurring-motif` / `image-as-canvas`; users can choose one or more. Source still comes from `image_usage`, which maps to §VIII rows using the normal source vocabulary (`ai` / `web` / `user` / `placeholder` / `slice`).
- When `recommend.image_usage` is `ai` or a custom plan that includes AI, also set `recommend.image_ai_path` to one of `auto` / `api` / `host-native` / `manual`; the page presents these as explicit choices.
- For a custom image plan, the page treats "may include AI" as true only when the recommendation includes `recommend.image_ai_path` or `image_strategy.candidates`; a custom plan without those signals is handled as non-AI and omits AI controls / fields.
- **Color candidates carry the user-facing core `palette`**: `background`, `secondary_bg`, `primary`, `accent`, `secondary_accent`, and `body_text`. The page renders labelled swatches and offers per-role override inputs for precise single-role edits, plus a **Custom color card with a free-text box** (parallel to the custom typography box) — the user can describe the palette in words or paste HEX values instead of filling each role; this writes `color: { "name": "custom", "custom": "<text>" }` to `result.json` for the AI to interpret. Legacy `text` is accepted as an alias for `body_text`, but new files should write `body_text`. Strategist derives secondary text, borders, state colors, and visual-style neutral tiers later when writing `design_spec.md` / `spec_lock.md`; those are not user-facing confirmation choices.
@@ -160,6 +161,7 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
"image_usage": "ai",
"image_ai_path": "auto",
"illustration_usage": "use",
+ "illustration_strategy": ["hero-only", "sparse-spots"],
"image_strategy": { "name": "方案 A", "rendering": "vector-illustration", "palette": "cool-corporate", "visual": "...", "color": "...", "mood": "..." },
"generation_mode": "continuous",
"refine_spec": false,
@@ -172,7 +174,7 @@ The AI launches Tier 1 (`--daemon --wait`), reads the tier-1 result, **re-derive
The shape above is the **final** (Tier 2) result, carrying all Tier 1 + Tier 2 fields. The intermediate **Tier 1** write carries only the anchor fields plus `"stage": "tier1"`, `"status": "tier1-confirmed"`; the AI reads it to re-derive Tier 2 and never treats it as the final confirmation. A legacy single-pass write has no `stage` (or `stage: "final"`) and `status: "confirmed"`.
- Any option field may instead hold a **free-text custom string** (the user picked **Custom**); `color` / `typography` custom entries set `name: "custom"`. Image usage custom values must be concrete prose plans, not the literal string `"custom"`. The AI interprets custom text against the canonical references.
-- `illustration_usage` is a closed `none` / `use` toggle. `none` = do not intentionally add decorative illustrations (default, current behavior); `use` = make illustrations part of the deck, with intensity (sparse vs pervasive) the Strategist's call from content + visual style. The source still comes from `image_usage`: `image_usage: none` produces no decorative illustration rows; otherwise AI-backed illustration sets may use an illustration sheet plus `slice` rows, provided assets become `user` rows, web assets become `web` rows when licensing is acceptable, and deferred illustrations become `placeholder` rows.
+- `illustration_usage` is a closed `none` / `use` toggle. `none` = do not intentionally add decorative illustrations (default, current behavior) and the page omits `illustration_strategy`; `use` = make illustrations part of the deck and show `illustration_strategy` as a closed multi-select. The source still comes from `image_usage`: `image_usage: none` produces no decorative illustration rows; otherwise AI-backed illustration sets may use an illustration sheet plus `slice` rows, provided assets become `user` rows, web assets become `web` rows when licensing is acceptable, and deferred illustrations become `placeholder` rows.
- `image_ai_path` and `image_strategy` are omitted from `result.json` unless `image_usage` is `ai` or a custom image plan that may include generated images. Both are honored downstream as confirmed choices — and the page is only a convenience surface over the **canonical chat channel**: the same choices made in chat are honored identically when no `result.json` exists. `image_ai_path` drives the Step 5 generation path (`image-generator.md` §7 — `host-native` forces the host tool even when `IMAGE_BACKEND` is set); the chosen `image_strategy` candidate is locked verbatim by Strategist h.5 (no re-pick).
- After the user clicks the **final Confirm** (Tier 2, or single-pass), the page saves `result.json` and shuts the server down (auto-close). A Tier-1 **Next** instead keeps the page open (it polls for the re-derived Tier 2). In the default flow, the first `--daemon --wait` returns on the tier-1 result and the second `--wait-only` returns on the final result; the AI reads each immediately — no extra chat confirmation is required. Chat confirmation remains the fallback when the page cannot be used. Either way, Step 4 ends with a `--shutdown` cleanup so a never-confirmed page cannot keep holding port 5050 ahead of the Step 6 live preview.
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index 923eca4b..3536edf9 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -221,6 +221,8 @@ class SVGQualityChecker:
# severity is 'error' or 'warning'. Printed in print_summary.
self._template_issues: List[Tuple[str, str, str]] = []
self._animation_issues: List[Tuple[str, str]] = []
+ self._illustration_issues: List[Tuple[str, str, str]] = []
+ self._aggregate_counts_applied = False
def check_file(self, svg_file: str, expected_format: str = None) -> Dict:
"""
@@ -1167,9 +1169,361 @@ class SVGQualityChecker:
self._check_template_contract(dir_path, svg_files)
elif dir_path.is_dir():
self._check_animation_config_contract(dir_path)
+ self._check_illustration_strategy_contract(dir_path)
return self.results
+ def _check_illustration_strategy_contract(self, dir_path: Path) -> None:
+ """Project-level illustration strategy checks."""
+ project_path = self._resolve_project_path(dir_path)
+ spec_path = project_path / 'design_spec.md'
+ if not spec_path.exists():
+ return
+
+ try:
+ spec_text = spec_path.read_text(encoding='utf-8')
+ except OSError as exc:
+ self._illustration_issues.append((
+ 'warning',
+ 'spec_unreadable',
+ f"could not read {spec_path}: {exc}",
+ ))
+ return
+
+ rows = self._extract_image_resource_rows(spec_text)
+ if not rows:
+ return
+
+ lock_images = self._load_project_lock_images(project_path)
+ svg_texts = self._load_project_svg_texts(project_path)
+ all_svg_text = "\n".join(svg_texts.values())
+
+ sheet_rows = [row for row in rows if self._row_type(row).lower() == 'illustration sheet']
+ slice_rows = [row for row in rows if self._row_acquire(row) == 'slice']
+ image_rows = [
+ row for row in rows
+ if self._row_acquire(row) in {'ai', 'web', 'user', 'placeholder', 'slice'}
+ and self._row_type(row).lower() not in {'latex formula', 'illustration sheet'}
+ ]
+
+ for row in sheet_rows:
+ filename = self._row_filename(row)
+ if not filename:
+ continue
+ if filename in lock_images:
+ self._illustration_issues.append((
+ 'error',
+ 'sheet_in_lock',
+ f"{filename} is an Illustration Sheet but is listed in spec_lock.md images; "
+ "only sliced element rows may be listed.",
+ ))
+ if filename in all_svg_text:
+ self._illustration_issues.append((
+ 'error',
+ 'sheet_referenced',
+ f"{filename} is an Illustration Sheet but is referenced by an SVG; "
+ "generate it only as a slice source, never place it.",
+ ))
+
+ for row in slice_rows:
+ filename = self._row_filename(row)
+ if filename and filename not in lock_images:
+ self._illustration_issues.append((
+ 'error',
+ 'slice_missing_lock',
+ f"{filename} is a slice row but is absent from spec_lock.md images.",
+ ))
+
+ has_coverage_note = 'Image-as-canvas' in spec_text or 'image-as-canvas' in spec_text
+ pattern_ids = self._collect_layout_pattern_ids(image_rows)
+ if len(image_rows) >= 4 and not any(38 <= pid <= 46 for pid in pattern_ids):
+ if not has_coverage_note:
+ self._illustration_issues.append((
+ 'warning',
+ 'missing_image_as_canvas',
+ "deck has 4+ image-bearing rows but no #38-#46 image-as-canvas "
+ "layout and no coverage note in design_spec.md §VIII.",
+ ))
+
+ conventional_ids = {1, 2, 3, 5, 6}
+ if len(image_rows) >= 4 and pattern_ids and pattern_ids.issubset(conventional_ids):
+ if not has_coverage_note:
+ self._illustration_issues.append((
+ 'warning',
+ 'layout_pattern_degenerated',
+ "all image-bearing rows use only basic full-bleed / left-right / "
+ "top-bottom patterns (#1/#2/#3/#5/#6); re-check "
+ "references/image-layout-patterns.md for modifiers or image-as-canvas options.",
+ ))
+
+ for row in image_rows:
+ self._check_decorative_image_row(row, project_path, svg_texts)
+
+ @staticmethod
+ def _resolve_project_path(dir_path: Path) -> Path:
+ """Resolve a checker target directory to its project root."""
+ if dir_path.name in {'svg_output', 'svg_final'}:
+ return dir_path.parent
+ if (dir_path / 'svg_output').exists() or (dir_path / 'design_spec.md').exists():
+ return dir_path
+ return dir_path.parent
+
+ @staticmethod
+ def _split_md_table_row(line: str) -> List[str]:
+ """Split a simple Markdown table row into stripped cells."""
+ return [cell.strip().strip('`') for cell in line.strip().strip('|').split('|')]
+
+ @classmethod
+ def _extract_image_resource_rows(cls, spec_text: str) -> List[Dict[str, str]]:
+ """Extract rows from design_spec.md §VIII Image Resource List."""
+ section_match = re.search(
+ r"^##\s+VIII\.\s+Image Resource List\b.*?(?=^##\s+|\Z)",
+ spec_text,
+ re.MULTILINE | re.DOTALL,
+ )
+ if not section_match:
+ return []
+
+ lines = section_match.group(0).splitlines()
+ header = None
+ rows: List[Dict[str, str]] = []
+ in_resource_table = False
+ for line in lines:
+ if not line.strip().startswith('|'):
+ if in_resource_table and rows:
+ break
+ continue
+
+ cells = cls._split_md_table_row(line)
+ if not cells:
+ continue
+ if header is None:
+ if any(cell.lower() == 'filename' for cell in cells):
+ header = cells
+ in_resource_table = True
+ continue
+ if set(cell.replace('-', '').strip() for cell in cells) == {''}:
+ continue
+ if not in_resource_table:
+ continue
+ row = {header[i]: cells[i] if i < len(cells) else '' for i in range(len(header))}
+ filename = row.get('Filename', '').strip()
+ if filename and filename.lower() != 'filename':
+ rows.append(row)
+
+ return rows
+
+ @staticmethod
+ def _row_filename(row: Dict[str, str]) -> str:
+ return Path(row.get('Filename', '').strip()).name
+
+ @staticmethod
+ def _row_type(row: Dict[str, str]) -> str:
+ return row.get('Type', '').strip()
+
+ @staticmethod
+ def _row_acquire(row: Dict[str, str]) -> str:
+ return row.get('Acquire Via', '').strip().lower()
+
+ @staticmethod
+ def _row_layout(row: Dict[str, str]) -> str:
+ return row.get('Layout pattern', '').strip()
+
+ @staticmethod
+ def _collect_layout_pattern_ids(rows: List[Dict[str, str]]) -> set[int]:
+ ids: set[int] = set()
+ for row in rows:
+ for match in re.finditer(r'#(\d+)\b', SVGQualityChecker._row_layout(row)):
+ ids.add(int(match.group(1)))
+ return ids
+
+ def _load_project_lock_images(self, project_path: Path) -> set[str]:
+ """Return filenames listed under spec_lock.md images."""
+ lock_path = project_path / 'spec_lock.md'
+ if _parse_spec_lock is None or not lock_path.exists():
+ return set()
+ try:
+ lock = _parse_spec_lock(lock_path)
+ except Exception:
+ return set()
+ images = set()
+ for value in lock.get('images', {}).values():
+ path_part = value.split('|', 1)[0].strip()
+ images.add(Path(path_part).name)
+ return images
+
+ @staticmethod
+ def _load_project_svg_texts(project_path: Path) -> Dict[Path, str]:
+ """Read project SVG output files for project-level cross-checks."""
+ svg_dir = project_path / 'svg_output'
+ if not svg_dir.exists():
+ return {}
+ out: Dict[Path, str] = {}
+ for svg_path in sorted(svg_dir.glob('*.svg')):
+ try:
+ out[svg_path] = svg_path.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ return out
+
+ def _check_decorative_image_row(
+ self,
+ row: Dict[str, str],
+ project_path: Path,
+ svg_texts: Dict[Path, str],
+ ) -> None:
+ """Warn when decorative image patterns lack obvious SVG/file evidence."""
+ filename = self._row_filename(row)
+ if not filename:
+ return
+ layout = self._row_layout(row)
+ ids = {int(match.group(1)) for match in re.finditer(r'#(\d+)\b', layout)}
+ decorative_ids = ids & {4, 58, 63, 66, 69}
+ if not decorative_ids:
+ return
+ if self._row_type(row).lower() == 'illustration sheet':
+ return
+
+ referenced_tags: List[Tuple[Path, str]] = []
+ for svg_path, content in svg_texts.items():
+ for tag in re.findall(r'<image\b[^>]*>', content, re.IGNORECASE):
+ if filename in tag:
+ referenced_tags.append((svg_path, tag))
+
+ if 63 in decorative_ids:
+ if Path(filename).suffix.lower() != '.png':
+ self._illustration_issues.append((
+ 'warning',
+ 'sticker_not_png',
+ f"{filename} uses #63 transparent sticker / cutout but is not a PNG.",
+ ))
+ elif not self._png_has_alpha(project_path / 'images' / filename):
+ self._illustration_issues.append((
+ 'warning',
+ 'sticker_no_alpha',
+ f"{filename} uses #63 transparent sticker / cutout but the PNG "
+ "does not appear to have an alpha channel.",
+ ))
+
+ if not referenced_tags:
+ return
+
+ if 69 in decorative_ids and not any('rotate(' in tag for _path, tag in referenced_tags):
+ self._illustration_issues.append((
+ 'warning',
+ 'rotation_missing',
+ f"{filename} declares #69 slight rotation but no referenced <image> "
+ "tag contains rotate(...).",
+ ))
+
+ if 4 in decorative_ids and not self._has_off_canvas_reference(referenced_tags):
+ self._illustration_issues.append((
+ 'warning',
+ 'edge_bleed_missing',
+ f"{filename} declares #4 edge bleed but no referenced <image> appears "
+ "to extend past the canvas edge.",
+ ))
+
+ if 58 in decorative_ids and not self._has_corner_fragment_reference(referenced_tags):
+ self._illustration_issues.append((
+ 'warning',
+ 'corner_fragment_missing',
+ f"{filename} declares #58 decorative corner fragment but no referenced "
+ "<image> appears near a canvas corner.",
+ ))
+
+ if 66 in decorative_ids:
+ content_scope = "\n".join(svg_texts.get(path, '') for path, _tag in referenced_tags)
+ if '<linearGradient' not in content_scope and 'opacity' not in content_scope:
+ self._illustration_issues.append((
+ 'warning',
+ 'fade_missing',
+ f"{filename} declares #66 fade into background but the referencing "
+ "SVG has no obvious gradient or opacity treatment.",
+ ))
+
+ @staticmethod
+ def _png_has_alpha(path: Path) -> bool:
+ """Return True when a PNG appears to carry transparent pixels."""
+ if not path.exists():
+ return False
+ try:
+ from PIL import Image as PILImage
+ with PILImage.open(path) as img:
+ if img.mode in {'RGBA', 'LA'}:
+ alpha = img.getchannel('A')
+ return alpha.getextrema()[0] < 255
+ return 'transparency' in img.info
+ except (ImportError, OSError, ValueError):
+ return False
+
+ @staticmethod
+ def _parse_image_geometry(tag: str) -> Tuple[float, float, float, float] | None:
+ """Extract x/y/width/height from an <image> tag."""
+ values = {}
+ for attr in ('x', 'y', 'width', 'height'):
+ match = re.search(rf'\b{attr}\s*=\s*["\']([^"\']+)["\']', tag)
+ if not match:
+ return None
+ try:
+ values[attr] = float(match.group(1))
+ except ValueError:
+ return None
+ return values['x'], values['y'], values['width'], values['height']
+
+ @staticmethod
+ def _parse_svg_viewbox(content: str) -> Tuple[float, float] | None:
+ """Return viewBox width/height from SVG content."""
+ match = re.search(r'viewBox="[^"]*?\s+([0-9.]+)\s+([0-9.]+)"', content)
+ if not match:
+ return None
+ try:
+ return float(match.group(1)), float(match.group(2))
+ except ValueError:
+ return None
+
+ @classmethod
+ def _has_off_canvas_reference(cls, refs: List[Tuple[Path, str]]) -> bool:
+ for svg_path, tag in refs:
+ geometry = cls._parse_image_geometry(tag)
+ if geometry is None:
+ continue
+ x, y, width, height = geometry
+ try:
+ content = svg_path.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ viewbox = cls._parse_svg_viewbox(content)
+ if viewbox is None:
+ continue
+ vb_width, vb_height = viewbox
+ if x < 0 or y < 0 or x + width > vb_width or y + height > vb_height:
+ return True
+ return False
+
+ @classmethod
+ def _has_corner_fragment_reference(cls, refs: List[Tuple[Path, str]]) -> bool:
+ for svg_path, tag in refs:
+ geometry = cls._parse_image_geometry(tag)
+ if geometry is None:
+ continue
+ x, y, width, height = geometry
+ try:
+ content = svg_path.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ viewbox = cls._parse_svg_viewbox(content)
+ if viewbox is None:
+ continue
+ vb_width, vb_height = viewbox
+ near_left = x <= 40
+ near_top = y <= 40
+ near_right = x + width >= vb_width - 40
+ near_bottom = y + height >= vb_height - 40
+ if (near_left or near_right) and (near_top or near_bottom):
+ return True
+ return False
+
def _check_animation_config_contract(self, dir_path: Path) -> None:
"""Project-level animations.json reference checks."""
if _load_animation_config is None or _validate_animation_config is None:
@@ -1447,6 +1801,8 @@ class SVGQualityChecker:
def print_summary(self):
"""Print check summary"""
+ self._apply_aggregated_issue_counts()
+
print("=" * 80)
print("[SUMMARY] Check Summary")
print("=" * 80)
@@ -1473,6 +1829,9 @@ class SVGQualityChecker:
# Animation config aggregation.
self._print_animation_summary()
+ # Illustration strategy aggregation.
+ self._print_illustration_summary()
+
# Fix suggestions
if self.summary['errors'] > 0 or self.summary['warnings'] > 0:
print(f"\n[TIP] Common fixes:")
@@ -1488,10 +1847,6 @@ class SVGQualityChecker:
errors = [item for item in self._animation_issues if item[0] == 'error']
warnings = [item for item in self._animation_issues if item[0] == 'warning']
- self.summary['errors'] += len(errors)
- self.summary['warnings'] += len(warnings)
- for severity, _msg in self._animation_issues:
- self.issue_types[f'animation_config_{severity}'] += 1
print("\n[ANIMATION] animations.json checks")
for _severity, msg in errors:
@@ -1499,6 +1854,24 @@ class SVGQualityChecker:
for _severity, msg in warnings:
print(f" [WARN] {msg}")
+ def _print_illustration_summary(self):
+ """Print project-level illustration strategy issues if present."""
+ if not self._illustration_issues:
+ return
+
+ errors = [item for item in self._illustration_issues if item[0] == 'error']
+ warnings = [item for item in self._illustration_issues if item[0] == 'warning']
+
+ print("\n[ILLUSTRATION] Illustration strategy checks")
+ if errors:
+ print(f" Errors ({len(errors)}):")
+ for _severity, kind, msg in errors:
+ print(f" [{kind}] {msg}")
+ if warnings:
+ print(f" Warnings ({len(warnings)}):")
+ for _severity, kind, msg in warnings:
+ print(f" [{kind}] {msg}")
+
def _print_template_summary(self):
"""Aggregate template-mode roster / placeholder issues at the bottom.
@@ -1512,13 +1885,6 @@ class SVGQualityChecker:
errors = [item for item in self._template_issues if item[0] == 'error']
warnings = [item for item in self._template_issues if item[0] == 'warning']
- # Mirror into the global summary so downstream "0 errors" gates honor
- # template-mode issues.
- self.summary['errors'] += len(errors)
- self.summary['warnings'] += len(warnings)
- for severity, kind, _msg in self._template_issues:
- self.issue_types[f"template_{kind}"] += 1
-
print("\n[TEMPLATE] Template mode checks")
if errors:
print(f" Errors ({len(errors)}):")
@@ -1532,6 +1898,33 @@ class SVGQualityChecker:
print(" No structural roster issues. Placeholder hints above are advisory only;")
print(" declare 'placeholders:' frontmatter in design_spec.md to silence them.")
+ def _apply_aggregated_issue_counts(self):
+ """Mirror project-level aggregate issues into summary counters once."""
+ if self._aggregate_counts_applied:
+ return
+ self._aggregate_counts_applied = True
+
+ animation_errors = [item for item in self._animation_issues if item[0] == 'error']
+ animation_warnings = [item for item in self._animation_issues if item[0] == 'warning']
+ self.summary['errors'] += len(animation_errors)
+ self.summary['warnings'] += len(animation_warnings)
+ for severity, _msg in self._animation_issues:
+ self.issue_types[f'animation_config_{severity}'] += 1
+
+ template_errors = [item for item in self._template_issues if item[0] == 'error']
+ template_warnings = [item for item in self._template_issues if item[0] == 'warning']
+ self.summary['errors'] += len(template_errors)
+ self.summary['warnings'] += len(template_warnings)
+ for severity, kind, _msg in self._template_issues:
+ self.issue_types[f'template_{kind}_{severity}'] += 1
+
+ illustration_errors = [item for item in self._illustration_issues if item[0] == 'error']
+ illustration_warnings = [item for item in self._illustration_issues if item[0] == 'warning']
+ self.summary['errors'] += len(illustration_errors)
+ self.summary['warnings'] += len(illustration_warnings)
+ for severity, kind, _msg in self._illustration_issues:
+ self.issue_types[f'illustration_{kind}_{severity}'] += 1
+
def _print_drift_summary(self):
"""Print spec_lock drift aggregation if any was observed.
@@ -1571,7 +1964,7 @@ class SVGQualityChecker:
"""Calculate percentage"""
if self.summary['total'] == 0:
return 0
- return int(count / self.summary['total'] * 100)
+ return min(100, int(count / self.summary['total'] * 100))
def export_report(self, output_file: str = 'svg_quality_report.txt'):
"""Export check report"""
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 3c42fb93..e24e332a 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -253,10 +253,24 @@ Catalog read: 71 templates
## VIII. Image Resource List (if needed)
+### Illustration System (when `illustration_usage: use`)
+
+| Field | Decision |
+| ----- | -------- |
+| Strategy | [one or more of `hero-only` / `sparse-spots` / `recurring-motif` / `image-as-canvas`; omit this block or write `none` only when no intentional illustrations are used] |
+| Motif family | [the repeated visual family, e.g. paper objects / workflow tokens / product metaphors / cultural symbols] |
+| Reuse rule | [where and how often the motif appears; include size / edge / rotation / behind-text rules for spot illustrations] |
+| Do not use on | [page types where illustrations would weaken clarity, e.g. dense tables, charts, legal text, screenshots] |
+| Boundary | [icons label concepts; illustrations set story / mood / metaphor; charts carry data; photos prove real-world context] |
+
+> **Illustration System is a planning contract** — it does not replace the resource list below. `image_usage` still decides each row's `Acquire Via`; the strategy decides role, reuse, placement, and exclusions.
+
| Filename | Dimensions | Ratio | Purpose | Type | Layout pattern | Acquire Via | Status | Reference | text_policy | page_role |
| -------- | --------- | ----- | ------- | ---- | -------------- | ----------- | ------ | --------- | ----------- | --------- |
| cover_bg.png | {canvas_info['dimensions']} | [ratio] | Atmospheric cover backdrop — SVG title overlays the calm region | Background | #1 full-bleed background with floating title + #29 two-stop scrim | ai | Pending | [subject + intent + composition, no style/HEX] | none | hero_page |
| comparison_p07.png | {canvas_info['dimensions']} | [ratio] | Three-panel approach comparison — panel labels stay inside the image | Diagram | #44 background image + native network/architecture diagram | ai | Pending | Three side-by-side schematic motifs comparing approach A / B / C, panel labels rendered inside each motif | embedded | local |
+| spot_sheet.png | 1024×1024 | 1.00 | 2x3 same-family spot illustration sheet — generated only, never placed | Illustration Sheet | #63 transparent PNG sticker / cutout | ai | Pending | 2x3 grid of isolated spot elements with flat background for slicing | none | local |
+| spot_growth.png | TBD after slicing | TBD | P06 decorative growth spot from `spot_sheet.png` cell 1,1 | Illustration | #63 transparent PNG sticker / cutout + #58 image fragment as decorative corner element + #69 image rotated at a slight angle for editorial feel | slice | Pending | From `spot_sheet.png` cell 1,1 | | |
| formula_001.png | [actual dimensions from formula manifest / image_analysis] | [ratio] | Block equation on P03 | Latex Formula | formula-block | formula | Rendered | `E = mc^2` — energy-mass equation | | |
> **Layout pattern column is MANDATORY** — for non-formula rows, value is one or more `#<id> <name>` joined by ` + ` drawn verbatim from [`references/image-layout-patterns.md`](../references/image-layout-patterns.md) (Primary + optional Modifiers). Empty cells, paraphrased names, or invented ids invalidate the row. Formula rows are the only exception; use `formula-inline` or `formula-block`. See `strategist.md §h` GATE for the three-layer requirement (read → produce → image-as-canvas coverage).