@vodailoc/kilo-kit-mcp 1.1.0

package/skills/writing-docs/slides/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: slides
+description: Create and edit presentation slide decks (`.pptx`) with PptxGenJS, bundled layout helpers, and render/validation utilities. Use when tasks involve building a new PowerPoint deck, recreating slides from screenshots/PDFs/reference decks, modifying slide content while preserving editable output, adding charts/diagrams/visuals, or diagnosing layout issues such as overflow, overlaps, and font substitution.
+---
+
+# Slides
+
+## Overview
+
+Use PptxGenJS for slide authoring. Do not use `python-pptx` for deck generation unless the task is inspection-only; keep editable output in JavaScript and deliver both the `.pptx` and the source `.js`.
+
+Keep work in a task-local directory. Only copy final artifacts to the requested destination after rendering and validation pass.
+
+## Bundled Resources
+
+- `assets/pptxgenjs_helpers/`: Copy this folder into the deck workspace and import it locally instead of reimplementing helper logic.
+- `scripts/render_slides.py`: Rasterize a `.pptx` or `.pdf` to per-slide PNGs.
+- `scripts/slides_test.py`: Detect content that overflows the slide canvas.
+- `scripts/create_montage.py`: Build a contact-sheet style montage of rendered slides.
+- `scripts/detect_font.py`: Report missing or substituted fonts as LibreOffice resolves them.
+- `scripts/ensure_raster_image.py`: Convert SVG/EMF/HEIC/PDF-like assets into PNGs for quick inspection.
+- `references/pptxgenjs-helpers.md`: Load only when you need API details or dependency notes.
+
+## Workflow
+
+1. Inspect the request and determine whether you are creating a new deck, recreating an existing deck, or editing one.
+2. Set the slide size up front. Default to 16:9 (`LAYOUT_WIDE`) unless the source material clearly uses another aspect ratio.
+3. Copy `assets/pptxgenjs_helpers/` into the working directory and import the helpers from there.
+4. Build the deck in JavaScript with an explicit theme font, stable spacing, and editable PowerPoint-native elements when practical.
+5. Run the bundled scripts from this skill directory or copy the needed ones into the task workspace. Render the result with `render_slides.py`, review the PNGs, and fix layout issues before delivery.
+6. Run `slides_test.py` for overflow checks when slide edges are tight or the deck is dense.
+7. Deliver the `.pptx`, the authoring `.js`, and any generated assets that are required to rebuild the deck.
+
+## Authoring Rules
+
+- Set theme fonts explicitly. Do not rely on PowerPoint defaults if typography matters.
+- Use `autoFontSize`, `calcTextBox`, and related helpers to size text boxes; do not use PptxGenJS `fit` or `autoFit`.
+- Use bullet options, not literal `•` characters.
+- Use `imageSizingCrop` or `imageSizingContain` instead of PptxGenJS built-in image sizing.
+- Use `latexToSvgDataUri()` for equations and `codeToRuns()` for syntax-highlighted code blocks.
+- Prefer native PowerPoint charts for simple bar/line/pie/histogram style visuals so reviewers can edit them later.
+- For charts or diagrams that PptxGenJS cannot express well, render SVG externally and place the SVG in the slide.
+- Include both `warnIfSlideHasOverlaps(slide, pptx)` and `warnIfSlideElementsOutOfBounds(slide, pptx)` in the submitted JavaScript whenever you generate or substantially edit slides.
+- Fix all unintentional overlap and out-of-bounds warnings before delivering. If an overlap is intentional, leave a short code comment near the relevant element.
+
+## Recreate Or Edit Existing Slides
+
+- Render the source deck or reference PDF first so you can compare slide geometry visually.
+- Match the original aspect ratio before rebuilding layout.
+- Preserve editability where possible: text should stay text, and simple charts should stay native charts.
+- If a reference slide uses raster artwork, use `ensure_raster_image.py` to generate debug PNGs from vector or odd image formats before placing them.
+
+## Validation Commands
+
+Examples below assume you copied the needed scripts into the working directory. If not, invoke the same script paths relative to this skill folder.
+
+```bash
+# Render slides to PNGs for review
+python3 scripts/render_slides.py deck.pptx --output_dir rendered
+
+# Build a montage for quick scanning
+python3 scripts/create_montage.py --input_dir rendered --output_file montage.png
+
+# Check for overflow beyond the original slide canvas
+python3 scripts/slides_test.py deck.pptx
+
+# Detect missing or substituted fonts
+python3 scripts/detect_font.py deck.pptx --json
+```
+
+Load `references/pptxgenjs-helpers.md` if you need the helper API summary or dependency details.

