@ztffn/presentation-generator-plugin 1.0.0

package/skills/presentation-generator/system/node-schema.md

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

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