@vodailoc/kilo-kit-mcp 1.1.0 → 1.1.1

package/skills/writing-docs/slides/assets/pptxgenjs_helpers/layout.js

@@ -1,643 +1,643 @@
-// Copyright (c) OpenAI. All rights reserved.
-"use strict";
-
-function inferElementType(obj) {
-  if (!obj) return "unknown";
-  const data = obj.data || obj.options || {};
-  // Distinguish lines explicitly via type only. Many objects have a 'line' style; don't misclassify those.
-  if (obj.type === "line") return "line";
-  if (obj.type && typeof obj.type === "string") return obj.type;
-  if (obj.text || typeof data.text === "string") return "text";
-  if (data.path || obj.image) return "image";
-  if (data.chartType) return "chart";
-  if (data.shape || data.line) return "shape";
-  if (data.mediaType) return "media";
-  if (data.table || Array.isArray(data.rows)) return "table";
-  if (data.smartArt) return "smartart";
-  return "unknown";
-}
-
-const TEXT_OVERLAP_ERROR_THRESHOLD = 0.1;
-const RECTIFY_DIRECTION_EQUALITY_TOLERANCE = 0.15;
-
-function warnIfSlideHasOverlaps(slide, pptx, options = {}) {
-  if (!slide || !Array.isArray(slide._slideObjects)) {
-    console.warn("Invalid slide object passed to warnIfSlideOverlaps()");
-    return;
-  }
-  const opts = {
-    // By default, containment cases are very common (e.g., full-slide backgrounds)
-    // and usually not actionable. Mute them unless explicitly requested.
-    muteContainment:
-      options.muteContainment !== undefined ? options.muteContainment : true,
-    // Do NOT ignore lines or decorative shapes by default; users want true overlaps.
-    ignoreLines:
-      options.ignoreLines !== undefined ? options.ignoreLines : false,
-    ignoreDecorativeShapes:
-      options.ignoreDecorativeShapes !== undefined
-        ? options.ignoreDecorativeShapes
-        : false,
-  };
-  const slideIndex =
-    pptx && Array.isArray(pptx._slides) ? pptx._slides.indexOf(slide) : -1;
-  const slideLabel =
-    slideIndex >= 0 ? `Slide ${slideIndex + 1}` : "(Unknown slide index)";
-  const formatElement = (el) => {
-    const cx = (el.x + el.w / 2).toFixed(3);
-    const cy = (el.y + el.h / 2).toFixed(3);
-    return `element ${el.index} (${el.type}, center_x=${cx}, center_y=${cy})`;
-  };
-  const elements = slide._slideObjects.map((obj, i) => {
-    const {
-      x = 0,
-      y = 0,
-      w = 0,
-      h = 0,
-      fill,
-      line,
-    } = obj.data || obj.options || {};
-    const type = inferElementType(obj);
-    const isDecorative = (() => {
-      if (!opts.ignoreDecorativeShapes) return false;
-      // Border rectangles used as frames: transparent fill (or fully transparent) with a stroke
-      const transparency =
-        typeof fill?.transparency === "number" ? fill.transparency : null;
-      const hasOnlyBorder = !!line && (!fill || transparency !== null);
-      const fullyTransparent = transparency !== null && transparency >= 99;
-      return type === "shape" && hasOnlyBorder && fullyTransparent;
-    })();
-    const ignorable = (opts.ignoreLines && type === "line") || isDecorative;
-    return { index: i, type, x, y, w, h, ignorable };
-  });
-  let overlapCount = 0;
-  let containmentCount = 0;
-  for (let i = 0; i < elements.length; i++) {
-    const a = elements[i];
-    if (a.ignorable) continue;
-    for (let j = i + 1; j < elements.length; j++) {
-      const b = elements[j];
-      if (b.ignorable) continue;
-      const comparison = compareElementPosition(slide, a.index, b.index);
-      if (comparison.relation === "overlapping") {
-        // Special-case: diagonal line's bounding box overlapping a rectangle is often a false positive.
-        const EPS = 1e-6;
-        const getBounds = (e) => ({
-          x: e.x,
-          y: e.y,
-          x2: e.x + e.w,
-          y2: e.y + e.h,
-        });
-        const lineRectFalsePositive = (() => {
-          const oneIsLine = (a.type === "line") ^ (b.type === "line");
-          if (!oneIsLine) return false;
-          const line = a.type === "line" ? a : b;
-          const rect = a.type === "line" ? b : a;
-          // If line is diagonal, verify actual segment intersects rect; if not, ignore.
-          const isDiagonal = line.w > EPS && line.h > EPS;
-          const lineSeg = {
-            x1: line.x,
-            y1: line.y,
-            x2: line.x + line.w,
-            y2: line.y + line.h,
-          };
-          const rectB = getBounds(rect);
-          const pointInRect = (px, py, rb) =>
-            px >= rb.x - EPS &&
-            px <= rb.x2 + EPS &&
-            py >= rb.y - EPS &&
-            py <= rb.y2 + EPS;
-          const segsIntersect = (p1, p2, q1, q2) => {
-            const cross = (ax, ay, bx, by) => ax * by - ay * bx;
-            const d1x = p2.x - p1.x,
-              d1y = p2.y - p1.y;
-            const d2x = q2.x - q1.x,
-              d2y = q2.y - q1.y;
-            const denom = cross(d1x, d1y, d2x, d2y);
-            if (Math.abs(denom) < EPS) {
-              // Parallel: check colinearity and overlapping projections
-              const crossCol = cross(q1.x - p1.x, q1.y - p1.y, d1x, d1y);
-              if (Math.abs(crossCol) > EPS) return false;
-              const proj = (a, b, c) =>
-                Math.min(Math.max(a, b), Math.max(Math.min(a, b), c));
-              const overlapX = !(
-                Math.max(p1.x, p2.x) < Math.min(q1.x, q2.x) - EPS ||
-                Math.max(q1.x, q2.x) < Math.min(p1.x, p2.x) - EPS
-              );
-              const overlapY = !(
-                Math.max(p1.y, p2.y) < Math.min(q1.y, q2.y) - EPS ||
-                Math.max(q1.y, q2.y) < Math.min(p1.y, p2.y) - EPS
-              );
-              return overlapX && overlapY;
-            }
-            const t = cross(q1.x - p1.x, q1.y - p1.y, d2x, d2y) / denom;
-            const u = cross(q1.x - p1.x, q1.y - p1.y, d1x, d1y) / denom;
-            return t >= -EPS && t <= 1 + EPS && u >= -EPS && u <= 1 + EPS;
-          };
-          const intersectsRect = (seg, rb) => {
-            if (
-              pointInRect(seg.x1, seg.y1, rb) ||
-              pointInRect(seg.x2, seg.y2, rb)
-            )
-              return true;
-            const r1 = { x: rb.x, y: rb.y },
-              r2 = { x: rb.x2, y: rb.y },
-              r3 = { x: rb.x2, y: rb.y2 },
-              r4 = { x: rb.x, y: rb.y2 };
-            const p1 = { x: seg.x1, y: seg.y1 },
-              p2 = { x: seg.x2, y: seg.y2 };
-            return (
-              segsIntersect(p1, p2, r1, r2) ||
-              segsIntersect(p1, p2, r2, r3) ||
-              segsIntersect(p1, p2, r3, r4) ||
-              segsIntersect(p1, p2, r4, r1)
-            );
-          };
-          return isDiagonal && !intersectsRect(lineSeg, rectB);
-        })();
-        if (!lineRectFalsePositive) {
-          overlapCount++;
-
-          const severeTextOverlap = (() => {
-            if (!comparison.intersection) return false;
-            const exceedsThreshold = (element) =>
-              element.type === "text" &&
-              comparison.intersection.w >= TEXT_OVERLAP_ERROR_THRESHOLD &&
-              comparison.intersection.h >= TEXT_OVERLAP_ERROR_THRESHOLD;
-            return exceedsThreshold(a) || exceedsThreshold(b);
-          })();
-          if (severeTextOverlap) {
-            const overlapW = comparison.intersection.w;
-            const overlapH = comparison.intersection.h;
-            let rectificationSuggestion = "";
-            if (overlapW > EPS && overlapH > EPS) {
-              const maxOverlap = Math.max(overlapW, overlapH);
-              const diffRatio = Math.abs(overlapW - overlapH) / maxOverlap;
-              const directions = [];
-              // Attempt to determine the primary direction of the overlap. This is the direction
-              // in which the overlap is smaller (and so requires the smallest adjustment to rectify).
-              if (diffRatio <= RECTIFY_DIRECTION_EQUALITY_TOLERANCE) {
-                directions.push("horizontally", "vertically");
-              } else if (overlapW < overlapH) {
-                directions.push("horizontally");
-              } else {
-                directions.push("vertically");
-              }
-              rectificationSuggestion = `Suggestion: reposition elements ${directions.join(
-                " and "
-              )}.`;
-            }
-
-            console.error(
-              `❌ ${slideLabel}: Severe text overlap detected between ${formatElement(
-                a
-              )} and ${formatElement(
-                b
-              )} (overlap_horizontal=${comparison.intersection.w.toFixed(
-                3
-              )}, overlap_vertical=${comparison.intersection.h.toFixed(
-                3
-              )}). THIS MUST BE FIXED. ${rectificationSuggestion}`
-            );
-          } else {
-            console.warn(
-              `⚠️ ${slideLabel}: Overlap detected between ${formatElement(
-                a
-              )} and ${formatElement(b)}.`
-            );
-          }
-        }
-      } else if (comparison.relation === "contained") {
-        if (!opts.muteContainment) {
-          containmentCount++;
-          const container = elements[comparison.containerIndex];
-          const contained = elements[comparison.containedIndex];
-          console.warn(
-            `⚠️ ${slideLabel}: ${formatElement(
-              contained
-            )} is fully contained within ${formatElement(container)}`
-          );
-        } else {
-          // Still count internally when muted? We keep for summary only when un-muted
-        }
-      }
-    }
-  }
-  if (!(overlapCount === 0 && (!containmentCount || opts.muteContainment))) {
-    const issues = [];
-    if (overlapCount > 0) issues.push(`${overlapCount} overlapping pair(s)`);
-    if (!opts.muteContainment && containmentCount > 0)
-      issues.push(`${containmentCount} containment case(s)`);
-    console.log(`⚠️ ${slideLabel}: Found ${issues.join(" and ")}.`);
-  }
-}
-
-function compareElementPosition(slide, firstIndex, secondIndex) {
-  if (!slide || !Array.isArray(slide._slideObjects)) {
-    throw new Error("Invalid slide object passed to compareElementPosition()");
-  }
-  if (
-    typeof firstIndex !== "number" ||
-    typeof secondIndex !== "number" ||
-    !Number.isInteger(firstIndex) ||
-    !Number.isInteger(secondIndex)
-  ) {
-    throw new Error("Element indices must be integer values.");
-  }
-  const elements = slide._slideObjects;
-  if (
-    firstIndex < 0 ||
-    firstIndex >= elements.length ||
-    secondIndex < 0 ||
-    secondIndex >= elements.length
-  ) {
-    throw new Error(
-      "Element index out of bounds for compareElementPosition()."
-    );
-  }
-  const EPS = 1e-4;
-  const getBounds = (obj) => {
-    const source = obj?.data || obj?.options || {};
-    let x = typeof source.x === "number" ? source.x : 0;
-    let y = typeof source.y === "number" ? source.y : 0;
-    let w = typeof source.w === "number" ? source.w : 0;
-    let h = typeof source.h === "number" ? source.h : 0;
-    if (source.sizing && source.sizing.type === "crop") {
-      if (typeof source.sizing.w === "number") w = source.sizing.w;
-      if (typeof source.sizing.h === "number") h = source.sizing.h;
-    }
-    return { x, y, w, h, x2: x + w, y2: y + h };
-  };
-  const boundsA = getBounds(elements[firstIndex]);
-  const boundsB = getBounds(elements[secondIndex]);
-  const separated =
-    boundsA.x2 < boundsB.x - EPS ||
-    boundsB.x2 < boundsA.x - EPS ||
-    boundsA.y2 < boundsB.y - EPS ||
-    boundsB.y2 < boundsA.y - EPS;
-  if (separated) {
-    return {
-      relation: "disjoint",
-      containerIndex: null,
-      containedIndex: null,
-      aBounds: boundsA,
-      bBounds: boundsB,
-      intersection: null,
-    };
-  }
-  const aContainsB =
-    boundsA.x <= boundsB.x + EPS &&
-    boundsA.y <= boundsB.y + EPS &&
-    boundsA.x2 >= boundsB.x2 - EPS &&
-    boundsA.y2 >= boundsB.y2 - EPS;
-  const bContainsA =
-    boundsB.x <= boundsA.x + EPS &&
-    boundsB.y <= boundsA.y + EPS &&
-    boundsB.x2 >= boundsA.x2 - EPS &&
-    boundsB.y2 >= boundsA.y2 - EPS;
-  const ix1 = Math.max(boundsA.x, boundsB.x);
-  const iy1 = Math.max(boundsA.y, boundsB.y);
-  const ix2 = Math.min(boundsA.x2, boundsB.x2);
-  const iy2 = Math.min(boundsA.y2, boundsB.y2);
-  const intersectionWidth = Math.max(0, ix2 - ix1);
-  const intersectionHeight = Math.max(0, iy2 - iy1);
-  const intersection =
-    intersectionWidth > EPS && intersectionHeight > EPS
-      ? { x: ix1, y: iy1, w: intersectionWidth, h: intersectionHeight }
-      : null;
-  if (aContainsB && !bContainsA) {
-    return {
-      relation: "contained",
-      containerIndex: firstIndex,
-      containedIndex: secondIndex,
-      aBounds: boundsA,
-      bBounds: boundsB,
-      intersection,
-    };
-  }
-  if (bContainsA && !aContainsB) {
-    return {
-      relation: "contained",
-      containerIndex: secondIndex,
-      containedIndex: firstIndex,
-      aBounds: boundsA,
-      bBounds: boundsB,
-      intersection,
-    };
-  }
-  if (intersection) {
-    return {
-      relation: "overlapping",
-      containerIndex: null,
-      containedIndex: null,
-      aBounds: boundsA,
-      bBounds: boundsB,
-      intersection,
-    };
-  }
-  return {
-    relation: "touching",
-    containerIndex: null,
-    containedIndex: null,
-    aBounds: boundsA,
-    bBounds: boundsB,
-    intersection: null,
-  };
-}
-
-const VALID_ALIGNMENTS = new Set([
-  "left",
-  "right",
-  "top",
-  "bottom",
-  "verticallyCenter",
-  "horizontallyCenter",
-]);
-
-const getElementBounds = (obj) => {
-  const source = obj?.data || obj?.options || {};
-  let x = typeof source.x === "number" ? source.x : 0;
-  let y = typeof source.y === "number" ? source.y : 0;
-  let w = typeof source.w === "number" ? source.w : 0;
-  let h = typeof source.h === "number" ? source.h : 0;
-  // If an image is placed with crop sizing, pptxgenjs stores a larger virtual image w/h
-  // and a viewport in source.sizing.{w,h}. For visual overlap purposes, use the viewport.
-  if (source.sizing && source.sizing.type === "crop") {
-    if (typeof source.sizing.w === "number") w = source.sizing.w;
-    if (typeof source.sizing.h === "number") h = source.sizing.h;
-  }
-  return { x, y, w, h, x2: x + w, y2: y + h };
-};
-
-const setElementPosition = (obj, coords) => {
-  const ensureTarget = (targetObj) => {
-    if (!targetObj || typeof targetObj !== "object") return null;
-    return targetObj;
-  };
-  const targets = [];
-  const dataTarget = ensureTarget(obj.data);
-  if (dataTarget) targets.push(dataTarget);
-  const optionsTarget =
-    obj.options && obj.options !== obj.data ? ensureTarget(obj.options) : null;
-  if (optionsTarget) targets.push(optionsTarget);
-  if (targets.length === 0) {
-    obj.data = obj.data && typeof obj.data === "object" ? obj.data : {};
-    targets.push(obj.data);
-  }
-  targets.forEach((target) => {
-    if (coords.x !== undefined) target.x = coords.x;
-    if (coords.y !== undefined) target.y = coords.y;
-  });
-};
-
-const dimensionKeyPairs = [
-  ["width", "height"],
-  ["w", "h"],
-  ["cx", "cy"],
-  ["slideWidth", "slideHeight"],
-  ["slideWidthInches", "slideHeightInches"],
-  ["widthInches", "heightInches"],
-];
-
-const toNumber = (value) => {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  if (typeof value === "string") {
-    const parsed = parseFloat(value);
-    return Number.isFinite(parsed) ? parsed : null;
-  }
-  return null;
-};
-
-const readDimensionsFromObject = (candidate, seen = new Set()) => {
-  if (!candidate || typeof candidate !== "object") return null;
-  if (seen.has(candidate)) return null;
-  seen.add(candidate);
-  for (const [wKey, hKey] of dimensionKeyPairs) {
-    const width = toNumber(candidate[wKey]);
-    const height = toNumber(candidate[hKey]);
-    if (width !== null && height !== null && width > 0 && height > 0) {
-      return { width, height };
-    }
-  }
-  const nestedKeys = ["size", "slideSize", "layout", "slideLayout"];
-  for (const key of nestedKeys) {
-    const nested = readDimensionsFromObject(candidate[key], seen);
-    if (nested) return nested;
-  }
-  return null;
-};
-
-const getSlideDimensions = (slide, pptx) => {
-  const candidates = [
-    slide?._presLayout,
-    slide?._slideLayout,
-    slide?._pres?.layout,
-    slide?._parent?.layout,
-    slide?._layout,
-    pptx?._presLayout,
-    pptx?._layout,
-    pptx?.layout,
-    pptx?.presLayout,
-  ];
-  for (const candidate of candidates) {
-    const dims = readDimensionsFromObject(candidate);
-    if (dims) {
-      // Some internals are in EMUs; convert if values look too large for inches
-      const EMU_PER_IN = 914400;
-      const looksEmu = dims.width > 1000 || dims.height > 1000;
-      if (looksEmu) {
-        return {
-          width: dims.width / EMU_PER_IN,
-          height: dims.height / EMU_PER_IN,
-          source: "emu_converted",
-        };
-      }
-      return { ...dims, source: "detected" };
-    }
-  }
-  throw new Error(
-    "getSlideDimensions(): Unable to determine slide dimensions from pptxgenjs internals."
-  );
-};
-
-function alignSlideElements(slide, indices, alignment) {
-  if (!slide || !Array.isArray(slide._slideObjects)) {
-    throw new Error("Invalid slide object passed to alignSlideElements()");
-  }
-  if (!Array.isArray(indices) || indices.length === 0) {
-    throw new Error("indices must be a non-empty array.");
-  }
-  if (!VALID_ALIGNMENTS.has(alignment)) {
-    throw new Error(`Unsupported alignment option: ${alignment}`);
-  }
-  const uniqueIndices = [...new Set(indices)];
-  const elements = slide._slideObjects;
-  const selected = uniqueIndices.map((idx) => {
-    if (typeof idx !== "number" || !Number.isInteger(idx)) {
-      throw new Error("Element indices must be integers.");
-    }
-    if (idx < 0 || idx >= elements.length) {
-      throw new Error("Element index out of bounds for alignSlideElements().");
-    }
-    const obj = elements[idx];
-    const bounds = getElementBounds(obj);
-    return { index: idx, obj, bounds };
-  });
-  if (selected.length < 2) return;
-  const minX = Math.min(...selected.map((item) => item.bounds.x));
-  const maxX2 = Math.max(...selected.map((item) => item.bounds.x2));
-  const minY = Math.min(...selected.map((item) => item.bounds.y));
-  const maxY2 = Math.max(...selected.map((item) => item.bounds.y2));
-  const centerX = (minX + maxX2) / 2;
-  const centerY = (minY + maxY2) / 2;
-  selected.forEach(({ obj, bounds }) => {
-    const { w, h } = bounds;
-    switch (alignment) {
-      case "left":
-        setElementPosition(obj, { x: minX });
-        break;
-      case "right":
-        setElementPosition(obj, { x: maxX2 - w });
-        break;
-      case "top":
-        setElementPosition(obj, { y: minY });
-        break;
-      case "bottom":
-        setElementPosition(obj, { y: maxY2 - h });
-        break;
-      case "horizontallyCenter":
-        setElementPosition(obj, { x: centerX - w / 2 });
-        break;
-      case "verticallyCenter":
-        setElementPosition(obj, { y: centerY - h / 2 });
-        break;
-      default:
-        throw new Error(`Unhandled alignment option: ${alignment}`);
-    }
-  });
-}
-
-function distributeSlideElements(slide, indices, direction) {
-  if (!slide || !Array.isArray(slide._slideObjects)) {
-    throw new Error("Invalid slide object passed to distributeSlideElements()");
-  }
-  if (!Array.isArray(indices) || indices.length === 0) {
-    throw new Error("indices must be a non-empty array.");
-  }
-  if (direction !== "horizontal" && direction !== "vertical") {
-    throw new Error(`Unsupported distribution direction: ${direction}`);
-  }
-  const uniqueIndices = [...new Set(indices)];
-  if (uniqueIndices.length < 2) return;
-  const elements = slide._slideObjects;
-  const selected = uniqueIndices.map((idx) => {
-    if (typeof idx !== "number" || !Number.isInteger(idx)) {
-      throw new Error("Element indices must be integers.");
-    }
-    if (idx < 0 || idx >= elements.length) {
-      throw new Error(
-        "Element index out of bounds for distributeSlideElements()."
-      );
-    }
-    const obj = elements[idx];
-    const bounds = getElementBounds(obj);
-    return { index: idx, obj, bounds };
-  });
-  const axisStartKey = direction === "horizontal" ? "x" : "y";
-  const axisEndKey = direction === "horizontal" ? "x2" : "y2";
-  const sizeKey = direction === "horizontal" ? "w" : "h";
-  selected.sort((a, b) => {
-    const delta = a.bounds[axisStartKey] - b.bounds[axisStartKey];
-    return Math.abs(delta) > 1e-6 ? delta : a.index - b.index;
-  });
-  const minCoord = Math.min(
-    ...selected.map((item) => item.bounds[axisStartKey])
-  );
-  const maxCoord = Math.max(...selected.map((item) => item.bounds[axisEndKey]));
-  const totalSpan = maxCoord - minCoord;
-  const gaps = selected.length - 1;
-  const totalSize = selected.reduce(
-    (sum, item) => sum + item.bounds[sizeKey],
-    0
-  );
-  const gapSize = gaps > 0 ? (totalSpan - totalSize) / gaps : 0;
-  let cursor = minCoord;
-  selected.forEach(({ obj, bounds }) => {
-    if (direction === "horizontal") {
-      setElementPosition(obj, { x: cursor });
-      cursor += bounds.w + gapSize;
-    } else {
-      setElementPosition(obj, { y: cursor });
-      cursor += bounds.h + gapSize;
-    }
-  });
-}
-
-function warnIfSlideElementsOutOfBounds(slide, pptx) {
-  if (!slide || !Array.isArray(slide._slideObjects)) {
-    console.warn(
-      "Invalid slide object passed to warnIfSlideElementsOutOfBounds()"
-    );
-    return;
-  }
-  const {
-    width: slideWidth,
-    height: slideHeight,
-    source,
-  } = getSlideDimensions(slide, pptx);
-  const slideIndex =
-    pptx && Array.isArray(pptx._slides) ? pptx._slides.indexOf(slide) : -1;
-  const slideLabel =
-    slideIndex >= 0 ? `Slide ${slideIndex + 1}` : "(Unknown slide index)";
-  if (source === "default") {
-    console.warn(
-      `⚠️ ${slideLabel}: Unable to determine slide dimensions from pptxgenjs internals; assuming width=${slideWidth}, height=${slideHeight}.`
-    );
-  }
-  const EPS = 1e-4;
-  let outOfBoundsCount = 0;
-  const formatElement = (idx, type, bounds) => {
-    const cx = (bounds.x + bounds.w / 2).toFixed(3);
-    const cy = (bounds.y + bounds.h / 2).toFixed(3);
-    return `Element ${idx} (${type}, center_x=${cx}, center_y=${cy})`;
-  };
-  slide._slideObjects.forEach((obj, index) => {
-    const bounds = getElementBounds(obj);
-    const type = inferElementType(obj);
-    const violations = [];
-    if (bounds.x < -EPS) violations.push(`left=${bounds.x.toFixed(3)} < 0`);
-    if (bounds.y < -EPS) violations.push(`top=${bounds.y.toFixed(3)} < 0`);
-    if (bounds.x2 > slideWidth + EPS)
-      violations.push(
-        `right=${bounds.x2.toFixed(3)} > width=${slideWidth.toFixed(3)}`
-      );
-    if (bounds.y2 > slideHeight + EPS)
-      violations.push(
-        `bottom=${bounds.y2.toFixed(3)} > height=${slideHeight.toFixed(3)}`
-      );
-    if (violations.length > 0) {
-      outOfBoundsCount++;
-      console.warn(
-        `⚠️ ${slideLabel}: ${formatElement(
-          index,
-          type,
-          bounds
-        )} exceeds slide bounds (${violations.join(", ")}).`
-      );
-    }
-  });
-  if (outOfBoundsCount > 0) {
-    console.log(
-      `⚠️ ${slideLabel}: Found ${outOfBoundsCount} element(s) extending beyond the slide bounds.`
-    );
-  }
-}
-
-module.exports = {
-  inferElementType,
-  compareElementPosition,
-  warnIfSlideHasOverlaps,
-  alignSlideElements,
-  distributeSlideElements,
-  warnIfSlideElementsOutOfBounds,
-  getSlideDimensions,
-};
+// Copyright (c) OpenAI. All rights reserved.
+"use strict";
+
+function inferElementType(obj) {
+  if (!obj) return "unknown";
+  const data = obj.data || obj.options || {};
+  // Distinguish lines explicitly via type only. Many objects have a 'line' style; don't misclassify those.
+  if (obj.type === "line") return "line";
+  if (obj.type && typeof obj.type === "string") return obj.type;
+  if (obj.text || typeof data.text === "string") return "text";
+  if (data.path || obj.image) return "image";
+  if (data.chartType) return "chart";
+  if (data.shape || data.line) return "shape";
+  if (data.mediaType) return "media";
+  if (data.table || Array.isArray(data.rows)) return "table";
+  if (data.smartArt) return "smartart";
+  return "unknown";
+}
+
+const TEXT_OVERLAP_ERROR_THRESHOLD = 0.1;
+const RECTIFY_DIRECTION_EQUALITY_TOLERANCE = 0.15;
+
+function warnIfSlideHasOverlaps(slide, pptx, options = {}) {
+  if (!slide || !Array.isArray(slide._slideObjects)) {
+    console.warn("Invalid slide object passed to warnIfSlideOverlaps()");
+    return;
+  }
+  const opts = {
+    // By default, containment cases are very common (e.g., full-slide backgrounds)
+    // and usually not actionable. Mute them unless explicitly requested.
+    muteContainment:
+      options.muteContainment !== undefined ? options.muteContainment : true,
+    // Do NOT ignore lines or decorative shapes by default; users want true overlaps.
+    ignoreLines:
+      options.ignoreLines !== undefined ? options.ignoreLines : false,
+    ignoreDecorativeShapes:
+      options.ignoreDecorativeShapes !== undefined
+        ? options.ignoreDecorativeShapes
+        : false,
+  };
+  const slideIndex =
+    pptx && Array.isArray(pptx._slides) ? pptx._slides.indexOf(slide) : -1;
+  const slideLabel =
+    slideIndex >= 0 ? `Slide ${slideIndex + 1}` : "(Unknown slide index)";
+  const formatElement = (el) => {
+    const cx = (el.x + el.w / 2).toFixed(3);
+    const cy = (el.y + el.h / 2).toFixed(3);
+    return `element ${el.index} (${el.type}, center_x=${cx}, center_y=${cy})`;
+  };
+  const elements = slide._slideObjects.map((obj, i) => {
+    const {
+      x = 0,
+      y = 0,
+      w = 0,
+      h = 0,
+      fill,
+      line,
+    } = obj.data || obj.options || {};
+    const type = inferElementType(obj);
+    const isDecorative = (() => {
+      if (!opts.ignoreDecorativeShapes) return false;
+      // Border rectangles used as frames: transparent fill (or fully transparent) with a stroke
+      const transparency =
+        typeof fill?.transparency === "number" ? fill.transparency : null;
+      const hasOnlyBorder = !!line && (!fill || transparency !== null);
+      const fullyTransparent = transparency !== null && transparency >= 99;
+      return type === "shape" && hasOnlyBorder && fullyTransparent;
+    })();
+    const ignorable = (opts.ignoreLines && type === "line") || isDecorative;
+    return { index: i, type, x, y, w, h, ignorable };
+  });
+  let overlapCount = 0;
+  let containmentCount = 0;
+  for (let i = 0; i < elements.length; i++) {
+    const a = elements[i];
+    if (a.ignorable) continue;
+    for (let j = i + 1; j < elements.length; j++) {
+      const b = elements[j];
+      if (b.ignorable) continue;
+      const comparison = compareElementPosition(slide, a.index, b.index);
+      if (comparison.relation === "overlapping") {
+        // Special-case: diagonal line's bounding box overlapping a rectangle is often a false positive.
+        const EPS = 1e-6;
+        const getBounds = (e) => ({
+          x: e.x,
+          y: e.y,
+          x2: e.x + e.w,
+          y2: e.y + e.h,
+        });
+        const lineRectFalsePositive = (() => {
+          const oneIsLine = (a.type === "line") ^ (b.type === "line");
+          if (!oneIsLine) return false;
+          const line = a.type === "line" ? a : b;
+          const rect = a.type === "line" ? b : a;
+          // If line is diagonal, verify actual segment intersects rect; if not, ignore.
+          const isDiagonal = line.w > EPS && line.h > EPS;
+          const lineSeg = {
+            x1: line.x,
+            y1: line.y,
+            x2: line.x + line.w,
+            y2: line.y + line.h,
+          };
+          const rectB = getBounds(rect);
+          const pointInRect = (px, py, rb) =>
+            px >= rb.x - EPS &&
+            px <= rb.x2 + EPS &&
+            py >= rb.y - EPS &&
+            py <= rb.y2 + EPS;
+          const segsIntersect = (p1, p2, q1, q2) => {
+            const cross = (ax, ay, bx, by) => ax * by - ay * bx;
+            const d1x = p2.x - p1.x,
+              d1y = p2.y - p1.y;
+            const d2x = q2.x - q1.x,
+              d2y = q2.y - q1.y;
+            const denom = cross(d1x, d1y, d2x, d2y);
+            if (Math.abs(denom) < EPS) {
+              // Parallel: check colinearity and overlapping projections
+              const crossCol = cross(q1.x - p1.x, q1.y - p1.y, d1x, d1y);
+              if (Math.abs(crossCol) > EPS) return false;
+              const proj = (a, b, c) =>
+                Math.min(Math.max(a, b), Math.max(Math.min(a, b), c));
+              const overlapX = !(
+                Math.max(p1.x, p2.x) < Math.min(q1.x, q2.x) - EPS ||
+                Math.max(q1.x, q2.x) < Math.min(p1.x, p2.x) - EPS
+              );
+              const overlapY = !(
+                Math.max(p1.y, p2.y) < Math.min(q1.y, q2.y) - EPS ||
+                Math.max(q1.y, q2.y) < Math.min(p1.y, p2.y) - EPS
+              );
+              return overlapX && overlapY;
+            }
+            const t = cross(q1.x - p1.x, q1.y - p1.y, d2x, d2y) / denom;
+            const u = cross(q1.x - p1.x, q1.y - p1.y, d1x, d1y) / denom;
+            return t >= -EPS && t <= 1 + EPS && u >= -EPS && u <= 1 + EPS;
+          };
+          const intersectsRect = (seg, rb) => {
+            if (
+              pointInRect(seg.x1, seg.y1, rb) ||
+              pointInRect(seg.x2, seg.y2, rb)
+            )
+              return true;
+            const r1 = { x: rb.x, y: rb.y },
+              r2 = { x: rb.x2, y: rb.y },
+              r3 = { x: rb.x2, y: rb.y2 },
+              r4 = { x: rb.x, y: rb.y2 };
+            const p1 = { x: seg.x1, y: seg.y1 },
+              p2 = { x: seg.x2, y: seg.y2 };
+            return (
+              segsIntersect(p1, p2, r1, r2) ||
+              segsIntersect(p1, p2, r2, r3) ||
+              segsIntersect(p1, p2, r3, r4) ||
+              segsIntersect(p1, p2, r4, r1)
+            );
+          };
+          return isDiagonal && !intersectsRect(lineSeg, rectB);
+        })();
+        if (!lineRectFalsePositive) {
+          overlapCount++;
+
+          const severeTextOverlap = (() => {
+            if (!comparison.intersection) return false;
+            const exceedsThreshold = (element) =>
+              element.type === "text" &&
+              comparison.intersection.w >= TEXT_OVERLAP_ERROR_THRESHOLD &&
+              comparison.intersection.h >= TEXT_OVERLAP_ERROR_THRESHOLD;
+            return exceedsThreshold(a) || exceedsThreshold(b);
+          })();
+          if (severeTextOverlap) {
+            const overlapW = comparison.intersection.w;
+            const overlapH = comparison.intersection.h;
+            let rectificationSuggestion = "";
+            if (overlapW > EPS && overlapH > EPS) {
+              const maxOverlap = Math.max(overlapW, overlapH);
+              const diffRatio = Math.abs(overlapW - overlapH) / maxOverlap;
+              const directions = [];
+              // Attempt to determine the primary direction of the overlap. This is the direction
+              // in which the overlap is smaller (and so requires the smallest adjustment to rectify).
+              if (diffRatio <= RECTIFY_DIRECTION_EQUALITY_TOLERANCE) {
+                directions.push("horizontally", "vertically");
+              } else if (overlapW < overlapH) {
+                directions.push("horizontally");
+              } else {
+                directions.push("vertically");
+              }
+              rectificationSuggestion = `Suggestion: reposition elements ${directions.join(
+                " and "
+              )}.`;
+            }
+
+            console.error(
+              `❌ ${slideLabel}: Severe text overlap detected between ${formatElement(
+                a
+              )} and ${formatElement(
+                b
+              )} (overlap_horizontal=${comparison.intersection.w.toFixed(
+                3
+              )}, overlap_vertical=${comparison.intersection.h.toFixed(
+                3
+              )}). THIS MUST BE FIXED. ${rectificationSuggestion}`
+            );
+          } else {
+            console.warn(
+              `⚠️ ${slideLabel}: Overlap detected between ${formatElement(
+                a
+              )} and ${formatElement(b)}.`
+            );
+          }
+        }
+      } else if (comparison.relation === "contained") {
+        if (!opts.muteContainment) {
+          containmentCount++;
+          const container = elements[comparison.containerIndex];
+          const contained = elements[comparison.containedIndex];
+          console.warn(
+            `⚠️ ${slideLabel}: ${formatElement(
+              contained
+            )} is fully contained within ${formatElement(container)}`
+          );
+        } else {
+          // Still count internally when muted? We keep for summary only when un-muted
+        }
+      }
+    }
+  }
+  if (!(overlapCount === 0 && (!containmentCount || opts.muteContainment))) {
+    const issues = [];
+    if (overlapCount > 0) issues.push(`${overlapCount} overlapping pair(s)`);
+    if (!opts.muteContainment && containmentCount > 0)
+      issues.push(`${containmentCount} containment case(s)`);
+    console.log(`⚠️ ${slideLabel}: Found ${issues.join(" and ")}.`);
+  }
+}
+
+function compareElementPosition(slide, firstIndex, secondIndex) {
+  if (!slide || !Array.isArray(slide._slideObjects)) {
+    throw new Error("Invalid slide object passed to compareElementPosition()");
+  }
+  if (
+    typeof firstIndex !== "number" ||
+    typeof secondIndex !== "number" ||
+    !Number.isInteger(firstIndex) ||
+    !Number.isInteger(secondIndex)
+  ) {
+    throw new Error("Element indices must be integer values.");
+  }
+  const elements = slide._slideObjects;
+  if (
+    firstIndex < 0 ||
+    firstIndex >= elements.length ||
+    secondIndex < 0 ||
+    secondIndex >= elements.length
+  ) {
+    throw new Error(
+      "Element index out of bounds for compareElementPosition()."
+    );
+  }
+  const EPS = 1e-4;
+  const getBounds = (obj) => {
+    const source = obj?.data || obj?.options || {};
+    let x = typeof source.x === "number" ? source.x : 0;
+    let y = typeof source.y === "number" ? source.y : 0;
+    let w = typeof source.w === "number" ? source.w : 0;
+    let h = typeof source.h === "number" ? source.h : 0;
+    if (source.sizing && source.sizing.type === "crop") {
+      if (typeof source.sizing.w === "number") w = source.sizing.w;
+      if (typeof source.sizing.h === "number") h = source.sizing.h;
+    }
+    return { x, y, w, h, x2: x + w, y2: y + h };
+  };
+  const boundsA = getBounds(elements[firstIndex]);
+  const boundsB = getBounds(elements[secondIndex]);
+  const separated =
+    boundsA.x2 < boundsB.x - EPS ||
+    boundsB.x2 < boundsA.x - EPS ||
+    boundsA.y2 < boundsB.y - EPS ||
+    boundsB.y2 < boundsA.y - EPS;
+  if (separated) {
+    return {
+      relation: "disjoint",
+      containerIndex: null,
+      containedIndex: null,
+      aBounds: boundsA,
+      bBounds: boundsB,
+      intersection: null,
+    };
+  }
+  const aContainsB =
+    boundsA.x <= boundsB.x + EPS &&
+    boundsA.y <= boundsB.y + EPS &&
+    boundsA.x2 >= boundsB.x2 - EPS &&
+    boundsA.y2 >= boundsB.y2 - EPS;
+  const bContainsA =
+    boundsB.x <= boundsA.x + EPS &&
+    boundsB.y <= boundsA.y + EPS &&
+    boundsB.x2 >= boundsA.x2 - EPS &&
+    boundsB.y2 >= boundsA.y2 - EPS;
+  const ix1 = Math.max(boundsA.x, boundsB.x);
+  const iy1 = Math.max(boundsA.y, boundsB.y);
+  const ix2 = Math.min(boundsA.x2, boundsB.x2);
+  const iy2 = Math.min(boundsA.y2, boundsB.y2);
+  const intersectionWidth = Math.max(0, ix2 - ix1);
+  const intersectionHeight = Math.max(0, iy2 - iy1);
+  const intersection =
+    intersectionWidth > EPS && intersectionHeight > EPS
+      ? { x: ix1, y: iy1, w: intersectionWidth, h: intersectionHeight }
+      : null;
+  if (aContainsB && !bContainsA) {
+    return {
+      relation: "contained",
+      containerIndex: firstIndex,
+      containedIndex: secondIndex,
+      aBounds: boundsA,
+      bBounds: boundsB,
+      intersection,
+    };
+  }
+  if (bContainsA && !aContainsB) {
+    return {
+      relation: "contained",
+      containerIndex: secondIndex,
+      containedIndex: firstIndex,
+      aBounds: boundsA,
+      bBounds: boundsB,
+      intersection,
+    };
+  }
+  if (intersection) {
+    return {
+      relation: "overlapping",
+      containerIndex: null,
+      containedIndex: null,
+      aBounds: boundsA,
+      bBounds: boundsB,
+      intersection,
+    };
+  }
+  return {
+    relation: "touching",
+    containerIndex: null,
+    containedIndex: null,
+    aBounds: boundsA,
+    bBounds: boundsB,
+    intersection: null,
+  };
+}
+
+const VALID_ALIGNMENTS = new Set([
+  "left",
+  "right",
+  "top",
+  "bottom",
+  "verticallyCenter",
+  "horizontallyCenter",
+]);
+
+const getElementBounds = (obj) => {
+  const source = obj?.data || obj?.options || {};
+  let x = typeof source.x === "number" ? source.x : 0;
+  let y = typeof source.y === "number" ? source.y : 0;
+  let w = typeof source.w === "number" ? source.w : 0;
+  let h = typeof source.h === "number" ? source.h : 0;
+  // If an image is placed with crop sizing, pptxgenjs stores a larger virtual image w/h
+  // and a viewport in source.sizing.{w,h}. For visual overlap purposes, use the viewport.
+  if (source.sizing && source.sizing.type === "crop") {
+    if (typeof source.sizing.w === "number") w = source.sizing.w;
+    if (typeof source.sizing.h === "number") h = source.sizing.h;
+  }
+  return { x, y, w, h, x2: x + w, y2: y + h };
+};
+
+const setElementPosition = (obj, coords) => {
+  const ensureTarget = (targetObj) => {
+    if (!targetObj || typeof targetObj !== "object") return null;
+    return targetObj;
+  };
+  const targets = [];
+  const dataTarget = ensureTarget(obj.data);
+  if (dataTarget) targets.push(dataTarget);
+  const optionsTarget =
+    obj.options && obj.options !== obj.data ? ensureTarget(obj.options) : null;
+  if (optionsTarget) targets.push(optionsTarget);
+  if (targets.length === 0) {
+    obj.data = obj.data && typeof obj.data === "object" ? obj.data : {};
+    targets.push(obj.data);
+  }
+  targets.forEach((target) => {
+    if (coords.x !== undefined) target.x = coords.x;
+    if (coords.y !== undefined) target.y = coords.y;
+  });
+};
+
+const dimensionKeyPairs = [
+  ["width", "height"],
+  ["w", "h"],
+  ["cx", "cy"],
+  ["slideWidth", "slideHeight"],
+  ["slideWidthInches", "slideHeightInches"],
+  ["widthInches", "heightInches"],
+];
+
+const toNumber = (value) => {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+};
+
+const readDimensionsFromObject = (candidate, seen = new Set()) => {
+  if (!candidate || typeof candidate !== "object") return null;
+  if (seen.has(candidate)) return null;
+  seen.add(candidate);
+  for (const [wKey, hKey] of dimensionKeyPairs) {
+    const width = toNumber(candidate[wKey]);
+    const height = toNumber(candidate[hKey]);
+    if (width !== null && height !== null && width > 0 && height > 0) {
+      return { width, height };
+    }
+  }
+  const nestedKeys = ["size", "slideSize", "layout", "slideLayout"];
+  for (const key of nestedKeys) {
+    const nested = readDimensionsFromObject(candidate[key], seen);
+    if (nested) return nested;
+  }
+  return null;
+};
+
+const getSlideDimensions = (slide, pptx) => {
+  const candidates = [
+    slide?._presLayout,
+    slide?._slideLayout,
+    slide?._pres?.layout,
+    slide?._parent?.layout,
+    slide?._layout,
+    pptx?._presLayout,
+    pptx?._layout,
+    pptx?.layout,
+    pptx?.presLayout,
+  ];
+  for (const candidate of candidates) {
+    const dims = readDimensionsFromObject(candidate);
+    if (dims) {
+      // Some internals are in EMUs; convert if values look too large for inches
+      const EMU_PER_IN = 914400;
+      const looksEmu = dims.width > 1000 || dims.height > 1000;
+      if (looksEmu) {
+        return {
+          width: dims.width / EMU_PER_IN,
+          height: dims.height / EMU_PER_IN,
+          source: "emu_converted",
+        };
+      }
+      return { ...dims, source: "detected" };
+    }
+  }
+  throw new Error(
+    "getSlideDimensions(): Unable to determine slide dimensions from pptxgenjs internals."
+  );
+};
+
+function alignSlideElements(slide, indices, alignment) {
+  if (!slide || !Array.isArray(slide._slideObjects)) {
+    throw new Error("Invalid slide object passed to alignSlideElements()");
+  }
+  if (!Array.isArray(indices) || indices.length === 0) {
+    throw new Error("indices must be a non-empty array.");
+  }
+  if (!VALID_ALIGNMENTS.has(alignment)) {
+    throw new Error(`Unsupported alignment option: ${alignment}`);
+  }
+  const uniqueIndices = [...new Set(indices)];
+  const elements = slide._slideObjects;
+  const selected = uniqueIndices.map((idx) => {
+    if (typeof idx !== "number" || !Number.isInteger(idx)) {
+      throw new Error("Element indices must be integers.");
+    }
+    if (idx < 0 || idx >= elements.length) {
+      throw new Error("Element index out of bounds for alignSlideElements().");
+    }
+    const obj = elements[idx];
+    const bounds = getElementBounds(obj);
+    return { index: idx, obj, bounds };
+  });
+  if (selected.length < 2) return;
+  const minX = Math.min(...selected.map((item) => item.bounds.x));
+  const maxX2 = Math.max(...selected.map((item) => item.bounds.x2));
+  const minY = Math.min(...selected.map((item) => item.bounds.y));
+  const maxY2 = Math.max(...selected.map((item) => item.bounds.y2));
+  const centerX = (minX + maxX2) / 2;
+  const centerY = (minY + maxY2) / 2;
+  selected.forEach(({ obj, bounds }) => {
+    const { w, h } = bounds;
+    switch (alignment) {
+      case "left":
+        setElementPosition(obj, { x: minX });
+        break;
+      case "right":
+        setElementPosition(obj, { x: maxX2 - w });
+        break;
+      case "top":
+        setElementPosition(obj, { y: minY });
+        break;
+      case "bottom":
+        setElementPosition(obj, { y: maxY2 - h });
+        break;
+      case "horizontallyCenter":
+        setElementPosition(obj, { x: centerX - w / 2 });
+        break;
+      case "verticallyCenter":
+        setElementPosition(obj, { y: centerY - h / 2 });
+        break;
+      default:
+        throw new Error(`Unhandled alignment option: ${alignment}`);
+    }
+  });
+}
+
+function distributeSlideElements(slide, indices, direction) {
+  if (!slide || !Array.isArray(slide._slideObjects)) {
+    throw new Error("Invalid slide object passed to distributeSlideElements()");
+  }
+  if (!Array.isArray(indices) || indices.length === 0) {
+    throw new Error("indices must be a non-empty array.");
+  }
+  if (direction !== "horizontal" && direction !== "vertical") {
+    throw new Error(`Unsupported distribution direction: ${direction}`);
+  }
+  const uniqueIndices = [...new Set(indices)];
+  if (uniqueIndices.length < 2) return;
+  const elements = slide._slideObjects;
+  const selected = uniqueIndices.map((idx) => {
+    if (typeof idx !== "number" || !Number.isInteger(idx)) {
+      throw new Error("Element indices must be integers.");
+    }
+    if (idx < 0 || idx >= elements.length) {
+      throw new Error(
+        "Element index out of bounds for distributeSlideElements()."
+      );
+    }
+    const obj = elements[idx];
+    const bounds = getElementBounds(obj);
+    return { index: idx, obj, bounds };
+  });
+  const axisStartKey = direction === "horizontal" ? "x" : "y";
+  const axisEndKey = direction === "horizontal" ? "x2" : "y2";
+  const sizeKey = direction === "horizontal" ? "w" : "h";
+  selected.sort((a, b) => {
+    const delta = a.bounds[axisStartKey] - b.bounds[axisStartKey];
+    return Math.abs(delta) > 1e-6 ? delta : a.index - b.index;
+  });
+  const minCoord = Math.min(
+    ...selected.map((item) => item.bounds[axisStartKey])
+  );
+  const maxCoord = Math.max(...selected.map((item) => item.bounds[axisEndKey]));
+  const totalSpan = maxCoord - minCoord;
+  const gaps = selected.length - 1;
+  const totalSize = selected.reduce(
+    (sum, item) => sum + item.bounds[sizeKey],
+    0
+  );
+  const gapSize = gaps > 0 ? (totalSpan - totalSize) / gaps : 0;
+  let cursor = minCoord;
+  selected.forEach(({ obj, bounds }) => {
+    if (direction === "horizontal") {
+      setElementPosition(obj, { x: cursor });
+      cursor += bounds.w + gapSize;
+    } else {
+      setElementPosition(obj, { y: cursor });
+      cursor += bounds.h + gapSize;
+    }
+  });
+}
+
+function warnIfSlideElementsOutOfBounds(slide, pptx) {
+  if (!slide || !Array.isArray(slide._slideObjects)) {
+    console.warn(
+      "Invalid slide object passed to warnIfSlideElementsOutOfBounds()"
+    );
+    return;
+  }
+  const {
+    width: slideWidth,
+    height: slideHeight,
+    source,
+  } = getSlideDimensions(slide, pptx);
+  const slideIndex =
+    pptx && Array.isArray(pptx._slides) ? pptx._slides.indexOf(slide) : -1;
+  const slideLabel =
+    slideIndex >= 0 ? `Slide ${slideIndex + 1}` : "(Unknown slide index)";
+  if (source === "default") {
+    console.warn(
+      `⚠️ ${slideLabel}: Unable to determine slide dimensions from pptxgenjs internals; assuming width=${slideWidth}, height=${slideHeight}.`
+    );
+  }
+  const EPS = 1e-4;
+  let outOfBoundsCount = 0;
+  const formatElement = (idx, type, bounds) => {
+    const cx = (bounds.x + bounds.w / 2).toFixed(3);
+    const cy = (bounds.y + bounds.h / 2).toFixed(3);
+    return `Element ${idx} (${type}, center_x=${cx}, center_y=${cy})`;
+  };
+  slide._slideObjects.forEach((obj, index) => {
+    const bounds = getElementBounds(obj);
+    const type = inferElementType(obj);
+    const violations = [];
+    if (bounds.x < -EPS) violations.push(`left=${bounds.x.toFixed(3)} < 0`);
+    if (bounds.y < -EPS) violations.push(`top=${bounds.y.toFixed(3)} < 0`);
+    if (bounds.x2 > slideWidth + EPS)
+      violations.push(
+        `right=${bounds.x2.toFixed(3)} > width=${slideWidth.toFixed(3)}`
+      );
+    if (bounds.y2 > slideHeight + EPS)
+      violations.push(
+        `bottom=${bounds.y2.toFixed(3)} > height=${slideHeight.toFixed(3)}`
+      );
+    if (violations.length > 0) {
+      outOfBoundsCount++;
+      console.warn(
+        `⚠️ ${slideLabel}: ${formatElement(
+          index,
+          type,
+          bounds
+        )} exceeds slide bounds (${violations.join(", ")}).`
+      );
+    }
+  });
+  if (outOfBoundsCount > 0) {
+    console.log(
+      `⚠️ ${slideLabel}: Found ${outOfBoundsCount} element(s) extending beyond the slide bounds.`
+    );
+  }
+}
+
+module.exports = {
+  inferElementType,
+  compareElementPosition,
+  warnIfSlideHasOverlaps,
+  alignSlideElements,
+  distributeSlideElements,
+  warnIfSlideElementsOutOfBounds,
+  getSlideDimensions,
+};