package/skills/writing-docs/slides/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Slides"
+  short_description: "Create and edit PPTX slide decks"
+  icon_small: "./assets/slides-small.svg"
+  icon_large: "./assets/slides.png"
+  default_prompt: "Use $slides to create or update this PPTX slide deck with PptxGenJS and validate the layout."

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

@@ -0,0 +1,104 @@
+// Copyright (c) OpenAI. All rights reserved.
+"use strict";
+
+const fs = require("fs");
+const Prism = require("prismjs");
+let THEME_MAP;
+
+function loadPrismLanguage(lang) {
+  const normalized = String(lang || "plaintext").toLowerCase();
+  const known = new Set([
+    "markup",
+    "html",
+    "xml",
+    "svg",
+    "mathml",
+    "css",
+    "clike",
+    "javascript",
+    "js",
+    "typescript",
+    "ts",
+    "python",
+    "py",
+    "bash",
+    "sh",
+    "json",
+    "yaml",
+    "yml",
+  ]);
+  const map = {
+    js: "javascript",
+    ts: "typescript",
+    py: "python",
+    sh: "bash",
+    yml: "yaml",
+    html: "markup",
+    xml: "markup",
+  };
+  const id = map[normalized] || normalized;
+  if (!Prism.languages[id]) {
+    try {
+      require(`prismjs/components/prism-${id}`);
+    } catch (_e) {}
+  }
+  return Prism.languages[id] || Prism.languages.plain || {};
+}
+
+function buildThemeMap(themeCssModule = "prismjs/themes/prism-okaidia.css") {
+  try {
+    const css = fs.readFileSync(require.resolve(themeCssModule), "utf8");
+    return Object.fromEntries(
+      [
+        ...css.matchAll(
+          /\.token\.([\w-]+)[^{]*\{[^}]*color:\s*([^;\s]+)[^}]*\}/g
+        ),
+      ].map(([, t, c]) => [t, c.replace(/#|!important/g, "").trim()])
+    );
+  } catch (err) {
+    return { plain: "FFFFFF", comment: "999999" };
+  }
+}
+
+function getThemeMap() {
+  if (!THEME_MAP) THEME_MAP = buildThemeMap();
+  return THEME_MAP;
+}
+
+function run(text, type = "plain") {
+  const theme = getThemeMap();
+  return {
+    text,
+    options: {
+      fontFace: "Consolas",
+      color: theme[type] || theme.plain || "FFFFFF",
+      fontSize: 14,
+    },
+  };
+}
+
+function tokensToRuns(tokens) {
+  return tokens.flatMap((t) =>
+    typeof t === "string"
+      ? [run(t)]
+      : Array.isArray(t.content)
+      ? tokensToRuns(t.content)
+      : [run(t.content, t.type)]
+  );
+}
+
+function codeToRuns(code, lang) {
+  const grammar = loadPrismLanguage(lang);
+  const lines = String(code || "").split("\n");
+  const pad = lines.length.toString().length;
+  return lines.flatMap((line, i) => [
+    run(`${(i + 1).toString().padStart(pad, " ")} `, "comment"),
+    ...tokensToRuns(Prism.tokenize(line, grammar)),
+    ...(i < lines.length - 1 ? [run("\n")] : []),
+  ]);
+}
+
+module.exports = {
+  codeToRuns,
+  buildThemeMap,
+};

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

@@ -0,0 +1,333 @@
+// Copyright (c) OpenAI. All rights reserved.
+"use strict";
+
+const fs = require("fs");
+
+// Accept either a filesystem path, a data URI, raw SVG string, or a Buffer
+// and normalize to a Buffer for type/size probing.
+function readInputAsBuffer(source) {
+  if (!source) throw new Error("Image source is empty");
+  if (Buffer.isBuffer(source)) return { buffer: source, type: "buffer" };
+  if (typeof source === "string") {
+    // data URI (we primarily emit base64 data URIs for SVG via helpers)
+    if (source.startsWith("data:")) {
+      const type = "dataUri";
+      const comma = source.indexOf(",");
+      const payload = comma !== -1 ? source.slice(comma + 1) : source;
+      // Our helpers use base64; if not, try URI decode then treat as raw text
+      try {
+        return { buffer: Buffer.from(payload, "base64"), type: type };
+      } catch (_e) {
+        try {
+          return {
+            buffer: Buffer.from(decodeURIComponent(payload), "utf8"),
+            type: type,
+          };
+        } catch (_e2) {
+          return { buffer: Buffer.from(payload, "utf8"), type: type };
+        }
+      }
+    }
+    // Raw inline SVG string
+    if (source.includes("<svg")) {
+      return { buffer: Buffer.from(source, "utf8"), type: "rawSvg" };
+    }
+    // Treat as filesystem path
+    return { buffer: fs.readFileSync(source), type: "path" };
+  }
+  throw new Error("Unsupported image source type");
+}
+
+function isPng(buf) {
+  return (
+    buf.length >= 24 &&
+    buf[0] === 0x89 &&
+    buf[1] === 0x50 &&
+    buf[2] === 0x4e &&
+    buf[3] === 0x47 &&
+    buf[4] === 0x0d &&
+    buf[5] === 0x0a &&
+    buf[6] === 0x1a &&
+    buf[7] === 0x0a
+  );
+}
+
+function isJpeg(buf) {
+  return (
+    buf.length > 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff
+  );
+}
+
+function isGif(buf) {
+  return (
+    buf.length >= 10 &&
+    buf[0] === 0x47 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x38 &&
+    (buf[4] === 0x39 || buf[4] === 0x37) &&
+    buf[5] === 0x61
+  );
+}
+
+function isWebp(buf) {
+  return (
+    buf.length >= 16 &&
+    buf[0] === 0x52 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x46 &&
+    buf[8] === 0x57 &&
+    buf[9] === 0x45 &&
+    buf[10] === 0x42 &&
+    buf[11] === 0x50
+  );
+}
+
+function isSvg(buf) {
+  const head = buf.slice(0, 200).toString("utf8");
+  return head.includes("<svg");
+}
+
+function readPngSize(buf) {
+  // IHDR chunk: width/height at offset 16, big-endian
+  const width = buf.readUInt32BE(16);
+  const height = buf.readUInt32BE(20);
+  return { width, height, type: "png" };
+}
+
+function readGifSize(buf) {
+  const width = buf.readUInt16LE(6);
+  const height = buf.readUInt16LE(8);
+  return { width, height, type: "gif" };
+}
+
+function readWebpSize(buf) {
+  // Handle VP8X, VP8L, VP8
+  // Reference: https://developers.google.com/speed/webp/docs/riff_container
+  const riffSize = buf.readUInt32LE(4) + 8;
+  let offset = 12; // start of first chunk
+  while (offset + 8 <= riffSize && offset + 8 <= buf.length) {
+    const chunkTag = buf.slice(offset, offset + 4).toString("ascii");
+    const chunkSize = buf.readUInt32LE(offset + 4);
+    if (chunkTag === "VP8X") {
+      // Canvas size stored at bytes 12..17 (6 bytes), 24 bits each minus 1
+      const wMinus1 = buf.readUIntLE(offset + 12, 3);
+      const hMinus1 = buf.readUIntLE(offset + 15, 3);
+      return { width: wMinus1 + 1, height: hMinus1 + 1, type: "webp" };
+    }
+    if (chunkTag === "VP8 ") {
+      // Lossy bitstream: frame header at start of data
+      // Parse minimally for width/height
+      const start = offset + 8;
+      if (start + 10 < buf.length) {
+        const width = buf.readUInt16LE(start + 6) & 0x3fff;
+        const height = buf.readUInt16LE(start + 8) & 0x3fff;
+        return { width, height, type: "webp" };
+      }
+    }
+    if (chunkTag === "VP8L") {
+      // Lossless bitstream: 14-bit width/height encoded
+      const start = offset + 8;
+      if (start + 5 <= buf.length) {
+        const b0 = buf[start + 1];
+        const b1 = buf[start + 2];
+        const b2 = buf[start + 3];
+        const b3 = buf[start + 4];
+        const width = 1 + (((b1 & 0x3f) << 8) | b0);
+        const height =
+          1 + (((b3 & 0xf) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6));
+        return { width, height, type: "webp" };
+      }
+    }
+    offset += 8 + ((chunkSize + 1) & ~1); // chunks are padded to even size
+  }
+  throw new Error("Unsupported WEBP variant for size detection");
+}
+
+function readJpegSize(buf) {
+  let offset = 2;
+  while (offset < buf.length) {
+    if (buf[offset] !== 0xff) {
+      offset++;
+      continue;
+    }
+    const marker = buf[offset + 1];
+    // SOF0..SOF3, SOF5..SOF7, SOF9..SOF11, SOF13..SOF15
+    if (
+      (marker >= 0xc0 && marker <= 0xc3) ||
+      (marker >= 0xc5 && marker <= 0xc7) ||
+      (marker >= 0xc9 && marker <= 0xcb) ||
+      (marker >= 0xcd && marker <= 0xcf)
+    ) {
+      const blockLength = buf.readUInt16BE(offset + 2);
+      const height = buf.readUInt16BE(offset + 5);
+      const width = buf.readUInt16BE(offset + 7);
+      return { width, height, type: "jpeg" };
+    }
+    const blockLength = buf.readUInt16BE(offset + 2);
+    if (!Number.isFinite(blockLength) || blockLength < 2) break;
+    offset += 2 + blockLength;
+  }
+  throw new Error("JPEG size not found");
+}
+
+function parseSvgSize(buf) {
+  const text = buf.toString("utf8");
+  const a = text.indexOf("<svg");
+  const b = text.indexOf("</svg>");
+  const inner = a !== -1 && b !== -1 ? text.slice(a, b + 6) : text;
+  const widthMatch = inner.match(/\bwidth\s*=\s*"([^"]+)"/i);
+  const heightMatch = inner.match(/\bheight\s*=\s*"([^"]+)"/i);
+  const viewBoxMatch = inner.match(/\bviewBox\s*=\s*"([^"]+)"/i);
+
+  function toPx(v) {
+    if (!v) return null;
+    const m = String(v)
+      .trim()
+      .match(/([0-9.]+)\s*(px|pt|em|ex|cm|mm|in|%)?/i);
+    if (!m) return null;
+    const n = parseFloat(m[1]);
+    const unit = (m[2] || "px").toLowerCase();
+    const dpi = 96;
+    switch (unit) {
+      case "px":
+        return n;
+      case "pt":
+        return (n * dpi) / 72;
+      case "in":
+        return n * dpi;
+      case "cm":
+        return (n * dpi) / 2.54;
+      case "mm":
+        return (n * dpi) / 25.4;
+      case "em":
+      case "ex":
+        return n * 16; // rough fallback
+      default:
+        return null;
+    }
+  }
+
+  let widthPx = widthMatch ? toPx(widthMatch[1]) : null;
+  let heightPx = heightMatch ? toPx(heightMatch[1]) : null;
+  if ((widthPx == null || heightPx == null) && viewBoxMatch) {
+    const parts = viewBoxMatch[1].trim().split(/\s+/).map(Number);
+    if (parts.length === 4) {
+      const vbw = parts[2];
+      const vbh = parts[3];
+      if (!widthPx && vbh) widthPx = vbw;
+      if (!heightPx && vbw) heightPx = vbh;
+    }
+  }
+  if (!widthPx || !heightPx) {
+    // Fallback if sizes missing
+    widthPx = widthPx || 100;
+    heightPx = heightPx || 100;
+  }
+  return { width: widthPx, height: heightPx, type: "svg" };
+}
+
+function getImageDimensions(pathOrData) {
+  const { buffer: buf, type } = readInputAsBuffer(pathOrData);
+  let meta;
+  if (isPng(buf)) meta = readPngSize(buf);
+  else if (isJpeg(buf)) meta = readJpegSize(buf);
+  else if (isGif(buf)) meta = readGifSize(buf);
+  else if (isWebp(buf)) meta = readWebpSize(buf);
+  else if (isSvg(buf)) meta = parseSvgSize(buf);
+  else {
+    const suffix =
+      type === "path" && typeof pathOrData === "string"
+        ? ` (path: ${pathOrData})`
+        : "";
+    throw new Error("Unsupported image format for provided source" + suffix);
+  }
+
+  const aspectRatio =
+    meta.width > 0 && meta.height > 0 ? meta.width / meta.height : 1;
+  return {
+    width: meta.width,
+    height: meta.height,
+    aspectRatio,
+    type: meta.type,
+  };
+}
+
+function imageSizingCrop(source, x, y, w, h, cx, cy, cw, ch) {
+  const { aspectRatio } = getImageDimensions(source);
+  const boxAspect = w / h;
+
+  if (
+    cx === undefined ||
+    cy === undefined ||
+    cw === undefined ||
+    ch === undefined
+  ) {
+    let cropXFrac, cropYFrac, cropWFrac, cropHFrac;
+    if (aspectRatio >= boxAspect) {
+      cropHFrac = 1;
+      cropWFrac = boxAspect / aspectRatio;
+      cropXFrac = (1 - cropWFrac) / 2;
+      cropYFrac = 0;
+    } else {
+      cropWFrac = 1;
+      cropHFrac = aspectRatio / boxAspect;
+      cropXFrac = 0;
+      cropYFrac = (1 - cropHFrac) / 2;
+    }
+    cx = cropXFrac;
+    cy = cropYFrac;
+    cw = cropWFrac;
+    ch = cropHFrac;
+  }
+
+  let virtualW = w / cw;
+  let virtualH = virtualW / aspectRatio;
+  const eps = 1e-6;
+  if (Math.abs(virtualH * ch - h) > eps) {
+    virtualH = h / ch;
+    virtualW = virtualH * aspectRatio;
+  }
+
+  const cropXIn = cx * virtualW;
+  const cropYIn = cy * virtualH;
+  return {
+    x,
+    y,
+    w: virtualW,
+    h: virtualH,
+    sizing: {
+      type: "crop",
+      x: cropXIn,
+      y: cropYIn,
+      w: w,
+      h: h,
+    },
+  };
+}
+
+function imageSizingContain(source, x, y, w, h) {
+  const { aspectRatio } = getImageDimensions(source);
+  let w2, h2;
+  const boxAspect = w / h;
+  if (aspectRatio >= boxAspect) {
+    w2 = w;
+    h2 = w2 / aspectRatio;
+  } else {
+    h2 = h;
+    w2 = h2 * aspectRatio;
+  }
+  return {
+    x: x + (w - w2) / 2,
+    y: y + (h - h2) / 2,
+    w: w2,
+    h: h2,
+  };
+}
+
+module.exports = {
+  getImageDimensions,
+  imageSizingCrop,
+  imageSizingContain,
+};

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

