@cuppacue/cli 0.1.0

package/dist/ai/images.js

@@ -0,0 +1,71 @@
+function getProvider() {
+    const pexelsKey = process.env.PEXELS_API_KEY;
+    if (pexelsKey)
+        return { name: "pexels", key: pexelsKey };
+    const unsplashKey = process.env.UNSPLASH_ACCESS_KEY;
+    if (unsplashKey)
+        return { name: "unsplash", key: unsplashKey };
+    return null;
+}
+/**
+ * Resolve placeholder images to real photos via Pexels or Unsplash.
+ * Checks PEXELS_API_KEY first, then UNSPLASH_ACCESS_KEY.
+ * When neither is set, placeholders remain and render nicely in the player.
+ */
+export async function resolveImages(cup) {
+    const placeholders = [];
+    for (const scene of cup.content?.scenes ?? []) {
+        for (const el of scene.elements ?? []) {
+            if (el.type === "image" && el.placeholder) {
+                placeholders.push(el);
+            }
+        }
+    }
+    if (placeholders.length === 0)
+        return;
+    const provider = getProvider();
+    if (!provider) {
+        console.log("Tip: Set PEXELS_API_KEY or UNSPLASH_ACCESS_KEY to resolve image placeholders to real photos");
+        return;
+    }
+    await Promise.allSettled(placeholders.map((img) => resolveOne(img, provider)));
+}
+function sanitizeQuery(alt) {
+    return alt.replace(/[^\w\s-]/g, " ").trim().slice(0, 100);
+}
+async function resolveOne(img, provider) {
+    const query = sanitizeQuery(img.alt ?? "abstract background");
+    if (provider.name === "pexels") {
+        await resolveViaPexels(img, query, provider.key);
+    }
+    else {
+        await resolveViaUnsplash(img, query, provider.key);
+    }
+}
+async function resolveViaPexels(img, query, apiKey) {
+    const url = `https://api.pexels.com/v1/search?query=${encodeURIComponent(query)}&per_page=1&orientation=landscape`;
+    const res = await fetch(url, {
+        headers: { Authorization: apiKey },
+    });
+    if (!res.ok)
+        return;
+    const data = (await res.json());
+    if (data.photos?.length > 0) {
+        img.src = data.photos[0].src.large2x;
+        img.placeholder = false;
+    }
+}
+async function resolveViaUnsplash(img, query, accessKey) {
+    const url = `https://api.unsplash.com/search/photos?query=${encodeURIComponent(query)}&per_page=1&orientation=landscape`;
+    const res = await fetch(url, {
+        headers: { Authorization: `Client-ID ${accessKey}` },
+    });
+    if (!res.ok)
+        return;
+    const data = (await res.json());
+    if (data.results?.length > 0) {
+        img.src = data.results[0].urls.regular;
+        img.placeholder = false;
+    }
+}
+//# sourceMappingURL=images.js.map

package/dist/ai/images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"images.js","sourceRoot":"","sources":["../../src/ai/images.ts"],"names":[],"mappings":"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"}

package/dist/ai/index.d.ts

@@ -0,0 +1,7 @@
+export { FORMAT_SCHEMA } from "./schema.js";
+export { EXAMPLE_CUPFILE } from "./example.js";
+export { buildGeneratePrompt, buildRefinePrompt } from "./prompt.js";
+export { createClient, callClaude } from "./client.js";
+export { generate } from "./generate.js";
+export { refine } from "./refine.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/ai/index.js

@@ -0,0 +1,7 @@
+export { FORMAT_SCHEMA } from "./schema.js";
+export { EXAMPLE_CUPFILE } from "./example.js";
+export { buildGeneratePrompt, buildRefinePrompt } from "./prompt.js";
+export { createClient, callClaude } from "./client.js";
+export { generate } from "./generate.js";
+export { refine } from "./refine.js";
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/ai/prompt.d.ts

@@ -0,0 +1,10 @@
+import type { CupFile } from "@cuppacue/format";
+export declare function buildGeneratePrompt(userPrompt: string, sourceContent?: string): {
+    system: string;
+    user: string;
+};
+export declare function buildRefinePrompt(currentCupFile: CupFile, instruction: string): {
+    system: string;
+    user: string;
+};
+//# sourceMappingURL=prompt.d.ts.map

