# Narro

> Developer-first presentations. Author decks in Markdown or React, render them
> in the browser, export to PPTX, PDF, or a single HTML file.

Narro is text, so you can write a deck directly. This file plus the linked
resources are enough — you do not need to have seen the repository.

## Read this first

- **Everything in ONE file (no follow-up fetches — take this if you can only fetch once):** https://getnarro.com/llms-full.txt
- **No web access?** The same documentation ships through npm, over the registry
  that already installed your packages: `npm i -D @getnarro/docs`, then read
  `@getnarro/docs/llms-full.txt`, `@getnarro/docs/catalog.json`, or
  `@getnarro/docs/content/<slug>.md`. It pins to the version actually installed.
- **Rules to paste into your own AGENTS.md / CLAUDE.md / .cursor/rules:** https://getnarro.com/docs/agent-rules.md
- **Then check your work** — this is the part that matters more than the prose:

      npx @getnarro/cli check deck.md --render    # what every slide renders: elements, classes, text
      npx @getnarro/cli check deck.md --strict    # the CI gate: warnings are errors
      npx @getnarro/cli check deck.md --fit       # does the content fit the slide? (needs a browser)
      npx @getnarro/cli build deck.md             # the real build

  `check` names the bad layout, the unknown theme, the malformed directive, and
  every class that was written but landed on nothing. A deck you have not run it
  on is a deck you have not verified. `--strict` is the CI gate; `--render`
  answers "did that class attach to the word or the paragraph?" without a browser;
  `--fit` is the only check that can tell you a dense slide is clipping, and the
  only narro-provided check React mode has (point it at `dist/`).

## Fastest path to a deck

    npx @getnarro/cli new deck.md     # a single-file markdown deck
    npx @getnarro/cli dev deck.md     # open it, hot-reloading

Or scaffold a React project:

    npm create narro@latest my-deck

Note: the npm package named `narro` is unrelated to this project. Narro's
packages are all under the `@getnarro/` scope, and the CLI binary `narro`
comes from `@getnarro/cli`.

## Which mode

| You want | Use | Start at |
| --- | --- | --- |
| One file, no build setup, deck is prose-shaped | Markdown mode | https://getnarro.com/docs/markdown-mode.md |
| Live components, data, custom interaction | React mode | https://getnarro.com/docs/react-api.md |

You do not have to choose permanently: markdown decks climb to per-element
Tailwind, then to ejected React layouts, then to MDX, without being rewritten.

## Closed sets — do not invent names

Every value below is generated from the shipping source. If a name is not in
this list it does not exist, and a deck naming it will build and render wrong
rather than fail loudly. The full machine-readable set, including every
component's props and every exported string union, is one fetch:

- https://getnarro.com/catalog.json
- https://getnarro.com/components.json — every component's props, read out of the TypeScript types
- https://getnarro.com/llms/<Component>.md — one component's reference, on its own URL (names are
  case-sensitive and exact: https://getnarro.com/llms/Presentation.md). https://getnarro.com/llms/index.md lists
  every valid name; a guessed name 404s, so look it up rather than retrying.
- https://getnarro.com/schema/deck-frontmatter.schema.json
- https://getnarro.com/schema/slide-frontmatter.schema.json

Built-in layouts (`layout:` in slide frontmatter): default, cover, section, quote, end, two-column, three-column, image-right, image-full

Themes (`theme:` in deck frontmatter): default, corporate-dark, minimalist-light, creative-gradient, ocean-blue, forest-green, sunset-warm, midnight-purple, tech-dark, startup-bold, academic-classic

Colour schemes — **not a frontmatter key.** They are palettes, applied with
`narro themes apply <id> --color-scheme` or read as data from
`@getnarro/marketplace` (`getColorSchemeById`): ocean-blue, sunset-warm, forest-mist, royal-purple, rose-gold, arctic-blue, charcoal-slate, emerald-night

Font presets — **not a frontmatter key.** Applied from React with
`applyFontPreset(name)` from `@getnarro/core`: system, inter, roboto, openSans, lato, montserrat, poppins, raleway, sourceSerif, playfairDisplay, merriweather, jetBrainsMono

Deck frontmatter keys: title, author, date, theme, template, aspectRatio, transition, class, keyboard, mouse, touch, routing, favicon, maxDuration, plus any key beginning
`x-` — those are yours, nothing reads them, and `check --strict` stays quiet.

Slide frontmatter keys: layout, class, id, transition, background, notes

Tailwind in `{ … }`: whatever Tailwind calls it, including arbitrary values
(`text-[10px]`, `bg-[#0a0a0a]`), opacity modifiers and fractions
(`bg-white/5`, `w-1/2`), variants (`hover:`, `md:`, `dark:`), half-steps
(`p-1.5`) and `!` overrides. The one exception is a literal `{` or `}` inside
the block — put that class in `deck.css`.

Templates for `npm create narro@latest`: markdown-minimal, markdown-app, markdown-docs, minimal, corporate, developer, creative, bold-statement, visual-story, data-narrative, startup-pitch, tech-conference, template0

