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(native-shapes): add semantic preset discovery
hugohe39c11cb9148f9
diff --git a/skills/ppt-master/references/native-shape-authoring.md b/skills/ppt-master/references/native-shape-authoring.mdindex 2c33258d..f99d4901 100644--- a/skills/ppt-master/references/native-shape-authoring.md+++ b/skills/ppt-master/references/native-shape-authoring.md@@ -12,20 +12,26 @@ only when those constructions fail. Neither helper writes a page. The presethelper does not create the shape's own `p:txBody`; keep visible text outside theatomic fragment.-**Mandatory — complete registry discovery at authoring entry**: before the+**Mandatory — semantic registry discovery at authoring entry**: before thefirst newly authored page or template contour in each valid context, run the-following command unfiltered and retain its complete output (currently 187-names). This is authoring-time capability discovery, never a Strategist task or-Design Spec field. Rerun only after context invalidation or a registry change.+following command unfiltered and retain its complete output. It organizes all+187 presets by the official Office gallery categories, then adds semantic+groups, scopes, and one-line intent summaries. This compact index is+authoring-time capability discovery, never a Strategist task or Design Spec+field. Rerun only after context invalidation or a registry change.```bash-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list --grouped```-Choose from that full inventory by page job. Use `list --search` only to narrow-the already-read inventory and `describe <name>` only after identifying a-candidate; neither replaces the complete initial read. Discovery is prerequisite;-each page consumes it through §§1–2.1 without a quota.+The plain `list` command remains a compatibility view of exact registry names;+it does not replace grouped discovery. For each page, run `recommend` from the+actual page role and applicable relationship, direction, aspect, text capacity,+scope, or intent terms, then run `describe <name>` on the serious candidates.+Those page-local commands supply the full match reasons, intended uses, and+misuse boundaries omitted from the compact entry index. Recommendation is+diverse candidate recall, not a whitelist, automatic choice, or shape quota.+Each page still resolves the final contour through §§1–2.1.## 1. Contour Selection and Materialization Gate@@ -82,36 +88,48 @@ objects or their composition.----## 2. Semantic Preset Candidate Guide+## 2. Semantic Preset Selection-Use this table as navigation, not a shortlist. Match intent against the loaded-inventory before selecting a neutral primitive or freeform; examples, style,-and syntax never hide a more specific contour. Style composition examples-remain vocabulary, not a menu.+The catalog's top level follows the Office gallery taxonomy: Lines,+Rectangles, Basic Shapes, Block Arrows, Equation Shapes, Flowchart, Stars and+Banners, Callouts, and Action Buttons. The bundled semantic layer at+`scripts/pptx_shapes/data/presetShapeSemantics.json` adds authoring roles and+use boundaries; it does not redefine the DrawingML registry.-"Automatic" means the Executor applies this gate before drawing. Export never-scans or upgrades existing geometry.+Apply this page-local sequence before drawing:-| Visual intent | Candidate presets | Boundary |+| Pass | Action | Result ||---|---|---|-| Page field, outline, or content carrier | `rect`, `round*Rect`, `snip*Rect`, `plaque`, `bevel`, `frame`, `halfFrame`, `corner`, `foldedCorner`, `homePlate` | Match edge, corner, and opening behavior to ownership, hierarchy, or deck language; keep `rect` when no inflection helps. |-| Grouping or ownership boundary | `leftBrace`, `rightBrace`, `bracePair`, `leftBracket`, `rightBracket`, `bracketPair` | Use a brace / bracket when one visible boundary must collect or assign content without becoming a filled card. |-| Literal geometric body | `triangle`, `diamond`, `pentagon`, `hexagon`, `octagon`, `star5` | Use only when the named geometry itself is the intent. |-| Solid block direction | `rightArrow`, `leftArrow`, `upArrow`, `downArrow`, `leftRightArrow`, `upDownArrow`, `chevron` | Use `<line>` for a thin straight relationship; do not fake a solid directional object with a stroked path. |-| Standard flowchart node | `flowChartProcess`, `flowChartDecision`, `flowChartInputOutput`, `flowChartTerminator`, `flowChartDocument` | Use only for an actual flowchart; ordinary content cards remain cards. |-| Stock bent / curved relationship contour | `bentConnector*`, `curvedConnector*` | Prefer when the contour fits and endpoint attachment is not required. The authored object is an unconnected native Connector, so moving nodes does not reroute it. |-| Stock callout | `wedgeRectCallout`, `wedgeRoundRectCallout`, `wedgeEllipseCallout`, `cloudCallout` | For a brand-specific or custom tail, continue through the Boolean gate; use freeform only if the result still cannot be expressed faithfully. |-| Stock ribbon or scroll | `ribbon*`, `ellipseRibbon*`, `verticalScroll`, `horizontalScroll` | Select only when the stock contour is visually acceptable. |-| Standalone math symbol | `mathPlus`, `mathMinus`, `mathMultiply`, `mathDivide`, `mathEqual`, `mathNotEqual` | Use only when the symbol itself is a diagram shape; simple notation remains text, while non-trivial inline or block mathematics follows [`native-formula.md`](./native-formula.md). |-| Literal Office symbol | `heart`, `sun`, `moon`, `lightningBolt`, `gear6`, `gear9` | Never replace an icon required by `spec_lock.icons`. |--Narrow and inspect candidates from the already-loaded inventory:+| Job | State what the object must do for the reader before naming a shape. | Page role plus any real relationship, direction, aspect, text load, or literal scope. |+| Recall | Run `recommend` with the known criteria. Keep the default `general` scope unless the page truly needs `literal`, `flowchart`, or `navigation`. | A group-diverse candidate set with match reasons and misuse boundaries. |+| Inspect | Run `describe` for candidates whose contour could fit; compare `intent`, `recommended_for`, `avoid_for`, adjustments, text rectangle, and connection sites. | Evidence for choosing or rejecting each serious candidate. |+| Select | Choose the contour whose inference and visual character fit the page, including a neutral primitive when neutrality is useful. | One page-fit contour; no syntax decision yet. |+| Encode | Apply §1's materialization gate. | Ordinary SVG primitive, helper-authored preset, Boolean result, or necessary freeform. |++Example recall and inspection commands:```bash-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py list --search arrow-python3 ${SKILL_DIR}/scripts/preset_shape_svg.py describe rightArrow+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py recommend \+ --role spine --relationship order --directionality horizontal --aspect wide+python3 ${SKILL_DIR}/scripts/preset_shape_svg.py describe chevron++python3 ${SKILL_DIR}/scripts/preset_shape_svg.py recommend \+ --scope flowchart --role node --relationship flow --query decision```+**Hard rule — semantic fit, not name association**: a preset name, topic word,+or metaphor is not evidence of use. Respect `literal_only` and `scope` before+visual preference. For example, a scroll is not a generic playbook carrier, a+lightning bolt is not generic price tension, `chartX` / `chartStar` /+`chartPlus` are partition symbols rather than charts, and a flowchart symbol+belongs only in an actual flowchart. An action-button preset supplies visual+geometry only; it never creates an action or hyperlink.++The semantic catalog chooses contours, not syntax. It never requires `rect`,+`ellipse`, `line`, or any other primitive to pass through the preset helper;+after selection, the simplest exact authoring form in §1 remains authoritative.+Export never scans or upgrades existing geometry.+**Shape-first diagram rule**: use `<line>` for straight thin relationships;use an exact connector-family preset for a stock bent or curved contour; use ablock-arrow / chevron preset for a solid direction. Resort to an open freeform@@ -123,6 +141,8 @@ owned by the preserve/mirror round-trip contract.**Forbidden — false native semantics**:+- a catalog entry with `literal_only=true` when the depicted literal concept is+ absent, or a `flowchart` / `navigation` scope outside that real context;- `actionButton*` when navigation or trigger behavior is expected; the helpermaps its visual preset geometry only and never creates an action or hyperlink;- `chartX`, `chartStar`, or `chartPlus` as a substitute for native charts;diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 5ce345bb..afb37b89 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -197,7 +197,8 @@ python3 scripts/pptx_delivery_check.py <finished.pptx>Native preset shape authoring (one or more registry-backed fragments on stdout):```bash-python3 scripts/preset_shape_svg.py list --search arrow+python3 scripts/preset_shape_svg.py list --grouped+python3 scripts/preset_shape_svg.py recommend --role spine --relationship order --directionality horizontal --aspect widepython3 scripts/preset_shape_svg.py describe rightArrowpython3 scripts/preset_shape_svg.py render rightArrow --id process-arrow --frame 120 180 240 96 --fill '#2563EB'python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'@@ -208,18 +209,35 @@ python3 scripts/preset_shape_svg.py render-batch --input - <<'JSON'JSON```+`list --grouped` is the compact entry index: it organizes the exact 187-name+registry under the official Office gallery categories, then exposes semantic+groups, scopes, one-line intent summaries, and grouped preset names. Full match+reasons, intended uses, and misuse boundaries remain page-local in `recommend`+and `describe` instead of being repeated in the mandatory discovery output.+`recommend` recalls candidates from page-job criteria; its default `general`+scope excludes literal-only symbols, flowchart notation, and action controls.+Its result is neither a whitelist nor an automatic selection. `describe`+combines the selected preset's semantic record with its technical geometry+metadata. A zero-match recommendation is valid JSON with exit code 0 so the+caller can relax its criteria; a zero-match `list --search` remains a failed+lookup with exit code 1. Plain `list [--search QUERY]` remains the compatibility+name view.+The helper never writes a page or project file. Select one exact semanticstock-shape match, inspect the emitted fragment, and insert it into the-hand-authored SVG with the normal patch workflow. Its project-authored output-is one compact atomic `<g>` with direct registry-generated visible paths. When-one effect is justified, optional `--filter-id softShadow` references one-existing direct page-level filter under the shared shadow/glow contract and-applies it once to a shape preset. Connector presets do not accept that option.-The helper does not create the filter definition. `render-batch` accepts a-non-empty JSON array using the snake_case forms of the single-render options;-it validates every item and duplicate id before printing, so one invalid item-produces no partial fragment output. The batch remains fragment-only input for-one current construction, not a page generator or project manifest.+hand-authored SVG with the normal patch workflow. Semantic discovery does not+force ordinary rectangles, ellipses, or lines through `render`; use the+simplest exact authoring form from the native-shape reference. A rendered+project-owned preset is one compact atomic `<g>` with direct registry-generated+visible paths. When one effect is justified, optional `--filter-id softShadow`+references one existing direct page-level filter under the shared shadow/glow+contract and applies it once to a shape preset. Connector presets do not accept+that option. The helper does not create the filter definition. `render-batch`+accepts a non-empty JSON array using the snake_case forms of the single-render+options; it validates every item and duplicate id before printing, so one+invalid item produces no partial fragment output. The batch remains+fragment-only input for one current construction, not a page generator or+project manifest.Quality check and export rerender the registry instead of relying on a hiddencarrier, preview wrapper, or stored preview fingerprint. PPTX import andround-trip SVGs deliberately keep their expanded carrier/preview evidence anddiff --git a/skills/ppt-master/scripts/pptx_shapes/__init__.py b/skills/ppt-master/scripts/pptx_shapes/__init__.pyindex 5e724838..52d7ccbe 100644--- a/skills/ppt-master/scripts/pptx_shapes/__init__.py+++ b/skills/ppt-master/scripts/pptx_shapes/__init__.py@@ -55,6 +55,18 @@ from .registry import (PresetShapeRegistry,get_preset_registry,)+from .semantics import (+ BUNDLED_SEMANTICS_PATH,+ SEMANTIC_ASPECTS,+ SEMANTIC_DIRECTIONALITY,+ SEMANTIC_RELATIONSHIPS,+ SEMANTIC_ROLES,+ SEMANTIC_SCOPES,+ SEMANTIC_TEXT_CAPACITIES,+ SEMANTIC_VISUAL_WEIGHTS,+ PresetShapeSemantics,+ get_preset_shape_semantics,+)from .semantic_hash import (NATIVE_FALLBACK_SHA256_ATTR,resolve_preset_preview_hash,@@ -69,6 +81,7 @@ from .xml_safety import RELATIONSHIPS_NS, has_relationship_attributes__all__ = ["BUNDLED_DEFINITIONS_PATH","BUNDLED_DEFINITIONS_SHA256",+ "BUNDLED_SEMANTICS_PATH","BUNDLED_SHAPE_TYPES_PATH","BUNDLED_SHAPE_TYPES_SHA256","CONNECTOR_PRESET_TYPES",@@ -89,12 +102,21 @@ __all__ = ["PresetShapeDefinition","PresetShapeError","PresetShapeRegistry",+ "PresetShapeSemantics","RELATIONSHIPS_NS",+ "SEMANTIC_ASPECTS",+ "SEMANTIC_DIRECTIONALITY",+ "SEMANTIC_RELATIONSHIPS",+ "SEMANTIC_ROLES",+ "SEMANTIC_SCOPES",+ "SEMANTIC_TEXT_CAPACITIES",+ "SEMANTIC_VISUAL_WEIGHTS","UnknownGuideError","UnknownPresetShapeError","build_builtin_guides","evaluate_formula","get_preset_registry",+ "get_preset_shape_semantics","has_relationship_attributes","load_preset_shape_definitions","load_shape_type_values",diff --git a/skills/ppt-master/scripts/pptx_shapes/data/presetShapeSemantics.json b/skills/ppt-master/scripts/pptx_shapes/data/presetShapeSemantics.jsonnew file mode 100644index 00000000..f534c955--- /dev/null+++ b/skills/ppt-master/scripts/pptx_shapes/data/presetShapeSemantics.json@@ -0,0 +1,1217 @@+{+ "schema": "ppt-master.preset-shape-semantics.v1",+ "sources": [+ {+ "kind": "office-gallery-categories",+ "url": "https://support.microsoft.com/en-US/Accessibility/powerpoint/use-a-screen-reader-to-insert-and-edit-pictures-and-tables-in-powerpoint",+ "use": "Office category names"+ },+ {+ "kind": "drawingml-preset-enum",+ "url": "https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.drawing.shapetypevalues?view=openxml-3.0.1",+ "use": "DrawingML preset names"+ },+ {+ "kind": "powerpoint-shape-enum",+ "url": "https://learn.microsoft.com/en-us/javascript/api/powerpoint/powerpoint.geometricshapetype?view=powerpoint-js-preview",+ "use": "Literal shape identity and terminology"+ },+ {+ "kind": "powerpoint-action-buttons",+ "url": "https://support.microsoft.com/en-us/powerpoint/add-commands-to-your-presentation-with-action-buttons",+ "use": "Action-button behavior boundary"+ }+ ],+ "office_categories": [+ {+ "id": "lines",+ "label": "Lines",+ "summary": "Straight, bent, and curved relationship contours."+ },+ {+ "id": "rectangles",+ "label": "Rectangles",+ "summary": "Neutral and corner-inflected rectangular carriers."+ },+ {+ "id": "basic-shapes",+ "label": "Basic Shapes",+ "summary": "Geometric bodies, boundaries, radial contours, and literal symbols."+ },+ {+ "id": "block-arrows",+ "label": "Block Arrows",+ "summary": "Filled directional bodies for sequence, movement, and route emphasis."+ },+ {+ "id": "equation-shapes",+ "label": "Equation Shapes",+ "summary": "Literal mathematical operators."+ },+ {+ "id": "flowchart",+ "label": "Flowchart",+ "summary": "Conventional flowchart notation for explicit process diagrams."+ },+ {+ "id": "stars-and-banners",+ "label": "Stars and Banners",+ "summary": "Emblems, bursts, banners, scrolls, and wave accents."+ },+ {+ "id": "callouts",+ "label": "Callouts",+ "summary": "Annotation bodies and leaders that point to another object or region."+ },+ {+ "id": "action-buttons",+ "label": "Action Buttons",+ "summary": "Visual navigation-control shapes whose actions must be assigned separately."+ }+ ],+ "groups": [+ {+ "id": "straight-lines",+ "label": "Straight lines and connectors",+ "office_category": "lines",+ "scope": "general",+ "roles": ["edge", "spine", "boundary"],+ "relationships": ["link", "order", "contrast", "annotation"],+ "directionality": ["horizontal", "vertical", "diagonal"],+ "aspects": ["linear"],+ "text_capacity": "none",+ "visual_weight": "quiet",+ "literal_only": false,+ "recommended_for": [+ "Direct links, dividers, leaders, and reading-path spines.",+ "Thin relationships whose meaning comes from endpoints, routing, or an optional marker."+ ],+ "avoid_for": [+ "Do not substitute a line for a filled directional body or content carrier.",+ "Do not imply endpoint attachment; newly authored connector presets remain unconnected."+ ],+ "presets": {+ "line": {"intent": "Straight line with the default diagonal orientation."},+ "lineInv": {"intent": "Straight line with the inverse default diagonal orientation."},+ "straightConnector1": {"intent": "Straight connector contour when connector object identity matters."}+ }+ },+ {+ "id": "bent-connectors",+ "label": "Bent connectors",+ "office_category": "lines",+ "scope": "general",+ "roles": ["edge", "spine"],+ "relationships": ["link", "order", "hierarchy", "flow"],+ "directionality": ["bent"],+ "aspects": ["flexible"],+ "text_capacity": "none",+ "visual_weight": "quiet",+ "literal_only": false,+ "recommended_for": [+ "Orthogonal routing around content or between aligned zones.",+ "Relationships whose route needs visible right-angle structure."+ ],+ "avoid_for": [+ "Do not add bends when a straight relationship is clearer.",+ "Do not use the extra segments as decoration or imply unsupported endpoint attachment."+ ],+ "presets": {+ "bentConnector2": {"intent": "One-bend orthogonal connector."},+ "bentConnector3": {"intent": "Two-bend orthogonal connector."},+ "bentConnector4": {"intent": "Three-bend orthogonal connector."},+ "bentConnector5": {"intent": "Four-bend orthogonal connector for more complex routing."}+ }+ },+ {+ "id": "curved-connectors",+ "label": "Curved connectors",+ "office_category": "lines",+ "scope": "general",+ "roles": ["edge", "spine"],+ "relationships": ["link", "order", "cycle", "flow"],+ "directionality": ["curved"],+ "aspects": ["flexible"],+ "text_capacity": "none",+ "visual_weight": "quiet",+ "literal_only": false,+ "recommended_for": [+ "Soft rerouting, feedback links, or relationships that must pass around objects.",+ "Continuous paths where curvature carries meaning."+ ],+ "avoid_for": [+ "Do not curve a direct link merely to make it look less plain.",+ "Do not imply unsupported endpoint attachment."+ ],+ "presets": {+ "curvedConnector2": {"intent": "Single-curve connector."},+ "curvedConnector3": {"intent": "Two-segment curved connector."},+ "curvedConnector4": {"intent": "Three-segment curved connector."},+ "curvedConnector5": {"intent": "Four-segment curved connector for complex routing."}+ }+ },+ {+ "id": "neutral-rectangles",+ "label": "Neutral rectangular carriers",+ "office_category": "rectangles",+ "scope": "general",+ "roles": ["field", "carrier", "node", "label"],+ "relationships": ["none", "membership", "contrast", "hierarchy"],+ "directionality": ["none"],+ "aspects": ["flexible"],+ "text_capacity": "high",+ "visual_weight": "quiet",+ "literal_only": false,+ "recommended_for": [+ "Content ownership, stable fields, and nodes that need no directional or symbolic inflection.",+ "Layouts where the absence of contour meaning is itself useful."+ ],+ "avoid_for": [+ "Do not choose neutrality only because primitive syntax is shorter.",+ "Do not wrap every text block when spacing already communicates ownership."+ ],+ "presets": {+ "rect": {"intent": "Fully neutral rectangular field or carrier."},+ "roundRect": {"intent": "Uniformly rounded carrier with a softer, more approachable boundary."}+ }+ },+ {+ "id": "corner-inflected-rectangles",+ "label": "Corner-inflected rectangles",+ "office_category": "rectangles",+ "scope": "general",+ "roles": ["field", "carrier", "node", "label"],+ "relationships": ["membership", "order", "hierarchy", "contrast"],+ "directionality": ["none", "horizontal", "vertical", "diagonal"],+ "aspects": ["flexible"],+ "text_capacity": "high",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Carriers whose rounded or clipped corners mark an entry edge, open edge, or deck-wide contour language.",+ "Subtle hierarchy without adding arrows or icons."+ ],+ "avoid_for": [+ "Do not scatter corner variants randomly; the changed corners must have a page-level reason.",+ "Do not let a decorative corner imply direction that the content does not have."+ ],+ "presets": {+ "round1Rect": {"intent": "One rounded corner for a single softened or attached edge."},+ "round2SameRect": {"intent": "Two rounded corners on one side, creating a clear opening or terminal edge."},+ "round2DiagRect": {"intent": "Two diagonally opposed rounded corners for reciprocal or diagonal tension."},+ "snipRoundRect": {"intent": "Mixed clipped and rounded corners for controlled technical contrast."},+ "snip1Rect": {"intent": "One clipped corner for a single technical or directional cue."},+ "snip2SameRect": {"intent": "Two clipped corners on one side for an open or connected edge."},+ "snip2DiagRect": {"intent": "Two diagonally clipped corners for diagonal rhythm or contrast."}+ }+ },+ {+ "id": "triangular-bodies",+ "label": "Triangular bodies",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["node", "carrier", "accent", "symbol"],+ "relationships": ["hierarchy", "order", "contrast", "literal"],+ "directionality": ["none", "horizontal", "vertical", "diagonal"],+ "aspects": ["square", "flexible"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Apex, escalation, directional focus, or a literal triangular object.",+ "Corner anchoring where a diagonal edge materially organizes the page."+ ],+ "avoid_for": [+ "Do not use as a generic card; an apex or diagonal edge creates a strong inference.",+ "Do not replace a true arrow when movement or endpoint direction is the job."+ ],+ "presets": {+ "triangle": {"intent": "Symmetric triangle for apex, priority, or upward/downward focus."},+ "rtTriangle": {"intent": "Right triangle for corner anchoring, diagonal split, or literal geometry."}+ }+ },+ {+ "id": "slanted-quadrilaterals",+ "label": "Slanted quadrilaterals",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["carrier", "node", "accent"],+ "relationships": ["order", "contrast", "flow"],+ "directionality": ["horizontal", "diagonal"],+ "aspects": ["wide", "flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Motion, transformation, comparison, or a sloped handoff between zones.",+ "Nodes where the slanted sides reinforce the reading direction."+ ],+ "avoid_for": [+ "Do not use the diamond as a fake flowchart decision outside an actual flowchart.",+ "Do not use slanted edges on static content with no directional meaning."+ ],+ "presets": {+ "diamond": {"intent": "Four-sided focal node for branching, opposition, or a literal diamond."},+ "parallelogram": {"intent": "Parallel slants for motion, transfer, or input/output-like movement."},+ "trapezoid": {"intent": "Symmetric widening or narrowing for expansion, compression, or stage change."},+ "nonIsoscelesTrapezoid": {"intent": "Asymmetric widening or narrowing for off-axis transition."}+ }+ },+ {+ "id": "regular-polygons",+ "label": "Regular polygon bodies",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["carrier", "node", "label", "accent"],+ "relationships": ["none", "membership", "hierarchy", "contrast"],+ "directionality": ["none", "radial"],+ "aspects": ["square"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Compact nodes, numbered stages, badges, or radial systems where side count supports the visual language.",+ "Focal carriers that need more presence than a circle or rectangle."+ ],+ "avoid_for": [+ "Do not encode a number merely by matching the polygon side count unless readers benefit.",+ "Do not use many unrelated polygon families on one page."+ ],+ "presets": {+ "pentagon": {"intent": "Five-sided compact node or badge."},+ "hexagon": {"intent": "Six-sided technical or modular node."},+ "heptagon": {"intent": "Seven-sided emblematic node with unusual visual rhythm."},+ "octagon": {"intent": "Eight-sided stop-like or high-presence node."},+ "decagon": {"intent": "Ten-sided near-circular badge with faceted edges."},+ "dodecagon": {"intent": "Twelve-sided near-circular badge or radial node."}+ }+ },+ {+ "id": "organic-carriers",+ "label": "Organic carriers",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["field", "carrier", "node", "accent"],+ "relationships": ["membership", "hierarchy", "overlap", "contrast"],+ "directionality": ["none", "radial"],+ "aspects": ["flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Soft focal zones, ports, lenses, or organic contrast against angular geometry.",+ "Overlap and containment when a continuous curved edge improves grouping."+ ],+ "avoid_for": [+ "Do not default to circles for every metric or icon.",+ "Do not use a teardrop unless its pointed end has a focus or direction."+ ],+ "presets": {+ "ellipse": {"intent": "Continuous oval field, focal lens, or soft node."},+ "teardrop": {"intent": "Rounded body with one pointed focus for origin, destination, or literal drop imagery."}+ }+ },+ {+ "id": "ornamental-carriers",+ "label": "Ornamental carriers",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["carrier", "label", "accent"],+ "relationships": ["membership", "hierarchy", "contrast"],+ "directionality": ["none"],+ "aspects": ["flexible", "wide"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "A single high-emphasis label, title plate, or inset whose edge treatment matches the deck language."+ ],+ "avoid_for": [+ "Do not repeat as ordinary cards; concave corners or beveling create ceremonial emphasis.",+ "Do not use solely to make a box look less plain."+ ],+ "presets": {+ "plaque": {"intent": "Concave-corner plate for a formal label, title, or emblem."},+ "bevel": {"intent": "Beveled rectangular body for a raised or inset focal surface."}+ }+ },+ {+ "id": "radial-contours",+ "label": "Radial contours and segments",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["field", "spine", "boundary", "accent"],+ "relationships": ["cycle", "overlap", "membership", "contrast"],+ "directionality": ["radial", "curved"],+ "aspects": ["square", "flexible"],+ "text_capacity": "short",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Cycles, apertures, partial reveals, circular zoning, or a curved page spine.",+ "Non-quantitative radial structure where the contour itself guides reading."+ ],+ "avoid_for": [+ "Do not imply a measured proportion unless the angle is backed by data.",+ "Do not imitate a pie or donut chart when a native data chart is required."+ ],+ "presets": {+ "pieWedge": {"intent": "Single circular wedge for a radial anchor or literal sector."},+ "pie": {"intent": "Circle with an adjustable missing sector for reveal or incomplete-cycle meaning."},+ "blockArc": {"intent": "Thick curved band for a cycle segment, portal, or curved spine."},+ "donut": {"intent": "Closed ring for circular containment, focus, or a literal ring."},+ "chord": {"intent": "Circular segment bounded by an arc and chord for overlap or partial-reveal geometry."},+ "arc": {"intent": "Open curved contour for a light boundary, trajectory, or partial frame."}+ }+ },+ {+ "id": "frames-and-corners",+ "label": "Frames, corners, and edge pieces",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["field", "boundary", "accent"],+ "relationships": ["membership", "hierarchy", "contrast"],+ "directionality": ["none", "horizontal", "vertical", "diagonal"],+ "aspects": ["flexible"],+ "text_capacity": "none",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Open ownership boundaries, page apertures, edge anchors, and corner-led composition.",+ "Grouping without turning every content unit into a filled card."+ ],+ "avoid_for": [+ "Do not place a frame around content that already has clear ownership.",+ "Do not use folded or diagonal details without a matching page-level edge language."+ ],+ "presets": {+ "foldedCorner": {"intent": "Sheet-like carrier or accent with one folded corner."},+ "frame": {"intent": "Closed rectangular frame for a strong aperture or ownership boundary."},+ "halfFrame": {"intent": "Partially open frame for directional grouping or an incomplete boundary."},+ "corner": {"intent": "L-shaped corner piece for edge anchoring or a partial frame."},+ "diagStripe": {"intent": "Diagonal band for edge emphasis, slanted continuity, or a literal stripe."}+ }+ },+ {+ "id": "brackets",+ "label": "Brackets",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["boundary", "callout"],+ "relationships": ["membership", "annotation", "hierarchy"],+ "directionality": ["horizontal", "vertical"],+ "aspects": ["tall", "wide", "flexible"],+ "text_capacity": "none",+ "visual_weight": "quiet",+ "literal_only": false,+ "recommended_for": [+ "Collecting adjacent items, marking a range, or assigning a label to one side of a group."+ ],+ "avoid_for": [+ "Do not use when a filled carrier already establishes membership.",+ "Do not mix bracket directions without a clear ownership side."+ ],+ "presets": {+ "leftBracket": {"intent": "Left-side bracket that collects content to its right."},+ "rightBracket": {"intent": "Right-side bracket that collects content to its left."},+ "bracketPair": {"intent": "Paired brackets that enclose a complete range or set."}+ }+ },+ {+ "id": "braces",+ "label": "Braces",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["boundary", "callout"],+ "relationships": ["membership", "annotation", "hierarchy"],+ "directionality": ["horizontal", "vertical"],+ "aspects": ["tall", "wide", "flexible"],+ "text_capacity": "none",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Visible grouping, aggregation, or one-to-many ownership where a bracket is too mechanical."+ ],+ "avoid_for": [+ "Do not use as ornamental punctuation detached from a real group.",+ "Do not use paired braces when one-sided assignment is the actual relationship."+ ],+ "presets": {+ "leftBrace": {"intent": "Left-side brace that groups or assigns content to its right."},+ "rightBrace": {"intent": "Right-side brace that groups or assigns content to its left."},+ "bracePair": {"intent": "Paired braces that enclose a complete set."}+ }+ },+ {+ "id": "literal-pictograms",+ "label": "Literal pictograms",+ "office_category": "basic-shapes",+ "scope": "literal",+ "roles": ["symbol", "accent"],+ "relationships": ["literal"],+ "directionality": ["none"],+ "aspects": ["square"],+ "text_capacity": "none",+ "visual_weight": "emblematic",+ "literal_only": true,+ "recommended_for": [+ "A concept whose ordinary meaning is exactly the depicted object or symbol."+ ],+ "avoid_for": [+ "Do not select by loose metaphor or keyword association.",+ "Do not use as a generic visual-energy substitute for real structure."+ ],+ "presets": {+ "cube": {"intent": "Literal cube or compact three-dimensional object."},+ "can": {"intent": "Literal cylinder, database-like store, or container."},+ "lightningBolt": {"intent": "Literal lightning, electricity, shock, or sudden-impact symbol.", "avoid_for": ["Do not use for generic tension, urgency, or price change without literal electrical or shock meaning."]},+ "heart": {"intent": "Literal affection, preference, health-heart, or favorite symbol."},+ "sun": {"intent": "Literal sun, daylight, heat, or weather symbol."},+ "moon": {"intent": "Literal moon, night, sleep, or lunar symbol."},+ "smileyFace": {"intent": "Literal positive-emotion or satisfaction symbol."},+ "noSmoking": {"intent": "Prohibition symbol with an adjustable slash over a target."},+ "cloud": {"intent": "Literal cloud, cloud-computing domain, or atmospheric thought field."}+ }+ },+ {+ "id": "functional-pictograms",+ "label": "Functional pictograms",+ "office_category": "basic-shapes",+ "scope": "literal",+ "roles": ["symbol", "node", "accent"],+ "relationships": ["literal", "flow"],+ "directionality": ["none", "radial"],+ "aspects": ["square", "tall"],+ "text_capacity": "none",+ "visual_weight": "strong",+ "literal_only": true,+ "recommended_for": [+ "Literal mechanism, settings, processing, or filtering concepts."+ ],+ "avoid_for": [+ "Do not use gears as a generic synonym for every process.",+ "Do not use a funnel unless narrowing, screening, or conversion is the actual relationship."+ ],+ "presets": {+ "gear6": {"intent": "Six-tooth gear for a literal mechanism, settings, or interlocking process."},+ "gear9": {"intent": "Nine-tooth gear for a denser literal mechanism or system component."},+ "funnel": {"intent": "Literal filtering, narrowing, qualification, or conversion funnel."}+ }+ },+ {+ "id": "plus-symbol",+ "label": "Plus symbol",+ "office_category": "basic-shapes",+ "scope": "literal",+ "roles": ["symbol", "accent", "node"],+ "relationships": ["literal", "convergence"],+ "directionality": ["multidirectional"],+ "aspects": ["square"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": true,+ "recommended_for": [+ "Literal addition, inclusion, medical-cross, or combined-value meaning."+ ],+ "avoid_for": [+ "Do not use as a generic decoration between unrelated items.",+ "Use mathPlus when the page is explicitly mathematical notation."+ ],+ "presets": {+ "plus": {"intent": "Broad plus or cross body for literal addition, inclusion, or cross symbolism."}+ }+ },+ {+ "id": "corner-tabs",+ "label": "Corner and edge tabs",+ "office_category": "basic-shapes",+ "scope": "general",+ "roles": ["field", "boundary", "accent"],+ "relationships": ["membership", "hierarchy", "contrast"],+ "directionality": ["none", "multidirectional"],+ "aspects": ["flexible"],+ "text_capacity": "none",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Four-corner framing, registration marks, or a technical aperture around a focal zone."+ ],+ "avoid_for": [+ "Do not treat the four tabs as independent data points.",+ "Do not add them when a simpler frame already communicates the boundary."+ ],+ "presets": {+ "cornerTabs": {"intent": "Four triangular corner tabs defining an implied rectangle."},+ "squareTabs": {"intent": "Four square edge tabs defining an implied rectangle."},+ "plaqueTabs": {"intent": "Four rounded corner tabs defining an implied rectangle."}+ }+ },+ {+ "id": "partition-symbols",+ "label": "Partition symbols",+ "office_category": "basic-shapes",+ "scope": "literal",+ "roles": ["symbol", "node", "accent"],+ "relationships": ["overlap", "convergence", "literal"],+ "directionality": ["multidirectional"],+ "aspects": ["square"],+ "text_capacity": "none",+ "visual_weight": "strong",+ "literal_only": true,+ "recommended_for": [+ "A literal four- or six-region partition, intersection, or hub motif."+ ],+ "avoid_for": [+ "Despite their names, these are not charts and carry no data semantics.",+ "Do not use as a substitute for a native chart or an explained matrix."+ ],+ "presets": {+ "chartX": {"intent": "Rectangle divided diagonally into four triangular regions."},+ "chartStar": {"intent": "Rectangle divided into six regions by vertical and diagonal lines."},+ "chartPlus": {"intent": "Rectangle divided into four quarters by vertical and horizontal lines."}+ }+ },+ {+ "id": "arrow-carriers",+ "label": "Arrow-shaped carriers",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["carrier", "node", "spine"],+ "relationships": ["order", "flow", "hierarchy"],+ "directionality": ["horizontal"],+ "aspects": ["wide"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Stage bodies, handoffs, and compact process steps whose container and direction are one object."+ ],+ "avoid_for": [+ "Do not use as a generic card; the pointed end asserts flow.",+ "Do not use when a thin connector between independent nodes is clearer."+ ],+ "presets": {+ "homePlate": {"intent": "Pentagon-like horizontal stage body with one pointed destination edge."},+ "chevron": {"intent": "Compact V-notched directional stage for repeated sequence or handoff."}+ }+ },+ {+ "id": "cardinal-arrows",+ "label": "Cardinal block arrows",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["spine", "edge", "accent"],+ "relationships": ["order", "flow", "hierarchy"],+ "directionality": ["horizontal", "vertical"],+ "aspects": ["wide", "tall"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Strong one-way movement, escalation, decline, or a dominant next-step direction."+ ],+ "avoid_for": [+ "Do not use for a neutral link or divider.",+ "Do not point toward content unless the endpoint relationship is real."+ ],+ "presets": {+ "rightArrow": {"intent": "Strong left-to-right movement or next-step direction.", "directionality": ["horizontal"], "aspects": ["wide"]},+ "leftArrow": {"intent": "Strong right-to-left movement, return, or reverse direction.", "directionality": ["horizontal"], "aspects": ["wide"]},+ "upArrow": {"intent": "Strong upward movement, growth, or escalation.", "directionality": ["vertical"], "aspects": ["tall"]},+ "downArrow": {"intent": "Strong downward movement, decline, or descent.", "directionality": ["vertical"], "aspects": ["tall"]}+ }+ },+ {+ "id": "stylized-forward-arrows",+ "label": "Stylized forward arrows",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["spine", "accent"],+ "relationships": ["order", "flow", "contrast"],+ "directionality": ["horizontal"],+ "aspects": ["wide"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Forward motion where the tail treatment communicates acceleration, entry, or interlock."+ ],+ "avoid_for": [+ "Do not choose the tail treatment only for novelty.",+ "Do not use when a plain cardinal arrow already expresses the job."+ ],+ "presets": {+ "stripedRightArrow": {"intent": "Right arrow with tail stripes for acceleration, launch, or staged entry."},+ "notchedRightArrow": {"intent": "Right arrow with an inward tail notch for interlock or handoff."}+ }+ },+ {+ "id": "multi-axis-arrows",+ "label": "Multi-axis arrows",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["spine", "node", "accent"],+ "relationships": ["contrast", "convergence", "flow", "link"],+ "directionality": ["bidirectional", "multidirectional"],+ "aspects": ["wide", "tall", "square"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Reciprocity, branching, multi-way movement, or a hub with explicit directional alternatives."+ ],+ "avoid_for": [+ "Do not imply symmetry or available routes that the content does not support.",+ "Do not use as a generic central decoration."+ ],+ "presets": {+ "leftRightArrow": {"intent": "Horizontal reciprocity or two-way exchange.", "directionality": ["horizontal", "bidirectional"], "aspects": ["wide"]},+ "upDownArrow": {"intent": "Vertical reciprocity or two-way change.", "directionality": ["vertical", "bidirectional"], "aspects": ["tall"]},+ "leftUpArrow": {"intent": "Two-route branch toward left and up.", "directionality": ["multidirectional"], "aspects": ["square"]},+ "leftRightUpArrow": {"intent": "Three-route branch toward left, right, and up.", "directionality": ["multidirectional"], "aspects": ["square"]},+ "quadArrow": {"intent": "Four-way hub or movement in all cardinal directions.", "directionality": ["multidirectional"], "aspects": ["square"]}+ }+ },+ {+ "id": "turn-arrows",+ "label": "Bent and return arrows",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["spine", "edge", "accent"],+ "relationships": ["order", "flow", "cycle"],+ "directionality": ["bent", "curved"],+ "aspects": ["flexible", "square"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "A real turn, reroute, reversal, or return within a process path."+ ],+ "avoid_for": [+ "Do not use a turn arrow for generic progress with no change of direction.",+ "Do not confuse a filled turn body with a thin routed connector."+ ],+ "presets": {+ "bentUpArrow": {"intent": "Sharp right-angle route ending upward.", "directionality": ["bent", "vertical"]},+ "bentArrow": {"intent": "Rounded right-angle route for a directional turn.", "directionality": ["bent", "horizontal"]},+ "uturnArrow": {"intent": "Explicit reversal, return, or loop-back path.", "directionality": ["curved", "vertical"]}+ }+ },+ {+ "id": "circular-arrows",+ "label": "Circular arrows",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["spine", "edge", "accent"],+ "relationships": ["cycle", "flow", "link"],+ "directionality": ["radial", "bidirectional"],+ "aspects": ["square"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Closed-loop processes, recurrence, refresh, or circular exchange."+ ],+ "avoid_for": [+ "Do not imply repetition or reversibility unless it exists.",+ "Do not use as a decorative halo around unrelated content."+ ],+ "presets": {+ "circularArrow": {"intent": "One-direction circular loop or refresh path.", "directionality": ["radial"]},+ "leftCircularArrow": {"intent": "Counter-oriented circular loop or return path.", "directionality": ["radial"]},+ "leftRightCircularArrow": {"intent": "Two-way circular exchange or reversible cycle."}+ }+ },+ {+ "id": "curved-arrows",+ "label": "Curved and swoosh arrows",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["spine", "edge", "accent"],+ "relationships": ["order", "flow", "convergence"],+ "directionality": ["curved", "horizontal", "vertical"],+ "aspects": ["wide", "tall", "flexible"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Directional motion that must arc around a focal object or converge from an offset origin."+ ],+ "avoid_for": [+ "Do not add curvature merely to make an arrow more expressive.",+ "Do not use when the path would falsely imply bypass or convergence."+ ],+ "presets": {+ "curvedRightArrow": {"intent": "Curved path ending to the right.", "directionality": ["curved", "horizontal"], "aspects": ["wide"]},+ "curvedLeftArrow": {"intent": "Curved path ending to the left.", "directionality": ["curved", "horizontal"], "aspects": ["wide"]},+ "curvedUpArrow": {"intent": "Curved path ending upward.", "directionality": ["curved", "vertical"], "aspects": ["tall"]},+ "curvedDownArrow": {"intent": "Curved path ending downward.", "directionality": ["curved", "vertical"], "aspects": ["tall"]},+ "swooshArrow": {"intent": "Fast tapered sweep for launch, acceleration, or a dynamic handoff.", "directionality": ["curved", "horizontal"], "aspects": ["wide"]}+ }+ },+ {+ "id": "arrow-callouts",+ "label": "Arrow callout bodies",+ "office_category": "block-arrows",+ "scope": "general",+ "roles": ["carrier", "callout", "spine"],+ "relationships": ["annotation", "order", "flow", "contrast"],+ "directionality": ["horizontal", "vertical", "bidirectional", "multidirectional"],+ "aspects": ["wide", "tall", "square"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "A short message whose body and directional emphasis must be one strong object."+ ],+ "avoid_for": [+ "Do not use as an ordinary content card.",+ "Do not point in multiple directions unless the message truly applies to each route."+ ],+ "presets": {+ "leftArrowCallout": {"intent": "Text-bearing callout with strong leftward direction.", "directionality": ["horizontal"], "aspects": ["wide"]},+ "rightArrowCallout": {"intent": "Text-bearing callout with strong rightward direction.", "directionality": ["horizontal"], "aspects": ["wide"]},+ "upArrowCallout": {"intent": "Text-bearing callout with strong upward direction.", "directionality": ["vertical"], "aspects": ["tall"]},+ "downArrowCallout": {"intent": "Text-bearing callout with strong downward direction.", "directionality": ["vertical"], "aspects": ["tall"]},+ "leftRightArrowCallout": {"intent": "Text-bearing callout for horizontal two-way emphasis.", "directionality": ["horizontal", "bidirectional"], "aspects": ["wide"]},+ "upDownArrowCallout": {"intent": "Text-bearing callout for vertical two-way emphasis.", "directionality": ["vertical", "bidirectional"], "aspects": ["tall"]},+ "quadArrowCallout": {"intent": "Text-bearing callout for four-way or hub emphasis.", "directionality": ["multidirectional"], "aspects": ["square"]}+ }+ },+ {+ "id": "equation-operators",+ "label": "Equation operators",+ "office_category": "equation-shapes",+ "scope": "literal",+ "roles": ["symbol", "node"],+ "relationships": ["literal", "convergence", "contrast"],+ "directionality": ["none", "multidirectional"],+ "aspects": ["square", "wide"],+ "text_capacity": "none",+ "visual_weight": "strong",+ "literal_only": true,+ "recommended_for": [+ "An explicit mathematical or logical operator between operands."+ ],+ "avoid_for": [+ "Do not use equation symbols as generic separators or decorative icons.",+ "Keep operand order and mathematical meaning unambiguous."+ ],+ "presets": {+ "mathPlus": {"intent": "Mathematical addition operator."},+ "mathMinus": {"intent": "Mathematical subtraction operator."},+ "mathMultiply": {"intent": "Mathematical multiplication operator."},+ "mathDivide": {"intent": "Mathematical division operator."},+ "mathEqual": {"intent": "Mathematical equality operator."},+ "mathNotEqual": {"intent": "Mathematical inequality operator."}+ }+ },+ {+ "id": "flowchart-operations",+ "label": "Flowchart operations",+ "office_category": "flowchart",+ "scope": "flowchart",+ "roles": ["node"],+ "relationships": ["flow", "order"],+ "directionality": ["none"],+ "aspects": ["wide", "flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Exact conventional operation nodes inside an actual flowchart."+ ],+ "avoid_for": [+ "Do not use flowchart notation as a decorative card vocabulary.",+ "Do not substitute one operation symbol for another because its contour looks better."+ ],+ "presets": {+ "flowChartProcess": {"intent": "Standard process or operation step."},+ "flowChartPredefinedProcess": {"intent": "Named subprocess or predefined operation."},+ "flowChartAlternateProcess": {"intent": "Alternate process step."},+ "flowChartPreparation": {"intent": "Preparation or initialization step."},+ "flowChartManualOperation": {"intent": "Operation performed manually."},+ "flowChartDelay": {"intent": "Delay or waiting period."}+ }+ },+ {+ "id": "flowchart-routing",+ "label": "Flowchart decisions and routing",+ "office_category": "flowchart",+ "scope": "flowchart",+ "roles": ["node"],+ "relationships": ["flow", "link", "convergence"],+ "directionality": ["none", "multidirectional"],+ "aspects": ["square", "flexible"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Exact branch, merge, junction, or continuation semantics inside an actual flowchart."+ ],+ "avoid_for": [+ "Do not infer routing semantics from appearance alone.",+ "Do not use these symbols outside a diagram that explains its flow."+ ],+ "presets": {+ "flowChartDecision": {"intent": "Decision or branch point."},+ "flowChartConnector": {"intent": "On-page continuation connector."},+ "flowChartOffpageConnector": {"intent": "Continuation to another page or diagram frame."},+ "flowChartSummingJunction": {"intent": "Summing junction where flows combine."},+ "flowChartOr": {"intent": "Logical OR junction."},+ "flowChartCollate": {"intent": "Collate or reconcile inputs into an ordered result."},+ "flowChartSort": {"intent": "Sort or order operation."},+ "flowChartExtract": {"intent": "Extract one stream or subset from another."},+ "flowChartMerge": {"intent": "Merge multiple flow paths into one."}+ }+ },+ {+ "id": "flowchart-input-output",+ "label": "Flowchart input and output",+ "office_category": "flowchart",+ "scope": "flowchart",+ "roles": ["node"],+ "relationships": ["flow"],+ "directionality": ["none", "horizontal"],+ "aspects": ["wide", "flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Exact data-entry or presentation nodes inside an actual flowchart."+ ],+ "avoid_for": [+ "Do not use obsolete media symbols unless the depicted medium is intentional.",+ "Do not use input/output notation as a general slanted content card."+ ],+ "presets": {+ "flowChartInputOutput": {"intent": "General data input or output."},+ "flowChartManualInput": {"intent": "Data entered manually."},+ "flowChartPunchedCard": {"intent": "Punched-card input or a deliberately historical medium."},+ "flowChartPunchedTape": {"intent": "Punched-tape input or a deliberately historical medium."},+ "flowChartDisplay": {"intent": "Information shown on a display."}+ }+ },+ {+ "id": "flowchart-documents",+ "label": "Flowchart documents",+ "office_category": "flowchart",+ "scope": "flowchart",+ "roles": ["node"],+ "relationships": ["flow", "membership"],+ "directionality": ["none"],+ "aspects": ["wide", "flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Document artifacts that enter, leave, or are produced by an actual flowchart."+ ],+ "avoid_for": [+ "Do not use the wavy bottom as a generic decorative card edge."+ ],+ "presets": {+ "flowChartDocument": {"intent": "Single document artifact."},+ "flowChartMultidocument": {"intent": "Multiple document artifacts or a document set."}+ }+ },+ {+ "id": "flowchart-storage",+ "label": "Flowchart storage",+ "office_category": "flowchart",+ "scope": "flowchart",+ "roles": ["node"],+ "relationships": ["flow", "membership"],+ "directionality": ["none"],+ "aspects": ["wide", "tall", "flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Exact storage-media semantics inside an actual flowchart."+ ],+ "avoid_for": [+ "Do not choose a storage symbol by silhouette alone.",+ "Use historical media shapes only when that distinction matters."+ ],+ "presets": {+ "flowChartInternalStorage": {"intent": "Internal storage or memory."},+ "flowChartOfflineStorage": {"intent": "Offline storage."},+ "flowChartOnlineStorage": {"intent": "Online or directly accessible storage."},+ "flowChartMagneticTape": {"intent": "Sequential-access magnetic tape storage."},+ "flowChartMagneticDisk": {"intent": "Magnetic disk storage."},+ "flowChartMagneticDrum": {"intent": "Magnetic drum or direct-access historical storage."}+ }+ },+ {+ "id": "flowchart-terminator",+ "label": "Flowchart terminator",+ "office_category": "flowchart",+ "scope": "flowchart",+ "roles": ["node"],+ "relationships": ["flow", "order"],+ "directionality": ["none"],+ "aspects": ["wide"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "Start, end, or terminal state in an actual flowchart."+ ],+ "avoid_for": [+ "Do not use as a generic pill-shaped label when no terminal state is intended."+ ],+ "presets": {+ "flowChartTerminator": {"intent": "Start, end, or terminal state."}+ }+ },+ {+ "id": "stars",+ "label": "Stars",+ "office_category": "stars-and-banners",+ "scope": "literal",+ "roles": ["symbol", "accent", "label"],+ "relationships": ["literal", "hierarchy", "contrast"],+ "directionality": ["radial"],+ "aspects": ["square"],+ "text_capacity": "short",+ "visual_weight": "emblematic",+ "literal_only": true,+ "recommended_for": [+ "Literal rating, award, sparkle, burst, or one exceptional focal badge."+ ],+ "avoid_for": [+ "Do not use as a routine bullet, card, or unexplained attention device.",+ "High-point stars carry burst or sparkle energy and are poor text carriers."+ ],+ "presets": {+ "star4": {"intent": "Four-point sparkle or compass-like accent."},+ "star5": {"intent": "Conventional rating, award, or favorite star."},+ "star6": {"intent": "Six-point geometric star or literal emblem."},+ "star7": {"intent": "Seven-point unusual emblem or focal burst."},+ "star8": {"intent": "Eight-point badge, compass, or controlled burst."},+ "star10": {"intent": "Ten-point seal-like badge or radial emphasis."},+ "star12": {"intent": "Twelve-point seal-like badge or radial emphasis."},+ "star16": {"intent": "Dense burst for exceptional emphasis."},+ "star24": {"intent": "Very dense sparkle or burst accent."},+ "star32": {"intent": "Maximum-density sparkle or burst accent."}+ }+ },+ {+ "id": "irregular-seals",+ "label": "Irregular seals and explosions",+ "office_category": "stars-and-banners",+ "scope": "literal",+ "roles": ["symbol", "accent", "label"],+ "relationships": ["literal", "contrast"],+ "directionality": ["radial"],+ "aspects": ["square"],+ "text_capacity": "short",+ "visual_weight": "emblematic",+ "literal_only": true,+ "recommended_for": [+ "A literal burst, warning, sale seal, or exceptional interruption."+ ],+ "avoid_for": [+ "Do not use for ordinary emphasis or as a recurring section badge.",+ "Do not place long text inside the irregular contour."+ ],+ "presets": {+ "irregularSeal1": {"intent": "Irregular burst with a coarser explosion edge."},+ "irregularSeal2": {"intent": "Irregular burst with a denser explosion edge."}+ }+ },+ {+ "id": "straight-ribbons",+ "label": "Straight ribbons",+ "office_category": "stars-and-banners",+ "scope": "general",+ "roles": ["label", "carrier", "accent"],+ "relationships": ["hierarchy", "contrast", "order"],+ "directionality": ["horizontal", "bidirectional"],+ "aspects": ["wide"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "One ceremonial title, milestone, award label, or section banner."+ ],+ "avoid_for": [+ "Do not use as a generic content card or repeat on every page.",+ "Do not imply directional arrows from ribbon tails unless the reading path supports it."+ ],+ "presets": {+ "ribbon": {"intent": "Banner with the center panel raised above its folded ends.", "directionality": ["horizontal"]},+ "ribbon2": {"intent": "Banner with the center panel lowered below its folded ends.", "directionality": ["horizontal"]},+ "leftRightRibbon": {"intent": "Straight ribbon with outward left and right tail emphasis."}+ }+ },+ {+ "id": "curved-ribbons",+ "label": "Curved ribbons",+ "office_category": "stars-and-banners",+ "scope": "general",+ "roles": ["label", "carrier", "accent"],+ "relationships": ["hierarchy", "contrast"],+ "directionality": ["curved", "horizontal"],+ "aspects": ["wide"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "A single arched title or badge whose curvature is part of the page composition."+ ],+ "avoid_for": [+ "Do not bend ordinary labels for decoration alone.",+ "Do not use when the curve conflicts with the page's reading axis."+ ],+ "presets": {+ "ellipseRibbon": {"intent": "Curved ribbon arcing upward around a central label."},+ "ellipseRibbon2": {"intent": "Curved ribbon arcing downward around a central label."}+ }+ },+ {+ "id": "scrolls",+ "label": "Scrolls",+ "office_category": "stars-and-banners",+ "scope": "literal",+ "roles": ["label", "carrier", "symbol"],+ "relationships": ["literal", "hierarchy"],+ "directionality": ["horizontal", "vertical"],+ "aspects": ["wide", "tall"],+ "text_capacity": "medium",+ "visual_weight": "emblematic",+ "literal_only": true,+ "recommended_for": [+ "A literal scroll, proclamation, archival document, or deliberately historical motif."+ ],+ "avoid_for": [+ "Do not use a scroll as a generic playbook, process card, or long-form content container.",+ "Do not select it merely because the topic mentions a document."+ ],+ "presets": {+ "verticalScroll": {"intent": "Tall rolled document or vertical historical proclamation.", "directionality": ["vertical"], "aspects": ["tall"]},+ "horizontalScroll": {"intent": "Wide rolled document or horizontal historical proclamation.", "directionality": ["horizontal"], "aspects": ["wide"]}+ }+ },+ {+ "id": "waves",+ "label": "Waves",+ "office_category": "stars-and-banners",+ "scope": "literal",+ "roles": ["accent", "spine", "symbol"],+ "relationships": ["literal", "flow", "cycle"],+ "directionality": ["curved", "horizontal"],+ "aspects": ["wide"],+ "text_capacity": "none",+ "visual_weight": "strong",+ "literal_only": true,+ "recommended_for": [+ "Literal wave, oscillation, fluid motion, or one continuous undulating accent."+ ],+ "avoid_for": [+ "Do not use as an arbitrary section divider.",+ "Do not imply volatility or oscillation unless the content supports it."+ ],+ "presets": {+ "wave": {"intent": "Single undulating band for literal wave or oscillation."},+ "doubleWave": {"intent": "Double undulating band for stronger ripple or oscillation."}+ }+ },+ {+ "id": "leader-callouts",+ "label": "Leader-line callouts",+ "office_category": "callouts",+ "scope": "general",+ "roles": ["callout", "label", "edge"],+ "relationships": ["annotation", "link"],+ "directionality": ["callout", "bent"],+ "aspects": ["flexible"],+ "text_capacity": "medium",+ "visual_weight": "moderate",+ "literal_only": false,+ "recommended_for": [+ "A short annotation that must visibly point to one object or region.",+ "Choose bend count and border/accent treatment from the routing and emphasis need."+ ],+ "avoid_for": [+ "Do not use as a free-standing content card with no target.",+ "Do not add bends or accent bars that carry no routing or hierarchy purpose."+ ],+ "presets": {+ "callout1": {"intent": "Unbordered callout with a straight leader."},+ "callout2": {"intent": "Unbordered callout with one bent leader."},+ "callout3": {"intent": "Unbordered callout with a double-bent leader."},+ "accentCallout1": {"intent": "Straight-leader callout with an accent bar but no full border."},+ "accentCallout2": {"intent": "One-bend callout with an accent bar but no full border."},+ "accentCallout3": {"intent": "Double-bend callout with an accent bar but no full border."},+ "borderCallout1": {"intent": "Bordered callout with a straight leader."},+ "borderCallout2": {"intent": "Bordered callout with one bent leader."},+ "borderCallout3": {"intent": "Bordered callout with a double-bent leader."},+ "accentBorderCallout1": {"intent": "Bordered straight-leader callout with an accent bar."},+ "accentBorderCallout2": {"intent": "Bordered one-bend callout with an accent bar."},+ "accentBorderCallout3": {"intent": "Bordered double-bend callout with an accent bar."}+ }+ },+ {+ "id": "wedge-callouts",+ "label": "Wedge and thought callouts",+ "office_category": "callouts",+ "scope": "general",+ "roles": ["callout", "carrier", "label"],+ "relationships": ["annotation", "link"],+ "directionality": ["callout"],+ "aspects": ["flexible"],+ "text_capacity": "medium",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "A speech, thought, or annotation body whose wedge visibly identifies the target."+ ],+ "avoid_for": [+ "Do not use without a real target.",+ "Use the cloud variant only for thought, uncertainty, or a literal cloud context."+ ],+ "presets": {+ "wedgeRectCallout": {"intent": "Rectangular annotation body with a pointed wedge to the target."},+ "wedgeRoundRectCallout": {"intent": "Rounded rectangular annotation body with a pointed wedge."},+ "wedgeEllipseCallout": {"intent": "Oval speech-like annotation body with a pointed wedge."},+ "cloudCallout": {"intent": "Cloud-shaped thought callout with a dotted tail."}+ }+ },+ {+ "id": "action-controls",+ "label": "Action-button controls",+ "office_category": "action-buttons",+ "scope": "navigation",+ "roles": ["control", "symbol"],+ "relationships": ["navigation", "literal"],+ "directionality": ["none", "horizontal"],+ "aspects": ["square", "flexible"],+ "text_capacity": "short",+ "visual_weight": "strong",+ "literal_only": false,+ "recommended_for": [+ "Interactive presentation controls when the matching click or hover action will also be assigned."+ ],+ "avoid_for": [+ "The preset supplies visual geometry only; it does not create navigation, media, or hyperlink behavior.",+ "Do not use action-button chrome as a decorative icon set in a noninteractive deck."+ ],+ "presets": {+ "actionButtonBlank": {"intent": "Blank action-button body for a custom control label or icon."},+ "actionButtonHome": {"intent": "Home navigation control."},+ "actionButtonHelp": {"intent": "Help control."},+ "actionButtonInformation": {"intent": "Information control."},+ "actionButtonForwardNext": {"intent": "Forward or next navigation control."},+ "actionButtonBackPrevious": {"intent": "Back or previous navigation control."},+ "actionButtonEnd": {"intent": "End or last-slide navigation control."},+ "actionButtonBeginning": {"intent": "Beginning or first-slide navigation control."},+ "actionButtonReturn": {"intent": "Return navigation control."},+ "actionButtonDocument": {"intent": "Document-opening control."},+ "actionButtonSound": {"intent": "Sound playback control."},+ "actionButtonMovie": {"intent": "Movie or video playback control."}+ }+ }+ ]+}diff --git a/skills/ppt-master/scripts/pptx_shapes/semantics.py b/skills/ppt-master/scripts/pptx_shapes/semantics.pynew file mode 100644index 00000000..75e7f2c4--- /dev/null+++ b/skills/ppt-master/scripts/pptx_shapes/semantics.py@@ -0,0 +1,716 @@+#!/usr/bin/env python3+"""+PPT Master - DrawingML Preset Shape Semantics++Load and validate the bundled Office-category and authoring-use catalog for+DrawingML preset shapes.++Usage:+ Import get_preset_shape_semantics from pptx_shapes.semantics.++Examples:+ catalog = get_preset_shape_semantics()+ arrow = catalog.describe("rightArrow")++Dependencies:+ None (only uses standard library and local PPT Master modules)+"""++from __future__ import annotations++import json+import re+from functools import lru_cache+from pathlib import Path+from typing import Sequence++from .errors import PresetShapeDataError, UnknownPresetShapeError+from .registry import get_preset_registry+++BUNDLED_SEMANTICS_PATH = (+ Path(__file__).resolve().parent / "data" / "presetShapeSemantics.json"+)++SEMANTIC_ROLES = (+ "field",+ "carrier",+ "node",+ "edge",+ "spine",+ "boundary",+ "callout",+ "label",+ "symbol",+ "control",+ "accent",+)+SEMANTIC_RELATIONSHIPS = (+ "none",+ "membership",+ "order",+ "link",+ "hierarchy",+ "contrast",+ "convergence",+ "cycle",+ "overlap",+ "annotation",+ "flow",+ "literal",+ "navigation",+)+SEMANTIC_DIRECTIONALITY = (+ "none",+ "horizontal",+ "vertical",+ "diagonal",+ "bidirectional",+ "multidirectional",+ "bent",+ "curved",+ "radial",+ "callout",+)+SEMANTIC_ASPECTS = (+ "flexible",+ "wide",+ "tall",+ "square",+ "linear",+)+SEMANTIC_TEXT_CAPACITIES = ("none", "short", "medium", "high")+SEMANTIC_VISUAL_WEIGHTS = ("quiet", "moderate", "strong", "emblematic")+SEMANTIC_SCOPES = ("general", "literal", "flowchart", "navigation")++_TEXT_CAPACITY_RANK = {+ value: index for index, value in enumerate(SEMANTIC_TEXT_CAPACITIES)+}+_QUERY_TOKEN_RE = re.compile(r"[a-z0-9]+")+_CAMEL_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")+_QUERY_STOP_WORDS = frozenset({+ "a",+ "an",+ "and",+ "for",+ "of",+ "or",+ "the",+ "to",+ "with",+})+++class PresetShapeSemantics:+ """Read-only semantic catalog aligned exactly with the preset registry."""++ def __init__(self, payload: object, expected_names: Sequence[str]) -> None:+ root = _require_dict(payload, "catalog")+ self.schema = _require_string(root.get("schema"), "catalog.schema")+ self.sources = tuple(+ _require_dict(item, f"catalog.sources[{index}]")+ for index, item in enumerate(+ _require_list(root.get("sources"), "catalog.sources")+ )+ )++ categories = _require_list(+ root.get("office_categories"),+ "catalog.office_categories",+ )+ self._categories: list[dict[str, object]] = []+ self._category_by_id: dict[str, dict[str, object]] = {}+ for index, raw_category in enumerate(categories):+ label = f"catalog.office_categories[{index}]"+ category = _require_dict(raw_category, label)+ _reject_unknown_fields(category, label, {"id", "label", "summary"})+ category_id = _require_string(category.get("id"), f"{label}.id")+ if category_id in self._category_by_id:+ raise PresetShapeDataError(+ f"Duplicate Office shape category: {category_id!r}"+ )+ normalized = {+ "id": category_id,+ "label": _require_string(category.get("label"), f"{label}.label"),+ "summary": _require_string(+ category.get("summary"),+ f"{label}.summary",+ ),+ }+ self._categories.append(normalized)+ self._category_by_id[category_id] = normalized++ groups = _require_list(root.get("groups"), "catalog.groups")+ self._groups: list[dict[str, object]] = []+ self._preset_semantics: dict[str, dict[str, object]] = {}+ self._group_order: dict[str, int] = {}+ self._preset_order = {+ name: index for index, name in enumerate(expected_names)+ }+ for index, raw_group in enumerate(groups):+ group = self._normalize_group(raw_group, index)+ group_id = str(group["id"])+ if group_id in self._group_order:+ raise PresetShapeDataError(+ f"Duplicate preset semantic group: {group_id!r}"+ )+ self._group_order[group_id] = index+ self._groups.append(group)+ presets = group["presets"]+ assert isinstance(presets, dict)+ for preset_name, preset_details in presets.items():+ if preset_name in self._preset_semantics:+ raise PresetShapeDataError(+ f"Preset appears in multiple semantic groups: {preset_name!r}"+ )+ details = dict(group)+ details.pop("presets")+ details["preset"] = preset_name+ details.update(preset_details)+ details["recommended_for"] = _merge_strings(+ group["recommended_for"],+ preset_details.get("recommended_for", ()),+ )+ details["avoid_for"] = _merge_strings(+ group["avoid_for"],+ preset_details.get("avoid_for", ()),+ )+ self._preset_semantics[preset_name] = details++ expected = set(expected_names)+ actual = set(self._preset_semantics)+ missing = sorted(expected - actual)+ extra = sorted(actual - expected)+ if missing or extra:+ raise PresetShapeDataError(+ "Preset semantic catalog differs from ShapeTypeValues: "+ f"missing={missing}, extra={extra}"+ )++ @classmethod+ def bundled(cls) -> PresetShapeSemantics:+ """Load the semantic catalog shipped with PPT Master."""++ try:+ payload = json.loads(BUNDLED_SEMANTICS_PATH.read_text(encoding="utf-8"))+ except OSError as exc:+ raise PresetShapeDataError(+ f"Cannot read preset semantic catalog: {exc}"+ ) from exc+ except json.JSONDecodeError as exc:+ raise PresetShapeDataError(+ "Invalid preset semantic JSON at "+ f"line {exc.lineno}, column {exc.colno}: {exc.msg}"+ ) from exc+ return cls(payload, get_preset_registry().names)++ @property+ def preset_count(self) -> int:+ """Return the number of catalogued presets."""++ return len(self._preset_semantics)++ def describe(self, preset: str) -> dict[str, object]:+ """Return the resolved semantic record for one preset."""++ try:+ return dict(self._preset_semantics[preset])+ except KeyError as exc:+ raise UnknownPresetShapeError(+ f"Unknown DrawingML preset shape: {preset!r}"+ ) from exc++ def grouped(self, search: str = "") -> dict[str, object]:+ """Return a compact Office/group index and matching preset names."""++ query_tokens = _query_tokens(search)+ category_payloads: list[dict[str, object]] = []+ for category in self._categories:+ group_payloads: list[dict[str, object]] = []+ for group in self._groups:+ if group["office_category"] != category["id"]:+ continue+ presets = group["presets"]+ assert isinstance(presets, dict)+ matching_presets = []+ group_matches = _matches_query(+ {+ key: value+ for key, value in group.items()+ if key != "presets"+ },+ query_tokens,+ )+ for name, details in presets.items():+ if query_tokens and not group_matches and not _matches_query(+ {"preset": name, **details},+ query_tokens,+ ):+ continue+ matching_presets.append(name)+ if not matching_presets:+ continue+ recommended_for = group["recommended_for"]+ assert isinstance(recommended_for, tuple)+ group_payload = {+ "id": group["id"],+ "label": group["label"],+ "scope": group["scope"],+ "intent": recommended_for[0],+ "presets": matching_presets,+ }+ group_payloads.append(group_payload)+ if group_payloads:+ category_payloads.append({**category, "groups": group_payloads})+ return {+ "schema": self.schema,+ "sources": [dict(source) for source in self.sources],+ "preset_count": sum(+ len(group["presets"])+ for category in category_payloads+ for group in category["groups"]+ ),+ "search": search,+ "office_categories": category_payloads,+ }++ def recommend(+ self,+ *,+ roles: Sequence[str],+ scope: str = "general",+ relationships: Sequence[str] = (),+ directionality: str | None = None,+ aspect: str | None = None,+ text_capacity: str | None = None,+ visual_weight: str | None = None,+ query: str = "",+ limit: int = 12,+ ) -> dict[str, object]:+ """Return a diverse, semantics-matched candidate recall set."""++ query_tokens = _query_tokens(query)+ candidates: list[dict[str, object]] = []+ for details in self._preset_semantics.values():+ if scope != "all" and details["scope"] != scope:+ continue++ role_matches = [role for role in roles if role in details["roles"]]+ if not role_matches:+ continue+ relationship_matches = [+ relationship+ for relationship in relationships+ if relationship in details["relationships"]+ ]+ if relationships and not relationship_matches:+ continue+ if directionality and directionality not in details["directionality"]:+ continue+ if aspect and not _aspect_matches(details["aspects"], aspect):+ continue+ if text_capacity and not _capacity_matches(+ str(details["text_capacity"]),+ text_capacity,+ ):+ continue+ if visual_weight and details["visual_weight"] != visual_weight:+ continue++ query_score = _query_score(details, query_tokens, query)+ if query_tokens and query_score == 0:+ continue+ score = (+ len(role_matches) * 20+ + len(relationship_matches) * 12+ + (5 if directionality else 0)+ + (4 if aspect else 0)+ + (3 if text_capacity else 0)+ + (2 if visual_weight else 0)+ + query_score+ )+ why = [f"role={value}" for value in role_matches]+ why.extend(+ f"relationship={value}" for value in relationship_matches+ )+ if directionality:+ why.append(f"directionality={directionality}")+ if aspect:+ why.append(f"aspect={aspect}")+ if text_capacity:+ why.append(f"text_capacity>={text_capacity}")+ if visual_weight:+ why.append(f"visual_weight={visual_weight}")+ if query_tokens:+ why.append(f"query={query}")+ candidates.append({+ "score": score,+ "preset": details["preset"],+ "office_category": {+ "id": details["office_category"],+ "label": details["office_category_label"],+ },+ "group": details["id"],+ "scope": details["scope"],+ "intent": details["intent"],+ "why": why,+ "recommended_for": details["recommended_for"],+ "avoid_for": details["avoid_for"],+ "literal_only": details["literal_only"],+ })++ ordered = self._diverse_order(candidates)+ return {+ "criteria": {+ "roles": list(roles),+ "scope": scope,+ "relationships": list(relationships),+ "directionality": directionality,+ "aspect": aspect,+ "text_capacity": text_capacity,+ "visual_weight": visual_weight,+ "query": query,+ },+ "candidate_count": len(candidates),+ "returned_count": min(len(ordered), limit),+ "selection_note": (+ "Candidate recall only. Compare contour, content fit, and avoid_for "+ "before choosing; this is neither a whitelist nor an automatic choice."+ if ordered+ else "No candidates matched. This is a valid recall result; relax or "+ "change the criteria before selecting a contour."+ ),+ "candidates": ordered[:limit],+ }++ def _normalize_group(+ self,+ raw_group: object,+ index: int,+ ) -> dict[str, object]:+ label = f"catalog.groups[{index}]"+ group = _require_dict(raw_group, label)+ _reject_unknown_fields(+ group,+ label,+ {+ "id",+ "label",+ "office_category",+ "scope",+ "roles",+ "relationships",+ "directionality",+ "aspects",+ "text_capacity",+ "visual_weight",+ "literal_only",+ "recommended_for",+ "avoid_for",+ "presets",+ },+ )+ category_id = _require_string(+ group.get("office_category"),+ f"{label}.office_category",+ )+ if category_id not in self._category_by_id:+ raise PresetShapeDataError(+ f"{label} references unknown Office category {category_id!r}"+ )+ scope = _require_choice(group.get("scope"), f"{label}.scope", SEMANTIC_SCOPES)+ roles = _require_choices(group.get("roles"), f"{label}.roles", SEMANTIC_ROLES)+ relationships = _require_choices(+ group.get("relationships"),+ f"{label}.relationships",+ SEMANTIC_RELATIONSHIPS,+ )+ directionality = _require_choices(+ group.get("directionality"),+ f"{label}.directionality",+ SEMANTIC_DIRECTIONALITY,+ )+ aspects = _require_choices(+ group.get("aspects"),+ f"{label}.aspects",+ SEMANTIC_ASPECTS,+ )+ presets = _require_dict(group.get("presets"), f"{label}.presets")+ if not presets:+ raise PresetShapeDataError(f"{label}.presets must not be empty")+ normalized_presets: dict[str, dict[str, object]] = {}+ for preset_name, raw_details in presets.items():+ preset_label = f"{label}.presets[{preset_name!r}]"+ details = _require_dict(raw_details, preset_label)+ _reject_unknown_fields(+ details,+ preset_label,+ {+ "intent",+ "scope",+ "roles",+ "relationships",+ "directionality",+ "aspects",+ "text_capacity",+ "visual_weight",+ "literal_only",+ "recommended_for",+ "avoid_for",+ },+ )+ normalized_details: dict[str, object] = {+ "intent": _require_string(+ details.get("intent"),+ f"{preset_label}.intent",+ )+ }+ repeated_choices = {+ "roles": SEMANTIC_ROLES,+ "relationships": SEMANTIC_RELATIONSHIPS,+ "directionality": SEMANTIC_DIRECTIONALITY,+ "aspects": SEMANTIC_ASPECTS,+ }+ for field, choices in repeated_choices.items():+ if field in details:+ normalized_details[field] = _require_choices(+ details[field],+ f"{preset_label}.{field}",+ choices,+ )+ single_choices = {+ "scope": SEMANTIC_SCOPES,+ "text_capacity": SEMANTIC_TEXT_CAPACITIES,+ "visual_weight": SEMANTIC_VISUAL_WEIGHTS,+ }+ for field, choices in single_choices.items():+ if field in details:+ normalized_details[field] = _require_choice(+ details[field],+ f"{preset_label}.{field}",+ choices,+ )+ if "literal_only" in details:+ normalized_details["literal_only"] = _require_bool(+ details["literal_only"],+ f"{preset_label}.literal_only",+ )+ for field in ("recommended_for", "avoid_for"):+ if field in details:+ normalized_details[field] = _require_string_list(+ details[field],+ f"{preset_label}.{field}",+ )+ normalized_presets[preset_name] = normalized_details+ recommended_for = _require_string_list(+ group.get("recommended_for"),+ f"{label}.recommended_for",+ )+ avoid_for = _require_string_list(+ group.get("avoid_for"),+ f"{label}.avoid_for",+ )+ if not recommended_for or not avoid_for:+ raise PresetShapeDataError(+ f"{label}.recommended_for and avoid_for must not be empty"+ )+ return {+ "id": _require_string(group.get("id"), f"{label}.id"),+ "label": _require_string(group.get("label"), f"{label}.label"),+ "office_category": category_id,+ "office_category_label": self._category_by_id[category_id]["label"],+ "scope": scope,+ "roles": roles,+ "relationships": relationships,+ "directionality": directionality,+ "aspects": aspects,+ "text_capacity": _require_choice(+ group.get("text_capacity"),+ f"{label}.text_capacity",+ SEMANTIC_TEXT_CAPACITIES,+ ),+ "visual_weight": _require_choice(+ group.get("visual_weight"),+ f"{label}.visual_weight",+ SEMANTIC_VISUAL_WEIGHTS,+ ),+ "literal_only": _require_bool(+ group.get("literal_only"),+ f"{label}.literal_only",+ ),+ "recommended_for": recommended_for,+ "avoid_for": avoid_for,+ "presets": normalized_presets,+ }++ def _diverse_order(+ self,+ candidates: list[dict[str, object]],+ ) -> list[dict[str, object]]:+ candidates.sort(+ key=lambda item: (+ -int(item["score"]),+ self._group_order[str(item["group"])],+ self._preset_order[str(item["preset"])],+ )+ )+ ordered: list[dict[str, object]] = []+ scores = sorted({int(item["score"]) for item in candidates}, reverse=True)+ for score in scores:+ score_items = [item for item in candidates if item["score"] == score]+ first_by_group: list[dict[str, object]] = []+ remaining: list[dict[str, object]] = []+ seen_groups: set[str] = set()+ for item in score_items:+ group_id = str(item["group"])+ target = first_by_group if group_id not in seen_groups else remaining+ target.append(item)+ seen_groups.add(group_id)+ ordered.extend(first_by_group)+ ordered.extend(remaining)+ return ordered+++@lru_cache(maxsize=1)+def get_preset_shape_semantics() -> PresetShapeSemantics:+ """Return the process-wide, lazily loaded bundled semantic catalog."""++ return PresetShapeSemantics.bundled()+++def _require_dict(value: object, label: str) -> dict[str, object]:+ if not isinstance(value, dict):+ raise PresetShapeDataError(f"{label} must be a JSON object")+ return value+++def _reject_unknown_fields(+ value: dict[str, object],+ label: str,+ allowed: set[str],+) -> None:+ unknown = sorted(set(value) - allowed)+ if unknown:+ raise PresetShapeDataError(+ f"{label} contains unsupported fields: {', '.join(unknown)}"+ )+++def _require_list(value: object, label: str) -> list[object]:+ if not isinstance(value, list):+ raise PresetShapeDataError(f"{label} must be a JSON array")+ return value+++def _require_string(value: object, label: str) -> str:+ if not isinstance(value, str) or not value.strip():+ raise PresetShapeDataError(f"{label} must be a non-empty string")+ return value.strip()+++def _require_bool(value: object, label: str) -> bool:+ if not isinstance(value, bool):+ raise PresetShapeDataError(f"{label} must be a boolean")+ return value+++def _require_choice(value: object, label: str, choices: Sequence[str]) -> str:+ text = _require_string(value, label)+ if text not in choices:+ raise PresetShapeDataError(+ f"{label} must be one of {', '.join(choices)}; got {text!r}"+ )+ return text+++def _require_choices(+ value: object,+ label: str,+ choices: Sequence[str],+) -> tuple[str, ...]:+ values = _require_string_list(value, label)+ if not values:+ raise PresetShapeDataError(f"{label} must not be empty")+ unknown = sorted(set(values) - set(choices))+ if unknown:+ raise PresetShapeDataError(+ f"{label} contains unsupported values: {', '.join(unknown)}"+ )+ return values+++def _require_string_list(value: object, label: str) -> tuple[str, ...]:+ items = _require_list(value, label)+ values = tuple(+ _require_string(item, f"{label}[{index}]")+ for index, item in enumerate(items)+ )+ if len(values) != len(set(values)):+ raise PresetShapeDataError(f"{label} contains duplicate values")+ return values+++def _merge_strings(first: object, second: object) -> tuple[str, ...]:+ merged: list[str] = []+ for values in (first, second):+ assert isinstance(values, tuple)+ for value in values:+ if value not in merged:+ merged.append(value)+ return tuple(merged)+++def _query_tokens(query: str) -> tuple[str, ...]:+ normalized = _CAMEL_BOUNDARY_RE.sub(" ", query).casefold()+ return tuple(+ token+ for token in _QUERY_TOKEN_RE.findall(normalized)+ if token not in _QUERY_STOP_WORDS+ )+++def _search_text(value: object) -> str:+ if isinstance(value, str):+ return _CAMEL_BOUNDARY_RE.sub(" ", value).casefold()+ if isinstance(value, (list, tuple)):+ return " ".join(_search_text(item) for item in value)+ if isinstance(value, dict):+ return " ".join(_search_text(item) for item in value.values())+ return ""+++def _matches_query(details: dict[str, object], query_tokens: Sequence[str]) -> bool:+ if not query_tokens:+ return True+ haystack = _search_text(details)+ return all(token in haystack for token in query_tokens)+++def _query_score(+ details: dict[str, object],+ query_tokens: Sequence[str],+ query: str,+) -> int:+ if not query_tokens:+ return 0+ haystack = _search_text(details)+ matches = sum(1 for token in query_tokens if token in haystack)+ if matches == 0:+ return 0+ score = matches * 4+ normalized_query = " ".join(_query_tokens(query))+ if normalized_query and normalized_query in haystack:+ score += 10+ preset = str(details["preset"])+ if query.casefold() == preset.casefold():+ score += 20+ return score+++def _aspect_matches(values: object, requested: str) -> bool:+ assert isinstance(values, tuple)+ return requested in values or "flexible" in values+++def _capacity_matches(actual: str, requested: str) -> bool:+ return _TEXT_CAPACITY_RANK[actual] >= _TEXT_CAPACITY_RANK[requested]diff --git a/skills/ppt-master/scripts/preset_shape_svg.py b/skills/ppt-master/scripts/preset_shape_svg.pyindex 3bd574fa..4f3cacc8 100644--- a/skills/ppt-master/scripts/preset_shape_svg.py+++ b/skills/ppt-master/scripts/preset_shape_svg.py@@ -2,17 +2,21 @@"""PPT Master - Preset Shape SVG Fragment Tool-List DrawingML presets or print compact canonical native-preset SVG groups to-stdout for manual insertion into a hand-authored page or template.+Browse and recommend DrawingML presets, or print compact canonical+native-preset SVG groups to stdout for manual insertion into a hand-authored+page or template.Usage:- python3 scripts/preset_shape_svg.py list [--search QUERY]+ python3 scripts/preset_shape_svg.py list [--grouped] [--search QUERY]python3 scripts/preset_shape_svg.py describe PRESET+ python3 scripts/preset_shape_svg.py recommend --role ROLE [options]python3 scripts/preset_shape_svg.py render PRESET --id ID --frame X Y W Hpython3 scripts/preset_shape_svg.py render-batch --input FILE_OR_DASHExamples:- python3 scripts/preset_shape_svg.py list --search arrow+ python3 scripts/preset_shape_svg.py list --grouped+ python3 scripts/preset_shape_svg.py recommend --role spine \+ --relationship order --directionality horizontalpython3 scripts/preset_shape_svg.py describe rightArrowpython3 scripts/preset_shape_svg.py render rightArrow --id next-step \--frame 160 210 320 112 --fill "#2563EB" --stroke none@@ -32,6 +36,16 @@ from typing import Sequencefrom console_encoding import configure_utf8_stdiofrom pptx_shapes import CONNECTOR_PRESET_TYPES, get_preset_registry+from pptx_shapes.semantics import (+ SEMANTIC_ASPECTS,+ SEMANTIC_DIRECTIONALITY,+ SEMANTIC_RELATIONSHIPS,+ SEMANTIC_ROLES,+ SEMANTIC_SCOPES,+ SEMANTIC_TEXT_CAPACITIES,+ SEMANTIC_VISUAL_WEIGHTS,+ get_preset_shape_semantics,+)from pptx_to_svg.preset_authoring import render_preset_shape_fragment@@ -73,7 +87,18 @@ def build_parser() -> argparse.ArgumentParser:list_parser.add_argument("--search",default="",- help="Case-insensitive preset-name substring.",+ help=(+ "Case-insensitive preset-name substring; grouped output also "+ "searches semantic text."+ ),+ )+ list_parser.add_argument(+ "--grouped",+ action="store_true",+ help=(+ "Print a compact Office-category and semantic-group index with "+ "one-line intent summaries and preset names as JSON."+ ),)describe_parser = subparsers.add_parser(@@ -82,6 +107,65 @@ def build_parser() -> argparse.ArgumentParser:)describe_parser.add_argument("preset", help="DrawingML preset name.")+ recommend_parser = subparsers.add_parser(+ "recommend",+ help="Recall semantically matched preset candidates as JSON.",+ )+ recommend_parser.add_argument(+ "--role",+ action="append",+ required=True,+ choices=SEMANTIC_ROLES,+ help="Required page role; repeat to allow multiple roles.",+ )+ recommend_parser.add_argument(+ "--relationship",+ action="append",+ default=[],+ choices=SEMANTIC_RELATIONSHIPS,+ help="Required relationship fit; repeat to allow alternatives.",+ )+ recommend_parser.add_argument(+ "--scope",+ choices=("all", *SEMANTIC_SCOPES),+ default="general",+ help=(+ "Semantic scope. The general default excludes literal-only, "+ "flowchart, and navigation shapes."+ ),+ )+ recommend_parser.add_argument(+ "--directionality",+ choices=SEMANTIC_DIRECTIONALITY,+ help="Required direction or route character.",+ )+ recommend_parser.add_argument(+ "--aspect",+ choices=SEMANTIC_ASPECTS,+ help="Required frame tendency; flexible candidates also match.",+ )+ recommend_parser.add_argument(+ "--text-capacity",+ choices=SEMANTIC_TEXT_CAPACITIES,+ help="Minimum useful text capacity.",+ )+ recommend_parser.add_argument(+ "--visual-weight",+ choices=SEMANTIC_VISUAL_WEIGHTS,+ help="Required visual-weight band.",+ )+ recommend_parser.add_argument(+ "--query",+ default="",+ help="Optional English intent terms used to refine the recall set.",+ )+ recommend_parser.add_argument(+ "--limit",+ type=_positive_integer,+ default=12,+ help="Maximum returned candidates; default: 12.",+ )+render_parser = subparsers.add_parser("render",help="Print one canonical authored-preset <g> fragment to stdout.",@@ -184,6 +268,13 @@ def main(argv: Sequence[str] | None = None) -> int:registry = get_preset_registry()if args.command == "list":+ if args.grouped:+ payload = get_preset_shape_semantics().grouped(args.search)+ if payload["preset_count"] == 0:+ print(f"No preset semantics match {args.search!r}", file=sys.stderr)+ return 1+ print(json.dumps(payload, ensure_ascii=False, indent=2))+ return 0query = args.search.casefold().strip()names = [name for name in registry.names@@ -210,10 +301,26 @@ def main(argv: Sequence[str] | None = None) -> int:"path_count": len(definition.paths),"connection_site_count": len(definition.connections),"has_text_rectangle": definition.text_rectangle is not None,+ "semantics": get_preset_shape_semantics().describe(args.preset),}print(json.dumps(payload, ensure_ascii=False, indent=2))return 0+ if args.command == "recommend":+ payload = get_preset_shape_semantics().recommend(+ roles=args.role,+ scope=args.scope,+ relationships=args.relationship,+ directionality=args.directionality,+ aspect=args.aspect,+ text_capacity=args.text_capacity,+ visual_weight=args.visual_weight,+ query=args.query,+ limit=args.limit,+ )+ print(json.dumps(payload, ensure_ascii=False, indent=2))+ return 0+if args.command == "render-batch":try:items = _read_batch_items(args.input)@@ -260,6 +367,16 @@ def _parse_adjustments(values: Sequence[str]) -> dict[str, str]:return adjustments+def _positive_integer(value: str) -> int:+ try:+ number = int(value)+ except ValueError as exc:+ raise argparse.ArgumentTypeError("expected a positive integer") from exc+ if number < 1:+ raise argparse.ArgumentTypeError("expected a positive integer")+ return number++def _style_from_args(args: argparse.Namespace) -> dict[str, str]:return _style_from_values(fill=args.fill,