@elyracode/anna 0.5.4

package/README.md

@@ -0,0 +1,58 @@
+# @elyracode/anna
+
+Elyra extension for **Anna.js** -- generate, preview, and build Markdown presentations with terminal animations, live code, Mermaid diagrams, and audience interaction.
+
+## Install
+
+```
+elyra install npm:@elyracode/anna
+```
+
+Requires Anna.js CLI:
+```
+npm install -g @kwhorne/anna.js
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `generate_presentation` | Generate a complete Anna.js presentation from a topic or project context |
+| `preview_presentation` | Start dev server with live reload and open in browser |
+| `build_presentation` | Generate self-contained HTML (with optional offline/PWA support) |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/presentation [topic]` | Generate a new presentation |
+| `/slides [file]` | Preview an existing presentation |
+
+## Skills
+
+The `anna-js` skill provides the complete Anna.js syntax reference so the agent generates correct Markdown including slides, fragments, terminal animations, live code playgrounds, Mermaid diagrams, component layouts, speaker notes, and themes.
+
+## Usage
+
+```
+> Create a presentation about our project architecture
+> Generate slides for a Kubernetes intro with terminal demos and diagrams
+> Add a slide with a Mermaid flowchart showing the auth flow
+> Preview slides.md in the browser
+> Build the presentation as offline HTML
+/presentation API onboarding guide
+/slides
+```
+
+## Features
+
+The agent can generate presentations with:
+- **Slides** with horizontal (`---`) and vertical (`--`) navigation
+- **Fragments** for step-by-step reveals
+- **Terminal animations** with realistic typing effects
+- **Live code playgrounds** (JS, HTML, CSS) with console output
+- **Mermaid diagrams** (flowcharts, sequence, gantt, etc.)
+- **Component layouts** (columns, comparison, timeline, stats, cards, quotes)
+- **Speaker notes** and keyboard shortcuts
+- **11 themes** (dark and light)
+- **Offline/PWA** mode for conferences without WiFi

package/extensions/index.ts

