@lutrin/core 1.0.0

package/src/kit/archive.mjs

@@ -0,0 +1,448 @@
+/**
+ * `.deckkit` archives — pack, download, extract (see the "Kits" section of the
+ * README, and SECURITY.md for the threat model).
+ *
+ * Lives in `src/kit/` and not in `src/deck/`: this module depends on JSZip, and
+ * the `deck/` core knows no third-party library of that kind
+ * (boundary.test.mjs). The distinction is also right on the merits —
+ * compiling a deck knows nothing of archives; only the CLI installs. The
+ * MANIFEST, for its part, stays in `deck/kit.mjs`: theme resolution needs it,
+ * and it is pure.
+ *
+ * This is the ONLY place in the project that writes bytes coming from the
+ * outside onto the user's disk. Everything that follows is a safeguard, and
+ * none of them is optional:
+ *
+ *   1. PATH TRAVERSAL — any entry whose normalized path leaves the target
+ *      directory is refused, absolute paths and `..` included. It is the
+ *      classic bug of every unzipper ("zip slip").
+ *   2. EXTENSION ALLOWLIST — a kit is DATA. No `.mjs`, `.js` or `.node` gets
+ *      in. It is this property, and it alone, that makes installing from a URL
+ *      defensible: nothing that is installed will ever be executed.
+ *   3. LIMITS — archive size, uncompressed total, entry count. Without them,
+ *      1 MB of archive can write 10 GB ("zip bomb").
+ *   4. HTTPS ONLY, and never a redirect to another protocol.
+ *   5. DIGEST — the SHA-256 of the archive is displayed and kept, so that the
+ *      author of a kit can state what they published. It is NOT a signature:
+ *      it does not authenticate the source, it allows comparison.
+ *   6. ATOMIC EXTRACTION — everything is written to a neighboring temporary
+ *      directory, validated, then swapped in by a rename(). An interrupted
+ *      installation never leaves a half-written kit.
+ *
+ * The uncompressed total is checked DURING decompression (nodeStream), not
+ * after: the size an archive announces is a declaration by the archive, hence
+ * by a third party, and a single 10 GB file would exhaust memory before an
+ * after-the-fact check ever got a word in.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import https from 'node:https';
+import JSZip from 'jszip';
+import { parseKitManifest, escapesKit, KIT_MANIFEST, KIT_EXT } from '../deck/kit.mjs';
+import { remoteUrlRefusal } from '../deck/assets.mjs';
+
+/** Safety limits. Generous for a real kit (a complete kit with its fonts and
+ *  logos weighs ~500 KB), tight for a hostile archive. */
+export const LIMITS = {
+  archiveBytes: 20 * 1024 * 1024,
+  extractedBytes: 100 * 1024 * 1024,
+  entries: 500,
+  redirects: 5,
+};
+
+/** Tooling directories, never packed: they belong to the kit's repository, not
+ *  to the kit. `test/` is still walked — its .mjs files are skipped by the
+ *  allowlist, but a .json or .png fixture has its place there. */
+export const SKIP_DIRS = new Set(['node_modules', '.git', '.github', '.vscode', '.idea', 'dist']);
+
+/** What a kit is allowed to contain. Data only: nothing executable. */
+export const ALLOWED_EXT = new Set([
+  '.json',
+  '.md',
+  '.txt',
+  '.woff2',
+  '.woff',
+  '.ttf',
+  '.otf',
+  '.svg',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.webp',
+  '.gif',
+]);
+
+class KitArchiveError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'KitArchiveError';
+  }
+}
+
+const fail = (msg) => {
+  throw new KitArchiveError(msg);
+};
+
+export const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+// ---------------------------------------------------------------------------
+// Reading an archive
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks an archive entry and returns its safe relative path.
+ *
+ * IMPORTANT NOTE — do not remove this check believing it dead. JSZip
+ * normalizes entry names in loadAsync: "../../etc/passwd" becomes
+ * "etc/passwd" there BEFORE reaching this point, including for an archive
+ * built outside JSZip. Protection against path traversal therefore rests
+ * today on the dependency, and this check is the SECOND line: it covers a
+ * change in JSZip's behaviour, a replacement of the library, and the
+ * extensions that are not admitted (which JSZip, for its part, lets through).
+ * It is tested directly in kit-archive.test.mjs, for want of being testable
+ * end to end.
+ *
+ * @returns {string|null} POSIX relative path, or null if the entry is to be ignored
+ */
+export function safeEntryPath(name) {
+  // archives built under Windows carry `\` separators: under POSIX those are
+  // NAME characters, so `..\..\x` would pass for a harmless file — escapesKit
+  // normalizes them before judging
+  if (name.endsWith('/')) return null; // directory: created implicitly
+  if (escapesKit(name))
+    fail(
+      `Entry refused: "${name}" escapes the kit (absolute path or ".." traversal). Archive rejected.`,
+    );
+  const ext = path.extname(name).toLowerCase();
+  if (!ALLOWED_EXT.has(ext))
+    fail(
+      `Entry refused: "${name}" — extension "${ext || '(none)'}" not allowed in a kit. ` +
+        `A kit contains only data (${[...ALLOWED_EXT].join(' ')}), never code.`,
+    );
+  return name.replace(/\\/g, '/');
+}
+
+/** Decompresses an entry while watching its REAL size as it goes. */
+function readEntry(entry, budget) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    const stream = entry.nodeStream('nodebuffer');
+    stream.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > budget.remaining) {
+        stream.destroy();
+        reject(
+          new KitArchiveError(
+            `Archive refused: the uncompressed content exceeds ${Math.round(LIMITS.extractedBytes / 1024 / 1024)} MB ` +
+              `(entry "${entry.name}"). Archive rejected.`,
+          ),
+        );
+        return;
+      }
+      chunks.push(chunk);
+    });
+    stream.on('error', reject);
+    stream.on('end', () => {
+      budget.remaining -= size;
+      resolve(Buffer.concat(chunks));
+    });
+  });
+}
+
+/**
+ * Reads a `.deckkit` archive IN MEMORY and validates everything that can be
+ * validated before a single byte touches the disk: entries, manifest, limits.
+ *
+ * @param {Buffer} buf
+ * @returns {Promise<{ manifest: object, files: Map<string, Buffer>,
+ *                     digest: string, diagnostics: Array }>}
+ */
+export async function readKitArchive(buf) {
+  if (!Buffer.isBuffer(buf) || !buf.length) fail('Empty archive.');
+  if (buf.length > LIMITS.archiveBytes)
+    fail(
+      `Archive refused: ${Math.round(buf.length / 1024 / 1024)} MB > ${Math.round(LIMITS.archiveBytes / 1024 / 1024)} MB.`,
+    );
+
+  let zip;
+  try {
+    zip = await JSZip.loadAsync(buf);
+  } catch (e) {
+    fail(`Archive could not be read: ${e?.message ?? e} — a ${KIT_EXT} file is a zip archive.`);
+  }
+
+  const entries = Object.values(zip.files).filter((f) => !f.dir);
+  if (entries.length > LIMITS.entries)
+    fail(`Archive refused: ${entries.length} entries > ${LIMITS.entries}.`);
+  if (!entries.length) fail('Empty archive: no file.');
+
+  const budget = { remaining: LIMITS.extractedBytes };
+  const files = new Map();
+  for (const entry of entries) {
+    const rel = safeEntryPath(entry.name);
+    if (rel === null) continue;
+    files.set(rel, await readEntry(entry, budget));
+  }
+
+  // the manifest must be at the ROOT: an archive that wraps its kit in a
+  // directory (the reflex of many compression tools) is a frequent and honest
+  // case — saying so precisely is worth more than an "invalid"
+  const raw = files.get(KIT_MANIFEST);
+  if (!raw) {
+    const elsewhere = [...files.keys()].find((f) => f.endsWith(`/${KIT_MANIFEST}`));
+    fail(
+      elsewhere
+        ? `Archive refused: ${KIT_MANIFEST} found in "${elsewhere}" and not at the root. Compress the CONTENTS of the kit, not the directory that holds it.`
+        : `Archive refused: no ${KIT_MANIFEST} at the root.`,
+    );
+  }
+
+  let json;
+  try {
+    json = JSON.parse(raw.toString('utf8'));
+  } catch (e) {
+    fail(`Archive refused: ${KIT_MANIFEST} — invalid JSON (${e?.message ?? e}).`);
+  }
+  const { manifest, diagnostics } = parseKitManifest(json, { where: `${KIT_MANIFEST} (archive)` });
+  if (!manifest) {
+    const err = diagnostics.find((d) => d.severity === 'error');
+    fail(`Archive refused: ${err?.message ?? 'invalid manifest'}`);
+  }
+
+  return { manifest, files, digest: sha256(buf), diagnostics };
+}
+
+// ---------------------------------------------------------------------------
+// Writing an archive
+// ---------------------------------------------------------------------------
+
+/**
+ * Packs the kit directory `dir` into a `.deckkit` archive.
+ *
+ * Applies the SAME rules as extraction: what we would refuse to install must
+ * not be producible here — otherwise the author of a kit discovers the refusal
+ * at their users' end rather than at their own.
+ *
+ * @returns {Promise<{ buffer: Buffer, manifest: object, entries: string[], skipped: string[] }>}
+ */
+export async function packKit(dir) {
+  const root = path.resolve(dir);
+  const manifestPath = path.join(root, KIT_MANIFEST);
+  if (!fs.existsSync(manifestPath))
+    fail(`${root} contains no ${KIT_MANIFEST} — this is not a kit.`);
+
+  let json;
+  try {
+    json = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    fail(`${KIT_MANIFEST} could not be read: ${e?.message ?? e}`);
+  }
+  const { manifest } = parseKitManifest(json, { where: manifestPath });
+  if (!manifest) fail(`${KIT_MANIFEST} invalid — fix the manifest before packing.`);
+
+  const zip = new JSZip();
+  const entries = [];
+  const skipped = [];
+  let total = 0;
+
+  const walk = (abs, rel) => {
+    for (const e of fs
+      .readdirSync(abs, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name))) {
+      const childAbs = path.join(abs, e.name);
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      // a symbolic link would be followed outside the kit: never packed
+      if (e.isSymbolicLink()) {
+        skipped.push(`${childRel} (symbolic link)`);
+        continue;
+      }
+      // kit DEVELOPMENT tooling: never in the archive. Without this, a kit
+      // that has its own tests carries all of node_modules — including the
+      // dependencies' package.json files, which the ".json" allowlist lets
+      // through without blinking. Silent: this is not "skipped", it is beside
+      // the point, and reporting it would drown the real warnings.
+      if (e.isDirectory() && SKIP_DIRS.has(e.name)) continue;
+      if (e.isDirectory()) {
+        walk(childAbs, childRel);
+        continue;
+      }
+      if (!e.isFile()) {
+        skipped.push(`${childRel} (special file)`);
+        continue;
+      }
+      if (!ALLOWED_EXT.has(path.extname(e.name).toLowerCase())) {
+        skipped.push(`${childRel} (extension not allowed)`);
+        continue;
+      }
+      const buf = fs.readFileSync(childAbs);
+      total += buf.length;
+      if (total > LIMITS.extractedBytes)
+        fail(`Kit too large: > ${Math.round(LIMITS.extractedBytes / 1024 / 1024)} MB.`);
+      if (entries.length >= LIMITS.entries) fail(`Kit has too many files: > ${LIMITS.entries}.`);
+      zip.file(childRel, buf);
+      entries.push(childRel);
+    }
+  };
+  walk(root, '');
+
+  // fixed date: two packings of the same content give the same bytes, hence
+  // the same digest — otherwise the published SHA-256 changes on every
+  // `kit create` and no longer means anything
+  const buffer = await zip.generateAsync({
+    type: 'nodebuffer',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 9 },
+    date: new Date(0),
+  });
+  if (buffer.length > LIMITS.archiveBytes)
+    fail(`Produced archive too large: ${Math.round(buffer.length / 1024 / 1024)} MB.`);
+  return { buffer, manifest, entries, skipped };
+}
+
+// ---------------------------------------------------------------------------
+// Download
+// ---------------------------------------------------------------------------
+
+/**
+ * Downloads an archive over HTTPS. Refuses every other protocol, including
+ * after a redirect: an https URL that sends you to file:// or http:// is an
+ * attack, not a convenience.
+ *
+ * The SAME address guard as remote images (remoteUrlRefusal: DNS resolution +
+ * refusal of private/local addresses) is replayed before every connection and
+ * at every redirect hop — without it, an https URL pointing at 127.0.0.1 or an
+ * internal address would serve as a probe of the victim's network. The https
+ * check below applies in addition.
+ *
+ * @returns {Promise<Buffer>}
+ */
+export function fetchKitArchive(url, { redirectsLeft = LIMITS.redirects } = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return Promise.reject(new KitArchiveError(`Invalid URL: ${url}`));
+  }
+  if (parsed.protocol !== 'https:')
+    return Promise.reject(
+      new KitArchiveError(
+        `Protocol refused: ${parsed.protocol}// — only https is accepted for installing a kit.`,
+      ),
+    );
+
+  return remoteUrlRefusal(url).then(
+    (refusal) =>
+      new Promise((resolve, reject) => {
+        if (refusal) {
+          reject(new KitArchiveError(`Address refused: ${refusal}`));
+          return;
+        }
+        const req = https.get(parsed, (res) => {
+          const { statusCode, headers } = res;
+
+          if (statusCode >= 300 && statusCode < 400 && headers.location) {
+            res.resume(); // release the socket
+            if (redirectsLeft <= 0) {
+              reject(new KitArchiveError(`Too many redirects (> ${LIMITS.redirects}): ${url}`));
+              return;
+            }
+            const next = new URL(headers.location, parsed).toString();
+            resolve(fetchKitArchive(next, { redirectsLeft: redirectsLeft - 1 }));
+            return;
+          }
+          if (statusCode !== 200) {
+            res.resume();
+            reject(new KitArchiveError(`Download failed: HTTP ${statusCode} — ${url}`));
+            return;
+          }
+
+          // Content-Length is only an announcement: refusing early avoids the
+          // transfer, the running total below is what actually protects
+          const declared = Number(headers['content-length']);
+          if (Number.isFinite(declared) && declared > LIMITS.archiveBytes) {
+            res.destroy();
+            reject(
+              new KitArchiveError(
+                `Archive refused: ${Math.round(declared / 1024 / 1024)} MB announced > ${Math.round(LIMITS.archiveBytes / 1024 / 1024)} MB.`,
+              ),
+            );
+            return;
+          }
+
+          const chunks = [];
+          let size = 0;
+          res.on('data', (c) => {
+            size += c.length;
+            if (size > LIMITS.archiveBytes) {
+              res.destroy();
+              reject(
+                new KitArchiveError(
+                  `Archive refused: download > ${Math.round(LIMITS.archiveBytes / 1024 / 1024)} MB, interrupted.`,
+                ),
+              );
+              return;
+            }
+            chunks.push(c);
+          });
+          res.on('end', () => resolve(Buffer.concat(chunks)));
+          res.on('error', reject);
+        });
+        req.on('error', (e) => reject(new KitArchiveError(`Download failed: ${e?.message ?? e}`)));
+        req.setTimeout(30_000, () => {
+          req.destroy();
+          reject(new KitArchiveError(`Download failed: timed out (30 s) — ${url}`));
+        });
+      }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Installation
+// ---------------------------------------------------------------------------
+
+/**
+ * Installs an already-read archive under `kitsDir/<manifest.name>`.
+ *
+ * The installation name comes from the MANIFEST, never from the file name: the
+ * latter is chosen by whoever distributes the archive, and `parseKitManifest`
+ * has already proved that `manifest.name` cannot traverse the file system.
+ *
+ * @returns {{ dir: string, replaced: boolean }}
+ */
+export function installKitArchive({ manifest, files, digest }, kitsDir, { force = false } = {}) {
+  const dest = path.join(path.resolve(kitsDir), manifest.name);
+  const replaced = fs.existsSync(dest);
+  if (replaced && !force)
+    fail(
+      `The kit "${manifest.name}" is already installed (${dest}). Re-run with --force to replace it.`,
+    );
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  // NEIGHBORING temporary directory: a rename() is atomic only within the same
+  // file system, which /tmp does not guarantee
+  const staging = fs.mkdtempSync(`${dest}.tmp-`);
+  try {
+    for (const [rel, buf] of files) {
+      const abs = path.join(staging, rel);
+      // belt AND braces: safeEntryPath has already judged every path, we
+      // re-check against the REAL directory before writing
+      const r = path.relative(staging, abs);
+      if (r.startsWith('..') || path.isAbsolute(r)) fail(`Entry refused at write time: "${rel}".`);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, buf);
+    }
+    fs.writeFileSync(path.join(staging, '.integrity'), `${digest}\n`);
+
+    if (replaced) fs.rmSync(dest, { recursive: true, force: true });
+    fs.renameSync(staging, dest);
+    return { dir: dest, replaced };
+  } catch (e) {
+    fs.rmSync(staging, { recursive: true, force: true });
+    throw e;
+  }
+}
+
+export { KitArchiveError };

package/src/pptx/anim.mjs

@@ -0,0 +1,196 @@
+/**
+ * Injection of the entrance animations into the .pptx (post-processing).
+ *
+ * PptxGenJS cannot produce animations, but the OOXML format describes them
+ * in the `<p:timing>` tree of each slideN.xml. So we reopen the zip written
+ * by PptxGenJS and inject into it, for every animated slide, a main "on
+ * click" sequence of native entrance effects (the very XML PowerPoint
+ * writes for itself):
+ *   - one step = one click; all the objects of a step appear together
+ *     (the first as clickEffect, the following ones as withEffect);
+ *   - a bullet list is built "by paragraph" (`<p:bldP build="p">` + one
+ *     `<p:pRg>` range per item): each bullet appears on its own click,
+ *     exactly like PowerPoint's native animation;
+ *   - the effect is chosen by the semantics of the block (PRESET_BY_KIND):
+ *     fade for text, wipe for the panels of structured layouts, zoom for
+ *     timeline milestones and metrics — unless an effect is imposed on the
+ *     slide by `<!-- animate: fade|wipe|zoom|appear -->`.
+ *
+ * Objects are matched to shapes by order of appearance in the `<p:spTree>`:
+ * the renderer records one entry per addText / addShape / addImage /
+ * addTable call (null = chrome that is not animated), in the exact order in
+ * which PptxGenJS writes the shapes. The page-number placeholder
+ * (type="sldNum"), added by the master, is excluded from the count. At the
+ * slightest structural mismatch, the slide is left exactly as it is —
+ * never a broken .pptx.
+ */
+
+import fs from 'node:fs';
+import JSZip from 'jszip';
+
+/** Effect per block type (default: fade). A panel is revealed by a wipe
+ *  upwards, a milestone or a metric bursts in with a zoom — the brand's
+ *  visual hierarchy, translated into movement. */
+export const PRESET_BY_KIND = {
+  panel: 'wipe',
+  'timeline-dot': 'zoom',
+  metric: 'zoom',
+};
+
+export const presetFor = (kind, override) => override ?? PRESET_BY_KIND[kind] ?? 'fade';
+
+/** Top-level shapes of the spTree, in document order. */
+const SHAPE_RE = /<p:(sp|pic|graphicFrame)>([\s\S]*?)<\/p:\1>/g;
+
+/** `cNvPr` ids of the animatable shapes of a slideN.xml, in write order. */
+function shapeIds(xml) {
+  const ids = [];
+  for (const m of xml.matchAll(SHAPE_RE)) {
+    if (m[1] === 'sp' && /type="sldNum"/.test(m[2])) continue; // placeholder from the master
+    const id = m[2].match(/<p:cNvPr id="(\d+)"/);
+    if (id) ids.push(Number(id[1]));
+  }
+  return ids;
+}
+
+/** Target element of a behaviour: whole shape, or paragraph range. */
+function tgtEl(target) {
+  const txEl =
+    target.para != null ? `<p:txEl><p:pRg st="${target.para}" end="${target.para}"/></p:txEl>` : '';
+  return `<p:tgtEl><p:spTgt spid="${target.spid}">${txEl}</p:spTgt></p:tgtEl>`;
+}
+
+/** "Make visible" behaviour of a target (whole shape or paragraph). */
+function setVisible(nid, target) {
+  return `<p:set><p:cBhvr><p:cTn id="${nid()}" dur="1" fill="hold"><p:stCondLst><p:cond delay="0"/></p:stCondLst></p:cTn>${tgtEl(target)}<p:attrNameLst><p:attrName>style.visibility</p:attrName></p:attrNameLst></p:cBhvr><p:to><p:strVal val="visible"/></p:to></p:set>`;
+}
+
+/** Filtered entrance transition (fade, wipe) on a target. */
+function animEffect(nid, target, filter, dur = 400) {
+  return `<p:animEffect transition="in" filter="${filter}"><p:cBhvr><p:cTn id="${nid()}" dur="${dur}"/>${tgtEl(target)}</p:cBhvr></p:animEffect>`;
+}
+
+/** Growth from 40 % to 100 % of a target (zoom effect). */
+function animScale(nid, target, dur = 400) {
+  return `<p:animScale><p:cBhvr><p:cTn id="${nid()}" dur="${dur}" fill="hold"/>${tgtEl(target)}</p:cBhvr><p:from x="40000" y="40000"/><p:to x="100000" y="100000"/></p:animScale>`;
+}
+
+/** Entrance effects: presetID/presetSubtype = the label shown in
+ *  PowerPoint's Animations pane; the child behaviours do the effect. */
+const EFFECTS = {
+  appear: { presetID: 1, subtype: 0, extra: () => '' },
+  fade: { presetID: 10, subtype: 0, extra: (nid, t) => animEffect(nid, t, 'fade') },
+  wipe: { presetID: 22, subtype: 1, extra: (nid, t) => animEffect(nid, t, 'wipe(up)') },
+  zoom: {
+    presetID: 23,
+    subtype: 0,
+    extra: (nid, t) => animEffect(nid, t, 'fade') + animScale(nid, t),
+  },
+};
+
+/** Entrance effect of a target, according to its preset (resolved by presetFor). */
+function effectPar(nid, target, nodeType) {
+  const fx = EFFECTS[target.preset] ?? EFFECTS.appear;
+  return `<p:par><p:cTn id="${nid()}" presetID="${fx.presetID}" presetClass="entr" presetSubtype="${fx.subtype}" fill="hold" grpId="0" nodeType="${nodeType}"><p:stCondLst><p:cond delay="0"/></p:stCondLst><p:childTnLst>${setVisible(nid, target)}${fx.extra(nid, target)}</p:childTnLst></p:cTn></p:par>`;
+}
+
+/** One click: all the targets of the step appear together. */
+function clickPar(nid, targets) {
+  const effects = targets
+    .map((t, k) => effectPar(nid, t, k === 0 ? 'clickEffect' : 'withEffect'))
+    .join('');
+  return `<p:par><p:cTn id="${nid()}" fill="hold"><p:stCondLst><p:cond delay="indefinite"/></p:stCondLst><p:childTnLst><p:par><p:cTn id="${nid()}" fill="hold"><p:stCondLst><p:cond delay="0"/></p:stCondLst><p:childTnLst>${effects}</p:childTnLst></p:cTn></p:par></p:childTnLst></p:cTn></p:par>`;
+}
+
+/** Complete `<p:timing>` tree of a slide. */
+function timingXml(stepTargets) {
+  let id = 0;
+  const nid = () => ++id;
+  const rootId = nid();
+  const seqId = nid();
+  const clicks = stepTargets.map((targets) => clickPar(nid, targets)).join('');
+
+  // <p:bldLst>: build mode per shape — "by paragraph" for lists, whole shape
+  // (background included) for the rest
+  const byPara = new Map();
+  for (const targets of stepTargets)
+    for (const t of targets) byPara.set(t.spid, (byPara.get(t.spid) ?? false) || t.para != null);
+  const bld = [...byPara]
+    .map(([spid, p]) =>
+      p
+        ? `<p:bldP spid="${spid}" grpId="0" build="p"/>`
+        : `<p:bldP spid="${spid}" grpId="0" animBg="1"/>`,
+    )
+    .join('');
+
+  return `<p:timing><p:tnLst><p:par><p:cTn id="${rootId}" dur="indefinite" restart="never" nodeType="tmRoot"><p:childTnLst><p:seq concurrent="1" nextAc="seek"><p:cTn id="${seqId}" dur="indefinite" nodeType="mainSeq"><p:childTnLst>${clicks}</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:bldLst>${bld}</p:bldLst></p:timing>`;
+}
+
+/**
+ * Injects the entrance animations into a .pptx already written to disk.
+ * Idempotent; any slide with an unexpected structure is ignored.
+ *
+ * @param {string} pptxPath path of the .pptx to modify in place
+ * @param {Map<number, {entries: Array<null|{step:number, paras?:number, kind?:string}>, preset: string|null}>} slideAnims
+ *        by slide number (1-based): `entries` = one entry per shape written
+ *        (in the order of the addText/addShape/addImage/addTable calls) —
+ *        null = chrome that is not animated; {step, kind} = entrance step
+ *        and block type (choice of the effect); {step, paras: n} = text
+ *        built by paragraph (n items); `preset` = effect imposed on the
+ *        slide (otherwise PRESET_BY_KIND decides per shape).
+ * @returns {Promise<{count:number, warnings:string[]}>} animated slides and
+ *          warnings — every slide left untouched is reported, never
+ *          silently ignored.
+ */
+export async function embedAnimations(pptxPath, slideAnims) {
+  const warnings = [];
+  if (!slideAnims?.size) return { count: 0, warnings };
+  const zip = await JSZip.loadAsync(fs.readFileSync(pptxPath));
+  let done = 0;
+
+  for (const [n, { entries, preset }] of slideAnims) {
+    const name = `ppt/slides/slide${n}.xml`;
+    const file = zip.file(name);
+    if (!file) {
+      warnings.push(`slide ${n}: ${name} missing from the .pptx — animations ignored`);
+      continue;
+    }
+    const xml = await file.async('string');
+    if (xml.includes('<p:timing>')) continue; // already done (idempotence, not a failure)
+
+    const ids = shapeIds(xml);
+    if (ids.length !== entries.length) {
+      // unexpected structure: break nothing, but say so
+      warnings.push(
+        `slide ${n}: unexpected structure (${ids.length} shapes in the XML, ` +
+          `${entries.length} expected) — animations ignored`,
+      );
+      continue;
+    }
+
+    // step → targets (one bullet = one step; several shapes = the same click)
+    const stepTargets = [];
+    entries.forEach((entry, k) => {
+      if (!entry) return;
+      const fx = presetFor(entry.kind, preset);
+      if (entry.paras > 1) {
+        for (let p = 0; p < entry.paras; p++)
+          (stepTargets[entry.step + p] ??= []).push({ spid: ids[k], para: p, preset: fx });
+      } else {
+        (stepTargets[entry.step] ??= []).push({ spid: ids[k], preset: fx });
+      }
+    });
+    const steps = stepTargets.filter(Boolean);
+    if (!steps.length) continue;
+
+    zip.file(name, xml.replace('</p:sld>', `${timingXml(steps)}</p:sld>`));
+    done++;
+  }
+
+  if (done)
+    fs.writeFileSync(
+      pptxPath,
+      await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }),
+    );
+  return { count: done, warnings };
+}