package/dist/ai/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/ai/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAuFhD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAoBlC;AAED,wBAAgB,iBAAiB,CAC/B,cAAc,EAAE,OAAO,EACvB,WAAW,EAAE,MAAM,GAClB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAkBlC"}

package/dist/ai/prompt.js

@@ -0,0 +1,119 @@
+import { FORMAT_SCHEMA } from "./schema.js";
+import { EXAMPLE_CUPFILE } from "./example.js";
+const SYSTEM_ROLE = `You are an expert presentation designer. You create visually appealing, well-structured presentations in the CuppaCue JSON format.`;
+const GENERATE_GUIDELINES = `
+## Guidelines
+- Create 5-8 scenes (slides) unless the user specifies otherwise
+- Keep text concise — bullet points over paragraphs
+- ALWAYS set layout on every scene — never rely on position fields
+- Do NOT set position fields — the layout engine handles positioning automatically
+- Use meaningful animations: fadeInUp for titles, revealDown for code, fadeInLeft for lists, bounceIn for cards, zoomIn for images/charts/stats, blurIn for mermaid/captions, slideUp for terminals
+- Add "pause" markers on complex scenes (code blocks, dense content) so presenters can explain
+- Use real language tags on code blocks (e.g. "typescript", "python", not "code")
+- Give every element a unique, descriptive ID (e.g. "intro-title", "arch-code")
+- Include a timesheet with staggered animations (400ms apart typically)
+- Scene duration should accommodate all animations plus 1500ms padding
+- Set manifest.sceneCount to match the actual number of scenes
+
+## Slide Structure
+- Start with a title slide using "intro" layout (H1 title + subtitle + caption)
+- Use "section" layout for topic dividers between major sections
+- Use "header-body" for most content slides (lists, tables, cards, stats)
+- Use "split" for text + code/image side-by-side, "code-focus" for code walkthroughs
+- Use "quote" for key quotes or value propositions
+- End with a closing slide using "end" or "intro" layout
+- Use varied transitions: "fade" for section dividers, "slide" for content, "zoom" for emphasis, "morph" for smooth flow, "reveal" for dramatic reveals, "flip" for fun/playful
+
+## Rich Elements
+- Use CardsElement for feature overviews (3-4 cards with icon/title/description)
+- Use StatsElement for key metrics (3-4 stats with value + label)
+- Use TerminalElement for CLI demos (command + output pairs)
+- Use TableElement for comparisons or structured data
+- Use MermaidElement for architecture or flow diagrams (flowchart/sequence/graph syntax)
+- Use ChartElement for data visualization (bar/line/pie with labels + datasets)
+- Place rich elements in "header-body" layout with a heading above
+
+## Images
+- Include 1-3 ImageElements per presentation where visuals add value
+- Use placeholder: true and src: "placeholder" — real images are resolved automatically
+- Write descriptive alt text for image search (e.g. "modern server room with blue lighting")
+- Place images in "header-body", "split", "image-left", or "image-right" layouts
+
+## References
+- Add a "References" or "Learn More" scene before the closing slide
+- Use a ListElement with 3-6 relevant URLs (docs, articles, repos)
+- Use layout "header-body" with a heading
+
+## Theme Selection
+- Pick a built-in theme that matches the presentation topic and tone:
+  - "dark" — technical talks, developer content (default)
+  - "light" — general purpose, business
+  - "minimal" — startup pitches, product demos, clean aesthetic
+  - "corporate" — business presentations, proposals
+  - "elegant" — creative talks, storytelling, design
+  - "bold" — keynotes, marketing, announcements
+  - "forest" — nature, sustainability, green topics
+  - "ocean" — technology, data, research
+- Use the theme colors/fonts from the built-in preset — do not invent custom colors
+- Auto-select typography preset matching the theme:
+  - "elegant" theme → elegant typography (serif headings)
+  - "bold" theme → bold typography (heavy weights)
+  - "minimal" theme → minimal typography (light weights)
+  - Others → default typography (no typography field needed)
+
+## Speaker Notes
+- Add brief speaker notes to scenes with complex content (code blocks, dense lists, key arguments)
+- Notes help presenters remember key talking points — keep them concise (1-3 sentences)
+- Set the "notes" field on scenes, not on elements
+- Title and closing slides typically don't need notes
+`.trim();
+const REFINE_GUIDELINES = `
+## Guidelines
+- Modify the existing presentation — do not regenerate from scratch
+- Preserve the parts the user did not ask to change
+- Keep the same theme unless asked to change it
+- Maintain valid element IDs and scene IDs
+- ALWAYS set layout on every scene — never rely on position fields
+- Do NOT set position fields — the layout engine handles positioning automatically
+- Update the timesheet to match any content changes
+- Update manifest.sceneCount if scenes were added or removed
+- When adding images, use placeholder: true and src: "placeholder" with descriptive alt text
+- A references scene with URLs is recommended if not already present
+`.trim();
+export function buildGeneratePrompt(userPrompt, sourceContent) {
+    const system = `${SYSTEM_ROLE}
+
+${FORMAT_SCHEMA}
+
+## Example CupFile
+\`\`\`json
+${EXAMPLE_CUPFILE}
+\`\`\`
+
+${GENERATE_GUIDELINES}
+
+Respond with ONLY valid JSON — a single CupFile object. No explanation, no markdown fences.`;
+    let user = userPrompt;
+    if (sourceContent) {
+        user = `${userPrompt}\n\n## Source Content\n${sourceContent}`;
+    }
+    return { system, user };
+}
+export function buildRefinePrompt(currentCupFile, instruction) {
+    const system = `${SYSTEM_ROLE}
+
+${FORMAT_SCHEMA}
+
+${REFINE_GUIDELINES}
+
+Respond with ONLY valid JSON — the complete modified CupFile object. No explanation, no markdown fences.`;
+    const user = `## Current Presentation
+\`\`\`json
+${JSON.stringify(currentCupFile, null, 2)}
+\`\`\`
+
+## Instruction
+${instruction}`;
+    return { system, user };
+}
+//# sourceMappingURL=prompt.js.map

