@ztffn/presentation-generator-plugin 1.2.0 → 1.3.0

package/skills/graph-json-spec/SKILL.md

@@ -0,0 +1,812 @@
+---
+name: graph-json-spec
+description: >
+  Complete specification for generating valid graph-based presentation JSON —
+  node schema, edge wiring, positioning grid, layout decisions, and slide recipes.
+  Used by the presentation-design agent.
+user-invocable: false
+---
+
+# Graph JSON Specification
+
+Complete reference for producing valid presentation graph JSON.
+Derived from the renderer at `src/types/presentation.ts` and validated demo JSON.
+
+## Quick Reference
+
+The most common errors and their fixes — read this first.
+
+| Rule | Correct | Wrong |
+|---|---|---|
+| Slide title field | `data.label` | ~~title~~, ~~headline~~, ~~heading~~ |
+| Body content field | `data.content` | ~~body~~, ~~text~~, ~~bullets~~ |
+| Speaker notes field | `data.notes` | ~~speakerNotes~~, ~~speakerNote~~ |
+| Node type | `"huma"` | ~~"slide"~~, ~~"default"~~ |
+| Slide type values | `"content"` \| `"r3f"` \| `"chart"` \| `"custom"` | ~~"titleAndBullets"~~, ~~"image"~~ |
+| Layout values | `"single"` \| `"two-column"` | ~~"top"~~, ~~"split"~~, ~~"left-right"~~ |
+| Source handles | `s-right`, `s-left`, `s-top`, `s-bottom` | ~~right~~, ~~left~~ (bare) |
+| Target handles | `t-right`, `t-left`, `t-top`, `t-bottom` | ~~right~~, ~~left~~ (bare) |
+| Horizontal spacing | 240px | ~~250px~~, ~~200px~~ |
+| Vertical spacing | 150px | ~~100px~~, ~~200px~~ |
+| Node size | `{ width: 180, height: 70 }` in both `style` and `measured` | any other size |
+| Edge pairs | Every forward edge needs a return edge | one-way edges |
+
+**Banned data field names** — these are silently ignored by the renderer:
+`headline`, `subheadline`, `bullets`, `speakerNote`, `speakerNotes`, `visualHint`, `theme`, `title`, `body`, `text`, `background`, `showLogo`, `keyMessage`, `claim`, `hook`, `description`, `summary`
+
+---
+
+## Node Structure
+
+Every node in the graph has this wrapper:
+
+```json
+{
+  "id": "unique-slug",
+  "type": "huma",
+  "position": { "x": 0, "y": 0 },
+  "data": { /* SlideNodeData fields */ },
+  "style": { "width": 180, "height": 70 },
+  "measured": { "width": 180, "height": 70 }
+}
+```
+
+- `id`: Kebab-case slug (e.g. `"cover"`, `"problem-detail"`, `"feat-3d"`)
+- `type`: Always `"huma"` — the custom node type with directional handles
+- `position`: `{ x, y }` in graph canvas coordinates (see Positioning Grid below)
+- `style.width`: Always `180`. `style.height`: Always `70`.
+- `measured`: Must mirror `style` — `{ width: 180, height: 70 }`
+- Optional: `style.backgroundColor` — hex string for node background in the graph editor (also applied as slide background)
+
+### SlideNodeData Fields
+
+#### Content Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string?` | — | Slide title displayed in graph editor and as slide heading |
+| `topic` | `string?` | — | Section badge on the slide (e.g. `"01 / Problem"`, `"Solution"`) |
+| `content` | `string?` | — | Markdown body. Supports headings, bullets, bold, code, tables, `[chart:name]` embeds, `![](url)` images/videos, `[text](#nodeId)` navigation links |
+| `notes` | `string?` | — | Speaker notes, shown only in the presenter panel |
+
+#### Slide Type
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `type` | `"content" \| "r3f" \| "chart" \| "custom"` | `"content"` | Slide renderer. `"content"` for standard text, `"r3f"` for 3D scene, `"chart"` for full-viewport chart |
+
+#### Layout & Display
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `centered` | `boolean?` | `true` | Center content vertically and horizontally |
+| `layout` | `"single" \| "two-column"` | `"single"` | Content layout. `"two-column"` splits on `---` delimiter in content |
+| `lightText` | `boolean?` | `false` | Force white text for dark backgrounds |
+| `brandFont` | `boolean?` | `false` | Use HumaDisplay display font for the title |
+| `showBranding` | `boolean?` | `true` | Show branding overlay |
+| `brandingText` | `string?` | — | Bottom-left branding label (e.g. `"huma.energy"`) |
+
+#### Background Media
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `backgroundImage` | `string?` | — | URL to background image |
+| `backgroundImageFit` | `"cover" \| "contain"` | `"cover"` | How image fills the slide |
+| `backgroundImageOverlay` | `boolean?` | `false` | Dark scrim over background image for text readability |
+| `backgroundVideo` | `string?` | — | URL to background video |
+| `backgroundVideoFit` | `"cover" \| "contain"` | `"cover"` | How video fills the slide |
+| `backgroundVideoLoop` | `boolean?` | `true` | Loop background video |
+
+#### Inline Video
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `inlineVideoControls` | `boolean?` | `true` | Show controls on inline videos in `content` |
+| `inlineVideoAutoplay` | `boolean?` | `true` | Autoplay inline videos |
+| `inlineVideoLoop` | `boolean?` | `true` | Loop inline videos |
+
+#### R3F Scene (when `type: "r3f"`)
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `scene.component` | `string` | — | Registry key (e.g. `"rotating-cube"`, `"particle-field"`) |
+| `scene.props` | `Record<string, unknown>?` | — | Props passed to the scene component |
+| `scene.controls` | `boolean?` | — | Enable OrbitControls for user interaction |
+| `scene.background` | `string?` | — | Scene background hex color |
+
+#### Charts
+
+**Full-viewport chart** (when `type: "chart"`):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `chart.chartType` | `"bar" \| "line" \| "area" \| "pie" \| "radar"` | — | Chart renderer |
+| `chart.data` | `Array<Record<string, unknown>>` | — | Data array |
+| `chart.config.xKey` | `string?` | — | X-axis data key |
+| `chart.config.yKeys` | `string[]?` | — | Y-axis data keys |
+| `chart.config.colors` | `string[]?` | — | Series colors |
+| `chart.config.showGrid` | `boolean?` | — | Show grid lines |
+| `chart.config.showLegend` | `boolean?` | — | Show legend |
+
+**Inline charts** (referenced via `[chart:name]` in content):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `charts` | `Record<string, ChartConfig>` | — | Named chart configurations. Key is referenced in content as `[chart:keyname]` |
+
+Each `ChartConfig` has the same shape as `chart` above (`chartType`, `data`, `config`).
+
+#### Other
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `sceneGroup` | — | — | Scene group reference |
+| `focus` | — | — | Focus state |
+
+### Content Markdown Features
+
+The `content` field supports:
+
+- `## Heading` — headings (ATX style only, no setext)
+- `- bullet` or `* bullet` — unordered lists
+- `1. item` — ordered lists
+- `` ```language ``` `` — syntax-highlighted code blocks
+- `> blockquote` — styled blockquotes
+- `**bold**` and `*italic*` — inline formatting
+- `| col | col |` — GFM tables
+- `![alt](url)` — images; `.mp4/.webm/.mov` URLs render as inline video
+- `[text](url)` — external links (open in new tab)
+- `[text](#nodeId)` — navigation links to other slides
+- `[chart:name]` — inline chart embed (must be on its own line)
+- `---` — column delimiter when `layout: "two-column"`
+- Single newline = visible line break (not collapsed)
+- Multiple blank lines = visible vertical spacing
+
+---
+
+## Edge Wiring
+
+Edges define valid navigation paths — without correct edges, arrow keys won't work.
+
+### Handle IDs
+
+Eight handle IDs exist, four source and four target:
+
+| Handle ID | Type | Position | Navigation |
+|---|---|---|---|
+| `s-right` | source | Right side | Pressing **right arrow** follows this edge |
+| `s-left` | source | Left side | Pressing **left arrow** follows this edge |
+| `s-bottom` | source | Bottom | Pressing **down arrow** follows this edge |
+| `s-top` | source | Top | Pressing **up arrow** follows this edge |
+| `t-right` | target | Right side | Arrived via **left arrow** from source |
+| `t-left` | target | Left side | Arrived via **right arrow** from source |
+| `t-bottom` | target | Bottom | Arrived via **up arrow** from source |
+| `t-top` | target | Top | Arrived via **down arrow** from source |
+
+### Bidirectional Pair Rule
+
+**Every navigation edge must have a return edge** with swapped source/target and swapped handles.
+
+If the user can press right to go from A to B, they must be able to press left to go from B back to A.
+
+### Standard Edge Pairs
+
+**Horizontal Forward/Back (Spine Navigation):**
+
+```json
+{ "id": "e-a-b", "source": "a", "target": "b", "sourceHandle": "s-right", "targetHandle": "t-left" }
+{ "id": "e-b-a", "source": "b", "target": "a", "sourceHandle": "s-left", "targetHandle": "t-right" }
+```
+
+**Drill-Down / Return-to-Parent:**
+
+```json
+{ "id": "e-parent-child", "source": "parent", "target": "child", "sourceHandle": "s-bottom", "targetHandle": "t-top" }
+{ "id": "e-child-parent", "source": "child", "target": "parent", "sourceHandle": "s-top", "targetHandle": "t-bottom" }
+```
+
+**Horizontal Within a Drill-Down Branch (Siblings):**
+
+```json
+{ "id": "e-child1-child2", "source": "child1", "target": "child2", "sourceHandle": "s-right", "targetHandle": "t-left" }
+{ "id": "e-child2-child1", "source": "child2", "target": "child1", "sourceHandle": "s-left", "targetHandle": "t-right" }
+```
+
+### Edge ID Convention
+
+Pattern: `e-{source}-{target}` using the node IDs or abbreviated forms.
+
+Examples: `e-cover-problem`, `e-problem-cover`, `e-problem-detail`, `e-detail-problem`
+
+### Edge Object Structure
+
+```json
+{
+  "id": "e-cover-problem",
+  "source": "cover",
+  "target": "problem",
+  "sourceHandle": "s-right",
+  "targetHandle": "t-left"
+}
+```
+
+All four fields (`source`, `target`, `sourceHandle`, `targetHandle`) are required. Always set handles explicitly.
+
+### Validation Checklist
+
+1. Every node has at least one outgoing edge — no dead ends
+2. Every forward edge has a paired return edge — source/target swapped, handles swapped
+3. All handle IDs are from the valid set — only the 8 IDs listed above
+4. Source handles start with `s-` and target handles start with `t-`
+5. The first spine node has no incoming `s-right` edge — it's the leftmost entry point
+6. The last spine node has no outgoing `s-right` edge (or loops back to cover)
+7. Drill-down children always have `s-top`/`t-bottom` return edge to parent
+8. No duplicate edge IDs
+
+---
+
+## Positioning Grid
+
+### Grid Constants
+
+| Parameter | Value |
+|---|---|
+| Horizontal spacing | 240px |
+| Vertical spacing | 150px |
+| Node width | 180px (in `style` and `measured`) |
+| Node height | 70px (in `style` and `measured`) |
+
+### Spine Row
+
+All spine nodes sit at `y: 0`, starting at `x: 0`, incrementing by 240 per node.
+
+```
+x:    0      240     480     720     960    1200
+y: 0  [Cover] [Problem] [Solution] [Value] [Features] [CTA]
+```
+
+### Drill-Down Rows
+
+Drill-down children are placed directly below their parent:
+
+- First level: `y: 150`
+- Second level: `y: 300`
+
+The first child inherits the parent's `x` position. Additional siblings at the same depth increment `x` by 240.
+
+```
+x:   720     960
+y:0  [Value]
+      |
+y:150 [Case A]  [Case B]
+```
+
+- First child: same `x` as parent (720)
+- Second child: parent `x` + 240 (960)
+- Third child: parent `x` + 480 (1200)
+
+### Position Quick Reference
+
+| Node | x | y | Role |
+|---|---|---|---|
+| cover | 0 | 0 | Spine 1 |
+| problem | 240 | 0 | Spine 2 |
+| problem-detail | 240 | 150 | Drill-down under problem |
+| solution | 480 | 0 | Spine 3 |
+| solution-how | 480 | 150 | Drill-down under solution |
+| value | 720 | 0 | Spine 4 |
+| value-case | 720 | 150 | Drill-down under value |
+| cta | 960 | 0 | Spine 5 |
+
+### Rules
+
+1. Position reflects visual layout in the editor — it has no effect on navigation
+2. Navigation is determined solely by edges and their handle assignments
+3. Spine nodes must be at `y: 0` for visual clarity
+4. Drill-downs must be below their parent
+5. No two nodes should overlap (maintain at least 240px horizontal, 150px vertical separation)
+
+---
+
+## Design Decisions
+
+### Slide Type Selection
+
+| Content Signal | `type` | Key Fields |
+|---|---|---|
+| Standard text, bullets, headings | `"content"` (default) | `content`, `layout` |
+| Full-viewport data visualization | `"chart"` | `chart` (ChartConfig) |
+| Interactive 3D scene | `"r3f"` | `scene` (R3FSceneConfig) |
+
+Most slides are `"content"`. Use `"chart"` or `"r3f"` only when the content is primarily a visualization.
+
+### Layout Decisions
+
+**When to use `two-column`** — set `layout: "two-column"` and split content on `---`:
+
+- Comparison: before/after, old/new, us/them
+- Pros/cons: advantages on left, considerations on right
+- Text + chart: explanation on left, `[chart:name]` on right
+- Text + media: bullets on left, `![](image)` on right
+- Dual evidence: two independent supporting points side by side
+
+Do not force two-column when content is naturally sequential.
+
+**When to center** — set `centered: true` for:
+
+- Cover slides: Title + subtitle, branded
+- Call-to-action slides: Single message, end of presentation
+- Single-message impact slides: One powerful statement or quote
+- Transition slides: Brief pause between major sections
+
+Set `centered: false` for content-heavy slides, data slides, comparison slides.
+
+**When to use brand font** — set `brandFont: true` for:
+
+- Cover slide (first slide)
+- Closing/CTA slide (last slide)
+- High-impact single-message slides
+
+Do not use on content-heavy or data slides — brand fonts are display fonts, not body fonts.
+
+**When to show branding** — set `showBranding: true` and `brandingText` for:
+
+- Cover slide, closing slide, slides likely to be screenshotted
+
+Set `showBranding: false` for immersive slides (R3F, full-bleed video) where the overlay is distracting.
+
+### Background Treatment
+
+**Background image** — use when the outline indicates mood, atmosphere, visual evidence, or impact:
+
+- Set `backgroundImageOverlay: true` and `lightText: true` when text appears over the image
+- Image URLs: use Unsplash with query params `?w=1920&q=80`
+
+**Background video** — use for cinematic section openers or demo context:
+
+- Set `backgroundVideo` to a placeholder: `"PLACEHOLDER: [description of needed video]"`
+- Set `backgroundVideoFit: "cover"` and `backgroundVideoLoop: true`
+- Add to delivery summary for manual upload
+
+**Inline video** — for videos embedded via `![alt](url)` in content:
+
+- Set URL to placeholder, configure `inlineVideoControls`, `inlineVideoAutoplay`, `inlineVideoLoop`
+- Add to delivery summary
+
+**Text contrast** — set `lightText: true` whenever background is dark:
+
+- Dark `style.backgroundColor`
+- `backgroundImage` with `backgroundImageOverlay: true`
+- `backgroundVideo` slides
+- `type: "r3f"` with dark scene background
+
+### Chart Decisions
+
+**Full-viewport chart** (`type: "chart"`) — when the data IS the slide:
+
+```json
+{
+  "type": "chart",
+  "chart": {
+    "chartType": "bar",
+    "data": [...],
+    "config": { "xKey": "quarter", "yKeys": ["revenue", "cost"], "showGrid": true, "showLegend": true }
+  },
+  "content": "Optional caption below the chart"
+}
+```
+
+**Inline chart** (`[chart:name]` in content) — when data supports a text argument:
+
+```json
+{
+  "content": "## Why this approach wins\n\n[chart:comparison]\n\nClosing statement.",
+  "charts": {
+    "comparison": {
+      "chartType": "radar",
+      "data": [...],
+      "config": { "xKey": "axis", "yKeys": ["ours", "theirs"], "showLegend": true }
+    }
+  }
+}
+```
+
+**Chart title rule** — `label` states the insight, not the data category:
+
+| Weak | Strong |
+|---|---|
+| "Revenue Data" | "Revenue grew 40% QoQ after the pricing change" |
+| "Response Time" | "Response time dropped 60% after caching rollout" |
+
+**Chart type selection:**
+
+| Data Pattern | Chart Type |
+|---|---|
+| Trend over time | `"line"` or `"area"` |
+| Category comparison | `"bar"` |
+| Multi-axis comparison | `"radar"` |
+| Part-of-whole | `"pie"` |
+| Volume trend | `"area"` |
+
+### R3F Scene Decisions
+
+Available scenes:
+- `"rotating-cube"` — interactive cube, good for tech demos. Set `scene.controls: true`.
+- `"particle-field"` — atmospheric particle cloud. Set `scene.controls: false`.
+
+Always set `lightText: true` for R3F slides (dark backgrounds).
+
+### Topic Badge Conventions
+
+Format: `"NN / Section Name"` for numbered sections:
+- `"01 / Problem"`, `"02 / Solution"`, `"03 / Value"`, `"04 / Evidence"`
+
+Or plain text: `"Huma Showcase"`, `"Technical Deep Dive"`.
+
+---
+
+## Visual Intent Mapping
+
+The narrative agent annotates each slide with a `**Visual intent:**` label. Map them to JSON treatments:
+
+| Visual Intent | type | centered | layout | brandFont | Background | lightText | Notes |
+|---|---|---|---|---|---|---|---|
+| `bookend` | content | true | single | true | optional image/color | if dark bg | Cover and CTA slides. showBranding: true |
+| `chapter-opener` | content | false or true | single | false | backgroundImage + overlay | true | Full-bleed image, sets section mood. Max 3 bullet points. |
+| `impact` | content | true | single | false | optional dark color | if dark bg | Single statement, no bullets. Let whitespace do the work. |
+| `workhorse` | content | false | single or two-column | false | none | false | Standard bullets/content. The default treatment. |
+| `evidence` | content or chart | false | single or two-column | false | none | false | Data-forward: chart, table, or comparison. |
+| `breathing-room` | content | true | single | false | backgroundImage + overlay OR style.backgroundColor | true | Minimal text. Visual pause. Resets audience attention. |
+
+When the outline lacks visual intent annotations, infer them:
+- First slide → bookend
+- Last slide → bookend
+- Slide after 2+ consecutive bullet-heavy slides → breathing-room or impact
+- Slide introducing a new topic section → chapter-opener
+- Slide with chart data or comparison → evidence
+- Everything else → workhorse
+
+---
+
+## Slide Recipes
+
+Complete `data` field patterns for common slide types.
+
+### Cover / Call to Action
+
+```json
+{
+  "label": "[Title or Ask]",
+  "topic": "[Company or Meeting Context]",
+  "content": "One sentence: what this is and for whom. (Cover) — or — what happens next and when. (CTA)",
+  "centered": true,
+  "brandFont": true,
+  "showBranding": true,
+  "brandingText": "[company.domain]"
+}
+```
+
+### Standard Bullets
+
+```json
+{
+  "label": "Headline claim that makes the point",
+  "topic": "01 / Problem",
+  "content": "## Headline claim in one sentence\n\n- Specific point with a number or named entity\n- Second point — consequence or contrast\n- Third point — the implication\n\nClosing sentence bridging to the next slide.",
+  "notes": "Talking point not on screen. Objection signal: 'If they ask X, navigate to [node-id].' Time: 2 minutes max.",
+  "centered": false
+}
+```
+
+### Impact Statement
+
+```json
+{
+  "label": "The Shift",
+  "topic": "01 / Problem",
+  "content": "The market has permanently changed.\n\n**Batch scheduling is structurally incompatible with same-day delivery expectations.**",
+  "notes": "Pause. Do not advance immediately.",
+  "centered": true
+}
+```
+
+### Two-Column Comparison
+
+```json
+{
+  "label": "Old Way vs. New Way",
+  "topic": "02 / Solution",
+  "content": "## Today\n- 3 systems, no shared state\n- 11 hours/week reconciling exports\n\n---\n\n## With [Product]\n- Single live record across all systems\n- Reports update in real time",
+  "layout": "two-column",
+  "centered": false
+}
+```
+
+### Text + Inline Chart
+
+```json
+{
+  "label": "The Data Confirms It",
+  "topic": "03 / Evidence",
+  "content": "## Continuous monitoring outperforms batch on every metric\n\nThree field studies. Same result each time.\n\n---\n\n[chart:comparison]",
+  "charts": {
+    "comparison": {
+      "chartType": "bar",
+      "data": [{ "metric": "Uptime %", "ours": 98.2, "baseline": 91.5 }],
+      "config": { "xKey": "metric", "yKeys": ["ours", "baseline"], "showGrid": true, "showLegend": true }
+    }
+  },
+  "layout": "two-column",
+  "centered": false
+}
+```
+
+### Proof Point / Customer Quote
+
+```json
+{
+  "label": "Summit Health: Year One",
+  "topic": "04 / Proof",
+  "content": "## 2.3 hours of admin time eliminated per nurse per shift\n\n> \"The conflicts surfaced automatically.\"\n> — VP Operations, Summit Health (42 facilities)\n\n- 38% reduction in shift coverage failures\n- Full rollout across 6 units in 11 weeks",
+  "notes": "If they ask about rollout timeline, the drill-down below has the full breakdown.",
+  "centered": false
+}
+```
+
+### Section Opener with Background Image
+
+```json
+{
+  "label": "The Opportunity",
+  "topic": "03 / Opportunity",
+  "content": "## A $40B market with no dominant platform\n\nEvery competitor is solving scheduling.\nNobody is solving the coordination layer.",
+  "backgroundImage": "https://images.unsplash.com/photo-XXXXX?w=1920&q=80",
+  "backgroundImageFit": "cover",
+  "backgroundImageOverlay": true,
+  "lightText": true,
+  "centered": false
+}
+```
+
+### Styled Background Color Slide
+
+```json
+{
+  "label": "Styling & Branding",
+  "topic": "04 / Features",
+  "content": "## Per-slide styling\n\n- Custom background colors\n- Light text mode for dark backgrounds\n- Brand font for titles",
+  "lightText": true,
+  "brandFont": true,
+  "centered": true,
+  "showBranding": true,
+  "brandingText": "huma.energy"
+}
+```
+
+With `style.backgroundColor` set at the node level:
+
+```json
+"style": { "width": 180, "height": 70, "backgroundColor": "#1a1a2e" }
+```
+
+---
+
+## Complete Reference Example
+
+A 7-node presentation demonstrating key slide types. This is the minimum viable structure the design agent should know how to produce.
+
+```json
+{
+  "meta": {
+    "name": "Graph-Based Presentations"
+  },
+  "nodes": [
+    {
+      "id": "cover",
+      "type": "huma",
+      "position": { "x": 0, "y": 0 },
+      "data": {
+        "label": "Graph-Based Presentations",
+        "topic": "Huma Showcase",
+        "content": "Non-linear storytelling for technical teams.\n\nNavigate with arrow keys. Press **down** to drill into any topic.",
+        "centered": true,
+        "brandFont": true,
+        "showBranding": true,
+        "brandingText": "huma.energy"
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "problem",
+      "type": "huma",
+      "position": { "x": 240, "y": 0 },
+      "data": {
+        "label": "The Problem",
+        "topic": "01 / Problem",
+        "content": "## Linear tools break complex stories\n\n- Cannot branch based on audience questions\n- Skipping sections breaks the flow\n- Presenters get lost navigating dense topics\n- No private view for speaker notes during screen share\n\nEvery meeting is different. The presentation should adapt.",
+        "notes": "Pause here and ask: 'Does this match what you experience with your current tooling?' Key talking point: the fourth bullet resonates most with technical presenters.",
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "problem-detail",
+      "type": "huma",
+      "position": { "x": 240, "y": 150 },
+      "data": {
+        "label": "Value Breakdown",
+        "topic": "03 / Value",
+        "content": "## Flexible narratives\nAdapt flow to audience type and questions in real time\n\n---\n\n## Consistent style\nReuse front-end web styling and components directly\n\n## Professional delivery\nSpeaker notes and timing without the audience seeing them",
+        "layout": "two-column",
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "value",
+      "type": "huma",
+      "position": { "x": 480, "y": 0 },
+      "data": {
+        "label": "The Value",
+        "topic": "03 / Value",
+        "content": "## Why this approach wins\n\n[chart:value]\n\nAdapt to the audience. Reuse web components. Deliver with confidence.",
+        "charts": {
+          "value": {
+            "chartType": "radar",
+            "data": [
+              { "axis": "Flexibility", "graph": 95, "traditional": 30 },
+              { "axis": "Visual Quality", "graph": 90, "traditional": 50 },
+              { "axis": "Interactivity", "graph": 85, "traditional": 20 },
+              { "axis": "Ease of Use", "graph": 60, "traditional": 90 },
+              { "axis": "Consistency", "graph": 85, "traditional": 40 },
+              { "axis": "Tech Signal", "graph": 95, "traditional": 15 }
+            ],
+            "config": {
+              "xKey": "axis",
+              "yKeys": ["graph", "traditional"],
+              "showGrid": true,
+              "showLegend": true
+            }
+          }
+        },
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "feat-3d",
+      "type": "huma",
+      "position": { "x": 720, "y": 0 },
+      "data": {
+        "label": "3D Scenes",
+        "topic": "04 / Features",
+        "type": "r3f",
+        "scene": {
+          "component": "rotating-cube",
+          "controls": true,
+          "background": "#1a1a2e"
+        },
+        "content": "Interactive React Three Fiber scene.\n\nDrag to rotate. Scroll to zoom. Scenes load from a component registry.",
+        "lightText": true
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "feat-bgimage",
+      "type": "huma",
+      "position": { "x": 960, "y": 0 },
+      "data": {
+        "label": "Background Image",
+        "topic": "04 / Features",
+        "content": "## Full-bleed imagery\n\nUpload any image as a slide background. Toggle overlay for text readability.\n\n- Cover/contain fit modes\n- Dark overlay toggle\n- Light text auto-detection",
+        "backgroundImage": "https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920&q=80",
+        "backgroundImageFit": "cover",
+        "backgroundImageOverlay": true,
+        "lightText": true,
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "end",
+      "type": "huma",
+      "position": { "x": 1200, "y": 0 },
+      "data": {
+        "label": "Get Started",
+        "content": "Fork this template to build your own.\n\nEvery slide, chart, and scene is editable in the graph editor.",
+        "centered": true,
+        "brandFont": true,
+        "showBranding": true,
+        "brandingText": "huma.energy"
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    }
+  ],
+  "edges": [
+    { "id": "e-cover-problem", "source": "cover", "target": "problem", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-problem-cover", "source": "problem", "target": "cover", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-problem-value", "source": "problem", "target": "value", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-value-problem", "source": "value", "target": "problem", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-problem-detail", "source": "problem", "target": "problem-detail", "sourceHandle": "s-bottom", "targetHandle": "t-top" },
+    { "id": "e-detail-problem", "source": "problem-detail", "target": "problem", "sourceHandle": "s-top", "targetHandle": "t-bottom" },
+    { "id": "e-value-3d", "source": "value", "target": "feat-3d", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-3d-value", "source": "feat-3d", "target": "value", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-3d-bgimage", "source": "feat-3d", "target": "feat-bgimage", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-bgimage-3d", "source": "feat-bgimage", "target": "feat-3d", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-bgimage-end", "source": "feat-bgimage", "target": "end", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-end-bgimage", "source": "end", "target": "feat-bgimage", "sourceHandle": "s-left", "targetHandle": "t-right" }
+  ]
+}
+```
+
+### Additional Patterns from the Demo
+
+**Styled background color node** (node-level `style.backgroundColor`):
+
+```json
+{
+  "id": "feat-style",
+  "type": "huma",
+  "position": { "x": 1920, "y": 150 },
+  "data": {
+    "label": "Styling & Branding",
+    "topic": "04 / Features",
+    "content": "## Per-slide styling\n\n- Custom background colors\n- Light text mode for dark backgrounds\n- Brand font for titles",
+    "lightText": true,
+    "brandFont": true,
+    "centered": true,
+    "showBranding": true,
+    "brandingText": "huma.energy"
+  },
+  "style": { "width": 180, "height": 70, "backgroundColor": "#1a1a2e" },
+  "measured": { "width": 180, "height": 70 }
+}
+```
+
+**Second-level drill-down** (y:300, child of a y:150 node):
+
+```json
+{
+  "id": "feat-tables",
+  "type": "huma",
+  "position": { "x": 960, "y": 300 },
+  "data": { "label": "Tables", "topic": "04 / Features", "content": "...", "centered": false },
+  "style": { "width": 180, "height": 70 },
+  "measured": { "width": 180, "height": 70 }
+}
+```
+
+Edges: `feat-markdown` (y:150) → `feat-tables` (y:300) via `s-bottom`/`t-top`.
+
+**Sibling drill-downs connected horizontally** (same y-level, `s-right`/`t-left`):
+
+```json
+{ "id": "e-md-charts", "source": "feat-markdown", "target": "feat-charts", "sourceHandle": "s-right", "targetHandle": "t-left" }
+{ "id": "e-charts-md", "source": "feat-charts", "target": "feat-markdown", "sourceHandle": "s-left", "targetHandle": "t-right" }
+```
+
+Both at y:150, connected horizontally within the drill-down branch.
+
+---
+
+## Media Delivery Summary Format
+
+After generating the JSON, list any slides with placeholder media:
+
+```
+Slides requiring manual media upload:
+- "Cover" — background video: [description]
+- "Demo" — inline video: [description]
+
+Upload via POST /api/slide-images/upload (multipart/form-data, field: "file")
+Returns { ok: true, key, url } — replace placeholder with returned url
+Accepted: all image/*, video/mp4, video/webm, video/quicktime
+Max size: 50MB
+```