@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/slides/assets/pptxgenjs_helpers/util.js

@@ -0,0 +1,24 @@
+// Copyright (c) OpenAI. All rights reserved.
+"use strict";
+
+// Safe outer shadow helper (avoid inner/outer mix and XML pitfalls)
+function safeOuterShadow(
+  color = "000000",
+  opacity = 0.25,
+  angle = 45,
+  blur = 3,
+  offset = 2
+) {
+  return {
+    type: "outer",
+    color,
+    opacity,
+    angle,
+    blur,
+    offset,
+  };
+}
+
+module.exports = {
+  safeOuterShadow,
+};

package/skills/slides/assets/slides-small.svg

@@ -0,0 +1,3 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M13.4678 7.86641C13.4678 7.29758 13.4671 6.90292 13.442 6.5961C13.4174 6.29551 13.372 6.12642 13.3076 6.00001C13.1669 5.7238 12.9424 5.49935 12.6662 5.3586C12.5398 5.2942 12.3707 5.24879 12.0701 5.22423C11.7633 5.19916 11.3686 5.19845 10.7998 5.19845H5.19981C4.63097 5.19845 4.23631 5.19916 3.92949 5.22423C3.62893 5.24879 3.4598 5.2942 3.3334 5.3586C3.0572 5.49935 2.83273 5.7238 2.69199 6.00001C2.62758 6.12642 2.58218 6.29551 2.55762 6.5961C2.53255 6.90292 2.53184 7.29758 2.53184 7.86641V9.86641C2.53184 10.4352 2.53255 10.8299 2.55762 11.1367C2.58218 11.4373 2.62759 11.6064 2.69199 11.7328C2.83273 12.009 3.05721 12.2335 3.3334 12.3742C3.45981 12.4386 3.62893 12.484 3.92949 12.5086C4.23631 12.5337 4.63097 12.5344 5.19981 12.5344H10.7998C11.3686 12.5344 11.7633 12.5337 12.0701 12.5086C12.3707 12.484 12.5398 12.4386 12.6662 12.3742C12.9424 12.2335 13.1669 12.009 13.3076 11.7328C13.372 11.6064 13.4174 11.4373 13.442 11.1367C13.4671 10.8299 13.4678 10.4352 13.4678 9.86641V7.86641ZM9.81465 2.11563L12.0053 2.13438L12.1123 2.1461C12.3542 2.19814 12.5344 2.41482 12.5318 2.67188C12.5292 2.92875 12.3448 3.14096 12.1021 3.18829L11.9943 3.19845L9.80996 3.1797C7.87499 3.16721 6.50265 3.17347 4.00527 3.19845C3.71153 3.20138 3.4708 2.96561 3.46777 2.67188C3.46484 2.37813 3.7006 2.1374 3.99434 2.13438C6.49686 2.10936 7.87466 2.10313 9.81465 2.11563ZM14.5318 9.86641C14.5318 10.4177 14.5324 10.8633 14.5029 11.2234C14.473 11.5897 14.4095 11.9143 14.2561 12.2156C14.0133 12.6921 13.6255 13.0799 13.149 13.3227C12.8477 13.4761 12.5231 13.5396 12.1568 13.5695C11.7966 13.599 11.3511 13.5984 10.7998 13.5984H5.19981C4.64853 13.5984 4.20297 13.599 3.84277 13.5695C3.47655 13.5396 3.15187 13.4761 2.85059 13.3227C2.37416 13.0799 1.98631 12.6921 1.74356 12.2156C1.5901 11.9143 1.52661 11.5897 1.49668 11.2234C1.46725 10.8633 1.46777 10.4177 1.46777 9.86641V7.86641C1.46777 7.31514 1.46725 6.86958 1.49668 6.50938C1.52661 6.14315 1.59012 5.81849 1.74356 5.5172C1.98631 5.04077 2.37416 4.65292 2.85059 4.41016C3.15188 4.25671 3.47653 4.19322 3.84277 4.16329C4.20297 4.13386 4.64853 4.13438 5.19981 4.13438H10.7998C11.3511 4.13438 11.7966 4.13386 12.1568 4.16329C12.5231 4.19322 12.8477 4.25671 13.149 4.41016C13.6255 4.65292 14.0133 5.04077 14.2561 5.5172C14.4095 5.81849 14.473 6.14315 14.5029 6.50938C14.5324 6.86958 14.5318 7.31514 14.5318 7.86641V9.86641Z" fill="currentColor"/>
+</svg>

package/skills/slides/references/pptxgenjs-helpers.md