package/dist/ai/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/ai/prompt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,GAAG,oIAAoI,CAAC;AAEzJ,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE3B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,iBAAiB,GAAG;;;;;;;;;;;;CAYzB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,mBAAmB,CACjC,UAAkB,EAClB,aAAsB;IAEtB,MAAM,MAAM,GAAG,GAAG,WAAW;;EAE7B,aAAa;;;;EAIb,eAAe;;;EAGf,mBAAmB;;4FAEuE,CAAC;IAE3F,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,GAAG,GAAG,UAAU,0BAA0B,aAAa,EAAE,CAAC;IAChE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,cAAuB,EACvB,WAAmB;IAEnB,MAAM,MAAM,GAAG,GAAG,WAAW;;EAE7B,aAAa;;EAEb,iBAAiB;;yGAEsF,CAAC;IAExG,MAAM,IAAI,GAAG;;EAEb,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;;;;EAIvC,WAAW,EAAE,CAAC;IAEd,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/ai/refine.d.ts

@@ -0,0 +1,6 @@
+import type { CupFile } from "@cuppacue/format";
+export interface RefineOptions {
+    model?: string;
+}
+export declare function refine(cupFile: CupFile, instruction: string, opts?: RefineOptions): Promise<CupFile>;
+//# sourceMappingURL=refine.d.ts.map

package/dist/ai/refine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine.d.ts","sourceRoot":"","sources":["../../src/ai/refine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAOhD,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,MAAM,CAC1B,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,OAAO,CAAC,CAiBlB"}

package/dist/ai/refine.js

@@ -0,0 +1,22 @@
+import { validateCupFile } from "@cuppacue/format";
+import { buildRefinePrompt } from "./prompt.js";
+import { callClaude } from "./client.js";
+import { extractJson, autoFix } from "./generate.js";
+import { resolveImages } from "./images.js";
+export async function refine(cupFile, instruction, opts = {}) {
+    const { system, user } = buildRefinePrompt(cupFile, instruction);
+    const response = await callClaude(system, user, opts.model);
+    const jsonStr = extractJson(response);
+    const data = JSON.parse(jsonStr);
+    const cup = autoFix(data);
+    await resolveImages(cup);
+    const result = validateCupFile(cup);
+    if (!result.valid) {
+        console.error("Warning: Refined presentation has validation issues:");
+        for (const err of result.errors) {
+            console.error(`  ${err.path}: ${err.message}`);
+        }
+    }
+    return cup;
+}
+//# sourceMappingURL=refine.js.map

