Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(image-layout): add directional multi-image composition grammar

hugohe386defe088a61
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.md
index b9a48d28..7164eae1 100644
--- a/skills/ppt-master/references/executor-image.md
+++ b/skills/ppt-master/references/executor-image.md
@@ -30,21 +30,40 @@ Handle images by status; enum and lifecycle: [`svg-image-embedding.md`](svg-imag
**Default — active image integration (may override when plain placement is
stronger)**: Treat loaded [`image-layout-patterns.md`](./image-layout-patterns.md)
as vocabulary and [`image-layout-spec.md`](./image-layout-spec.md) as math, not
-a quota or lock. Run the catalog's §7 playbook before drawing; its combinations
-are recall aids, not coverage targets. A `#P...` suggestion completes only the
-page skeleton; omitted `M`, effect, Boolean, or native overlay leaves
-realization open and never means “keep plain.” For every image-bearing page,
-derive the image/content or image/shape relationship from its communication job,
-hierarchy, copy, asset ratio/focus, and deck rhythm. Before drawing, form one
-relevant treatment candidate, compare it with `P`-only, implement the stronger
-legal composition, and realize any adopted treatment through the already-loaded
-[`svg-effects.md`](./svg-effects.md) and
-[`native-shape-authoring.md`](./native-shape-authoring.md). This is an opportunity
-pass, not an effect quota. Deepen, simplify, replace, or combine suggestions;
-plain placement remains valid when it communicates better. Preserve role/source,
+a quota or lock. A `#P...` suggestion is only a skeleton; deepen, simplify, or
+combine it through the already-loaded [`svg-effects.md`](./svg-effects.md) and
+[`native-shape-authoring.md`](./native-shape-authoring.md). Plain placement or a
+regular grid remains valid when it communicates better. Preserve role/source,
must-use, crop/content, and explicit user/template constraints; expression-only
changes need no upstream rewrite.
+**Mandatory — per-page image composition decision**: Using this already-loaded
+branch, decide once immediately before geometry on every page containing a
+non-formula image and keep the result only in active context:
+`role → direction generator → parent contour → slots/rhythm → crop →
+image-shape action → labels/overlays → depth/continuity`. Derive the relationship
+from the communication job, hierarchy, copy, asset ratio/focus, and deck rhythm;
+use `anchor`, `continue`, `bridge`, `overlap`, `reveal`, `echo`, or `register`
+only when useful. Compare the resulting candidate with plain/`P`-only placement
+and implement the stronger legal composition. Create no artifact or extra pass,
+and do not reread the branch while its active context remains valid.
+
+**Reference — direction generators, not templates**:
+
+| Generator | Behavior |
+|---|---|
+| `vector` | Progress slots along one shared movement vector |
+| `shared-baseline` | Share a baseline while size, offset, or overlap changes systematically |
+| `curve-spine` | Derive slots and turns from one continuous curve or folded path |
+| `panel` | Subdivide one coherent tilted, stepped, or polygonal parent panel |
+| `none/grid` | Retain calm plain placement or a regular grid |
+
+**Default — coherent multi-image direction (may override when deliberate disorder
+serves the communication job)**: Within one image group, derive slot positions,
+crop edges, overlap, and any rotation from one primary direction generator.
+Varied angles need one declared rhythm or collision rule; they are not a shortcut
+to variety.
+
**Reference — motion-ready image layering, not a constraint**: For adopted §IX or an explicit focus, comparison, evidence, reveal-order, or cross-page requirement, decide during SVG authoring whether the final composition needs separate visible units. Keep ordinary stable framing/background static and wrap each independently revealed or continuing Slide-local unit in a descriptive direct-root `<g id>`; structured atoms/slots retain their boundaries. Existing units or a page transition may suffice. The motion stage owns effects, pairing, order, and timing.
**Hard rule — visible-layer timing**: Any crop, lens, scrim, comparison, evidence, or annotation layer required by an adopted motion plan MUST already exist in the final SVG without violating structural contracts. The later stage may regroup ordinary Slide-local content visual-equivalently, but cannot invent or modify missing visible content. If no legal existing unit can serve a non-binding suggestion, simplify it to available units, a page transition, or `none`; an explicit requirement that cannot be represented follows failure recovery.
diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.md
index 526e5116..6b77bbdb 100644
--- a/skills/ppt-master/references/image-layout-spec.md
+++ b/skills/ppt-master/references/image-layout-spec.md
@@ -149,7 +149,56 @@ Use weighted tracks when one item is primary. A spanning item receives the sum o
### 4.3 Free multi-item composition
-For montage, arc, overlap, or another non-grid arrangement, assign one explicit region to every item and verify the union against `(W,H)`. Reuse one gap/rhythm system where separation is intended; overlap is explicit geometry, not a negative-gap accident.
+**Mandatory**: For montage, arc, overlap, or another non-grid arrangement, give
+every carrier a finite center and positive size, give every intended overlap an
+unambiguous front item, and verify the visible union against `(W,H)`.
+
+**Default — shared direction (may override when deliberate disorder serves the
+communication job)**: Select one direction generator and derive related carriers
+from shared geometry. An override still declares a bounded placement/angle rule
+so disorder is authored rather than accidental. Use the following state:
+
+| State | Definition |
+|---|---|
+| `p[i] = (cx[i], cy[i])` | Explicit center of item `i` |
+| `(w[i], h[i])` | Explicit positive carrier size |
+| `s[i] > 0` | Optional shared size rhythm: `(w[i], h[i]) = s[i] × (w0, h0)` |
+| `P` (optional) | Parent contour controlling the outer silhouette, shared seam, reveal, or attachment path |
+| `V[i]` | Visible carrier after applying its clip and, when `P` is a silhouette, intersecting it with `P` |
+| `z[i]` | Stacking rank required for carriers that overlap |
+
+For a straight shared direction `θ`, calculate centers in its local frame:
+
+```text
+d = (cos(θ), sin(θ))
+n = (-sin(θ), cos(θ))
+p[i] = p0 + t[i] × d + e[i] × n
+```
+
+Choose `t[i]` and transverse offset `e[i]` as explicit sequences; add `s[i]`
+when scale carries the rhythm. Reuse a progression when rhythm is intended; do
+not substitute unrelated per-item values.
+
+| Generator | Executable rule |
+|---|---|
+| `vector` | Use the straight-frame equation with ordered `t[i]`; set `t[i+1] = t[i] + advance[i]`, where each `advance[i] > 0`. Control overlap through `advance[i]`, not an accidental negative gap. |
+| `shared-baseline` | Choose baseline `B(t) = b + t × d`. If `r[i]` is the carrier's half-extent along `n`, place `p[i] = B(t[i]) + r[i] × n`; this keeps one carrier edge on the same baseline while sizes vary. |
+| `curve-spine` | Choose ordered parameters `u[i]` on `C(u)` with `||C'(u[i])|| > 0`. Set `d[i] = normalize(C'(u[i]))`, `n[i] = (-d[i].y, d[i].x)`, and `p[i] = C(u[i]) + e[i] × n[i]`; at a zero derivative, use the secant between nearest distinct samples or another generator. |
+| `panel` | Define one convex 2D quadrilateral `A,B,C,D` in consistent winding and `F(u,v) = (1-u)(1-v)A + u(1-v)B + uvC + (1-u)vD`. Split monotone `u`/`v` intervals; each cell uses its four `F` corners. |
+
+For each intended overlap, calculate `area(V[i] ∩ V[j]) > 0` and assign the
+front item through `z[i]` and `z[j]`. `P` must visibly control at least one
+listed structural role; otherwise use the selected region boundary and omit it.
+
+**Reference — not a constraint**: Use one of these angle mechanisms according to the selected composition:
+
+| Mechanism | Geometry |
+|---|---|
+| Clip-shape angle | Keep the bitmap upright and angle only the carrier contour or clip path. |
+| Parent-group rotation | Build the complete arrangement first, then rotate its carriers, frames, and attached labels together around one pivot. |
+| Tangent rotation | On `curve-spine`, rotate item `i` around `p[i]` by `atan2(d[i].y, d[i].x)` when the carriers should follow the path. |
+
+**Forbidden — unsupported image deformation**: Do not use shear, skew, or true perspective mapping. A `panel` is a set of 2D quadrilateral clips/crops; it does not warp the image plane.
---
@@ -178,6 +227,11 @@ Contain each formula independently in its lane. When formulas are visual peers,
| Adjacent text/content region cannot carry its material | Reweight or change the selected relationship |
| Equal cells imply equality that the content does not have | Use weighted tracks or a free composition |
| Peer images use inconsistent visual scale without meaning | Normalize their regions or make the hierarchy explicit |
+| A free carrier lacks an explicit center or positive size, or an intended overlap lacks stacking order | Supply the missing geometry or z-order before drawing |
+| Items intended as one system lack both a shared direction and a deliberate-disorder rule | Derive them from one vector, baseline, curve, panel, or bounded override |
+| Per-item angles vary without a shared direction or deliberate-disorder rule | Use one parent-group angle, a shared clip-shape direction, curve tangents, or a bounded angle rhythm |
+| The parent contour does not affect silhouette, seam, reveal, or attachment | Remove it or reconstruct the carriers from that contour |
+| A panel depends on shear, skew, or perspective warping | Replace it with 2D quadrilateral carriers and focal-safe crops |
| Formula symbols become unreadable at the intended viewing size | Enlarge its region or restructure the page |
| Gaps, alignments, or overlaps drift without purpose | Recalculate from the shared region and gap values |
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index cb098bbf..8f11aeb9 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -323,19 +323,33 @@ follows its resolved behavior without inventing a nearby preset.
Do not load `executor-base.md`: it owns Default's persisted-plan handoff,
first-page gate, and completion routing. Excluding that file is not a capability
exclusion; Quick loads the shared and conditional execution authorities here
-directly. For any image/formula, always read
+directly. When any image/formula exists, read once before the first affected
+page and reuse throughout the valid execution context:
[`executor-image.md`](../../references/executor-image.md),
[`image-layout-spec.md`](../../references/image-layout-spec.md),
[`image-layout-patterns.md`](../../references/image-layout-patterns.md), and
[`svg-image-embedding.md`](../../references/svg-image-embedding.md); add
[`executor-web-image.md`](../../references/executor-web-image.md) for a sourced
-web image. Load [`canvas-formats.md`](../../references/canvas-formats.md) only
-for a non-default canvas.
+web image. Reread only after a known file change or context invalidation. Load
+[`canvas-formats.md`](../../references/canvas-formats.md) only for a non-default
+canvas.
`executor-structure.md` is loaded once before all SVG authoring so Quick cannot
omit shape-composition reasoning. Reuse it throughout the valid execution
context; reread only after a known file change or context invalidation.
+**Mandatory — per-image-page composition decision**: For every page with one
+or more non-formula images, after its content and communication move are
+determined but before choosing geometry, apply
+[`executor-image.md`](../../references/executor-image.md)'s active image-integration
+decision once. Keep its role, direction source, parent
+contour, slot/rhythm system, image/shape action, and any continuity only in
+active context; create no artifact, spec, lock, manifest, or extra pass. A
+deliberate plain or equal-grid result remains valid when it communicates the
+relationship better. Formula-only pages use
+[`image-layout-spec.md`](../../references/image-layout-spec.md) without forcing a
+multi-image system.
+
**Mandatory — per-page Structure decision**: after the current page's content
and communication move are determined, but before choosing any geometry or
shape, decide whether geometry must carry qualitative `order`, `link`, `parent`,
@@ -444,6 +458,7 @@ or lock.
- [x] All required source/resource preparation is complete
- [x] One mode and visual style were resolved, and every catalog source actually used was read
- [x] Every page considered the complete visual-carrier menu without a coverage quota
+- [x] Every non-formula image-bearing page made its one pre-geometry composition decision
- [x] Resolved SVG pages and their project-local references exist
- [x] Every role declared by an installed template spec is locatable in the finished pages, or its non-use is deliberate — checked per installed spec, not from memory
- [x] Every triggered capability-specific preparation and pre-checker verification completed