lumina-slides 8.0.0 → 8.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +71 -84
  2. package/dist/layout-embedded.json +65 -0
  3. package/dist/lumina-slides.js +1208 -1061
  4. package/dist/lumina-slides.umd.cjs +3 -3
  5. package/dist/style.css +1 -1
  6. package/package.json +19 -5
package/README.md CHANGED
@@ -3,24 +3,34 @@
3
3
  <div align="center">
4
4
  <br />
5
5
  <p>
6
- <b>The Declarative Presentation Engine for the Modern Web</b>
6
+ <b>The Interface Layer for the Agentic Era</b>
7
7
  </p>
8
8
  <p>
9
- Create cinematic, timeline-driven presentations using simple JSON and the full power of Vue 3 + GSAP.
9
+ The first presentation engine designed for <b>LLMs</b>. Turn JSON into cinematic, interactive experiences.
10
10
  </p>
11
11
  <br />
12
12
  </div>
13
13
 
14
- **Lumina Engine** is a high-performance, drop-in library that turns declarative JSON definitions into GPU-accelerated, interactive slide decks. It is designed for developers who want to build immersive storytelling experiences without getting bogged down in animation logic.
14
+ **Lumina Engine** is a high-performance, declarative library that enables AI agents and LLMs to generate professional, interactive UI and slide decks by simply outputting JSON. It bridges the gap between text generation and visual storytelling, offering deterministic, GPU-accelerated rendering without the hallucination of pixel-generation.
15
+
16
+ > [!IMPORTANT] > **Building an Agent?**
17
+ > Read the complete **[Lumina for Agents Guide](./AGENTS.md)** to learn about Streaming, Auto-Layouts, and Token Optimization.
18
+
19
+ ## 🤖 Why for LLMs?
20
+
21
+ Traditional UI libraries require understanding complex component trees, CSS modules, and state management. Lumina abstracts this into a **single, flat JSON schema**.
22
+
23
+ - **structured_output Friendly**: Designed to match the capabilities of models like GPT-4o, Claude 3.5 Sonnet, and Gemini Pro.
24
+ - **Hallucination Proof**: The renderer handles the "how", the LLM only cares about the "what".
25
+ - **Zero Config**: No build steps or bundler configuration needed to generate visual content dynamically.
15
26
 
16
27
  ## ✨ Features
17
28
 
18
- - **� Declarative First**: Define your entire deck structure, content, and flow in a single JSON object.
19
- - **🚀 Performance Core**: Built on Vue 3's Composition API for reactivity and GSAP for buttery smooth standard-compliant animations.
20
- - **🎨 Cinematic Layouts**: Comes with 5+ responsive, production-ready layouts (`statement`, `timeline`, `features`, `half`, `steps`).
21
- - **🛡️ Type Safe**: Written in 100% strict TypeScript.
22
- - **🔌 Event Driven**: Hook into every slide change, interaction, and state update with a robust event system.
23
- - **� Theming API**: Runtime CSS variable generation for instant branding (Dark/Light mode ready).
29
+ - **📄 JSON-First Architecture**: Define entire decks, including content, styling, and flow, in one serializable object.
30
+ - **⚡ Reactive & Performant**: Built on Vue 3 + GSAP for 60fps animations even on mobile.
31
+ - **🎨 Cinematic Layouts**: "Pro" layouts (`timeline`, `statement`, `features`) that look good by default.
32
+ - **🛡️ Type Safe**: Full TypeScript support with exported types for your AI system prompts.
33
+ - **🔌 Event Driven**: Hook into every user interaction to feed state back to your agent.
24
34
 
25
35
  ## 📦 Installation
26
36
 
@@ -28,106 +38,83 @@
28
38
  npm install lumina-slides gsap
29
39
  ```
30
40
 
31
- ## ⚡ Quick Start
41
+ ## ⚡ Quick Start for Agents
42
+
43
+ ### 1. The "System Prompt"
44
+
45
+ Your agent generates this structure:
46
+
47
+ ```json
48
+ {
49
+ "meta": { "title": "Quarterly Review" },
50
+ "slides": [
51
+ {
52
+ "type": "statement",
53
+ "title": "Q4 Performance",
54
+ "subtitle": "Exceeding expectations.",
55
+ "meta": { "variant": "gradient" }
56
+ },
57
+ {
58
+ "type": "features",
59
+ "title": "Key Metrics",
60
+ "features": [
61
+ {
62
+ "title": "Growth",
63
+ "description": "+145% YoY",
64
+ "icon": "trending-up"
65
+ },
66
+ { "title": "Retention", "description": "98% Renewal", "icon": "users" }
67
+ ]
68
+ }
69
+ ]
70
+ }
71
+ ```
32
72
 
33
- ### 1. Initialize the Engine
73
+ ### 2. The Engine Renders
34
74
 
35
- Mount the engine to any DOM element.
75
+ You pass that JSON directly to Lumina.
36
76
 
37
77
  ```typescript
38
78
  import { Lumina } from "lumina-slides";
39
79
  import "lumina-slides/style.css";
40
80
 
