Format Reference

Complete reference for the Cuppa Studio .cup format — element types, layouts, and animation system.

Element Types

Cuppa Studio supports 17 element types, each rendered differently by the player:

Text

Standard text content. Roles determine visual styling:

Role	Markdown	Description
`title`	`# Heading`	Large title text
`subtitle`	`### Subheading`	Subtitle under title
`heading`	`## Heading`	Section heading
`body`	Paragraph text	Body text
`caption`	`> Blockquote`	Caption / quote text

Code

Syntax-highlighted code blocks using Shiki. Each theme has a matching code theme for consistent styling.

```typescript
function hello(name: string) {
  return `Hello, ${name}!`;
}
```

Add a filename to show a header bar above the code block:

```typescript [src/api/handler.ts]
export function handle(req: Request) {
  return new Response("OK");
}
```

Add line highlights for code stepping:

```typescript {1-3,5}
const server = createServer();
server.listen(8080);
console.log("Ready");

server.on("request", handle);
```

Highlighted lines create pause markers — click to step through code groups.

List

Bullet or numbered lists with animated reveal:

- First item
- Second item
- Third item

1. Ordered item one
2. Ordered item two

Inside scene templates, lists render as designed card rows with multi-color accents. Use the two-line pattern for richer items:

- **Feature Name** — Description of what it does
- **Another Feature** — More details here

Table

Standard markdown tables with alignment:

| Feature | Status |
| :--- | :---: |
| Markdown | Done |
| AI | Done |

Tables with 3 or more columns get styled headers with per-column accent colors automatically.

Highlight specific rows with a comment directive (1-based row indices):

<!-- highlight: 2,4 -->
| Service | Latency | Status |
| :--- | :---: | :---: |
| API | 12ms | OK |
| Auth | 340ms | Slow |
| DB | 8ms | OK |
| Cache | 280ms | Slow |

Image

Images from local paths or URLs:

![Alt text](./images/diagram.png)

For more control, use the image fenced block:

```image
src: resources/screenshot.png
alt: Dashboard view
caption: The main dashboard
fit: contain
rounded: true
```

Properties: src, alt, caption, fit (contain | cover), rounded (true | false).

Images Gallery

Multiple images in a responsive grid:

```images
columns: 3
- src: resources/img1.jpg
  caption: First image
- src: resources/img2.jpg
  caption: Second image
- src: resources/img3.jpg
  caption: Third image
```

Terminal

Command-line simulations with command/output distinction:

```terminal
$ npm install mycuppa
  added 0 dependencies
$ mycuppa build slides.md
  Built 5 scenes → slides.cup
```

Set a custom prompt with the prompt: directive on the first line:

```terminal
prompt: root@server:~#
root@server:~# systemctl status nginx
  Active: running (since Mon)
```

Add colored output using inline color tags:

```terminal
$ mycuppa validate slides.cup
  [green]✓ manifest valid[/green]
  [green]✓ 8 scenes parsed[/green]
  [red]✗ missing image: hero.png[/red]
  [yellow]⚠ scene 3 has no title[/yellow]
```

Available colors: [green], [red], [yellow], [cyan], [dim].

Cards

Card grid layout for features or highlights. Each card supports accent colors, code snippets, and images:

```cards
columns: 2
- title: Fast
  icon: zap
  desc: Sub-100ms builds
  accent: "#38bdf8"

- title: Simple
  icon: code
  desc: Just markdown
  accent: "#34d399"
  code: server.listen(3000)
  codeLanguage: javascript
```

Card properties:

Property	Description
`title`	Card heading (required)
`icon`	Icon name from the built-in icon set
`desc`	Description text — supports HTML (`<br>` for line breaks, `<br>•` for bullet lists)
`accent`	Left border color (hex, e.g. `"#38bdf8"`)
`code`	Code snippet shown at bottom of card. Use `code: \|` for multi-line
`codeLanguage`	Language for syntax highlighting (e.g. `swift`, `kotlin`)
`image`	Image path shown at bottom of card

Use columns: N (1–4) on the first line to control the grid layout.

Stats

Key metrics display:

```stats
- 85 KB | Player Bundle
- <100ms | Build Time
- 346 | Tests Passing
```