@@ -0,0 +1,61 @@
+# PptxGenJS Helpers
+
+## When To Read This
+
+Read this file when you need helper API details, command examples for the bundled Python scripts, or dependency notes for a slide-generation task.
+
+## Helper Modules
+
+- `autoFontSize(textOrRuns, fontFace, opts)`: Pick a font size that fits a fixed box.
+- `calcTextBox(fontSizePt, opts)`: Estimate text-box geometry from font size and content.
+- `calcTextBoxHeightSimple(fontSizePt, numLines, leading?, padding?)`: Quick text height estimate.
+- `imageSizingCrop(pathOrData, x, y, w, h)`: Center-crop an image into a target box.
+- `imageSizingContain(pathOrData, x, y, w, h)`: Fit an image fully inside a target box.
+- `svgToDataUri(svgString)`: Convert an SVG string into an embeddable data URI.
+- `latexToSvgDataUri(texString)`: Render LaTeX to SVG for crisp equations.
+- `getImageDimensions(pathOrData)`: Read image width, height, type, and aspect ratio.
+- `safeOuterShadow(...)`: Build a safe outer-shadow config for PowerPoint output.
+- `codeToRuns(source, language)`: Convert source code into rich-text runs for `addText`.
+- `warnIfSlideHasOverlaps(slide, pptx)`: Emit overlap warnings for diagnostics.
+- `warnIfSlideElementsOutOfBounds(slide, pptx)`: Emit boundary warnings for diagnostics.
+- `alignSlideElements(slide, indices, alignment)`: Align selected elements precisely.
+- `distributeSlideElements(slide, indices, direction)`: Evenly space selected elements.
+
+## Dependency Notes
+
+JavaScript helpers expect these packages when you use the corresponding features:
+
+- Core authoring: `pptxgenjs`
+- Text measurement: `skia-canvas`, `linebreak`, `fontkit`
+- Syntax highlighting: `prismjs`
+- LaTeX rendering: `mathjax-full`
+
+Python scripts expect these packages:
+
+- `Pillow`
+- `pdf2image`
+- `python-pptx`
+- `numpy`
+
+System tools used by the Python scripts:
+
+- `soffice` / LibreOffice for PPTX to PDF conversion
+- Poppler tools for PDF size/raster support used by `pdf2image`
+- `fc-list` for font inspection
+- Optional rasterization tools for `ensure_raster_image.py`: Inkscape, ImageMagick, Ghostscript, `heif-convert`, `JxrDecApp`
+
+## Script Notes
+
+- `render_slides.py`: Convert a deck to PNGs. Good for visual review and diffing.
+- `slides_test.py`: Add a gray border outside the original canvas, render, and check whether any content leaks into the border.
+- `create_montage.py`: Combine multiple rendered slide images into a single overview image.
+- `detect_font.py`: Distinguish between fonts that are missing entirely and fonts that are installed but substituted during rendering.
+- `ensure_raster_image.py`: Produce a PNG from common vector or unusual raster formats so you can inspect or place the asset easily.
+
+## Practical Rules
+
+- Default to `LAYOUT_WIDE` unless the source material says otherwise.
+- Set font families explicitly before measuring text.
+- Use `valign: "top"` for content boxes that may grow.
+- Prefer native PowerPoint charts over rendered images when the chart is simple and likely to be edited later.
+- Use SVG instead of PNG for diagrams whenever possible.

