@ztffn/presentation-generator-plugin 1.2.0 → 1.3.0

package/skills/presentation-generator/SKILL.md

@@ -187,7 +187,7 @@ Replace the PLACEHOLDER string with the returned URL after upload.
 |---|---|---|
 | `presentation-content` | `content-signals` | Extract structured brief from documents |
 | `presentation-narrative` | `frameworks`, `slide-content`, `graph-topology` | Design story structure and slide content |
-| `presentation-design` | `node-schema`, `edge-conventions`, `layout-templates`, `positioning`, `pitch-reference` | Translate outline to valid graph JSON |
+| `presentation-design` | `graph-json-spec` | Translate outline to valid graph JSON |
 
 ## Working Without Documents
 

package/skills/slide-content/SKILL.md

@@ -196,3 +196,48 @@ Same content, different quality. Study what changed and why.
 | Bullets | Generic descriptions | Named roles with concrete hour counts |
 | Implication | Absent | Explicit (→ connector) |
 | Speaker notes | Repetition of screen content | Anticipation, objection routing, time guidance |
+
+## Visual Rhythm
+
+Presentations that feel designed — not generated — alternate between dense and light slides. A deck of wall-to-wall bullets is exhausting. A deck of nothing but images is empty. The rhythm between them is what holds attention.
+
+### The Rhythm Principle
+
+Alternate content-heavy slides with breathing-room slides. After 2-3 slides carrying bullets, data, or detailed argument, insert a visual reset: an image slide, an impact statement, or a centered single thought. This gives the audience a moment to absorb before the next dense block.
+
+Think of it as chapters in a book. Dense paragraphs need white space between them. A presentation spine needs the same cadence.
+
+### Visual Intent Annotations
+
+The narrative agent should annotate each slide in the outline with a `**Visual intent:**` line indicating the slide's visual role. These labels communicate pacing intent to the design agent without prescribing any specific layout or JSON treatment.
+
+| Label | Purpose |
+|---|---|
+| `chapter-opener` | Full-bleed image, centered text, sets mood for a new section |
+| `impact` | Single bold statement, centered, no bullets, emotional weight |
+| `workhorse` | Standard bullets/content, the default |
+| `evidence` | Data-forward: chart, table, or comparison |
+| `bookend` | Cover or CTA, branded, symmetrical with its pair |
+| `breathing-room` | Minimal text over image or color, resets attention after dense slides |
+
+Example annotation in an outline:
+
+```
+Slide 4: "Response time dropped 60% — infrastructure cost followed"
+Key message: The platform delivers measurable speed and cost gains.
+**Visual intent:** evidence
+```
+
+### Pacing Rules
+
+1. **No three-in-a-row.** Never place 3 or more `workhorse` slides consecutively without a visual reset (`impact`, `chapter-opener`, or `breathing-room`).
+
+2. **Alternate dense and light.** The spine should weave between heavy and light visual weight. `workhorse` → `evidence` → `impact` → `workhorse` is better than `workhorse` → `workhorse` → `workhorse` → `impact`.
+
+3. **Chapter openers at section boundaries.** When the spine moves to a new major topic, mark the transitional slide as `chapter-opener`. This signals a mood shift and gives the audience a visual cue that the argument is entering new territory.
+
+4. **Bookends mirror each other.** The cover slide and the closing CTA should feel symmetrical in visual weight. Both are `bookend` — they frame the presentation as a pair.
+
+5. **Breathing room after sustained density.** If the outline has a run of `workhorse` and `evidence` slides (detailed argument, data, comparison), follow it with a `breathing-room` or `impact` slide before continuing. The audience needs a reset.
+
+These annotations describe intent only. How the design agent translates them into layout, background, and typography is not the narrative agent's concern.

package/skills/edge-conventions/SKILL.md

