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

fix(typography): bound sparse display-size reuse

hugohe348abc4574dbb
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index f27e27e5..1c05995f 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -96,14 +96,15 @@ Use named lock roles literally when that role applies, and use optional `Templat
- Icons may use any SVG already prepared under `<project_path>/icons/`. `icons.library` records the Strategist's primary bundled style choice and `icons.inventory` records its planned selection; neither is an execution whitelist over project-local assets.
- Core color roles retain their meaning. Derive tints, shades, alpha, gradients, and effects; preserve natural asset colors; and use sparse page-local accents for differentiation/ornament. They must not become a competing or recurring palette.
- Resolve structural families by role: exact `<role>_family` first, then `title_family` for title roles or `body_family` for other unoverridden roles, then legacy `font_family`. Never flatten declared role overrides. A sparse export-safe accent family may style short non-structural display/ornament only—never title/body/data/annotation. Recurrence requires upstream selection.
-- Font sizes use the named `typography` role values as deck-wide anchors. Map every structural or feature text item to a declared role before drawing; never inherit a template placeholder size. Start from the anchor, then use composition and content fit to adjust that occurrence by at most `±2`px. Keep same-page peers consistent and preserve the role hierarchy; bounded adjustment does not create a new role.
+- Font sizes use the named `typography` role values as deck-wide anchors. Map every structural text item to a declared role before drawing; never inherit a template placeholder size. Start from the anchor, then use composition and content fit to adjust that occurrence by at most `±2`px. Keep same-page peers consistent and preserve the role hierarchy; bounded adjustment does not create a new role.
- **Core message ≥ `body`**: map the page's primary claim to declared `lead` / `subtitle`, never below the current body treatment. Footnotes, page numbers, and credits use declared `footnote` / `annotation`; do not invent a smaller role.
-- **Write unitless px, with at most two decimals.** Use only the mapped role's anchor or a value within its `±2`px band; do not substitute familiar pt-style numbers or emit long precision tails.
-- **Outside-band recovery**: reflow geometry and use the declared role band locally. If the page needs a new semantic role, a size outside anchor `±2`px, or a hierarchy change, stop and return to Strategist to repair the Design Spec and `spec_lock.md`, then regenerate page-context. Never flatten a justified distinction or add a role merely to silence the checker. Generated `svg_output/` values outside every declared band are blocking errors; mirror pages preserve exact source typography as inherited input.
+- **Write unitless px, with at most two decimals.** Structural and mapped-role text uses only its anchor or a value within its `±2`px band; the sparse display-size exception is defined separately below. Do not substitute familiar pt-style numbers or emit long precision tails.
+- **Sparse display-size exception**: a short non-structural Hero/Display element may use one undeclared size outside all anchor bands at most twice across the deck without a lock row. The third occurrence makes that size recurring: stop and return to Strategist to name the role in the Design Spec and `spec_lock.md`, then regenerate page-context. This exception never applies to titles, body copy, subtitles, annotations, footnotes, captions, data labels, or card copy, and nearby sizes must not be introduced to imitate one recurring treatment.
+- **Outside-band recovery**: for structural text, reflow geometry and use the declared role band locally. For a sparse display occurrence, keep the unitless value and verify that its deck-wide count remains at most two. Never flatten a justified distinction or add a role merely to silence the checker. Mirror pages preserve exact source typography as inherited input.
- Images MUST reference files listed under `images`; no invented filenames
- Formula PNGs are images with `Acquire Via: formula`; place a `Rendered` file only from its listed path, use the normal placeholder for `Needs-Manual`, and never recreate the formula as text.
-Return upstream before any derived/accent identity becomes recurring or structural, or before typography needs a new semantic role or an outside-band size, then regenerate context. Local garnish and same-role `±2`px adjustments need no lock row. Never expand the lock to silence a comparison. New icon acquisition, images, structural fonts, role anchors, and resources keep their preparation/role rules.
+Return upstream before any derived/accent identity becomes recurring or structural, or when an undeclared display size reaches its third occurrence, then regenerate context. Local garnish, same-role `±2`px adjustments, and at most two sparse display-size occurrences need no lock row. Never expand the lock to silence a comparison. New icon acquisition, images, structural fonts, role anchors, and resources keep their preparation/role rules.
**Per-page layout rhythm — `page_rhythm` section**:
diff --git a/skills/ppt-master/references/executor-structured.md b/skills/ppt-master/references/executor-structured.md
index b4a9e659..771fab8c 100644
--- a/skills/ppt-master/references/executor-structured.md
+++ b/skills/ppt-master/references/executor-structured.md
@@ -34,17 +34,17 @@ Resolve the per-page template SVG from `page_context.template.prototype`; the ow
**Default — re-skin `layout` (may override when the application plan keeps template visuals and the lock reflects them)**: inherit geometry, label/legend placement, and series encoding; otherwise repaint template gradients, shadows, fills, and strokes from the current style/lock. Template font sizes remain placeholders. `mirror` preserves visuals under §1.1.
-**Font size is skin, not geometry (non-mirror).** A chart / layout template's hardcoded `font-size` values (often 11–16px, sized for the template's own dense placeholder text) are NOT inherited. Classify each text into its `spec_lock.md` role, start from that role's anchor, and keep any contextual adjustment within anchor `±2`px. The template's placeholder px never becomes the starting point or an extra role.
+**Font size is skin, not geometry (non-mirror).** A chart / layout template's hardcoded `font-size` values (often 11–16px, sized for the template's own dense placeholder text) are NOT inherited. Structural text and reusable slots start from their `spec_lock.md` role and stay within anchor `±2`px; only a qualifying Slide-local Hero/Display element follows the sparse exception in `executor-base.md`. Template placeholder px supplies neither a role anchor nor a sparse display value.
**Typography execution order (mandatory):**
1. Build a per-page text inventory from `design_spec.md §IX` + the current `notes/<NN>_*.md`.
-2. Classify each text item before drawing. **Structural and feature roles** (`title`, `subtitle` / `lead`, `body`, `annotation`, `footnote` / `page_number`, hero or emphasis slots) map to a declared `spec_lock.typography` size role. A missing semantic role returns upstream; do not borrow an unrelated size because it is numerically close.
-3. Choose the role anchor or one contextual value within anchor `±2`px before placing the text. Never start from a template `font-size` and then adjust it.
+2. Classify each text item before drawing. **Structural roles and reusable feature slots** (`title`, `subtitle` / `lead`, `body`, `annotation`, `footnote` / `page_number`, reusable hero or emphasis slots) map to a declared `spec_lock.typography` size role. A missing semantic role returns upstream; do not borrow an unrelated size because it is numerically close. Only a Slide-local, non-slot Hero/Display element may use the sparse-size exception in [`executor-base.md`](./executor-base.md); reusable Layout slots never do.
+3. For every mapped role or reusable slot, choose the role anchor or one contextual value within anchor `±2`px before placing the text. A qualifying Slide-local sparse display follows `executor-base.md` directly. Never start from a template `font-size` and then adjust it.
4. Layout from those chosen sizes: compute line-height, wrapped line count, child `y` / `dy`, card padding, card height, column gaps, and available image/chart area.
5. Reflow containers and local geometry together with the bounded role treatment; an inherited template slot never justifies leaving the declared band.
-**Geometry and bounded type co-adapt**: widen or heighten the card, open spacing, recompute child `y` / `dy`, and choose within the mapped role's anchor `±2`px instead of inheriting the template's compact size. Page count and density remain the confirmed Strategist decision: do not repaginate, split, or drop content. If the page still needs a value outside the band, return upstream under [`executor-base.md`](./executor-base.md) §2.1. Mirror instead preserves source typography under §1.1.
+**Geometry and bounded type co-adapt**: widen or heighten the card, open spacing, recompute child `y` / `dy`, and choose within the mapped role's anchor `±2`px instead of inheriting the template's compact size. Page count and density remain the confirmed Strategist decision: do not repaginate, split, or drop content. If structural text or a reusable slot still needs a value outside the band, return upstream under [`executor-base.md`](./executor-base.md) §2.1; only qualifying Slide-local display text uses its sparse exception. Mirror instead preserves source typography under §1.1.
### 1.1 Mirror reuse — literal page replacement
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index eb3a8f62..7f0dd804 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -240,7 +240,7 @@ Other canvases use the body baseline in [`canvas-formats.md`](canvas-formats.md)
| Annotation | 0.7–0.85× |
| Footnote / page number | 0.5–0.65× |
-Scan §IX before locking. Declare every recurring role, including `lead`, `footnote`, and chart annotations when used; a lead is always at least body size. Give each role one deck-wide anchor and snap derived anchors to clean even px (for body 24, a sound set is title 42, subtitle 32, lead 30, annotation 18, footnote 16). Executor may vary one occurrence within that role's anchor ±2px while preserving hierarchy and readability. A new semantic role or any size outside ±2px requires an explicit named slot; feature elements that need a larger departure are planned here rather than improvised downstream.
+Scan §IX before locking. Declare every recurring role, including `lead`, `footnote`, and chart annotations when used; a lead is always at least body size. Give each role one deck-wide anchor and snap derived anchors to clean even px (for body 24, a sound set is title 42, subtitle 32, lead 30, annotation 18, footnote 16). Executor may vary one occurrence within that role's anchor ±2px while preserving hierarchy and readability. A short non-structural Hero/Display size planned for at most two occurrences may remain undeclared; the third planned occurrence makes it recurring and requires an explicit named slot. Structural text never uses this sparse exception.
#### Formula Planning Trigger
Formula policy and formula-asset planning are conditional. If the source contains formula-worthy expressions, or the user explicitly requests formula handling, read [`strategist-image.md`](./strategist-image.md) §3 before confirming the production policy or writing formula rows. Load it even when `image_usage` is `none`; otherwise omit formula planning from the core path.
@@ -413,7 +413,7 @@ Generate Step 4 owns this reference-first sequence. `design_spec.md` is the Stra
⛔ **GATE 2 — lock context fidelity.** After the Design Spec passes Gate 1, author its machine-relevant execution anchors and routing values into `spec_lock.md`. The lock may normalize syntax and add named recurring implementation roles justified by the Design Spec/page plan, but it must not change confirmed identity or introduce a competing direction. It is intentionally not a field-for-field copy and not a whitelist of every legal SVG value. If authoring exposes a contradiction or missing confirmed decision, return to Gate 1 and repair the Design Spec from the retained final-confirmation state; on a fresh recovery turn only, read the persisted final result once to restore that state.
-**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography role and any planned feature role that needs to leave another role's ±2px band; never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, pattern, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor rebuilds page projection before every page ([executor-base.md](executor-base.md) §2.1). Repair the Design Spec only from retained final confirmation, then re-author affected lock rows.
+**Execution lock content**: `spec_lock.md` compactly carries communication, stable color/type anchors, icons, images, page rhythm, chart choices, and route-specific PowerPoint structure. Name every recurring typography role; a planned short non-structural Hero/Display size may stay omitted only while the same value appears at most twice, and its third occurrence requires a named role. Never re-derive a confirmed anchor. New locks keep `font_family` as the body/default compatibility stack and also write explicit `title_family` + `body_family`; every additional recurring Design Spec role projects to `<role>_family`. Collapsing distinct Design Spec stacks into `font_family`, or dropping an extra role, fails Gate 2. Keep core fonts/palette roles stable; page authoring varies treatment and may add sparse local garnish. Project every placed §VIII image's source, pattern, and crop policy; omit unplaced sheets and planning provenance. Free-design, brand-only, and `template_reuse_scope: style` use `pptx_structure.mode: flat`; the template module owns structured mappings. Executor rebuilds page projection before every page ([executor-base.md](executor-base.md) §2.1). Repair the Design Spec only from retained final confirmation, then re-author affected lock rows.
**Contextual extension**: derived paint or sparse local font/color garnish may stay in one SVG while non-structural and non-recurring. New base/semantic colors, structural/recurring fonts, resources, or patterns require upstream repair; Executor never reverse-projects a choice as fact. Promote garnish upstream before reuse, regenerate page-context, and never add values to silence a comparison.
diff --git a/skills/ppt-master/scripts/project_specs.py b/skills/ppt-master/scripts/project_specs.py
index 5fa27f35..3bfa521c 100644
--- a/skills/ppt-master/scripts/project_specs.py
+++ b/skills/ppt-master/scripts/project_specs.py
@@ -19,6 +19,7 @@ Dependencies:
from __future__ import annotations
import json
+import math
import re
from pathlib import Path
from typing import Mapping
@@ -426,6 +427,38 @@ def _validate_section(
f"'{field_name}' does not match '{pattern}'"
)
+ field_value_rules = definition.get("field_value_rules", [])
+ if isinstance(field_value_rules, list):
+ for rule in field_value_rules:
+ if not isinstance(rule, dict):
+ continue
+ key_pattern = rule.get("key_pattern")
+ value_pattern = rule.get("value_pattern")
+ if not isinstance(key_pattern, str) or not isinstance(
+ value_pattern, str
+ ):
+ continue
+ requirement = str(rule.get("requirement", "match its value grammar"))
+ for field_name, raw_value in fields.items():
+ if re.fullmatch(key_pattern, str(field_name)) is None:
+ continue
+ value = str(raw_value).strip()
+ if bool(rule.get("normalize", True)):
+ value = _normalize_schema_value(value)
+ value_matches = re.fullmatch(value_pattern, value) is not None
+ if value_matches and rule.get("numeric") == "positive_finite":
+ try:
+ number = float(value)
+ except ValueError:
+ value_matches = False
+ else:
+ value_matches = math.isfinite(number) and number > 0
+ if not value_matches:
+ errors.append(
+ f"{markdown_name} schema: section '{section_id}' field "
+ f"'{field_name}' must {requirement}; found '{value}'"
+ )
+
minimum = definition.get("min_entries")
if isinstance(minimum, int) and len(fields) < minimum:
errors.append(
diff --git a/skills/ppt-master/scripts/prompt_audit_manifest.json b/skills/ppt-master/scripts/prompt_audit_manifest.json
index 93fb3f4e..c2a5b7ce 100644
--- a/skills/ppt-master/scripts/prompt_audit_manifest.json
+++ b/skills/ppt-master/scripts/prompt_audit_manifest.json
@@ -17,7 +17,7 @@
"file_budgets": {
"AGENTS.md": 2350,
"skills/ppt-master/SKILL.md": 800,
- "skills/ppt-master/references/executor-base.md": 7150,
+ "skills/ppt-master/references/executor-base.md": 7250,
"skills/ppt-master/references/executor-structured.md": 5300,
"skills/ppt-master/references/executor-chart.md": 3100,
"skills/ppt-master/references/executor-image.md": 900,
@@ -28,11 +28,11 @@
"skills/ppt-master/references/svg-effects.md": 11600,
"skills/ppt-master/references/native-data-interface.md": 6200,
"skills/ppt-master/references/pptx-structure-interface.md": 4300,
- "skills/ppt-master/references/strategist.md": 13400,
+ "skills/ppt-master/references/strategist.md": 13450,
"skills/ppt-master/references/strategist-image.md": 2100,
"skills/ppt-master/references/strategist-template.md": 2100,
"skills/ppt-master/templates/design_spec_reference.md": 2750,
- "skills/ppt-master/templates/spec_lock_reference.md": 2250,
+ "skills/ppt-master/templates/spec_lock_reference.md": 2350,
"skills/ppt-master/workflows/generate-pptx.md": 12450,
"skills/ppt-master/workflows/stages/apply-template-workspace.md": 1800
},
@@ -306,7 +306,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 81800
+ "max_tokens": 82000
},
"route.generate.flat-ai-two-types": {
"description": "Generate-PPTX context with AI images, representative multi-source custom rendering, and two local types.",
@@ -319,7 +319,7 @@
"stage.generate.image.ai-two-types"
],
"files": [],
- "max_tokens": 122000
+ "max_tokens": 122200
},
"route.generate.flat-in-hand-image": {
"description": "Generate-PPTX context with provided, placeholder, or formula images and no acquisition role.",
@@ -331,7 +331,7 @@
"stage.generate.executor.notes"
],
"files": [],
- "max_tokens": 95300
+ "max_tokens": 95500
},
"route.generate.flat-web-image": {
"description": "Generate-PPTX context with web image acquisition.",
@@ -344,7 +344,7 @@
"stage.generate.image.web"
],
"files": [],
- "max_tokens": 102500
+ "max_tokens": 102700
},
"route.enhance-native-pptx.audio": {
"description": "Enhance Native PPTX with the shared narration-audio stage.",
@@ -364,7 +364,7 @@
"profile.generate.beautify-pptx"
],
"files": [],
- "max_tokens": 88600
+ "max_tokens": 88900
},
"route.generate.flat-no-image-chart": {
"description": "Default flat Generate-PPTX path with chart authoring, native-data replacement, and verification.",
@@ -377,7 +377,7 @@
"stage.generate.verify-charts"
],
"files": [],
- "max_tokens": 105800
+ "max_tokens": 106000
},
"route.generate.brand-flat-no-image": {
"description": "Brand-preset flat Generate-PPTX path without image acquisition.",
@@ -389,7 +389,7 @@
"stage.generate.template.brand"
],
"files": [],
- "max_tokens": 88800
+ "max_tokens": 89000
},
"route.generate.deck-structured-no-image": {
"description": "Deck-preset structured Generate-PPTX path without image acquisition.",
@@ -401,7 +401,7 @@
"stage.generate.template.deck"
],
"files": [],
- "max_tokens": 98600
+ "max_tokens": 98900
},
"route.generate.layout-structured-no-image": {
"description": "Layout-preset structured Generate-PPTX path without image acquisition.",
@@ -413,7 +413,7 @@
"stage.generate.template.layout"
],
"files": [],
- "max_tokens": 99100
+ "max_tokens": 99400
},
"route.generate.topic-only-flat-no-image": {
"description": "Topic research followed by the default flat no-image Generate-PPTX path.",
@@ -423,7 +423,7 @@
"route.generate.flat-no-image"
],
"files": [],
- "max_tokens": 83200
+ "max_tokens": 83400
},
"stage.generate.executor.flat": {
"description": "Incremental flat Executor core with representative multi-source custom mode/style execution.",
@@ -533,7 +533,7 @@
"stage.generate.executor.image"
],
"files": [],
- "max_tokens": 58500
+ "max_tokens": 58600
},
"stage.generate.topic-research": {
"description": "Gap-targeted factual intake stage.",
@@ -661,7 +661,7 @@
"stage.generate.strategist.template"
],
"files": [],
- "max_tokens": 59700
+ "max_tokens": 59800
},
"route.generate.planning-template-ai": {
"description": "Explicit template workspace plus confirmed AI-image planning.",
@@ -671,7 +671,7 @@
"route.generate.planning-ai"
],
"files": [],
- "max_tokens": 71800
+ "max_tokens": 72000
},
"stage.generate.executor.chart": {
"description": "Conditional chart/table page execution rules.",
diff --git a/skills/ppt-master/scripts/svg_quality_checker.py b/skills/ppt-master/scripts/svg_quality_checker.py
index e26eb4e3..b3bf880b 100644
--- a/skills/ppt-master/scripts/svg_quality_checker.py
+++ b/skills/ppt-master/scripts/svg_quality_checker.py
@@ -889,6 +889,7 @@ PPT_SAFE_FONTS = {
# is prompt-owned; Checker only verifies that a used value is close to at least
# one declared size anchor.
FONT_SIZE_ANCHOR_TOLERANCE_PX = 2.0
+SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES = 2
# Oversampling alone does not imply distortion and is often harmless for small
# logos. Warn about downscaling only when the source also has material on-disk
@@ -1160,6 +1161,8 @@ class SVGQualityChecker:
'fonts': defaultdict(set),
'sizes': defaultdict(set),
}
+ self._undeclared_size_occurrences: Counter[str] = Counter()
+ self._undeclared_size_counts_ready = False
self._lock_seen = False # True once we locate at least one spec_lock.md
self._source_manifest_cache: Dict[Path, Dict] = {}
# Template-mode aggregation (populated by check_directory when
@@ -1370,10 +1373,10 @@ class SVGQualityChecker:
self._check_semantic_markers(root, svg_path, result)
# 9. Compare values with spec_lock anchors. Additional colors
- # and fonts are informational. Generated-page type sizes
- # outside every role band are errors; other spec-backed SVG
- # locations retain advisory review. Templates do not ship a
- # spec_lock.md, so skip in template mode to avoid noise.
+ # and fonts are informational. Generated-page type sizes may
+ # stay sparse twice; the third occurrence is an error. Other
+ # spec-backed SVG locations retain advisory review. Templates
+ # do not ship a spec_lock.md, so skip in template mode.
if not self.template_mode:
self._check_spec_lock_alignment(
content,
@@ -4779,7 +4782,8 @@ class SVGQualityChecker:
self,
) -> Tuple[set[str], set[str], set[str]]:
"""Return color/font/size values owned by the selected mirror page."""
- if self._active_prototype_root() is None:
+ prototype_root = self._active_prototype_root()
+ if prototype_root is None:
return set(), set(), set()
try:
content = self._active_prototype_path.read_text(encoding='utf-8')
@@ -4805,13 +4809,180 @@ class SVGQualityChecker:
for value in self._font_family_values(content)
if self._normalize_font_stack(value)
}
- sizes = {
- self._normalize_size(value)
- for value in self._svg_property_values(content, 'font-size')
- if self._normalize_size(value)
- }
+ sizes = set(self._effective_text_size_counts(prototype_root))
return colors, fonts, sizes
+ def _declared_typography_size_anchors(
+ self,
+ lock: Dict,
+ ) -> Tuple[Dict, set[str], List[float], List[str]]:
+ """Return valid declared size anchors and malformed lock rows."""
+ typography = lock.get('typography', {})
+ positive_numeric_re = re.compile(
+ r'^(?=.*[1-9])(?:[0-9]+(?:\.[0-9]+)?|\.[0-9]+)$'
+ )
+ locked_sizes: set[str] = set()
+ anchor_sizes: List[float] = []
+ invalid_sizes: List[str] = []
+ for key, raw_value in typography.items():
+ if key == 'font_family' or key.endswith('_family'):
+ continue
+ value = raw_value.strip()
+ if positive_numeric_re.fullmatch(value) is None:
+ invalid_sizes.append(f"{key}: {raw_value}")
+ continue
+ try:
+ anchor = float(value)
+ except (TypeError, ValueError):
+ invalid_sizes.append(f"{key}: {raw_value}")
+ continue
+ if not math.isfinite(anchor) or anchor <= 0:
+ invalid_sizes.append(f"{key}: {raw_value}")
+ continue
+ locked_sizes.add(self._canonical_font_size_key(anchor))
+ anchor_sizes.append(anchor)
+ return typography, locked_sizes, anchor_sizes, invalid_sizes
+
+ def _count_undeclared_size_occurrences(
+ self,
+ root: ET.Element,
+ *,
+ locked_sizes: set[str],
+ anchor_sizes: List[float],
+ prototype_sizes: set[str],
+ ) -> Counter[str]:
+ """Count text objects using valid sizes outside all declared bands."""
+ counts: Counter[str] = Counter()
+ if not locked_sizes:
+ return counts
+ for value, occurrence_count in self._effective_text_size_counts(root).items():
+ if value in prototype_sizes and value not in locked_sizes:
+ continue
+ if value in locked_sizes:
+ continue
+ try:
+ used_px = float(value)
+ except (TypeError, ValueError):
+ continue
+ if not math.isfinite(used_px) or used_px < 0:
+ continue
+ if any(
+ abs(used_px - anchor_px) <= FONT_SIZE_ANCHOR_TOLERANCE_PX
+ for anchor_px in anchor_sizes
+ ):
+ continue
+ counts[value] += occurrence_count
+ return counts
+
+ def _effective_text_size_counts(self, root: ET.Element) -> Counter[str]:
+ """Count each effective size once per non-empty SVG text object."""
+ counts: Counter[str] = Counter()
+ if _resolve_project_font_sizes is None:
+ return counts
+ working_root = root
+ if (
+ _expand_local_use_references is not None
+ and _UseExpansionError is not None
+ ):
+ expanded_root = copy.deepcopy(root)
+ try:
+ _expand_local_use_references(expanded_root)
+ except _UseExpansionError:
+ pass
+ else:
+ working_root = expanded_root
+ try:
+ effective_sizes = _resolve_project_font_sizes(working_root)
+ except ValueError:
+ return counts
+
+ def collect_text_object_sizes(element: ET.Element) -> set[str]:
+ values: set[str] = set()
+
+ def visit(node: ET.Element) -> None:
+ if (node.text or '').strip():
+ values.add(
+ self._canonical_font_size_key(effective_sizes[id(node)])
+ )
+ for child in node:
+ visit(child)
+ if (child.tail or '').strip():
+ values.add(
+ self._canonical_font_size_key(
+ effective_sizes[id(node)]
+ )
+ )
+
+ visit(element)
+ return values
+
+ definition_containers = {
+ 'clippath',
+ 'defs',
+ 'marker',
+ 'mask',
+ 'pattern',
+ 'symbol',
+ }
+
+ def visit_visible(element: ET.Element) -> None:
+ local_name = _local_name(element).casefold()
+ if local_name in definition_containers:
+ return
+ if local_name == 'text':
+ counts.update(collect_text_object_sizes(element))
+ return
+ for child in element:
+ visit_visible(child)
+
+ visit_visible(working_root)
+ return counts
+
+ @staticmethod
+ def _canonical_font_size_key(value: float) -> str:
+ """Canonicalize equivalent numeric spellings for deck-wide counting."""
+ return format(value, '.12g')
+
+ def _prepare_undeclared_size_occurrences(
+ self,
+ svg_files: List[Path],
+ ) -> None:
+ """Pre-count sparse undeclared sizes before per-file diagnostics."""
+ previous_prototype = self._active_prototype_path
+ try:
+ for svg_path in svg_files:
+ lock = self._get_spec_lock(svg_path)
+ if lock is None:
+ continue
+ _typography, locked_sizes, anchor_sizes, _invalid = (
+ self._declared_typography_size_anchors(lock)
+ )
+ self._active_prototype_path = self._prototype_by_output.get(
+ svg_path.resolve()
+ )
+ _colors, _fonts, prototype_sizes = (
+ self._prototype_drift_allowances()
+ )
+ try:
+ content = svg_path.read_text(encoding='utf-8')
+ except OSError:
+ continue
+ try:
+ root = ET.fromstring(content)
+ except ET.ParseError:
+ continue
+ self._undeclared_size_occurrences.update(
+ self._count_undeclared_size_occurrences(
+ root,
+ locked_sizes=locked_sizes,
+ anchor_sizes=anchor_sizes,
+ prototype_sizes=prototype_sizes,
+ )
+ )
+ finally:
+ self._active_prototype_path = previous_prototype
+ self._undeclared_size_counts_ready = True
+
def _check_spec_lock_alignment(
self,
content: str,
@@ -4825,12 +4996,13 @@ class SVGQualityChecker:
Covers colors (fill / stroke / stop-color / flood-color / pattern
metadata), font-family, and font-size.
Additional colors and font families are valid contextual authoring and
- are recorded as information. Font sizes outside every declared role
- anchor's ±2px band are errors in generated ``svg_output`` pages and
- warnings in other spec-backed SVG locations. Exact mirror-prototype
- values remain inherited information. Exact values are accumulated in
- self._anchor_value_summary for the end-of-run aggregation. When
- spec_lock.md is missing, silently skip this local comparison; the
+ are recorded as information. A valid undeclared display size may occur
+ at most twice across generated pages; its third occurrence makes it a
+ recurring role and blocks ``svg_output`` until the role is declared.
+ Structural text still maps to declared role bands. Exact mirror-
+ prototype values remain inherited information. Exact values are
+ accumulated in self._anchor_value_summary for end-of-run aggregation.
+ When spec_lock.md is missing, silently skip this local comparison; the
Generate route's required-artifact gate owns whether execution may begin.
"""
lock = self._get_spec_lock(svg_path)
@@ -4879,20 +5051,15 @@ class SVGQualityChecker:
locked_colors = set(allowed_colors)
allowed_colors.update(prototype_colors)
- typo = lock.get('typography', {})
- numeric_size_re = re.compile(r'^(?:\d+(?:\.\d+)?|\.\d+)$')
- invalid_lock_sizes = []
- for k, v in typo.items():
- if k == 'font_family' or k.endswith('_family'):
- continue
- if not numeric_size_re.fullmatch(v.strip()):
- invalid_lock_sizes.append(f"{k}: {v}")
+ typo, locked_sizes, anchor_sizes, invalid_lock_sizes = (
+ self._declared_typography_size_anchors(lock)
+ )
if invalid_lock_sizes:
shown = ', '.join(invalid_lock_sizes[:5])
more = len(invalid_lock_sizes) - 5
suffix = f" (+{more} more)" if more > 0 else ""
result['errors'].append(
- f"spec_lock typography sizes must be unitless numeric px values; "
+ f"spec_lock typography sizes must be positive finite unitless px values; "
f"found {shown}{suffix}."
)
@@ -4919,20 +5086,6 @@ class SVGQualityChecker:
# Sizes: declared slots are anchors. Checker cannot infer which role a
# text node carries, so it uses the union of their ±2px bands as a cheap
# numeric safety net; prompt rules own semantic role mapping.
- allowed_sizes = set()
- anchor_sizes = []
- for k, v in typo.items():
- if k == 'font_family' or k.endswith('_family'):
- continue
- normalized_size = self._normalize_size(v)
- allowed_sizes.add(normalized_size)
- try:
- anchor_sizes.append(float(normalized_size))
- except (ValueError, TypeError):
- pass
- locked_sizes = set(allowed_sizes)
- allowed_sizes.update(prototype_sizes)
-
# Scan SVG for used values
color_drifts = set()
inherited_colors = set()
@@ -4970,26 +5123,17 @@ class SVGQualityChecker:
):
inherited_fonts.add(val)
- size_drifts = set()
+ size_drift_counts = self._count_undeclared_size_occurrences(
+ root,
+ locked_sizes=locked_sizes,
+ anchor_sizes=anchor_sizes,
+ prototype_sizes=prototype_sizes,
+ )
+ size_drifts = set(size_drift_counts)
inherited_sizes = set()
- for raw_value in self._svg_property_values(content, 'font-size'):
- val = self._normalize_size(raw_value)
+ for val in self._effective_text_size_counts(root):
if val in prototype_sizes and val not in locked_sizes:
inherited_sizes.add(val)
- continue
- if not allowed_sizes or val in allowed_sizes:
- continue
- try:
- used_px = float(val)
- except (TypeError, ValueError):
- size_drifts.add(val)
- continue
- if any(
- abs(used_px - anchor_px) <= FONT_SIZE_ANCHOR_TOLERANCE_PX
- for anchor_px in anchor_sizes
- ):
- continue
- size_drifts.add(val)
# Record in run-wide aggregation. Colors/fonts beyond the anchor set are
# contextual values, not release issues. Generated-page sizes enforce
@@ -5010,22 +5154,45 @@ class SVGQualityChecker:
if contextual_values:
result['info']['contextual_values'] = contextual_values
- if size_drifts:
+ sparse_sizes = {}
+ recurring_sizes = {}
+ for value, local_count in size_drift_counts.items():
+ total_count = (
+ self._undeclared_size_occurrences.get(value, local_count)
+ if self._undeclared_size_counts_ready
+ else local_count
+ )
+ target = (
+ sparse_sizes
+ if total_count <= SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES
+ else recurring_sizes
+ )
+ target[value] = total_count
+
+ if sparse_sizes:
+ result['info']['sparse_typography_sizes'] = {
+ value: count for value, count in sorted(sparse_sizes.items())
+ }
+
+ if recurring_sizes:
+ shown = ', '.join(
+ f"{value} ({count} occurrences)"
+ for value, count in sorted(recurring_sizes.items())
+ )
size_issue = (
- f"{len(size_drifts)} font-size value(s) fall outside ±2px of "
- "every declared spec_lock role anchor (see anchor comparison "
- "summary)"
+ f"undeclared font-size {shown} exceeds the sparse-display limit "
+ f"of {SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES} occurrences"
)
if svg_path.parent.name == 'svg_output':
result['errors'].append(
- "spec_lock typography-size violation: "
- f"{size_issue}. Reflow within a declared role band or repair "
- "the Design Spec and spec_lock with a justified named role; "
- "do not add a role only to silence the checker."
+ "spec_lock typography-size recurrence: "
+ f"{size_issue}. Structural text must return to its declared "
+ "role band; a genuinely recurring display treatment needs a "
+ "justified named role in the Design Spec and spec_lock."
)
else:
result['warnings'].append(
- f"spec_lock typography-size review: {size_issue}"
+ f"spec_lock typography-size recurrence review: {size_issue}"
)
inherited_parts = []
if inherited_colors:
@@ -5223,6 +5390,8 @@ class SVGQualityChecker:
"""
dir_path = Path(directory)
self._has_incomplete_page_roster = False
+ self._undeclared_size_occurrences = Counter()
+ self._undeclared_size_counts_ready = False
if not dir_path.exists():
print(f"[ERROR] Directory does not exist: {directory}")
@@ -5294,6 +5463,8 @@ class SVGQualityChecker:
return []
self._configure_prototype_context(dir_path, svg_files)
+ if not self.template_mode:
+ self._prepare_undeclared_size_occurrences(svg_files)
directory_expected_viewbox: str | None = None
directory_expected_label = "the first SVG canvas"
@@ -6765,8 +6936,8 @@ class SVGQualityChecker:
self._anchor_value_summary[category]
for category in ('colors', 'fonts')
)
- has_size_issues = bool(self._anchor_value_summary['sizes'])
- if not has_contextual and not has_size_issues:
+ has_undeclared_sizes = bool(self._anchor_value_summary['sizes'])
+ if not has_contextual and not has_undeclared_sizes:
print(
"\n[OK] spec_lock anchor comparison: no additional contextual "
"colors/fonts or out-of-band font sizes"
@@ -6797,19 +6968,31 @@ class SVGQualityChecker:
"recurring named semantic role."
)
- if has_size_issues:
+ if has_undeclared_sizes:
print(
"\nTypography sizes outside every declared role anchor ±2px "
- "(blocking in generated svg_output; advisory elsewhere):"
+ "(up to 2 occurrences are sparse; the 3rd is recurring):"
)
entries = sorted(
self._anchor_value_summary['sizes'].items(),
key=lambda item: (-len(item[1]), item[0]),
)
for val, files in entries:
- count = len(files)
- suffix = "file" if count == 1 else "files"
- print(f" {val} ({count} {suffix})")
+ occurrences = self._undeclared_size_occurrences.get(
+ val,
+ len(files),
+ )
+ file_count = len(files)
+ file_suffix = "file" if file_count == 1 else "files"
+ policy = (
+ "sparse"
+ if occurrences <= SPARSE_UNDECLARED_FONT_SIZE_MAX_OCCURRENCES
+ else "recurring — declare a role"
+ )
+ print(
+ f" {val} ({occurrences} occurrences in {file_count} "
+ f"{file_suffix}; {policy})"
+ )
def _percentage(self, count: int) -> int:
"""Calculate percentage"""
@@ -6919,8 +7102,8 @@ class SVGQualityChecker:
introduced.append(item)
# Keep the legacy `drift` JSON field for report compatibility. Its
- # colors/fonts entries are informational anchor comparisons; size
- # entries produce errors for generated pages and warnings elsewhere.
+ # colors/fonts entries are informational anchor comparisons; sparse
+ # size entries are informational until their third occurrence.
drift = {
category: {
value: sorted(files)
diff --git a/skills/ppt-master/templates/design_spec_reference.md b/skills/ppt-master/templates/design_spec_reference.md
index 74cfdb9c..edb3a9f8 100644
--- a/skills/ppt-master/templates/design_spec_reference.md
+++ b/skills/ppt-master/templates/design_spec_reference.md
@@ -133,7 +133,7 @@ Use these exact subsections and field shapes:
| --- | --- | --- |
```
-Preserve the confirmed Title/Body system, then add every Strategist-established recurring family override justified by the completed page plan. Append the same semantic role to the Font Plan table and add `- **<Role> stack**: <complete ordered stack>`. Typical optional roles include `Annotation`, `Footer`, `Footnote`, `Data`, `Emphasis`, `Quote`, and `Code`; add only roles that recur and intentionally differ. `Role rationale` records the decision but does not itself become a lock field. Do not collapse distinct Title/Body stacks or discard a declared optional role. Treat every Font Size Hierarchy value as a role anchor: Executor may adjust one occurrence within anchor `±2px`, but a new semantic role or any planned feature outside that band needs its own row. Add every recurring palette role and typography-size anchor established by the plan; do not enumerate one-off paint or font-family garnish. For confirmed custom directions, add the applicable `Mode References`, `Mode Behavior`, `Visual Style References`, and `Visual Style Behavior` lines under Theme Style. Include `Stroke Width` under §VI only for a stroke library. `simple-icons` may accompany the one primary bundled library and is recorded only when real brand marks were selected. The icon table records planned usage, but user-provided, template-carried, imported, custom, and other prepared SVGs under the project `icons/` directory remain usable without being forced into that stylistic selection. Leave the §VI table empty when no icons are used.
+Preserve the confirmed Title/Body system, then add every Strategist-established recurring family override justified by the completed page plan. Append the same semantic role to the Font Plan table and add `- **<Role> stack**: <complete ordered stack>`. Typical optional roles include `Annotation`, `Footer`, `Footnote`, `Data`, `Emphasis`, `Quote`, and `Code`; add only roles that recur and intentionally differ. `Role rationale` records the decision but does not itself become a lock field. Do not collapse distinct Title/Body stacks or discard a declared optional role. Treat every Font Size Hierarchy value as a role anchor: Executor may adjust one occurrence within anchor `±2px`; a short non-structural Hero/Display size may stay unlisted only while the same value is planned at most twice, and its third occurrence needs a named row. Add every recurring palette role and typography-size anchor established by the plan; do not enumerate one-off paint or font-family garnish. For confirmed custom directions, add the applicable `Mode References`, `Mode Behavior`, `Visual Style References`, and `Visual Style Behavior` lines under Theme Style. Include `Stroke Width` under §VI only for a stroke library. `simple-icons` may accompany the one primary bundled library and is recorded only when real brand marks were selected. The icon table records planned usage, but user-provided, template-carried, imported, custom, and other prepared SVGs under the project `icons/` directory remain usable without being forced into that stylistic selection. Leave the §VI table empty when no icons are used.
When §VIII contains any `Acquire Via: ai` row, add this subsection under §III and preserve the complete confirmed AI direction:
diff --git a/skills/ppt-master/templates/schemas/spec_lock.schema.json b/skills/ppt-master/templates/schemas/spec_lock.schema.json
index 2d5ba71a..9f6cb4aa 100644
--- a/skills/ppt-master/templates/schemas/spec_lock.schema.json
+++ b/skills/ppt-master/templates/schemas/spec_lock.schema.json
@@ -140,21 +140,21 @@
"pattern": "^typography$",
"required": true,
"required_fields": ["font_family", "body", "title"],
- "field_patterns": {
- "font_family": "^\\S(?:.*\\S)?$",
- "title_family": "^\\S(?:.*\\S)?$",
- "body_family": "^\\S(?:.*\\S)?$",
- "subtitle_family": "^\\S(?:.*\\S)?$",
- "annotation_family": "^\\S(?:.*\\S)?$",
- "footer_family": "^\\S(?:.*\\S)?$",
- "footnote_family": "^\\S(?:.*\\S)?$",
- "data_family": "^\\S(?:.*\\S)?$",
- "emphasis_family": "^\\S(?:.*\\S)?$",
- "quote_family": "^\\S(?:.*\\S)?$",
- "code_family": "^\\S(?:.*\\S)?$",
- "body": "^[0-9]+(?:\\.[0-9]+)?$",
- "title": "^[0-9]+(?:\\.[0-9]+)?$"
- }
+ "entry_key_pattern": "^[a-z][a-z0-9_]*$",
+ "field_value_rules": [
+ {
+ "key_pattern": "^(?:font_family|[a-z][a-z0-9_]*_family)$",
+ "value_pattern": "^\\S(?:.*\\S)?$",
+ "requirement": "be a non-empty font-family stack"
+ },
+ {
+ "key_pattern": "^(?!font_family$)(?![a-z][a-z0-9_]*_family$)[a-z][a-z0-9_]*$",
+ "value_pattern": "^(?=.*[1-9])(?:[0-9]+(?:\\.[0-9]+)?|\\.[0-9]+)$",
+ "normalize": false,
+ "numeric": "positive_finite",
+ "requirement": "be a positive finite unitless px number"
+ }
+ ]
},
{
"id": "icons",
diff --git a/skills/ppt-master/templates/spec_lock_reference.md b/skills/ppt-master/templates/spec_lock_reference.md
index 7cdb8019..4bff6dd0 100644
--- a/skills/ppt-master/templates/spec_lock_reference.md
+++ b/skills/ppt-master/templates/spec_lock_reference.md
@@ -81,14 +81,14 @@ Typography projection is role-for-role, not a lossy summary:
| Any additional recurring font role `<role>` | `<role>_family` |
| Every Font Size Hierarchy role `<role>` | lowercase `<role>` with its numeric anchor |
-New locks always write `title_family` and `body_family`, even when their values happen to match. Every additional recurring family row and every size-anchor row in the Design Spec must appear under the same lowercase snake_case role; omit only family roles that inherit without an explicit override. Existing locks without family-role fields remain readable through `font_family` fallback. Executor may choose the anchor or a value within that role's `±2px` band; the lock does not enumerate intermediate values.
+New locks always write `title_family` and `body_family`, even when their values happen to match. Every additional recurring family row and every size-anchor row in the Design Spec must appear under the same lowercase snake_case role; omit only family roles that inherit without an explicit override. Existing locks without family-role fields remain readable through `font_family` fallback. Executor may choose the anchor or a value within that role's `±2px` band; the lock does not enumerate intermediate values. A short non-structural Hero/Display size may remain absent only while the same undeclared value appears at most twice across the deck; its third occurrence requires a named role.
---
## 4. Field Grammar Index
- `font_family`, `title_family`, `body_family`, and every optional `<role>_family` use one non-empty PPT-safe exported family stack. `font_family` is the body/default compatibility stack, not permission to erase role differences.
-- Every non-family `typography` value is a positive unitless px anchor. Intermediate values need no lock row when they stay within the mapped role's anchor `±2px`; a new semantic role or an outside-band size requires Design Spec repair and a new anchor.
+- Every non-family `typography` value is a positive finite unitless px anchor. Intermediate values need no lock row when they stay within the mapped role's anchor `±2px`. At most two occurrences of one undeclared short non-structural Hero/Display size may remain sparse; a third occurrence or any structural use requires Design Spec repair and a named anchor.
- `icons.library` records the primary stylistic library selected from `chunk-filled`, `tabler-filled`, `tabler-outline`, or `phosphor-duotone`, or `none` when no generic bundled icons are selected. Selected `simple-icons/*` brand marks may appear alone or alongside it in `inventory` without becoming a stylistic library. The inventory records planned bundled choices, while every SVG already under `<project_path>/icons/` remains valid prepared execution material.
- `objective` grammar: one concise sentence preserving the deck goal and audience success condition.
- `image_rendering` grammar: one catalog id, or `custom` with `image_rendering_behavior`.
@@ -128,5 +128,5 @@ Field meaning and selection logic stay in the owning Strategist modules. Executo
- Confirmed core palette roles and every declared typography family/size role remain stable cross-page anchors.
- Page-local tints, gradient stops, shadow/glow paints, transparency composites, and one-off export-safe display families may be authored from context without adding a lock row.
- Executor may adjust one occurrence within its declared size role's anchor `±2px` while preserving hierarchy and readability; intermediate values are realization choices, not new lock rows.
-- When a contextual value becomes a recurring semantic role, or typography needs a value outside every applicable anchor band, add the descriptive color/family/size role and regenerate page-context before later pages use it.
+- When a contextual value becomes a recurring semantic role, or one undeclared display size reaches its third occurrence, add the descriptive color/family/size role and regenerate page-context before later pages use it. Structural typography outside its applicable anchor band returns upstream immediately.
- Do not expand the lock merely to make an informational checker comparison empty. A lock edit should express reuse or identity, not enumerate incidental literals.