package/skills/slides/scripts/create_montage.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+# Copyright (c) OpenAI. All rights reserved.
+import argparse
+import re
+import sys
+import tempfile
+from math import ceil
+from os import listdir
+from os.path import basename, expanduser, isfile, join, splitext
+from pathlib import Path
+from typing import Literal
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+if str(SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIR))
+
+from ensure_raster_image import SUPPORTED_EXTS, ensure_raster_image  # type: ignore
+from PIL import Image, ImageDraw, ImageFont, ImageOps
+
+
+def _make_placeholder(w: int, h: int) -> Image.Image:
+    """Create a visible placeholder tile with a light gray fill and a red X cross."""
+    ph = Image.new("RGBA", (w, h), (220, 220, 220, 255))
+    ph_draw = ImageDraw.Draw(ph)
+    line_color = (180, 0, 0, 255)
+    ph_draw.line([(0, 0), (ph.width - 1, ph.height - 1)], fill=line_color, width=3)
+    ph_draw.line([(ph.width - 1, 0), (0, ph.height - 1)], fill=line_color, width=3)
+    return ph
+
+
+def _load_images_with_placeholders(
+    input_files: list[str], retain_converted_files: bool, fail_on_image_error: bool = False
+) -> tuple[list[str], list[Image.Image | None]]:
+    labels = [basename(p) for p in input_files]
+    images: list[Image.Image | None] = []
+    if retain_converted_files:
+        for p in input_files:
+            try:
+                images.append(Image.open(ensure_raster_image(p)))
+            except Exception as e:
+                if fail_on_image_error:
+                    raise
+                print(f'Warning: Failed to convert or load image "{p}": {e}')
+                images.append(None)
+    else:
+        with tempfile.TemporaryDirectory(prefix="montage_convert_") as tmp_conv:
+            for p in input_files:
+                try:
+                    images.append(Image.open(ensure_raster_image(p, tmp_conv)))
+                except Exception as e:
+                    if fail_on_image_error:
+                        raise
+                    print(f'Warning: Failed to convert or load image "{p}": {e}')
+                    images.append(None)
+    return labels, images
+
+
+def _natural_key(s: str) -> list:
+    """Key function for natural sorting (e.g., Slide2 before Slide10)."""
+    return [int(part) if part.isdigit() else part for part in re.split(r"(\d+)", s)]
+
+
+def create_montage(
+    input_files: list[str],
+    output_file: str,
+    num_col: int,
+    cell_w: int,
+    cell_h: int,
+    gap: int,
+    label_mode: Literal["number", "filename", "none"],
+    retain_converted_files: bool = False,
+    fail_on_image_error: bool = False,
+) -> None:
+    """Build a montage with a fixed number of columns.
+
+    Each cell has size `cell_w` x `cell_h`. Every input image is resized isotropically to fit inside
+    the cell. `gap` controls spacing around and between cells (outer margin equals gap).
+    Label behavior is controlled by `label_mode` which can be one of:
+      - "none": no labels are drawn
+      - "number": draw a 1-based index beneath each image
+      - "filename": draw the filename (no directory) beneath each image
+    """
+
+    if num_col <= 0:
+        raise ValueError("num_col must be positive")
+    if cell_w <= 0 or cell_h <= 0:
+        raise ValueError("cell_w and cell_h must be positive")
+
+    labels, images = _load_images_with_placeholders(
+        input_files=input_files,
+        retain_converted_files=retain_converted_files,
+        fail_on_image_error=fail_on_image_error,
+    )
+
+    num_images = len(images)
+    num_valid = sum(1 for im in images if im is not None)
+    if num_valid == 0:
+        raise ValueError("No valid images to render.")
+    if num_valid < num_images:
+        cell_size = round(min(cell_w, cell_h) * 0.6)
+        placeholder = _make_placeholder(cell_size, cell_size)
+    else:
+        placeholder = None
+    cols = num_col
+    rows = ceil(num_images / cols)
+
+    temp_canvas = Image.new("RGB", (10, 10), (255, 255, 255))
+    temp_draw = ImageDraw.Draw(temp_canvas)
+
+    # Choose a readable default font size relative to cell height
+    font: ImageFont.FreeTypeFont | ImageFont.ImageFont
+    try:
+        # Attempt to use a common system font for clarity; fallback to default
+        font_size = max(12, min(36, int(cell_h * 0.12)))
+        font = ImageFont.truetype("arial.ttf", font_size)
+    except Exception:
+        font = ImageFont.load_default()
+        # Adjust default font effect size estimate
+        font_size = 12
+
+    draw_labels = label_mode != "none"
+    label_height = 0
+    if draw_labels:
+        # Height is approximately constant across strings for a given font
+        # Use 'Ag' to approximate ascent ('A') and descender ('g') for filename text
+        sample_text = "1" if label_mode == "number" else "Ag"
+        lbbox = temp_draw.textbbox((0, 0), sample_text, font=font)
+        label_height = ceil(lbbox[3] - lbbox[1]) + 6
+
+    row_h = cell_h + label_height
+
+    canvas_w = cols * cell_w + (cols + 1) * gap
+    canvas_h = rows * row_h + (rows + 1) * gap
+    # Light grey canvas background as in typical slide sorter view
+    canvas = Image.new("RGB", (canvas_w, canvas_h), (242, 242, 242))
+    draw = ImageDraw.Draw(canvas)
+
+    for idx, img in enumerate(images):
+        col = idx % cols
+        row = idx // cols
+
+        # Top-left corner of the cell including outer margin and gaps
+        x0 = gap + col * (cell_w + gap)
+        y0 = gap + row * (row_h + gap)
+
+        # Fit the image within the cell while preserving aspect ratio
+        if label_mode == "number":
+            label = str(idx + 1)
+        elif label_mode == "filename":
+            label = labels[idx]
+        else:
+            label = ""
+
+        if draw_labels:
+            bbox = draw.textbbox((0, 0), label, font=font)
+            text_w = bbox[2] - bbox[0]
+        else:
+            text_w = 0
+
+        if img:
+            resized = ImageOps.contain(
+                img.convert("RGBA"),
+                (cell_w, cell_h),
+                method=Image.Resampling.LANCZOS,
+            )
+        else:
+            print(f"Warning: Using placeholder for invalid image at row={row + 1}, col={col + 1}")
+            assert placeholder is not None
+            resized = placeholder
+
+        paste_x = x0 + (cell_w - resized.width) // 2
+        paste_y = y0 + (cell_h - resized.height) // 2
+        canvas.paste(
+            resized,
+            (paste_x, paste_y),
+            mask=resized.split()[3] if resized.mode == "RGBA" else None,
+        )
+
+        border_color = (160, 160, 160)
+        bw = 1
+        draw.rectangle(
+            [
+                paste_x - bw,
+                paste_y - bw,
+                paste_x + resized.width,
+                paste_y + resized.height,
+            ],
+            outline=border_color,
+            width=bw,
+        )
+
+        if draw_labels:
+            tx = x0 + round((cell_w - text_w) / 2)
+            ty = y0 + cell_h + 3
+            draw.text((tx, ty), label, font=font, fill=(0, 0, 0))
+
+    canvas.save(output_file)
+    print(f"Montage saved to {output_file}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Create a montage with a fixed number of columns. "
+            "Each image is resized isotropically to fit inside a cell of size (cell_width x cell_height)."
+        )
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--input_files", nargs="+", help="List of input image file paths")
+    group.add_argument("--input_dir", help="Directory containing input images")
+    parser.add_argument(
+        "--output_file",
+        required=True,
+        help=(
+            "Path to save the output montage image. The format is inferred from the file extension."
+        ),
+    )
+    parser.add_argument(
+        "--num_col",
+        type=int,
+        default=5,
+        help="Number of images per row (default: 5)",
+    )
+    parser.add_argument(
+        "--cell_width",
+        type=int,
+        default=400,
+        help="Container width in pixels for each image (default: 400)",
+    )
+    parser.add_argument(
+        "--cell_height",
+        type=int,
+        default=225,
+        help="Container height in pixels for each image (default: 225)",
+    )
+    parser.add_argument(
+        "--gap",
+        type=int,
+        default=16,
+        help="Gap in pixels between images and canvas margins (default: 16)",
+    )
+    parser.add_argument(
+        "--label_mode",
+        choices=["number", "filename", "none"],
+        default="number",
+        help=(
+            "Label mode: 'number' to draw 1-based indices (default), 'filename' to use the "
+            "image's filename (no directory), or 'none' for no labels"
+        ),
+    )
+    parser.add_argument(
+        "--retain_converted_files",
+        action="store_true",
+        default=False,
+        help=(
+            "If set, write converted images (e.g., SVG->PNG, WDP->PNG) next to the original files "
+            "instead of a temporary directory."
+        ),
+    )
+    parser.add_argument(
+        "--fail_on_image_error",
+        action="store_true",
+        default=False,
+        help=(
+            "If set, fail immediately when any image conversion/loading fails (no placeholders). "
+            "By default, failures are tolerated and placeholders are used."
+        ),
+    )
+    args = parser.parse_args()
+
+    output_path = expanduser(args.output_file)
+    if args.input_files:
+        input_files = [expanduser(p) for p in args.input_files]
+    else:
+        input_dir = expanduser(args.input_dir)
+        names = sorted(listdir(input_dir), key=_natural_key)
+        dir_entries = [join(input_dir, f) for f in names]
+        input_files = [
+            p for p in dir_entries if isfile(p) and splitext(p)[1].lower() in SUPPORTED_EXTS
+        ]
+        if not input_files:
+            raise ValueError(
+                "No image files with supported extensions were found in the specified directory."
+            )
+
+    create_montage(
+        input_files=input_files,
+        output_file=output_path,
+        num_col=args.num_col,
+        cell_w=args.cell_width,
+        cell_h=args.cell_height,
+        gap=args.gap,
+        label_mode=args.label_mode,
+        retain_converted_files=args.retain_converted_files,
+        fail_on_image_error=args.fail_on_image_error,
+    )
+
+
+if __name__ == "__main__":
+    main()