html2pptx-local-mcp 1.1.17

package/src/animation-injector.js

@@ -0,0 +1,724 @@
+// src/animation-injector.js
+//
+// Post-processes a generated PPTX ZIP by injecting <p:transition> and <p:timing>
+// elements into each slide's XML, based on data-anim-* attributes found in the
+// source HTML.
+//
+// DSL (declarative, AOS-style):
+//
+//   <section class="slide"
+//     data-transition="fade"
+//     data-transition-duration="800">
+//     ...
+//     <h1 data-anim="flyin"
+//         data-anim-direction="left"
+//         data-anim-duration="1000"
+//         data-anim-delay="200"
+//         data-anim-trigger="afterPrevious">Title</h1>
+//   </section>
+//
+// Design goals:
+//   - Zero-effect on HTML that has no data-anim-* (backward compatible)
+//   - Works as a PostProcess on the ZIP produced by PptxGenJS, no upstream changes
+//   - Keeps the authored text / shape editable — we only append <p:timing> nodes
+//
+// This is a deliberately minimal MVP that supports slide transitions and a
+// handful of entrance animations. Extend `ENTRANCE_PRESETS` and `TRANSITION_PRESETS`
+// to grow the catalogue.
+
+/* ----------------------------------------------------------------------
+ * PRESETS — OOXML <p:transition> children
+ * See http://officeopenxml.com/prSlide-transitions.php
+ * ---------------------------------------------------------------------- */
+// Each factory returns the inner XML for the given <p:transition>.
+// Called with a `direction` parameter from data-transition-direction (optional).
+// Modern transitions (morph / vortex / ferris / gallery / etc.) require the
+// Office 2016+ extension list and use the p16 namespace. We emit them as
+// <p:extLst> children so they render in PowerPoint 2016+ and gracefully
+// fall back to no-transition in older viewers.
+const TRANSITION_PRESETS = {
+  none: () => '',
+  fade: () => '<p:fade/>',
+  push: (dir = 'left') => `<p:push dir="${dirShort(dir, 'l')}"/>`,
+  wipe: (dir = 'left') => `<p:wipe dir="${dirShort(dir, 'l')}"/>`,
+  cover: (dir = 'left') => `<p:cover dir="${dirShort(dir, 'l')}"/>`,
+  uncover: (dir = 'left') => `<p:pull dir="${dirShort(dir, 'l')}"/>`,
+  split: (dir = 'out') => `<p:split orient="horz" dir="${dir === 'in' ? 'in' : 'out'}"/>`,
+  cut: () => '<p:cut/>',
+  dissolve: () => '<p:dissolve/>',
+  zoom: () => '<p:fade/>',     // legacy fallback
+  random: () => '<p:random/>',
+
+  // --- Office 2016+ modern transitions via extLst ---
+  //   ref: [MS-PPT] §2.5.129 / ECMA-376 Part 4 §13.11
+  morph: () => modernTransitionExt('morph', 'byObject'),
+  vortex: (dir = 'left') => modernTransitionExt('vortex', null, { dir: dirShort(dir, 'l') }),
+  ferris: (dir = 'left') => modernTransitionExt('ferris', null, { dir: dirShort(dir, 'l') }),
+  gallery: (dir = 'left') => modernTransitionExt('gallery', null, { dir: dirShort(dir, 'l') }),
+  conveyor: (dir = 'left') => modernTransitionExt('conveyor', null, { dir: dirShort(dir, 'l') }),
+  flash: () => modernTransitionExt('flash'),
+  prism: (dir = 'left') => modernTransitionExt('prism', null, { dir: dirShort(dir, 'l') }),
+  glitter: (dir = 'left') => modernTransitionExt('glitter', null, { dir: dirShort(dir, 'l') }),
+  honeycomb: () => modernTransitionExt('honeycomb'),
+  warp: (dir = 'in') => modernTransitionExt('warp', null, { dir: dir === 'in' ? 'in' : 'out' }),
+  window: (dir = 'in') => modernTransitionExt('window', null, { dir: dir === 'in' ? 'in' : 'out' }),
+  orbit: () => modernTransitionExt('orbit'),
+  shred: (dir = 'in') => modernTransitionExt('shred', null, { dir: dir === 'in' ? 'in' : 'out' }),
+  switch: (dir = 'left') => modernTransitionExt('switch', null, { dir: dirShort(dir, 'l') }),
+  flip: (dir = 'left') => modernTransitionExt('flip', null, { dir: dirShort(dir, 'l') }),
+  cube: (dir = 'left') => modernTransitionExt('cube', null, { dir: dirShort(dir, 'l') }),
+  doors: (dir = 'horz') => modernTransitionExt('doors', null, { dir: dir === 'horz' ? 'horz' : 'vert' }),
+  box: (dir = 'in') => modernTransitionExt('box', null, { dir: dir === 'in' ? 'in' : 'out' }),
+  rotate: () => modernTransitionExt('rotate'),
+  revealSmoothly: () => modernTransitionExt('revealSmoothly'),
+};
+
+function modernTransitionExt(name, option = null, attrs = {}) {
+  const attrStr = Object.entries(attrs)
+    .map(([k, v]) => `${k}="${escapeXmlAttr(v)}"`)
+    .join(' ');
+  const optionAttr = option ? ` option="${escapeXmlAttr(option)}"` : '';
+  return [
+    '<p:extLst>',
+    `<p:ext uri="{E01B4FDE-8C12-4F1D-8B9C-1E2C5E4AB7E1}">`,
+    `<p14:${name} xmlns:p14="http://schemas.microsoft.com/office/powerpoint/2010/main"${attrStr ? ' ' + attrStr : ''}${optionAttr}/>`,
+    '</p:ext>',
+    '</p:extLst>',
+  ].join('');
+}
+
+function dirShort(dir, fallback) {
+  const m = { left: 'l', right: 'r', up: 'u', down: 'd' };
+  return m[dir] || fallback;
+}
+
+import { renderPresetChildTimeline } from './animation-renderers.js';
+
+function escapeXmlAttr(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/* ----------------------------------------------------------------------
+ * PRESETS — Entrance/Emphasis/Exit animations
+ *
+ * presetID values follow ECMA-376 §19.5 and the Microsoft animation schema
+ *   https://learn.microsoft.com/en-us/office/open-xml/presentation/working-with-animation
+ *
+ * Where the spec is ambiguous we use the mapping PowerPoint 2016+ writes
+ * out when you pick the effect manually.
+ * ---------------------------------------------------------------------- */
+const ENTRANCE_PRESETS = {
+  // --- Basic ---
+  appear: { presetID: 1, presetClass: 'entr', presetSubtype: 0, directional: false },
+  fadein: { presetID: 10, presetClass: 'entr', presetSubtype: 0, directional: false },
+  flyin: { presetID: 2, presetClass: 'entr', presetSubtype: 4, directional: 'cardinal' },
+  floatin: { presetID: 42, presetClass: 'entr', presetSubtype: 0, directional: 'cardinal' },
+  split: { presetID: 3, presetClass: 'entr', presetSubtype: 26, directional: 'inout' },
+  wipe: { presetID: 4, presetClass: 'entr', presetSubtype: 4, directional: 'cardinal' },
+  zoom: { presetID: 23, presetClass: 'entr', presetSubtype: 0, directional: 'inout' },
+  bounce: { presetID: 26, presetClass: 'entr', presetSubtype: 0, directional: false },
+  swivel: { presetID: 18, presetClass: 'entr', presetSubtype: 1, directional: false },
+  // --- Subtle ---
+  dissolvein: { presetID: 9, presetClass: 'entr', presetSubtype: 0, directional: false },
+  expand: { presetID: 13, presetClass: 'entr', presetSubtype: 0, directional: false },
+  fadeswivel: { presetID: 45, presetClass: 'entr', presetSubtype: 0, directional: false },
+  zoomcenter: { presetID: 23, presetClass: 'entr', presetSubtype: 16, directional: false },
+  // --- Moderate ---
+  ascend: { presetID: 39, presetClass: 'entr', presetSubtype: 0, directional: false },
+  basiczoom: { presetID: 23, presetClass: 'entr', presetSubtype: 0, directional: false },
+  centerrevolve: { presetID: 12, presetClass: 'entr', presetSubtype: 0, directional: false },
+  compress: { presetID: 21, presetClass: 'entr', presetSubtype: 0, directional: false },
+  descend: { presetID: 40, presetClass: 'entr', presetSubtype: 0, directional: false },
+  fadedzoom: { presetID: 23, presetClass: 'entr', presetSubtype: 16, directional: false },
+  gridout: { presetID: 4, presetClass: 'entr', presetSubtype: 1, directional: false },
+  risefall: { presetID: 49, presetClass: 'entr', presetSubtype: 0, directional: false },
+  riseup: { presetID: 43, presetClass: 'entr', presetSubtype: 0, directional: false },
+  spinner: { presetID: 17, presetClass: 'entr', presetSubtype: 0, directional: false },
+  stretch: { presetID: 46, presetClass: 'entr', presetSubtype: 4, directional: 'cardinal' },
+  // --- Exciting ---
+  boomerang: { presetID: 25, presetClass: 'entr', presetSubtype: 0, directional: false },
+  credits: { presetID: 28, presetClass: 'entr', presetSubtype: 0, directional: false },
+  curveup: { presetID: 15, presetClass: 'entr', presetSubtype: 0, directional: false },
+  flipin: { presetID: 20, presetClass: 'entr', presetSubtype: 0, directional: false },
+  float: { presetID: 42, presetClass: 'entr', presetSubtype: 0, directional: false },
+  foldin: { presetID: 7, presetClass: 'entr', presetSubtype: 0, directional: false },
+  glidein: { presetID: 19, presetClass: 'entr', presetSubtype: 0, directional: false },
+  pinwheel: { presetID: 38, presetClass: 'entr', presetSubtype: 0, directional: false },
+  spiral: { presetID: 27, presetClass: 'entr', presetSubtype: 0, directional: false },
+  thread: { presetID: 30, presetClass: 'entr', presetSubtype: 0, directional: false },
+  whip: { presetID: 32, presetClass: 'entr', presetSubtype: 0, directional: false },
+
+  // ================================================================
+  // EMPHASIS
+  // ================================================================
+  pulse: { presetID: 1, presetClass: 'emph', presetSubtype: 0, directional: false },
+  spin: { presetID: 8, presetClass: 'emph', presetSubtype: 0, directional: false },
+  grow: { presetID: 6, presetClass: 'emph', presetSubtype: 0, directional: false },
+  shrink: { presetID: 6, presetClass: 'emph', presetSubtype: 1, directional: false },
+  flash: { presetID: 14, presetClass: 'emph', presetSubtype: 0, directional: false },
+  colorpulse: { presetID: 2, presetClass: 'emph', presetSubtype: 0, directional: false },
+  teeter: { presetID: 3, presetClass: 'emph', presetSubtype: 0, directional: false },
+  shimmer: { presetID: 24, presetClass: 'emph', presetSubtype: 0, directional: false },
+  blink: { presetID: 20, presetClass: 'emph', presetSubtype: 0, directional: false },
+  bold: { presetID: 9, presetClass: 'emph', presetSubtype: 0, directional: false },
+  wave: { presetID: 37, presetClass: 'emph', presetSubtype: 0, directional: false },
+  desaturate: { presetID: 13, presetClass: 'emph', presetSubtype: 0, directional: false },
+  darken: { presetID: 11, presetClass: 'emph', presetSubtype: 0, directional: false },
+  lighten: { presetID: 17, presetClass: 'emph', presetSubtype: 0, directional: false },
+  transparent: { presetID: 19, presetClass: 'emph', presetSubtype: 0, directional: false },
+  colorwave: { presetID: 36, presetClass: 'emph', presetSubtype: 0, directional: false },
+  brushon: { presetID: 35, presetClass: 'emph', presetSubtype: 0, directional: false },
+  wobble: { presetID: 21, presetClass: 'emph', presetSubtype: 0, directional: false },
+
+  // ================================================================
+  // EXIT
+  // ================================================================
+  disappear: { presetID: 1, presetClass: 'exit', presetSubtype: 0, directional: false },
+  fadeout: { presetID: 10, presetClass: 'exit', presetSubtype: 0, directional: false },
+  flyout: { presetID: 2, presetClass: 'exit', presetSubtype: 4, directional: 'cardinal' },
+  floatout: { presetID: 42, presetClass: 'exit', presetSubtype: 0, directional: 'cardinal' },
+  zoomout: { presetID: 23, presetClass: 'exit', presetSubtype: 0, directional: 'inout' },
+  splitout: { presetID: 3, presetClass: 'exit', presetSubtype: 26, directional: 'inout' },
+  wipeout: { presetID: 4, presetClass: 'exit', presetSubtype: 4, directional: 'cardinal' },
+  shrinkout: { presetID: 6, presetClass: 'exit', presetSubtype: 1, directional: false },
+  dissolveout: { presetID: 9, presetClass: 'exit', presetSubtype: 0, directional: false },
+  peekout: { presetID: 24, presetClass: 'exit', presetSubtype: 4, directional: 'cardinal' },
+  bounceout: { presetID: 26, presetClass: 'exit', presetSubtype: 0, directional: false },
+  swivelout: { presetID: 18, presetClass: 'exit', presetSubtype: 0, directional: false },
+  spiralout: { presetID: 27, presetClass: 'exit', presetSubtype: 0, directional: false },
+  flipout: { presetID: 20, presetClass: 'exit', presetSubtype: 0, directional: false },
+  foldout: { presetID: 7, presetClass: 'exit', presetSubtype: 0, directional: false },
+  glideout: { presetID: 19, presetClass: 'exit', presetSubtype: 0, directional: false },
+  boomerangout: { presetID: 25, presetClass: 'exit', presetSubtype: 0, directional: false },
+  contract: { presetID: 13, presetClass: 'exit', presetSubtype: 0, directional: false },
+};
+
+// Cardinal direction → subtype mapping (OOXML presetSubtype values).
+// Used by flyin / floatin / wipe / flyout where "from the left", etc. matters.
+const CARDINAL_SUBTYPES = {
+  left: 4,
+  right: 8,
+  up: 1,
+  down: 2,
+  topleft: 5,
+  topright: 9,
+  bottomleft: 6,
+  bottomright: 10,
+};
+
+// In/Out direction → subtype for split / zoom / zoomout.
+const INOUT_SUBTYPES = {
+  in: 16,
+  out: 32,
+};
+
+/* ----------------------------------------------------------------------
+ * MOTION PATHS — <p:animMotion path="..." />
+ *
+ * Each entry returns the SVG-style path string expected by PowerPoint.
+ * Coordinates are in the 0..1 space (relative to the slide). The value
+ * accepted by PowerPoint is a mini SVG path DSL with "M"/"L"/"C"/"E" commands.
+ *
+ * Docs: https://learn.microsoft.com/en-us/office/open-xml/presentation/working-with-animation
+ * ---------------------------------------------------------------------- */
+const MOTION_PATHS = {
+  line: 'M 0 0 L 0.2 0 E',
+  lineright: 'M 0 0 L 0.3 0 E',
+  lineleft: 'M 0 0 L -0.3 0 E',
+  lineup: 'M 0 0 L 0 -0.3 E',
+  linedown: 'M 0 0 L 0 0.3 E',
+  arc: 'M 0 0 C 0.1 -0.1 0.2 -0.1 0.3 0 E',
+  arcup: 'M 0 0 C 0.1 -0.2 0.2 -0.2 0.3 0 E',
+  arcdown: 'M 0 0 C 0.1 0.2 0.2 0.2 0.3 0 E',
+  curve: 'M 0 0 C 0.05 -0.1 0.15 0.1 0.3 0 E',
+  scurve: 'M 0 0 C 0.1 -0.15 0.2 0.15 0.3 0 E',
+  circle: 'M 0 0 C 0.1 0 0.2 0.1 0.2 0.2 C 0.2 0.3 0.1 0.4 0 0.4 C -0.1 0.4 -0.2 0.3 -0.2 0.2 C -0.2 0.1 -0.1 0 0 0 E',
+  square: 'M 0 0 L 0.2 0 L 0.2 0.2 L 0 0.2 L 0 0 E',
+  diamond: 'M 0 0 L 0.15 -0.15 L 0.3 0 L 0.15 0.15 L 0 0 E',
+  triangle: 'M 0 0 L 0.15 -0.2 L 0.3 0 L 0 0 E',
+  bounce: 'M 0 0 C 0.05 -0.15 0.1 0 0.1 0 C 0.15 -0.08 0.2 0 0.2 0 C 0.25 -0.04 0.3 0 0.3 0 E',
+  loop: 'M 0 0 C 0.1 -0.2 0.3 -0.2 0.2 0 C 0.1 0.15 -0.1 0.15 0 0 L 0.3 0 E',
+  zigzag: 'M 0 0 L 0.05 -0.1 L 0.1 0.1 L 0.15 -0.1 L 0.2 0.1 L 0.25 0 E',
+  wave: 'M 0 0 C 0.05 -0.1 0.1 -0.1 0.15 0 C 0.2 0.1 0.25 0.1 0.3 0 E',
+  spiral: 'M 0 0 C 0.05 -0.05 0.1 0 0.05 0.05 C -0.05 0.1 -0.1 0 0 -0.05 L 0.2 -0.05 E',
+  figure8: 'M 0 0 C -0.1 -0.1 -0.1 0.1 0 0 C 0.1 -0.1 0.1 0.1 0 0 E',
+  pointyright: 'M 0 0 L 0.1 -0.05 L 0.2 0 L 0.1 0.05 L 0 0 E',
+  decayingwave: 'M 0 0 C 0.03 -0.12 0.06 0.12 0.09 -0.08 C 0.12 0.08 0.15 -0.04 0.18 0.04 C 0.21 0 0.24 0 0.3 0 E',
+};
+
+function resolveSubtype(preset, direction) {
+  if (!preset.directional || !direction) return preset.presetSubtype;
+  if (preset.directional === 'cardinal' && CARDINAL_SUBTYPES[direction] != null) {
+    return CARDINAL_SUBTYPES[direction];
+  }
+  if (preset.directional === 'inout' && INOUT_SUBTYPES[direction] != null) {
+    return INOUT_SUBTYPES[direction];
+  }
+  return preset.presetSubtype;
+}
+
+/* ----------------------------------------------------------------------
+ * extractAnimationPlan
+ * Walk the source HTML and collect per-slide animation descriptors.
+ *
+ * Returns:
+ *   [
+ *     {
+ *       slideIndex: 0,
+ *       transition: { type, duration } | null,
+ *       entries: [{ shapeId, type, direction, duration, delay, trigger, presetInfo }, ...]
+ *     },
+ *     ...
+ *   ]
+ *
+ * Note: shapeId matching is the hard part. PptxGenJS generates shape IDs in the
+ * order it processes elements. We assign `data-pptx-shape-index` to each text/
+ * shape element before PPTX generation and read that back here.
+ * ---------------------------------------------------------------------- */
+export function extractAnimationPlan(rootElement) {
+  const plans = [];
+  const slides = rootElement.querySelectorAll('section.slide');
+
+  slides.forEach((slide, slideIndex) => {
+    const plan = { slideIndex, transition: null, entries: [] };
+
+    // --- transition ---
+    const tType = slide.getAttribute('data-transition');
+    if (tType && TRANSITION_PRESETS[tType] != null) {
+      plan.transition = {
+        type: tType,
+        duration: parseInt(slide.getAttribute('data-transition-duration'), 10) || 800,
+        direction: slide.getAttribute('data-transition-direction') || null,
+      };
+    }
+
+    // --- element animations ---
+    const animNodes = slide.querySelectorAll('[data-anim]');
+    animNodes.forEach((node, localIndex) => {
+      const type = node.getAttribute('data-anim');
+      const preset = ENTRANCE_PRESETS[type];
+      if (!preset) {
+        console.warn(`[animation-injector] Unknown data-anim value: "${type}"`);
+        return;
+      }
+      const direction = node.getAttribute('data-anim-direction');
+      const presetSubtype = resolveSubtype(preset, direction);
+
+      plan.entries.push({
+        localIndex,
+        type,
+        direction,
+        duration: parseInt(node.getAttribute('data-anim-duration'), 10) || 500,
+        delay: parseInt(node.getAttribute('data-anim-delay'), 10) || 0,
+        // Default to "afterPrevious" so animations auto-cascade in the
+        // slideshow instead of requiring a click per element. Authors that
+        // want click-gated reveals can set data-anim-trigger="onClick".
+        trigger: node.getAttribute('data-anim-trigger') || 'afterPrevious',
+        presetID: preset.presetID,
+        presetClass: preset.presetClass,
+        presetSubtype,
+        kind: 'preset',
+        shapeIndex: parseInt(node.getAttribute('data-pptx-shape-index'), 10),
+      });
+    });
+
+    // --- text-level animations (per character / word / paragraph reveal) ---
+    // Carried on a normal element animated with data-anim="fadein" (or any
+    // other entrance effect). Adding data-anim-text="bychar" makes PowerPoint
+    // apply the effect to each text run in sequence.
+    //   data-anim-text="bychar"      — letter by letter
+    //   data-anim-text="byword"      — word by word
+    //   data-anim-text="byparagraph" — line/paragraph by line
+    // Optional pacing (inter-letter delay, in ms):
+    //   data-anim-text-pace="80"
+    plan.entries.forEach((entry) => {
+      if (entry.kind !== 'preset') return;
+      // Find the originating DOM node to read its text-build attributes
+      const animNodes = slide.querySelectorAll('[data-anim]');
+      const node = animNodes[entry.localIndex];
+      if (!node) return;
+      const build = node.getAttribute('data-anim-text');
+      const pace = parseInt(node.getAttribute('data-anim-text-pace'), 10);
+      if (build) {
+        entry.textBuild = build; // 'bychar' | 'byword' | 'byparagraph'
+        if (Number.isFinite(pace) && pace >= 0) entry.textPaceMs = pace;
+      }
+    });
+
+    // --- motion paths ---
+    const motionNodes = slide.querySelectorAll('[data-anim-motion]');
+    motionNodes.forEach((node, localIndex) => {
+      const pathName = node.getAttribute('data-anim-motion');
+      const customPath = node.getAttribute('data-anim-motion-path');
+      const path = customPath || MOTION_PATHS[pathName];
+      if (!path) {
+        console.warn(`[animation-injector] Unknown data-anim-motion value: "${pathName}"`);
+        return;
+      }
+      plan.entries.push({
+        localIndex: plan.entries.length + localIndex,
+        type: `motion:${pathName || 'custom'}`,
+        duration: parseInt(node.getAttribute('data-anim-duration'), 10) || 1000,
+        delay: parseInt(node.getAttribute('data-anim-delay'), 10) || 0,
+        // Default to "afterPrevious" so animations auto-cascade in the
+        // slideshow instead of requiring a click per element. Authors that
+        // want click-gated reveals can set data-anim-trigger="onClick".
+        trigger: node.getAttribute('data-anim-trigger') || 'afterPrevious',
+        kind: 'motion',
+        motionPath: path,
+        shapeIndex: parseInt(node.getAttribute('data-pptx-shape-index'), 10),
+      });
+    });
+
+    if (plan.transition || plan.entries.length > 0) {
+      plans.push(plan);
+    }
+  });
+
+  return plans;
+}
+
+/* ----------------------------------------------------------------------
+ * buildTransitionXml — minimal <p:transition> snippet
+ * ---------------------------------------------------------------------- */
+function buildTransitionXml(transition) {
+  if (!transition) return '';
+  const factory = TRANSITION_PRESETS[transition.type];
+  const inner = typeof factory === 'function' ? factory(transition.direction) : '';
+  const dur = Math.max(100, Math.min(5000, transition.duration));
+  // spd attribute: 'slow' | 'med' | 'fast' — derive from duration
+  let spd = 'med';
+  if (dur < 500) spd = 'fast';
+  else if (dur > 1500) spd = 'slow';
+  return `<p:transition spd="${spd}" advClick="1">${inner}</p:transition>`;
+}
+
+/* ----------------------------------------------------------------------
+ * buildTimingXml — minimal <p:timing> block for a list of entries
+ * Schema reference: ECMA-376 §19.5.76
+ * ---------------------------------------------------------------------- */
+function buildTimingXml(entries) {
+  if (!entries.length) return '';
+
+  // One <p:par> per top-level sequence. Each entry is wrapped in its own
+  // <p:par> inside the main sequence, with presetID applied.
+  const parList = entries
+    .map((e, idx) => {
+      // nodeType depends on trigger
+      //   onClick       → tn id=... nodeType="clickEffect"
+      //   withPrevious  → tn id=... nodeType="withEffect"
+      //   afterPrevious → tn id=... nodeType="afterEffect"
+      const nodeType =
+        e.trigger === 'withPrevious'
+          ? 'withEffect'
+          : e.trigger === 'afterPrevious'
+            ? 'afterEffect'
+            : 'clickEffect';
+
+      const durMs = e.duration;
+      const delay = e.delay;
+      const shapeSpid = e.shapeSpid || 0;
+      const baseId = 100 + idx * 10;
+
+      // Motion-path entries use <p:animMotion> instead of <p:animEffect>.
+      if (e.kind === 'motion') {
+        return `
+        <p:par>
+          <p:cTn id="${baseId}" presetID="0" presetClass="path" presetSubtype="0" fill="hold" grpId="0" nodeType="${nodeType}">
+            <p:stCondLst><p:cond delay="${delay}"/></p:stCondLst>
+            <p:childTnLst>
+              <p:animMotion origin="layout" path="${escapeXmlAttr(e.motionPath)}" pathEditMode="relative" rAng="0" ptsTypes="">
+                <p:cBhvr>
+                  <p:cTn id="${baseId + 1}" dur="${durMs}" fill="hold"/>
+                  <p:tgtEl><p:spTgt spid="${shapeSpid}"/></p:tgtEl>
+                  <p:attrNameLst><p:attrName>ppt_x</p:attrName><p:attrName>ppt_y</p:attrName></p:attrNameLst>
+                </p:cBhvr>
+              </p:animMotion>
+            </p:childTnLst>
+          </p:cTn>
+        </p:par>`;
+      }
+
+      // When textBuild is set, the shape's text reveals piece-by-piece via
+      //   <p:iterate type="lt|wd|el"> ... <p:tmAbs val="<paceMs>"/></p:iterate>
+      // on the outer <p:cTn>. The same preset-specific animation below then
+      // fires once per piece.
+      const buildMap = { bychar: 'lt', byword: 'wd', byparagraph: 'el' };
+      const iterType = e.textBuild ? buildMap[e.textBuild] : null;
+      const paceMs = Number.isFinite(e.textPaceMs) ? e.textPaceMs : 80;
+      const iterateXml = iterType
+        ? `<p:iterate type="${iterType}"><p:tmAbs val="${paceMs}"/></p:iterate>`
+        : '';
+
+      // Preset-specific animation body (see animation-renderers.js). Each
+      // renderer knows the right <p:set>/<p:anim>/<p:animEffect> children
+      // for its effect — this replaces the previous "opacity 0→1 for
+      // everything" stub that made every preset look like fadein.
+      const childTimeline = renderPresetChildTimeline(e.type, {
+        baseId,
+        durMs,
+        delayMs: delay,
+        spid: shapeSpid,
+        direction: e.direction,
+        presetClass: e.presetClass,
+      });
+
+      return `
+        <p:par>
+          <p:cTn id="${baseId}" presetID="${e.presetID}" presetClass="${e.presetClass}" presetSubtype="${e.presetSubtype}" fill="hold" grpId="0" nodeType="${nodeType}">
+            <p:stCondLst><p:cond delay="${delay}"/></p:stCondLst>
+            ${iterateXml}
+            <p:childTnLst>${childTimeline}
+            </p:childTnLst>
+          </p:cTn>
+        </p:par>`;
+    })
+    .join('');
+
+  return `
+    <p:timing>
+      <p:tnLst>
+        <p:par>
+          <p:cTn id="1" dur="indefinite" restart="never" nodeType="tmRoot">
+            <p:childTnLst>
+              <p:seq concurrent="1" nextAc="seek">
+                <p:cTn id="2" dur="indefinite" nodeType="mainSeq">
+                  <p:childTnLst>${parList}
+                  </p:childTnLst>
+                </p:cTn>
+                <p:prevCondLst><p:cond evt="onPrev" delay="0"><p:tgtEl><p:sldTgt/></p:tgtEl></p:cond></p:prevCondLst>
+                <p:nextCondLst><p:cond evt="onNext" delay="0"><p:tgtEl><p:sldTgt/></p:tgtEl></p:cond></p:nextCondLst>
+              </p:seq>
+            </p:childTnLst>
+          </p:cTn>
+        </p:par>
+      </p:tnLst>
+    </p:timing>`;
+}
+
+/* ----------------------------------------------------------------------
+ * injectIntoSlideXml — mutate an existing slideN.xml string
+ * Inserts <p:transition> and <p:timing> immediately before </p:cSld>-sibling
+ * elements (they are siblings of <p:cSld>, not inside it).
+ *
+ * Structure expected:
+ *   <p:sld ...>
+ *     <p:cSld>...</p:cSld>
+ *     [<p:clrMapOvr>...</p:clrMapOvr>]
+ *     [<p:transition>...</p:transition>]   ← we insert here
+ *     [<p:timing>...</p:timing>]            ← and here
+ *   </p:sld>
+ * ---------------------------------------------------------------------- */
+export function injectIntoSlideXml(slideXml, { transition, entries }) {
+  let xml = slideXml;
+
+  // Resolve shape ids: walk <p:sp> / <p:pic> elements in order. The Nth one
+  // corresponds to shapeIndex === N. Extract the numeric id from <p:cNvPr id="..."/>.
+  const shapeRegex = /<p:(sp|pic|grpSp|graphicFrame)\b[^>]*>\s*<p:nvSpPr>\s*<p:cNvPr id="(\d+)"/g;
+  const altRegex = /<p:cNvPr id="(\d+)"/g;
+  const ids = [];
+  let m;
+  while ((m = altRegex.exec(xml)) !== null) ids.push(parseInt(m[1], 10));
+  // Skip first id (group root) — typical PptxGenJS output starts with an id=1 root group.
+  const shapeIds = ids.slice(1);
+
+  const resolvedEntries = entries
+    .map((e) => ({
+      ...e,
+      shapeSpid:
+        Number.isFinite(e.shapeIndex) && shapeIds[e.shapeIndex] != null
+          ? shapeIds[e.shapeIndex]
+          : shapeIds[0] || 0,
+    }))
+    .filter((e) => e.shapeSpid > 0);
+
+  const transitionXml = buildTransitionXml(transition);
+  const timingXml = buildTimingXml(resolvedEntries);
+
+  const insertion = `${transitionXml}${timingXml}`;
+  if (!insertion) return xml;
+
+  // Remove any existing p:timing/p:transition that PptxGenJS may have put in
+  xml = xml.replace(/<p:transition\b[^<]*(?:<[^/][^>]*>[\s\S]*?<\/p:transition>|\/?>)/g, '');
+  xml = xml.replace(/<p:timing\b[\s\S]*?<\/p:timing>/g, '');
+
+  // Insert right before </p:sld>
+  xml = xml.replace('</p:sld>', `${insertion}</p:sld>`);
+  return xml;
+}
+
+/* ----------------------------------------------------------------------
+ * applyPlansToZip — given a loaded JSZip PPTX and a list of plans, mutate
+ * slides/slideN.xml in place.
+ * ---------------------------------------------------------------------- */
+export async function applyPlansToZip(zip, plans) {
+  for (const plan of plans) {
+    const path = `ppt/slides/slide${plan.slideIndex + 1}.xml`;
+    const entry = zip.file(path);
+    if (!entry) {
+      console.warn(`[animation-injector] Slide not found: ${path}`);
+      continue;
+    }
+    const xml = await entry.async('string');
+    const newXml = injectIntoSlideXml(xml, plan);
+    zip.file(path, newXml);
+  }
+  return zip;
+}
+
+/* ----------------------------------------------------------------------
+ * preProcessHtml — assigns a sequential data-pptx-shape-index to every
+ * element that will become a PPTX shape. Must be called BEFORE the main
+ * HTML→PPTX conversion so that exportToPptx picks the same order.
+ *
+ * The heuristic: any element that has data-anim (we need it animated) AND
+ * is one of [text container, image, shape div] gets a shape index equal to
+ * its position in the slide's top-down traversal order.
+ * ---------------------------------------------------------------------- */
+export function preProcessHtml(rootElement) {
+  const slides = rootElement.querySelectorAll('section.slide');
+  slides.forEach((slide) => {
+    let counter = 0;
+    // NOTE: this traversal intentionally matches exportToPptx's own order —
+    // depth-first, document order. Elements without bg/text are skipped by
+    // the main converter, so we also skip them here.
+    const all = slide.querySelectorAll('*');
+    all.forEach((el) => {
+      // Always index elements that explicitly request an animation.
+      const wantsAnim =
+        el.hasAttribute('data-anim') || el.hasAttribute('data-anim-motion');
+      const style = el.getAttribute('style') || '';
+      const hasTextOrBg = /position:|background|border|color|font-size/i.test(style);
+      if (wantsAnim || hasTextOrBg) {
+        el.setAttribute('data-pptx-shape-index', String(counter));
+        counter += 1;
+      }
+    });
+  });
+}
+
+/* ----------------------------------------------------------------------
+ * Public helpers
+ * ---------------------------------------------------------------------- */
+export const SUPPORTED_TRANSITIONS = Object.keys(TRANSITION_PRESETS);
+export const SUPPORTED_ANIMATIONS = Object.keys(ENTRANCE_PRESETS);
+export const SUPPORTED_MOTION_PATHS = Object.keys(MOTION_PATHS);
+
+/**
+ * Machine-readable catalogue of every animation/transition the injector
+ * supports. Used by the MCP `html2pptx_animation_catalog` tool and the
+ * public `GET /api/animations/catalog` endpoint. Designed so an AI agent
+ * can pick the right animation without reading the source.
+ */
+export function getAnimationCatalog() {
+  const entrance = [];
+  const emphasis = [];
+  const exit = [];
+  Object.entries(ENTRANCE_PRESETS).forEach(([name, preset]) => {
+    const directions =
+      preset.directional === 'cardinal'
+        ? Object.keys(CARDINAL_SUBTYPES)
+        : preset.directional === 'inout'
+          ? Object.keys(INOUT_SUBTYPES)
+          : [];
+    const entry = { name, directions };
+    if (preset.presetClass === 'entr') entrance.push(entry);
+    else if (preset.presetClass === 'emph') emphasis.push(entry);
+    else if (preset.presetClass === 'exit') exit.push(entry);
+  });
+
+  return {
+    version: 3,
+    dsl: {
+      element: {
+        'data-anim': 'Animation name (e.g. "fadein", "flyin", "bounce") — see animations.entrance/emphasis/exit',
+        'data-anim-direction': 'Optional direction (cardinal: left/right/up/down [+ corners], or in/out for zoom-style)',
+        'data-anim-duration': 'Duration in ms (100–5000, default 500)',
+        'data-anim-delay': 'Delay in ms before the animation starts (default 0)',
+        'data-anim-trigger': 'When to start: onClick (default) | withPrevious | afterPrevious',
+        'data-anim-motion': 'Motion path name (e.g. "line", "arc", "loop") — see motionPaths',
+        'data-anim-motion-path': 'OPTIONAL custom SVG-style path override, e.g. "M 0 0 L 0.3 -0.2 E" (overrides data-anim-motion preset)',
+        'data-anim-text': 'Apply effect piece-by-piece: "bychar" | "byword" | "byparagraph"',
+        'data-anim-text-pace': 'Inter-piece delay in ms for text builds (default 80)',
+      },
+      slide: {
+        'data-transition': 'Slide transition name (e.g. "fade", "push", "morph", "vortex", "cube")',
+        'data-transition-direction': 'Optional direction for directional transitions (left/right/up/down or in/out or horz/vert)',
+        'data-transition-duration': 'Duration in ms (100–5000, default 800)',
+      },
+    },
+    transitions: Object.keys(TRANSITION_PRESETS).map((name) => ({
+      name,
+      directional: ['push', 'wipe', 'cover', 'uncover', 'vortex', 'ferris', 'gallery', 'conveyor', 'prism', 'glitter', 'switch', 'flip', 'cube'].includes(name)
+        ? 'cardinal'
+        : ['split', 'warp', 'window', 'shred', 'box'].includes(name)
+          ? 'inout'
+          : name === 'doors'
+            ? 'horzvert'
+            : false,
+      modern: ['morph', 'vortex', 'ferris', 'gallery', 'conveyor', 'flash', 'prism', 'glitter', 'honeycomb', 'warp', 'window', 'orbit', 'shred', 'switch', 'flip', 'cube', 'doors', 'box', 'rotate', 'revealSmoothly'].includes(name),
+    })),
+    animations: { entrance, emphasis, exit },
+    motionPaths: Object.keys(MOTION_PATHS),
+    triggers: ['onClick', 'withPrevious', 'afterPrevious'],
+    examples: [
+      {
+        title: 'Fade-in title',
+        html: '<h1 data-anim="fadein" data-anim-duration="1000">Hello</h1>',
+      },
+      {
+        title: 'Fly in from the left after previous',
+        html: '<p data-anim="flyin" data-anim-direction="left" data-anim-delay="300" data-anim-trigger="afterPrevious">Body</p>',
+      },
+      {
+        title: 'Slide with fade transition',
+        html: '<section class="slide" data-transition="fade" data-transition-duration="600">...</section>',
+      },
+      {
+        title: 'Staggered list',
+        html: [
+          '<ul>',
+          '  <li data-anim="fadein" data-anim-trigger="withPrevious">A</li>',
+          '  <li data-anim="fadein" data-anim-trigger="afterPrevious" data-anim-delay="200">B</li>',
+          '  <li data-anim="fadein" data-anim-trigger="afterPrevious" data-anim-delay="400">C</li>',
+          '</ul>',
+        ].join('\n'),
+      },
+      {
+        title: 'Motion path — element arcs across the slide',
+        html: '<div data-anim-motion="arcup" data-anim-duration="1500">Shape</div>',
+      },
+      {
+        title: 'Custom motion path (SVG-style)',
+        html: '<div data-anim-motion="custom" data-anim-motion-path="M 0 0 L 0.4 -0.2 L 0 0 E">Shape</div>',
+      },
+      {
+        title: 'Typewriter — reveal letter by letter',
+        html: '<h1 data-anim="fadein" data-anim-text="bychar" data-anim-text-pace="60" data-anim-duration="40">Hello, world</h1>',
+      },
+      {
+        title: 'Word-by-word reveal',
+        html: '<p data-anim="fadein" data-anim-text="byword" data-anim-text-pace="180">Three things to know</p>',
+      },
+      {
+        title: 'Morph transition (PowerPoint 2016+)',
+        html: '<section class="slide" data-transition="morph" data-transition-duration="1000">...</section>',
+      },
+      {
+        title: 'Cube transition',
+        html: '<section class="slide" data-transition="cube" data-transition-direction="left">...</section>',
+      },
+    ],
+    notes: [
+      'HTML authored without data-anim/data-transition/data-anim-motion attributes renders identically to the current html2pptx output (fully backward compatible).',
+      'Modern transitions (morph, vortex, ferris, cube, etc.) require PowerPoint 2016+ and emit p14-namespaced ext markers. Older viewers ignore them gracefully.',
+      'Motion paths use a compact SVG-style DSL: M (move), L (line), C (cubic bezier), E (end). Coordinates are 0..1 slide-relative.',
+      'Text builds (data-anim-text) emit a <p:iterate> timing so PowerPoint reveals the text piece-by-piece at the given pace.',
+      'PowerPoint (Mac, Windows, Web), Keynote, and LibreOffice honour most timings. Google Slides may ignore some effects.',
+    ],
+  };
+}