41
- const engine = new Lumina("#app", {
42
- theme: {
43
- colors: { primary: "#6366f1" }, // Customize your brand color
44
- },
45
- });
46
- ```
81
+ const engine = new Lumina("#app");
47
82
 
48
- ### 2. Load Your Deck
83
+ // Imagine this comes from your LLM stream
84
+ const llmOutput = await agent.generatePresentation();
49
85
 
50
- Pass your declarative JSON structure to the `load` method.
51
-
52
- ```typescript
53
- engine.load({
54
- meta: { title: "Project Roadmap" },
55
- slides: [
56
- {
57
- type: "statement",
58
- title: "Welcome to Lumina",
59
- subtitle: "Declarative presentations for the web.",
60
- meta: { orbColor: "#4f46e5" },
61
- },
62
- {
63
- type: "timeline",
64
- title: "History",
65
- timeline: [
66
- { date: "2023", title: "Inception", description: "Project started." },
67
- { date: "2024", title: "Launch", description: "v1.0 Release." },
68
- ],
69
- },
70
- ],
71
- });
86
+ engine.load(llmOutput);
72
87
  ```
73
88
 
74
89
  ## 🧩 Built-in Layouts
75
90
 
76
- Lumina comes with a set of "Pro" layouts out of the box. Just specify the `type` property in your slide object.
91
+ Lumina provides semantic layout types that LLMs can easily select based on context.
77
92
 
78
- | Type | Description | Key Props |
79
- | :-------------- | :--------------------------------------------------------- | :--------------------------------- |
80
- | **`statement`** | High-impact text focus. Perfect for covers and quotes. | `title`, `subtitle`, `tag` |
81
- | **`half`** | Split layout with image on one side, content on the other. | `image`, `imageSide`, `paragraphs` |
82
- | **`features`** | Responsive grid of cards with icons. | `features` (array of cards) |
83
- | **`timeline`** | Vertical interactive chronological list. | `timeline` (array of events) |
84
- | **`steps`** | Sequential process steps with numbers. | `steps` (array of steps) |
93
+ | Type | Best Used For... |
94
+ | :-------------- | :--------------------------------------------------- |
95
+ | **`statement`** | Big ideas, quotes, titles. Great for "cover" slides. |
96
+ | **`half`** | Comparisons, text + image context. |
97
+ | **`features`** | Lists of benefits, KPIs, or grid items. |
98
+ | **`timeline`** | Chronological events, roadmaps, history. |
99
+ | **`steps`** | Tutorials, flows, numbered processes. |
85
100
 
86
101
  ## 📚 API Reference
87
102
 
103
+ ### `engine.load(deck: DeckDefinition)`
104
+
105
+ Loads a new deck. This is reactive - calling it again with new data (e.g. streaming chunks) will update the view seamlessly.
106
+
88
107
  ### `engine.on(event, callback)`
89
108
 
90
- Listen to engine events to build custom navigational controls or analytics.
109
+ Listen to interactions to create loops where the user's action prompts the AI for the next step.
91
110
 
92
111
  ```typescript
93
- // Slide Change Event
94
- engine.on("slideChange", (payload) => {
95
- console.log(`Current Slide Index: ${payload.index}`);
96
- console.log("Active Slide Data:", payload.slide);
97
- });
98
-
99
- // User Actions (Buttons, Links)
100
112
  engine.on("action", (payload) => {
101
- if (payload.type === "cta-click") {
102
- window.open(payload.value, "_blank");
103
- }
113
+ // Feed user interaction back to the AI
114
+ agent.send(`User clicked on button: ${payload.value}`);
104
115
  });
105
116
  ```
106
117
 
107
- ### Configuration Options
108
-
109
- Pass these to the constructor `new Lumina(selector, options)`.
110
-
111
- ```typescript
112
- interface LuminaOptions {
113
- /** Enable infinite looping of slides */
114
- loop?: boolean;
115
- /** Enable keyboard arrow navigation */
116
- keyboard?: boolean;
117
- /** UI Visibility Settings */
118
- ui?: {
119
- showProgressBar?: boolean;
120
- showControls?: boolean;
121
- showSlideCount?: boolean;
122
- };
123
- /** Animation Tunings */
124
- animation?: {
125
- stagger?: number; // Time between element entries
126
- durationIn?: number; // Slide entry speed
127
- };
128
- }
129
- ```
130
-
131
118
  ## 📄 License
132
119
 
133
120
  MIT
package/dist/layout-embedded.json ADDED
@@ -0,0 +1,65 @@
1
+ {
2
+ "meta": {
3
+ "title": "Layout: Embedded Widget"
4
+ },
5
+ "slides": [
6
+ {
7
+ "type": "statement",
8
+ "sizing": "container",
9
+ "meta": {
10
+ "orbColor": "#ec4899"
11
+ },
12
+ "tag": "Widget Mode",
13
+ "title": "Interactive",
14
+ "subtitle": "Swipe or click to navigate deeply."
15
+ },
16
+ {
17
+ "type": "timeline",
18
+ "sizing": "container",
19
+ "meta": {
20
+ "orbColor": "#ec4899"
21
+ },
22
+ "title": "Widget Mode",
23
+ "subtitle": "This slide adapts to its container.",
24
+ "timeline": [
25
+ {
26
+ "date": "Step 1",
27
+ "title": "Init",
28
+ "description": "Engine detects container size."
29
+ },
30
+ {
31
+ "date": "Step 2",
32
+ "title": "Render",
33
+ "description": "Content flows naturally without forcing 100vh."
34
+ },
35
+ {
36
+ "date": "Step 3",
37
+ "title": "Embed",
38
+ "description": "Perfect for dashboards and docs."
39
+ }
40
+ ]
41
+ },
42
+ {
43
+ "type": "features",
44
+ "sizing": "container",
45
+ "title": "Compact Power",
46
+ "features": [
47
+ {
48
+ "title": "Responsive",
49
+ "desc": "Adapts to any div",
50
+ "icon": "fa-compress"
51
+ },
52
+ {
53
+ "title": "Interactive",
54
+ "desc": "Full touch support",
55
+ "icon": "fa-hand-pointer"
56
+ },
57
+ {
58
+ "title": "Fast",
59
+ "desc": "Hardware accelerated",
60
+ "icon": "fa-bolt"
61
+ }
62
+ ]
63
+ }
64
+ ]
65
+ }