@@ -1,97 +0,0 @@
----
-name: edge-conventions
-description: Authoritative reference for wiring navigation edges — handle IDs, bidirectional pairs, and validation checklist.
----
-
-# Edge Conventions
-
-Authoritative reference for wiring navigation edges in the presentation graph.
-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" }
-```
-
-A → (right) → B and B → (left) → A
-
-### 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" }
-```
-
-Parent → (down) → Child and Child → (up) → Parent
-
-### Horizontal Within a Drill-Down Branch
-
-Siblings within a drill-down branch use the same horizontal pattern:
-
-```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
-
-Use descriptive hyphenated strings:
-
-- `e-cover-problem` — cover to problem
-- `e-problem-cover` — problem back to cover
-- `e-problem-detail` — problem drill-down to detail
-- `e-detail-problem` — detail return to problem
-
-Pattern: `e-{source}-{target}` using the node IDs or abbreviated forms.
-
-## Validation Checklist
-
-Run this checklist before writing the final JSON:
-
-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**
-
-## 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. Edges without explicit handles will have direction inferred from node positions, but this is a fallback — always set handles explicitly.

package/skills/layout-templates/SKILL.md

@@ -1,315 +0,0 @@
----
-name: layout-templates
-description: Decision guide mapping content signals to slide type, layout, background treatment, and visual configuration.
----
-
-# Layout Templates & Design Decisions
-
-Decision guide for the design agent. Maps content signals from the slide outline
-to the correct visual treatment in the graph JSON.
-
-## 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 `---` when:
-
-- **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:** Bullets, tables, code, multiple paragraphs
-- **Data slides:** Charts with explanatory text
-- **Comparison slides:** Two-column layouts
-
-### 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: "huma.energy"` (or client name) for:
-
-- Cover slide
-- Closing slide
-- Any slide where the audience might screenshot or reference later
-
-Default is `true`, so only set `showBranding: false` for immersive slides (R3F, full-bleed video) where the overlay is distracting.
-
-## Background Treatment
-
-### Background Image
-
-Use `backgroundImage` when the outline indicates:
-- A mood or atmosphere for a section opener
-- Visual evidence (photo of a product, facility, or result)
-- Impact slide where imagery reinforces the message
-
-Set `backgroundImageOverlay: true` and `lightText: true` when text appears over the image.
-
-**Image sourcing:** Use external URLs directly. Unsplash with query params works well:
-```
-https://images.unsplash.com/photo-XXXXX?w=1920&q=80
-```
-
-### Background Video
-
-Use `backgroundVideo` for cinematic section openers or demo context.
-
-**Video sourcing is deferred.** For any slide requiring background video:
-1. Set `backgroundVideo` to a placeholder: `"PLACEHOLDER: [description of needed video]"`
-2. Set `backgroundVideoFit: "cover"` and `backgroundVideoLoop: true`
-3. Add the slide title to the delivery summary for manual upload
-
-### Inline Video
-
-For videos embedded in slide content (via `![alt](url)` in markdown):
-1. Set the URL to a placeholder: `"PLACEHOLDER: [description]"`
-2. Configure `inlineVideoControls`, `inlineVideoAutoplay`, `inlineVideoLoop` as appropriate
-3. Add to delivery summary
-
-### Text Contrast
-
-Set `lightText: true` whenever the 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"`)
-
-Use when the data IS the slide — the chart is the primary message, not supporting evidence.
-
-```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)
-
-Use when data supports a text argument — the chart is evidence, not the headline.
-
-```json
-{
-  "content": "## Why this approach wins\n\n[chart:comparison]\n\nAdapt to the audience. Deliver with confidence.",
-  "charts": {
-    "comparison": {
-      "chartType": "radar",
-      "data": [...],
-      "config": { "xKey": "axis", "yKeys": ["ours", "theirs"], "showLegend": true }
-    }
-  }
-}
-```
-
-### Chart Title Rule
-
-A chart's `label` field states the insight, not the data category. The audience should understand your point before reading the chart.
-
-| Weak (category label) | Strong (insight claim) |
-|---|---|
-| "Revenue Data" | "Revenue grew 40% QoQ after the pricing change" |
-| "Response Time" | "Response time dropped 60% after caching rollout" |
-| "User Growth" | "1M users in 6 months — 2× ahead of plan" |
-
-The label is your assertion. The chart is your evidence.
-
-### 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
-
-Use `type: "r3f"` when the outline calls for a 3D demo or visual impact.
-
-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). Content renders as an overlay on top of the 3D scene.
-
-## Topic Badge Conventions
-
-Use `topic` to group slides by section. Format: `"NN / Section Name"` for numbered sections:
-
-- `"01 / Problem"`
-- `"02 / Solution"`
-- `"03 / Value"`
-- `"04 / Evidence"`
-
-Or plain text for non-numbered groupings: `"Huma Showcase"`, `"Technical Deep Dive"`.
-
-## Slide Recipes
-
-Complete `data` field patterns for common pitch slide types. Combine with `node-schema.md` for the full field reference.
-
-### Cover / Call to Action
-
-Cover = first spine node. CTA = last. Both: centered, branded, no bullets. The only difference is the label and content.
-
-```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 — Workhorse
-
-Default for problem, solution, evidence, and detail nodes.
-
-```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
-
-Single message, no bullets. Use for named shifts, "why now" openers, or bold claims that stand alone.
-
-```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. If the room agrees, the rest is inevitable.",
-  "centered": true
-}
-```
-
-### Two-Column Comparison
-
-Before/after, us/them, or two parallel arguments. Content splits on `---`; left column renders first.
-
-```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- Reports are always one day stale\n\n---\n\n## With [Product]\n- Single live record across all systems\n- Reports update in real time\n- Finance, ops, and leadership see the same data",
-  "layout": "two-column",
-  "centered": false
-}
-```
-
-### Text + Inline Chart
-
-Text on left makes the claim; chart on right is the evidence. Chart is supporting, not the headline.
-
-```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
-
-Named case study or customer quote. Blockquote (`>`) renders as a styled pull quote — lead with it before the numbers.
-
-```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 — we'd been creating them for years without knowing it.\"\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 — Background Image
-
-Spine node opening a new chapter. Sets atmosphere. Max 3 bullet points on an image slide.
-
-```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
-}
-```
-
-## Media Delivery Summary
-
-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
-```

package/skills/node-schema/SKILL.md

@@ -1,135 +0,0 @@
----
-name: node-schema
-description: Authoritative reference for SlideNodeData interface — all fields, types, and defaults for graph presentation nodes.
----
-
-# Node Schema Reference
-
-Authoritative reference for the `SlideNodeData` interface.
-Derived from `src/types/presentation.ts`. All fields, types, and defaults documented here.
-
-## Node Wrapper
-
-Every node in the graph has this structure:
-
-```json
-{
-  "id": "unique-slug",
-  "type": "huma",
-  "position": { "x": 0, "y": 0 },
-  "data": { /* SlideNodeData fields below */ },
-  "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.md`)
-- `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.
-
-## Available R3F Scene Components
-
-| Registry Key | Description |
-|---|---|
-| `rotating-cube` | Interactive rotating cube with OrbitControls |
-| `particle-field` | Animated particle cloud background |
-
-## 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