@ztffn/presentation-generator-plugin 1.1.5 → 1.3.0

package/skills/presentation-generator/system/layout-templates.md

@@ -1,310 +0,0 @@
-# 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/presentation-generator/system/node-schema.md

@@ -1,130 +0,0 @@
-# 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

package/skills/presentation-generator/system/positioning.md

@@ -1,84 +0,0 @@
-# Node Positioning
-
-How to place nodes on the graph canvas for a clean, readable layout in the editor.
-Position affects visual arrangement only — navigation is determined by edges.
-
-## Grid System
-
-| 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:   240     480
-y:0  [Problem] [Solution]
-      ↓          ↓
-y:150 [Detail]  [How It Works]
-      ↓
-y:300 [Root Cause]
-```
-
-### Multiple Siblings in a Branch
-
-When a spine node has multiple drill-down children at the same depth:
-
-```
-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 Template
-
-```json
-{
-  "position": { "x": 0, "y": 0 }
-}
-```
-
-Quick reference for a 5-node spine with one drill-down each:
-
-| 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 for the folder-tree metaphor to hold
-5. No two nodes should overlap (maintain at least 240px horizontal, 150px vertical separation)