Mermaid

Diagrams via Mermaid syntax:

```mermaid
graph LR
  A[Markdown] --> B[Compiler]
  B --> C[.cup File]
  C --> D[Player]
```

Chart

Data visualizations via Chart.js:

```chart
type: bar
labels: [Q1, Q2, Q3, Q4]
datasets:
  - label: Revenue
    data: [10, 25, 40, 60]
```

Flow

Progressive flow diagrams that reveal nodes step-by-step with pause markers:

```flow
direction: LR
[input] Raw Data
[process] Transform
[output] Results
input --> process : clean
process --> output : validate
```

Nodes are defined with [id] Label. Edges use from --> to : label. Direction can be LR (left-right) or TD (top-down). Each node reveals progressively with click-to-advance.

Callout

Styled callout boxes for tips, warnings, and important information:

```callout:info
Use `mycuppa serve --watch` for live reload during development.
```

```callout:warning
This will overwrite existing files in the output directory.
```

```callout:tip
Combine `--from` with `--refine` to iteratively improve AI output.
```

```callout:danger
Never commit your API key to source control.
```

Four types: info (blue), warning (amber), tip (green), danger (red). Each has a matching icon and color scheme.

API Endpoint

Display REST API endpoints with method badges, parameters, and response examples:

```api
POST /api/v2/inventory
Create or update inventory records in bulk.

name | type | required | description
sku | string | yes | Product SKU identifier
quantity | int | yes | Stock quantity
warehouse | string | no | Warehouse code (default: "primary")

Response (201 Created):
json
{ "updated": 3, "errors": [] }
```

Methods: GET, POST, PUT, PATCH, DELETE — each styled with a distinct color badge.

File Tree

Directory structure visualization with box-drawing characters:

```tree
root: payment-service/
src/
  handlers/
    *checkout.ts
    refund.ts
  models/
    order.ts
  index.ts
tests/
package.json
```

Indent with 2 spaces for nesting. Prefix with * to highlight a file. Trailing / marks directories. The root: directive sets the tree label.

Diff

Code diffs with line-by-line added/removed highlighting:

```diff
- const cache = new Map();
- function getUser(id) {
+ const cache = new LRUCache({ max: 1000 });
+ async function getUser(id) {
    if (cache.has(id)) return cache.get(id);
-   const user = db.query(id);
+   const user = await db.query(id);
    cache.set(id, user);
    return user;
  }
```

Lines starting with + show in green, - in red. Unchanged lines display normally.

Timeline

Horizontal or vertical timelines for milestones and chronological events:

```timeline
direction: vertical
- label: Incident Detected
  date: 14:32 UTC
  desc: Monitoring alerts fire for elevated error rates
  color: "#ef4444"

- label: Root Cause Found
  date: 14:58 UTC
  desc: Bad config deployed to payment-service
  color: "#f59e0b"

- label: Fix Deployed
  date: 15:15 UTC
  desc: Config rollback and service restart
  color: "#22c55e"
```

Direction: horizontal (default) or vertical. Each item supports label, date, desc, icon, and color.

Divider

A visual separator between elements on the same slide.

Layouts

Cuppa Studio auto-detects the best layout for each slide, but you can override with the layout directive:

Category	Layout	Use Case
Title	`intro`	Opening slide with title + subtitle
Title	`section`	Section divider
Title	`end`	Closing slide
Title	`quote`	Centered blockquote
Content	`center`	Centered content
Content	`header-body`	Heading + body content
Content	`split`	Two-column layout
Content	`code-focus`	Code block prominent
Media	`image-left`	Image on left, text right
Media	`image-right`	Image on right, text left
Media	`image-full`	Full-bleed image background
Media	`image-grid`	Responsive grid of images (auto-detected with 2+ images)
Special	`full`	Edge-to-edge content
Special	`blank`	Empty canvas

Setting Layouts

Two equivalent ways to set a layout:

---
layout: image-grid
---
![](photo1.jpg)
![](photo2.jpg)

Or using an HTML comment directive (also works for class, background, transition):

<!-- layout: image-grid -->
![](photo1.jpg)
![](photo2.jpg)