@@ -0,0 +1,249 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { Type } from "typebox";
+
+export default function (elyra: ExtensionAPI): void {
+
+	// ── Tool: generate_presentation ──
+	elyra.registerTool({
+		name: "generate_presentation",
+		label: "Generate Presentation",
+		description:
+			"Generate an Anna.js Markdown presentation from a description or project context. " +
+			"Creates a complete .md file with slides, fragments, diagrams, terminal animations, " +
+			"and code playgrounds. Use the anna-js skill for correct syntax. " +
+			"The presentation can be previewed with `anna serve`.",
+		parameters: Type.Object({
+			topic: Type.String({
+				description: "Topic or description for the presentation (e.g., 'Project architecture overview', 'API onboarding guide')",
+			}),
+			output: Type.Optional(
+				Type.String({ description: "Output file path (default: slides.md)" }),
+			),
+			theme: Type.Optional(
+				Type.String({ description: "Theme: league, moon, night, black, blood, white, beige, sky, serif, simple, solarized (default: moon)" }),
+			),
+			slides: Type.Optional(
+				Type.Number({ description: "Approximate number of slides (default: 10)" }),
+			),
+			features: Type.Optional(
+				Type.Array(Type.String(), {
+					description: "Features to include: terminal, playground, mermaid, fragments, components (default: all)",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			const output = params.output ?? "slides.md";
+			const theme = params.theme ?? "moon";
+			const slideCount = params.slides ?? 10;
+			const features = params.features ?? ["terminal", "playground", "mermaid", "fragments", "components"];
+
+			const instructions: string[] = [
+				`# Generate Anna.js Presentation`,
+				"",
+				`**Topic**: ${params.topic}`,
+				`**Output file**: ${output}`,
+				`**Theme**: ${theme}`,
+				`**Target slides**: ~${slideCount}`,
+				`**Features**: ${features.join(", ")}`,
+				"",
+				"## Instructions",
+				"",
+				"Write a complete Anna.js Markdown presentation file. Requirements:",
+				"",
+				"1. Start with YAML frontmatter (title, theme, transition)",
+				"2. Use `---` for horizontal slide separators",
+				"3. Use `--` for vertical sub-slides where appropriate",
+				"4. Use `<!-- .fragments -->` for step-by-step reveals on lists",
+				"5. Add speaker notes with `Note:` where helpful",
+			];
+
+			if (features.includes("terminal")) {
+				instructions.push("6. Include ````terminal` blocks for CLI demos with realistic commands");
+			}
+			if (features.includes("playground")) {
+				instructions.push("7. Include ````playground` blocks for live code examples");
+			}
+			if (features.includes("mermaid")) {
+				instructions.push("8. Include ````mermaid` blocks for architecture/flow diagrams");
+			}
+			if (features.includes("components")) {
+				instructions.push("9. Use layout components (`<!-- @columns -->`, `<!-- @stats -->`, `<!-- @timeline -->`) for visual variety");
+			}
+
+			instructions.push(
+				"",
+				`Write the presentation to \`${output}\` using the write tool.`,
+				"Make it visually engaging with a mix of text, code, and diagrams.",
+				"End with a clear summary/thank-you slide.",
+			);
+
+			return {
+				content: [{ type: "text", text: instructions.join("\n") }],
+				details: { output, theme, slideCount },
+			};
+		},
+	});
+
+	// ── Tool: preview_presentation ──
+	elyra.registerTool({
+		name: "preview_presentation",
+		label: "Preview Presentation",
+		description:
+			"Start the Anna.js dev server to preview a presentation in the browser. " +
+			"Opens the presentation with live reload -- edits to the .md file update instantly. " +
+			"Requires @kwhorne/anna.js to be installed globally.",
+		parameters: Type.Object({
+			file: Type.Optional(
+				Type.String({ description: "Markdown file to preview (default: slides.md)" }),
+			),
+			port: Type.Optional(
+				Type.Number({ description: "Server port (default: 3000)" }),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			const file = params.file ?? "slides.md";
+			const port = params.port ?? 3000;
+			const cwd = process.cwd();
+
+			if (!existsSync(join(cwd, file))) {
+				return {
+					content: [{ type: "text", text: `File not found: ${file}. Generate a presentation first with generate_presentation.` }],
+					details: {},
+				};
+			}
+
+			// Check if anna is installed
+			if (!isAnnaInstalled()) {
+				return {
+					content: [{
+						type: "text",
+						text: "Anna.js CLI not found. Install it with:\n\nnpm install -g @kwhorne/anna.js\n\nThen try again.",
+					}],
+					details: {},
+				};
+			}
+
+			// Start anna serve in background
+			try {
+				execSync(`anna serve "${file}" --port ${port} --open &`, {
+					cwd,
+					timeout: 5000,
+					stdio: "pipe",
+				});
+			} catch {
+				// Expected -- the & backgrounds it
+			}
+
+			return {
+				content: [{
+					type: "text",
+					text: `Presentation server started at http://localhost:${port}\nFile: ${file}\nLive reload enabled -- edit the .md file to see changes instantly.`,
+				}],
+				details: { file, port },
+			};
+		},
+	});
+
+	// ── Tool: build_presentation ──
+	elyra.registerTool({
+		name: "build_presentation",
+		label: "Build Presentation HTML",
+		description:
+			"Generate the HTML file from an Anna.js Markdown presentation. " +
+			"Creates a self-contained HTML file that can be opened directly in a browser. " +
+			"Use --offline for bundled Mermaid, --pwa for installable offline app.",
+		parameters: Type.Object({
+			file: Type.Optional(
+				Type.String({ description: "Markdown file to build (default: slides.md)" }),
+			),
+			offline: Type.Optional(
+				Type.Boolean({ description: "Bundle Mermaid locally for offline use (default: false)" }),
+			),
+			pwa: Type.Optional(
+				Type.Boolean({ description: "Generate PWA manifest and service worker (default: false)" }),
+			),
+		}),
+		execute: async (_toolCallId, params) => {
+			const file = params.file ?? "slides.md";
+			const cwd = process.cwd();
+
+			if (!existsSync(join(cwd, file))) {
+				return {
+					content: [{ type: "text", text: `File not found: ${file}` }],
+					details: {},
+				};
+			}
+
+			if (!isAnnaInstalled()) {
+				return {
+					content: [{ type: "text", text: "Anna.js CLI not found. Install with: npm install -g @kwhorne/anna.js" }],
+					details: {},
+				};
+			}
+
+			const flags: string[] = [];
+			if (params.offline) flags.push("--offline");
+			if (params.pwa) flags.push("--pwa");
+
+			try {
+				const result = execSync(`anna generate "${file}" ${flags.join(" ")}`, {
+					cwd,
+					timeout: 30000,
+					encoding: "utf-8",
+					stdio: ["pipe", "pipe", "pipe"],
+				});
+
+				const htmlFile = file.replace(/\.md$/, ".html");
+				return {
+					content: [{ type: "text", text: `Built: ${htmlFile}\n${result.trim()}` }],
+					details: { output: htmlFile },
+				};
+			} catch (error) {
+				const msg = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text", text: `Build failed: ${msg}` }],
+					details: {},
+				};
+			}
+		},
+	});
+
+	// ── Commands ──
+	elyra.registerCommand("presentation", {
+		description: "Generate an Anna.js presentation from a topic or project",
+		handler: async (args, _ctx) => {
+			if (!args.trim()) {
+				elyra.sendUserMessage(
+					"I want to create a presentation. Ask me what topic or project area to present, " +
+					"how many slides, and which features to include (terminal demos, live code, diagrams).",
+				);
+				return;
+			}
+			elyra.sendUserMessage(`Generate an Anna.js presentation about: ${args}`);
+		},
+	});
+
+	elyra.registerCommand("slides", {
+		description: "Preview or build an existing presentation",
+		handler: async (args, _ctx) => {
+			const file = args.trim() || "slides.md";
+			elyra.sendUserMessage(`Preview the presentation at ${file} using anna serve.`);
+		},
+	});
+}
+
+function isAnnaInstalled(): boolean {
+	try {
+		execSync("which anna 2>/dev/null || where anna 2>/dev/null", {
+			timeout: 5000,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@elyracode/anna",
+  "version": "0.5.4",
+  "description": "Elyra extension for Anna.js -- generate, preview, and edit Markdown presentations with terminal animations, live code, and Mermaid diagrams",
+  "type": "module",
+  "keywords": ["elyra-package", "anna", "presentation", "slides", "markdown", "mermaid"],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/anna"
+  },
+  "elyra": {
+    "extensions": ["./extensions/index.ts"],
+    "skills": ["./skills"]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}

package/skills/anna-js/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: anna-js
+description: Complete reference for Anna.js presentation framework. Use when generating, editing, or converting Markdown presentations with Anna.js syntax including slides, fragments, terminal animations, live code playgrounds, Mermaid diagrams, components, and layouts.
+---
+
+# Anna.js Syntax Reference
+
+## Slide Structure
+
+```markdown
+---
+title: My Presentation
+theme: moon
+transition: slide
+controls: true
+progress: true
+center: true
+---
+
+# First Slide
+
+---
+
+## Second Slide
+
+Content here.
+
+--
+
+### Vertical Sub-slide
+
+Under the second slide.
+
+---
+
+## Third Slide
+```
+
+- `---` separates horizontal slides
+- `--` separates vertical sub-slides (navigate with arrow down)
+- YAML frontmatter configures the presentation
+
+## Frontmatter Options
+
+| Option | Values | Default |
+|--------|--------|---------|
+| `title` | string | untitled |
+| `author` | string | - |
+| `theme` | league, moon, night, black, blood, white, beige, sky, serif, simple, solarized | league |
+| `transition` | slide, fade, convex, concave, zoom, none | slide |
+| `controls` | true/false | true |
+| `progress` | true/false | true |
+| `center` | true/false | true |
+| `hash` | true/false | true |
+| `autoSlide` | milliseconds (0 = off) | 0 |
+| `loop` | true/false | false |
+
+## Fragments (Step-by-step Reveal)
+
+```markdown
+<!-- .fragments -->
+- First point (revealed on click)
+- Second point
+- Third point
+```
+
+Single paragraph fragment:
+```markdown
+<!-- .fragment -->
+This paragraph appears on click.
+```
+
+## Speaker Notes
+
+```markdown
+## My Slide
+
+Content visible to audience.
+
+Note:
+These are speaker notes.
+Only visible in speaker view (press S).
+```
+
+## Backgrounds
+
+```markdown
+<!-- .slide: data-background="#4d7e65" -->
+## Green Background
+
+<!-- .slide: data-background-image="photo.jpg" -->
+## Image Background
+```
+
+## Terminal Animations
+
+Commands are typed out character by character with a realistic typing effect:
+
+````markdown
+```terminal
+$ npm install anna.js
+added 42 packages in 2.3s
+
+$ anna generate slides.md
+✓ slides.md → slides.html
+```
+````
+
+Each command group separated by blank lines is a fragment step.
+
+## Live Code Playground
+
+### JavaScript
+````markdown
+```playground
+const greeting = "Hello, Anna.js!";
+console.log(greeting);
+```
+````
+
+### HTML
+````markdown
+```playground html
+<h1 style="color: coral">Hello!</h1>
+<p>This renders live.</p>
+```
+````
+
+### Multi-file (JS + HTML + CSS tabs)
+````markdown
+```playground multi
+=== js
+document.getElementById('msg').textContent = 'Hello!';
+=== html
+<div id="msg">Loading...</div>
+=== css
+#msg { color: coral; font-size: 2em; text-align: center; }
+```
+````
+
+### Step-by-step Code (incremental with diffs)
+````markdown
+```playground step 1
+const x = 1;
+console.log(x);
+```
+````
+
+Next slide:
+````markdown
+```playground step 2
+const x = 1;
+const y = 2;
+console.log(x + y);
+```
+````
+
+Added lines are highlighted in green.
+
+### Console Support
+Captures: `console.log()`, `console.error()`, `console.warn()`, `console.info()`, `console.table()`, `console.clear()`, `console.group()`, `console.groupEnd()`, plus the return value of the last expression.
+
+## Mermaid Diagrams
+
+````markdown
+```mermaid
+graph LR
+    A[Idea] --> B[Markdown] --> C[Presentation]
+```
+````
+
+````markdown
+```mermaid
+sequenceDiagram
+    User->>CLI: slides.md
+    CLI->>HTML: Generate
+    HTML-->>User: slides.html
+```
+````
+
+````markdown
+```mermaid
+gantt
+    title Project Timeline
+    section Phase 1
+    Research: 2024-01-01, 30d
+    section Phase 2
+    Development: 2024-02-01, 60d
+```
+````
+
+All Mermaid diagram types are supported. Theme auto-matches the presentation theme.
+
+## Component Layouts
+
+### Columns
+```markdown
+<!-- @columns -->
+### Left Column
+Content here.
+<!-- @col -->
+### Right Column
+More content.
+<!-- @end -->
+```
+
+### Comparison (Pros/Cons)
+```markdown
+<!-- @comparison pros="Advantages" cons="Disadvantages" -->
+- Fast performance
+- Easy to learn
+<!-- @vs -->
+- Steep learning curve
+- Complex setup
+<!-- @end -->
+```
+
+### Timeline
+```markdown
+<!-- @timeline -->
+- **2020** — Project started
+- **2021** — First release
+- **2023** — Version 2.0
+<!-- @end -->
+```
+
+### Stats (Big Numbers)
+```markdown
+<!-- @stats -->
+- 10K+ | Downloads
+- 99.9% | Uptime
+- 50ms | Response Time
+<!-- @end -->
+```
+
+### Quote
+```markdown
+<!-- @quote author="Knut W. Horne" -->
+The best presentations are written in Markdown.
+<!-- @end -->
+```
+
+### Cards
+```markdown
+<!-- @cards -->
+### Card 1
+Description here.
+### Card 2
+Another description.
+<!-- @end -->
+```
+
+### Image + Text
+```markdown
+<!-- @image-text src="photo.jpg" -->
+### Title
+Description next to the image.
+<!-- @end -->
+```
+
+### Icon List
+```markdown
+<!-- @icon-list -->
+- 🚀 | **Fast** | Built for speed
+- 🔒 | **Secure** | Enterprise ready
+- 🎨 | **Beautiful** | 11 themes
+<!-- @end -->
+```
+
+### Custom Components (Reusable)
+```markdown
+<!-- @component: team-card -->
+### {name}
+*{role}*
+<!-- @end -->
+
+<!-- @use: team-card name="Knut" role="Creator" -->
+<!-- @use: team-card name="Anna" role="Designer" -->
+```
+
+## Live Audience Interaction
+
+### Polls (requires `anna live`)
+````markdown
+```poll What is your favorite language?
+- JavaScript
+- Python
+- Rust
+- Go
+```
+````
+
+### Q&A (requires `anna live`)
+````markdown
+```qa Ask me anything!
+```
+````
+
+## CLI Commands
+
+```bash
+anna init my-presentation          # scaffold new project
+anna generate slides.md            # generate HTML
+anna generate slides.md --watch    # watch mode
+anna serve slides.md               # dev server with live reload
+anna live slides.md                # live server with polls/Q&A
+anna ai "Topic"                    # AI-generated presentation
+anna ai refine slides.md           # improve existing
+anna ai translate slides.md --lang en  # translate
+anna export slides.md              # export to PDF
+```
+
+## Themes
+
+**Dark:** black, night, moon, blood, league (default)
+**Light:** white, beige, sky, serif, simple, solarized
+
+## Keyboard Shortcuts (in presentation)
+
+| Key | Function |
+|-----|----------|
+| Arrow keys | Navigate |
+| Space / N | Next slide |
+| P | Previous |
+| ESC / O | Overview |
+| S | Speaker notes |
+| F | Fullscreen |
+| B / . | Pause (black screen) |
+
+## Embed Mode (Web Components)
+
+```html
+<script src="https://unpkg.com/anna.js/js/anna-embed.js"></script>
+
+<anna-slide theme="moon">
+  ## Hello World
+  - Point 1
+  - Point 2
+</anna-slide>
+
+<anna-deck theme="night">
+  <anna-slide># Slide 1</anna-slide>
+  <anna-slide># Slide 2</anna-slide>
+</anna-deck>
+```