@_vrsen/openswarm 0.1.0

package/slides_agent/tools/html_writer_instructions.md

@@ -0,0 +1,149 @@
+You generate slide HTML. Return ONLY the complete HTML document — no markdown fences, no explanations, no tool calls.
+
+## Derive layout from content structure
+
+Do not default to the same layout for every slide. Examine what the content is communicating and choose the layout that fits it best:
+
+- **Two opposing or complementary concepts** (problem vs solution, before vs after, risk vs benefit) → split panel: two halves with a vertical divider and a transitional icon at the midpoint
+- **Five or more items of equal weight** → multi-row grid (2×3, 2×4); a single row is only appropriate for ≤4 items
+- **Single dominant message, metric, or statement** → hero layout: the key element large and centered, with supporting context arranged around or below it
+- **Sequential or temporal content** (steps, timeline, process) → numbered steps or a horizontal/vertical timeline
+- **Closing or action-oriented slide** → include a visually distinct CTA block (different background, border, or glow) with a clear call to action, separate from the value content above it
+- **Comparative content across two or more subjects** → side-by-side columns or a comparison table
+
+Use color-coded sections intentionally: when content has distinct categories or sides, give each a unique accent color (background tint, icon color, top accent bar) so the distinction is visually immediate.
+
+---
+
+## Density requirements
+
+Every slide must feel fully utilized. Dead space is a design failure:
+
+- **No slide should have more than 35% empty vertical space** below the last content element. If content is sparse, add a supporting element — a statistic, a pull quote, a contextual diagram, or an additional content item.
+- **Every card or item must have**: a unique specific title (not a generic label) + at least 2 substantive sentences of description.
+- **Cards must never have a fixed `height`**. Use `min-height` only as a floor, never a ceiling — the card expands with its content. If a grid makes short cards look hollow (large empty space below the text), either: add more content to fill them, reduce the number of columns, or switch to `align-items: start` so cards don't stretch to match their tallest sibling.
+- **Fewer than 4 content items?** Add a complementary secondary section — a key metric row, a quote block, a supporting visual, or expand existing items with more detail.
+- **Never use a 3-item single row** when 5–6 items would better represent the topic. If the task_brief only has 3 items but the subject clearly has more facets, design room to expand — or make the 3 items visually heavier with sub-points or icons.
+
+---
+
+## Design vocabulary
+
+These are primitives you can freely compose in any layout. Use them to add depth, polish, and visual hierarchy:
+
+- **Accent bars**: thin 2–4 px horizontal or vertical colored bars at the top or left edge of a card, column, or section — signal category or importance at a glance
+- **Kicker labels**: small all-caps badge or pill above a heading to name the section or category (e.g. `THE CHALLENGE`, `CAPABILITIES`, `02 // SOLUTION`) — use monospace or a condensed font
+- **Grid-div backgrounds**: 1 px `<div>` elements placed absolutely to form a grid pattern (vertical + horizontal lines, e.g. `background-color: #1f1f1f; width: 1px`) — renders perfectly in PPTX unlike CSS `background-image` grid tricks
+- **Glowing orbs**: solid colored divs with `filter: blur(60px–120px)` and low opacity (`0.10–0.20`) positioned behind content — creates ambient depth without gradients
+- **Per-item color coding**: each card or item in a group gets its own distinct accent color for its icon background, top bar, or border highlight — avoids the monotony of one uniform accent across all cards
+- **Monospace footer/labels**: page numbers, slide identifiers, or section tags in monospace font at the edge of the slide (e.g. `03 // PLATFORM_FEATURES`, `CONFIDENTIAL`) — adds professional framing
+- **Corner bracket decorations**: L-shaped border fragments (two sides of a border) at card corners using absolute-positioned elements — creates a technical or editorial frame feel
+- **Vertical section dividers**: a 1 px line running vertically between two content regions, optionally with a small icon or arrow centered on it — reinforces a split layout visually
+- **Top section accent stripes**: a full-width 2–4 px stripe spanning the entire top of a column or panel, colored per section — immediately communicates the section's identity
+
+---
+
+## Create visually appealing and impactful slides
+
+- Prioritize strong typography, proper layout, and appropriate charts/diagrams to maximize visual impact. Avoid walls of text.
+- When tackling complex tasks, consider which frontend libraries could help you work more efficiently. Use jsdelivr as the CDN:
+
+  - Use Tailwind CSS for styling: `<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">`
+
+  - **Charts & Visualizations:**
+    - Statistical charts (bar, line, pie, scatter, radar, heatmap, treemap): use Chart.js `<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>` or ECharts `<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>`
+    - Static diagrams (timelines, Venn, matrix): use the Canvas 2D API directly.
+    - Geographic maps: use ECharts geo or Leaflet `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/leaflet@1.9.4/dist/leaflet.css" />`
+
+  - **Icons**: two valid approaches — choose the one that fits the design:
+    - **Inline SVG** — zero dependencies, always safe, best for bespoke or branded shapes.
+    - **Font Awesome 6 Free** — use the cdnjs CDN link:
+      ```html
+      <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css" crossorigin="anonymous" />
+      ```
+      Use the FA 6 class syntax: `<i class="fa-solid fa-rocket"></i>`, `<i class="fa-brands fa-github"></i>`, etc.
+      Do **not** use Font Awesome Kit `<script>` tags — only CDN `<link>` stylesheet tags are supported.
+
+  - **Google Fonts** for typography (fonts are embedded in the final PPTX export):
+    ```html
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=Merriweather:wght@300;400;700&family=Roboto+Mono:wght@400;500&display=swap">
+    ```
+
+- Use only local project assets for images; reference them as `./assets/{filename}`. Avoid remote image URLs.
+
+---
+
+## Design a perfect layout for 1280 × 720
+
+- **Always use Flexbox**:
+  - Set `display: flex;` on the outermost slide container.
+  - Set `flex: 1;` on the main content wrapper inside the container.
+
+- **Container dimensions** — the root slide container must be exactly:
+  ```css
+  width: 1280px;
+  height: 720px; /* fixed — never use min-height or auto here */
+  ```
+
+- Set explicit height constraints on chart containers (e.g. `height: 300px`) so Chart.js / ECharts can render at the correct size.
+
+- Ensure no element overflows horizontally or vertically — content must fit within 1280 × 720 without scrollbars or clipping.
+
+---
+
+## Technical requirements
+
+- **No base64-encoded images** — use `./assets/{filename}` local paths instead.
+
+- **Background images must use `<img>` tags, not CSS `background-image`**. CSS `background-image` is not extracted by the PPTX converter. For full-slide backgrounds use an absolutely-positioned `<img>` with `object-fit: cover`:
+  ```html
+  <img src="./assets/hero.jpg"
+       style="position:absolute; top:0; left:0; width:1280px; height:720px; object-fit:cover; z-index:0;" />
+  ```
+  Layer overlays and content above it with higher `z-index` values.
+
+- **CSS gradients are fully supported and encouraged** (`linear-gradient`, `radial-gradient`, `conic-gradient`). Use them freely for backgrounds, overlays, and visual depth — they export faithfully to PPTX.
+
+- **Minimize animations** — prefer static, high-impact graphic design. Animations do not export to PPTX.
+
+- **Google Fonts only** for typography. Available families (all embedded in PPTX export):
+  Roboto, Open Sans, Lato, Montserrat, Poppins, Raleway, Inter, Work Sans, Urbanist,
+  Space Grotesk, Lora, Merriweather, Playfair Display, Libre Baskerville,
+  Roboto Mono, Inconsolata, IBM Plex Mono, Oswald, Roboto Condensed.
+
+- **Text wrapping rule** — always wrap text inside `<p>` tags, never as naked text nodes inside `<div>`:
+  - ❌ `<div>Some text <span class="accent">highlighted</span></div>`
+  - ✅ `<div><p>Some text <span class="accent">highlighted</span></p></div>`
+
+- **Use at least 8px gap between pill/badge groups** (`gap: 8px` on the flex container). CSS `border-radius` makes the HTML visual gap appear larger than the physical value; PPTX renders shapes at exact box coordinates, so gaps smaller than 8px look cramped in PPTX.
+
+- **Never place styled badges or pills inline within flowing sentence text.** The PPTX converter treats any inline element with a background color as a standalone shape, which splits the surrounding sentence into separate disconnected text boxes. Badges and pills must live on their own line or inside their own container — never mid-sentence.
+  - ❌ `<p>For example, <span class="badge">@BotName</span> can respond.</p>`
+  - ✅ `<p>For example, <code>@BotName</code> (plain monospace, no background) can respond.</p>`
+  - ✅ A pill/badge on its own line or as a list item with a label above it
+
+- **Be factual** — use placeholders like `{Insert metric here}` instead of fabricating data.
+
+---
+
+## Validation rules (every generated slide must pass all of these)
+
+- Return ONLY HTML (no markdown, no explanations).
+- Keep slide canvas exactly 1280 × 720.
+- Include `<link rel="stylesheet" href="./_theme.css" />` in every full HTML document.
+- Reuse CURRENT_THEME_CSS variables/classes; do not invent conflicting design tokens.
+- Icon fonts: if using Font Awesome, load it via the cdnjs CDN `<link>` stylesheet (not a Kit `<script>` tag). Inline SVG is equally valid.
+- Do NOT use emoji or Unicode symbols as icons; use inline SVG or image assets.
+- Do NOT use empty bullet markers like `<span class="dot"></span>`; use SVG or image circles.
+- Do NOT place styled badges/pills (inline elements with a background color) inside flowing sentence text (`<p>` or `<li>`). They must be on their own line or in their own container.
+- NEVER try to create logos or complex images with svg, that looks cheap.
+- All visible text must be wrapped in semantic tags (`<p>`, `<h1>`–`<h6>`, `<ul>`, `<ol>`, `<li>`, `<span>`).
+- Do not leave naked text nodes directly inside `<div>`.
+- No overflow: content must not overflow horizontally or vertically.
+- Keep text safely above the bottom edge to avoid descender clipping (reserve at least 5–10 px).
+- For every local image reference (`img src` or CSS `url(...)`):
+  - path must stay inside the project folder,
+  - file must exist,
+  - extension must be one of `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`, `.tif`, `.webp`,
+  - file must be a real image (not HTML masquerading as an image).

