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

docs(image-layout): define addressable same-source crop workflow

hugohe3b708017abde3
diff --git a/skills/ppt-master/references/executor-image.md b/skills/ppt-master/references/executor-image.md
index 0539d137..064fa7db 100644
--- a/skills/ppt-master/references/executor-image.md
+++ b/skills/ppt-master/references/executor-image.md
@@ -23,9 +23,9 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
**Template-bundled images**: [`apply-template-workspace.md`](../workflows/stages/apply-template-workspace.md) copies them into project `images/`. Outside `mirror`, reference `../images/<name>` and never copy a template SVG's bare sibling href: the rendered page lives in `svg_output/`. `mirror` ([`executor-structured.md`](./executor-structured.md) §1.1) keeps hrefs verbatim; export resolves them against `images/`.
-**Reference — preferred pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once when this branch loads, then resolve every primary/modifier id in each active §VIII/lock row so the Strategist's recommendation is understood. Use it as a strong starting point, but adapt its geometry or choose another catalog/ordinary composition when the actual page can communicate better. Preserve the resource role, file/source, must-use status, crop policy, content, and explicit user/template constraints; a pattern-only change needs no upstream rewrite. Avoid generic left/right repetition.
+**Reference — preferred pattern, flexible realization**: Read [`image-layout-patterns.md`](./image-layout-patterns.md) once and resolve every active §VIII/lock pattern id. Adapt its geometry or composition when the page communicates better, while preserving resource role, source, must-use status, crop policy, content, and explicit user/template constraints. Pattern-only changes need no upstream rewrite. Avoid generic left/right repetition.
-**Reference — motion-ready image layering, not a constraint**: When the Executor adopts a §IX `Motion suggestion`, or an explicit user requirement calls for focus, comparison, evidence, reveal order, or cross-page continuation, decide during main SVG authoring whether the fully revealed composition benefits from separate visible semantic units. Useful splits include a stable image field plus annotation/hotspot groups, base and comparison images, a full view plus same-source crop/lens, atmosphere plus evidence, or a static field plus cutout foreground. For ordinary Slide-local content, keep stable framing/background static and wrap each independently revealable or cross-page continuing unit in a descriptive direct-root `<g id>`. Structured atoms/slots keep their declared boundaries and may serve as units only as-is. If existing legal units or a page transition already carry the communication job, add nothing. Effects, pairing, order, and timing belong to the later motion stage.
+**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.
@@ -35,4 +35,19 @@ Handle images by their status in the Design Spec's Image Resource List. Status e
**Crop policy**: read the §VIII row and matching lock projection. On every slide that uses a `crop=no-crop` source (or a legacy trailing `| no-crop`), retain one visible complete instance using one of the nine legal anchors with `meet`, never `none`, and no `clip-path`, `mask`, clipping overflow, or nested `<svg>` crop viewport. An auxiliary same-slide detail or lens may crop the same source only while that complete instance remains visible. `crop=adaptive` permits but never requires cropping; choose `meet` or focal-safe `slice` from purpose, ratio, focus, and container. A missing or conflicting `source` / `pattern` / `crop` projection returns upstream instead of being inferred during execution; the accurately projected `pattern` remains a preferred expression that may be adapted without rewriting the lock.
+**Hard rule — same-source addressable crops**: for binding use or pattern
+`#100`, reuse one exact `href` without slice assets. Give every
+independent/Morph object a stable
+page-unique id and a distinct nested crop wrapper under
+[`svg-effects.md`](./svg-effects.md) §6.5. Plain rectangles need no crop marker;
+shaped frames put `data-pptx-crop="1"` on the wrapper and a matching
+`userSpaceOnUse` clip on its inner `<image>`, never the wrapper. Repeated crops
+or SVG/PPT visual drift fail. Derive every wrapper `viewBox` from one shared
+source-to-page transform over the union of the visible containers. Never run
+`cover` / focal cropping independently per container: different container
+positions and heights must change the source-unit `x`, `y`, `width`, and
+`height` by the same union-relative mapping, so the gaps remove pixels without
+rescaling the scene. A compound clip on one `<image>` is pattern `#82`, not a
+substitute when the objects must remain independently editable or Morphable.
+
**Formula images — declared-inference fallback for a missing `no-crop` flag**: rows with `Acquire Via: formula` or `Type: Latex Formula` MUST be treated as no-crop. For a rendered file, use dimensions in this order: current `analysis/image_analysis.csv`, `design_spec.md §VIII`, then `images/formula_manifest.json`. For a `Needs-Manual` row, size the dashed placeholder from the planned dimensions in §VIII, then the manifest; the Step 7 readiness gate re-analyzes the supplied file and reconciles the container before export. Do not normalize all formulas to one height unless the spec explicitly states that layout choice.
diff --git a/skills/ppt-master/references/image-layout-patterns.md b/skills/ppt-master/references/image-layout-patterns.md
index b9878997..511bf7e4 100644
--- a/skills/ppt-master/references/image-layout-patterns.md
+++ b/skills/ppt-master/references/image-layout-patterns.md
@@ -4,7 +4,7 @@ A vocabulary registry of ways images can be placed on a slide. The point of this
Every entry has a name plus a short technical hint. Common techniques get a single line. Less obvious or easily forgotten techniques get a short paragraph — not a full tutorial, but enough that a model unfamiliar with the project can implement it without guessing. This is a registry, not a teaching document; no use-case prescriptions, no decision tables.
-> **Numbers are stable identifiers, not sequence.** The file is split into **Part 1 — Primary Structures** (#1–#19, #38–#56, #73–#81, #88, #92–#94) and **Part 2 — Modifier Layers** (#20–#37, #57–#72, #82–#87, #89–#91, #95–#99). Numbers jump within each Part because Primary structures were grouped first; existing references to `#38`, `#48`, etc. anywhere in the project still resolve correctly. **High-Yield Patterns** below is a router over those same numbers, not a third part — read it first, then jump to the entry it names.
+> **Numbers are stable identifiers, not sequence.** The file is split into **Part 1 — Primary Structures** (#1–#19, #38–#56, #73–#81, #88, #92–#94) and **Part 2 — Modifier Layers** (#20–#37, #57–#72, #82–#87, #89–#91, #95–#100). Numbers jump within each Part because Primary structures were grouped first; existing references to `#38`, `#48`, etc. anywhere in the project still resolve correctly. **High-Yield Patterns** below is a router over those same numbers, not a third part — read it first, then jump to the entry it names.
---
@@ -31,7 +31,8 @@ The patterns below are what separate a deck that looks designed from a deck that
| One ordinary photo must carry a cover or a chapter divider | `#90` scrim with shapes cut out + `#86` contour echo | Three elements turn a stock image into a designed page; the cut contour is where the page's character comes from |
| The supplied image does not fit the canvas | `#89` same image twice — sharp cutout over a receded copy | Subject at full fidelity in any aspect ratio; no stretching, no letterbox bars, no second asset |
| Several peer images belong to one frame | `#92` split tiling — one parent cut into interlocking cells | Edges interlock exactly; the group still reads as one object |
-| One image should appear inside several detached containers | `#82` one image shattered across separated shapes | Merge-Shapes look; the photo runs continuously behind the gaps |
+| One image should span detached containers as one edit object | `#82` one image shattered across separated shapes | Merge-Shapes look; the photo runs continuously behind the gaps |
+| Those same-source containers must remain independently editable or animated | `#100` same-source addressable crops | Several native picture objects share one source coordinate system without slice assets |
| A panel needs a real opening onto what is behind it | `#83` panel with a hole punched through it | True subtraction — survives a gradient, a texture, or a second image behind the panel |
| A photo row needs depth without 3D | `#94` embracing arc row, or `#93` containers arrayed along a curve | A perspective wall reproduced in 2D from scale + vertical offset alone |
| A flat scrim reads as a sheet of paint over the photo | `#98` grid scrim with per-cell opacity | The overlay reads as panelled glass or a contact sheet, felt rather than drawn |
@@ -43,7 +44,7 @@ The patterns below are what separate a deck that looks designed from a deck that
**Mandatory**: Pair a modifier-only router result with a content-appropriate Part 1 Primary as the page bones before §VIII. The pairing makes the recommendation complete; it does not lock Executor geometry or create a usage quota.
-**Hard rule — registration is what makes this family work**: in `#82`, `#85`, `#87`, `#89`, `#96`, and `#97`, the image stays anchored to the *union* of its containers, or the two copies stay in exact register. A few pixels of drift reads as a printing error, and giving each container its own image collapses the page into an ordinary tile grid. `#84` is the one pattern that breaks registration on purpose, and it only reads as a decision because the others establish the expectation.
+**Hard rule — registration is what makes this family work**: in `#82`, `#85`, `#87`, `#89`, `#96`, `#97`, and `#100`, the image stays anchored to the *union* of its containers, or the copies share one source coordinate system. A few pixels of drift reads as a printing error. `#84` alone breaks registration on purpose.
**Prepared-asset gate**: select `#96` only when a registered cutout PNG already exists, `#97` only when its blurred crop exists, and `#99` only when its desaturated copy exists. If not, keep the original asset and fall back to a native-shape treatment such as `#30` / `#29`; do not invent an image-processing step during execution.
@@ -160,7 +161,9 @@ This is the family that opens up the largest design space and the one AI is most
**Authoring**: compute each cell's contour and write it as its own `<path>` clip — the geometry is deterministic, so derive the cells rather than eyeballing them. `shape_boolean_svg.py render <svg-file> --operation fragment --source <id> --source <id> --id <result-id>` returns exactly these interlocking regions as separately addressable paths. Give every cell the same stroke (2px, background color) so the cuts read as designed seams.
- **Choosing between #92 and #82**: same construction, opposite content rule. One image across all cells (#82) says "these fragments are one thing"; a different image per cell (#92) says "these are peers, cut from one frame". Mixing them destroys both readings. Distinct from #50 / #51, where cells are independent rectangles that never shared a parent.
+ **Choosing between #92 and #82 / #100**: different images per cell (#92)
+ are peers. One registered source means one edit object (#82) or independent
+ same-source objects (#100).
52–53. **Filmstrip / stack** — a sequence of `<image>` with thin consistent gaps: horizontal, equal height and varying widths (**#52**), or vertical, aligned by width with shared annotations down one side (**#53**).
@@ -210,13 +213,31 @@ Stack any of these freely on top of a Primary structure. Multiple Modifiers per
25. **Layered paper-cut stack** — clip each image layer under the image-only contract in [`shared-standards-core.md`](./shared-standards-core.md) §1.2; draw vector layers directly in their final geometry. A small conditional shadow on each layer can create physical separation.
-82. **One image shattered across separated shapes (Merge Shapes look)** — a *single* `<image>` clipped by **one `<path>` whose `d` contains several disjoint subpaths** (`M … Z M … Z`), so one photo appears inside several detached containers — staggered rounded slices, a gapped 2×2 grid, a rotated cross. This is the SVG equivalent of PowerPoint's Merge Shapes 结合 → 相交, and export maps it to one picture with `custGeom`.
-
- **Geometry**: write each container as its own subpath in one `d`. A rounded rect is `M x+r,y H x+w-r A r,r 0 0 1 x+w,y+r V y+h-r A r,r 0 0 1 x+w-r,y+h H x+r A r,r 0 0 1 x,y+h-r V y+r A r,r 0 0 1 x+r,y Z`; repeat per container, all in the same `<path>`. Keep the subpaths disjoint so no winding rule is ever needed.
-
- **The one thing that makes or breaks it — registration**: place the `<image>` over the *union bounding box* of every subpath (not one image per shape), sized with `preserveAspectRatio="xMidYMid slice"`. The photo then runs continuously *behind* the containers and the gaps read as cuts through one scene. Give each container a different image and it instantly collapses into an ordinary tile grid (#50 / #51) — the continuity is the entire design, not the shapes.
-
- Distinct from #24 (one connected contour) and #47–#56 (every cell its own image). For non-trivial contours take the `d` from the `union` or `combine` operation of `shape_boolean_svg.py render` (see [`native-shape-authoring.md`](./native-shape-authoring.md) §6) instead of deriving it by hand. Clip-shape constraints — one direct shape child, no `fill-rule` / `clip-rule`, `<image>` targets only — are owned by [`shared-standards-core.md`](./shared-standards-core.md) §1.2.
+82. **One image shattered across separated shapes (Merge Shapes look)** — clip
+one `<image>` with one `<path>` containing disjoint closed subpaths. Size the
+image over their union so the scene remains continuous; export yields one
+picture with `custGeom`. Use `shape_boolean_svg.py render` `union` / `combine`
+for non-trivial contours and obey
+[`shared-standards-core.md`](./shared-standards-core.md) §1.2. Distinct from
+#24 (one contour), #47–#56 (different sources), and #100 (several pictures).
+
+100. **Same-source addressable crops** — repeat one exact `href` in independent
+nested crop wrappers with different source-unit `viewBox` values. They export
+as separate native picture objects for editing and Morph while assembling one
+registered scene without slice assets. Follow
+[`executor-image.md`](./executor-image.md) §1. Unlike #82 this yields several
+pictures; unlike #84 registration remains exact.
+
+ **Registration construction**: choose one visible container union
+ `U = (ux, uy, uw, uh)` and one source region
+ `S = (sx, sy, sw, sh)`. For a container
+ `F = (x, y, w, h)`, derive its source-unit crop as
+ `Sx = sx + (x-ux)/uw × sw`, `Sy = sy + (y-uy)/uh × sh`,
+ `Sw = w/uw × sw`, and `Sh = h/uh × sh`. Use that result as the nested
+ wrapper `viewBox`; do not choose each crop by eye and do not apply
+ independent `cover`. This makes irregular heights and gaps behave like
+ windows cut from one continuous image while keeping every window a native
+ picture object.
83. **Panel with a real hole punched through it (Subtract window)** — a solid or tinted panel with a shape-cut opening that reveals the image below, PowerPoint's Merge Shapes 剪除.
@@ -398,7 +419,7 @@ Combine freely. The "AI-default" failure mode is the opposite: defaulting to bar
| Benefits with one dominant proof image | `#80` |
| Light promotional page without photos | `#81` |
-**Reach for the boolean-geometry family (#82–#99) before adding another photo to the page.** Routing, the registration invariant, and the skip-detection signal are in **High-Yield Patterns** at the top of this file.
+**Reach for the boolean-geometry family (#82–#100) before adding another photo to the page.** Routing, the registration invariant, and the skip-detection signal are in **High-Yield Patterns** at the top of this file.
**Cross-page through-line (recurring motif).** The patterns above are per-page, but a deck reads as *designed* when one illustration motif family recurs across pages—a cover anchor, section dividers repeating the motif (`#75`), and small `#63` spots threaded through the body. Keep one family (shared rendering / locked deck colors / subject world), vary scale and placement, and never turn recurrence into a quota.
diff --git a/skills/ppt-master/references/shared-standards-core.md b/skills/ppt-master/references/shared-standards-core.md
index 15d483cf..38dffcce 100644
--- a/skills/ppt-master/references/shared-standards-core.md
+++ b/skills/ppt-master/references/shared-standards-core.md
@@ -171,9 +171,9 @@ diagnostic behavior are indexed in
### 1.2 Image Clipping (Conditional Contract)
-`clip-path` has a native picture-geometry mapping only on SVG-namespace
-`<image>` elements (plus the exact imported crop wrapper defined under Images)
-and only under this contract:
+`clip-path` maps natively only on SVG `<image>` (including an exact crop
+wrapper's inner image) under this contract. Legacy imported crops may retain
+an outer-wrapper clip as compatible input:
| Concern | Required form |
|---|---|
@@ -181,7 +181,7 @@ and only under this contract:
| Contains exactly one direct SVG-namespace supported shape child | Multiple shapes are not composited |
| Shape is one of: `<circle>`, `<ellipse>`, `<rect>` (optional rx/ry), `<path>`, `<polygon>` | These map to DrawingML geometry (preset or custom) |
| No `clip-rule` or `fill-rule`, whether direct or in inline `style` | DrawingML picture geometry has no equivalent winding-rule control |
-| Used only on `<image>` or an exact imported crop wrapper | Shapes, groups, text, and generalized nested SVG targets are **forbidden** |
+| Used only on `<image>` or a compatible legacy imported crop wrapper | Shapes, groups, text, and generalized nested SVG targets are **forbidden** |
| SVG clip shape | DrawingML output |
|---|---|
diff --git a/skills/ppt-master/references/svg-effects.md b/skills/ppt-master/references/svg-effects.md
index 48baad9a..c9c095c3 100644
--- a/skills/ppt-master/references/svg-effects.md
+++ b/skills/ppt-master/references/svg-effects.md
@@ -278,34 +278,23 @@ unresolved only during template checking; export requires the resolved image.
Missing, ambiguous, corrupt, mislabeled, or unsupported sources are errors and
must never be dropped or packaged as invalid zero-byte media.
-**Hard rule — nested SVG is an imported crop transport, not a general
-viewport**: every non-root `<svg>` must be the exact picture-crop wrapper emitted
-by `pptx_to_svg`. The outer element has explicit registered project-geometry
-`x`, `y`, positive `width`/`height`, a unit-coordinate `viewBox` made of four
-ordinary decimal values, and
-`preserveAspectRatio="none"`; it contains exactly one direct, empty `<image>`
-with exactly one non-empty `href` or `xlink:href`, `x="0"`, `y="0"`, `width="1"`,
-`height="1"`, and `preserveAspectRatio="none"`. Its ancestor chain contains
-only the root SVG and ordinary visual `<g>` wrappers; definitions, text,
-render-only geometry details, and other non-visual containers cannot own this
-transport. The outer wrapper may additionally carry `id`, a supported
-`transform`, registered structure metadata (`data-pptx-layer` or
-`data-pptx-carrier`), and the importer metadata
-`data-pptx-frame`, `data-pptx-object`, `data-pptx-shape-id`,
-`data-pptx-shape-name`, and `data-pptx-shape-scope`. A shape clip is present
-only when exact `data-pptx-crop="1"` and a registered image-only `clip-path`
-occur together and the local clip definition resolves. The inner image may
-add only registered `opacity`. The `viewBox` must quantize without clamping to
-a DrawingML `srcRect` with a positive visible region: each signed crop value
-must fit the OOXML percentage integer range `-2147483648..2147483647`, while
-`l + r < 100000` and
-`t + b < 100000` preserve a positive visible region. Negative crop values and
-crop windows extending outside the source unit rectangle are retained exactly,
-not clamped. `0 0 1 1` is redundant and must be written as a plain `<image>`.
-Extra visual children, indirect images, character data, unknown attributes,
-malformed or unrepresentable crop coordinates, and generalized nested
-viewports are errors. Checker and the converter share this parser so a nested
-subtree cannot pass validation and then silently disappear during export.
+**Hard rule — nested SVG is picture-crop transport, not a general viewport**:
+every non-root `<svg>` is the exact wrapper accepted by the shared crop parser:
+
+| Part | Required form |
+|---|---|
+| Outer | Registered `x`, `y`, positive `width`/`height`; four ordinary-decimal unit coordinates in `viewBox`; `preserveAspectRatio="none"`; `overflow="hidden"` |
+| Child | Exactly one direct empty `<image>` with one non-empty `href`/`xlink:href`, `x="0" y="0" width="1" height="1" preserveAspectRatio="none"` |
+| Context | Only root SVG / ordinary visual `<g>` ancestors; outer may add `id`, supported `transform`, registered layer/carrier metadata, and `data-pptx-frame`, `data-pptx-object`, `data-pptx-shape-id`, `data-pptx-shape-name`, `data-pptx-shape-scope` |
+| Shape crop | Exact outer `data-pptx-crop="1"`; authored wrappers put the registered, locally resolving image-only clip on the inner image, using `userSpaceOnUse` geometry matching the visible `viewBox`; legacy imported outer clips remain compatible |
+
+The inner image may add only registered `opacity` and that clip. Quantize the
+`viewBox` without clamping: every signed crop fits
+`-2147483648..2147483647`, with `l + r < 100000` and `t + b < 100000`.
+Retain negative/outside-source crops exactly; write redundant `0 0 1 1` as a
+plain `<image>`. Extra, indirect, or character content; unknown attributes;
+malformed or unrepresentable crops; and general nested viewports fail. Checker
+and converter share this parser.
| Overlay | Construction | Typical stops / alpha |
|---|---|---|
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 79610938..c96158ec 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -594,7 +594,10 @@ Behavior:
- After normal-flow publication, native export writes `validation/<output_stem>.report.json`. The report distinguishes authored Slides from internal Layout definitions, reruns ZIP integrity and published Slide-count checks, records slide/layout/master/notes part counts, labels relationship/structured/transition/animation validation as enforced at build time, links the final SVG quality report only when its SHA-256 source fingerprint matches the exact export inputs, and surfaces stale/unverified gates, unresolved template tokens, generic-only font stacks, and external image references. A matching final quality report with introduced warnings yields `passed-with-warnings` and a `quality_introduced_warnings=<N>` receipt instead of a clean `passed` claim.
- By default, a successful command also prints a compact receipt instead of requiring a report read: `[POSTFLIGHT] status=<...> quality_gate=<...> slides=<N> warning_categories=<N>`, followed by one compact line per warning category and the `[PPTX]` / `[REPORT]` paths. Resource-warning lines carry counts; a non-passing quality gate carries its status. Routine agents use this receipt and do not load either complete validation JSON into model context. Full reports remain cold audit artifacts; failure investigation and explicit audits extract only the required fields. `--quiet` keeps suppressing successful-run output.
- Before publishing structured template output, export reopens the temporary PPTX and validates the Slide → Layout → Master graph and registrations, Layout identity, placeholder identity, reusable bounds, and prompt/level-one sizes. A mismatch aborts publication. Flat release instead validates its single referenced Master/Layout shell and exact date/footer/slide-number hook roster before packaging.
-- SVG clip paths are still restricted for authored SVGs, but nested crop wrappers generated by PPTX import are mapped back to native picture crop / geometry when possible.
+- Authored SVG clip-path restrictions remain. Crop wrappers use an
+ overflow-hidden viewport; preview-safe shape clips target the inner image in
+ viewBox coordinates, while legacy imported wrapper clips remain compatible.
+ Both map to native picture crop/geometry when possible.
- Normal flow embeds speaker notes automatically unless `--no-notes` is used; quick-test always disables them
- Recorded narration is opt-in:
- `notes_to_audio.py` uses `edge-tts` by default, or a configured cloud TTS provider (`elevenlabs`, `minimax`, `qwen`, `cosyvoice`), and generates one audio file per slide into `audio/`