| 1 | > See [`executor-base.md`](./executor-base.md) for shared authoring and [`executor-chart.md`](./executor-chart.md) / [`executor-table.md`](./executor-table.md) for other information models. |
| 2 | |
| 3 | # Executor Shape Composition Grammar |
| 4 | |
| 5 | Runtime grammar for Slide-local qualitative relationships built from editable shapes; it is not a diagram/template catalog. |
| 6 | |
| 7 | **Load**: Default and Quick read this grammar once with their fixed construction |
| 8 | bundle before all SVG authoring and reuse it for every per-page decision. Loading |
| 9 | the grammar does not select `Structure=yes` or create a geometry quota. |
| 10 | |
| 11 | **Hard rule — no Structure catalog**: never recall or resolve `structure/<key>`. Compose from authoritative content, §IX relationships, the communication move, and the active visual system. |
| 12 | |
| 13 | **Hard rule — not structured PPTX**: this branch owns Slide-local geometry. [`executor-structured.md`](./executor-structured.md) independently owns reusable Master/Layout/placeholders under `pptx_structure.mode: structured`; neither implies the other. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## 1. Relationship Atoms |
| 18 | |
| 19 | | Atom | Meaning | Encode with | |
| 20 | |---|---|---| |
| 21 | | `order` | Sequence, progression, or rank | Position, numbering, direction, shared path | |
| 22 | | `link` | Dependency, exchange, influence, transition | Proximity/alignment when unmistakable; otherwise an edge | |
| 23 | | `parent` | One unit governs or decomposes into children | Branching, indentation, nesting, scale | |
| 24 | | `membership` | Units belong to a group, stage, lane, or region | Containment, shared field, band, repetition | |
| 25 | | `contrast` | Peers, states, options, or positions compare | Shared baseline, opposing regions, parallel framing | |
| 26 | | `overlap` | Units share a meaningful subset or duty | Intersecting regions plus a clear common area | |
| 27 | |
| 28 | Combine atoms as needed; never force a named business model. Numbers used only as labels do not create a chart. Value-derived position/length/angle/area/radius/width/color routes to [`executor-chart.md`](./executor-chart.md); row-header × column-header facts route to [`executor-table.md`](./executor-table.md). Qualitative lanes use this grammar, but date/duration-driven task-bar `x`/`width` is Gantt Chart geometry. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## 2. Shape Roles and Operations |
| 33 | |
| 34 | | Role | Job | |
| 35 | |---|---| |
| 36 | | `field` | Page/local region where a relationship operates | |
| 37 | | `node` | Semantic unit, state, actor, item, or group; may punctuate a drawn carrier as a stop, turn, junction, or bridge | |
| 38 | | `spine` | Explicit/implied scaffold or continuous carrier establishing reading direction | |
| 39 | | `edge` | Necessary semantic connection, branch, dependency, or transition | |
| 40 | | `label` | Text/evidence attached directly or by a non-relational leader/tether to a node, edge, region, or relationship | |
| 41 | | `garnish` | Non-semantic accent added after the relationship works | |
| 42 | |
| 43 | | Operation | Job | |
| 44 | |---|---| |
| 45 | | `repeat` | Create peers from one visual family; clone the full contour only when their structural states match | |
| 46 | | `arrange` | Establish order, alignment, rhythm, rank, comparison | |
| 47 | | `transform` | Vary scale, rotation, crop, fill, emphasis, or entry/continuation/turn/terminal port state meaningfully | |
| 48 | | `connect` | Add an edge when layout/containment is insufficient | |
| 49 | | `region` | Partition, contain, intersect, band, or layer fields | |
| 50 | | `attach` | Bind labels, badges, annotations, or evidence to an owner | |
| 51 | |
| 52 | **Hard rule — realization enters the construction gate**: Decide whether each |
| 53 | role is implicit/direct content or drawn geometry. Every drawn field, spine, |
| 54 | node carrier, or edge follows [`native-shape-authoring.md`](./native-shape-authoring.md) |
| 55 | §§1–2.1: contour before encoding → simplest exact native form → independent |
| 56 | compound → required Boolean → necessary freeform. Text styling cannot replace |
| 57 | required geometry; implicit/direct roles need no container. Decoration cannot |
| 58 | invent a relationship. |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ## 3. Construction Order |
| 63 | |
| 64 | Choose the field and map required atoms, then follow: |
| 65 | |
| 66 | **Mandatory — spine/topology → nodes → connectors → labels → garnish**: |
| 67 | |
| 68 | | Layer | Completion evidence | |
| 69 | |---|---| |
| 70 | | `spine` | Entry, direction, and organizing path are clear; reversal, cycle, split/merge, or stage change reshapes a continuous carrier before node placement | |
| 71 | | `nodes` | Every required unit has one home and intentional weight; each is direct content or a §2-approved carrier; carrier-crossing nodes intentionally continue, stop, turn, join, or bridge its visible path | |
| 72 | | `connectors` (`edge`) | Only unresolved semantic links become edges; route/source/target is clear; every drawn edge passes §2 | |
| 73 | | `labels` | Copy and caveats visibly attach directly or by leader/tether to what they explain; when a node has multiple text roles, cue → claim/value → support → note remains perceptibly descending and absent roles stay absent | |
| 74 | | `garnish` | Removing accents leaves all meaning intact | |
| 75 | |
| 76 | **Hard rule — relationship before styling**: establish atoms, field, spine, nodes, and necessary edges before palette, type, effects, or containers. Prefer containment, alignment, baselines, and proximity; add lines/Connectors only for real edges, never to make a page look process-like. |
| 77 | |
| 78 | **Default — visible structural composition (may override for naked-text |
| 79 | rhythm/style)**: Make one relationship-bearing field, spine, node carrier, or |
| 80 | directional shape the page-scale move; never add geometry merely because |
| 81 | Structure is `yes`. When drawn roles interact, resolve relationship-bearing |
| 82 | parent contour/direction → contact → joint or intentional void → |
| 83 | z-order/occlusion → canvas-edge behavior before labels/garnish. Skip |
| 84 | inapplicable operations; implicit/direct roles remain container-free. |
| 85 | |
| 86 | --- |
| 87 | |
| 88 | ## 4. Validation |
| 89 | |
| 90 | | Check | Pass condition | |
| 91 | |---|---| |
| 92 | | Coverage | Every authoritative atom is visible; none was invented | |
| 93 | | Reading path | Entry, progression, hierarchy, and endpoint are unambiguous | |
| 94 | | Roles | Nodes/edges have one duty; garnish carries no meaning | |
| 95 | | Attachment | Labels/evidence belong to the correct node, edge, or region | |
| 96 | | Removal | Without color/effects/icons/garnish, placement still communicates | |
| 97 | | Fidelity | All required units, qualifiers, values, and caveats remain | |
| 98 | | Construction | Drawn roles pass §2; implicit/direct roles need no carrier; freeform follows failed exact-native/independent-compound/Boolean routes | |
| 99 | | Composition | Every used contact, void, overlap, cutout, occlusion, or canvas-edge crossing maps to an atom/role or remains removable garnish; none obscures ownership or reading path | |
| 100 | |
| 101 | Load Chart/Table branches independently for embedded objects. Keep one dominant reading path while allowing secondary atoms whose ownership stays clear. |
| 102 |