@julioventura/opensquad 0.1.17

package/skills/image-ai-generator/scripts/generate.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+Image Generator — Opensquad Skill
+Generates images via Openrouter API using AI image models.
+
+Usage:
+  # Single image
+  python3 generate.py --prompt "description" --output "path/to/image.jpg" --mode test
+
+    # Single image with reference (logo/mascot)
+    python3 generate.py --prompt "description" --output "path/to/image.jpg" --reference "path/to/logo.jpg" --mode production
+
+  # Batch (JSON file with list of {prompt, output} objects)
+  python3 generate.py --batch "path/to/batch.json" --mode production
+"""
+
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+import urllib.request
+import urllib.error
+
+# Model configuration per mode
+MODELS = {
+    "test": "sourceful/riverflow-v2-fast",
+    "production": "google/gemini-3.1-flash-image-preview",
+}
+
+API_URL = "https://openrouter.ai/api/v1/chat/completions"
+
+
+def load_api_key():
+    """Load OPENROUTER_API_KEY from environment."""
+    key = os.environ.get("OPENROUTER_API_KEY")
+    if not key:
+        # Try loading from .env in project root
+        env_candidates = [
+            os.path.join(os.getcwd(), ".env"),
+            os.path.join(os.path.dirname(__file__), "..", "..", "..", ".env"),
+        ]
+        for env_path in env_candidates:
+            env_path = os.path.abspath(env_path)
+            if os.path.exists(env_path):
+                with open(env_path, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line.startswith("OPENROUTER_API_KEY=") and not line.startswith("#"):
+                            key = line.split("=", 1)[1].strip().strip('"').strip("'")
+                            break
+                if key:
+                    break
+    if not key:
+        print("ERROR: OPENROUTER_API_KEY not found in environment or .env file", file=sys.stderr)
+        sys.exit(1)
+    return key
+
+
+def generate_image(prompt, output_path, mode, api_key, reference_image=None):
+    """Generate a single image and save to output_path."""
+    model = MODELS.get(mode, MODELS["test"])
+
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+
+    if reference_image and os.path.exists(reference_image):
+        # Multimodal: send reference image + text prompt
+        ext = os.path.splitext(reference_image)[1].lower()
+        mime_map = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp", ".gif": "image/gif"}
+        mime = mime_map.get(ext, "image/jpeg")
+        with open(reference_image, "rb") as img_f:
+            img_b64 = base64.b64encode(img_f.read()).decode("utf-8")
+        content = [
+            {"type": "image_url", "image_url": {"url": f"data:{mime};base64,{img_b64}"}},
+            {"type": "text", "text": f"Generate an image using the logo/mascot shown in the reference image above. {prompt}. Only output the image, no text."}
+        ]
+    else:
+        content = f"Generate an image: {prompt}. Only output the image, no text."
+
+    payload = json.dumps({
+        "model": model,
+        "messages": [{
+            "role": "user",
+            "content": content
+        }]
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        API_URL,
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=120) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode("utf-8", errors="replace")
+        print(f"  API error [{e.code}]: {error_body[:200]}", file=sys.stderr)
+        return False
+    except Exception as e:
+        print(f"  Request error: {e}", file=sys.stderr)
+        return False
+
+    images = data.get("choices", [{}])[0].get("message", {}).get("images", [])
+    if not images:
+        # Some models return image in content as base64
+        content_resp = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+        if content_resp and isinstance(content_resp, str) and content_resp.startswith("data:image"):
+            img_data = content_resp.split(",", 1)[1] if "," in content_resp else content_resp
+        else:
+            print(f"  No image returned by model {model}", file=sys.stderr)
+            return False
+    else:
+        img_data = images[0].get("image_url", {}).get("url", "")
+        if img_data.startswith("data:"):
+            img_data = img_data.split(",", 1)[1]
+
+    with open(output_path, "wb") as f:
+        f.write(base64.b64decode(img_data))
+
+    size_kb = os.path.getsize(output_path) / 1024
+    print(f"  OK: {output_path} ({size_kb:.0f} KB)")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate images via Openrouter API")
+    parser.add_argument("--prompt", help="Text prompt for single image generation")
+    parser.add_argument("--output", help="Output file path for single image")
+    parser.add_argument("--batch", help="Path to JSON batch file")
+    parser.add_argument("--mode", choices=["test", "production"], default="test",
+                        help="Generation mode: test (cheap) or production (high-quality)")
+    parser.add_argument("--reference", help="Path to reference image to include in the prompt")
+    args = parser.parse_args()
+
+    if not args.prompt and not args.batch:
+        parser.error("Either --prompt or --batch is required")
+
+    api_key = load_api_key()
+    model = MODELS[args.mode]
+    print(f"Image Generator — Mode: {args.mode} | Model: {model}")
+
+    if args.batch:
+        # Batch mode
+        with open(args.batch, "r") as f:
+            items = json.load(f)
+        print(f"Generating {len(items)} images...\n")
+        success = 0
+        for i, item in enumerate(items, 1):
+            prompt = item["prompt"]
+            output = item["output"]
+            ref = item.get("reference")
+            print(f"[{i}/{len(items)}] {os.path.basename(output)}...")
+            if generate_image(prompt, output, args.mode, api_key, reference_image=ref):
+                success += 1
+            if i < len(items):
+                time.sleep(1)  # Rate limiting
+        print(f"\nDone: {success}/{len(items)} images generated.")
+        sys.exit(0 if success == len(items) else 1)
+    else:
+        # Single mode
+        if not args.output:
+            parser.error("--output is required for single image generation")
+        print(f"Generating: {os.path.basename(args.output)}...")
+        ok = generate_image(args.prompt, args.output, args.mode, api_key, reference_image=args.reference)
+        sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/image-creator/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: image-creator
+description: >
+  Renders HTML/CSS into production-ready images via Playwright.
+  Accepts complete HTML content, opens it in a headless browser at
+  the specified viewport, and captures a pixel-perfect screenshot.
+  Generic engine -- any visual format is defined by the HTML template.
+description_pt-BR: >
+  Renderiza HTML/CSS em imagens prontas para produção via Playwright.
+  Aceita conteúdo HTML completo, abre em um navegador headless na
+  viewport especificada e captura uma screenshot pixel-perfect.
+  Motor genérico -- qualquer formato visual é definido pelo template HTML.
+description_es: >
+  Renderiza HTML/CSS en imágenes listas para producción vía Playwright.
+  Acepta contenido HTML completo, lo abre en un navegador headless en
+  el viewport especificado y captura una screenshot pixel-perfect.
+  Motor genérico -- cualquier formato visual se define por el template HTML.
+type: mcp
+version: "1.0.0"
+mcp:
+  server_name: playwright
+categories: [design, automation, images]
+---
+
+# Image Creator
+
+## When to use
+
+Use the Visual Renderer when you need to generate production-ready images from HTML/CSS. This skill uses Playwright to render complete, self-contained HTML files in a headless browser and capture pixel-perfect screenshots. It is the primary engine for creating social media graphics, carousel slides, infographics, and any other visual content defined by HTML templates.
+
+## Instructions
+
+### Core Workflow
+
+1. **Generate HTML** -- Write a complete, self-contained HTML file with inline CSS. The HTML IS the design -- all styling, layout, fonts, colors, and content must be embedded.
+
+2. **Save HTML** -- Write the HTML file to the squad's output folder (e.g., `output/slides/slide-01.html`)
+
+3. **Start HTTP server** -- Before rendering, start a local HTTP server in the squad's output folder:
+   ```bash
+   python -m http.server 8765 --directory "OUTPUT_DIR" &
+   for i in $(seq 1 30); do curl -s http://localhost:8765 > /dev/null 2>&1 && break || sleep 0.1; done
+   ```
+   Replace OUTPUT_DIR with the actual absolute path to the output folder (quote paths that contain spaces).
+
+4. **Render** -- Use Playwright to:
+   - `browser_navigate` to `http://localhost:8765/slide-01.html` (filename only, not full path)
+   - `browser_resize` to target viewport dimensions
+  - `browser_take_screenshot` to save as JPG or PNG
+
+5. **Verify** -- Read the screenshot to confirm quality. Re-render if needed.
+
+  Before accepting the render, explicitly check that hero title, subtitle, and CTA text are fully visible inside the canvas. If any line clips, collides, or sits too close to the edge, edit the HTML first: shorten the copy or reduce the affected font size in small steps while staying above the platform minimums below. Never accept a cropped title/subtitle as a valid render.
+
+  For slide-based news squads that use the standardized opening/closing layout, prefer the shared helper in `skills/image-creator/editorial-slide-template.js` so title fitting, margin protection, and the editorial frame stay consistent across runs.
+  When `_build/discovery.yaml` provides `company.communication_channels`, preserve those entries in the run artifacts and downstream descriptions/footers. The default closing slide should stay visually clean and point to the description/footer for brand links; only render visible channel cards on the closing slide when the user or the squad instructions explicitly ask for that override.
+  The shared closing slide must stay self-contained. Never depend on remote QR generators or any other network-fetched asset to render the final JPG/PNG. If the main source needs emphasis on-canvas, use a local text/card treatment and keep the full links in `content-package.md`, YouTube descriptions, and newsletter/footer outputs.
+  Keep the exported slide artwork static. If a YouTube slideshow needs a temporal progress indicator, that overlay belongs to the shared video publisher, not to the rendered JPG/PNG slide files.
+  If the batch uses visible slide pagination, verify that the numbering reflects the full slide set rather than only the editorial middle subset.
+
+6. **Stop server** -- After all slides are rendered, stop the HTTP server:
+   ```bash
+   pkill -f "http.server 8765" 2>/dev/null || true
+   ```
+
+### Viewport Presets (width x height)
+
+Use these standard dimensions:
+- Instagram Post: 1080 x 1080
+- Instagram Carousel: 1080 x 1440
+- Instagram Story/Reel: 1080 x 1920
+- Facebook Post: 1200 x 630
+- Twitter/X Post: 1200 x 675
+- LinkedIn Post: 1200 x 627
+- YouTube Thumbnail: 1280 x 720
+- Custom: as specified by the squad
+
+### HTML Template Guidelines
+
+The HTML you generate MUST:
+- Be self-contained (inline CSS, no external dependencies)
+- Use web-safe fonts OR Google Fonts via `@import`
+- Embed images as absolute paths or base64 data URIs
+- Set exact body dimensions matching the viewport
+- Use `margin: 0; padding: 0; overflow: hidden` on body
+- Account for device pixel ratio if high-res needed
+
+Example minimal structure:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { width: 1080px; height: 1440px; overflow: hidden; }
+    /* ... your design ... */
+  </style>
+</head>
+<body>
+  <!-- Your content -->
+</body>
+</html>
+```
+
+### Batch Rendering (Carousels/Multi-slide)
+
+For multi-image outputs like carousels:
+1. Generate one HTML file per slide
+2. Start the HTTP server **once** before the batch (step 3 of Core Workflow)
+3. Render each slide sequentially (step 4 repeated per slide)
+4. Stop the HTTP server **once** after all slides are done (step 6 of Core Workflow)
+5. Name output files with zero-padded numbers: `slide-01.jpg` / `slide-01.png`, `slide-02.jpg` / `slide-02.png`, etc., matching the format chosen for that batch
+6. Keep all slides at the same viewport dimensions
+
+### Best Practices
+
+- Always verify the first rendered image before batch rendering
+- For multi-line hero blocks, treat text fit as a preflight gate: if title/subtitle overflow, fix the HTML before rendering the remaining slides
+- Use CSS Grid/Flexbox for layout -- most reliable across renderers
+- Avoid animations/transitions (static screenshot only)
+- For rounded corners on images, use CSS `border-radius` + `overflow`
+- For emoji rendering, rely on system fonts (Windows: Segoe UI Emoji)
+- Test text overflow -- ensure no content is clipped unexpectedly
+- Keep HTML files alongside output JPG/PNG files for easy re-rendering
+- Default to JPG for social/email batches unless the squad step explicitly asks for PNG; both JPG and PNG are accepted by the shared Opensquad publish flow
+- When a standardized opening slide uses a project name as the hero, fit it before rendering so the title preserves left and right padding; do not accept a title touching the frame edge
+
+### Typography & Readability Rules
+
+Text must be legible in the target platform's smallest viewing context (mobile feed for social platforms). Text inside linked or embedded image files (JPG, JPEG, base64 assets) is decorative and exempt. All HTML text nodes and inline SVG text are subject to these rules.
+
+These are HARD minimums -- never go below them for readable text.
+
+#### Minimum Font Sizes by Platform
+
+| Text Role        | Instagram Post/Carousel | Instagram Story/Reel | LinkedIn/Facebook | YouTube Thumb |
+|------------------|------------------------|----------------------|-------------------|---------------|
+| Hero / Display   | 58px                   | 56px                 | 40px              | 60px          |
+| Heading          | 43px                   | 42px                 | 32px              | 36px          |
+| Body / Bullets   | 34px                   | 32px                 | 24px              | 36px          |
+| Caption / Footer | 24px                   | 20px                 | 20px              | 32px          |
+
+**Universal rule**: No text element meant to be read may use a font size smaller than 20px, on any platform.
+
+#### Font Weight
+
+- Body text and above: use font-weight 500+ (medium/semibold/bold)
+- Caption text: font-weight 500+ strongly recommended; 400 only with explicit high-contrast background (4.5:1 ratio minimum)
+- Avoid thin/light weights (100-300) for any readable text
+
+#### Verification Checklist
+
+Before calling `browser_take_screenshot`, scan your HTML and confirm:
+- All text elements use explicit px sizes (not em/rem that could resolve smaller)
+- No heading is below the Heading minimum for the target platform
+- No body/bullet text is below the Body minimum
+- No footer or metadata text is below the Caption minimum
+- No readable text uses font-weight below 500 (caption at 400 only with 4.5:1 contrast background)
+
+## Available operations
+
+- **Render HTML to JPG/PNG** -- Convert self-contained HTML/CSS into a pixel-perfect screenshot
+- **Batch Render** -- Render multiple slides/pages sequentially for carousels and multi-image content
+- **Viewport Resize** -- Set precise viewport dimensions for any target platform
+- **Quality Verification** -- Visually inspect rendered output and re-render if needed