@@ -0,0 +1,33 @@
+// Copyright (c) OpenAI. All rights reserved.
+"use strict";
+
+const VERSION = "1.2.0";
+
+const text = require("./text");
+const image = require("./image");
+const svg = require("./svg");
+const latex = require("./latex");
+const code = require("./code");
+const layout = require("./layout");
+const layoutBuilders = require("./layout_builders");
+const util = require("./util");
+
+module.exports = {
+  VERSION,
+  // text layout
+  ...text,
+  // images
+  ...image,
+  // svg helpers
+  ...svg,
+  // LaTeX -> SVG
+  ...latex,
+  // code block -> pptx text runs
+  ...code,
+  // slide layout analyzers
+  ...layout,
+  // slide layout builders
+  ...layoutBuilders,
+  // text layout helpers and utilities
+  ...util,
+};

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

@@ -0,0 +1,51 @@
+// Copyright (c) OpenAI. All rights reserved.
+"use strict";
+
+let _mathjax;
+let _adaptor;
+let _doc;
+
+function ensureMathJax() {
+  if (_mathjax && _adaptor && _doc) return;
+  try {
+    const { mathjax } = require("mathjax-full/js/mathjax.js");
+    const { TeX } = require("mathjax-full/js/input/tex.js");
+    const { SVG } = require("mathjax-full/js/output/svg.js");
+    const { liteAdaptor } = require("mathjax-full/js/adaptors/liteAdaptor.js");
+    const { RegisterHTMLHandler } = require("mathjax-full/js/handlers/html.js");
+    const { AllPackages } = require("mathjax-full/js/input/tex/AllPackages.js");
+
+    _adaptor = liteAdaptor();
+    RegisterHTMLHandler(_adaptor);
+    const tex = new TeX({ packages: AllPackages });
+    const out = new SVG({ fontCache: "local" });
+    _doc = mathjax.document("", { InputJax: tex, OutputJax: out });
+    _mathjax = mathjax;
+  } catch (err) {
+    throw new Error(
+      "mathjax-full is not installed. Run `npm i mathjax-full` or avoid latexToSvgDataUri()."
+    );
+  }
+}
+
+function latexToSvgDataUri(latex, display = true) {
+  ensureMathJax();
+  const html = _adaptor.outerHTML(_doc.convert(latex, { display }));
+  const a = html.indexOf("<svg");
+  const b = html.indexOf("</svg>");
+  let svg = a !== -1 && b !== -1 ? html.slice(a, b + 6) : html;
+  svg = svg.replace(/<\?xml[^>]*>/g, "");
+  if (!/xmlns=\"http:\/\/www\.w3\.org\/2000\/svg\"/.test(svg)) {
+    svg = svg.replace(/<svg /, '<svg xmlns="http://www.w3.org/2000/svg" ');
+  }
+  svg = svg.replace(/(width|height)=\"([0-9.]+)(ex|em)\"/g, (_m, attr, num) => {
+    const px = Math.round(parseFloat(num) * 8.5);
+    return `${attr}="${px}px"`;
+  });
+  svg = svg.replace(/currentColor/g, "#000000");
+  return "data:image/svg+xml;base64," + Buffer.from(svg).toString("base64");
+}
+
+module.exports = {
+  latexToSvgDataUri,
+};