/ppt-master

PPTX Transition Core

The shared transition core owns page-transition vocabulary, slide-advance semantics, OOXML mutation, MCE preservation, package timing enablement, and read-back validation for every PPTX route.

1. Ownership

Hard rule: adapters resolve route policy, then call the shared core. They must not build, replace, or patch a transition with route-local XML or regex.

2. Domain Model

Enter policy:

Advance mode:

Hard rule: enter=none may coexist with a sound and/or timed advance. The valid result is a non-visual p:transition with p:sndAc, advance attributes, or both, and no visual-effect child.

3. Compatibility Contract

The native registry covers the complete current PowerPoint transition gallery: 12 Subtle effects, 29 Exciting effects, and 7 Dynamic Content effects. New selection, sidecars, plans, conversion traces, help, and writers use only these 48 native keys.

Eight established low-level names remain valid at input boundaries. They normalize to one native effect plus native effect_options; they are not a second transition registry:

Standard PresentationML effects use a direct p:transition carrier:

Office 2010 effects use a p14 Choice with a p:fade Fallback:

Office 2012 effects use a p15 Choice with a p:fade Fallback:

morph uses p159:morph option=byObject in an Office 2015 Choice with a p:fade Fallback. none is the explicit no-visual-effect input and therefore is not a registry entry.

3.1 Native Effect Options

Use effect_options only with an explicit native effect. Omitted options use the PowerPoint-authored default reported by --describe-transition:

Example:

{
  "transition": {
    "effect": "page_curl",
    "effect_options": {
      "direction": "left",
      "pages": "double"
    },
    "duration": 0.6,
    "sound": "sounds/bigsoundbank/<file>.wav"
  }
}

transition.sound is optional and accepts a .wav path resolved by the generated-project adapter. A bundled-library choice is synced on demand only after the visual transition plan is complete, then referenced by its project-relative sounds/<namespace>/<file>.wav path. The adapter packages the file and passes the shared core an embedded relationship id/name; the core never reads templates/sounds/ or resolves library ids.

Inspect the exact contract, including compatibility desugaring:

python3 skills/ppt-master/scripts/pptx_animations.py --describe-transition page_curl
python3 skills/ppt-master/scripts/pptx_animations.py --describe-transition diamond

Read-back reports the canonical native effect, its complete effective options, the raw OOXML child, and raw attributes. This makes option loss a validation failure rather than a silent downgrade.

Hard rule — no downgrade:

• Never rename or remove an established effect.
• Never omit its established direction or split attributes.
• Reject an unknown requested effect; never substitute fade.
• Preserve an unknown source effect when the route selects preserve.
• An extension counts as successful only when the primary Choice contains the requested effect. A fallback alone is not success.

3.2 Deterministic Morph Identity

The generated route may add an explicit slides.<destination>.morph block to bind direct-root SVG groups across adjacent slides. The sidecar stable key is lowered to the same top-level p:cNvPr@name="!!<key>" on both final Slide-local objects. This does not create an Animation Pane row and does not change either object's numeric shape id.

The full plan is resolved before any SVG conversion so a source group named by the following slide remains a stable top-level target. Names are written only after flat/structured/preserve processing has finished; structured slide-shape roster expectations are then refreshed. Package read-back requires:

• the declared source to be the immediately preceding public slide;
• exactly one !!<key> object on each side;
• the same OOXML object container type on both sides;
• Morph by object on the destination; and
• no structural target, same-slide name collision, group/key conflict, or undeclared shared !! name on a Morph edge.

Morph without an explicit pair block retains PowerPoint's automatic matching behavior. Explicit pairing is generated-route authoring; source-preserving round-trip export keeps existing object names and transition XML.

4. Route Mapping

The public create_pptx_with_native_svg Python API retains its legacy 0.5s default; the generated-deck CLI explicitly passes 0.4s.

5. OOXML Rules

Slide child order:

p:cSld
p:clrMapOvr
p:transition or transition mc:AlternateContent
p:timing
p:extLst

One slide may contain at most one logical transition carrier:

• one direct p:transition; or
• one root-level mc:AlternateContent whose Choice/Fallback branches contain p:transition.

Mutation rules:

Sound placement: for a direct transition, append p:sndAc inside p:transition after the visual-effect child, when present. For mc:AlternateContent, write the same sound action into both Choice and Fallback transition carriers so older Office consumers do not lose the cue. The slide relationship targets one packaged WAV part; replacing or removing a requested generated sound must not leave a dangling relationship.

MCE prefix rule: Requires and Ignorable values contain textual prefix names. Serialization must retain bindings for those exact names. Renaming an effect prefix without updating these attributes corrupts compatibility.

Package timing rule: when a route writes advTm, set ppt/presProps.xml p:presentationPr/p:showPr useTimings=1. Do not write showPr into ppt/presentation.xml.

Kiosk show: svg_to_pptx.py --kiosk writes p:showPr loop="1" with a p:kiosk child (PowerPoint's "Browsed at a kiosk"): the show loops until Escape and ignores click and keyboard advance, so only advTm timings and hyperlinks move between slides. It leaves useTimings to the timing rule, so a hyperlink-driven touch guide can be a kiosk show without timed advance.

6. Validation and Read-Back

Reject:

• unknown effect names;
• options without an explicit native effect;
• unknown option fields or values for the selected effect;
• non-finite values, including NaN and Infinity;
• duration less than or equal to zero;
• a missing/non-file transition sound, a non-WAV transition sound, or an unresolved/dangling sound relationship;
• negative advance or narration padding;
• booleans passed as numeric API values;
• multiple logical transition carriers;
• unresolved MCE Requires or Ignorable prefixes.
• invalid forced-Morph adjacency, identity uniqueness, object type, or destination effect.

Read-back must report the canonical native effect and complete effective options, while keeping the primary Choice child separate from the fallback. It must also report raw effect attributes, carrier type, duration, click mode, and automatic advance time, plus the transition sound relationship/name when present. Package validation must run after writing, not only before mutation.

Use inline smoke commands and gitignored projects/smoke* artifacts. Do not add a tests directory or test_*.py files.