package/dist/ai/refine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine.js","sourceRoot":"","sources":["../../src/ai/refine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAM5C,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,OAAgB,EAChB,WAAmB,EACnB,OAAsB,EAAE;IAExB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAA4B,CAAC;IAC5D,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IAEzB,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;QACtE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAChC,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/ai/schema.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Format schema description for the AI system prompt.
+ */
+export declare const FORMAT_SCHEMA: string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/ai/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/ai/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,aAAa,QA+RlB,CAAC"}

package/dist/ai/schema.js

@@ -0,0 +1,292 @@
+/**
+ * Format schema description for the AI system prompt.
+ */
+export const FORMAT_SCHEMA = `
+# CuppaCue Presentation Format (.cup)
+
+A presentation is a CupFile JSON object with four top-level keys:
+\`manifest\`, \`content\`, \`timesheet\`, \`theme\`.
+
+## Manifest
+\`\`\`
+{
+  "version": 1,             // always 1
+  "title": string,           // presentation title
+  "author"?: string,
+  "description"?: string,
+  "sceneCount": number       // must match content.scenes.length
+}
+\`\`\`
+
+## Content
+\`\`\`
+{
+  "scenes": Scene[]
+}
+\`\`\`
+
+### Scene
+\`\`\`
+{
+  "id": string,              // unique scene ID (e.g. "intro", "problem")
+  "elements": Element[],
+  "layout"?: LayoutType,
+  "background"?: string,     // CSS color, gradient, or image path (e.g. "resources/images/hero.jpg")
+  "transition"?: { "type": "fade" | "slide" | "none" | "zoom" | "reveal" | "flip" | "morph", "duration"?: number },
+  "class"?: string,          // extra CSS class for custom styling
+  "notes"?: string,          // speaker notes (not rendered on slide, shown in presenter view)
+  "accentBar"?: { "color": string, "position"?: "top" | "bottom", "height"?: string },
+                             // thin colored bar at top/bottom of slide for visual rhythm
+  "sceneTemplate"?: string,  // scene template ID (e.g. "tech-talk/intro") — overrides layout with designed composition
+  "templateData"?: Record<string, string>
+                             // template chrome data, e.g. { "badge": "TECH TALK", "footerKeywords": "Fast · Reliable" }
+}
+\`\`\`
+
+### Layout (ALWAYS SET ON EVERY SCENE)
+
+13 layouts available. Scene-level layout controls element positioning via CSS Grid:
+
+**Title layouts:**
+- **"intro"** — Vertically centered, left-aligned. Optional image in right column. Best for: opening title slides.
+- **"section"** — Large centered heading with accent underline. Best for: section dividers between topics.
+- **"end"** — Same as intro (left-aligned, optional right image). Best for: closing/thank-you slides.
+- **"quote"** — Centered, large italic text with decorative quote mark. Best for: key quotes, value propositions.
+
+**Content layouts:**
+- **"center"** — All elements centered. Best for: single quotes, key takeaways.
+- **"header-body"** — Heading on top, content below. Best for: most content slides (lists, tables, cards, stats).
+- **"split"** — Two columns with optional header. Text/lists go left, code/images go right. Best for: comparisons, text + code.
+- **"code-focus"** — Small heading + large code area. Best for: code walkthroughs, demos.
+
+**Media layouts:**
+- **"image-left"** — Image on left (2fr), text on right (3fr). Best for: visual + explanation.
+- **"image-right"** — Text on left (3fr), image on right (2fr). Best for: explanation + visual.
+- **"image-full"** — Full-bleed background image with text overlay at bottom. Best for: dramatic hero images.
+
+**Special layouts:**
+- **"full"** — Single area filling viewport. Best for: large diagrams, charts.
+- **"blank"** — No padding, complete custom control.
+
+When using a layout, elements are automatically placed into grid slots based on their type/role.
+You do NOT need to set position fields when using a layout.
+
+**Suggested patterns:**
+- Title slide → "intro"
+- Section divider → "section"
+- Content with heading + bullets/table → "header-body"
+- Content with heading + cards/stats → "header-body"
+- Code with explanation → "split" or "code-focus"
+- Key quote or value proposition → "quote"
+- Closing/thanks slide → "end" or "intro"
+
+### Background
+
+The \`background\` field accepts:
+- CSS colors: \`"#1a1a2e"\`, \`"rgb(26,26,46)"\`
+- CSS gradients: \`"linear-gradient(135deg, #0f172a, #1e293b)"\`
+- Image paths: \`"resources/images/hero.jpg"\` (resolved from .cup bundle)
+
+Background images display as \`background-size: cover; background-position: center\`.
+Combine with text elements for dramatic effect on "intro", "quote", or "section" layouts.
+
+### Transition
+
+Per-scene transitions control animation between slides:
+- **"fade"** (default) — Cross-fade between scenes (400ms default)
+- **"slide"** — Direction-aware slide (forward: left-to-right, backward: right-to-left)
+- **"zoom"** — Zoom in new scene, zoom out old scene
+- **"reveal"** — Clip-path wipe left-to-right
+- **"flip"** — 3D card flip (rotateY)
+- **"morph"** — Scale + blur transition (smooth, modern)
+- **"none"** — Instant swap
+
+Example: \`"transition": { "type": "zoom", "duration": 500 }\`
+
+### Element Types
+
+All elements have: \`id\` (unique string), \`type\`, optional \`position\`, optional \`style\`.
+
+**TextElement**: \`{ type: "text", content: string, role?: "title" | "subtitle" | "heading" | "body" | "caption" | "footer" }\`
+  - Use "footer" role for persistent slide footer text (company name, date, etc.)
+  - Content supports inline HTML: \`<strong>\`, \`<em>\`, \`<code>\`, \`<del>\`, \`<a href="...">\`
+
+**CodeElement**: \`{ type: "code", content: string, language: string, highlightLines?: number[] }\`
+
+**ListElement**: \`{ type: "list", items: string[], ordered?: boolean }\`
+  - Items support inline HTML
+
+**ImageElement**: \`{ type: "image", src: string, alt?: string, width?: string, height?: string, placeholder?: boolean }\`
+
+**TableElement**: \`{ type: "table", headers: string[], rows: string[][], alignments?: ("left" | "center" | "right" | null)[] }\`
+  - Cells support inline HTML
+
+**DividerElement**: \`{ type: "divider" }\`
+
+**CardsElement**: \`{ type: "cards", cards: [{ title: string, icon?: string, description?: string, accent?: string }] }\`
+  - accent: optional hex color for a colored top border stripe (e.g. "#38bdf8"). Use different accents per card to differentiate features.
+  - Icons: "code", "brain", "shield", "globe", "zap", "layout", "lock", "terminal", "sparkles", "search", "settings", "link", "target", "layers", "cpu", "wifi", "git-branch", "message-circle", "package", "trending-up", "activity", "download", "upload", "alert-triangle", "info", "check-circle", "file-text", "help-circle", "eye", "refresh", "rocket", "star", "heart", "database", "server", "cloud", "key", "bar-chart", "users", "mail", "clock", "arrow-right"
+  - Best in "header-body" layout with a heading
+
+**StatsElement**: \`{ type: "stats", stats: [{ value: string, label: string }] }\`
+  - Animated counters for key metrics
+  - Best in "header-body" layout with a heading
+
+**TerminalElement**: \`{ type: "terminal", lines: [{ type: "command" | "output", text: string }] }\`
+  - Simulated terminal with prompt styling
+  - Best in "split" or "code-focus" layout
+
+**MermaidElement**: \`{ type: "mermaid", definition: string }\`
+  - Mermaid diagram syntax
+  - Best in "full" or "header-body" layout
+
+**ChartElement**: \`{ type: "chart", chartType: "bar" | "line" | "pie", labels: string[], datasets: [{ label: string, data: number[] }] }\`
+  - Chart.js-powered charts
+  - Best in "full" or "header-body" layout
+
+### Position (legacy — only for custom layouts without a layout field)
+\`\`\`
+{
+  "x"?: string,    // e.g. "50%", "8%"
+  "y"?: string,    // e.g. "35%", "50%"
+  "anchor"?: "center" | "top-left" | "top-center" | "top-right" |
+             "center-left" | "center-right" |
+             "bottom-left" | "bottom-center" | "bottom-right",
+  "width"?: string,
+  "maxWidth"?: string   // e.g. "70%", "45%"
+}
+\`\`\`
+Do NOT use position fields when using a layout — the layout engine handles positioning automatically.
+
+### ElementStyle (optional)
+\`\`\`
+{
+  "fontSize"?: string,
+  "color"?: string,
+  "fontWeight"?: string,
+  "fontFamily"?: string,
+  "textAlign"?: string,
+  "opacity"?: number,
+  "padding"?: string
+}
+\`\`\`
+
+## Timesheet
+\`\`\`
+{
+  "timeline": TimelineEntry[],   // one per scene, same order as scenes
+  "defaults"?: { "sceneDuration"?: number, "animationDuration"?: number }
+}
+\`\`\`
+
+### TimelineEntry
+\`\`\`
+{
+  "sceneId": string,         // must match a scene ID
+  "duration": number,        // scene duration in ms
+  "events": TimelineEvent[],
+  "markers"?: Marker[]
+}
+\`\`\`
+
+### TimelineEvent
+\`\`\`
+{
+  "elementId": string,       // must match an element ID in that scene
+  "animation": AnimationName,
+  "at": number,              // start time in ms (relative to scene start)
+  "duration"?: number        // animation duration in ms
+}
+\`\`\`
+
+### AnimationName (one of):
+- \`fadeIn\` — general entrance, good for headings
+- \`fadeOut\` — exit animation
+- \`fadeInUp\` — entrance with upward motion, good for titles and body text
+- \`fadeInDown\` — entrance with downward motion
+- \`fadeInLeft\` — entrance from left, good for lists
+- \`fadeInRight\` — entrance from right, good for side-by-side layouts
+- \`typewriter\` — left-to-right character reveal, good for single-line text
+- \`revealDown\` — top-to-bottom reveal, ideal for code blocks (line-by-line appearance)
+- \`scale\` — scale up entrance, good for emphasis/closing titles
+- \`highlight\` — attention pulse, good for key points
+- \`bounceIn\` — bouncy scale entrance, great for cards and feature highlights
+- \`blurIn\` — blur-to-focus entrance, great for mermaid diagrams and captions
+- \`rotateIn\` — rotation entrance, great for emphasis elements
+- \`slideUp\` — slide from bottom, great for terminal elements
+- \`slideDown\` — slide from top, great for headers
+- \`zoomIn\` — zoom from zero, great for images, charts, and stats
+
+### Marker
+\`\`\`
+{
+  "at": number,              // time in ms
+  "label"?: string,          // optional description
+  "action": "pause" | "auto"
+}
+\`\`\`
+Use "pause" markers on complex scenes (code, many elements) so the presenter can explain.
+
+## Theme
+
+8 built-in themes are available. Pick one by name — use the theme object as shown.
+
+| Theme | Style | Best For |
+|-------|-------|----------|
+| dark | Cyan on dark slate | Technical talks, developer content |
+| light | Blue on white | General purpose, corporate |
+| minimal | Gray on off-white, light weights | Startup pitches, product demos |
+| corporate | Deep blue on white, structured | Business presentations, proposals |
+| elegant | Gold on charcoal, serif headings | Creative talks, storytelling, design |
+| bold | Yellow on black, heavy weights | Keynotes, marketing, announcements |
+| forest | Green on dark green | Nature/sustainability topics |
+| ocean | Teal on deep navy | Technology, data, research |
+
+### Theme Object Structure
+\`\`\`
+{
+  "name": string,            // theme name
+  "colors": {
+    "background": string,    // hex color
+    "foreground": string,
+    "primary": string,
+    "secondary": string,
+    "accent": string,
+    "codeBackground": string,
+    "codeForeground": string
+  },
+  "fonts": {
+    "heading": string,       // CSS font-family
+    "body": string,
+    "code": string
+  },
+  "codeTheme"?: string,      // "vitesse-dark" for dark themes, "vitesse-light" for light themes
+  "typography"?: Typography,  // per-role overrides (see below)
+  "fontImports"?: string[]   // Google Fonts URLs for custom fonts
+}
+\`\`\`
+
+### Typography (optional)
+Per-role overrides for font sizing and style. Available presets: "default", "elegant", "minimal", "bold".
+
+\`\`\`
+{
+  "title"?: TypographyRole,
+  "subtitle"?: TypographyRole,
+  "heading"?: TypographyRole,
+  "body"?: TypographyRole,
+  "caption"?: TypographyRole
+}
+\`\`\`
+
+**TypographyRole**: \`{ fontSize?: string, fontWeight?: string, lineHeight?: string, letterSpacing?: string, textTransform?: "none" | "uppercase" | "lowercase" | "capitalize" }\`
+
+**Preset: "elegant"** — Playfair Display serif headings + Lato body. Use fonts: \`{ heading: "'Playfair Display', Georgia, serif", body: "'Lato', system-ui, sans-serif", code: "'JetBrains Mono', 'Fira Code', monospace" }\` with fontImports: \`["https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;600;700&family=Lato:wght@300;400;700&display=swap"]\`
+
+**Preset: "minimal"** — Inter with lighter weights (300/400), wider letter-spacing.
+
+**Preset: "bold"** — Inter with heavier weights (700/800), tighter letter-spacing, uppercase captions.
+
+**Preset: "default"** — Inter, standard sizes/weights. No typography field needed.
+`.trim();
+//# sourceMappingURL=schema.js.map

