> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decktalk.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Slide recipes

> Six copyable DeckTalk slides with script lines, cues, and HTML, including a subtitle that follows the voice, a KaTeX derivation, a chat before-and-after, a code block, a two-column comparison, and a screenshot slide.

Each recipe below is a complete section: the lines for `script.md`, the entry for
`cues.json`, and the scene for `deck/index.html`. They use the stylesheet that
`decktalk init` writes, so paste them into the scaffold and build. They are recipes rather
than copies of the scaffold, whose own scenes are walked through in
[Your first deck](/guides/first-deck). The scene and step ids are placeholders, and any
section number works as long as the same number appears in the script heading, the
`[[section]]` table, and the `cues.json` key.

<Warning>Inside the backticks of a `render` template, write every backslash twice. The
`data-tex` value `\\frac{d}{dx}` reaches KaTeX as `\frac{d}{dx}`, and a single backslash
is swallowed by the template literal.</Warning>

## A subtitle that follows the voice

An element with `data-sync` reveals one word at a time, each at the second the voice
reaches it, so a line on the slide keeps pace with the narration. The scaffold uses it for
the subtitle of its title scene and for the three lines of its closing recap. The text
must be word for word what the voice says, because the runtime matches it against the
section's spoken words, ignoring case and punctuation, and prefers the run nearest the
cue. Give it `data-fx="none"`, since a fade on the container fights the per-word reveal.

```md script.md theme={null}
## 1. Open

Welcome. This is a narrated lesson, cut to the word. [beat] Every visual you see lands on
the word that introduces it.

## 5. Close

That is the whole idea. [beat] Write the script. [beat] Narrate it in your own voice.
[beat] And every reveal lands on its word.
```

```json cues.json theme={null}
"1": { "cues": [
  { "cue": "1.1a", "on": "$start" },
  { "cue": "1.1b", "on": "This is" },
  { "cue": "1.1c", "on": "lands on the word" }
] },
"5": { "cues": [
  { "cue": "5.1", "on": "$start" },
  { "cue": "5.1a", "on": "Write the script" },
  { "cue": "5.1b", "on": "Narrate it" },
  { "cue": "5.1c", "on": "every reveal" }
] }
```

```html deck/index.html theme={null}
DeckTalk.scene(1, { name: "Open", camera: "push", steps: [
  { id: "1.1", hold: 8, render: () => `
    <div class="slide">
      <h1 class="hero" data-cue="1.1a">My lesson</h1>
      <p class="line" data-cue="1.1b" data-sync data-fx="none">This is a narrated lesson, cut to the word.</p>
      <div class="lower" data-cue="1.1c" data-type="40" data-fx="fade">decktalk · scene 1</div>
    </div>` },
]});

DeckTalk.scene(5, { name: "Close", steps: [
  { id: "5.1", hold: 10, render: () => `
    <div class="slide">
      <p class="eyebrow">The whole idea</p>
      <p class="line" data-cue="5.1a" data-sync data-fx="none">Write the script.</p>
      <p class="line" data-cue="5.1b" data-sync data-fx="none">Narrate it in your own voice.</p>
      <p class="line" data-cue="5.1c" data-sync data-fx="none">Every reveal lands on its word.</p>
    </div>` },
]});
```

