Authoring slides

Why MDX

Drever is AI-first, but its source is still designed for people. MDX keeps the outline, hierarchy, and prose visible without hiding behavior:

• Markdown is the default for headings, lists, quotes, images, and code.
• JSX appears only where an idea benefits from interaction or a reusable visual.
• Git shows meaningful text changes instead of a generated scene graph.
• An AI agent can revise the same file a person can review.

Pure HTML is more verbose for ordinary writing. Pure React is powerful, but makes every sentence look like implementation. MDX keeps those two modes in proportion.

Slide boundaries

Put a root-level thematic break between slides, with blank lines around it:

# Opening idea

The premise in one sentence.

---

## The next decision

Supporting evidence belongs here.

The boundary is protected Drever grammar, not an optional plugin. Remark and Rehype plugins cannot silently change pagination.

Progressive disclosure with Step

An omitted at is assigned in document order. Explicit values are positive static integers, and intentional gaps remain part of the route contract.

## Three deliberate moments

<Step>Shown at stop 1.</Step>
<Step at={3}>Shown at stop 3.</Step>

This slide navigates through 0 → 1 → 3; Drever never invents stop 2. A Step is presentation state, not a timer. It can be rehearsed, linked, restored, tested, and exported.

Author every Step directly in the slide body. Do not hide one inside a JavaScript expression, component implementation, or JSX-valued layout prop such as visual={<Step>...</Step>}; the compiler cannot turn those runtime branches into addressable routes.

A Step is also a real DOM wrapper. If it reveals absolutely positioned content, make the Step a stable positioned and explicitly sized or inset owner, or put those children in their own stable positioned wrapper. Do not let a pending-to-active transform or translate change which box owns their coordinates.

Persistent accessible labels are present from Step 0. Keep an ancestor aria-label limited to the premise already visible, and put outcome-specific names or descriptions inside the Step that reveals them. The visual and accessible story should advance together.

Speaker notes

<Note>Ask the room for its concern before advancing.</Note>

Notes appear in Speaker View. They are not mounted for the audience, included in Document View, or printed into the PDF. A public static build still contains the authored note source, so never put secrets or confidential information in <Note>.

React when the idea needs behavior

import { AudienceSignal } from "./AudienceSignal.tsx";

## Ask the room

What would help you decide?

<AudienceSignal />

Use normal React state, events, and composition. Inactive audience slides preserve local state through React Activity while leaving the accessibility tree. Components with media, global listeners, or network work must be reviewed in Audience, Speaker, Document, and PDF surfaces because the same authored component participates in each.

A useful default

Give each slide one dominant idea. Prefer prose until behavior improves understanding. Use Steps for meaningful pacing, not to make the slide look busy. Put the title and persistent context outside motion groups so navigation cannot make them drift.

Custom scene CSS inherits the active Theme. Normalize only conflicting Markdown margins, maximum widths, line height, text transform, and foreground inside the scene root, then inspect computed font, spacing, color, bounds, and the largest painted frame. Treat the first complete render as Draft 1 and refine from every exact slide and Step state; source review and a successful build are not visual evidence.