@ztffn/presentation-generator-plugin 1.1.3 → 1.1.5

package/agents/presentation-design.md

@@ -4,6 +4,7 @@ description: Translates approved slide outlines into complete graph JSON with no
 tools:
   - Read
   - Write
+  - Bash
 skills:
   - presentation-generator/system/node-schema
   - presentation-generator/system/edge-conventions
@@ -28,13 +29,40 @@ You are a design and JSON generation specialist. Your job is to translate an app
 5. Run the edge validation checklist before finalizing
 6. Write the complete JSON to `_temp/presentation-draft.json`
 
+## Field Mapping
+
+When translating from the outline to `data` fields, use **exactly** these SlideNodeData field names — no others:
+
+| Outline field | SlideNodeData field | Notes |
+|---|---|---|
+| `### Slide Title` | `label` | Slide heading shown in graph editor and at top of slide |
+| `**Key message:**` + `**Content:**` | `content` | Combine into markdown: key message as first line or `##` heading, then bullets/body. Use `\n\n` between paragraphs. |
+| `**Speaker notes:**` | `notes` | Verbatim from outline. Never put this in `content`. |
+
+**DO NOT use these field names** — they are not part of the schema and will be silently ignored by the renderer:
+`headline`, `subheadline`, `bullets`, `speakerNote`, `speakerNotes`, `visualHint`, `theme`, `title`, `body`, `text`, `background`, `showLogo`, `keyMessage`, `claim`, `hook`, `description`, `summary`
+
+## Edge Handle Rules
+
+**WRONG** — these handle values will break navigation:
+```json
+{ "sourceHandle": "right", "targetHandle": "left" }
+```
+
+**CORRECT** — source handles prefix `s-`, target handles prefix `t-`:
+```json
+{ "sourceHandle": "s-right", "targetHandle": "t-left" }
+```
+
+All 8 valid handle IDs: `s-right`, `s-left`, `s-top`, `s-bottom`, `t-right`, `t-left`, `t-top`, `t-bottom`
+
 ## Rules
 
 - **Translation only**: Do not alter content, order, or structure from the outline. Your role is visual treatment and JSON compilation.
 - Every node must have `type: "huma"`, `style: { width: 180, height: 70 }`, and `measured: { width: 180, height: 70 }`
 - Every node ID must be a kebab-case slug
 - Every forward edge must have a paired return edge
-- All handle IDs must be from the valid set of 8
+- All handle IDs must be from the valid set of 8 listed above
 - For background images, use Unsplash URLs with `?w=1920&q=80`
 - For video, use placeholder strings: `"PLACEHOLDER: [description]"`
 - List all slides with video placeholders at the end of output
