@papert-code/papert-code 0.3.95 → 0.3.96

package/dist/skills/slack-gif-creator/core/gif_builder.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""
+GIF Builder - Core module for assembling frames into GIFs optimized for Slack.
+
+This module provides the main interface for creating GIFs from programmatically
+generated frames, with automatic optimization for Slack's requirements.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import imageio.v3 as imageio
+import numpy as np
+from PIL import Image
+
+
+class GIFBuilder:
+    """Builder for creating optimized GIFs from frames."""
+
+    def __init__(self, width: int = 480, height: int = 480, fps: int = 15):
+        """
+        Initialize GIF builder.
+
+        Args:
+            width: Frame width in pixels
+            height: Frame height in pixels
+            fps: Frames per second
+        """
+        self.width = width
+        self.height = height
+        self.fps = fps
+        self.frames: list[np.ndarray] = []
+
+    def add_frame(self, frame: np.ndarray | Image.Image):
+        """
+        Add a frame to the GIF.
+
+        Args:
+            frame: Frame as numpy array or PIL Image (will be converted to RGB)
+        """
+        if isinstance(frame, Image.Image):
+            frame = np.array(frame.convert("RGB"))
+
+        # Ensure frame is correct size
+        if frame.shape[:2] != (self.height, self.width):
+            pil_frame = Image.fromarray(frame)
+            pil_frame = pil_frame.resize(
+                (self.width, self.height), Image.Resampling.LANCZOS
+            )
+            frame = np.array(pil_frame)
+
+        self.frames.append(frame)
+
+    def add_frames(self, frames: list[np.ndarray | Image.Image]):
+        """Add multiple frames at once."""
+        for frame in frames:
+            self.add_frame(frame)
+
+    def optimize_colors(
+        self, num_colors: int = 128, use_global_palette: bool = True
+    ) -> list[np.ndarray]:
+        """
+        Reduce colors in all frames using quantization.
+
+        Args:
+            num_colors: Target number of colors (8-256)
+            use_global_palette: Use a single palette for all frames (better compression)
+
+        Returns:
+            List of color-optimized frames
+        """
+        optimized = []
+
+        if use_global_palette and len(self.frames) > 1:
+            # Create a global palette from all frames
+            # Sample frames to build palette
+            sample_size = min(5, len(self.frames))
+            sample_indices = [
+                int(i * len(self.frames) / sample_size) for i in range(sample_size)
+            ]
+            sample_frames = [self.frames[i] for i in sample_indices]
+
+            # Combine sample frames into a single image for palette generation
+            # Flatten each frame to get all pixels, then stack them
+            all_pixels = np.vstack(
+                [f.reshape(-1, 3) for f in sample_frames]
+            )  # (total_pixels, 3)
+
+            # Create a properly-shaped RGB image from the pixel data
+            # We'll make a roughly square image from all the pixels
+            total_pixels = len(all_pixels)
+            width = min(512, int(np.sqrt(total_pixels)))  # Reasonable width, max 512
+            height = (total_pixels + width - 1) // width  # Ceiling division
+
+            # Pad if necessary to fill the rectangle
+            pixels_needed = width * height
+            if pixels_needed > total_pixels:
+                padding = np.zeros((pixels_needed - total_pixels, 3), dtype=np.uint8)
+                all_pixels = np.vstack([all_pixels, padding])
+
+            # Reshape to proper RGB image format (H, W, 3)
+            img_array = (
+                all_pixels[:pixels_needed].reshape(height, width, 3).astype(np.uint8)
+            )
+            combined_img = Image.fromarray(img_array, mode="RGB")
+
+            # Generate global palette
+            global_palette = combined_img.quantize(colors=num_colors, method=2)
+
+            # Apply global palette to all frames
+            for frame in self.frames:
+                pil_frame = Image.fromarray(frame)
+                quantized = pil_frame.quantize(palette=global_palette, dither=1)
+                optimized.append(np.array(quantized.convert("RGB")))
+        else:
+            # Use per-frame quantization
+            for frame in self.frames:
+                pil_frame = Image.fromarray(frame)
+                quantized = pil_frame.quantize(colors=num_colors, method=2, dither=1)
+                optimized.append(np.array(quantized.convert("RGB")))
+
+        return optimized
+
+    def deduplicate_frames(self, threshold: float = 0.9995) -> int:
+        """
+        Remove duplicate or near-duplicate consecutive frames.
+
+        Args:
+            threshold: Similarity threshold (0.0-1.0). Higher = more strict (0.9995 = nearly identical).
+                      Use 0.9995+ to preserve subtle animations, 0.98 for aggressive removal.
+
+        Returns:
+            Number of frames removed
+        """
+        if len(self.frames) < 2:
+            return 0
+
+        deduplicated = [self.frames[0]]
+        removed_count = 0
+
+        for i in range(1, len(self.frames)):
+            # Compare with previous frame
+            prev_frame = np.array(deduplicated[-1], dtype=np.float32)
+            curr_frame = np.array(self.frames[i], dtype=np.float32)
+
+            # Calculate similarity (normalized)
+            diff = np.abs(prev_frame - curr_frame)
+            similarity = 1.0 - (np.mean(diff) / 255.0)
+
+            # Keep frame if sufficiently different
+            # High threshold (0.9995+) means only remove nearly identical frames
+            if similarity < threshold:
+                deduplicated.append(self.frames[i])
+            else:
+                removed_count += 1
+
+        self.frames = deduplicated
+        return removed_count
+
+    def save(
+        self,
+        output_path: str | Path,
+        num_colors: int = 128,
+        optimize_for_emoji: bool = False,
+        remove_duplicates: bool = False,
+    ) -> dict:
+        """
+        Save frames as optimized GIF for Slack.
+
+        Args:
+            output_path: Where to save the GIF
+            num_colors: Number of colors to use (fewer = smaller file)
+            optimize_for_emoji: If True, optimize for emoji size (128x128, fewer colors)
+            remove_duplicates: If True, remove duplicate consecutive frames (opt-in)
+
+        Returns:
+            Dictionary with file info (path, size, dimensions, frame_count)
+        """
+        if not self.frames:
+            raise ValueError("No frames to save. Add frames with add_frame() first.")
+
+        output_path = Path(output_path)
+
+        # Remove duplicate frames to reduce file size
+        if remove_duplicates:
+            removed = self.deduplicate_frames(threshold=0.9995)
+            if removed > 0:
+                print(
+                    f"  Removed {removed} nearly identical frames (preserved subtle animations)"
+                )
+
+        # Optimize for emoji if requested
+        if optimize_for_emoji:
+            if self.width > 128 or self.height > 128:
+                print(
+                    f"  Resizing from {self.width}x{self.height} to 128x128 for emoji"
+                )
+                self.width = 128
+                self.height = 128
+                # Resize all frames
+                resized_frames = []
+                for frame in self.frames:
+                    pil_frame = Image.fromarray(frame)
+                    pil_frame = pil_frame.resize((128, 128), Image.Resampling.LANCZOS)
+                    resized_frames.append(np.array(pil_frame))
+                self.frames = resized_frames
+            num_colors = min(num_colors, 48)  # More aggressive color limit for emoji
+
+            # More aggressive FPS reduction for emoji
+            if len(self.frames) > 12:
+                print(
+                    f"  Reducing frames from {len(self.frames)} to ~12 for emoji size"
+                )
+                # Keep every nth frame to get close to 12 frames
+                keep_every = max(1, len(self.frames) // 12)
+                self.frames = [
+                    self.frames[i] for i in range(0, len(self.frames), keep_every)
+                ]
+
+        # Optimize colors with global palette
+        optimized_frames = self.optimize_colors(num_colors, use_global_palette=True)
+
+        # Calculate frame duration in milliseconds
+        frame_duration = 1000 / self.fps
+
+        # Save GIF
+        imageio.imwrite(
+            output_path,
+            optimized_frames,
+            duration=frame_duration,
+            loop=0,  # Infinite loop
+        )
+
+        # Get file info
+        file_size_kb = output_path.stat().st_size / 1024
+        file_size_mb = file_size_kb / 1024
+
+        info = {
+            "path": str(output_path),
+            "size_kb": file_size_kb,
+            "size_mb": file_size_mb,
+            "dimensions": f"{self.width}x{self.height}",
+            "frame_count": len(optimized_frames),
+            "fps": self.fps,
+            "duration_seconds": len(optimized_frames) / self.fps,
+            "colors": num_colors,
+        }
+
+        # Print info
+        print(f"\n✓ GIF created successfully!")
+        print(f"  Path: {output_path}")
+        print(f"  Size: {file_size_kb:.1f} KB ({file_size_mb:.2f} MB)")
+        print(f"  Dimensions: {self.width}x{self.height}")
+        print(f"  Frames: {len(optimized_frames)} @ {self.fps} fps")
+        print(f"  Duration: {info['duration_seconds']:.1f}s")
+        print(f"  Colors: {num_colors}")
+
+        # Size info
+        if optimize_for_emoji:
+            print(f"  Optimized for emoji (128x128, reduced colors)")
+        if file_size_mb > 1.0:
+            print(f"\n  Note: Large file size ({file_size_kb:.1f} KB)")
+            print("  Consider: fewer frames, smaller dimensions, or fewer colors")
+
+        return info
+
+    def clear(self):
+        """Clear all frames (useful for creating multiple GIFs)."""
+        self.frames = []

package/dist/skills/slack-gif-creator/core/validators.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+Validators - Check if GIFs meet Slack's requirements.
+
+These validators help ensure your GIFs meet Slack's size and dimension constraints.
+"""
+
+from pathlib import Path
+
+
+def validate_gif(
+    gif_path: str | Path, is_emoji: bool = True, verbose: bool = True
+) -> tuple[bool, dict]:
+    """
+    Validate GIF for Slack (dimensions, size, frame count).
+
+    Args:
+        gif_path: Path to GIF file
+        is_emoji: True for emoji (128x128 recommended), False for message GIF
+        verbose: Print validation details
+
+    Returns:
+        Tuple of (passes: bool, results: dict with all details)
+    """
+    from PIL import Image
+
+    gif_path = Path(gif_path)
+
+    if not gif_path.exists():
+        return False, {"error": f"File not found: {gif_path}"}
+
+    # Get file size
+    size_bytes = gif_path.stat().st_size
+    size_kb = size_bytes / 1024
+    size_mb = size_kb / 1024
+
+    # Get dimensions and frame info
+    try:
+        with Image.open(gif_path) as img:
+            width, height = img.size
+
+            # Count frames
+            frame_count = 0
+            try:
+                while True:
+                    img.seek(frame_count)
+                    frame_count += 1
+            except EOFError:
+                pass
+
+            # Get duration
+            try:
+                duration_ms = img.info.get("duration", 100)
+                total_duration = (duration_ms * frame_count) / 1000
+                fps = frame_count / total_duration if total_duration > 0 else 0
+            except:
+                total_duration = None
+                fps = None
+
+    except Exception as e:
+        return False, {"error": f"Failed to read GIF: {e}"}
+
+    # Validate dimensions
+    if is_emoji:
+        optimal = width == height == 128
+        acceptable = width == height and 64 <= width <= 128
+        dim_pass = acceptable
+    else:
+        aspect_ratio = (
+            max(width, height) / min(width, height)
+            if min(width, height) > 0
+            else float("inf")
+        )
+        dim_pass = aspect_ratio <= 2.0 and 320 <= min(width, height) <= 640
+
+    results = {
+        "file": str(gif_path),
+        "passes": dim_pass,
+        "width": width,
+        "height": height,
+        "size_kb": size_kb,
+        "size_mb": size_mb,
+        "frame_count": frame_count,
+        "duration_seconds": total_duration,
+        "fps": fps,
+        "is_emoji": is_emoji,
+        "optimal": optimal if is_emoji else None,
+    }
+
+    # Print if verbose
+    if verbose:
+        print(f"\nValidating {gif_path.name}:")
+        print(
+            f"  Dimensions: {width}x{height}"
+            + (
+                f" ({'optimal' if optimal else 'acceptable'})"
+                if is_emoji and acceptable
+                else ""
+            )
+        )
+        print(
+            f"  Size: {size_kb:.1f} KB"
+            + (f" ({size_mb:.2f} MB)" if size_mb >= 1.0 else "")
+        )
+        print(
+            f"  Frames: {frame_count}"
+            + (f" @ {fps:.1f} fps ({total_duration:.1f}s)" if fps else "")
+        )
+
+        if not dim_pass:
+            print(
+                f"  Note: {'Emoji should be 128x128' if is_emoji else 'Unusual dimensions for Slack'}"
+            )
+
+        if size_mb > 5.0:
+            print(f"  Note: Large file size - consider fewer frames/colors")
+
+    return dim_pass, results
+
+
+def is_slack_ready(
+    gif_path: str | Path, is_emoji: bool = True, verbose: bool = True
+) -> bool:
+    """
+    Quick check if GIF is ready for Slack.
+
+    Args:
+        gif_path: Path to GIF file
+        is_emoji: True for emoji GIF, False for message GIF
+        verbose: Print feedback
+
+    Returns:
+        True if dimensions are acceptable
+    """
+    passes, _ = validate_gif(gif_path, is_emoji, verbose)
+    return passes

package/dist/skills/slack-gif-creator/requirements.txt

@@ -0,0 +1,4 @@
+pillow>=10.0.0
+imageio>=2.31.0
+imageio-ffmpeg>=0.4.9
+numpy>=1.24.0

package/dist/skills/theme-factory/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: theme-factory
+description: Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
+license: Complete terms in LICENSE.txt
+---
+
+
+# Theme Factory Skill
+
+This skill provides a curated collection of professional font and color themes themes, each with carefully selected color palettes and font pairings. Once a theme is chosen, it can be applied to any artifact.
+
+## Purpose
+
+To apply consistent, professional styling to presentation slide decks, use this skill. Each theme includes:
+- A cohesive color palette with hex codes
+- Complementary font pairings for headers and body text
+- A distinct visual identity suitable for different contexts and audiences
+
+## Usage Instructions
+
+To apply styling to a slide deck or other artifact:
+
+1. **Show the theme showcase**: Display the `theme-showcase.pdf` file to allow users to see all available themes visually. Do not make any modifications to it; simply show the file for viewing.
+2. **Ask for their choice**: Ask which theme to apply to the deck
+3. **Wait for selection**: Get explicit confirmation about the chosen theme
+4. **Apply the theme**: Once a theme has been chosen, apply the selected theme's colors and fonts to the deck/artifact
+
+## Themes Available
+
+The following 10 themes are available, each showcased in `theme-showcase.pdf`:
+
+1. **Ocean Depths** - Professional and calming maritime theme
+2. **Sunset Boulevard** - Warm and vibrant sunset colors
+3. **Forest Canopy** - Natural and grounded earth tones
+4. **Modern Minimalist** - Clean and contemporary grayscale
+5. **Golden Hour** - Rich and warm autumnal palette
+6. **Arctic Frost** - Cool and crisp winter-inspired theme
+7. **Desert Rose** - Soft and sophisticated dusty tones
+8. **Tech Innovation** - Bold and modern tech aesthetic
+9. **Botanical Garden** - Fresh and organic garden colors
+10. **Midnight Galaxy** - Dramatic and cosmic deep tones
+
+## Theme Details
+
+Each theme is defined in the `themes/` directory with complete specifications including:
+- Cohesive color palette with hex codes
+- Complementary font pairings for headers and body text
+- Distinct visual identity suitable for different contexts and audiences
+
+## Application Process
+
+After a preferred theme is selected:
+1. Read the corresponding theme file from the `themes/` directory
+2. Apply the specified colors and fonts consistently throughout the deck
+3. Ensure proper contrast and readability
+4. Maintain the theme's visual identity across all slides
+
+## Create your Own Theme
+To handle cases where none of the existing themes work for an artifact, create a custom theme. Based on provided inputs, generate a new theme similar to the ones above. Give the theme a similar name describing what the font/color combinations represent. Use any basic description provided to choose appropriate colors/fonts. After generating the theme, show it for review and verification. Following that, apply the theme as described above.

package/dist/skills/theme-factory/themes/arctic-frost.md

@@ -0,0 +1,19 @@
+# Arctic Frost
+
+A cool and crisp winter-inspired theme that conveys clarity, precision, and professionalism.
+
+## Color Palette
+
+- **Ice Blue**: `#d4e4f7` - Light backgrounds and highlights
+- **Steel Blue**: `#4a6fa5` - Primary accent color
+- **Silver**: `#c0c0c0` - Metallic accent elements
+- **Crisp White**: `#fafafa` - Clean backgrounds and text
+
+## Typography
+
+- **Headers**: DejaVu Sans Bold
+- **Body Text**: DejaVu Sans
+
+## Best Used For
+
+Healthcare presentations, technology solutions, winter sports, clean tech, pharmaceutical content.

package/dist/skills/theme-factory/themes/botanical-garden.md

@@ -0,0 +1,19 @@
+# Botanical Garden
+
+A fresh and organic theme featuring vibrant garden-inspired colors for lively presentations.
+
+## Color Palette
+
+- **Fern Green**: `#4a7c59` - Rich natural green
+- **Marigold**: `#f9a620` - Bright floral accent
+- **Terracotta**: `#b7472a` - Earthy warm tone
+- **Cream**: `#f5f3ed` - Soft neutral backgrounds
+
+## Typography
+
+- **Headers**: DejaVu Serif Bold
+- **Body Text**: DejaVu Sans
+
+## Best Used For
+
+Garden centers, food presentations, farm-to-table content, botanical brands, natural products.

package/dist/skills/theme-factory/themes/desert-rose.md

@@ -0,0 +1,19 @@
+# Desert Rose
+
+A soft and sophisticated theme with dusty, muted tones perfect for elegant presentations.
+
+## Color Palette
+
+- **Dusty Rose**: `#d4a5a5` - Soft primary color
+- **Clay**: `#b87d6d` - Earthy accent
+- **Sand**: `#e8d5c4` - Warm neutral backgrounds
+- **Deep Burgundy**: `#5d2e46` - Rich dark contrast
+
+## Typography
+
+- **Headers**: FreeSans Bold
+- **Body Text**: FreeSans
+
+## Best Used For
+
+Fashion presentations, beauty brands, wedding planning, interior design, boutique businesses.

package/dist/skills/theme-factory/themes/forest-canopy.md

@@ -0,0 +1,19 @@
+# Forest Canopy
+
+A natural and grounded theme featuring earth tones inspired by dense forest environments.
+
+## Color Palette
+
+- **Forest Green**: `#2d4a2b` - Primary dark green
+- **Sage**: `#7d8471` - Muted green accent
+- **Olive**: `#a4ac86` - Light accent color
+- **Ivory**: `#faf9f6` - Backgrounds and text
+
+## Typography
+
+- **Headers**: FreeSerif Bold
+- **Body Text**: FreeSans
+
+## Best Used For
+
+Environmental presentations, sustainability reports, outdoor brands, wellness content, organic products.

package/dist/skills/theme-factory/themes/golden-hour.md

@@ -0,0 +1,19 @@
+# Golden Hour
+
+A rich and warm autumnal palette that creates an inviting and sophisticated atmosphere.
+
+## Color Palette
+
+- **Mustard Yellow**: `#f4a900` - Bold primary accent
+- **Terracotta**: `#c1666b` - Warm secondary color
+- **Warm Beige**: `#d4b896` - Neutral backgrounds
+- **Chocolate Brown**: `#4a403a` - Dark text and anchors
+
+## Typography
+
+- **Headers**: FreeSans Bold
+- **Body Text**: FreeSans
+
+## Best Used For
+
+Restaurant presentations, hospitality brands, fall campaigns, cozy lifestyle content, artisan products.

package/dist/skills/theme-factory/themes/midnight-galaxy.md

@@ -0,0 +1,19 @@
+# Midnight Galaxy
+
+A dramatic and cosmic theme with deep purples and mystical tones for impactful presentations.
+
+## Color Palette
+
+- **Deep Purple**: `#2b1e3e` - Rich dark base
+- **Cosmic Blue**: `#4a4e8f` - Mystical mid-tone
+- **Lavender**: `#a490c2` - Soft accent color
+- **Silver**: `#e6e6fa` - Light highlights and text
+
+## Typography
+
+- **Headers**: FreeSans Bold
+- **Body Text**: FreeSans
+
+## Best Used For
+
+Entertainment industry, gaming presentations, nightlife venues, luxury brands, creative agencies.

package/dist/skills/theme-factory/themes/modern-minimalist.md

@@ -0,0 +1,19 @@
+# Modern Minimalist
+
+A clean and contemporary theme with a sophisticated grayscale palette for maximum versatility.
+
+## Color Palette
+
+- **Charcoal**: `#36454f` - Primary dark color
+- **Slate Gray**: `#708090` - Medium gray for accents
+- **Light Gray**: `#d3d3d3` - Backgrounds and dividers
+- **White**: `#ffffff` - Text and clean backgrounds
+
+## Typography
+
+- **Headers**: DejaVu Sans Bold
+- **Body Text**: DejaVu Sans
+
+## Best Used For
+
+Tech presentations, architecture portfolios, design showcases, modern business proposals, data visualization.

package/dist/skills/theme-factory/themes/ocean-depths.md

@@ -0,0 +1,19 @@
+# Ocean Depths
+
+A professional and calming maritime theme that evokes the serenity of deep ocean waters.
+
+## Color Palette
+
+- **Deep Navy**: `#1a2332` - Primary background color
+- **Teal**: `#2d8b8b` - Accent color for highlights and emphasis
+- **Seafoam**: `#a8dadc` - Secondary accent for lighter elements
+- **Cream**: `#f1faee` - Text and light backgrounds
+
+## Typography
+
+- **Headers**: DejaVu Sans Bold
+- **Body Text**: DejaVu Sans
+
+## Best Used For
+
+Corporate presentations, financial reports, professional consulting decks, trust-building content.

package/dist/skills/theme-factory/themes/sunset-boulevard.md

@@ -0,0 +1,19 @@
+# Sunset Boulevard
+
+A warm and vibrant theme inspired by golden hour sunsets, perfect for energetic and creative presentations.
+
+## Color Palette
+
+- **Burnt Orange**: `#e76f51` - Primary accent color
+- **Coral**: `#f4a261` - Secondary warm accent
+- **Warm Sand**: `#e9c46a` - Highlighting and backgrounds
+- **Deep Purple**: `#264653` - Dark contrast and text
+
+## Typography
+
+- **Headers**: DejaVu Serif Bold
+- **Body Text**: DejaVu Sans
+
+## Best Used For
+
+Creative pitches, marketing presentations, lifestyle brands, event promotions, inspirational content.

package/dist/skills/theme-factory/themes/tech-innovation.md

@@ -0,0 +1,19 @@
+# Tech Innovation
+
+A bold and modern theme with high-contrast colors perfect for cutting-edge technology presentations.
+
+## Color Palette
+
+- **Electric Blue**: `#0066ff` - Vibrant primary accent
+- **Neon Cyan**: `#00ffff` - Bright highlight color
+- **Dark Gray**: `#1e1e1e` - Deep backgrounds
+- **White**: `#ffffff` - Clean text and contrast
+
+## Typography
+
+- **Headers**: DejaVu Sans Bold
+- **Body Text**: DejaVu Sans
+
+## Best Used For
+
+Tech startups, software launches, innovation showcases, AI/ML presentations, digital transformation content.