Components (80 total; props at https://getnarro.com/components.json):
AnimatePresence, Canvas, CanvasElement, CanvasShape, ErrorBoundary, ErrorOverlay, MarqueeRow, MasonryBackground, Motion, MotionContainer, MotionList, MotionNumber, MotionPresence, MotionSpotlight, MotionStep, MotionSteps, MotionText, MotionTransform, NebulaBackground, Notes, OverviewGrid, Presentation, PresenterNotes, Slide, SlideContent, TransformSlide, TrustedByMarquee, AgendaItem, AnimatedList, Animation, Badge, BigText, Callout, Card, Chart, Code, CommentForm, CommentItem, CommentMarker, CommentPanel, ContentSlide, CountingNumber, Diagram, DottedArc, DualColumnTextAndImage, Embed, FlowDiagram, FourColumn, Fragment, Grid, Heading, HexPatternBackground, Icon, Image, ImageBackground, ImageSlide, ImageSpotlight, InfoCardWithIcon, List, LogoGrid, MorphElement, ProcessFlowChart, ProfileCard, ProgressRing, Quote, ScrollableImage, Text, ThreeColumn, TimelineWithIndicators, TitleSlide, TitleSlideWithElement, TwoColumn, TwoColumnHighlight, TypewriterText, Video, WaveLine, WordReveal, Workflow, WorkflowStep, ZoomImage

## Documentation

Every page below is also available as markdown by appending `.md` to its URL —
same content, a fraction of the tokens, no markup to parse back out.

### Start here

- [Introduction](https://getnarro.com/docs/introduction.md): What is Narro, and should I be writing markdown or React?
- [Installation](https://getnarro.com/docs/installation.md): What do I install, and what does the project look like afterwards?
- [First Deck](https://getnarro.com/docs/first-deck.md): What does a working React deck look like, end to end?
- [Markdown Mode](https://getnarro.com/docs/markdown-mode.md): How do I split a slide, style one word, or reveal a line — without leaving the markdown file?
- [Writing AI Prompts](https://getnarro.com/docs/ai-prompts.md): What do I tell an AI so the deck it writes actually builds?
- [Rules for AI Agents](https://getnarro.com/docs/agent-rules.md): What do I paste into my repo so an agent stops writing decks that build wrong?

### Reference

- [React API](https://getnarro.com/docs/react-api.md): Which component or hook do I import, and what does it take?
- [CLI](https://getnarro.com/docs/cli.md): Which command do I run, and what are its flags?
- [Markdown API](https://getnarro.com/docs/markdown-api.md): How do I read, edit, or validate a deck file from my own code instead of by hand?
- [Component Reference](https://getnarro.com/docs/components.md): What props does this component take, and which package do I import it from?

### Guides

- [Animation](https://getnarro.com/docs/animation.md): How do I reveal a list one line at a time, or move between slides with something other than a cut?
- [Navigation](https://getnarro.com/docs/navigation.md): How does the audience move through the deck, and how do I present it?
- [Canvas & Positioning](https://getnarro.com/docs/canvas-positioning.md): How do I put something at an exact position instead of in the flow?
- [Images & Media](https://getnarro.com/docs/media.md): How do I use an image as a background, tint it, or embed a video?
- [Architecture](https://getnarro.com/docs/architecture.md): Which package owns what, and why is the seam where it is?
- [Transform Mode](https://getnarro.com/docs/transform-mode.md): How do I zoom and pan across one big canvas instead of cutting between slides?
- [Import & Export](https://getnarro.com/docs/import-export.md): How do I get this deck out as PPTX, PDF, or one file I can email?
- [AI Integration](https://getnarro.com/docs/ai-integration.md): How do I wire an AI assistant up to Narro so it can write and build decks?
- [Theming](https://getnarro.com/docs/theming.md): How do I change the colours, fonts, and overall look of a deck?
- [Deck Templates](https://getnarro.com/docs/deck-templates.md): How do I define one house style with named layouts my slides can reference, like a PowerPoint master?
- [Troubleshooting](https://getnarro.com/docs/troubleshooting.md): Something is wrong with my deck. What is it, and how do I fix it?
- [Limitations](https://getnarro.com/docs/limitations.md): What can't Narro do, and what do I do instead?

---

Everything above is https://getnarro.com/llms.txt. Below is every documentation page in full,
in reading order. Component props in the API reference are generated from the
TypeScript source, so they describe the shipping API rather than a
hand-maintained copy of it.

---

# Animation

> Fragments, transitions, and the motion primitives
>
> Read this when: How do I reveal a list one line at a time, or move between slides with something other than a cut?

## Fragments

A fragment reveals part of a slide on the next keypress instead of showing
everything at once.

```tsx
import { Fragment } from "@getnarro/shared-ui";

<Slide id="reveal">
  <SlideContent>
    <Heading level={2}>Progressive reveal</Heading>

    <Fragment order={1}>
      <Text>Appears first</Text>
    </Fragment>

    <Fragment order={2} effect="slide-up">
      <Text>Appears second, sliding up</Text>
    </Fragment>

    <Fragment order={3} effect="scale-in" duration={400}>
      <Text>Then this</Text>
    </Fragment>
  </SlideContent>
</Slide>;
```

`Fragment` comes from `@getnarro/shared-ui`, not `@getnarro/core`.

| Prop | Type | Default |
| --- | --- | --- |
| `order` | `number` | source order |
| `effect` | `FragmentEffect` | `"fade-in"` |
| `duration` | `number` (ms) | — |
| `staggerDelay` | `number` (ms) | — |
| `isActive` | `boolean` | inherited from the slide |

`FragmentEffect` is "fade-in" | "fade-out" | "slide-up" | "slide-down" | "slide-left" | "slide-right" | "scale-in" | "scale-out" | "blur-in".

Fragments consume a navigation step: on a slide with three fragments, the first
three presses reveal them and the fourth advances. Every key that advances a
slide advances a fragment too, including the `PageDown` a presenter's clicker
sends.

Without an explicit `order`, fragments reveal in source order. Set `order` when
you want a different one — two fragments sharing an order reveal together.

`trigger="time"` opts out: those fragments reveal on slide entry, staggered by
`staggerDelay`, and do not consume a press.

```tsx
<Fragment>revealed first</Fragment>
<Fragment>then this</Fragment>
<Fragment trigger="time">already there when the slide opens</Fragment>
```

Used outside a `Slide` — a component in a storybook, a page that is not a deck
— there is nothing to step, so a fragment reveals on mount.

In markdown mode the equivalent is `{.step}`, and it behaves the same way:

```markdown
- appears first {.step}
- appears second {.step delay=200}
```

## Slide transitions

```tsx
<Slide transition="fade">…</Slide>
```

`"none" | "fade" | "slide" | "zoom"`. In markdown, set `transition:` in slide
frontmatter, or on the deck to change the default for every slide.

## Motion primitives

`@getnarro/core` wraps Framer Motion in components that already know whether
their slide is on screen — animations start when the slide appears, not when the
deck mounts.

```tsx
import { Motion, MotionNumber, MotionText } from "@getnarro/core";

<Motion effect="slideUp" delay={0.2}>
  <Heading level={1}>Animated in</Heading>
</Motion>

<MotionText type="wordByWord">One word at a time</MotionText>

<MotionNumber value={42} suffix="%" decimals={0} />
```

Durations and delays on motion components are in **seconds** (Framer Motion's
convention), while `Fragment`'s `duration` is in milliseconds.

`MotionEffect` is "fadeIn" | "fadeOut" | "slideUp" | "slideDown" | "slideLeft" | "slideRight" | "scaleUp" | "scaleDown" | "rotateIn" | "flip" | "bounce" | "elastic" | "blur" | "glow" | "typewriter" | "spotlight" | "parallax" | "morphPath" | "stagger" | "wave".

See the [component reference](/docs/components) for the full set — `Motion`,
`MotionContainer`, `MotionList`, `MotionText`, `MotionNumber`,
`MotionPresence`, `MotionSpotlight`, `MotionSteps`, `MotionStep`,
`MotionTransform`.

## Gating your own animation

To drive animation yourself, ask whether the slide is active. Both packages
export the hook — `@getnarro/shared-ui` and `@getnarro/core` — and both read the
context `Slide` provides, so either import works:

```tsx
import { useSlideActive } from "@getnarro/shared-ui";

function Chart() {
  const isActive = useSlideActive();
  return <svg className={isActive ? "animate-draw" : "opacity-0"} />;
}
```

Without this, every animation on every slide fires on load and is finished
before the audience sees it.

## Respecting reduced motion

Motion components honour `prefers-reduced-motion`. If you hand-roll animation,
gate it the same way:

```css
@media (prefers-reduced-motion: reduce) {
  .animate-draw {
    animation: none;
  }
}
```

---

# Navigation

> Keyboard, mouse, touch, URL routing, overview mode, and the presenter view
>
> Read this when: How does the audience move through the deck, and how do I present it?

## Keyboard

| Key | Action |
| --- | --- |
| `→`, `Space`, `Page Down` | Next slide or fragment |
| `←`, `Page Up` | Previous slide or fragment |
| `Home` | First slide |
| `End` | Last slide |
| `F` | Toggle fullscreen |
| `O` | Toggle overview grid |

Disable with `<Presentation keyboard={false}>`, or `keyboard: false` in deck
frontmatter. Worth doing when a slide embeds something that wants the arrow keys
itself.

## Mouse and touch

Clicking the left or right edge of the deck moves a slide. On touch devices,
swipe left and right. Both are controlled by the `mouse` and `touch` props.

## URL routing

With `routing` enabled (the default), the URL tracks the current slide:

```
https://example.com/#/slide/intro     ← a slide with id="intro"
https://example.com/#/slide/3         ← the fourth slide, if it has no id
```

Links stay stable across edits when slides have explicit `id`s — without one, a
slide's URL is its index, and inserting a slide earlier changes it.

## Overview mode

`O` shows every slide as a grid. Arrow keys move the focus, `Enter` jumps.
Useful mid-talk when a question sends you backwards.

## Presenter view

`narro dev` serves a presenter view on a second port with the current slide, the
next slide, speaker notes, and a timer. Set `maxDuration` (minutes) on the deck
to get a countdown:

```tsx
<Presentation maxDuration={25}>
```

The two views stay in sync in both directions, so advancing on either moves
both.

## Driving navigation yourself

```tsx
import { useNavigation } from "@getnarro/core";

function Agenda() {
  const { goToSlideById } = useNavigation();

  return (
    <button type="button" onClick={() => goToSlideById("results")}>
      Skip to results
    </button>
  );
}
```

See the [React API](/docs/react-api) for everything `useNavigation` returns.

---

# Canvas & Positioning

> Place elements at exact coordinates with Canvas, CanvasElement, and CanvasShape
>
> Read this when: How do I put something at an exact position instead of in the flow?

Most slides should use normal flow layout. `Canvas` is for the ones that should
not — diagrams, annotated screenshots, anything where an element belongs at a
specific point.

## Canvas

```tsx
import { Canvas, CanvasElement, CanvasShape } from "@getnarro/core";

<Slide id="architecture">
  <Canvas>{/* positioned children */}</Canvas>
</Slide>;
```

## CanvasElement

Positions any content. `x` and `y` are percentages of the slide by default, so a
deck keeps its layout at every resolution.

```tsx
<CanvasElement x={10} y={20} width={30} height={15}>
  <div className="rounded bg-blue-500 p-4">Top left area</div>
</CanvasElement>

<CanvasElement x="100px" y="50px" rotate={45} opacity={0.8} zIndex={2}>
  <Text>Rotated, semi-transparent</Text>
</CanvasElement>
```

Pass a string with a unit (`"100px"`) to position in pixels instead.

## CanvasShape

Ten built-in shapes, drawn as SVG so they stay crisp at any scale:

`circle`, `rectangle`, `triangle`, `star`, `hexagon`, `pentagon`, `arrow`, `diamond`, `ellipse`, `cloud`

```tsx
<CanvasShape shape="circle" x={50} y={50} size={100} color="#3b82f6" />

<CanvasShape
  shape="hexagon"
  x={400}
  y={150}
  size={90}
  color="#8b5cf6"
  stroke="#ffffff"
  strokeWidth={2}
  opacity={0.8}
  rotate={15}
/>
```

## When not to use it

Absolute positioning does not reflow. A canvas slide that looks right at 16:9
can overlap at 4:3, and text inside one will not wrap into a new line as it
grows. For anything that is fundamentally a list, a comparison, or a body of
text, use `SlideContent` and a layout component — they adapt, and they will
still look right on a projector you have not seen.

Exact prop tables are in the [component reference](/docs/components).

---

# Images & Media

> Filters, overlays, backgrounds, video, and embeds
>
> Read this when: How do I use an image as a background, tint it, or embed a video?

## Image filters

`Image` applies CSS filters directly, so a photo can be tuned to a deck's
palette without an editor in the loop.

```tsx
import { Image } from "@getnarro/shared-ui";

<Image src="/photo.jpg" alt="The team" filter="grayscale" />;
```

Presets: `none`, `blur`, `grayscale`, `sepia`, `brightness`, `contrast`, `saturate`, `hue-rotate`, `invert`, `opacity`, `drop-shadow`.

Anything else, pass CSS directly:

```tsx
<Image src="/photo.jpg" alt="Tuned" customFilter="brightness(80%) contrast(110%)" />
```

## Colour overlays

Tint an image to match the deck:

```tsx
<Image src="/photo.jpg" alt="Tinted" overlay="#3b82f6" overlayOpacity={0.4} />
```

Overlays are also the practical way to get readable text over a photo — a dark
overlay at 0.5 will rescue almost any background.

## Full-bleed backgrounds

```tsx
import { ImageBackground } from "@getnarro/shared-ui";

<Slide id="cover">
  <ImageBackground src="/hero.jpg" overlay="dark">
    <Heading level={1}>Over the image</Heading>
  </ImageBackground>
</Slide>;
```

## Large and zoomable images

- `ScrollableImage` — a tall screenshot the audience scrolls through
- `ZoomImage` — click to magnify, for dense diagrams
- `ImageSpotlight` — Keynote-style Magic Move between framings of one image
  across slides, by giving each a shared `spotlightId`

## Video

```tsx
import { Video } from "@getnarro/shared-ui";

<Video src="/demo.mp4" autoPlay loop muted />;
```

Browsers block autoplay with sound, so `autoPlay` needs `muted` to be reliable.
For a demo you will narrate over, that is what you want anyway.

## Embeds

```tsx
import { Embed } from "@getnarro/shared-ui";

<Embed url="https://example.com" title="Live site" aspectRatio="16:9" />

<Embed url="https://www.youtube.com/watch?v=VIDEO_ID" title="Talk" />
```

YouTube and Vimeo URLs are converted to their embed form automatically. Sites
that send `X-Frame-Options: DENY` cannot be framed at all — no library can work
around that, so screenshot those with `narro capture-website <url>`.

Embedded pages need the network. If the venue's wifi is a gamble, capture a
screenshot as a fallback slide.

## Animated backgrounds

`@getnarro/core` ships three, all of which pause when their slide is off screen:

```tsx
import { MasonryBackground, NebulaBackground, TrustedByMarquee } from "@getnarro/core";

<NebulaBackground isActive>
  <Heading level={1}>Starfield behind the title</Heading>
</NebulaBackground>

<MasonryBackground
  images={["/a.jpg", "/b.jpg", "/c.jpg"]}
  gridColumns={12}
  gridRows={6}
  swapMinIntervalMs={3000}
  swapMaxIntervalMs={6000}
/>

<TrustedByMarquee
  rows={[[{ name: "Acme", color: "#ffffff" }], [{ name: "Globex", color: "#60a5fa" }]]}
  isActive
  baseSpeed={40}
/>
```

Full prop tables: [component reference](/docs/components).

---

# Architecture

> How the packages fit together and why the seams are where they are
>
> Read this when: Which package owns what, and why is the seam where it is?

## The packages

```
@getnarro/core          the runtime: Presentation, Slide, navigation, motion
@getnarro/shared-ui     ~50 slide components, no runtime dependency on core
@getnarro/markdown      the markdown/MDX dialect + its Vite plugin
@getnarro/marketplace   themes, colour schemes, template metadata
@getnarro/cli           new / dev / build / export / import
@getnarro/mcp-server    MCP tools and resources for AI assistants
@getnarro/docs          these pages as data + the generated API reference
create-narro            npm create narro
```

## Why the seams are there

**`core` and `shared-ui` are separate** because they change at different rates
and for different reasons. `core` owns behaviour — how navigation works, when a
slide is active, how transitions run. `shared-ui` owns appearance. A deck can
use `core` alone and hand-write its markup, which is exactly what the `minimal`
template did until the docs made `shared-ui` the assumed baseline.

**`shared-ui` has no i18n and no state.** Components take text as props. That
keeps them usable from markdown, from React, and from generated code without
each caller having to set up a provider.

**`markdown` does not live in `cli`.** The dialect is a library — the Vite
plugin, the compiler, and the layouts are all importable — so a scaffolded
project can use it without depending on the CLI's much heavier install
(Playwright, sharp, the Google APIs client).

**`create-narro` does not live in `cli`** either, and cannot: `npm create narro`
resolves the `create-narro` package specifically, and scaffolding has to run
before anything is installed. `@getnarro/cli` depends on it so `narro create`
and `create-narro` share one implementation and one copy of the templates.

## How a deck renders

Both modes converge on the same runtime.

**React mode.** Your `App.tsx` composes `Presentation` and `Slide` directly.
Vite builds it like any other React app.

**Markdown mode.** The `@getnarro/markdown` Vite plugin compiles `deck.md` into
virtual modules:

```
virtual:narro/deck            the deck component
virtual:narro/deck.css        Tailwind, scanning the deck for utility classes
virtual:narro/slot/<i>/<n>    one compiled MDX module per slot
virtual:narro/layout/<name>   a resolved layout component
```

The result is a tree of `Presentation` and `Slide` — the same components React
mode uses. This is why the two modes share navigation, transitions, presenter
view, and export: there is only one runtime, and markdown is a front end to it.

Editing the deck recompiles only the slots whose content changed.

## Core concepts

**A slide is a component.** No slide registry, no ordering metadata — order is
source order, and a slide is addressable by `id`.

**Activity is context, not a prop.** `useSlideActive()` tells a component
whether its slide is on screen. This is what lets animations start when the
audience sees them, and lets off-screen backgrounds stop doing work.

**Fragments are navigation steps.** They participate in the same next/previous
sequence as slides, which is why a fragment reveal and a slide advance feel
identical to the presenter.

**Layouts resolve by name, most specific first.** A deck's own `layouts/`
directory shadows the theme, which shadows the built-ins. Overriding one layout
never means forking the rest.

---

# Transform Mode

> Prezi-style spatial navigation with TransformSlide
>
> Read this when: How do I zoom and pan across one big canvas instead of cutting between slides?

`TransformSlide` puts content on a plane and moves a camera between positions
instead of cutting between slides. One canvas, many framings.

```tsx
import { TransformSlide, type TransformSubSlide } from "@getnarro/core";

const steps: TransformSubSlide[] = [
  {
    content: <Heading level={1}>The whole system</Heading>,
    position: { x: 0, y: 0, scale: 1 },
  },
  {
    content: <Text>Zoom into ingestion</Text>,
    position: { x: 100, y: 0, scale: 0.8, rotate: -5 },
  },
  {
    content: <Text>And into storage</Text>,
    position: { x: 50, y: 80, scale: 1.2, rotate: 5 },
  },
];

<Slide id="tour">
  <TransformSlide subSlides={steps} duration={1000} easing="backInOut" perspective />
</Slide>;
```

| Prop | Type | Default |
| --- | --- | --- |
| `subSlides` | `TransformSubSlide[]` | required |
| `duration` | `number` (ms) | `800` |
| `easing` | easing name | — |
| `perspective` | `boolean` | `false` |

Each `position` is `{ x, y, scale, rotate? }`, where `x` and `y` are offsets
from the canvas origin and `scale` is the camera's zoom.

## Navigation

Sub-slides are navigation steps, like fragments: `→` moves to the next position
and only advances past the last one to the next slide. The presenter does not
have to think about the distinction.

## When it earns its keep

Transform mode is the right call when the spatial relationship *is* the content
— a system diagram you tour, a map, a timeline that reads as one long line, a
zoom from summary into detail and back out.

It is the wrong call for a normal talk. Constant camera movement is tiring to
watch and disorienting on a large screen, and audiences lose the thread when
they cannot tell where they are. If the connection between two slides is
logical rather than spatial, a cut says it better than a swoop.

A good compromise: normal slides for most of the deck, one transform slide for
the part that genuinely benefits.

## Motion sickness

Large scale changes and rotation are the parts that make people uncomfortable.
Keep `scale` within roughly 0.5–2, use `rotate` sparingly, and keep `duration`
under about 1200ms — a slow swoop is worse than a quick one.

---

# Import & Export

> PPTX, PDF, Google Slides, static sites, and single-file HTML
>
> Read this when: How do I get this deck out as PPTX, PDF, or one file I can email?

## Static site

```bash
narro build              # a scaffolded project
narro build deck.md      # a single markdown deck
narro preview --outDir dist
```

`dist/` is a plain static site. This is the highest-fidelity way to share a
deck: animations, embeds, and live components all still work.

## Single-file HTML

```bash
narro bundle
```

Inlines everything — JS, CSS, images — into one `.html` file that opens from a
filesystem with no server. This is the format to use when you are presenting
from a machine you do not control, or emailing a deck to someone who will not
run a build.

Images are base64-inlined, so an image-heavy deck produces a large file.

## PDF

```bash
narro export --to pdf
```

One page per slide, fragments flattened to their final state. For handouts.

## PowerPoint

```bash
narro export --to pptx output.pptx
narro export --to pptx output.pptx --template-path corporate.potx
```

Slides map onto real PowerPoint shapes rather than screenshots, so text stays
selectable and editable. Passing a `.potx` applies your organisation's master —
the usual reason a deck has to become PPTX at all.

What does not survive: animations beyond simple builds, embedded web content,
and anything driven by a live component. Those become their rendered state.

## Google Slides

```bash
narro export --to google-slides
narro export --to google-slides --template-id <id>
```

Needs Google OAuth credentials in the environment; the CLI walks through the
consent flow on first run.

## Importing

```bash
narro import deck.pptx
narro import --from google-slides <presentation-id>
```

Produces Narro slides from an existing deck: text, structure, images, and
speaker notes come across.

Treat the output as a starting point rather than a finished deck. PowerPoint
positions everything absolutely, so a faithful import is a pile of
`CanvasElement`s that will not reflow — readable, but not yet using layouts.
The usual workflow is to import, then convert the slides that matter into
`SlideContent` and layout components, and leave the rest.

`narro analyze-slides-for-components` reports which `shared-ui` components an
imported deck could be rewritten with, which makes that pass faster.

---

# AI Integration

> The MCP server, and how to give any assistant accurate Narro docs
>
> Read this when: How do I wire an AI assistant up to Narro so it can write and build decks?

There are two ways to point an AI assistant at Narro. Which you want depends on
whether the assistant already has a terminal.

## If your assistant has shell access

Coding agents — Claude Code, Cursor's agent, Copilot Workspace — can just use
the CLI. They need the documentation, not tools:

```
Read https://getnarro.com/llms.txt, then write a deck about <topic> to deck.md
and run `npx @getnarro/cli build deck.md` to check it.
```

Every docs page is available as markdown by appending `.md`, and
<https://getnarro.com/llms-full.txt> is all of them in one fetch.

Offline or sandboxed? Install the docs:

```bash
npm install --save-dev @getnarro/docs
```

```js
import { getDoc, listDocs, getComponent } from "@getnarro/docs";

listDocs();                    // every page's slug, title, description
getDoc("markdown-mode").body;  // the markdown
getComponent("List").props;    // generated from the TypeScript source
```

The component data is generated at build time from the types, so it describes
the version you installed rather than a hand-maintained copy.

## If your assistant does not

`@getnarro/mcp-server` exposes Narro over the Model Context Protocol.

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
`%APPDATA%\Claude\claude_desktop_config.json` on Windows:

```json
{
  "mcpServers": {
    "narro": {
      "command": "npx",
      "args": ["-y", "@getnarro/mcp-server"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add narro -- npx -y @getnarro/mcp-server
```

### Cursor, Cline, Continue

Same shape, under whatever key the extension uses for MCP servers — for Cline it
is `cline.mcpServers` in VS Code settings.

### Tools

| Tool | What it does |
| --- | --- |
| `create_presentation` | Scaffolds a project and returns its path |
| `list_slides` | Structured slide data from a deck |
| `add_slide` | Inserts a slide into the file |
| `update_slide` | Rewrites one slide |
| `delete_slide` | Removes a slide |
| `apply_theme` | Applies a marketplace theme |
| `check_presentation` | Validates names without building; fast enough for every edit |
| `build_presentation` | Builds, returning errors on failure |
| `export_presentation` | PPTX, PDF, Google Slides |
| `bundle_presentation` | Single-file HTML |
| `import_presentation` | From PPTX or Google Slides |
| `get_presentation_info` | Documentation on a topic |
| `manage_comments` | Slide comments |

These edit files on disk. Point them at a directory you are willing to have
written to.

### Resources

The server also exposes the documentation as MCP resources
(`narro://docs/<slug>`), which clients can cache and read without spending a
tool call.

## Getting good results

The [AI prompts](/docs/ai-prompts) page covers this in detail. The short
version:

1. **Give it the dialect.** The most common failure is a model writing a
   markdown syntax Narro does not speak.
2. **Make it build.** `narro build deck.md` is the pass/fail signal; without it
   nothing catches a bad prop.
3. **Say which package.** `Presentation`, `Slide`, `SlideContent`, `Notes` are
   in `@getnarro/core`; `Heading`, `Text`, `List`, and the rest are in
   `@getnarro/shared-ui`.

---

# Theming

> Themes, colour schemes, fonts, and per-deck styling
>
> Read this when: How do I change the colours, fonts, and overall look of a deck?

## Tailwind first

Every Narro component takes `className`, and it is merged with the component's
own classes rather than replacing them. For most decks this is the whole
theming story:

```tsx
<Slide className="bg-gradient-to-br from-slate-900 to-blue-950">
  <Heading level={1} className="text-blue-300">Title</Heading>
</Slide>
```

In markdown, the same thing via the attribute syntax:

```markdown
# Title {.text-blue-300}
```

…or `class:` in slide frontmatter to style the whole slide, or on the deck
frontmatter to set a default for every slide.

## Themes

`@getnarro/marketplace` ships themes as design tokens plus optional layout
overrides:

```bash
narro themes          # browse and apply
```

```markdown
---
theme: corporate-dark
---
```

Built-in themes: `default`, `corporate-dark`, `minimalist-light`, `creative-gradient`, `ocean-blue`, `forest-green`, `sunset-warm`, `midnight-purple`, `tech-dark`, `startup-bold`, `academic-classic`.
Colour schemes: `ocean-blue`, `sunset-warm`, `forest-mist`, `royal-purple`, `rose-gold`, `arctic-blue`, `charcoal-slate`, `emerald-night`.

A theme can also supply layouts. Layout names resolve most-specific-first — the
deck's own `layouts/` directory, then the deck template, then the theme, then
the built-ins — so overriding one layout never means forking the others.

## Themes and deck templates

A theme is a palette someone else shipped. A [deck template](/docs/deck-templates)
is the house style for *your* deck: one file beside it holding the tokens, the
chrome every slide carries — footer, logo, slide numbers — and a set of layouts
addressed by id.

| | Theme | Deck template |
| --- | --- | --- |
| Where it comes from | `@getnarro/marketplace`, by name | a file beside the deck |
| What it sets | colours and fonts | colours, fonts, chrome, layouts, defaults |
| Named layouts | a theme may ship some | that is the point of it |
| Checked by `narro check` | the name exists | the whole shape, plus every id and slot |

They compose: `theme:` for the palette, `template:` for the layouts, and the
template wins where they overlap. Reach for a theme to change how a deck looks
in one line; reach for a template when the same look has to hold across forty
slides.

## Fonts

```tsx
import { applyFontPreset } from "@getnarro/core";

applyFontPreset("inter");
```

Presets: `system`, `inter`, `roboto`, `openSans`, `lato`, `montserrat`, `poppins`, `raleway`, `sourceSerif`, `playfairDisplay`, `merriweather`, `jetBrainsMono`.

Or set them directly on the presentation:

```tsx
<Presentation
  theme={{
    fontHeading: '"Inter", sans-serif',
    fontBody: '"Inter", sans-serif',
    fontMono: '"JetBrains Mono", monospace',
  }}
>
```

Presets load from Google Fonts. If the room's network is unreliable, `system`
never fails — and a deck rendered in a fallback font is worse than one that
never asked for a webfont.

## Design tokens

Themes expose Tailwind v4 `@theme` tokens, so custom colours are available as
utilities:

```css
@theme {
  --color-brand-500: #6366f1;
}
```

```markdown
# Title {.text-brand-500}
```

## Practical advice

Two font sizes and two colours will carry an entire deck. Contrast that reads on
your laptop often disappears on a washed-out projector, so err darker on light
backgrounds and lighter on dark ones. And whatever you pick, apply it on the
deck frontmatter rather than per slide — it is the difference between changing
one line later and changing forty.

---

# Deck Templates

> The slide master for markdown mode — one file of tokens, chrome, and layouts addressed by id
>
> Read this when: How do I define one house style with named layouts my slides can reference, like a PowerPoint master?

A **deck template** is one file beside the deck that owns how the deck looks. It
is the same idea as a slide master in PowerPoint or Google Slides: design tokens
and the chrome every slide carries, plus a set of layouts addressed by id that a
slide references by name.

```markdown
---
title: Q3 Business Review
template: ./deck.template.ts
---

---
layout: title-slide
---

# Q3 Business Review
```

```ts
// deck.template.ts
import type { DeckTemplate } from "@getnarro/markdown";

export default {
  id: "acme",
  tokens: { colors: { brand: "#5b8cff", accent: "#ffb020" } },
  master: {
    footer: { text: "{title} · {date}" },
    slideNumber: { format: "{n} / {total}", from: 2 },
  },
  layouts: {
    "title-slide": { base: "cover", master: false },
    "metric-split": { base: "two-column", regions: { right: "text-right text-accent" } },
  },
} satisfies DeckTemplate;
```

That deck now has a footer and a slide number on every slide but the first, an
id (`title-slide`) that `narro check` accepts and `title-slidee` that it
rejects, and two colours usable as `text-brand` and `text-accent` anywhere in
the markdown.

A runnable version of exactly this is
[`apps/template-deck`](https://github.com/getnarro/narro/tree/main/apps/template-deck)
in the repository.

## Why not just `class:` everywhere

You can do all of this per slide, and for a ten-slide talk you should. A
template earns its keep when the same look has to hold across forty slides and
survive being edited by someone else:

- **The deck stops naming design.** No colours, no sizes, no chrome in the
  markdown — so rebranding is one edit rather than a find-and-replace.
- **Layout ids become a closed set.** A name that is not in the template does
  not exist, and `narro check` says so, with the ids that would have worked.
- **Slots get checked on custom layouts too.** A template layout declares its
  slots, so `::sidbar::` is an error instead of content that never renders.

## Where the file lives

`template:` in the deck frontmatter, relative to the deck:

```yaml
---
template: ./brand/acme.template.ts
---
```

Leave it out and a file beside the deck is used, if there is one:
`<deck>.template.*` first, then `template.*` — the same way `<deck>.css` and
then `deck.css` are picked up. Naming it explicitly is worth it when the deck is
going to be read by someone who has not seen this page.

Any of these extensions works: `.ts`, `.mts`, `.js`, `.mjs`, `.json`, `.yaml`, `.yml`.
TypeScript is the one to reach for. `satisfies DeckTemplate` gives autocomplete
on every key and an error on a mistyped one, and because the import is
`import type` it is erased before the file runs — so the template loads in a
deck directory with no `node_modules` at all. In a project that depends on
`@getnarro/markdown` you can write `defineTemplate({ … })` instead.

A template is **data**: no JSX, no imports of components, nothing that needs a
bundler. That is what lets `narro check` read it in milliseconds. The one thing
data cannot express has its own escape hatch, below.

## The shape

Top-level keys: `id`, `name`, `description`, `version`, `author`, `tokens`, `css`, `master`, `layouts`.
Unlike deck frontmatter, this shape is **closed** — a key it does not define is
an error, not something quietly kept for a theme to read. Nothing else reads a
template file, so a stranger in it is always a typo.

### Tokens

```ts
tokens: {
  colors: {
    background: "#080d18",
    foreground: "#e8edf7",
    primary: "#5b8cff",
    accent: "#ffb020",
    brand: "#5b8cff",
  },
  fonts: { heading: '"Inter", sans-serif', body: '"Inter", sans-serif' },
}
```

Each colour lands in three places. The six semantic names — `primary`,
`secondary`, `background`, `foreground`, `muted`, `accent` — become the
`--slide-*` variables the deck's base styling reads, so setting `background`
changes the deck's background without a class anywhere. Every name, semantic or
not, also becomes a Tailwind v4 theme colour: `brand` gives you `text-brand`,
`bg-brand/10`, `border-brand`, `from-brand`. Fonts work the same way, as
`font-heading` and friends.

This is the same variable set a marketplace theme fills in, so a deck can name
both — `theme:` for the palette, `template:` for the layouts — and the template
wins where they overlap.

For anything tokens cannot say, `css:` is appended to the deck's stylesheet
after them:

```ts
css: `.rs-chrome-footer { letter-spacing: 0.16em; text-transform: uppercase; }`,
```

### The master

`class`, `background`, `header`, `footer`, `logo`, `slideNumber`,
and every one of them applies to **every slide in the deck** — including slides
that name no layout at all, exactly as a PowerPoint master does.

```ts
master: {
  class: "bg-linear-to-b from-brand-deep to-background",
  footer: { text: "{title} · confidential" },
  logo: { image: "https://acme.example/logo.svg" },
  slideNumber: { format: "{n} / {total}", from: 2 },
}
```

The four placeholders — `header`, `footer`, `logo`, `slideNumber` — take
a placeholder takes `text`, `image`, `class`, `position`; `slideNumber` takes `format`, `class`, `position`, `from`.
`position` is one of
`top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, and the
defaults are chosen so the four never collide: header `top-left`, logo
`top-right`, footer `bottom-left`, slide number `bottom-right`.

Text may contain `{title}`, `{author}` and `{date}` — read from the deck
frontmatter — and `{n}` and `{total}`. They are substituted **when the deck is
built**, so what reaches the browser is a finished string, and
`narro check --render` sees the same slide the projector will. A brace naming
something else is left alone.

`from: 2` on `slideNumber` is the title-slide exemption; `image` is an ordinary
URL, so an absolute one, a data URI, or a file in a scaffolded project's
`public/` all work.

Placeholders never take a click — they are `pointer-events-none`, because a
bottom-left footer sits exactly where click-the-edge navigation lives.

### Layouts

Each key under `layouts` is an id a slide can name. A layout takes
`name`, `description`, `base`, `component`, `slots`, `class`, `regions`, `defaults`, `master`.

```ts
layouts: {
  chapter: {
    name: "Chapter divider",
    description: "Announces a section.",
    base: "section",
    class: "border-brand border-l-8",
    regions: { default: "text-brand" },
    defaults: { transition: "fade" },
    master: { footer: false },
  },
}
```

**`base`** is the built-in the layout is built on (or a layout in the deck's own
`layouts/` directory), defaulting to `default`. A base never resolves to another
template layout — layouts on a master do not chain, so there is no order to
learn and no cycle to worry about.

**`class`** goes on the slide root, after the master's and before the slide's
own `class:`.

**`regions`** attaches classes to one slot's content, keyed by slot name, with
`default` meaning the slide body. A declared region wraps that slot in a `<div>`
carrying the classes plus `flex flex-col gap-4` — which is what every built-in
already puts around slot content, so the wrapper does not change spacing.
Undeclared regions are not wrapped at all. Tailwind's arbitrary variants reach
inside: `"[&_h3]:text-7xl [&_h3]:text-accent"`.

**`defaults`** are slide frontmatter defaults — `background`, `transition`, or
any key the layout's component reads. A slide that sets the key wins.

**`master`** overrides the deck's. `false` turns off every placeholder for this
layout, which is the clean title slide most decks want; `{ footer: false }`
turns off one. The master's `class` and `background` survive `master: false` —
they are the deck's look rather than chrome. Override those with the layout's
own `class` and `defaults.background`.

**`slots`** declares the named slots the layout renders. It **declares**; it
does not create. A layout built on a built-in already has that built-in's slots
and cannot add to them — declaring one the base does not render is an error,
because a slide filling it would lose that content silently. Use `slots` for a
`component`, or for a base out of your own `layouts/` directory whose props
nothing here can see.

### A layout that needs code

Some layouts are not expressible as data. `component:` points at a React file,
relative to the template:

```ts
scorecard: {
  component: "./template/Scorecard.tsx",
  slots: ["cards"],
},
```

It is still a layout on the master: the slide still gets the footer, the logo
and the slide number, `scorecard` is still an id `narro check` knows, and
`cards` is still a slot it will reject a typo in. The component is an ordinary
Narro layout — see [markdown mode](/docs/markdown-mode#layouts).

## How a name resolves

A slide's `layout:` is looked up in this order, first match winning:

1. `<deckDir>/layouts/<name>.{tsx,jsx,mdx,ts,js}` — yours, shadows everything
2. The deck template's `layouts`
3. The active theme's layouts
4. The built-ins

So dropping a `layouts/chapter.tsx` beside the deck overrides the template's
`chapter` for that one deck without touching the template.

## What `narro check` tells you

```
$ narro check deck.md

  template: acme (deck.template.ts)
  layouts:  title-slide, agenda, chapter, metric-split, pullquote, scorecard, close
✓ deck.md looks good
```

Which ids exist is the question a template raises and nothing else answers —
they live in a file the deck does not otherwise mention. The same run rejects a
layout id that does not exist, a slot the layout does not render, a `base` that
is not a layout, a region styling a slot that is not there, a `component` path
that does not resolve, and a template file that does not match the shape. All of
them are names, all of them build cleanly otherwise, and all of them produce a
slide that is subtly not what the file said.

Editing the template in `narro dev` reloads the deck.

## What this is not

A template is a **house style for one deck or one directory of decks**, written
by whoever owns that deck. It is not a package: there is no registry, no
versioning beyond the `version` string, and no install step. Sharing one means
committing the file, or pointing several decks at the same path.

For a palette you did not write, use a marketplace [theme](/docs/theming). For a
whole starting project, use a
[template project](/docs/installation) — `npm create narro@latest`. The word is
overloaded; these are three different things.

---

# Troubleshooting

> Symptoms, what causes them, and the fix — including the failures that produce no error
>
> Read this when: Something is wrong with my deck. What is it, and how do I fix it?

Entries are grouped by what you **observe**, not by what is wrong, because you
arrive here with a symptom rather than a diagnosis. The headings are the literal
strings you would search for.

Before reading further: `npx @getnarro/cli check deck.md` diagnoses most of this
in about a second and names the value that would have worked. Roughly half the
entries below exist because the failure happens *without* an error, which is
exactly when a checker is worth more than a message.

## Failures that produce no error at all

These are the expensive ones. Nothing throws, the build succeeds, and the deck
is wrong on screen.

### A directive shows up as literal text on the slide

**Symptom:** the audience sees `<!-- .element: class="fragment" -->` or
`::: note` rendered as body copy, instead of the effect it was supposed to have.

**Cause:** that is Marp, reveal.js, or Slidev syntax. Narro's dialect is
different, and markdown it does not recognise is just text — there is nothing
for it to reject. This is overwhelmingly the most common broken deck when the
markdown was written by an AI, because those three tools dominate its training
data.

**Fix:** the Narro equivalents are `{.class}` after an element, `<!-- notes: … -->`
for speaker notes, and `{.step}` on a list item for a fragment. Full dialect:
[Markdown mode](/docs/markdown-mode). If a model wrote the deck, paste the
dialect contract from [Rules for AI agents](/docs/agent-rules) into your
project's `AGENTS.md` — otherwise it will regenerate the same syntax next time.

**`narro check` catches this**, including when the syntax is Narro's own and the
element simply did not form. To print the markers on purpose, put them in a code
fence or `` `inline code` ``, or escape them — `\*\*not bold\*\*`.

### Everything after `::something::` vanishes

**Symptom:** half a slide is missing. No error, no warning, no blank space
where it should have been.

**Cause:** the slot name does not exist on that layout, so nothing renders it.
`two-column` has one named slot and it is called `right`; `::sidebar::` and
`::second::` are inventions.

**Fix:** run `check`, which reports this one precisely:

```
error  deck.md:10 (slide 2)
  Layout "two-column" has no slot "sidebar", so everything after `::sidebar::`
  would not render. Slots for this layout: right.
```

Slot names describe the **position**, not the content. See the layout table in
[Markdown mode](/docs/markdown-mode).

### The deck renders with default styling and ignores the theme

**Symptom:** a `theme:` is set in the deck frontmatter, and the deck looks like
it has no theme.

**Cause:** the theme name does not resolve. Theme ids are kebab-case and
qualified — `corporate-dark`, not `corporate`; `tech-dark`, not `tech`.

**Fix:** `check` catches this as an error and lists every installed theme.
Valid ids are
`default`, `corporate-dark`, `minimalist-light`, `creative-gradient`, `ocean-blue`, `forest-green`, `sunset-warm`, `midnight-purple`, `tech-dark`, `startup-bold`, `academic-classic`.

### A frontmatter key does nothing

**Symptom:** you set `aspect-ratio: "16:9"` (or `color-scheme`, or
`font-preset`) and the deck ignores it.

**Cause:** frontmatter keys are camelCase. An unrecognised key is not an error —
a theme or a custom layout is allowed to read its own keys — so it is kept and
ignored.

**Fix:** `check` reports it as a warning with the correction:

```
warning  deck.md
  Deck frontmatter key "aspect-ratio" is not one the dialect defines, so nothing
  reads it unless your theme or layouts do. Did you mean "aspectRatio"?
```

Deck keys are
`title`, `author`, `date`, `theme`, `template`, `aspectRatio`, `transition`, `class`, `keyboard`, `mouse`, `touch`, `routing`, `favicon`, `maxDuration`;
slide keys are
`layout`, `class`, `id`, `transition`, `background`, `notes`.

### A list renders with plain bullets when you asked for checkmarks

**Symptom:** `<List variant="bullet">` or `variant="number"` produces the
default marker.

**Cause:** neither value exists. `List`'s `variant` names the CSS marker, not
the semantic role:
"disc" | "decimal" | "check" | "arrow" | "none".

**Fix:** `variant="disc"` for bullets, `variant="decimal"` for numbers,
`variant="check"` for checkmarks. The [component
reference](/docs/components) is generated from the types, so it is the
authority on every prop.

### You wanted a horizontal rule and got a new slide

**Symptom:** a `---` written as a divider inside a slide's body starts a new
slide instead of drawing a line.

**Cause:** `---` on its own line *is* the slide separator. There is no way for
the splitter to tell a thematic break from a slide break, so the slide break
wins.

**Fix:** use `***` or `___`, which markdown renders as the same horizontal rule
and the splitter ignores. A `---` inside a fenced code block — backticks or
tildes — is safe and does not split.

## Errors, with their fixes

### `Could not parse expression with acorn`

**Symptom:** a deck fails on a line containing `{`.

**Cause:** a slide is MDX, so `{` opens a JavaScript expression unless the block
is Narro's attribute syntax — `{.class}`, `{#id}`, `{key=value}`. A brace around
anything else, `{like this}`, is read as code.

The message names the offending character when it can:
*"Narro's attribute syntax does not accept `X`."* Today the only character that
cannot appear in a class is a literal `{` or `}`; arbitrary values
(`text-[10px]`), opacity modifiers (`bg-white/5`), fractions, variants
(`hover:`, `md:`), half-steps (`p-1.5`) and `!` overrides are all accepted. If
you are on an older version, those all failed here — upgrade rather than
rewriting the deck.

**Fix:** write `\{` for a literal brace, or put the text in `` `inline code` ``.
If the block really is a class list containing a brace, move that one class into
`deck.css`.

### `… is not attribute syntax, so this container has no classes at all`

**Symptom:** `check` or `build` fails on a `:::` line, or on a fenced code
block's info string.

**Cause:** a `{ … }` in either position has no second reading — unlike a brace in
prose, which MDX can compile as an expression — so a block that is not attribute
syntax there means the whole class list would be discarded. It used to be
discarded silently: the deck built, `check --strict` said `✓ looks good`, and the
box reached the projector unstyled.

**Fix:** make it attribute syntax (`.class`, `#id`, `key=value`), or remove it. A
fence's info string is `` ```bash {.rounded-xl} `` — language first, block last.

### `… written here but on no element in the compiled slide`

**Symptom:** `check` names a class you wrote and says nothing renders it.

**Cause:** the block parsed, the class is legal, and the element it attached to
does not exist in the output — most often because the block sits after something
that is not an element (an MDX comment, a slot marker) and had nothing to attach
to.

**Fix:** run `narro check deck.md --render` and look at the element you meant. An
attribute block styles the element it sits against: a list item styles the
`<li>`, a fence styles the `<pre>`, a block on its own line styles the block
above it, and one written tight against a word styles the word. Move the block
next to the element you meant.

### `N slides do not fit the canvas`

**Symptom:** `check --fit` reports overflow and names an element.

**Cause:** the slide's content is taller or wider than the canvas (1920×1080 by
default), so the audience sees it clipped. Nothing else in the toolchain can see
this — a build is silent about layout.

**Fix:** reduce a font size, a padding, or the amount on the slide; or split the
slide. The named element is the last one sticking out, which is usually the one
to shrink.

### `--fit needs a browser and none is installed`

**Symptom:** `check --fit` measures nothing.

**Cause:** `--fit` renders the deck for real, so it needs Chromium. It reports
this rather than passing quietly, and under `--strict` it fails.

**Fix:** `npx playwright install chromium`, or set
`NARRO_CHROMIUM=/path/to/chromium` if your image already has one.

### `Expected a closing tag for <br>`

**Symptom:** a deck that used to build now fails on a line of raw HTML.

**Cause:** raw HTML in a slide is JSX. Earlier versions compiled `.md` decks as
plain CommonMark, which silently *deleted* the tag rather than complaining — so
a deck could carry HTML that never rendered and never said so.

**Fix:** close every tag (`<br />`, `<img … />`) and camelCase every attribute
(`className`, not `class`). If the HTML was never rendering anyway, deleting it
changes nothing on screen.

### `Unknown layout "x". Available: …`

**Symptom:** `check` or `build` exits non-zero with this message.

**Cause:** the `layout:` value is not a built-in and there is no matching file
in a `layouts/` directory beside the deck.

**Fix:** use one of
`default`, `cover`, `section`, `quote`, `end`, `two-column`, `three-column`, `image-right`, `image-full`,
or create `layouts/<name>.tsx` next to the deck — the error names that path for
you. `check` also suggests the closest existing name, so a typo is a one-line
fix.

Note that `layout` means two different things and they are separate closed
sets. In slide frontmatter it is the layout name above. On the React
`SlideContent` component it is content alignment:
"default" | "centered" | "top" | "bottom".

### `has no exported member 'Heading'` / `does not provide an export named 'Heading'`

**Symptom:** TypeScript reports `Module '"@getnarro/core"' has no exported
member 'Heading'` (TS2305), or the browser reports `The requested module
'@getnarro/core' does not provide an export named 'Heading'`. The package
itself resolves fine; only the named import fails.

**Cause:** `@getnarro/core` is the presentation runtime plus the motion and
canvas primitives —
`AnimatePresence`, `Canvas`, `CanvasElement`, `CanvasShape`, `ErrorBoundary`, `ErrorOverlay`, `MarqueeRow`, `MasonryBackground`, `Motion`, `MotionContainer`, `MotionList`, `MotionNumber`, `MotionPresence`, `MotionSpotlight`, `MotionStep`, `MotionSteps`, `MotionText`, `MotionTransform`, `NebulaBackground`, `Notes`, `OverviewGrid`, `Presentation`, `PresenterNotes`, `Slide`, `SlideContent`, `TransformSlide`, `TrustedByMarquee`.
`Heading` is not among them. The content components —
53
of them, including `Heading`, `Text`, `List`, `Code`, and `Image` — are in
`@getnarro/shared-ui`.

**Fix:** import content components from `@getnarro/shared-ui`. The split is
deliberate: `shared-ui` has no runtime dependency on `core`, so a deck can use
the components without the presentation runtime. Which package exports what:
<https://getnarro.com/components.json>, or one component at a time at
<https://getnarro.com/llms/Heading.md>.

### `npx narro …` installs something that is not Narro

**Symptom:** `npx narro build deck.md` downloads a package and then fails in a
way that mentions no Narro command you recognise.

**Cause:** the npm package named `narro` is **unrelated to this project**.
Narro's packages are all published under the `@getnarro/` scope, and the
`narro` binary comes from `@getnarro/cli`.

**Fix:** `npx @getnarro/cli <command>`. Inside a scaffolded project the local
binary is already on the path, so plain `narro build deck.md` works there;
outside one, always name the scoped package.

**Anti-fix:** installing `narro` globally so the bare command resolves. It is
someone else's package, and it will not become Narro.

### The deck builds locally and fails in CI or on a fresh clone

**Symptom:** works on your machine, fails after `npm install` somewhere else.

**Cause:** almost always a dependency that resolves through your lockfile but
is not declared, or a file that is not in the package's `files` list.

**Fix:** reproduce it the way a user hits it — install into a directory outside
your project and build there. Narro's own repository runs exactly this as a
separate CI job (`pnpm test:templates`) because the workspace build stayed
green while every published template failed to build, for months.

## Still stuck

`check` reports every problem it finds in one run, so fix them all before
re-running rather than one at a time. If the deck passes `check` and is still
wrong, the problem is in a place `check` cannot see — a custom layout
component, a theme's own CSS, or an MDX component — and `build` with the
browser console open is the next step.

Something that should have been caught and was not is worth
[reporting](https://github.com/getnarro/narro/issues): a recurring
troubleshooting entry is a checker feature that has not been written yet.

---

# Limitations

> What Narro cannot do, and what to reach for instead
>
> Read this when: What can't Narro do, and what do I do instead?

Every entry here is something an author found by hitting it while writing a
deck. Knowing the shape of the box up front is worth more than discovering an
edge at the wrong moment, so this page is deliberately blunt.

If something is missing here and surprised you, that is a bug in this page.

Two restrictions that used to live here are gone, in case you have read an older
copy: the attribute syntax now accepts
[every Tailwind class](/docs/markdown-mode.md#which-tailwind-classes-it-accepts),
including arbitrary values, opacity modifiers and variants; and `Card`, `Badge`
and `Callout` exist, so a bordered panel or a pill is no longer hand-rolled.

## There is no diagram primitive

`Diagram` draws ASCII art. `FlowDiagram` and `ProcessFlowChart` draw linear step
chains. Nothing draws a nested tree, a mapping between two structures, or boxes
joined by labelled connectors — the shapes a technical deck asks for most.

This is the largest thing Narro does not have. It is not a small gap and this
page will not pretend otherwise.

**Instead:** build it out of containers and Tailwind. Every author who has hit
this reinvented the same thing, so here it is once, ready to paste. Nested `:::`
containers give the boxes; twelve lines of `deck.css` give the connectors.

```css
/* deck.css — a row of boxes joined by arrows. */
.rs-flow {
  display: flex;
  align-items: stretch;
  gap: 3rem;
}
.rs-flow > .rs-container {
  position: relative;
  display: flex;
  align-items: center;
}
/* The line, and then the head, both centred on the gap before each box after
   the first. `top: 50%` is load-bearing: without it an absolutely positioned
   pseudo-element falls to its static position, and the arrowhead lands under
   the line instead of on it. */
.rs-flow > .rs-container + .rs-container::before {
  content: "";
  position: absolute;
  top: 50%;
  right: 100%;
  width: 3rem;
  height: 2px;
  transform: translateY(-50%);
  background: currentColor;
  opacity: 0.35;
}
.rs-flow > .rs-container + .rs-container::after {
  content: "";
  position: absolute;
  top: 50%;
  right: calc(100% - 1px);
  transform: translateY(-50%);
  border: 7px solid transparent;
  border-left-color: currentColor;
  opacity: 0.35;
}
```

```markdown
:::{.rs-flow}

:::{.rounded-xl .border .border-white/20 .p-6}

**Deck**

:::

:::{.rounded-xl .border .border-white/20 .p-6}

**Compile**

:::

:::{.rounded-xl .border .border-white/20 .p-6}

**Slides**

:::

:::
```

For a **tree** rather than a row, nest the containers and swap `flex` for
`flex-col`, using `ml-8 border-l` on the children to draw the trunk. For anything
where the connectors cross — a mapping between two columns, a cascade that skips
a level — the honest answer is an SVG: draw it in whatever you draw diagrams in,
and use `![](./diagram.svg){.w-full}`. Nothing in Narro will do it for you.

## `Chart` is deliberately small

Bar, line, pie and donut, drawn with CSS and SVG. Bars can be horizontal or
vertical, can print their values, and can carry a `unit` or a `valueFormat`;
there is no axis, no gridline, no tooltip, no time series, and no stacking. A bar
chart therefore has no scale reference — the bars are proportional to each other
and to nothing else.

**Instead:** for anything analytical, render it with a real charting library and
put the result in a slide. `Chart` is for the one number a slide is about.

## Markdown mode cannot loop

There is no iteration, no reuse, and no reference-and-repeat. Twelve cards is
twelve containers: a twelve-item grid is around 120 lines of near-identical
markdown, and a change to the shape is twelve edits. Nothing about it is
*blocked* — it is just long, and it is the sharpest edge of the mode.

**Instead:** past about six repeated items, [MDX](/docs/markdown-mode.md#mdx) and
a `.map()` is 15 lines and one place to edit. One `import` in the deck preamble
buys it; the deck stays a markdown file.

## `check --fit` needs a browser

Every other check reads the compiled deck and needs nothing. `--fit` measures
real layout, so it needs Chromium — `npx playwright install chromium`, or point
`NARRO_CHROMIUM` at one your image already has. Without a browser it reports that
nothing was measured and, under `--strict`, fails; it never reports a pass it did
not verify.

There is no way to know a slide fits without rendering it, so there is no
browser-free version of this check to build.

## Markdown mode has no per-slide state

A slide cannot hold a value that changes as the audience watches — a selected
swatch, a filtered table, a live counter. `{.step}` reveals content that was
always there; it does not compute anything.

**Instead:** write a component and mount it. In a markdown deck, `import` it in
the preamble; the component is ordinary React and can hold whatever state it
likes.

## Reveal order is per slide, not per deck

`{.step}` and `<Fragment>` reveal in source order within their slide, and every
slide starts again from nothing. There is no deck-wide sequence, and no way to
carry a revealed state across a slide boundary.

## Two animation systems

CSS-keyframe components live in `@getnarro/shared-ui` (`Fragment`, `Animation`,
`AnimatedList`, `WordReveal`); Framer Motion components live in
`@getnarro/core` (`Motion`, `MotionText`, `MotionNumber`, `MotionSteps`). They
overlap — `CountingNumber` and `MotionNumber` both count, `TypewriterText` and
`MotionText type="typewriter"` both type — and their durations use different
units: milliseconds in shared-ui, seconds in core.

**Which to use:** the `Motion*` components when you want physics, spring easing
or layout animation; the shared-ui ones for a simple reveal. If you are
choosing between two components with similar names, they do the same thing and
either is fine.

**Mind the unit when you move a number between them.** `<Fragment duration={300}>`
is 300ms; `<Motion duration={300}>` is five minutes. The overlap is a deferred
decision and the unit mismatch is the sharp edge on it — check which package the
component came from before copying a duration across.

## No live data

A deck is a static build. Nothing polls, subscribes, or refetches on its own.

**Instead:** fetch in a component with `useEffect` like any React app, or bake
the number in at build time — which is usually what a deck wants, since a
presenter needs to know what the slide says before they say it.

## Export needs a browser

`narro export --pdf` and `--png` drive Playwright. In CI that means installing
it:

```bash
npm install -D playwright && npx playwright install chromium
```

**Without a browser:** `narro check deck.md --render` prints what each slide
renders — elements, classes and text — which covers "did that class land where
I meant" without a screenshot. It cannot tell you whether the slide *fits*; only
[`--fit`](#check---fit-needs-a-browser) can, and that needs the browser too.

## `Code` has no syntax highlighting

`Code` renders a styled block with the language recorded as a class and no
tokenising. For a deck where four slides carry code, that is a visible ceiling —
the clean example and the ugly one look equally grey.

**Instead:** highlight it yourself and drop the result in — Shiki's
`codeToHtml` at build time, or any highlighter that keys off the
`language-*` class the fence already carries.

## The runtime brings Framer Motion

`@getnarro/core` depends on `framer-motion`, and it ships whether or not a deck
uses a `Motion*` component. Measured: a three-slide markdown deck with no
components at all is **114 KB gzipped**, and adding a `<Motion>` to it costs
1 KB — which is the proof that the library was already there. A ten-slide deck
using a few `shared-ui` components lands around 130 KB. Almost none of that is
your content, and there is no lighter entry point.

**If bundle size is the point of your deck:** `narro bundle` produces one
self-contained HTML file, `narro export --png` produces images, and neither
carries a runtime at all.

## The npm name `narro` is someone else's

`npx narro` downloads an unrelated package. The CLI is `@getnarro/cli`, and
every Narro package is under the `@getnarro/` scope. There is no fix for this
beyond using the scoped name.

---

# React API

> Presentation, Slide, SlideContent, Notes, and the navigation hooks
>
> Read this when: Which component or hook do I import, and what does it take?

The structural components live in `@getnarro/core`. Full prop tables for every
component are in the [component reference](/docs/components), which is generated
from the types; this page covers the shape of the API and how the pieces fit.

## Presentation

The root container. Owns navigation, routing, keyboard and pointer handling, and
viewport scaling.

```tsx
import { Presentation } from "@getnarro/core";

<Presentation
  aspectRatio="16:9"
  keyboard
  mouse
  touch
  routing
  onSlideChange={(index) => console.log(index)}
>
  {/* slides */}
</Presentation>;
```

| Prop | Type | Default |
| --- | --- | --- |
| `children` | `ReactNode` | — |
| `aspectRatio` | `AspectRatio` | `"16:9"` |
| `autoPlay` | `number \| boolean \| number[]` | `false` |
| `autoPlayLoop` | `boolean` | `false` |
| `baseHeight` | `number` | `1080` |
| `baseWidth` | `number` | `1920` |
| `className` | `string` | — |
| `embedded` | `boolean` | `false` |
| `enableViewportScaling` | `boolean` | `true` |
| `favicon` | `string \| null` | — |
| `initialSlide` | `number` | `0` |
| `keepAwake` | `boolean` | `false` |
| `keyboard` | `boolean` | `true` |
| `maxDuration` | `number` | — |
| `mouse` | `boolean` | `true` |
| `onAutoPlayComplete` | `(() => void)` | — |
| `onSlideChange` | `((index: number) => void)` | — |
| `onSlidesData` | `((slides: SlideData[]) => void)` | — |
| `preserveAspectRatio` | `boolean` | `true` |
| `routing` | `boolean` | `true` |
| `showAutoPlayIndicator` | `boolean` | `false` |
| `sync` | `PresentationSync` | `false` |
| `theme` | `PresentationTheme` | — |
| `touch` | `boolean` | `true` |
| `transform` | `TransformConfig` | — |

## Slide

One slide. Give it an `id` if you want it linkable and stable across edits.

```tsx
<Slide id="intro" layout="title" className="bg-slate-900" transition="fade">
  {/* content */}
</Slide>
```

`layout` is "default" | "center" | "two-column" | "image" | "title".
`transition` is "none" | "fade" | "slide" | "zoom".

## SlideContent

Handles padding and vertical alignment inside a slide.

```tsx
<SlideContent layout="centered">{/* content */}</SlideContent>
```

`layout` here is "default" | "centered" | "top" | "bottom" — a **different**
set from `Slide`'s `layout`. The two are easy to confuse; `Slide` positions the
slide, `SlideContent` positions the content within it.

## Notes

Speaker notes. Renders nothing on the slide.

```tsx
<Slide id="intro">
  <SlideContent>…</SlideContent>
  <Notes>Open with the customer story, then the numbers.</Notes>
</Slide>
```

## Hooks

All hooks must be called inside a `<Presentation>`.

```tsx
import { useNavigation } from "@getnarro/core";

function ProgressBar() {
  const { currentSlide, totalSlides, next, previous, goToSlideById } = useNavigation();

  return <div style={{ width: `${((currentSlide + 1) / totalSlides) * 100}%` }} />;
}
```

`useNavigation()` returns the navigation state and its actions together:

**State** — `currentSlide`, `totalSlides`, `currentFragment`, `totalFragments`,
`currentSubSlide`, `totalSubSlides`, `isFirst`, `isLast`, `isOverviewMode`,
`isFullscreen`.

**Actions** — `next()`, `previous()`, `goToSlide(index)`,
`goToSlideById(id)`, `toggleFullscreen()`, `toggleOverviewMode()`,
`toggleAspectRatio()`.

Other exported hooks:

| Hook | For |
| --- | --- |
| `usePresentationContext()` | The raw `{ state, actions }` pair |
| `useSlideContext()` | The current slide's index and metadata |
| `useSlideActive()` | Whether the calling slide is on screen — use this to gate animation. Also exported by `@getnarro/shared-ui`; both read the context `Slide` provides |
| `useSlideIndex()` | The calling slide's index |
| `useFullscreen()` | Fullscreen state and toggle, outside a presentation |
| `useViewportScale()` | The current scale factor |
| `useWakeLock()` | Keep the screen awake while presenting |

There is no `usePresentation`, `useSlide`, or `useFragment` hook — those names
appeared in older documentation and were never exported.

---

# CLI

> narro new, dev, build, export, import, bundle, preview, themes
>
> Read this when: Which command do I run, and what are its flags?

```bash
npx @getnarro/cli <command>
```

Install it globally (`npm i -g @getnarro/cli`) and the binary is `narro`.

> `npx narro` resolves an unrelated package on npm. Use `npx @getnarro/cli`, or
> install globally and call `narro`.

## Commands

| Command | What it does |
| --- | --- |
| `narro analyze-slides-for-components` | Analyze presentation slides to identify needed shared-ui components |
| `narro build [file]` | Build for production (pass a .md file for markdown mode) |
| `narro bundle` | Bundle presentation into a single self-contained HTML file |
| `narro capture-website <url>` | Capture a full-page screenshot of a website |
| `narro check <file>` | Validate a markdown deck without building it |
| `narro comments` | Manage slide comments |
| `narro create [project-name]` | Create a new Narro presentation project |
| `narro create-template-from-screenshots [template-name]` | Generate a template from presentation screenshots using AI |
| `narro dev [file]` | Start development server (pass a .md file for markdown mode) |
| `narro export` | Export presentation to static files, PPTX, or Google Slides |
| `narro fmt <file>` | Normalise a deck's whitespace and frontmatter without changing what it renders |
| `narro import <source>` | Import presentation from PowerPoint or Google Slides |
| `narro new <file>` | Scaffold a starter markdown deck |
| `narro preview` | Preview built presentation |
| `narro themes` | Browse and apply themes from the marketplace |

## Reference

Generated from the command tree, so it cannot disagree with `narro --help`.

### `narro analyze-slides-for-components`

Analyze presentation slides to identify needed shared-ui components

| Option | For |
| --- | --- |
| `-d, --screenshots-dir <dir>` | Directory containing screenshot files |
| `-s, --screenshots <paths...>` | Screenshot file paths |
| `-o, --output <file>` | Output markdown file |
| `-p, --provider <provider>` | AI provider (openai or claude) |
| `-m, --model <model>` | AI model to use |

### `narro build [file]`

Build for production (pass a .md file for markdown mode)

| Option | For |
| --- | --- |
| `-o, --outDir <dir>` | output directory |
| `--base <path>` | base path for deployment |

### `narro bundle`

Bundle presentation into a single self-contained HTML file

| Option | For |
| --- | --- |
| `-o, --output <filename>` | output filename |
| `--minify` | minify output for smaller file size |
| `--inline-assets` | inline images as base64 (default: false) |
| `--check-size` | warn if output exceeds email attachment limit (~25MB) |

### `narro capture-website <url>`

Capture a full-page screenshot of a website

| Option | For |
| --- | --- |
| `-o, --output <path>` | Output file path (default: screenshot.png) |
| `-f, --full-page` | Capture full page (scrollable content) |
| `-w, --width <number>` | Viewport width in pixels |
| `-h, --height <number>` | Viewport height in pixels |
| `-d, --delay <number>` | Delay before screenshot in milliseconds |

### `narro check <file>`

Validate a markdown deck without building it

| Option | For |
| --- | --- |
| `--strict` | treat warnings as errors |
| `--render` | print what each slide renders — elements, classes, and text |
| `--fit` | render the deck in a headless browser and report slides whose content overflows |

### `narro comments`

Manage slide comments

### `narro create [project-name]`

Create a new Narro presentation project

| Option | For |
| --- | --- |
| `-t, --template <template>` | Template to use (minimal, corporate, developer, creative, bold-statement, visual-story, data-narrative, startup-pitch, tech-conference, template0, markdown-minimal, markdown-app, markdown-docs) |
| `-m, --mode <mode>` | Presentation mode: react (default) or markdown |
| `--skip-install` | Skip npm install |
| `--list` | List every template with what it is, and exit |

### `narro create-template-from-screenshots [template-name]`

Generate a template from presentation screenshots using AI

| Option | For |
| --- | --- |
| `-s, --screenshots <paths...>` | Screenshot file paths |
| `-o, --output <dir>` | Output directory |
| `-p, --provider <provider>` | AI provider (openai or claude) |
| `-m, --model <model>` | AI model to use |

### `narro dev [file]`

Start development server (pass a .md file for markdown mode)

| Option | For |
| --- | --- |
| `-p, --port <number>` | port to use |
| `--host` | expose to network |
| `-o, --open` | open browser on startup |
| `--no-open` | do not open the browser (markdown mode) |
| `--theme <name>` | theme override (markdown mode) |

### `narro export`

Export presentation to static files, PPTX, or Google Slides

| Option | For |
| --- | --- |
| `-o, --outDir <dir>` | output directory for HTML export |
| `--pdf` | export to PDF (requires Playwright) |
| `--png` | export slides as PNG images (requires Playwright) |
| `--to <format>` | export format: pptx, google-slides |
| `--output-path <path>` | output file path for PPTX export |
| `--include-notes` | include speaker notes in export |
| `--include-animations` | include animations in export |
| `--input-path <path>` | path to presentation project |
| `--template-path <path>` | PowerPoint template file (.potx or .pptx) to apply |
| `--template-id <id>` | Google Slides template presentation ID to copy from |
| `--google-client-id <id>` | Google OAuth client ID |
| `--google-client-secret <secret>` | Google OAuth client secret |
| `--google-refresh-token <token>` | Google OAuth refresh token |

### `narro fmt <file>`

Normalise a deck's whitespace and frontmatter without changing what it renders

| Option | For |
| --- | --- |
| `--check` | report whether the deck is formatted, and exit non-zero if not |

### `narro import <source>`

Import presentation from PowerPoint or Google Slides

| Option | For |
| --- | --- |
| `--from <source>` | import source: pptx, google-slides |
| `-o, --output-dir <dir>` | output directory for imported project |
| `--preserve-styles` | preserve original styles |
| `--convert-animations` | convert animations |
| `--google-client-id <id>` | Google OAuth client ID |
| `--google-client-secret <secret>` | Google OAuth client secret |
| `--google-refresh-token <token>` | Google OAuth refresh token |

### `narro new <file>`

Scaffold a starter markdown deck

### `narro preview`

Preview built presentation

| Option | For |
| --- | --- |
| `-p, --port <number>` | port to use |
| `--host` | expose to network |
| `-o, --open` | open browser on startup |

### `narro themes`

Browse and apply themes from the marketplace

## Notes

**`check` is the CI gate.** `narro check deck.md --strict` promotes warnings to
errors and exits non-zero, which is the step a pipeline runs — the scaffolded
markdown templates map their `lint` script to exactly that. Plain `check` exits 0
on warnings, which makes it the right form for the edit loop and the wrong form
for CI.

Three flags, three different questions:

| Flag | Answers |
| --- | --- |
| `--render` | What does the slide render, and did that class land on the word or the paragraph? No browser. |
| `--strict` | Is anything at all wrong, including the warnings? Exit code for CI. |
| `--fit` | Does the content fit the canvas? The only check that can see clipping, and the only one that needs a browser. |

**`--fit` and React mode.** `check` is markdown-only, but `--fit` measures built
output: `npm run build && npx @getnarro/cli check dist --fit` works for a React
deck and is the only fit check either mode has. It needs Chromium
(`npx playwright install chromium`); without one it says so and, under `--strict`,
fails rather than passing quietly. `NARRO_CHROMIUM=/path/to/chromium` points it at
a browser your image already has.

**Formatting.** Use `narro fmt`, not Prettier — a markdown formatter can reflow a
paragraph and move an attribute block onto its own line, which changes what it
styles with nothing to report it. See
[Formatting a deck](/docs/markdown-mode.md#formatting-a-deck).

**Scaffolding.** `npm create narro@latest my-deck` and `narro create my-deck`
run the same code. `narro new deck.md` is different: it writes a single markdown
file with no project around it.

**Markdown mode.** Passing a `.md` file to `dev` or `build` switches to markdown
mode, where no project or config file is needed — the CLI brings its own
runtime.

**Export fidelity.** A static build keeps animations, embeds, and live
components working. PPTX maps slides onto real PowerPoint shapes so text stays
editable, but anything driven by a live component becomes its rendered state.
PDF flattens fragments to their final state.

**Credentials.** Google Slides import and export need Google OAuth credentials
in the environment. `create-template-from-screenshots` and
`analyze-slides-for-components` call a hosted vision model and need
`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.

---

# Markdown API

> Reading, editing, validating, and compiling a deck from code — the four @getnarro/markdown entry points
>
> Read this when: How do I read, edit, or validate a deck file from my own code instead of by hand?

`@getnarro/markdown` is a library, not only a file format. The CLI's `check`,
`dev`, and `build`, the MCP server's slide-editing tools, and this
documentation's own generators are all built on the exports below — none of them
parses a deck by hand.

Reach for it when you are writing something that produces or edits decks: a
generator, an importer, a lint rule, a CMS integration, an agent tool.

## Four entry points

The specifier matters, and the split is by *where the code runs*, not by topic.
The root is Node-safe — it pulls in no React — which is why `narroMarkdown`,
`DeckShell`, and the layout components are not there. Reaching for one of those
from `@getnarro/markdown` fails at resolution.

The exception worth knowing: the shared **types** (`SlideLayoutProps`,
`SlideLayout`, `DeckFrontmatter`, `SlideFrontmatter`) are re-exported from both
the root and `/runtime`, because a layout component needs them and a Node-side
tool inspecting a deck does too. Either import works.

| Import from | Use it for | Runs in |
| --- | --- | --- |
| `@getnarro/markdown` | Parsing, editing, validating, compiling | Node — no React, no DOM |
| `@getnarro/markdown/vite` | The build plugin | Node, at build time |
| `@getnarro/markdown/runtime` | Rendering a compiled deck | The browser |
| `@getnarro/markdown/layouts` | The built-in layout components and registry | The browser |

Every **runtime** export, read out of the built modules rather than transcribed:

- `@getnarro/markdown` — `BUILTIN_THEME`, `CompileError`, `FrontmatterError`, `TEMPLATE_EXTENSIONS`, `TemplateError`, `applyTemplateToSlide`, `buildDeckModule`, `builtinLayoutNames`, `builtinLayoutSlots`, `closest`, `compileAndValidate`, `compileDeck`, `compileMdx`, `compileSlide`, `deckFrontmatterJsonSchema`, `deckFrontmatterKeys`, `defineTemplate`, `discoverTemplatePath`, `emptySlideFrontmatter`, `extractNotes`, `formatDiagnostics`, `interpolate`, `isBuiltinLayout`, `isReservedKey`, `loadTemplateFile`, `parseDeckDocument`, `parseDeckFrontmatter`, `parseSlideFrontmatter`, `parseTemplate`, `parseYamlObject`, `resolveDeckTemplate`, `serializeDeckDocument`, `slideFrontmatterJsonSchema`, `slideFrontmatterKeys`, `slideFrontmatterOf`, `slideId`, `slideTitle`, `slotsForBuiltinLayout`, `splitDeck`, `splitSlots`, `templateCss`, `templateJsonSchema`, `templateLayout`, `templateLayoutNames`, `templateLayoutRuntime`, `templateLayoutSlots`, `templateSchema`, `templateSlotMap`, `tokensCss`, `validateCompiledDeck`, `validateDeck`, `validateTemplate`
- `@getnarro/markdown/vite` — `narroMarkdown`
- `@getnarro/markdown/runtime` — `DeckMetaContext`, `DeckShell`, `DeckSlide`, `RsStep`, `SlideChrome`, `createTemplateLayout`, `deckMetaFrom`, `defaultMdxComponents`, `renderDeck`, `useDeckMeta`
- `@getnarro/markdown/layouts` — `CoverLayout`, `DefaultLayout`, `EndLayout`, `ImageFullLayout`, `ImageRightLayout`, `QuoteLayout`, `SectionLayout`, `ThreeColumnLayout`, `TwoColumnLayout`, `builtinLayoutNames`, `builtinLayouts`

Type-only exports are erased at runtime, so they do not appear in that list. The
ones you are most likely to reach for, and where each lives — the shipped
`.d.ts` for each entry point is the complete answer:

| Type | Import from |
| --- | --- |
| `ParsedDeck`, `ParsedSlideSource` | `@getnarro/markdown` |
| `DeckDocument`, `RawSlide` | `@getnarro/markdown` |
| `CompiledDeck`, `CompiledSlide`, `CompiledSlot`, `CompileOptions` | `@getnarro/markdown` |
| `Diagnostic`, `DiagnosticSeverity`, `ValidateOptions` | `@getnarro/markdown` |
| `Slot`, `JsonSchema` | `@getnarro/markdown` |
| `BuiltinLayoutName` | `@getnarro/markdown` or `/layouts` |
| `DeckFrontmatter`, `SlideFrontmatter`, `SlideLayout`, `SlideLayoutProps` | `@getnarro/markdown` or `/runtime` |
| `DeckShellProps`, `DeckSlideProps`, `DeckData`, `DeckSlideData`, `MdxComponents` | `@getnarro/markdown/runtime` |
| `NarroMarkdownOptions`, `ResolvedTheme` | `@getnarro/markdown/vite` |

## Reading a deck: two functions, and they are not interchangeable

This is the distinction to get right before anything else.

```ts
import { parseDeckDocument, splitDeck } from "@getnarro/markdown";

splitDeck(source);          // for rendering — frontmatter parsed into objects
parseDeckDocument(source);  // for editing — frontmatter kept as its original text
```

`splitDeck` returns a `ParsedDeck`: deck frontmatter as a typed object, the
shared MDX preamble, and one `ParsedSlideSource` per slide with its parsed
frontmatter and 1-based `startLine`. It is the right shape for compiling or
inspecting, and it **loses the original YAML text** — reserialising from it
would reformat every slide in the file.

`parseDeckDocument` returns a `DeckDocument`: the same fence-aware split, but
frontmatter and body as verbatim strings. It round-trips:

```ts
serializeDeckDocument(parseDeckDocument(source)) === source;   // true
```

That guarantee is what makes programmatic editing safe. A tool can splice one
slide and write the file back without touching the other forty, which is the
difference between an edit a human will accept in review and a whole-file
reformat.

One caveat: line endings are normalised to `\n` on parse, so a CRLF file
round-trips to LF rather than byte for byte. Everything else — spacing, YAML
key order, comments, trailing whitespace — is preserved.

Both are fence-aware: a `---` inside a fenced code block never splits a slide.

## Editing a deck

`DeckDocument.slides` is a plain array of `{ frontmatterText, body }`, so
insertion, deletion, and reordering are array operations:

```ts
import {
  parseDeckDocument,
  serializeDeckDocument,
  slideId,
  slideTitle,
} from "@getnarro/markdown";

const doc = parseDeckDocument(await readFile("deck.md", "utf8"));

// Where does the slide about revenue live?
const index = doc.slides.findIndex((slide) => slideTitle(slide)?.includes("Revenue"));

// Insert after it.
doc.slides.splice(index + 1, 0, {
  frontmatterText: "layout: section\nid: outlook",
  body: "\n## Outlook\n",
});

await writeFile("deck.md", serializeDeckDocument(doc));
```

| Function | Returns |
| --- | --- |
| `slideFrontmatterOf(slide)` | The slide's frontmatter parsed into a `SlideFrontmatter`, without disturbing the stored text |
| `slideId(slide, index)` | The slide's `id`, or `slide-<index + 1>` when it has none |
| `slideTitle(slide)` | The first heading in the body, with any trailing `{.attribute}` block stripped — or `undefined` |

`slideId` taking the index is deliberate: a deck where only some slides set `id`
still needs a stable key for every slide, and the caller always knows the
position. Address slides by `id` where one exists — an index shifts the moment a
slide is inserted above it, which is why `narro new` and the templates set `id`
on slides worth returning to.

## Validating

`validateDeck` is what `narro check` runs. It returns diagnostics rather than
throwing, so an author who mistyped three layout names learns all three in one
pass.

```ts
import { formatDiagnostics, splitDeck, validateDeck } from "@getnarro/markdown";
import { themes } from "@getnarro/marketplace";

const diagnostics = validateDeck(splitDeck(source), {
  extraLayouts: ["hero", "compare"],          // layouts the host can resolve
  availableThemes: themes.map((t) => t.id),   // omit to skip the theme check
  knownDeckKeys: deckFrontmatterKeys,         // omit to skip the key check
});

if (diagnostics.length > 0) console.log(formatDiagnostics(diagnostics, "deck.md"));
```

Each `Diagnostic` carries `severity` (`"error"` or `"warning"`), an optional
zero-based `slide`, an optional 1-based `line`, and a `message`.

Three things it catches, none of which is a parse error and none of which used
to stop a build:

| Mistake | What happened without validation |
| --- | --- |
| `layout: sidebar-left` — no such layout | The plugin emitted a `throw` into the generated module, so the build succeeded and the deck failed in the browser |
| `::rihgt::` — a mistyped slot | Content attached to a prop no layout reads, and never rendered |
| `aspectRation: "16:9"` — a mistyped deck key | Preserved as an unknown extra and ignored |

Every option is opt-in because each needs knowledge the library does not have:
which layouts the host can resolve, which themes are installed. Omitting one
skips that check rather than guessing.

`closest(value, candidates)` is exported separately — it is the "did you mean?"
matcher, and it is worth reusing so your tool's suggestions match the CLI's.

Severity is chosen deliberately: an unrecognised **deck** key is a warning, not
an error, because a theme is allowed to define its own keys. Pass `strict` to
the Vite plugin to promote warnings.

## Compiling

```ts
import { compileDeck } from "@getnarro/markdown";

const compiled = await compileDeck(parsed, { path: "/abs/deck.md", dev: true });
```

`compileDeck` turns a `ParsedDeck` into a `CompiledDeck`: per slide, its
`index`, `id`, resolved `layout` name, `frontmatter`, extracted `notes`, and one
`CompiledSlot` per slot — each carrying generated ESM module `code` rather than
a React element, so the caller decides how to load it.

`compileSlide` and `compileMdx` are the same machinery at slide and fragment
granularity. `dev: true` emits `jsx-dev-runtime` calls with source positions.

Failures throw `CompileError`, which carries `slideIndex` so a caller can point
at the slide rather than the file.

`buildDeckModule` assembles the ESM module the Vite plugin serves; you need it
only if you are replacing that plugin.

## Frontmatter

```ts
import {
  deckFrontmatterKeys,
  parseDeckFrontmatter,
  parseSlideFrontmatter,
  slideFrontmatterKeys,
} from "@getnarro/markdown";
```

Both parsers preserve unrecognised keys on `extra` rather than dropping or
rejecting them — deck-level for the theme to read, slide-level forwarded to the
layout component as props. `emptySlideFrontmatter()` gives you the zero value,
and `parseYamlObject` is the underlying reader.

The recognised keys are
`title`, `author`, `date`, `theme`, `template`, `aspectRatio`, `transition`, `class`, `keyboard`, `mouse`, `touch`, `routing`, `favicon`, `maxDuration`
for a deck and
`layout`, `class`, `id`, `transition`, `background`, `notes`
for a slide.

`deckFrontmatterJsonSchema()` and `slideFrontmatterJsonSchema()` return the same
contract as JSON Schema, built from the same zod objects the parser validates
against — so the published schema cannot describe a key the parser rejects. They
are served at:

- <https://getnarro.com/schema/deck-frontmatter.schema.json>
- <https://getnarro.com/schema/slide-frontmatter.schema.json>

Both set `additionalProperties: true`, because forbidding unknown keys would
contradict the `extra` behaviour above.

## Layouts

```ts
import { builtinLayoutNames, slotsForBuiltinLayout } from "@getnarro/markdown";
import { builtinLayouts } from "@getnarro/markdown/layouts";
```

`builtinLayoutSlots` is the source of truth for both. Ask it rather than
hardcoding a table — this page's own layout table was hand-maintained once and
was wrong about three of nine rows.

`slotsForBuiltinLayout(name)` returns the slot names or `undefined` if the name
is not built in, which is also how you test for a built-in without a second
lookup. `isBuiltinLayout` is the type guard.

The full table of names and slots is on the
[markdown mode](/docs/markdown-mode#layouts) page.

## Runtime

```tsx
import { DeckShell, DeckSlide, renderDeck } from "@getnarro/markdown/runtime";
import type { SlideLayoutProps } from "@getnarro/markdown/runtime";
```

`renderDeck(deck)` is the one-call path: it renders a `DeckShell` wrapping one
`DeckSlide` per slide, and is what the generated deck module calls.

`DeckShell` configures a core `Presentation` from deck frontmatter — `keyboard`,
`mouse`, `touch`, and `routing` all default to `true`, `aspectRatio` to `"16:9"`.
`DeckSlide` renders one slide: it takes the resolved `layout` component, the
per-slot compiled components (`default` is required), the frontmatter, and
optional `components` for user-provided MDX scope.

`SlideLayoutProps` is what a layout component receives: `children` is the
default slot, `frontmatter` is the resolved slide frontmatter including
forwarded `extra` keys, and every named slot arrives as a `ReactNode` prop
under its own name.

`RsStep` and `defaultMdxComponents` are the fragment plumbing — see
[markdown mode](/docs/markdown-mode#fragments) for what `{.step}` compiles to.

## The Vite plugin

```ts
import { narroMarkdown } from "@getnarro/markdown/vite";
```

| Option | Type | Default | For |
| --- | --- | --- | --- |
| `deckPath` | `string` | required | Absolute path to the deck `.md` |
| `theme` | `ResolvedTheme` | — | The resolved theme, whose layouts shadow the built-ins |
| `themeResolver` | `(name: string) => ResolvedTheme \| undefined` | — | How to resolve the deck's own `theme:` key |
| `templatePath` | `string` | — | The [deck template](/docs/deck-templates), overriding both the deck's `template:` key and the file found beside it |
| `dev` | `boolean` | `true` | Development mode |
| `cssResolveDir` | `string` | the deck's directory | Where `@import "tailwindcss"` resolves from — set it when the deck directory has no `node_modules` |
| `availableThemes` | `readonly string[]` | — | Theme names the host can resolve, so a deck naming a missing one fails the build. Omit to skip the check |
| `strict` | `boolean` | `false` | Treat validation warnings as errors |

`narroMarkdown` is also the entry point's default export, so
`import narroMarkdown from "@getnarro/markdown/vite"` works too.

The plugin exposes two virtual modules: `virtual:narro/deck` (the compiled deck)
and `virtual:narro/deck.css` (its stylesheet).

`strict` is off by default for the reason given above — an unrecognised deck key
is usually a theme's, not a typo. Turn it on in CI, where a typo should not
merge.

## Layout resolution order

The plugin resolves a `layout:` name in this order, first match winning:

1. `<deckDir>/layouts/<name>.{tsx,jsx,mdx,ts,js}` — yours, shadows everything
2. The [deck template](/docs/deck-templates)'s layouts
3. The active theme's layouts
4. The built-ins

Shadowing is by name, so defining `layouts/two-column.tsx` replaces the built-in
of that name for the whole deck without renaming any slide.

A template layout resolves to its own `base` plus its region wrappers, and that
base is looked up in steps 1 and 4 only — layouts on a master do not chain, so
there is no cycle to detect.

## Deck templates

```ts
import {
  type DeckTemplate,
  applyTemplateToSlide,
  loadTemplateFile,
  resolveDeckTemplate,
  templateSlotMap,
  tokensCss,
  validateTemplate,
} from "@getnarro/markdown";
```

`resolveDeckTemplate(deckPath, frontmatter)` is the whole entry point: it honours
the deck's `template:` key, falls back to discovery beside the deck, and returns
the parsed template with the path it came from. `validateTemplate` reports the
names in it that do not resolve, `templateSlotMap` produces the `layoutSlots`
`validateDeck` takes, and `applyTemplateToSlide` produces what a slide inherits —
classes, background, frontmatter defaults, and the resolved placeholders.

The build calls them in that order; so does `narro check`. See
[deck templates](/docs/deck-templates) for the file itself.

---

# Component Reference

> Every component in @getnarro/core and @getnarro/shared-ui, with its props
>
> Read this when: What props does this component take, and which package do I import it from?

<!-- Generated by scripts/generate.mjs from the TypeScript source. Do not edit. -->

80 components ship across two packages. Props below are read
out of the type definitions, so they match the installed version exactly.

## @getnarro/core

### `<AnimatePresence>`

`AnimatePresence` enables the animation of components that have been removed from the tree. When adding/removing more than a single child, every child **must** be given a unique `key` prop. Any `motion` components that have an `exit` property defined will animate out when removed from the tree. ```jsx import { motion, AnimatePresence } from 'framer-motion' export const Items = ({ items }) => ( <AnimatePresence> {items.map(item => ( <motion.div key={item.id} initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} /> ))} </AnimatePresence> ) ``` You can sequence exit animations throughout a tree using variants. If a child contains multiple `motion` components with `exit` props, it will only unmount the child once all `motion` components have finished animating out. Likewise, any components using `usePresence` all need to call `safeToRemove`.

```tsx
import { AnimatePresence } from "@getnarro/core";
```

### `<Canvas>`

A container for absolutely positioned elements

```tsx
<Canvas>
  <CanvasElement x={10} y={20} width={200} height={100}>
    <div>Positioned content</div>
  </CanvasElement>
  <CanvasShape shape="circle" x={50} y={50} size={100} color="#3b82f6" />
</Canvas>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children elements to position |
| `background` | `string` | — | Background color |
| `className` | `string` | — | Additional CSS classes |
| `height` | `string` | — | Height of the canvas (default: 100%) |
| `width` | `string` | — | Width of the canvas (default: 100%) |

### `<CanvasElement>`

A positioned element within a Canvas

```tsx
<CanvasElement x={10} y={20} width={200} height={100}>
  <div>Positioned at 10%, 20%</div>
</CanvasElement>
```

```tsx
Using pixels:
```tsx
<CanvasElement x="100px" y="50px" width="200px" height="100px">
  <div>Positioned at 100px, 50px</div>
</CanvasElement>
```
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children content |
| `x` | `PositionValue` | yes | X position (% or px) |
| `y` | `PositionValue` | yes | Y position (% or px) |
| `className` | `string` | — | Additional CSS classes |
| `height` | `PositionValue` | — | Height (% or px, optional) |
| `opacity` | `number` | — | Opacity (0-1) |
| `rotate` | `number` | — | Rotation in degrees |
| `width` | `PositionValue` | — | Width (% or px, optional) |
| `zIndex` | `number` | — | Z-index for layering |

### `<CanvasShape>`

A pre-built shape positioned on the Canvas

```tsx
<Canvas>
  <CanvasShape shape="circle" x={50} y={50} size={100} color="#3b82f6" />
  <CanvasShape shape="star" x={200} y={100} size={80} color="#fbbf24" />
  <CanvasShape shape="arrow" x={300} y={50} size={120} color="#10b981" rotate={45} />
</Canvas>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `shape` | `ShapeType` | yes | Shape type |
| `size` | `number` | yes | Size of the shape |
| `x` | `PositionValue` | yes | X position (% or px) |
| `y` | `PositionValue` | yes | Y position (% or px) |
| `className` | `string` | — | Additional CSS classes |
| `color` | `string` | — | Fill color |
| `opacity` | `number` | — | Opacity (0-1) |
| `rotate` | `number` | — | Rotation in degrees |
| `stroke` | `string` | — | Stroke color |
| `strokeWidth` | `number` | — | Stroke width |
| `zIndex` | `number` | — | Z-index for layering |

### `<ErrorBoundary>`

Error Boundary component that catches errors and displays the overlay

```tsx
<ErrorBoundary onError={(error) => console.error(error)}>
  <Presentation>
    <Slide>...</Slide>
  </Presentation>
</ErrorBoundary>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children to render |
| `fallback` | `ReactNode \| ((error: ErrorDetails, reset: () => void) => ReactNode)` | — | Fallback component to render on error (optional, defaults to ErrorOverlay) |
| `onError` | `((error: Error, errorInfo: ErrorInfo) => void)` | — | Callback when an error occurs |
| `showOverlay` | `boolean` | — | Enable development overlay (default: true in dev, false in prod) |

### `<ErrorOverlay>`

Error overlay component for development

```tsx
<ErrorOverlay
  error={{
    message: "Something went wrong",
    stack: "Error: Something went wrong\n  at Component ..."
  }}
  onDismiss={() => setError(null)}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `ErrorDetails` | yes | Error details to display |
| `onDismiss` | `(() => void)` | — | Callback to dismiss/reset the error |
| `showDismiss` | `boolean` | — | Show dismiss button (default: true) |

### `<MarqueeRow>`

One scrolling row of a marquee. Usually you want `TrustedByMarquee`, which arranges several of these.

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `MarqueeItem[]` | yes | Items to display in the marquee |
| `className` | `string` | — | Additional CSS class for the container |
| `direction` | `"left" \| "right"` | — | Scroll direction |
| `gap` | `number` | — | Gap between items in pixels (default: 16) |
| `isActive` | `boolean` | — | Whether the animation is active |
| `itemMinWidth` | `number` | — | Item minimum width in pixels (default: 180) |
| `renderItem` | `((item: MarqueeItem, index: number) => ReactNode)` | — | Custom item render function |
| `speed` | `number` | — | Scroll speed (pixels per frame, default: 0.5) |

### `<MasonryBackground>`

A full-bleed masonry grid of images that crossfades between them. Pauses while its slide is off screen, so an idle deck does no work.

```tsx
<MasonryBackground
  images={["/a.jpg", "/b.jpg", "/c.jpg"]}
  gridColumns={12}
  gridRows={6}
  swapMinIntervalMs={3000}
  swapMaxIntervalMs={6000}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `images` | `string[]` | yes | Array of image URLs to display and cycle through |
| `backgroundColor` | `string` | — | Background color (default: "black") |
| `className` | `string` | — | Additional CSS class for the container |
| `gridColumns` | `number` | — | Number of grid columns (default: 12) |
| `gridRows` | `number` | — | Number of grid rows (default: 6) |
| `imageBorderColor` | `string` | — | Border color for images (default: "rgba(255, 255, 255, 0.6)") |
| `imageBorderWidth` | `string` | — | Border width for images (default: "1px") |
| `imageGap` | `number` | — | Gap between images in pixels (default: 6) |
| `initialFillTimeMs` | `number` | — | Time in ms to fill the page with initial images (default: 800) |
| `isActive` | `boolean` | — | Whether the animation is active |
| `swapMaxIntervalMs` | `number` | — | Maximum time in ms between image swaps after initial fill (default: 2000) |
| `swapMinIntervalMs` | `number` | — | Minimum time in ms between image swaps after initial fill (default: 1000) |
| `tileLayout` | `TileLayout[]` | — | Grid tile layout configuration |
| `transitionDurationMs` | `number` | — | Duration of crossfade transition in ms (default: 800) |

### `<Motion>`

A Framer Motion animation wrapper Provides smooth, physics-based animations with 10+ built-in effects.

```tsx
<Motion effect="slideUp" duration={0.5}>
  <h1>Animated Title</h1>
</Motion>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children to animate |
| `className` | `string` | — | Additional class names |
| `delay` | `number` | — | Animation delay in seconds |
| `duration` | `number` | — | Animation duration in seconds |
| `easing` | `MotionEasing` | — | Easing function |
| `effect` | `MotionEffect` | — | Animation effect to apply |
| `inView` | `boolean` | — | Whether to trigger animation only when in view |
| `isActive` | `boolean` | — | Whether animation has played (for controlled animations) |
| `onAnimationComplete` | `(() => void)` | — | Callback when animation completes |
| `respectReducedMotion` | `boolean` | — | Enable reduced motion fallback |
| `style` | `CSSProperties` | — | Additional styles |

### `<MotionContainer>`

Container for staggered child animations

```tsx
<MotionContainer staggerDelay={0.1}>
  <Motion effect="slideUp">Item 1</Motion>
  <Motion effect="slideUp">Item 2</Motion>
  <Motion effect="slideUp">Item 3</Motion>
</MotionContainer>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children to animate with stagger |
| `className` | `string` | — | Additional class names |
| `isActive` | `boolean` | — | Whether children should animate |
| `staggerDelay` | `number` | — | Stagger delay between children in seconds |
| `style` | `CSSProperties` | — | Additional styles |

### `<MotionList>`

MotionList - Staggered list animation

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `ReactNode[]` | yes | List items |
| `className` | `string` | — | Additional class names for container |
| `effect` | `MotionEffect` | — | Animation effect for each item |
| `isActive` | `boolean` | — | Whether animations are active |
| `itemClassName` | `string` | — | Additional class names for items |
| `listStyle` | `"none" \| "disc" \| "decimal" \| "check"` | — | List style type |
| `staggerDelay` | `number` | — | Stagger delay between items in seconds |

### `<MotionNumber>`

Animated number counter

```tsx
<MotionNumber value={1000000} prefix="$" separator duration={2} />
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number` | yes | Target value |
| `className` | `string` | — | Additional class names |
| `decimals` | `number` | — | Number of decimal places |
| `delay` | `number` | — | Delay before starting |
| `duration` | `number` | — | Animation duration in seconds |
| `isActive` | `boolean` | — | Whether animation is active |
| `prefix` | `string` | — | Prefix (e.g., "$") |
| `separator` | `boolean` | — | Use thousands separator |
| `style` | `CSSProperties` | — | Additional styles |
| `suffix` | `string` | — | Suffix (e.g., "%") |

### `<MotionPresence>`

MotionPresence - Wrapper for AnimatePresence with slide-aware animations

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children to animate |
| `mode` | `"sync" \| "wait" \| "popLayout"` | — | Animation mode |
| `presenceKey` | `string` | — | Custom key for tracking |

### `<MotionSpotlight>`

Apple Keynote-style Magic Move for images Creates smooth zoom and pan animations between slides. Uses Framer Motion's layout animations for seamless morphing.

```tsx
// Slide 1 - Overview
<MotionSpotlight
  layoutId="product"
  src="/product.jpg"
  alt="Product"
  x={50} y={50} scale={1}
  width={800} height={400}
/>

// Slide 2 - Zoomed
<MotionSpotlight
  layoutId="product"
  src="/product.jpg"
  alt="Product detail"
  x={25} y={50} scale={2.5}
  width={800} height={400}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `alt` | `string` | yes | Alt text for accessibility |
| `src` | `string` | yes | Image source URL |
| `borderRadius` | `string \| number` | — | Border radius |
| `className` | `string` | — | Additional class names |
| `duration` | `number` | — | Animation duration in seconds |
| `height` | `string \| number` | — | Container height |
| `isActive` | `boolean` | — | Whether currently active |
| `layoutId` | `string` | — | Unique ID for cross-slide morphing |
| `onAnimationComplete` | `(() => void)` | — | Callback when animation completes |
| `scale` | `number` | — | Scale/zoom level |
| `shadow` | `boolean` | — | Show shadow |
| `width` | `string \| number` | — | Container width |
| `x` | `number` | — | X position as percentage (0-100) |
| `y` | `number` | — | Y position as percentage (0-100) |

### `<MotionStep>`

Individual step within MotionSteps container Shows when the current step is >= this step's number.

```tsx
<MotionStep step={1} effect="scaleUp">
  <div>This appears on step 1</div>
</MotionStep>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children to animate |
| `step` | `number` | yes | Step number (0-indexed) - element shows when currentStep >= this value |
| `className` | `string` | — | Additional class name |
| `duration` | `number` | — | Animation duration in seconds |
| `easing` | `MotionEasing` | — | Easing function |
| `effect` | `MotionEffect` | — | Animation effect when revealed |
| `style` | `CSSProperties` | — | Additional styles |

### `<MotionSteps>`

Container for step-by-step animations triggered by keystrokes Wrap MotionStep children to create a sequence of animations. Press arrow keys (right/down) to advance, (left/up) to go back.

```tsx
<MotionSteps totalSteps={3}>
  <MotionStep step={0} effect="scaleUp">
    <div>First element (visible immediately)</div>
  </MotionStep>
  <MotionStep step={1} effect="slideRight">
    <div>Second element (press arrow key)</div>
  </MotionStep>
  <MotionStep step={2} effect="elastic">
    <div>Third element (press again)</div>
  </MotionStep>
</MotionSteps>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children - should be MotionStep components |
| `className` | `string` | — | Additional class name |
| `loop` | `boolean` | — | Whether to loop back to start after last step |
| `onComplete` | `(() => void)` | — | Callback when all steps are complete |
| `startStep` | `number` | — | Starting step (0-indexed) |
| `totalSteps` | `number` | — | Total number of steps |

### `<MotionText>`

Animated text with various effects

```tsx
<MotionText type="typewriter" duration={0.05}>
  Hello, World!
</MotionText>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `string` | yes | Text content |
| `className` | `string` | — | Additional class names |
| `delay` | `number` | — | Delay before starting in seconds |
| `duration` | `number` | — | Animation duration per unit in seconds |
| `isActive` | `boolean` | — | Whether animation is active |
| `style` | `CSSProperties` | — | Additional styles |
| `type` | `"blur" \| "typewriter" \| "wave" \| "wordByWord" \| "charByChar"` | — | Animation type |

### `<MotionTransform>`

Applies cumulative transforms to a single element across steps Use this inside MotionSteps to animate the SAME element through multiple transformation states (fade, zoom, move, rotate, etc.)

```tsx
<MotionSteps totalSteps={4}>
  <MotionTransform
    transforms={[
      { opacity: 0 },                           // Step 0 (hidden)
      { opacity: 1 },                           // Step 1 (fade in)
      { opacity: 1, scale: 1.5 },              // Step 2 (zoom)
      { opacity: 1, scale: 1.5, x: 150 },      // Step 3 (move right)
    ]}
  >
    <div className="w-64 h-64 bg-blue-500">
      Transform me!
    </div>
  </MotionTransform>
</MotionSteps>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children to transform |
| `transforms` | `TransformState[]` | yes | Array of transform states for each step |
| `className` | `string` | — | Additional class name |
| `duration` | `number` | — | Animation duration in seconds |
| `easing` | `MotionEasing` | — | Easing function |
| `style` | `CSSProperties` | — | Additional styles |

### `<NebulaBackground>`

An animated starfield with nebula glow, behind whatever you put in it.

```tsx
<NebulaBackground isActive>
  <Heading level={1}>Title over the stars</Heading>
</NebulaBackground>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `backgroundGradient` | `string` | — | Background gradient (CSS value) |
| `children` | `ReactNode` | — | Children to render on top of the background |
| `className` | `string` | — | Additional CSS class for the container |
| `isActive` | `boolean` | — | Whether the animation is active |
| `nebulaColors` | `NebulaGlow[]` | — | Nebula glow effects configuration |
| `shootingStarDuration` | `number` | — | Duration of shooting star animation in ms (default: 2000) |
| `shootingStarFrequency` | `number` | — | Time between shooting stars in ms (default: 3000) |
| `starColors` | `StarColor[]` | — | Star color distribution |
| `starLayers` | `StarLayer[]` | — | Star layer configuration |
| `twinkleSpeed` | `{ min: number; max: number; }` | — | Twinkle speed range in ms |

### `<Notes>`

Notes component - Speaker notes Notes are not rendered in the main presentation view. They are meant to be displayed in presenter mode or exported separately.

```tsx
<Slide>
  <h1>My Slide Title</h1>
  <Notes>
    Remember to explain the key points here.
    - Point 1
    - Point 2
  </Notes>
</Slide>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Speaker notes content |

### `<OverviewGrid>`

OverviewGrid component - Displays slides in a grid for quick navigation

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | `NavigationActions` | yes | Navigation actions |
| `slidesData` | `SlideData[]` | yes | Slides data for rendering previews |
| `state` | `NavigationState` | yes | Navigation state |

### `<Presentation>`

Presentation component - Root container

```tsx
<Presentation>
  <Slide id="intro">
    <h1>Welcome</h1>
  </Slide>
  <Slide id="content">
    <h2>Main Content</h2>
  </Slide>
</Presentation>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children slides |
| `aspectRatio` | `AspectRatio` | — | Aspect ratio (default: "16:9") |
| `autoPlay` | `number \| boolean \| number[]` | — | Enable auto-play mode to automatically advance slides. Can be a boolean (uses default 5000ms interval) or a number specifying the interval in milliseconds. Can also be an array of numbers specifying the interval for each slide. |
| `autoPlayLoop` | `boolean` | — | Whether to loop back to the first slide when auto-play reaches the end. Default: false |
| `baseHeight` | `number` | — | Base height for viewport scaling (default: 1080). Content scales proportionally from this baseline |
| `baseWidth` | `number` | — | Base width for viewport scaling (default: 1920). Content scales proportionally from this baseline |
| `className` | `string` | — | Additional CSS classes |
| `embedded` | `boolean` | — | Enable embedded mode for presentations in smaller containers. When true, viewport scaling uses container size instead of window size. Useful for embedding presentations in modals, cards, or side panels. |
| `enableViewportScaling` | `boolean` | — | Enable viewport scaling (default: true). Scales content based on viewport size for responsive presentations |
| `favicon` | `string \| null` | — | Favicon URL or data URI for the presentation. Can be a path to an image file, a data URI, or undefined to use the default Narro favicon. Set to `null` to disable favicon management (keep existing favicon). |
| `initialSlide` | `number` | — | Initial slide index |
| `keepAwake` | `boolean` | — | Keep the screen awake while the presentation is open (Screen Wake Lock API, best-effort). Useful so the projector/laptop never sleeps mid-talk. Default: false |
| `keyboard` | `boolean` | — | Enable keyboard navigation (default: true) |
| `maxDuration` | `number` | — | Optional maximum duration in minutes for countdown timer in presenter panel |
| `mouse` | `boolean` | — | Enable mouse navigation (default: true) |
| `onAutoPlayComplete` | `(() => void)` | — | Callback when auto-play reaches the last slide and completes. Only called when autoPlay is enabled. |
| `onSlideChange` | `((index: number) => void)` | — | Callback when slide changes |
| `onSlidesData` | `((slides: SlideData[]) => void)` | — | Callback invoked with the registered slide data whenever the slide set changes. Useful for building companion views (notes, overviews) that need access to slide content and speaker notes. |
| `preserveAspectRatio` | `boolean` | — | Preserve aspect ratio (default: true). When false, slides fill viewport |
| `routing` | `boolean` | — | Enable URL-based routing (default: true) |
| `showAutoPlayIndicator` | `boolean` | — | Show an auto-play indicator icon at the bottom right of the presentation. Shows a play/pause icon during playback and a replay icon when complete. Clicking the replay icon restarts the presentation. Default: false |
| `sync` | `PresentationSync` | — | Broadcast the current slide to a presenter-sync relay so companion views (e.g. a speaker-notes window on a different port) can follow along live. Pass `true` to use the default relay URL, or an object to customise it. Default: false |
| `theme` | `PresentationTheme` | — | Theme configuration for the presentation |
| `touch` | `boolean` | — | Enable touch navigation (default: true) |
| `transform` | `TransformConfig` | — | Transform-based animation configuration |

### `<PresenterNotes>`

PresenterNotes component - live speaker-notes companion view.

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | The same slide elements rendered by the deck. Their inline `<Notes>` are harvested and shown in slide order. |
| `className` | `string` | — | Additional CSS classes for the root container. |
| `currentSlide` | `number` | — | Controlled current slide index. When provided, sync is ignored and the view follows this value (useful for tests or custom wiring). |
| `keepAwake` | `boolean` | — | Keep the screen awake while the notes view is open (best-effort). Default: true (this is a presenter tool). |
| `pacing` | `PresenterPacing` | — | Optional pacing schedule. When provided, the notes view shows an elapsed timer plus an on-time / ahead / over indicator and the planned total. |
| `script` | `((slide: { id: string; index: number; step: number; }) => string \| undefined)` | — | Optional resolver for a fuller, per-slide script (e.g. a verbatim manuscript) shown in a secondary, scrollable pane next to the notes. Return `undefined` for slides that have no script. When omitted, no script pane is shown. |
| `sync` | `PresentationSync` | — | Subscribe to a live deck via the presenter-sync relay. Pass `true` for the default relay URL or an object to customise it. |

### `<Slide>`

Slide component - Individual slide wrapper

```tsx
<Slide id="intro" layout="title">
  <h1>Welcome to My Presentation</h1>
  <p>Subtitle goes here</p>
</Slide>
```

```tsx
With sub-slides
```tsx
<Slide id="multi-step" subSlides={[
{ id: "step1", content: <div>Step 1</div> },
{ id: "step2", content: <div>Step 2</div>, transition: "slide-left" }
]} />
```
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `__slideIndex` | `number` | — | Internal: Explicit slide index from Presentation component |
| `background` | `string` | — | Background color or image |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `id` | `string` | — | Unique identifier for the slide |
| `layout` | `LayoutType` | — | Layout type (default: "default") |
| `subSlides` | `SubSlide[]` | — | Sub-slides for multi-step content within this slide |
| `transition` | `TransitionEffect` | — | Transition effect |

### `<SlideContent>`

SlideContent component - Content layout container

```tsx
<Slide>
  <SlideContent layout="centered">
    <h1>Centered Content</h1>
  </SlideContent>
</Slide>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Children content |
| `className` | `string` | — | Additional CSS classes |
| `layout` | `"default" \| "centered" \| "top" \| "bottom"` | — | Layout mode |

### `<TransformSlide>`

A slide with multiple sub-slides and transform-based navigation

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `subSlides` | `TransformSubSlide[]` | yes | Array of sub-slides with their positions |
| `background` | `string` | — | Background color or gradient |
| `className` | `string` | — | Additional CSS classes |
| `duration` | `number` | — | Transition duration in seconds (default: 1) |
| `easing` | `"linear" \| "easeIn" \| "easeOut" \| "easeInOut" \| "circInOut" \| "backInOut"` | — | Transition easing (default: "easeInOut") |
| `initialSubSlide` | `number` | — | Initial sub-slide index (default: 0) |
| `perspective` | `boolean` | — | Enable 3D perspective (default: true) |
| `perspectiveValue` | `number` | — | Perspective value in pixels (default: 1000) |

### `<TrustedByMarquee>`

Rows of logos or names scrolling infinitely in alternating directions.

```tsx
<TrustedByMarquee
  rows={[[{ name: "Acme", color: "#ffffff" }], [{ name: "Globex", color: "#60a5fa" }]]}
  isActive
  baseSpeed={40}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | `MarqueeItem[][]` | yes | Array of row data, each containing items |
| `baseSpeed` | `number` | — | Base scroll speed (default: 0.3) |
| `className` | `string` | — | Additional CSS class for the container |
| `gap` | `number` | — | Gap between items in pixels (default: 16) |
| `isActive` | `boolean` | — | Whether the animation is active |
| `itemMinWidth` | `number` | — | Item minimum width in pixels (default: 180) |
| `renderItem` | `((item: MarqueeItem, index: number) => ReactNode)` | — | Custom item render function |
| `rowGap` | `number` | — | Gap between rows (default: 8) |
| `speedIncrement` | `number` | — | Speed increment per row (default: 0.05) |

## @getnarro/shared-ui

### `<AgendaItem>`

A styled agenda item component Displays an agenda item with a centered number in bold with a colored underline, followed by descriptive text. Useful for agenda presentations and step-by-step processes.

```tsx
<AgendaItem number={1} title="Introduction" />
<AgendaItem number={2} title="Main Topic" underlineColor="#00BFA5" />
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `number` | `number` | yes | The number of the agenda item |
| `title` | `string` | yes | Title of the agenda item |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `underlineColor` | `string` | — | Color of the underline |

### `<AnimatedList>`

List with staggered animations Note: Import the animations CSS file to use this component: import "@getnarro/shared-ui/styles/animations.css";

```tsx
<AnimatedList
  items={['First point', 'Second point', 'Third point']}
  animation="slide-up"
  staggerDelay={150}
  variant="check"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `ReactNode[]` | yes | List items to animate |
| `animation` | `ListAnimationType` | — | Animation type |
| `className` | `string` | — | Additional CSS classes |
| `duration` | `number` | — | Animation duration per item in milliseconds |
| `initialDelay` | `number` | — | Delay before starting first animation in milliseconds |
| `isActive` | `boolean` | — | Override slide active state |
| `ordered` | `boolean` | — | Ordered or unordered list |
| `staggerDelay` | `number` | — | Delay between each item in milliseconds |
| `variant` | `"disc" \| "decimal" \| "check" \| "arrow" \| "none"` | — | List style variant |

### `<Animation>`

A CSS animation wrapper component When used inside a Slide component from narro, animations will only trigger when the slide becomes active. Note: Import the animations CSS file to use this component: import "@getnarro/shared-ui/styles/animations.css";

```tsx
<Animation type="slide-up" delay={200} duration={500}>
  <Heading level={1}>Animated Title</Heading>
</Animation>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `delay` | `number` | — | Animation delay (ms) |
| `duration` | `number` | — | Animation duration (ms) |
| `easing` | `"linear" \| "ease-out" \| "ease-in-out" \| "ease" \| "ease-in"` | — | Animation easing |
| `isActive` | `boolean` | — | Override slide active state (for use without narro context) |
| `trigger` | `"mount" \| "hover" \| "visible"` | — | Trigger animation on mount |
| `type` | `AnimationType` | — | Animation type |

### `<Badge>`

a short inline label.

```tsx
<Badge tone="success">WCAG AA</Badge>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `radius` | `SurfaceRadius` | — | Corner rounding. Defaults to a pill. |
| `tone` | `SurfaceTone` | — | Colour role of the badge. |

### `<BigText>`

Extremely large, impactful text component

```tsx
<BigText effect="gradient" animate="blur-reveal">
  IMPACT
</BigText>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "left" \| "right"` | — | Text alignment |
| `animate` | `BigTextAnimation` | — | Animation preset |
| `animationDuration` | `number` | — | Animation duration in milliseconds |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `color` | `string` | — | Text color |
| `effect` | `BigTextEffect` | — | Text effect to apply |
| `gradientColors` | `string` | — | Custom gradient colors (when effect is "gradient") |

### `<Callout>`

a card with a coloured edge, for the one thing on the slide that matters most.

```tsx
<Callout tone="warning" title="Not swapped">
  This one is added, not replaced.
</Callout>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `icon` | `ReactNode` | — | Anything to sit left of the text — an `<Icon>`, an emoji. |
| `title` | `string` | — | Bold line above the body. |
| `tone` | `SurfaceTone` | — | Colour role of the edge and background. |

### `<Card>`

a bordered surface.

```tsx
<Card tone="primary" padding="lg">
  <Heading level={3}>Narro</Heading>
  <Text>Decks as code.</Text>
</Card>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `bordered` | `boolean` | — | Draw the border. Off gives a plain tinted panel. |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `padding` | `"none" \| "sm" \| "md" \| "lg"` | — | Inner spacing. |
| `radius` | `SurfaceRadius` | — | Corner rounding. |
| `tone` | `SurfaceTone` | — | Colour role of the surface. |

### `<Chart>`

A simple chart component This is a basic CSS-based implementation suitable for presentations. For more advanced charts, consider integrating with Chart.js or Recharts.

```tsx
<Chart
  type="bar"
  data={[
    { label: 'Q1', value: 100 },
    { label: 'Q2', value: 150 },
    { label: 'Q3', value: 200 },
  ]}
  title="Quarterly Sales"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `ChartDataPoint[]` | yes | Chart data |
| `type` | `"line" \| "bar" \| "pie" \| "donut"` | yes | Chart type |
| `className` | `string` | — | Additional CSS classes |
| `colors` | `string[]` | — | Colour palette, applied in data order. To emphasise one point regardless of ordering, set `color` on that `ChartDataPoint` instead — it wins over the palette. |
| `height` | `number` | — | Chart height |
| `orientation` | `"horizontal" \| "vertical"` | — | Bar direction. Horizontal reads better when labels are long: a long label under a narrow column is unreadable, which is what vertical-only forced. Bar charts only. |
| `showLegend` | `boolean` | — | Show legend |
| `showValues` | `boolean` | — | Print each value on its bar, rather than folding it into the label. |
| `title` | `string` | — | Chart title |
| `unit` | `string` | — | Unit appended to every printed value — `unit="KB"` prints `72 KB`. A bundle-size chart needs "72 KB", not "72", and folding the unit into the label meant `showValues` then printed the bare number a second time. Declarative because an attribute block in a markdown deck cannot pass a function. |
| `valueFormat` | `((value: number) => string)` | — | Full control over how a value is printed. Wins over {@link unit}. |

### `<Code>`

A code block component with optional line numbers and copy button Note: This is a basic implementation. For production use, consider integrating with Shiki or Prism for proper syntax highlighting.

```tsx
<Code language="typescript" lineNumbers>
{`const greeting = "Hello, World!";
console.log(greeting);`}
</Code>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `string` | yes | Code content |
| `className` | `string` | — | Additional CSS classes |
| `copyButton` | `boolean` | — | Show copy button |
| `highlightLines` | `string` | — | Lines to highlight (comma-separated or range) |
| `language` | `string` | — | Programming language |
| `lineNumbers` | `boolean` | — | Show line numbers |
| `theme` | `"dark" \| "light"` | — | Theme variant |

### `<CommentForm>`

A form for creating or editing comments

```tsx
<CommentForm
  slideId="slide-1"
  defaultAuthor="John Doe"
  onSubmit={(comment) => handleAddComment(comment)}
  onCancel={() => setShowForm(false)}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `onSubmit` | `(comment: Omit<SlideComment, "id" \| "createdAt">) => void` | yes | Callback when comment is submitted |
| `slideId` | `string` | yes | Slide ID to add comment to |
| `className` | `string` | — | Additional CSS classes |
| `defaultAuthor` | `string` | — | Default author name |
| `initialContent` | `string` | — | Initial content (for editing) |
| `isEditing` | `boolean` | — | Whether this is editing an existing comment |
| `onCancel` | `(() => void)` | — | Callback when form is cancelled |
| `parentId` | `string` | — | Parent comment ID for replies |
| `placeholder` | `string` | — | Placeholder text |
| `position` | `CommentPosition` | — | Position for inline comments |

### `<CommentItem>`

Displays a single comment with actions

```tsx
<CommentItem
  comment={comment}
  onEdit={(id) => handleEdit(id)}
  onDelete={(id) => handleDelete(id)}
  onResolve={(id, resolved) => handleResolve(id, resolved)}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | `SlideComment` | yes | The comment to display |
| `className` | `string` | — | Additional CSS classes |
| `currentUser` | `string` | — | Current user's name (to determine if they can edit/delete) |
| `onDelete` | `((commentId: string) => void)` | — | Callback when delete is clicked |
| `onEdit` | `((commentId: string) => void)` | — | Callback when edit is clicked |
| `onReaction` | `((commentId: string, emoji: string) => void)` | — | Callback when a reaction is added |
| `onReply` | `((commentId: string, content: string) => void)` | — | Callback when reply is submitted |
| `onResolve` | `((commentId: string, resolved: boolean) => void)` | — | Callback when resolve is toggled |
| `replies` | `SlideComment[]` | — | Child comments (replies) |
| `showReplyForm` | `boolean` | — | Whether to show the reply form |

### `<CommentMarker>`

A visual indicator for comment positions on slides

```tsx
<CommentMarker
  position={{ x: 50, y: 30 }}
  count={3}
  onClick={() => setShowComments(true)}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `position` | `CommentPosition` | yes | Position of the marker on the slide (percentage 0-100) |
| `className` | `string` | — | Additional CSS classes |
| `commentId` | `string` | — | Comment ID this marker represents |
| `count` | `number` | — | Number of comments at this position |
| `isActive` | `boolean` | — | Whether the marker is in an active/selected state |
| `onClick` | `(() => void)` | — | Callback when marker is clicked |

### `<CommentPanel>`

A sidebar panel for managing comments

```tsx
<CommentPanel
  slideId="slide-1"
  comments={allComments}
  onAddComment={(comment) => addComment(comment)}
  onDeleteComment={(id) => deleteComment(id)}
  currentUser="John Doe"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `comments` | `SlideComment[]` | yes | All comments data |
| `onAddComment` | `(comment: Omit<SlideComment, "id" \| "createdAt">) => void` | yes | Callback to add a new comment |
| `className` | `string` | — | Additional CSS classes |
| `currentUser` | `string` | — | Current user name |
| `filter` | `CommentFilterOptions` | — | Filter options |
| `isCollapsed` | `boolean` | — | Whether the panel is in collapsed state |
| `onCollapseChange` | `((collapsed: boolean) => void)` | — | Callback when collapse state changes |
| `onDeleteComment` | `((commentId: string) => void)` | — | Callback to delete a comment |
| `onFilterChange` | `((filter: CommentFilterOptions) => void)` | — | Callback when filter changes |
| `onResolveComment` | `((commentId: string, resolved: boolean) => void)` | — | Callback to resolve/unresolve a comment |
| `onUpdateComment` | `((commentId: string, updates: Partial<SlideComment>) => void)` | — | Callback to update a comment |
| `slideId` | `string` | — | Slide ID to show comments for (if undefined, shows all) |

### `<ContentSlide>`

A slide with optional title and content area

```tsx
<ContentSlide title="Key Features">
  <List items={['Feature 1', 'Feature 2', 'Feature 3']} />
</ContentSlide>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `title` | `ReactNode` | — | Slide title |

### `<CountingNumber>`

Animated number counter

```tsx
<CountingNumber
  value={1000000}
  duration={2000}
  format={{ prefix: "$", separator: true }}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number` | yes | Target value to count to |
| `className` | `string` | — | Additional CSS classes |
| `delay` | `number` | — | Delay before starting animation in milliseconds |
| `duration` | `number` | — | Animation duration in milliseconds |
| `easing` | `"linear" \| "ease-out" \| "ease-in-out"` | — | Animation easing |
| `format` | `{ decimals?: number \| undefined; prefix?: string \| undefined; suffix?: string \| undefined; separator?: boolean \| undefined; locale?: string \| undefined; }` | — | Number format options |
| `from` | `number` | — | Starting value (default: 0) |
| `isActive` | `boolean` | — | Override slide active state |
| `onComplete` | `(() => void)` | — | Callback when animation completes |

### `<Diagram>`

A diagram rendering component This is a basic text/pre-formatted implementation. For actual Mermaid support, integrate with the mermaid library: https://mermaid.js.org/

```tsx
// Text/ASCII diagram
<Diagram type="text">
{`
  +--------+     +--------+
  | Client | --> | Server |
  +--------+     +--------+
`}
</Diagram>

// Mermaid (requires mermaid library integration)
<Diagram type="mermaid">
{`graph LR
  A[Client] --> B[Server]
  B --> C[Database]`}
</Diagram>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `theme` | `"dark" \| "light" \| "forest"` | — | Diagram theme |
| `type` | `"text"` | — | Diagram type. `"mermaid"` used to be here and rendered the literal string "Mermaid Diagram (requires mermaid library)" followed by your source — a placeholder on the projector, through a fully typed public API. Narro ships no Mermaid renderer; use one directly and put the result in a slide, or keep the ASCII form this component draws. |

### `<DottedArc>`

Decorative concentric dotted arcs Creates a series of concentric arcs with dashed lines in varying colors. Used as a decorative element for title slides and maintaining brand consistency.

```tsx
<DottedArc
  colors={["#ff6b35", "#4ecdc4", "#1a535c"]}
  position="bottom-right"
/>
```

```tsx
// Custom sizing and spacing
<DottedArc
  colors={["orange", "green", "blue"]}
  width={3}
  spacing={10}
  size={400}
  position="bottom-left"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `colors` | `string[]` | yes | Array of colors for each arc |
| `className` | `string` | — | Additional CSS classes |
| `position` | `"bottom-right" \| "bottom-left" \| "top-right" \| "top-left"` | — | Arc position |
| `size` | `number` | — | Size of the arc container |
| `spacing` | `number` | — | Spacing between arcs |
| `width` | `number` | — | Line width for arcs |

### `<DualColumnTextAndImage>`

A two-column layout where text is on one side and an image is on the other

```tsx
<DualColumnTextAndImage
  text="This is the text content"
  image="/path/to/image.png"
  imageAlt="Description of image"
  gap="md"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `image` | `string` | yes | URL of the image to display in the right column |
| `text` | `ReactNode` | yes | Text content to display in the left column |
| `className` | `string` | — | Additional CSS classes |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between columns |
| `imageAlt` | `string` | — | Alt text for the image |
| `reverse` | `boolean` | — | Reverse the layout (image left, text right) |

### `<Embed>`

External content embedding component Supports YouTube, Vimeo, Google Slides, websites, web applications, and generic iframes.

```tsx
// Embed a YouTube video
<Embed
  url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  title="Video demonstration"
  aspectRatio="16:9"
/>

// Embed a web application with sandbox restrictions
<Embed
  url="https://codesandbox.io/embed/..."
  title="Live code demo"
  sandbox="allow-scripts allow-same-origin"
  loading="lazy"
/>

// Embed a website
<Embed
  url="https://example.com"
  title="Example website"
  aspectRatio="16:9"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | yes | URL to embed (YouTube, Vimeo, websites, web apps, etc.) |
| `allow` | `string` | — | Custom permissions for iframe (default includes common permissions) |
| `allowFullscreen` | `boolean` | — | Allow fullscreen |
| `aspectRatio` | `"1:1" \| "16:9" \| "4:3"` | — | Aspect ratio |
| `className` | `string` | — | Additional CSS classes |
| `loading` | `"lazy" \| "eager"` | — | Lazy loading strategy |
| `referrerPolicy` | `"no-referrer" \| "no-referrer-when-downgrade" \| "origin" \| "origin-when-cross-origin" \| "same-origin" \| "strict-origin" \| "strict-origin-when-cross-origin" \| "unsafe-url"` | — | Referrer policy |
| `sandbox` | `string` | — | Sandbox restrictions for iframe security |
| `title` | `string` | — | Embed title for accessibility |

### `<FlowDiagram>`

A visual representation of a process flow with steps

```tsx
<FlowDiagram
  steps={[
    {label: 'Step 1', icon: '/icon1.png', description: 'First step'},
    {label: 'Step 2', icon: '/icon2.png', description: 'Second step'}
  ]}
  direction="horizontal"
  color="#08979c"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `steps` | `FlowStep[]` | yes | List of steps with labels and optional icons |
| `className` | `string` | — | Additional CSS classes |
| `color` | `string` | — | Color for step boxes and connectors |
| `direction` | `"horizontal" \| "vertical"` | — | Direction of flow |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between steps |

### `<FourColumn>`

A four-column layout component with equal columns

```tsx
<FourColumn
  first={<Text>Column 1</Text>}
  second={<Text>Column 2</Text>}
  third={<Text>Column 3</Text>}
  fourth={<Text>Column 4</Text>}
  gap="lg"
  align="center"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `first` | `ReactNode` | yes | First column content |
| `fourth` | `ReactNode` | yes | Fourth column content |
| `second` | `ReactNode` | yes | Second column content |
| `third` | `ReactNode` | yes | Third column content |
| `align` | `"center" \| "start" \| "end" \| "stretch"` | — | Vertical alignment |
| `className` | `string` | — | Additional CSS classes |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between columns |
| `responsive` | `boolean` | — | Stack columns on small screens |

### `<Fragment>`

Step-by-step reveal component Each Fragment animates in sequence based on its `order` prop. The delay is calculated as: order * staggerDelay When used inside a Slide component from narro, animations will only trigger when the slide becomes active. Note: Import the animations CSS file to use this component: import "@getnarro/shared-ui/styles/animations.css";

```tsx
<Fragment order={1} effect="fade-in">
  <Text>This appears first (after 400ms)</Text>
</Fragment>
<Fragment order={2} effect="slide-up">
  <Text>This appears second (after 800ms)</Text>
</Fragment>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `duration` | `number` | — | Animation duration (ms) |
| `effect` | `FragmentEffect` | — | Animation effect |
| `isActive` | `boolean` | — | Override slide active state (for use without narro context) |
| `order` | `number` | — | Order in which fragment appears |
| `staggerDelay` | `number` | — | Delay between each fragment (ms) - used to stagger animations |
| `trigger` | `"time" \| "step"` | — | What reveals the fragment. `"step"` (the default) waits for the presenter: each press reveals the next fragment and the press after the last one advances the slide. `"time"` reveals everything on slide entry, staggered by `order` — the behaviour before reveals were wired to navigation. Outside a `Slide` there is nothing to step, so `"time"` is used whatever this says. |

### `<Grid>`

A flexible grid layout component

```tsx
<Grid columns={3} gap="md">
  <InfoCardWithIcon title="First">Item 1</InfoCardWithIcon>
  <InfoCardWithIcon title="Second">Item 2</InfoCardWithIcon>
  <InfoCardWithIcon title="Third">Item 3</InfoCardWithIcon>
</Grid>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "start" \| "end" \| "stretch"` | — | Horizontal alignment |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `columns` | `2 \| 3 \| 4 \| 5 \| 6 \| 1` | — | Number of columns |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between items |
| `justify` | `"center" \| "start" \| "end" \| "stretch"` | — | Vertical alignment |

### `<Heading>`

A styled heading component (h1-h6)

```tsx
<Heading level={1}>Main Title</Heading>
<Heading level={2} color="primary">Subtitle</Heading>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "left" \| "right"` | — | Text alignment |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `color` | `"default" \| "primary" \| "muted" \| "accent"` | — | Color variant |
| `level` | `2 \| 3 \| 4 \| 5 \| 6 \| 1` | — | Heading level (1-6) |

### `<HexPatternBackground>`

A background with a hexagonal pattern

```tsx
<HexPatternBackground backgroundColor="#00d9c4" hexColor="#08979c">
  <h1>Content here</h1>
</HexPatternBackground>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `backgroundColor` | `string` | — | Background color (hex or rgb) |
| `children` | `ReactNode` | — | Content to be rendered on top of the hexagon pattern background |
| `className` | `string` | — | Additional CSS classes |
| `hexColor` | `string` | — | Hexagon stroke color (hex or rgb) |
| `patternSize` | `"sm" \| "md" \| "lg"` | — | Pattern size (affects hexagon scale) |

### `<Icon>`

A simple icon component This is a basic implementation using Unicode symbols and emoji. For production use with custom icons, consider integrating with a proper icon library like Lucide, Heroicons, or Font Awesome.

```tsx
<Icon name="check" size="lg" color="green" />
<Icon name="github" size={32} />
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | Icon name or SVG content |
| `className` | `string` | — | Additional CSS classes |
| `color` | `string` | — | Icon color |
| `label` | `string` | — | Accessibility label |
| `size` | `number \| "sm" \| "md" \| "lg" \| "xl"` | — | Icon size |

### `<Image>`

An optimized image component with filter support

```tsx
<Image
  src="/images/photo.jpg"
  alt="A beautiful landscape"
  fit="cover"
  rounded="lg"
  shadow
  filter="grayscale"
/>
```

```tsx
Custom filter:
```tsx
<Image
  src="/images/photo.jpg"
  alt="Custom filtered"
  customFilter="brightness(80%) contrast(110%)"
/>
```
```

```tsx
Color overlay:
```tsx
<Image
  src="/images/photo.jpg"
  alt="Blue tinted"
  overlay="#3b82f6"
  overlayOpacity={0.4}
/>
```
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `alt` | `string` | yes | Alt text for accessibility |
| `src` | `string` | yes | Image source URL |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `customFilter` | `string` | — | Custom CSS filter value (overrides filter preset) |
| `filter` | `ImageFilter` | — | Apply CSS filter preset |
| `fit` | `"none" \| "cover" \| "contain" \| "fill"` | — | Object fit mode |
| `height` | `string \| number` | — | Height constraint |
| `overlay` | `string` | — | Color overlay (CSS color value) |
| `overlayOpacity` | `number` | — | Opacity of the color overlay (0-1, default: 0.5) |
| `rounded` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | — | Border radius |
| `shadow` | `boolean` | — | Add shadow |
| `width` | `string \| number` | — | Width constraint |

### `<ImageBackground>`

A full-bleed background image with content overlay

```tsx
<ImageBackground
  src="/images/hero.jpg"
  alt="Hero background"
  overlay="dark"
  kenBurns
>
  <Heading level={1}>Bold Title</Heading>
  <Text>Subtitle text here</Text>
</ImageBackground>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `src` | `string` | yes | Image source URL |
| `alt` | `string` | — | Image alt text for accessibility |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `kenBurns` | `boolean` | — | Enable Ken Burns animation effect (slow zoom/pan) |
| `kenBurnsDuration` | `number` | — | Ken Burns animation duration in seconds |
| `overlay` | `ImageBackgroundOverlay` | — | Overlay type for text readability |
| `overlayColor` | `string` | — | Custom overlay color (CSS color value) |
| `position` | `"center" \| "cover" \| "contain" \| "top" \| "bottom"` | — | Image positioning |

### `<ImageSlide>`

A full-bleed image slide with optional overlay

```tsx
<ImageSlide
  src="/images/hero.jpg"
  alt="Hero image"
  overlay={<Heading level={1}>Welcome</Heading>}
  overlayPosition="center"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `src` | `string` | yes | Image source URL |
| `alt` | `string` | — | Image alt text |
| `className` | `string` | — | Additional CSS classes |
| `fit` | `"cover" \| "contain" \| "fill"` | — | Object fit mode |
| `overlay` | `ReactNode` | — | Overlay content |
| `overlayPosition` | `"center" \| "top" \| "bottom"` | — | Overlay position |

### `<ImageSpotlight>`

Keynote-style Magic Move for images Creates smooth zoom and pan animations between slides. Elements with the same spotlightId will animate smoothly when transitioning between slides.

```tsx
// Slide 1 - Overview (centered, no zoom)
<ImageSpotlight
  spotlightId="diagram"
  src="/architecture.svg"
  alt="Architecture diagram"
  x={50}
  y={50}
  scale={1}
  width="100%"
  height={400}
/>

// Slide 2 - Zoom to top-left element
<ImageSpotlight
  spotlightId="diagram"
  src="/architecture.svg"
  alt="Architecture diagram"
  x={25}
  y={25}
  scale={2.5}
  width="100%"
  height={400}
/>

// Slide 3 - Pan to bottom-right element
<ImageSpotlight
  spotlightId="diagram"
  src="/architecture.svg"
  alt="Architecture diagram"
  x={75}
  y={75}
  scale={2.5}
  width="100%"
  height={400}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `alt` | `string` | yes | Alt text for accessibility |
| `spotlightId` | `string` | yes | Unique identifier for cross-slide morphing - elements with same id will animate between slides |
| `src` | `string` | yes | Image source URL |
| `className` | `string` | — | Additional CSS classes for container |
| `duration` | `number` | — | Animation duration in ms, default 800 |
| `easing` | `"linear" \| "ease-out" \| "ease-in-out" \| "ease" \| "ease-in" \| "spring"` | — | Animation easing function |
| `height` | `string \| number` | — | Container height (CSS value or number in px) |
| `imageClassName` | `string` | — | Additional CSS classes for image |
| `onAnimationComplete` | `(() => void)` | — | Callback when animation completes |
| `overlay` | `ReactNode` | — | Optional overlay content that appears on top |
| `rounded` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | — | Border radius |
| `scale` | `number` | — | Scale/zoom level, default 1 |
| `shadow` | `boolean` | — | Show shadow |
| `width` | `string \| number` | — | Container width (CSS value or number in px) |
| `x` | `number` | — | X position as percentage (0-100), default 50 (centered) |
| `y` | `number` | — | Y position as percentage (0-100), default 50 (centered) |

### `<InfoCardWithIcon>`

A styled information card with icon Displays an icon on the left with bold headings and descriptive text to the right. Uses consistent alignment and spacing. Perfect for concept highlights and important points.

```tsx
<InfoCardWithIcon
  iconSrc="/icon.svg"
  title="Key Feature"
  description="This is an important concept to highlight"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | `string` | yes | Description text explaining the icon |
| `iconSrc` | `string` | yes | URL for the icon image |
| `title` | `string` | yes | Title of the info card |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |

### `<List>`

An animated list component

```tsx
<List
  items={['First point', 'Second point', 'Third point']}
  variant="check"
  animated
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | `ReactNode[]` | yes | List items |
| `animated` | `boolean` | — | Enable animations |
| `animationDelay` | `number` | — | Animation delay between items (ms) |
| `className` | `string` | — | Additional CSS classes |
| `ordered` | `boolean` | — | Ordered or unordered list |
| `variant` | `"disc" \| "decimal" \| "check" \| "arrow" \| "none"` | — | List style |

### `<LogoGrid>`

A grid layout for displaying multiple logos with even spacing

```tsx
<LogoGrid
  logos={[
    {src: '/path/to/logo1.png', name: 'Company 1'},
    {src: '/path/to/logo2.png', name: 'Company 2'}
  ]}
  columns={3}
  gap="md"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `logos` | `Logo[]` | yes | Array of logo objects with source and alt text. |
| `className` | `string` | — | Additional CSS classes |
| `columns` | `2 \| 3 \| 4 \| 5 \| 6` | — | Number of columns |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between logos |

### `<MorphElement>`

Element that morphs across slides using View Transitions API When elements with the same transitionName exist on consecutive slides, they will smoothly morph into each other during slide transitions.

```tsx
// Slide 1
<MorphElement transitionName="hero-image">
  <img src="product.jpg" style={{ width: 200 }} />
</MorphElement>

// Slide 2 - same transitionName, different size
<MorphElement transitionName="hero-image">
  <img src="product.jpg" style={{ width: "100%" }} />
</MorphElement>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Element content |
| `transitionName` | `string` | yes | Unique name for cross-slide morphing |
| `as` | `ElementType<any, keyof IntrinsicElements>` | — | HTML tag to render |
| `className` | `string` | — | Additional CSS classes |
| `style` | `CSSProperties` | — | Additional inline styles |

### `<ProcessFlowChart>`

Interactive flowchart for process visualization Creates a flowchart with customizable nodes and connections. Nodes are automatically laid out based on the direction prop, and connections are drawn between them with arrows.

```tsx
<ProcessFlowChart
  nodes={[
    { id: "start", label: "Start", color: "#4ecdc4" },
    { id: "process", label: "Process", color: "#ff6b35" },
    { id: "end", label: "End", color: "#95e1d3" }
  ]}
  connections={[
    { from: "start", to: "process" },
    { from: "process", to: "end" }
  ]}
  direction="horizontal"
/>
```

```tsx
// Vertical flow with custom styling
<ProcessFlowChart
  nodes={[
    { id: "1", label: "Input", color: "#1a535c", textColor: "#fff" },
    { id: "2", label: "Transform", color: "#4ecdc4" },
    { id: "3", label: "Output", color: "#ff6b35", textColor: "#fff" }
  ]}
  connections={[
    { from: "1", to: "2", label: "data" },
    { from: "2", to: "3", label: "result" }
  ]}
  direction="vertical"
  nodeGap="lg"
  arrowStyle="dashed"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `connections` | `ProcessFlowConnection[]` | yes | Array of connections between node ids |
| `nodes` | `ProcessFlowNode[]` | yes | Array of nodes with labels and colors |
| `arrowStyle` | `"solid" \| "dashed"` | — | Arrow style for connections |
| `className` | `string` | — | Additional CSS classes |
| `direction` | `"horizontal" \| "vertical"` | — | Orientation of the flow |
| `nodeGap` | `"sm" \| "md" \| "lg"` | — | Gap between nodes |

### `<ProfileCard>`

A styled profile card component Displays a profile image, name, title, and associated company icons. Perfect for team introductions and speaker introductions.

```tsx
<ProfileCard
  imageSrc="/avatar.jpg"
  name="John Doe"
  title="CEO & Founder"
  companyIcons={["/company1.svg", "/company2.svg"]}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `imageSrc` | `string` | yes | Source URL for the profile image |
| `name` | `string` | yes | Name of the individual |
| `title` | `string` | yes | Title or role of the individual |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `companyIcons` | `string[]` | — | Array of icon URLs to display |

### `<ProgressRing>`

Animated circular progress indicator

```tsx
<ProgressRing value={75} size={120} showValue />
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `number` | yes | Progress value (0-100) |
| `backgroundColor` | `string` | — | Background ring color |
| `children` | `ReactNode` | — | Custom center content |
| `className` | `string` | — | Additional CSS classes |
| `color` | `string` | — | Ring color |
| `delay` | `number` | — | Delay before starting animation in milliseconds |
| `duration` | `number` | — | Animation duration in milliseconds |
| `isActive` | `boolean` | — | Override slide active state |
| `onComplete` | `(() => void)` | — | Callback when animation completes |
| `showValue` | `boolean` | — | Show percentage text in center |
| `size` | `number` | — | Size of the ring in pixels |
| `strokeWidth` | `number` | — | Stroke width in pixels |

### `<Quote>`

A styled blockquote component

```tsx
<Quote
  author="Albert Einstein"
  source="Interview, 1929"
>
  "Imagination is more important than knowledge."
</Quote>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `author` | `string` | — | Quote author |
| `authorStyle` | `CSSProperties` | — | Custom style for the author/figcaption |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `source` | `string` | — | Source or reference |
| `variant` | `"default" \| "large" \| "minimal"` | — | Visual variant |

### `<ScrollableImage>`

Displays a scrollable image Perfect for displaying full-page website screenshots that are too tall to fit in a slide.

```tsx
// Basic scrollable image
<ScrollableImage
  src="/screenshots/long-page.png"
  alt="Full page screenshot"
  maxHeight="70vh"
/>

// With auto-scroll
<ScrollableImage
  src="/screenshots/website.png"
  alt="Website screenshot"
  maxHeight="70vh"
  autoScrollSpeed={50}
  showIndicators
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `alt` | `string` | yes | Alt text for accessibility |
| `src` | `string` | yes | Image source URL or path |
| `autoScrollSpeed` | `number` | — | Auto-scroll speed in pixels per second (0 to disable) |
| `className` | `string` | — | Additional CSS classes |
| `maxHeight` | `string` | — | Maximum height of the container |
| `showIndicators` | `boolean` | — | Show scroll indicators |
| `smoothScroll` | `boolean` | — | Enable smooth scrolling |

### `<Text>`

A styled text block component

```tsx
<Text size="lg" weight="medium">
  This is styled body text for your slides.
</Text>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `align` | `"center" \| "left" \| "right" \| "justify"` | — | Text alignment |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `color` | `"default" \| "primary" \| "muted" \| "accent"` | — | Color variant |
| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl"` | — | Text size |
| `weight` | `"medium" \| "normal" \| "semibold" \| "bold"` | — | Font weight |

### `<ThreeColumn>`

A three-column layout component

```tsx
<ThreeColumn
  first={<Text>First column</Text>}
  second={<Text>Second column</Text>}
  third={<Image src="image.jpg" alt="Third column" />}
  ratio="1:2:1"
  gap="lg"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `first` | `ReactNode` | yes | First column content |
| `second` | `ReactNode` | yes | Second column content |
| `third` | `ReactNode` | yes | Third column content |
| `align` | `"center" \| "start" \| "end" \| "stretch"` | — | Vertical alignment |
| `className` | `string` | — | Additional CSS classes |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between columns |
| `ratio` | `"1:1:1" \| "2:1:1" \| "1:2:1" \| "1:1:2" \| "2:2:1" \| "1:2:2"` | — | Column ratio (e.g., "1:1:1", "2:1:1", "1:2:1") |
| `responsive` | `boolean` | — | Stack columns on small screens |

### `<TimelineWithIndicators>`

A horizontal timeline component Creates a horizontal timeline with circular indicators linked by a line. Includes labels below each indicator. Perfect for historical overviews and progress tracking.

```tsx
<TimelineWithIndicators
  events={[
    { year: "2020", label: "Founded" },
    { year: "2021", label: "Series A" },
    { year: "2022", label: "Expansion" },
  ]}
  lineColor="#14b8a6"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | `TimelineEvent[]` | yes | Array of event objects with year and label |
| `className` | `string` | — | Additional CSS classes |
| `lineColor` | `string` | — | Color of the connecting line |

### `<TitleSlide>`

A centered title slide layout

```tsx
<TitleSlide
  title="Welcome to My Presentation"
  subtitle="An Overview of Our Progress"
  author="John Doe"
  date="January 2025"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | yes | Main title |
| `author` | `ReactNode` | — | Author or presenter name |
| `className` | `string` | — | Additional CSS classes |
| `date` | `ReactNode` | — | Date or additional info |
| `subtitle` | `ReactNode` | — | Subtitle |

### `<TitleSlideWithElement>`

A title slide with a flexible element area

```tsx
<TitleSlideWithElement
  title="Product Launch"
  subtitle="Introducing our newest innovation"
  element={<Image src="product.png" alt="Product" />}
  elementPosition="right"
  elementAnimation="fade-in"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `element` | `ReactNode` | yes | Element to display (image, icon, chart, etc.) |
| `title` | `ReactNode` | yes | Main title |
| `animationDelay` | `number` | — | Animation delay in milliseconds |
| `className` | `string` | — | Additional CSS classes |
| `elementAnimation` | `ElementAnimation` | — | Animation preset for the element |
| `elementPosition` | `ElementPosition` | — | Position of the element relative to title/subtitle |
| `subtitle` | `ReactNode` | — | Subtitle |

### `<TwoColumn>`

A two-column layout component

```tsx
<TwoColumn
  left={<Text>Left content</Text>}
  right={<Image src="image.jpg" alt="Right image" />}
  ratio="2:1"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `left` | `ReactNode` | yes | Left column content |
| `right` | `ReactNode` | yes | Right column content |
| `align` | `"center" \| "start" \| "end" \| "stretch"` | — | Vertical alignment |
| `className` | `string` | — | Additional CSS classes |
| `gap` | `"sm" \| "md" \| "lg" \| "xl"` | — | Gap between columns |
| `ratio` | `"1:1" \| "2:1" \| "1:2" \| "3:2" \| "2:3"` | — | Column ratio |

### `<TwoColumnHighlight>`

Two-column layout with highlighted sections A layout component featuring two columns with different backgrounds, typically used for section headers or emphasizing key points. The left column is typically darker with a narrower width.

```tsx
<TwoColumnHighlight
  leftContent={<Heading level={1}>Section Title</Heading>}
  rightContent={<Text>Description text goes here</Text>}
  ratio="1:2"
/>
```

```tsx
// With custom colors
<TwoColumnHighlight
  leftContent="Key Point"
  rightContent="Detailed explanation"
  leftBg="#000000"
  rightBg="#ffffff"
  leftTextColor="#ffffff"
  rightTextColor="#000000"
  highlightColor="#ff6b35"
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `leftContent` | `ReactNode` | yes | Content for the left column |
| `rightContent` | `ReactNode` | yes | Content for the right column |
| `className` | `string` | — | Additional CSS classes |
| `highlight` | `string` | — | Text to highlight in the right column |
| `highlightColor` | `string` | — | Highlight color for emphasized text |
| `leftBg` | `string` | — | Left column background color |
| `leftTextColor` | `string` | — | Left column text color |
| `ratio` | `"1:2" \| "2:3" \| "1:3"` | — | Column width ratio (left:right) |
| `rightBg` | `string` | — | Right column background color |
| `rightTextColor` | `string` | — | Right column text color |

### `<TypewriterText>`

Text that appears character by character

```tsx
<TypewriterText speed="medium" cursor>
  Hello, World!
</TypewriterText>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `string` | yes | Text content to animate |
| `className` | `string` | — | Additional CSS classes |
| `cursor` | `boolean` | — | Show blinking cursor |
| `delay` | `number` | — | Delay before starting animation in milliseconds |
| `isActive` | `boolean` | — | Override slide active state |
| `onComplete` | `(() => void)` | — | Callback when animation completes |
| `speed` | `number \| "slow" \| "medium" \| "fast"` | — | Speed of typing in milliseconds per character |

### `<Video>`

A video embedding component

```tsx
<Video
  src="/videos/demo.mp4"
  poster="/images/poster.jpg"
  title="Product demo video"
  autoPlay
  loop
  muted
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `src` | `string` | yes | Video source URL |
| `autoPlay` | `boolean` | — | Autoplay video |
| `className` | `string` | — | Additional CSS classes |
| `controls` | `boolean` | — | Show controls |
| `fit` | `"cover" \| "contain" \| "fill"` | — | Object fit mode |
| `loop` | `boolean` | — | Loop video |
| `muted` | `boolean` | — | Mute video |
| `poster` | `string` | — | Poster image |
| `title` | `string` | — | Accessible title/description for the video |

### `<WaveLine>`

A decorative curved dashed line component Creates a smooth, curved dashed line that spans across a slide to add dynamic visual elements. Perfect for title slide decoration and section separators.

```tsx
<WaveLine />
<WaveLine color="#00BFA5" dashWidth={3} />
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Children content |
| `className` | `string` | — | Additional CSS classes |
| `color` | `string` | — | Color of the dashed line |
| `dashWidth` | `number` | — | Width of each dash |

### `<WordReveal>`

Text that reveals word by word Note: Import the animations CSS file to use this component: import "@getnarro/shared-ui/styles/animations.css";

```tsx
<WordReveal animation="blur" staggerDelay={100}>
  This text will appear word by word
</WordReveal>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `string` | yes | Text content to animate (will be split by words) |
| `animation` | `WordRevealAnimation` | — | Animation type |
| `className` | `string` | — | Additional CSS classes |
| `delay` | `number` | — | Delay before starting animation in milliseconds |
| `duration` | `number` | — | Animation duration per word in milliseconds |
| `isActive` | `boolean` | — | Override slide active state |
| `onComplete` | `(() => void)` | — | Callback when all words are revealed |
| `staggerDelay` | `number` | — | Delay between each word in milliseconds |

### `<Workflow>`

Animated workflow diagram Note: Import the animations CSS file to use this component: import "@getnarro/shared-ui/styles/animations.css";

```tsx
<Workflow animation="progressive" direction="horizontal">
  <WorkflowStep icon="1" title="Start">Begin here</WorkflowStep>
  <WorkflowStep icon="2" title="Process">Do the work</WorkflowStep>
  <WorkflowStep icon="3" title="Complete">All done!</WorkflowStep>
</Workflow>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | WorkflowStep children |
| `animation` | `WorkflowAnimation` | — | Animation type |
| `className` | `string` | — | Additional CSS classes |
| `connectorColor` | `string` | — | Connector line color |
| `direction` | `WorkflowDirection` | — | Layout direction |
| `highlightActive` | `boolean` | — | Highlight the currently active step |
| `isActive` | `boolean` | — | Override slide active state |
| `showConnectors` | `boolean` | — | Show connecting lines/arrows between steps |
| `staggerDelay` | `number` | — | Delay between each step in milliseconds |

### `<WorkflowStep>`

Individual step in a workflow

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | yes | Step content |
| `className` | `string` | — | Additional CSS classes |
| `description` | `string` | — | Step description |
| `icon` | `ReactNode` | — | Icon or number to display |
| `title` | `string` | — | Step title |

### `<ZoomImage>`

Image with click-to-zoom functionality

```tsx
<ZoomImage
  src="/diagram.png"
  alt="Architecture diagram"
  zoomable
  zoomScale={2}
/>
```

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `alt` | `string` | yes | Alt text for accessibility |
| `src` | `string` | yes | Image source URL |
| `className` | `string` | — | Additional CSS classes |
| `fit` | `"none" \| "cover" \| "contain" \| "fill"` | — | Object fit mode |
| `height` | `string \| number` | — | Height constraint |
| `rounded` | `"none" \| "sm" \| "md" \| "lg" \| "full"` | — | Border radius |
| `shadow` | `boolean` | — | Add shadow |
| `width` | `string \| number` | — | Width constraint |
| `zoomable` | `boolean` | — | Enable click-to-zoom |
| `zoomScale` | `number` | — | Zoom scale factor |

---

# Introduction

> What Narro is, and which of its two authoring modes you want
>
> Read this when: What is Narro, and should I be writing markdown or React?

Narro builds presentations out of web technology. A deck is either a markdown
file or a tree of React components; either way it renders in a browser, lives in
Git, and exports to PPTX, PDF, or a single self-contained HTML file.

## Two ways to write a deck

Both modes use the same runtime, the same navigation, and the same export
pipeline. Pick by how much control you want, not by how big the deck is —
markdown decks can drop into React wherever they need to.

### Markdown mode

One `.md` file, no project to scaffold:

```bash
npx @getnarro/cli new deck.md
npx @getnarro/cli dev deck.md
```

The dialect is designed as a **ladder with no cliff**: plain markdown → layout
directives → per-element Tailwind → your own React layouts → full MDX with live
components. You climb it without ever rewriting the deck. See
[Markdown mode](/docs/markdown-mode).

### React mode

A Vite project where every slide is a component:

```bash
npm create narro@latest my-deck
```

Reach for this when slides need real application logic — live data, custom
interaction, a component you already have. See [First deck](/docs/first-deck).

## Why not PowerPoint

Narro is worth the setup when you need something a WYSIWYG tool cannot give you:

- **Code that is really code** — syntax highlighting, and live components if you
  want them running on the slide
- **Version control** — a deck is text, so it diffs and merges
- **Reuse** — a slide is a component; a component works in the next deck too
- **Generation** — text in, deck out, which is what makes AI authoring practical

If your deck is five bullet points and a photo, use PowerPoint. Narro is for the
cases where you have been fighting the tool.

## Packages

| Package | What it is |
| --- | --- |
| `@getnarro/cli` | CLI tools for creating and managing Narro presentations |
| `@getnarro/core` | The React runtime for Narro presentations — Presentation, Slide, navigation, transitions, and speaker notes |
| `@getnarro/docs` | Narro's documentation as data — markdown pages, a generated component API reference, and llms.txt |
| `@getnarro/markdown` | Markdown & MDX authoring for Narro presentations |
| `@getnarro/marketplace` | Themes, colour schemes, and templates for Narro presentations |
| `@getnarro/mcp-server` | MCP (Model Context Protocol) server for AI-assisted Narro presentation creation |
| `@getnarro/shared-ui` | Slide components for Narro presentations — headings, text, lists, code, media, charts, and layouts |
| `create-narro` | Scaffold a new Narro presentation |

> The npm package named `narro` is unrelated to this project. Everything here is
> under the `@getnarro/` scope. The binary called `narro` comes from
> `@getnarro/cli`.

---

# Installation

> Get a deck running, in either mode
>
> Read this when: What do I install, and what does the project look like afterwards?

Node.js 20 or newer. Any of npm, pnpm, yarn, or bun.

## Markdown mode: no install

```bash
npx @getnarro/cli new deck.md    # write a starter deck
npx @getnarro/cli dev deck.md    # serve it with hot reload
npx @getnarro/cli build deck.md  # static build into dist/
```

Nothing is scaffolded and no config file is created. The CLI brings its own
runtime, so a lone `.md` file in an empty directory is a complete deck.

`markdown-minimal` scaffolds the same thing with a `package.json` that pins the
CLI version and gives you scripts:

```bash
npm create narro@latest my-deck -- --template markdown-minimal
```

For a deck that needs its own dependencies, pinned versions, or React layouts,
`markdown-app` puts the same `deck.md` inside a Vite project:

```bash
npm create narro@latest my-deck -- --template markdown-app
```

## React mode: scaffold a project

```bash
npm create narro@latest my-deck
cd my-deck
npm install
npm run dev
```

`npm create narro` prompts for a template. To skip the prompt:

```bash
npm create narro@latest my-deck -- --template developer
```

### Templates

**Markdown**

| Template | What it is | Notes |
| --- | --- | --- |
| `markdown-minimal` | One `deck.md` and a pinned CLI. Nothing to build. | **start here** |
| `markdown-app` | The same deck inside a Vite project, for React components and custom CSS. | — |
| `markdown-docs` | Documentation-shaped deck: long code samples, wide tables. | ships an example deck |

**React**

| Template | What it is | Notes |
| --- | --- | --- |
| `minimal` | Three slides and nothing else. Start here to write your own. | **start here** |
| `corporate` | Restrained business deck, dark theme. | ships an example deck |
| `developer` | Code-heavy technical talk with terminal chrome. | ships an example deck |
| `creative` | Bold colour and large type. | ships an example deck |
| `bold-statement` | One idea per slide, very large type. | ships an example deck |
| `visual-story` | Full-bleed imagery with overlay text. | ships an example deck |
| `data-narrative` | Charts and figures, light theme. | ships an example deck |
| `startup-pitch` | Ten-slide investor pitch, filled in. | ships an example deck |
| `tech-conference` | Conference talk with a title card and code slides. | ships an example deck |
| `template0` | Reference deck exercising every component. Read it, do not start from it. | ships an example deck |

Pass `--mode markdown` to be prompted with only the markdown templates, or
`npx create-narro --list` to print the table above from the version you have
installed.

## Adding Narro to an existing app

```bash
npm install @getnarro/core @getnarro/shared-ui
```

`react` and `react-dom` 19+ are peer dependencies. Styling assumes Tailwind CSS
v4; add `@tailwindcss/vite` to your Vite config if you do not have it.

## What a scaffolded project looks like

```bash
my-deck/
├── index.html
├── package.json
├── vite.config.ts
├── tsconfig.json
└── src/
    ├── App.tsx       # the deck — this is the file you edit
    ├── main.tsx      # mounts App
    └── index.css     # Tailwind entry
```

A markdown template swaps `src/App.tsx` for a `deck.md` at the project root and
a `src/main.tsx` that mounts the compiled deck.

## Scripts

| Command | What it does |
| --- | --- |
| `npm run dev` | Dev server with hot reload, on <http://localhost:5173> |
| `npm run build` | Production build into `dist/` |
| `npm run preview` | Serve the built deck |

---

# First Deck

> Build a three-slide React deck end to end
>
> Read this when: What does a working React deck look like, end to end?

This walks through a React deck. If you want the markdown path instead, see
[Markdown mode](/docs/markdown-mode) — it is shorter.

## 1. Scaffold

```bash
npm create narro@latest my-first-deck -- --template minimal
cd my-first-deck
npm install
```

## 2. Write the slides

Open `src/App.tsx`. Note where each component comes from: the structural pieces
are in `@getnarro/core`, the content pieces in `@getnarro/shared-ui`.

```tsx
import { Notes, Presentation, Slide, SlideContent } from "@getnarro/core";
import { Heading, List, Text } from "@getnarro/shared-ui";

export function App() {
  return (
    <Presentation aspectRatio="16:9">
      <Slide id="title" className="bg-gradient-to-br from-blue-900 to-slate-900">
        <SlideContent layout="centered">
          <Heading level={1} align="center">
            Welcome to Narro
          </Heading>
          <Text size="xl" align="center" color="muted">
            Build presentations with React
          </Text>
        </SlideContent>
        <Notes>Introduce yourself and set up the problem.</Notes>
      </Slide>

      <Slide id="features" className="bg-slate-900">
        <SlideContent>
          <Heading level={2}>Why Narro?</Heading>
          <List
            variant="check"
            items={[
              "React components as slides",
              "Tailwind for styling",
              "Export to PowerPoint and PDF",
            ]}
          />
        </SlideContent>
        <Notes>Spend the most time on the export story.</Notes>
      </Slide>

      <Slide id="end" className="bg-gradient-to-br from-purple-900 to-slate-900">
        <SlideContent layout="centered">
          <Heading level={2} align="center">
            Questions?
          </Heading>
        </SlideContent>
      </Slide>
    </Presentation>
  );
}
```

## 3. Run it

```bash
npm run dev
```

Open <http://localhost:5173>. Arrow keys or space move between slides; `F` is
fullscreen, `O` is the overview grid.

Because `id` is set on each slide, the URL tracks position — `#/slide/features`
links straight to the second slide.

## 4. Build

```bash
npm run build     # → dist/
npm run preview   # serve it
```

`dist/` is a static site. Any host will serve it.

## Things worth knowing early

- **`<Notes>` never renders on the slide.** It feeds the presenter view.
- **`SlideContent` handles vertical rhythm.** Its `layout` prop is
  "default" | "centered" | "top" | "bottom"
  — a different set from `Slide`'s own `layout` prop, which is
  "default" | "center" | "two-column" | "image" | "title".
- **Tailwind classes work everywhere.** `className` on any Narro component is
  merged, not replaced.

## Next

- [Markdown mode](/docs/markdown-mode) — the same deck in one `.md` file
- [Component reference](/docs/components) — everything you can import
- [Animation](/docs/animation) — fragments and progressive reveals

---

# Markdown Mode

> The full markdown and MDX dialect — slides, layouts, Tailwind attributes, fragments
>
> Read this when: How do I split a slide, style one word, or reveal a line — without leaving the markdown file?

Write a deck as one markdown file, then climb into React only where you need it.
This page is the complete dialect reference.

```bash
npx @getnarro/cli new deck.md      # starter deck
npx @getnarro/cli dev deck.md      # hot-reloading server
npx @getnarro/cli check deck.md    # validate without building
npx @getnarro/cli build deck.md    # static build
```

`check` is the fast loop. It resolves every layout, slot, theme and frontmatter
name and reports the ones that do not exist, along with what would have worked
— then compiles each slide and reports what only a compiled slide can show:

- markdown that reached the slide as **literal text** — an emphasis run that
  never closed, an attribute block that attached to nothing, a `::slot::`
  marker written mid-line. This is the failure that used to reach an audience,
  because the deck built cleanly around it.
- a slide that renders **blank** because a stray `---` created it
- a `{` MDX read as JavaScript, or an HTML tag that needs closing

Compiling costs about 90ms for ten slides, so it stays a loop you can run after
every edit. `narro build` applies the same rules, so a deck that renders its own
source does not build.

## Seeing what a slide renders

`narro check deck.md --render` prints the elements, classes and text of every
slide. No browser, no screenshot — it reads the compiled slide:

```
Slide 1  layout: cover  id: hook
    h1.text-7xl
      strong.text-red-500  Important!
      text  works now
    p
      text  Two
      code.bg-red-500  a
      text  and
      code.bg-blue-500  b
    pre.rounded-xl.bg-black
      code.language-bash  npx @getnarro/cli dev deck.md
  notes: phase 1
```

This is the fastest way to answer "did that class land on the word or the
paragraph?" — the question the attribute syntax raises most often, and the one a
build cannot answer.

## The customization ladder

| Rung | You write | Lives in |
| --- | --- | --- |
| 1. Plain markdown | `# Heading`, lists, tables | the `.md` file |
| 2. Directives | `layout:`, `class:`, `theme:` in frontmatter | the `.md` file |
| 3. Tailwind utilities | `{.text-8xl .text-blue-400}` on any element | the `.md` file |
| 4. Ejected layouts | a React component in `layouts/` | beside the file |
| 5. Full MDX | `import` + `<LiveComponent/>` | file + components |

Nothing is rewritten as you move up a rung.

## Slides and frontmatter

Slides are separated by a line of exactly `---`. The file may open with a YAML
**deck frontmatter** block, and each slide may start with its own YAML block.

```markdown
---
title: Q3 Review
theme: default
aspectRatio: "16:9"
class: font-sans
---

# First slide

---
layout: two-column
class: bg-slate-950
id: revenue
---

## Left

::right::

## Right
```

A `---` inside a fenced code block never splits a slide — backticks or tildes,
any fence length. What *does* split a slide is a `---` you meant as a horizontal
rule: use `***` or `___` for that, which markdown renders identically and the
splitter ignores.

A block after a separator counts as slide frontmatter only when it is at most 40
lines and **every** non-blank line is a top-level `key:` / `key: value`, an
indented continuation, or a `- ` list item. Anything else — a heading, a
sentence, a code fence — makes the whole block content instead. That rule is
deliberately conservative: swallowing a paragraph into frontmatter would delete
it from the slide with no error.

**Deck keys:** `title`, `author`, `date`, `theme`, `template`, `aspectRatio`, `transition`, `class`, `keyboard`, `mouse`, `touch`, `routing`, `favicon`, `maxDuration`.

**Slide keys:** `layout`, `class`, `id`, `transition`, `background`, `notes`.
Any other key is forwarded to the layout component as a prop.

Set `id` on slides you will link to — it is also what makes diffs stable when a
deck is edited programmatically.

Keys beginning `x-` are reserved for you: nothing reads them, and nothing warns
about them, including `check --strict`. They are the place to record what a file
is and how to run it, which an ordinary `.md` otherwise cannot say:

```yaml
---
x-library: narro — https://getnarro.com
x-run: npx @getnarro/cli dev deck.md
title: Q3 Review
---
```

## Your own CSS

A `deck.css` beside the deck — or `<name>.css` matching the deck's filename —
is picked up automatically and appended to the deck's stylesheet. That is where
a `@keyframes`, a `:has()` rule, or a single custom class goes.

The stable hooks to target: `.rs-deck` (the deck root), `.rs-slide`,
`.rs-container`, `.rs-step` (a fragment), and `.rs-layout-*` for each layout.

## Tailwind attribute syntax

Attach classes, an id, or props to the preceding element with a trailing
`{ … }`:

```markdown
# Big title {.text-8xl .font-black .text-blue-400}

A subtitle. {.text-2xl .opacity-70}

![diagram](./arch.png){.rounded-xl width=800}
```

- `{.foo}` → class
- `{#foo}` → id
- `{key=value}` → prop or attribute; quotes around the value are stripped
- `{key}` → a boolean `true` prop, but **only** alongside at least one of the
  three above

That last rule is what keeps the syntax compatible with MDX, where `{…}` is a
JavaScript expression. A block containing at least one `.class`, `#id`, or
`key=value` is treated as attributes; a block of only bare words — `{count}`,
`{items.length}` — is left alone and compiled as an expression. So
`{.step delay=200}` is attributes and `{delay}` on its own is not.

### Which Tailwind classes it accepts

**All of them.** A class is whatever Tailwind calls it, including every part of
the vocabulary that is not letters and dashes:

```markdown
Arbitrary values         {.text-[10px] .bg-[#0a0a0a] .grid-cols-[1fr_2fr]}
Opacity modifiers        {.bg-white/5 .border-amber-500/60}
Fractions                {.w-1/2 .basis-2/3}
Variants                 {.hover:bg-white/10 .md:text-2xl .dark:text-white}
Half-steps and overrides {.p-1.5 .!text-red-500}
Arbitrary variants       {.[&>*]:mt-4}
```

There is exactly one exception: a literal `{` or `}` **inside** the block, as in
`{.text-[calc(1rem_+_{x})]}`. The block ends at the first `}`, so that class has
to live in [`deck.css`](#your-own-css) instead. Everything else Tailwind accepts,
this accepts.

### Which element it attaches to

**The space decides.** Written tight against an inline element, the block is
that element's; written after a space, it is the whole block's.

```markdown
Only **this word**{.text-red-500} is red.

The whole paragraph is red. **Not just this.** {.text-red-500}

# A heading with **emphasis** {.text-7xl}
```

The third line sizes the heading, not the emphasised word — which is why the
space matters. Without the rule there would be no way to write it.

Because each block is resolved on its own, you can style two things
differently on one line:

```markdown
Compare `before`{.text-rose-400} with `after`{.text-lime-400}.
```

This works on headings, paragraphs, and the inline elements — images, links,
`**strong**`, `*emphasis*`, `` `code` ``, `~~delete~~`. For a **list or a
table**, put the attribute block on its own line as a separate paragraph with a
blank line above it; it then attaches to the block before it.

**On a list item, the block styles the `<li>`** — which is what a grid or flex
row of items needs, since the class has to be on the child the parent lays out:

```markdown
- Slate {.bg-sky-700 .p-6 .text-center}
- Ocean {.bg-cyan-700 .p-6 .text-center}

{.grid .grid-cols-2 .gap-3 .list-none .pl-0}
```

The last block is separated by a blank line and starts at column 0, so it belongs
to the list rather than to the item above it — indent it and it styles that
`<li>`, which is the rule in the paragraph above and worth reading twice. Run
`check --render` if you are unsure which one you got.

**In a table, it styles the cell** — `| Total {.text-right .font-black} |` puts
the classes on that `<th>` or `<td>`.

Repeated blocks on one element merge: classes concatenate, and a later `#id` or
`key=value` wins.

One thing the syntax cannot do: style an *empty* element. `**&nbsp;**{.w-8}`
does not parse, because emphasis needs non-space content.

For a coloured rectangle, a bar, or a spacer, use an **empty container** — it
takes attributes like any other and needs nothing but markdown:

```markdown
:::{.h-2 .w-48 .rounded-full .bg-cyan-400}

:::
```

An inline `<span className="…" />` works too and is the shorter answer inside a
sentence — see [MDX](#mdx) below.

### On a fenced code block

An attribute block in the info string styles the `<pre>`; the `language-*` class
on the inner `<code>` is left alone, so highlighting still works.

````markdown
```bash {.rounded-xl .bg-black .p-8}
npx @getnarro/cli dev deck.md
```
````

The separate-paragraph form works too, and is the one to use when the fence
already carries other metadata.

## Grouping blocks

`:::` opens a container and a bare `:::` closes it. It takes the same attribute
syntax as any element, and containers nest:

```markdown
:::{.flex .items-center .gap-8}
### 72 KB {.text-6xl .font-black}

Gzipped, including the runtime.
:::
```

This is how you get a row, a grid, or a bordered box without leaving markdown.
Before it existed, every horizontal arrangement had to be a `<ul>` carrying
`{.flex .list-none .pl-0}` — two utilities of pure boilerplate to undo list
styling — and anything a list could not express was out of reach.

Every container carries `rs-container`, so a stylesheet can target them.

Three things worth knowing before you build a grid out of these:

- **`:::` must start at column 0.** An indented `:::` is not a container marker;
  it stays on the slide as literal text (and `check` reports it).
- **Blank lines inside are optional.** The compact form above and the spaced form
  (a blank line after the opening fence and before the closing one) compile
  identically, at any nesting depth. Use whichever reads better.
- **There is no iteration.** Twelve cards is twelve containers; a deck cannot
  loop, reference-and-repeat, or define a fragment to reuse. A twelve-item grid
  is around 120 lines of markdown, and that is the point at which
  [MDX](#mdx) and a `.map()` — 15 lines — is the better tool. This is the
  sharpest edge of the mode; see
  [Limitations](/docs/limitations.md).

## Layout slots

`::name::` on its own line starts a named slot. Content before the first marker
is the `default` slot. Slots arrive at the layout component as props.

```markdown
---
layout: two-column
---

Goes to `children`.

::right::

Goes to the `right` prop.
```

**Every built-in layout takes `::header::` and `::footer::`** — full-width rows
above and below the content, whatever the layout puts in between:

```markdown
---
layout: two-column
---

::header::

## Before and after {.text-5xl}

::default::

The old way.

::right::

The new way.
```

Both rows render only when filled, so a deck that never uses them is unchanged.
Title-above-two-panels is the most common shape a deck asks for, and they were
column-layout-only for long enough that decks on `default` and `cover`
hand-stacked paragraphs to fake a header. An eyebrow line above a cover title, a
source note under a chart, and a page footer are all this.

`::default::` reopens the default slot, which is how you write a header first and
then the main content.

## Speaker notes

```markdown
<!-- notes: What to say on this slide. -->
```

The comment can sit anywhere in the slide, and a slide may carry more than one —
they are concatenated in source order, separated by a blank line. The comments
are removed before compilation, so nothing reaches the slide.

The `notes:` frontmatter key is the alternative, and is the better one when the
text is long enough to want YAML's block scalar:

```markdown
---
notes: |
  Open with the customer story.
  Then the number.
---
```

Either way the text shows up in the presenter view and nowhere else.

## Fragments

Reveal content step by step with `.step`:

```markdown
- appears first {.step}
- appears second {.step delay=200}
```

`delay` is milliseconds, and it is **consumed** by the step wrapper rather than
forwarded — it will not appear as an attribute on the element.

Each marked node is wrapped at compile time, and reaches the DOM as:

```html
<div class="rs-step" data-rs-step data-rs-step-delay="200">…</div>
```

Those hooks are the supported way to target fragments from a theme or a custom
stylesheet. `.step` is the only reserved class name in the attribute syntax:
every other `{.foo}` is passed through as a literal class.

## Layouts

Reference a layout by name in slide frontmatter. A name resolves in order, first
match winning:

1. `<deckDir>/layouts/<name>.{tsx,jsx,mdx,ts,js}` — yours, shadows everything
2. The [deck template](/docs/deck-templates)'s layouts, if the deck has one
3. The active theme's layouts
4. The built-ins:

| Layout | Slots |
| --- | --- |
| `default` | `header`, `footer` |
| `cover` | `header`, `footer` |
| `section` | `header`, `footer` |
| `quote` | `header`, `footer` |
| `end` | `header`, `footer` |
| `two-column` | `right`, `header`, `footer` |
| `three-column` | `two`, `three`, `header`, `footer` |
| `image-right` | `header`, `footer` |
| `image-full` | `header`, `footer` |

That table is generated from `builtinLayoutSlots`, which is also what the
validator checks against — so a slot name it does not list is one `narro check`
will reject, and content after it would not have rendered.

Two things the table does not show:

**Column names are positional, and `three-column` does not use `right`.** Its
slots are `two` and `three`; `two-column` has one slot called `right`. Writing
`::right::` on a three-column slide puts the content in a slot nothing reads.

**The image layouts take their image from frontmatter, not a slot.**
`image-right` and `image-full` read the slide's `image:` key, falling back to
`background:` — which is why neither has a named slot:

```markdown
---
layout: image-right
image: ./architecture.png
---

## What changed

The old pipeline is on the right.
```

A layout is a plain React component:

```tsx
import type { SlideLayoutProps } from "@getnarro/markdown/runtime";

export default function TwoColumn({ children, right }: SlideLayoutProps) {
  return (
    <div className="grid h-full grid-cols-2 gap-12 p-16">
      <div>{children}</div>
      <div>{right}</div>
    </div>
  );
}
```

### Naming your own layouts without writing components

A [deck template](/docs/deck-templates) is one file beside the deck that defines
layouts as data — a built-in plus classes, defaults, and the chrome every slide
carries — and gives each one an id the markdown references:

```ts
// deck.template.ts
export default {
  id: "acme",
  master: { footer: { text: "{title} · confidential" } },
  layouts: {
    "metric-split": { base: "two-column", regions: { right: "text-right text-accent" } },
  },
};
```

```markdown
---
layout: metric-split
---
```

It is the slide master: `narro check` knows the ids, the deck stops naming
colours, and rebranding is one file.

## MDX

A slide is MDX, whatever the file is called. Components, JSX and `{expression}`
work in a `.md` deck exactly as they do in a `.mdx` one.

Put `import` and `export` statements in the **preamble**: the statements at the
top of the file, after the deck frontmatter and before the first slide. They are
shared by every slide, and the preamble ends where the statements do — a `---`
after them is allowed but not required. Anything else up there is an error
rather than a slide that quietly disappears. An import inside a slide body is
also an error; move it to the preamble.

Two consequences of slides being MDX, both of which produce a build error
naming the line rather than a surprise on the projector:

- **HTML is JSX.** Every tag closes (`<br />`, not `<br>`) and attributes are
  camelCased (`className`, not `class`).
- **`{` opens an expression** unless the block is attribute syntax. Write `\{`
  for a literal brace, or put the text in `` `inline code` ``.

```markdown
import { LiveChart } from './components/chart'

export const Stat = ({ n, label }) => (
  <div className="text-8xl font-black">{n}<span className="text-2xl">{label}</span></div>
)

# Revenue

<LiveChart data={[1, 4, 9]} />
<Stat n="42%" label="growth" />
```

## Formatting a deck

Run `narro fmt deck.md`. **Do not point a general markdown formatter at a deck.**

The reason is [the space rule](#which-element-it-attaches-to): `**word**{.red}`
styles the word and `**word** {.red}` styles the block, so any formatter that
reflows a paragraph can move an attribute block onto its own line and silently
change what it applies to. Prettier does exactly that. Nothing errors, `check`
sees a legal deck, and the design is different.

`narro fmt` does only what cannot change rendering: trailing whitespace, runs of
blank lines, `---` separators, YAML colon spacing, and collapsing multiple spaces
before an attribute block — preserving tightness, which is the one thing that
carries meaning. `narro fmt --check` is the CI form.

If your repo runs Prettier over everything, add the deck to `.prettierignore`.
The scaffolded markdown templates already do.

## In a scaffolded project

`markdown-minimal` is the deck and nothing else — `deck.md`, and a
`package.json` that pins the CLI. The `markdown-app` and `markdown-docs`
templates wire the same plugin into a normal Vite project, which is what you
want when the deck needs its own dependencies or pinned versions:

```ts
// vite.config.ts
import path from "node:path";
import { narroMarkdown } from "@getnarro/markdown/vite";
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    narroMarkdown({ deckPath: path.resolve(import.meta.dirname, "deck.md") }),
    react(),
    tailwindcss(),
  ],
  resolve: { dedupe: ["react", "react-dom", "@getnarro/core"] },
});
```

The plugin exposes the compiled deck as `virtual:narro/deck` and its stylesheet
as `virtual:narro/deck.css`. Its full option list — including `strict`, which
promotes validation warnings to errors and belongs in CI — is on the
[markdown API](/docs/markdown-api#the-vite-plugin) page.

## Driving the format from code

Everything on this page is also reachable as a library. `@getnarro/markdown`
parses, edits, validates, and compiles decks, and it is what the CLI and the MCP
server are built on — a deck can be read and rewritten without a regex.

The one distinction worth knowing before you start: `splitDeck` parses for
*rendering* and loses the original YAML text, while `parseDeckDocument` parses
for *editing* and round-trips exactly, so a tool can change one slide without
reformatting the other forty. See [markdown API](/docs/markdown-api).

## One dialect

Narro has exactly one markdown dialect: this one. Older material described a
directive syntax (`::text[…]{size="lg"}`, `:::three-columns`) that was never
part of the shipping pipeline — that implementation has been removed. If you
find those directives in a deck, they will render as literal text.

---

# Writing AI Prompts

> How to brief an AI assistant so the deck it produces actually builds
>
> Read this when: What do I tell an AI so the deck it writes actually builds?

Narro is text, so an AI can write a deck directly. What separates a usable
result from a broken one is mostly the setup, not the prose of the prompt.

## Give the model the dialect first

The single biggest failure mode is a model writing markdown in a syntax Narro
does not speak — usually one it half-remembers from Marp or reveal.js. Point it
at the reference before asking for slides:

> Read <https://getnarro.com/docs/markdown-mode.md>, then write a deck about …

Better still, paste the dialect contract from [Rules for AI
agents](/docs/agent-rules) into your project's `AGENTS.md` — a link is read
once, a contract in the repository is read every session.

For offline or sandboxed agents, install the docs instead:

```bash
npm install --save-dev @getnarro/docs
```

`node_modules/@getnarro/docs/generated/llms-full.txt` is every page in one file,
`catalog.json` is every name a deck may use, and `components.json` is the
component API generated from the TypeScript source — none of the three can be
out of date with the version installed.

## Prefer markdown mode

Ask for a `.md` deck unless you specifically need React. It is one file, the
failure modes are visible, and `npx @getnarro/cli build deck.md` gives a
pass/fail signal the model can act on.

## Make the model verify

A deck that "looks right" can still be broken, so close the loop:

> Write the deck to `deck.md`, run `npx @getnarro/cli check deck.md` after each
> edit, and `npx @getnarro/cli build deck.md` at the end. Fix anything either
> reports.

`check` validates names — layouts, slots, themes — in about a second, and names
the valid options when one is wrong. `build` is the slower, complete answer. In
React mode the equivalent is `npm run build`. Without these nothing catches a
mistyped prop, a layout that does not exist, or a component imported from the
wrong package.

## Be specific about the deck, not the styling

Narro's themes handle styling. What a model cannot guess:

- **Audience and level** — "staff engineers who have not used Kafka"
- **Length** — "8 slides"
- **Arc** — "problem, why the obvious fix fails, our approach, results, ask"
- **Content it cannot invent** — real numbers, names, the actual results

### A prompt that works

> Read <https://getnarro.com/docs/markdown-mode.md>. Write an 8-slide deck at
> `deck.md` introducing our migration from REST to gRPC, for backend engineers
> who have not used gRPC. Arc: what hurt about REST at our scale, why we did not
> just add caching, what gRPC changed, the migration path, the p99 numbers
> (340ms → 95ms), what we would do differently. Confident but not salesy. Use
> `layout: section` between chapters. Then run
> `npx @getnarro/cli build deck.md` and fix any errors.

### A prompt that does not

> Make a presentation about gRPC.

You get ten slides of generic bullets, in whatever dialect the model guessed.

## Two things models get wrong

**Which package a component comes from.** `@getnarro/core` exports the
presentation runtime and the motion and canvas primitives — exactly
`AnimatePresence`, `Canvas`, `CanvasElement`, `CanvasShape`, `ErrorBoundary`, `ErrorOverlay`, `MarqueeRow`, `MasonryBackground`, `Motion`, `MotionContainer`, `MotionList`, `MotionNumber`, `MotionPresence`, `MotionSpotlight`, `MotionStep`, `MotionSteps`, `MotionText`, `MotionTransform`, `NebulaBackground`, `Notes`, `OverviewGrid`, `Presentation`, `PresenterNotes`, `Slide`, `SlideContent`, `TransformSlide`, `TrustedByMarquee`.
Everything else, `Heading` and `Text` and `List` and the rest, is in
`@getnarro/shared-ui`. Importing `Heading` from core is the most common broken
deck.

**Prop values that sound plausible.** `SlideContent`'s `layout` is
"default" | "centered" | "top" | "bottom".
`Slide`'s `layout` is a different set. `List`'s `variant` is
"disc" | "decimal" | "check" | "arrow" | "none" —
not `"bullet"` or `"number"`. The [component reference](/docs/components) is
generated from the types, so it is the authority.

## The MCP server

[`@getnarro/mcp-server`](/docs/ai-integration) gives an assistant Narro-specific
tools — scaffolding, listing and editing slides, exporting — and serves this
documentation as MCP resources. Useful for assistants without their own shell
access; a coding agent that already has a terminal can just use the CLI.

---

# Rules for AI Agents

> Copy-paste contracts for your AGENTS.md, CLAUDE.md, or .cursor/rules
>
> Read this when: What do I paste into my repo so an agent stops writing decks that build wrong?

This page is a set of blocks meant to be **pasted into your own project's
`AGENTS.md`, `CLAUDE.md`, or `.cursor/rules`** — not a description of how Narro
works. A project scaffolded with `npm create narro@latest` already has all of
this in its `AGENTS.md`; this page exists for the case where you added Narro to
a repository that already existed, so nothing wrote that file for you.

Paste the two contracts below and the verification loop. Each one prevents a
specific failure that a model, left to its own defaults, produces reliably.

## Choose the entry point before you scaffold

The first decision, and the one most often made wrong — a deck ends up inside a
Vite application it never needed, and every later question is about the project
rather than the deck.

| The deck is | Use | You get |
| --- | --- | --- |
| Prose, lists, code, tables — one file | `npx @getnarro/cli new deck.md` | `deck.md`, nothing else |
| The same, but version-pinned in a repo | `npm create narro@latest x -- --template markdown-minimal` | `deck.md` + `package.json` |
| Needs its own dependencies or React layouts | `npm create narro@latest x -- --template markdown-app` | the deck inside a Vite project |
| Live components, data, interaction | `npm create narro@latest x` | a React deck |

A single markdown file in an empty directory is a complete deck: the CLI brings
its own runtime, so `npx @getnarro/cli dev deck.md` needs no `package.json`, no
`node_modules`, and no config. Custom layouts (`layouts/<name>.tsx`) and custom
CSS (`deck.css`) both work beside a bare `deck.md` — reaching for a project is
about dependencies, not capability.

## Why a contract rather than a link to the docs

A model that has not read Narro's documentation falls back on the presentation
tooling it has seen most: Marp, reveal.js, Slidev. Those have a different
markdown dialect and a different component model, and the resulting deck
**builds and renders wrong rather than failing** — directives appear as literal
text on the slide, a heading is imported from the wrong package, a layout name
that never existed silently falls back to the default. Nothing throws, so
nothing tells the model to try again.

The contracts below are written to be retrieved by the next agent that is about
to make one of those mistakes.

## Contract 1 — the markdown dialect

````markdown
## Narro markdown rules

Narro is not Marp, reveal.js, or Slidev. Their syntax does not work here and
fails silently — a directive Narro does not recognise renders as literal text
on the slide.

1. Slides are separated by a line of exactly `---`. A `---` inside a fenced
   code block does not split a slide.
2. The file opens with YAML deck frontmatter; each slide may carry its own
   frontmatter block immediately after its separator.
3. Attach styling with `{.class}` after an element — `# Revenue {.text-7xl}`.
   These are Tailwind classes. There is no `<!-- .element: -->` and no `<style>`
   block.
4. `{#id}` sets an element id; `{key=value}` sets a prop.
5. `::name::` on its own line opens a named layout slot. Every built-in layout
   takes `::header::` and `::footer::`; the column layouts take one slot per
   column —
   `default` takes `header`, `footer`; `cover` takes `header`, `footer`; `section` takes `header`, `footer`; `quote` takes `header`, `footer`; `end` takes `header`, `footer`; `two-column` takes `right`, `header`, `footer`; `three-column` takes `two`, `three`, `header`, `footer`; `image-right` takes `header`, `footer`; `image-full` takes `header`, `footer`.
   Content after a slot the layout does not read renders nowhere, silently.
6. Speaker notes are `<!-- notes: … -->`. Not `???`, not `Note:`.
7. `{.step}` on a list item reveals it on the next keypress — one press per
   marker, in source order, then the slide advances. There is no
   `<!-- .slide: data-fragment -->`.
8. Any frontmatter key beginning `x-` is yours: nothing reads it, and
   `check --strict` stays quiet. Use it to say what the file is.
9. Deck frontmatter keys are exactly:
   `title`, `author`, `date`, `theme`, `template`, `aspectRatio`, `transition`, `class`, `keyboard`, `mouse`, `touch`, `routing`, `favicon`, `maxDuration`.
   Slide frontmatter keys are exactly:
   `layout`, `class`, `id`, `transition`, `background`, `notes`.
   An unrecognised key is ignored, not reported.
10. Set `id:` on any slide you may edit again — it keeps diffs stable and makes
    the slide linkable.
11. `{ … }` takes whatever Tailwind calls a class, including arbitrary values
    (`text-[10px]`), opacity modifiers (`bg-white/5`), fractions, variants
    (`hover:`, `md:`), half-steps (`p-1.5`) and `!` overrides. On a list item it
    styles the `<li>`; on a fence, the `<pre>`.
12. Full dialect: https://getnarro.com/docs/markdown-mode.md
````

## Contract 2 — never invent a name

This is the one that matters most, because every failure it prevents is silent.
`layout: split` and `theme: corporate` both read exactly like names Narro would
have. Neither exists.

````markdown
## Narro closed sets

Every name a Narro deck can use is enumerated. If a name is not on the list, it
does not exist — do not reach for a plausible-looking alternative, and do not
assume a name from another presentation tool carries over.

- Built-in layouts (`layout:`):
  `default`, `cover`, `section`, `quote`, `end`, `two-column`, `three-column`, `image-right`, `image-full`
- Named slots, per layout:
  `default` takes `header`, `footer`; `cover` takes `header`, `footer`; `section` takes `header`, `footer`; `quote` takes `header`, `footer`; `end` takes `header`, `footer`; `two-column` takes `right`, `header`, `footer`; `three-column` takes `two`, `three`, `header`, `footer`; `image-right` takes `header`, `footer`; `image-full` takes `header`, `footer`.
  `::right::` on a three-column slide is a slot nothing reads, and the content
  silently disappears. The image layouts take their image from the slide's
  `image:` key (falling back to `background:`), not from a slot.
- Themes (`theme:`):
  `default`, `corporate-dark`, `minimalist-light`, `creative-gradient`, `ocean-blue`, `forest-green`, `sunset-warm`, `midnight-purple`, `tech-dark`, `startup-bold`, `academic-classic`
- Colour schemes — **palettes, not a frontmatter key**; `narro themes apply <id>
  --color-scheme`, or read from `@getnarro/marketplace`:
  `ocean-blue`, `sunset-warm`, `forest-mist`, `royal-purple`, `rose-gold`, `arctic-blue`, `charcoal-slate`, `emerald-night`
- Font presets — **not a frontmatter key**; `applyFontPreset(name)` from
  `@getnarro/core`:
  `system`, `inter`, `roboto`, `openSans`, `lato`, `montserrat`, `poppins`, `raleway`, `sourceSerif`, `playfairDisplay`, `merriweather`, `jetBrainsMono`

The complete machine-readable set — the above plus every component's props,
every exported string union (transitions, fragment effects, shapes, chart
types), every CLI command — is one fetch:

    https://getnarro.com/catalog.json

Offline, the same file is `@getnarro/docs/catalog.json` after
`npm i -D @getnarro/docs`, pinned to the version actually installed.

## Narro imports

Two packages. Reaching into the wrong one is the most common broken deck, and
it fails at build time rather than silently — but only after you have written
the whole file.

`@getnarro/core` — the presentation runtime plus the motion and canvas
primitives. Exactly these, and nothing else:

`AnimatePresence`, `Canvas`, `CanvasElement`, `CanvasShape`, `ErrorBoundary`, `ErrorOverlay`, `MarqueeRow`, `MasonryBackground`, `Motion`, `MotionContainer`, `MotionList`, `MotionNumber`, `MotionPresence`, `MotionSpotlight`, `MotionStep`, `MotionSteps`, `MotionText`, `MotionTransform`, `NebulaBackground`, `Notes`, `OverviewGrid`, `Presentation`, `PresenterNotes`, `Slide`, `SlideContent`, `TransformSlide`, `TrustedByMarquee`

`@getnarro/shared-ui` — every slide content component: `Heading`, `Text`,
`List`, `Code`, `Image`, and the rest
(53 in total).

`import { Heading } from "@getnarro/core"` does not resolve. If a component is
not in the `core` list above, import it from `@getnarro/shared-ui`. Every
component's package and props: https://getnarro.com/components.json, or one at
a time at https://getnarro.com/llms/<Component>.md.
````

## Contract 3 — verify, do not trust

Documentation tells a model what is possible. Only a checker tells it whether
what it wrote is correct, and a model with a fast checker self-corrects while a
model with only prose cannot.

````markdown
## Narro verification loop

Run after every edit, not once at the end:

    npx @getnarro/cli check deck.md

`check` parses the deck, resolves every layout, theme, slot, and directive
name, reports every class that was written but landed on no element, and exits
non-zero naming what was wrong and which names would have worked. It takes about
a second.

When you want to see what a slide says, without a browser:

    npx @getnarro/cli check deck.md --render

Before you finish:

    npx @getnarro/cli check deck.md --strict   # the CI gate: warnings are errors
    npx @getnarro/cli check deck.md --fit      # does it fit the slide? needs Chromium
    npx @getnarro/cli build deck.md            # markdown decks
    npm run build                              # React projects

A deck that renders is not a deck that is correct. `check` is the only thing
that catches a layout that does not exist, a slot name the layout has no slot
for, a theme that is not installed, or a class that attached to nothing — none of
which produce an error at render time. `--fit` is the only thing that catches a
slide whose content is clipped, in either mode: for a React deck, build first and
point it at `dist`.

Do not run Prettier over `deck.md`. A reflow can move an attribute block onto its
own line, which changes what it styles, silently. `narro fmt deck.md` is the safe
formatter.
````

## Predicting a name you have not looked up

Narro's naming is regular, so a name can usually be derived rather than
guessed. State the rule, not just the list — a model that knows the rule stops
producing coin-flip guesses:

| You want | The name is | Not |
| --- | --- | --- |
| A frontmatter key | `camelCase` — `aspectRatio`, `colorScheme`, `fontPreset` | `aspect-ratio`, `color_scheme` |
| A layout, theme, or colour scheme | `kebab-case` — `two-column`, `corporate-dark` | `twoColumn`, `TwoColumn` |
| A layout slot | the position, not the content — `::right::`, `::left::` | `::sidebar::`, `::second::` |
| A component | `PascalCase`, singular — `List`, `Image`, `Slide` | `Lists`, `SlideItem` |
| A Tailwind class in `{…}` | whatever Tailwind calls it | a Narro-specific alias |

Two places where the regularity breaks, and both bite:

**`layout` means two different things.** In slide frontmatter it is the
built-in layout name (`two-column`). On the React `SlideContent` component it
is a content alignment:
"default" | "centered" | "top" | "bottom".
They are separate closed sets and neither accepts the other's values.

**`List` variants are CSS marker names, not semantic ones.** `variant` is
"disc" | "decimal" | "check" | "arrow" | "none" —
not `"bullet"` and not `"number"`, which are the two a model reaches for first.

## The rest of the AI surface

- <https://getnarro.com/llms.txt> — the entry point: install commands, the
  closed sets, and every page with the question it answers
- <https://getnarro.com/llms-full.txt> — the same file with every page inlined,
  for one-fetch ingestion
- <https://getnarro.com/catalog.json> — the closed sets, machine-readable
- <https://getnarro.com/components.json> — every component's props, read out of
  the TypeScript types
- Any page as markdown: append `.md` to its URL
- `npm i -D @getnarro/docs` — all of the above through the npm registry, with
  no web access, pinned to the installed version

For an assistant with no shell, the [MCP server](/docs/ai-integration) covers
the same ground as tools. For one with a shell, documentation plus `check` is
the better setup — see [AI integration](/docs/ai-integration) for the split.