The cue mounts the line, and the words arrive from there. A line whose text differs from
the script by one word reveals whole, and the recorder logs
`data-sync text not found in the spoken words`. In a browser, `?scene=5` reveals each
line whole, because the preview has no word times.
[The runtime reference](/reference/runtime#data-attributes-inside-a-step) has the rules.

## A derivation that reveals line by line

This derivation is a recipe rather than a scaffold scene. Each line is its own element
with its own cue, and `data-display` typesets it as display math. The answer uses `pop`
so that it lands harder than the steps.

```md script.md theme={null}
## 3. The derivative of x squared

Start with the definition of the derivative, the limit of a difference quotient. [beat]
Expand the square, and the x squared terms cancel. [beat] Only two x is left.
```

```json cues.json theme={null}
"3": { "cues": [
  { "cue": "3.1a", "on": "definition" },
  { "cue": "3.1b", "on": "Expand" },
  { "cue": "3.1c", "on": "Only two x", "offset": 0.2 }
] }
```

```html deck/index.html theme={null}
DeckTalk.scene(3, { name: "The derivative of x squared", steps: [
  { id: "3.1", hold: 14, cues: { "3.1a": 1, "3.1b": 5, "3.1c": 9 }, render: () => `
    <div class="slide">
      <p class="math" data-cue="3.1a" data-display
         data-tex="\\frac{d}{dx}\\,x^2 = \\lim_{h \\to 0} \\frac{(x+h)^2 - x^2}{h}">d/dx x^2 = lim (x+h)^2 - x^2 / h</p>
      <p class="math" data-cue="3.1b" data-display
         data-tex="= \\lim_{h \\to 0} \\frac{2xh + h^2}{h} = \\lim_{h \\to 0} (2x + h)">= lim (2xh + h^2) / h = lim (2x + h)</p>
      <p class="math answer" data-cue="3.1c" data-fx="pop" data-display
         data-tex="\\frac{d}{dx}\\,x^2 = 2x">d/dx x^2 = 2x</p>
    </div>` },
]});
```

The plain text inside each element is what shows when KaTeX is absent, so write it as a
readable fallback.

## A chat before and after

The question types in with `data-type`, and the reply fades in one line at a time. The
bubble and its first line share a cue, so the bubble's background appears at once while
the text arrives. The second step is the "after", and its cue `4.2` mounts it. The
scaffold's own before-and-after scene syncs each prompt to the voice with `data-sync`
instead, which suits a prompt the narrator reads aloud.

```md script.md theme={null}
## 4. Before and after

Watch a vague prompt first. [beat] Write about photosynthesis. [beat] The reply is true,
and it is flat. [beat] One line says what it is. [beat] Another line says where it happens.

[Step 4.2.]

Now ask for what you actually want. [beat] Explain it to a ninth grader, in three
sentences. [beat] Same model, better prompt.
```

```json cues.json theme={null}
"4": { "cues": [
  { "cue": "4.1ask", "on": "Write about" },
  { "cue": "4.1r1", "on": "One line" },
  { "cue": "4.1r2", "on": "another line" },
  { "cue": "4.2", "on": "Now ask" },
  { "cue": "4.2ask", "on": "Explain it" },
  { "cue": "4.2reply", "on": "Same model" }
] }
```

```html deck/index.html theme={null}
DeckTalk.scene(4, { name: "Before and after", steps: [
  { id: "4.1", hold: 12, cues: { "4.1ask": 1, "4.1r1": 5, "4.1r2": 7 }, render: () => `
    <div class="slide">
      <p class="eyebrow">Before</p>
      <div class="chat">
        <div class="bubble ask" data-cue="4.1ask" data-type="40" data-fx="fade">Write about photosynthesis.</div>
        <div class="bubble reply" data-cue="4.1r1" data-fx="fade">
          <p data-cue="4.1r1" data-fx="fade">Photosynthesis is the process by which plants convert light into energy.</p>
          <p data-cue="4.1r2" data-fx="fade">It takes place in the chloroplasts.</p>
        </div>
      </div>
    </div>` },
  { id: "4.2", hold: 12, cues: { "4.2ask": 1, "4.2reply": 6 }, render: () => `
    <div class="slide">
      <p class="eyebrow">After</p>
      <div class="chat">
        <div class="bubble ask" data-cue="4.2ask" data-type="30" data-fx="fade">Explain photosynthesis to a ninth grader in three sentences.</div>
        <div class="bubble reply" data-cue="4.2reply" data-fx="pop">
          <p>Plants catch sunlight and use it to turn water and air into sugar.</p>
        </div>
      </div>
    </div>` },
]});
```

## A code block that reveals one line per phrase

Each line is a block element with its own cue. A container with `white-space: pre` and a
monospace font keeps the indentation, and `fade` avoids the vertical motion of `rise`,
which looks wrong on code.

```md script.md theme={null}
## 5. Three commands

Three commands run the whole thing. [beat] Initialize a project. [beat] Build it
silently, with no key. [beat] Then build it with your voice.
```

```json cues.json theme={null}
"5": { "cues": [
  { "cue": "5.1a", "on": "Initialize" },
  { "cue": "5.1b", "on": "silently" },
  { "cue": "5.1c", "on": "your voice" }
] }
```

```html deck/index.html theme={null}
<style>
  .code { font: 40px/1.5 ui-monospace, Menlo, monospace; white-space: pre; background: var(--surface); border-radius: 24px; padding: 40px 56px; }
  .code .cmt { color: var(--muted); }
</style>
<script>
DeckTalk.scene(5, { name: "Three commands", steps: [
  { id: "5.1", hold: 10, cues: { "5.1a": 1, "5.1b": 4, "5.1c": 7 }, render: () => `
    <div class="slide">
      <div class="code"><div data-cue="5.1a" data-fx="fade">decktalk init my-lesson</div><div data-cue="5.1b" data-fx="fade">decktalk build --silent   <span class="cmt"># no key</span></div><div data-cue="5.1c" data-fx="fade">decktalk build</div></div>
    </div>` },
]});
</script>
```

Keep the lines on one physical line inside the `render` template, because `white-space: pre`
would otherwise render the template's own indentation.

## A two-column comparison

Two columns, each with a heading and a caption, revealed left then right. The flex `cols`
class from the scaffold lays them out, and each column gets one cue.

```md script.md theme={null}
## 6. Two ways to time a reveal

On the left, a timeline. Every reveal is a number of seconds, and every edit moves them
by hand. [beat] On the right, the words. Every reveal is a phrase, and it follows the
sentence wherever it goes.
```

```json cues.json theme={null}
"6": { "cues": [
  { "cue": "6.1left", "on": "a timeline" },
  { "cue": "6.1right", "on": "the words" }
] }
```

```html deck/index.html theme={null}
<style>
  .col { flex: 1; background: var(--surface); border-radius: 24px; padding: 48px; min-height: 520px; }
  .col h2 { font-size: 56px; margin: 0 0 24px; }
</style>
<script>
DeckTalk.scene(6, { name: "Two ways to time a reveal", steps: [
  { id: "6.1", hold: 12, cues: { "6.1left": 1, "6.1right": 6 }, render: () => `
    <div class="slide">
      <div class="cols">
        <div class="col" data-cue="6.1left">
          <h2>A timeline</h2>
          <p class="line">Every reveal is a number of seconds.</p>
          <p class="caption">Every edit moves them by hand.</p>
        </div>
        <div class="col" data-cue="6.1right">
          <h2 class="accent">The words</h2>
          <p class="line">Every reveal is a phrase.</p>
          <p class="caption">It follows the sentence wherever it goes.</p>
        </div>
      </div>
    </div>` },
]});
</script>
```

## A screenshot slide that waits for the image

The recorder starts the narration clock only after `window.__sceneReady` resolves, so a
page with a large image should set that promise to the image's decode. Set it in a
script that runs before the runtime starts, because the runtime sets its own promise
only when the page has not. The image is decoded into the browser's cache, so the `img`
element inside the step appears at once when its cue fires.

```md script.md theme={null}
## 7. The status report

Here is the status report after a build. [beat] Every section shows a recording and a
cut, and the captions and chapters sit beside the video.
```

```json cues.json theme={null}
"7": { "cues": [
  { "cue": "7.1shot", "on": "status report" },
  { "cue": "7.1note", "on": "captions" }
] }
```

```html deck/index.html theme={null}
<style>
  .shot { width: 1600px; border-radius: 16px; box-shadow: 0 24px 80px rgba(0,0,0,.5); }
</style>
<script src="decktalk-runtime.js"></script>
<script>
const shot = new Image();
shot.src = "../media/status.png";
window.__sceneReady = document.fonts.ready.then(() => shot.decode()).catch(() => {});

DeckTalk.scene(7, { name: "The status report", steps: [
  { id: "7.1", hold: 10, cues: { "7.1shot": 0.5, "7.1note": 5 }, render: () => `
    <div class="slide">
      <img class="shot" src="../media/status.png" alt="" data-cue="7.1shot" data-fx="fade">
      <p class="caption" data-cue="7.1note">Captions and chapters sit beside the video.</p>
    </div>` },
]});
</script>
```

A page that sets its own `__sceneReady` and also uses `data-tex` should wait for
`window.katex` itself, because the runtime's KaTeX wait is part of the promise it would
otherwise have set. [The runtime reference](/reference/runtime#window-__sceneready) has
the details.

## Next

[The page contract](/concepts/page-contract#designing-the-stage) has the sizes and
margins that keep text readable at 1920 by 1080, and a table of which reveal effect
suits which element.