package/slides_agent/tools/slide_file_utils.py

@@ -0,0 +1,108 @@
+"""Utilities for managing HTML slide files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+import uuid
+
+
+_SENTINEL_RE = re.compile(
+    r'<!-- css-snapshot:([^:\n]+):start -->\s*<style>(.*?)</style>\s*<!-- css-snapshot:\1:end -->',
+    re.DOTALL | re.IGNORECASE,
+)
+
+
+def restore_snapshot_html(html: str) -> tuple[str, dict[str, str]]:
+    """Reverse the sentinel blocks written by _inline_theme_css.
+
+    Each ``<!-- css-snapshot:<filename>:start --> <style>…</style>
+    <!-- css-snapshot:<filename>:end -->`` block is replaced with
+    ``<link rel="stylesheet" href="./<filename>" />`` and the CSS content is
+    returned so the caller can write it back to disk.
+
+    Returns:
+        (restored_html, {filename: css_content, …})
+    """
+    extracted: dict[str, str] = {}
+
+    def _replace(match: re.Match) -> str:
+        filename = match.group(1)
+        css = match.group(2).strip()
+        extracted[filename] = css
+        return f'<link rel="stylesheet" href="./{filename}" />'
+
+    restored = _SENTINEL_RE.sub(_replace, html)
+    return restored, extracted
+
+
+@dataclass(frozen=True)
+class SlideFile:
+    index: int
+    suffix: str
+    path: Path
+
+
+def get_mnt_dir() -> Path:
+    return Path("/app/mnt") if Path("/.dockerenv").is_file() else Path(__file__).parents[2] / "mnt"
+
+
+def get_project_dir(project_name: str) -> Path:
+    return get_mnt_dir() / project_name / "presentations"
+
+
+def list_slide_files(project_dir: Path, file_prefix: str = "slide") -> list[SlideFile]:
+    pattern = re.compile(rf"^{re.escape(file_prefix)}_(\d+)(.*)\.html$", re.IGNORECASE)
+    slides: list[SlideFile] = []
+    for path in project_dir.glob("*.html"):
+        match = pattern.match(path.name)
+        if not match:
+            continue
+        index = int(match.group(1))
+        suffix = match.group(2) or ""
+        slides.append(SlideFile(index=index, suffix=suffix, path=path))
+    return sorted(slides, key=lambda s: s.index)
+
+
+def compute_pad_width(slides: list[SlideFile], min_width: int = 2, extra_count: int = 0) -> int:
+    max_index = max([s.index for s in slides], default=0) + max(0, extra_count)
+    return max(min_width, len(str(max_index or 1)))
+
+
+def build_slide_name(file_prefix: str, index: int, pad_width: int, suffix: str) -> str:
+    return f"{file_prefix}_{index:0{pad_width}d}{suffix}.html"
+
+
+def next_pptx_version(desired: Path) -> Path:
+    """Return *desired* if it doesn't exist, otherwise the next free _vN path.
+
+    Strips any existing ``_vN`` suffix before searching so that passing
+    ``deck_v2.pptx`` when that file already exists yields ``deck_v3.pptx``
+    rather than ``deck_v2_v2.pptx``.
+    """
+    if not desired.exists():
+        return desired
+    base = re.sub(r"_v\d+$", "", desired.stem)
+    n = 2
+    while True:
+        candidate = desired.parent / f"{base}_v{n}{desired.suffix}"
+        if not candidate.exists():
+            return candidate
+        n += 1
+
+
+def apply_renames(rename_map: dict[Path, Path]) -> None:
+    temp_map: dict[Path, Path] = {}
+    for src, dest in rename_map.items():
+        if src == dest:
+            continue
+        temp_name = f".__tmp__{uuid.uuid4().hex}{src.suffix}"
+        tmp_path = src.with_name(temp_name)
+        src.rename(tmp_path)
+        temp_map[tmp_path] = dest
+
+    for tmp, dest in temp_map.items():
+        if dest.exists():
+            dest.unlink()
+        tmp.rename(dest)

package/slides_agent/tools/slide_html_utils.py

@@ -0,0 +1,354 @@
+"""Shared HTML scaffold and validation helpers for slides."""
+
+import os
+import re
+import tempfile
+from pathlib import Path
+
+from playwright.sync_api import sync_playwright
+
+# Extensions we consider valid for slide images (PPTX-friendly)
+VALID_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tiff", ".tif", ".webp"}
+
+
+def ensure_full_html(html_content: str) -> tuple[str, bool]:
+    """Ensure the slide has a full HTML scaffold."""
+    html_lower = html_content.lower()
+    is_full_doc = "<html" in html_lower or "<!doctype" in html_lower
+    if is_full_doc:
+        return html_content, False
+
+    base_css = """
+    * { box-sizing: border-box; }
+    html, body {
+      width: 1280px;
+      height: 720px;
+      margin: 0;
+      padding: 0;
+      overflow: hidden;
+      background-color: #0f0f0f;
+    }
+    body {
+      position: relative;
+    }
+    .slide-wrapper {
+      width: 1280px;
+      height: 720px;
+      margin: 0;
+      padding: 0;
+      position: relative;
+      overflow: hidden;
+      display: flex;
+      flex-direction: column;
+      background-color: #151517;
+      color: #ffffff;
+    }
+    .bg-grid {
+      background-image: url("data:image/svg+xml,%3Csvg width='40' height='40' viewBox='0 0 40 40' xmlns='http://www.w3.org/2000/svg'%3E%3Cg fill='%23ffffff' fill-opacity='0.03' fill-rule='evenodd'%3E%3Cpath d='M0 40L40 0H20L0 20M40 40V20L20 40'/%3E%3C/g%3E%3C/svg%3E");
+    }
+    .glass-panel {
+      background: rgba(255, 255, 255, 0.03);
+      backdrop-filter: blur(10px);
+      border: 1px solid rgba(255, 255, 255, 0.08);
+      border-radius: 24px;
+    }
+    .title-font {
+      font-family: 'Space Grotesk', sans-serif;
+    }
+    .slide {
+      width: 100%;
+      height: 100%;
+      padding: 0;
+      position: relative;
+      z-index: 10;
+      display: flex;
+      flex-direction: column;
+    }
+    .content-safe-area {
+      width: 100%;
+      max-width: 1100px;
+      margin: 0 auto;
+      padding: 54px 0;
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+    }
+    .canvas {
+      width: 100%;
+      height: 100%;
+    }
+"""
+    full_html = f"""<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet" />
+    <link href="https://fonts.googleapis.com/css2?family=Merriweather:wght@300;400;700&family=Space+Grotesk:wght@500;700&family=Roboto+Mono:wght@400;500&display=swap" rel="stylesheet" />
+    <link rel="stylesheet" href="./_theme.css" />
+    <style>
+{base_css}
+    </style>
+  </head>
+  <body>
+    <div class="slide-wrapper bg-grid">
+      <div class="slide">
+        <div class="content-safe-area">
+{html_content}
+        </div>
+      </div>
+    </div>
+  </body>
+</html>"""
+    return full_html, True
+
+
+def _collect_local_image_refs(html_content: str) -> list[str]:
+    """Collect img src and url() in style that look like local paths (./ or no scheme)."""
+    refs = []
+    # <img src="..."> and <img src='...'>
+    for m in re.finditer(r'<img[^>]+src\s*=\s*["\']([^"\']+)["\']', html_content, re.IGNORECASE):
+        refs.append(m.group(1).strip())
+    # url(...) in style or style attribute
+    for m in re.finditer(r'url\s*\(\s*["\']?([^"\')\s]+)["\']?\s*\)', html_content, re.IGNORECASE):
+        refs.append(m.group(1).strip())
+    # Keep only local-looking refs (no http/https/data:)
+    local = []
+    for r in refs:
+        r_lower = r.lower()
+        if r_lower.startswith(("http://", "https://", "data:")):
+            continue
+        local.append(r)
+    return local
+
+
+def _validate_image_refs(project_dir: Path, html_content: str) -> list[str]:
+    """Check that every local image reference in HTML exists under project_dir and is a valid image."""
+    errors = []
+    project_dir = project_dir.resolve()
+    seen = set()
+    for ref in _collect_local_image_refs(html_content):
+        if not ref or ref in seen:
+            continue
+        seen.add(ref)
+        # Resolve relative to project_dir (ref may be ./assets/x or assets/x)
+        normalized = ref.lstrip("/").replace("\\", "/")
+        if normalized.startswith("./"):
+            normalized = normalized[2:]
+        full_path = (project_dir / normalized).resolve()
+        try:
+            full_path.relative_to(project_dir)
+        except (ValueError, TypeError):
+            errors.append(f"Image path escapes project: {ref}")
+            continue
+        if not full_path.exists():
+            errors.append(f"Image file not found: {ref} (resolved to {full_path})")
+            continue
+        if full_path.suffix.lower() not in VALID_IMAGE_EXTENSIONS:
+            errors.append(
+                f"Image '{ref}' has unsupported extension '{full_path.suffix}'. "
+                f"Use one of: {', '.join(sorted(VALID_IMAGE_EXTENSIONS))}"
+            )
+            continue
+        # Optional: verify file is readable as image (avoid corrupt or HTML-masquerading files)
+        try:
+            with open(full_path, "rb") as f:
+                header = f.read(32)
+            if header.startswith(b"<") or header.startswith(b"<!") or b"<html" in header[:50].lower():
+                errors.append(f"Image '{ref}' is not a valid image file (looks like HTML). Re-download with DownloadImage.")
+        except Exception:
+            pass
+    return errors
+
+
+def validate_html(html_content: str, project_dir: Path, used_scaffold: bool) -> dict:
+    """Validate HTML layout using Playwright."""
+    errors = []
+
+    # Validate local image references (photos) exist and are valid
+    errors.extend(_validate_image_refs(project_dir, html_content))
+
+    if re.search(r"[\U0001F300-\U0001FAFF]", html_content):
+        errors.append(
+            "Emoji/Unicode symbols detected. Use image icons (PNG) instead of emoji."
+        )
+
+    if re.search(r"<span[^>]*class=[\"'][^\"']*\\bdot\\b[^\"']*[\"'][^>]*>\\s*</span>", html_content, flags=re.IGNORECASE):
+        errors.append(
+            "Detected empty .dot spans used as colored bullets. Replace with inline SVG circles or image assets to ensure PPTX rendering."
+        )
+
+    # Detect inline badges/pills inside flowing text (<p> or <li> containing sibling text nodes AND styled spans)
+    # Pattern: <p ...> or <li ...> that contains both plain text AND a <span> or <code> with inline style containing background
+    _inline_badge_in_text = re.compile(
+        # Requires at least one text character before the badge ([^<]+) to avoid flagging badge-only paragraphs.
+        r'<(?:p|li)[^>]*>[^<]+<(?:span|code|a)[^>]+style=["\'][^"\']*background[^"\']*["\'][^>]*>[^<]+</(?:span|code|a)>',
+        re.IGNORECASE | re.DOTALL,
+    )
+    if _inline_badge_in_text.search(html_content):
+        errors.append(
+            "Styled badge/pill detected inline inside <p> or <li> text. "
+            "Inline elements with background-color split the surrounding sentence into separate PPTX text boxes. "
+            "Move the badge to its own line or container, or use plain monospace text (no background) for inline code references."
+        )
+
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        suffix=".html",
+        delete=False,
+        encoding="utf-8",
+        dir=project_dir,
+    ) as f:
+        f.write(html_content)
+        temp_path = f.name
+
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch()
+            page = browser.new_page(viewport={"width": 1280, "height": 720})
+            page.goto(f"file://{temp_path}", wait_until="load")
+
+            if not used_scaffold and "_theme.css" not in html_content:
+                errors.append("Missing theme link: include <link rel=\"stylesheet\" href=\"./_theme.css\" />")
+
+            body_dims = page.evaluate("""() => {
+                const body = document.body;
+                const slide = document.querySelector('.content-safe-area') || document.querySelector('.slide') || document.querySelector('.slide-wrapper') || body;
+                const style = window.getComputedStyle(body);
+                return {
+                    width: parseFloat(style.width),
+                    height: parseFloat(style.height),
+                    scrollWidth: Math.max(body.scrollWidth, slide.scrollWidth),
+                    scrollHeight: Math.max(body.scrollHeight, slide.scrollHeight)
+                };
+            }""")
+
+            expected_width = 1280
+            expected_height = 720
+
+            if abs(body_dims["width"] - expected_width) > 2:
+                errors.append(f"Body width must be 1280px, got {body_dims['width']:.0f}px")
+            if abs(body_dims["height"] - expected_height) > 2:
+                errors.append(f"Body height must be 720px, got {body_dims['height']:.0f}px")
+
+            width_overflow = max(0, body_dims["scrollWidth"] - body_dims["width"] - 1)
+            height_overflow = max(0, body_dims["scrollHeight"] - body_dims["height"] - 1)
+
+            if width_overflow > 0:
+                errors.append(f"Content overflows horizontally by {width_overflow:.0f}px")
+                errors.append("  💡 Hint: Reduce content width or increase right margin")
+
+            if height_overflow > 0:
+                errors.append(f"Content overflows vertically by {height_overflow:.0f}px")
+                errors.append("  💡 Hint: Reduce content height, use smaller font, or move elements up from the bottom edge.")
+
+            # Check for descender clipping (elements too close to the bottom edge)
+            descender_issues = page.evaluate("""() => {
+                const body = document.body;
+                const bodyRect = body.getBoundingClientRect();
+                const textElements = Array.from(body.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, span'));
+                const issues = [];
+                for (const el of textElements) {
+                    const r = el.getBoundingClientRect();
+                    const distToBottom = bodyRect.bottom - r.bottom;
+                    // If text is within 3px of the bottom, it's likely clipping descenders
+                    if (distToBottom >= -1 && distToBottom < 3 && el.textContent.trim()) {
+                        issues.push({
+                            text: el.textContent.trim().substring(0, 30),
+                            dist: distToBottom
+                        });
+                    }
+                }
+                return issues;
+            }""")
+
+            if descender_issues:
+                for issue in descender_issues[:2]:
+                    errors.append(f"Text \"{issue['text']}...\" is too close to the bottom edge ({issue['dist']:.1f}px). Descenders (like 'g', 'y', 'p') may be clipped.")
+                errors.append("  💡 Hint: Move the element up by at least 5-10px for safety.")
+
+            if width_overflow > 0 or height_overflow > 0:
+                offenders = page.evaluate("""() => {
+                    const body = document.body;
+                    const bodyRect = body.getBoundingClientRect();
+                    const nodes = Array.from(body.querySelectorAll("*"));
+                    const over = [];
+                    for (const el of nodes) {
+                        const r = el.getBoundingClientRect();
+                        const overflowRight = Math.max(0, r.right - bodyRect.right);
+                        const overflowBottom = Math.max(0, r.bottom - bodyRect.bottom);
+                        const overflowLeft = Math.max(0, bodyRect.left - r.left);
+                        const overflowTop = Math.max(0, bodyRect.top - r.top);
+                        if (overflowRight > 0 || overflowBottom > 0 || overflowLeft > 0 || overflowTop > 0) {
+                            const area = Math.max(0, r.width) * Math.max(0, r.height);
+                            over.push({
+                                tag: el.tagName.toLowerCase(),
+                                id: el.id || "",
+                                className: el.className || "",
+                                overflowRight,
+                                overflowBottom,
+                                overflowLeft,
+                                overflowTop,
+                                area,
+                            });
+                        }
+                    }
+                    over.sort((a, b) => b.area - a.area);
+                    return over.slice(0, 3);
+                }""")
+                if offenders:
+                    errors.append("Top overflow offenders:")
+                    for off in offenders:
+                        ident = off["tag"]
+                        if off["id"]:
+                            ident += f"#{off['id']}"
+                        if off["className"]:
+                            ident += f".{str(off['className']).strip().replace(' ', '.')}"
+                        errors.append(
+                            f"  - {ident} (R:{off['overflowRight']:.0f}px, B:{off['overflowBottom']:.0f}px, "
+                            f"L:{off['overflowLeft']:.0f}px, T:{off['overflowTop']:.0f}px)"
+                        )
+
+            unwrapped = page.evaluate("""() => {
+                const divs = document.querySelectorAll('div');
+                const issues = [];
+                divs.forEach(div => {
+                    for (const node of div.childNodes) {
+                        if (node.nodeType === Node.TEXT_NODE && node.textContent.trim()) {
+                            const text = node.textContent.trim().substring(0, 50);
+                            issues.push(text + (node.textContent.trim().length > 50 ? '...' : ''));
+                        }
+                    }
+                });
+                return issues;
+            }""")
+
+            if unwrapped:
+                errors.append("Found unwrapped text in DIV elements:")
+                for text in unwrapped[:3]:
+                    errors.append(f"  - \"{text}\"")
+                errors.append("  💡 Hint: Wrap all text in <p>, <h1>-<h6>, <ul>, or <ol> tags")
+
+            browser.close()
+    except Exception as e:
+        errors.append(f"Validation error: {e}")
+    finally:
+        os.unlink(temp_path)
+
+    if errors:
+        return {"valid": False, "error": "\n".join(errors)}
+    return {"valid": True, "error": ""}
+
+
+MAIN_TEXT_MAX_CHARS = 100
+
+
+def list_slide_filenames(project_dir: Path) -> list[str]:
+    if not project_dir.exists():
+        return []
+    return sorted(p.name for p in project_dir.iterdir() if p.suffix.lower() == ".html")
+
+
+def _strip_html_to_text(html: str, max_chars: int = MAIN_TEXT_MAX_CHARS) -> str:
+    text = re.sub(r"<[^>]+>", " ", html)
+    text = re.sub(r"\s+", " ", text).strip()
+    return (text[:max_chars] + "…") if len(text) > max_chars else text

package/slides_agent/tools/template_registry.py

@@ -0,0 +1,55 @@
+"""Per-project template registry utilities for slides_agent_v2."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+TEMPLATE_DIRNAME = "_templates"
+TEMPLATE_INDEX_FILENAME = "index.json"
+
+
+def _templates_dir(project_dir: Path) -> Path:
+    return project_dir / TEMPLATE_DIRNAME
+
+
+def _template_index_path(project_dir: Path) -> Path:
+    return _templates_dir(project_dir) / TEMPLATE_INDEX_FILENAME
+
+
+def ensure_template_dir(project_dir: Path) -> Path:
+    path = _templates_dir(project_dir)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def load_template_index(project_dir: Path) -> dict[str, dict[str, Any]]:
+    path = _template_index_path(project_dir)
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    clean: dict[str, dict[str, Any]] = {}
+    for key, value in data.items():
+        if isinstance(key, str) and isinstance(value, dict):
+            clean[key] = value
+    return clean
+
+
+def save_template_index(project_dir: Path, index_data: dict[str, dict[str, Any]]) -> None:
+    ensure_template_dir(project_dir)
+    _template_index_path(project_dir).write_text(
+        json.dumps(index_data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def template_path(project_dir: Path, template_key: str) -> Path:
+    ensure_template_dir(project_dir)
+    return _templates_dir(project_dir) / f"{template_key}.html"
+