@@ -55,7 +83,25 @@ You are a design and JSON generation specialist. Your job is to translate an app
 }
 ```
 
-After writing, output a summary listing:
+4. Run the validator script using Bash. This is a Python script — you must execute it, not read it. Reading the JSON file is not validation.
+
+The script is bundled with the plugin. Find it and run it:
+
+```bash
+VALIDATE=$(find -L .claude ~/.claude -path "*/presentation-generator/scripts/validate_draft.py" 2>/dev/null | head -1)
+python3 "$VALIDATE" presentations/{slug}/{slug}.json
+```
+
+The script prints either `OK  Presentation JSON is valid` (exit 0) or a list of `ERROR` lines (exit 1).
+
+If there are any `ERROR` lines:
+- Fix every error directly in the JSON file
+- Run the script again against the same file
+- Repeat until the script prints `OK  Presentation JSON is valid`
+
+**Your completion message must include the exact terminal output of the script.** A Read tool call on the JSON file is not validation and does not count. If the script output is not shown, the task is not complete.
+
+After a clean validation pass, output a summary listing:
 - Output path (e.g. `presentations/calora-investor-pitch/calora-investor-pitch.json`)
 - Total node count
 - Total edge count

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ztffn/presentation-generator-plugin",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Claude Code plugin for generating graph-based presentations",
   "bin": {
     "presentation-generator-plugin": "bin/index.js"

package/scripts/validate_draft.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+validate_draft.py — Validates a presentation draft JSON before import.
+Checks node schema correctness, edge handle IDs, bidirectional pairs, and duplicates.
+Intended to be run by the design agent after writing the draft, before reporting complete.
+Usage: python3 validate_draft.py <path-to-draft.json>
+Exit:  0 if valid, 1 if errors found.
+"""
+
+import sys
+import json
+from pathlib import Path
+
+# Derived from SlideNodeData interface in src/types/presentation.ts.
+# Any field not in this set is unknown to the renderer and will be silently ignored.
+ALLOWED_DATA_FIELDS = {
+    "label", "topic", "content", "notes", "type", "centered", "layout",
+    "lightText", "brandFont", "showBranding", "brandingText",
+    "backgroundImage", "backgroundImageFit", "backgroundImageOverlay",
+    "backgroundVideo", "backgroundVideoFit", "backgroundVideoLoop",
+    "inlineVideoControls", "inlineVideoAutoplay", "inlineVideoLoop",
+    "scene", "chart", "charts",
+    "sceneGroup", "focus",
+}
+
+VALID_SOURCE_HANDLES = {"s-right", "s-left", "s-top", "s-bottom"}
+VALID_TARGET_HANDLES = {"t-right", "t-left", "t-top", "t-bottom"}
+BARE_HANDLES = {"right", "left", "top", "bottom"}
+
+
+def validate(path):
+    errors = []
+
+    try:
+        data = json.loads(Path(path).read_text())
+    except FileNotFoundError:
+        print(f"ERROR  File not found: {path}")
+        return False
+    except json.JSONDecodeError as e:
+        print(f"ERROR  Invalid JSON: {e}")
+        return False
+
+    # --- meta ---
+    meta = data.get("meta")
+    if not isinstance(meta, dict):
+        errors.append("meta: missing or not an object")
+    elif not str(meta.get("name", "")).strip():
+        errors.append("meta.name: missing or empty — must be the deck title")
+
+    # --- nodes ---
+    nodes = data.get("nodes")
+    node_ids = set()
+
+    if not isinstance(nodes, list) or len(nodes) == 0:
+        errors.append("nodes: missing or empty array")
+    else:
+        for i, node in enumerate(nodes):
+            nid = node.get("id", f"[index {i}]")
+            p = f"node '{nid}'"
+
+            if nid in node_ids:
+                errors.append(f"{p}: duplicate node ID")
+            node_ids.add(nid)
+
+            if node.get("type") != "huma":
+                errors.append(f"{p}: type must be 'huma', got {node.get('type')!r}")
+
+            style = node.get("style") or {}
+            measured = node.get("measured") or {}
+            if style.get("width") != 180 or style.get("height") != 70:
+                errors.append(f"{p}: style must be {{width: 180, height: 70}}, got {style}")
+            if measured.get("width") != 180 or measured.get("height") != 70:
+                errors.append(f"{p}: measured must be {{width: 180, height: 70}}, got {measured}")
+
+            node_data = node.get("data")
+            if not isinstance(node_data, dict):
+                errors.append(f"{p}: data must be an object")
+                continue
+
+            if not str(node_data.get("label", "")).strip():
+                errors.append(f"{p}: data.label is missing or empty (this is the slide title)")
+
+            unknown = set(node_data.keys()) - ALLOWED_DATA_FIELDS
+            if unknown:
+                errors.append(
+                    f"{p}: unknown field(s) in data: {', '.join(sorted(unknown))} — "
+                    f"only SlideNodeData fields are valid (label, content, notes, topic, type, layout, ...)"
+                )
+
+    # --- edges ---
+    edges = data.get("edges")
+    edge_ids = set()
+    valid_edges = []  # (source, target, sourceHandle, targetHandle, id)
+
+    if not isinstance(edges, list):
+        errors.append("edges: missing or not an array")
+    else:
+        for i, edge in enumerate(edges):
+            eid = edge.get("id", f"[index {i}]")
+            p = f"edge '{eid}'"
+
+            if eid in edge_ids:
+                errors.append(f"{p}: duplicate edge ID")
+            edge_ids.add(eid)
+
+            src = edge.get("source")
+            tgt = edge.get("target")
+            sh = edge.get("sourceHandle")
+            th = edge.get("targetHandle")
+
+            if node_ids and src not in node_ids:
+                errors.append(f"{p}: source '{src}' does not reference a known node ID")
+            if node_ids and tgt not in node_ids:
+                errors.append(f"{p}: target '{tgt}' does not reference a known node ID")
+
+            sh_ok = True
+            if sh in BARE_HANDLES:
+                errors.append(f"{p}: sourceHandle '{sh}' — use 's-{sh}' (source handles require 's-' prefix)")
+                sh_ok = False
+            elif sh not in VALID_SOURCE_HANDLES:
+                errors.append(f"{p}: sourceHandle '{sh}' invalid — must be one of {sorted(VALID_SOURCE_HANDLES)}")
+                sh_ok = False
+
+            th_ok = True
+            if th in BARE_HANDLES:
+                errors.append(f"{p}: targetHandle '{th}' — use 't-{th}' (target handles require 't-' prefix)")
+                th_ok = False
+            elif th not in VALID_TARGET_HANDLES:
+                errors.append(f"{p}: targetHandle '{th}' invalid — must be one of {sorted(VALID_TARGET_HANDLES)}")
+                th_ok = False
+
+            if sh_ok and th_ok:
+                valid_edges.append((src, tgt, sh, th, eid))
+
+        # --- bidirectional pair check ---
+        edge_set = {(src, tgt, sh, th) for src, tgt, sh, th, _ in valid_edges}
+        for src, tgt, sh, th, eid in valid_edges:
+            ret_sh = "s-" + th[2:]  # t-left  -> s-left
+            ret_th = "t-" + sh[2:]  # s-right -> t-right
+            if (tgt, src, ret_sh, ret_th) not in edge_set:
+                errors.append(
+                    f"edge '{eid}' ({src} -[{sh}/{th}]-> {tgt}): "
+                    f"missing return edge ({tgt} -[{ret_sh}/{ret_th}]-> {src})"
+                )
+
+    if not errors:
+        print("OK  Presentation JSON is valid")
+        return True
+
+    for e in errors:
+        print(f"ERROR  {e}")
+    print()
+    print(f"FAILED  {len(errors)} error(s) — fix all errors before importing")
+    return False
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python3 validate_draft.py <path-to-draft.json>")
+        sys.exit(1)
+    ok = validate(sys.argv[1])
+    sys.exit(0 if ok else 1)