When a directive comment appears mid-slide, it automatically starts a new scene.

Image Grid

The image-grid layout displays 1+ images in a responsive horizontal row. Auto-detected when a slide has 2 or more images.

---
layout: image-grid
---
![Home Screen](resources/home.png)
![Settings](resources/settings.png)
![Profile](resources/profile.png)

Add class: vertical for a single-column stack:

---
layout: image-grid
class: vertical
---
![](resources/before.png)
![](resources/after.png)

Transitions

Control how slides transition:

Transition	Description
`fade`	Cross-fade between slides (default)
`slide`	Direction-aware slide animation
`zoom`	Zoom in/out transition
`reveal`	Reveal with clip-path wipe
`flip`	3D flip between slides
`morph`	Morph transition with scale and rotation
`none`	Instant switch

Animations

Elements are automatically animated based on their type. Available animation names:

Animation	Description
`fadeIn`	Fade in from transparent
`fadeOut`	Fade out to transparent
`fadeInUp`	Fade in while sliding up
`fadeInDown`	Fade in while sliding down
`fadeInLeft`	Fade in from the left
`fadeInRight`	Fade in from the right
`slideUp`	Slide up from below
`slideDown`	Slide down from above
`zoomIn`	Zoom in from small with bounce
`bounceIn`	Scale up with elastic bounce
`blurIn`	Fade in with blur-to-sharp
`typewriter`	Character-by-character reveal
`revealDown`	Reveal from top to bottom (code blocks)
`scale`	Scale up from zero
`highlight`	Highlight background pulse
`rotateIn`	Rotate in from off-angle
`codeStep`	Step through highlighted code line groups
`chartStep`	Reveal chart datasets one at a time
`cardStep`	Reveal cards one at a time (Auto Drive only)
`flowReveal`	Progressively reveal flow diagram nodes

Layout Modifiers

Fine-tune element sizing and behavior with {...} modifiers on fenced code blocks. AI handles most cases automatically — use modifiers only when you need manual adjustment.

Element Modifiers

Add modifiers after the language/type on the opening fence line:

```cards {stepping: false, gap: compact}
columns: 2
- title: Feature A
  ...
```

```swift [ViewModel.swift] {fontSize: small}
class UserViewModel: ObservableObject {
    ...
}
```

Modifier	Values	Description
`fontSize`	`small` · `normal` · `large`	Text/code size — use `small` for dense code
`stepping`	`true` · `false`	Enable/disable step-through animation
`weight`	0–5	Space allocation priority (higher = more space)
`gap`	`compact` · `normal` · `spacious`	Internal spacing between sub-items
`padding`	`none` · `compact` · `normal` · `spacious`	Internal padding
`height`	`auto` · `fill` · `compact`	Height behavior within the layout slot
`maxHeight`	CSS value (e.g. `300px`)	Maximum height cap
`align`	`top` · `center` · `bottom`	Vertical alignment within allocated space

Scene Modifiers

Control scene-level spacing and alignment with HTML comments:

<!-- scene: gap=compact, bodyAlign=top, padding=compact -->

Modifier	Values	Description
`gap`	`compact` · `normal` · `spacious`	Gap between elements in the scene
`padding`	`none` · `compact` · `normal` · `spacious`	Scene padding
`bodyAlign`	`top` · `center` · `bottom`	Vertical alignment of body content
`columns`	CSS grid value (e.g. `2fr 3fr`)	Custom column widths for split layouts

Company Logo

Add a logo that appears on every slide:

---
title: My Presentation
logo: resources/logo.png
logoPosition: bottom-right
---

Positions: bottom-right (default), bottom-left, top-right, top-left. Supports local paths and URLs. Use PNG/SVG for transparency.

Hide the logo on specific slides with hideLogo: true in slide frontmatter.

Background Images

Set a background image on any slide (commonly used on intro slides):

---
background: /images/backgrounds/cuppa-bg-dark-01.jpg
---

# Title Slide

Background images fill the entire slide. Text automatically brightens for readability.

Speaker Notes

Add notes that appear in the presenter view:

<!-- notes: Your speaker notes here.
Can be multi-line. -->