package/dist/ai/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/ai/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+R5B,CAAC,IAAI,EAAE,CAAC"}

package/dist/commands/__tests__/backstage.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backstage.test.d.ts.map

package/dist/commands/__tests__/backstage.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backstage.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/backstage.test.ts"],"names":[],"mappings":""}

package/dist/commands/__tests__/backstage.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { applyNavAction } from "../serve.js";
+function state(currentIndex, totalScenes) {
+    return { currentIndex, totalScenes };
+}
+describe("applyNavAction", () => {
+    it("advances to next scene", () => {
+        expect(applyNavAction(state(0, 5), "next")).toBe(1);
+        expect(applyNavAction(state(2, 5), "next")).toBe(3);
+    });
+    it("clamps next at last scene", () => {
+        expect(applyNavAction(state(4, 5), "next")).toBe(4);
+        expect(applyNavAction(state(9, 10), "next")).toBe(9);
+    });
+    it("goes to previous scene", () => {
+        expect(applyNavAction(state(3, 5), "prev")).toBe(2);
+        expect(applyNavAction(state(1, 5), "prev")).toBe(0);
+    });
+    it("clamps prev at first scene", () => {
+        expect(applyNavAction(state(0, 5), "prev")).toBe(0);
+    });
+    it("jumps to a specific scene with goto", () => {
+        expect(applyNavAction(state(0, 10), "goto", 5)).toBe(5);
+        expect(applyNavAction(state(7, 10), "goto", 2)).toBe(2);
+    });
+    it("clamps goto within bounds", () => {
+        expect(applyNavAction(state(0, 5), "goto", 99)).toBe(4);
+        expect(applyNavAction(state(3, 5), "goto", -1)).toBe(0);
+    });
+    it("ignores goto without an index", () => {
+        expect(applyNavAction(state(3, 5), "goto")).toBe(3);
+    });
+    it("returns current index for unknown actions", () => {
+        expect(applyNavAction(state(2, 5), "unknown")).toBe(2);
+    });
+    it("handles single-scene presentation", () => {
+        expect(applyNavAction(state(0, 1), "next")).toBe(0);
+        expect(applyNavAction(state(0, 1), "prev")).toBe(0);
+    });
+    it("handles empty presentation gracefully", () => {
+        expect(applyNavAction(state(0, 0), "next")).toBe(0);
+        expect(applyNavAction(state(0, 0), "prev")).toBe(0);
+    });
+});
+//# sourceMappingURL=backstage.test.js.map

package/dist/commands/__tests__/backstage.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backstage.test.js","sourceRoot":"","sources":["../../../src/commands/__tests__/backstage.test.ts"],"names":[],"mappings":"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"}