Write a page by hand

decktalk init writes a deck that already builds, and copying one of its pages is the shortest route to a second one. This guide is for the other case: a page written from an empty file, because the deck belongs to a design that neither packaged example fits. Everything here is the same contract the starter obeys. A [data-scene] wrapper is one scene, each <template data-slide> inside it is one slide, an element has four moments and each moment is a cue name. No attribute says when a cue fires, because cues.json owns that.

The skeleton

deck/mine.html

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My lesson</title>

<link rel="stylesheet" href="/__decktalk/katex/katex.min.css">
<script src="/__decktalk/katex/katex.min.js"></script>
<script src="/__decktalk/decktalk-runtime.js"></script>

<style>
  :root { --ground: #ffffff; --ink: #0f0f12; --accent: #2c1fea;
          --sans: ui-sans-serif, system-ui, sans-serif; }
  html, body { margin: 0; background: var(--ground); color: var(--ink); font-family: var(--sans); }
  body { width: 100vw; height: 100vh; overflow: hidden; }
  #dt-canvas { background: var(--ground); }
  h1 { position: absolute; left: 120px; top: 190px; margin: 0; padding: 24px 40px; border-radius: 18px;
       background: var(--accent); color: #fff; font: 700 96px/1.1 var(--sans); }
</style>
</head>

<body>

<div data-scene="1" data-name="Open">
  <template data-slide="1.1" data-preview-seconds="10" data-describe="the opening title">
    <h1 data-in="title" data-describe="the title, My lesson">My lesson</h1>
  </template>
</div>

</body>
</html>

That is a complete page. It lists its scene when opened with no query, plays it with ?scene=1, and records under the cue times a run resolves.

Loading the runtime and KaTeX

DeckTalk serves two things itself, under /__decktalk/ on the origin it opens every page at: decktalk-runtime.js, the compiled runtime, and katex/, a pinned KaTeX release with its stylesheet and its font files. Both come from the installed engine, so the project holds no copy of either. Load them with the absolute paths above, which resolve the same from any directory a page sits in. KaTeX goes before the runtime, so the first slide is already typeset when the recorder starts the clock. The runtime waits for a typesetter a page asks for, and a page with data-tex on it and no KaTeX at all earns PAGE_KATEX_MISSING. A page with no equations needs neither line.

Load nothing from a network address. A recording that fetched a font, a stylesheet or a highlighter from somebody else’s server is a film that depends on a host it does not own, which is PAGE_CDN_ASSET. Copy the asset into deck/ instead, which is what the lesson example does with its bundled OFL fonts.

The canvas

The runtime builds a canvas element, #dt-canvas, of the frame’s shape with a short side of 1080 CSS pixels, 1920 by 1080 for a wide project, and scales it to fit the window. It puts the canvas’s size on :root as --dt-width and --dt-height and its shape as data-dt-shape, so a stylesheet that reads them lays the page out for a square or vertical frame as well. A page that declares its own <div id="dt-canvas"> keeps that element and the runtime builds around it, which is how a deck puts one background under all of its slides. Style it, and do not size it.

The scene wrapper

deck/mine.html

<div data-scene="1" data-name="Open">

data-scene is the id a [[section]] in decktalk.toml names in its scene key. data-name is the scene’s name in the index page and in the catalog, and a scene with no name is called “Scene” and its id. A wrapper holding no <template data-slide> is PAGE_SCENE_EMPTY. A moment attribute written on the wrapper itself, outside every template, has no slide to qualify it, so it is PAGE_MOMENT_UNKNOWN.

The slide templates

A slide is a <template> the runtime clones when the slide mounts. Four attributes belong to it.

Attribute	Values	Default	What it does
`data-slide`	any id	required	Declares the slide. Its id qualifies every moment written inside it.
`data-preview-seconds`	1 to 60 seconds	8	How long a preview rests on this slide. No recording reads it.
`data-enter`	`crossfade`, `cut`	`crossfade`	How this slide replaces the one before it. A crossfade is 0.24 s and a cut is instant.
`data-owns`	cue names, space separated	none	The cues only a handler serves, which no moment attribute mentions.

deck/mine.html

<template data-slide="1.4" data-preview-seconds="20" data-enter="cut" data-owns="long short"
          data-describe="the error drawn as a hill the model walks down">
  <h1 data-in="hill" data-describe="the heading, picture the error as a hill">Picture the error as a hill.</h1>
</template>

Use data-enter="cut" where the picture changes completely, because a crossfade there reads as a dissolve rather than as a new idea. data-describe on the template is the slide’s own subject, and data-describe on an element inside it is that element’s. Four rules the reader checks before a pixel is drawn.

A template inside a scene with no data-slide is PAGE_SLIDE_NO_ID.
Two templates claiming one id give every moment inside either of them two owners, which is PAGE_SLIDE_DOUBLED.
A template nested inside a slide with no data-slide of its own is never mounted, which is PAGE_TEMPLATE_IGNORED.
A slide no recorded section ever mounts is PAGE_SLIDE_UNUSED.

Design a slide covers the element attributes, and Slide recipes has a pattern for each thing they do.

The DeckTalk object

decktalk-runtime.js publishes window.DeckTalk, which is everything a page may call. A page written only in markup calls none of it.

Member	What it is
`DeckTalk.version`	The runtime version this page carries.
`DeckTalk.scene(id, definition)`	Declares one scene from script, for a slide built in code rather than written as a template. Returns `DeckTalk`, so calls chain.
`DeckTalk.on(cue, fn)`	Runs `fn` at one cue, wherever in the deck that cue belongs. Returns `DeckTalk`.
`DeckTalk.waitFor(promise)`	Holds the page’s readiness until a promise of your own has settled.
`DeckTalk.start()`	Reads the page and starts it, which a page that loads the runtime late may have to call itself.
`DeckTalk.frame(fn, { region })`	Calls `fn(t)` every frame with the section second, so something that moves is drawn from the second rather than from the wall clock. `region` is the element or selector it draws inside, which verify masks, and a hook with none is `PAGE_MOTION_UNDECLARED`. Returns `DeckTalk`.
`DeckTalk.motion(el, { from, to, ease, draw })`	Calls `draw(progress, seconds)` every frame between two cue ids, with the progress eased, and never after the arrival, so a `draw` still changing `el` then is `PAGE_MOTION_UNFINISHED`. Returns `DeckTalk`.
`DeckTalk.cues`	Every cue the page plays, keyed by cue id, against its second on the section clock.
`DeckTalk.words`	Every word the section speaks, as `{ word, at, voice, turn }`: the second it is said, the voice that says it and the turn it is said in.
`DeckTalk.stepTo(t)`	Moves the section clock to second `t` and shows it. The recorder calls this once a frame, and a page has no reason to call it.
`DeckTalk.scenes`	Every scene the page declared, as a Map keyed by scene id.
`DeckTalk.params`	The page’s own query, as `URLSearchParams`.
`DeckTalk.findSlide(id)`	The scene and slide one slide id names, or null.
`DeckTalk.buildSlide(scene, slide)`	One slide’s element, built and not yet wired.

window.__decktalk is the same page read back: the mode, the scene, the slide, the cues, the warnings and the measured catalog. The recorder and every check read the page through it, and a page never writes to it.

A cue a handler serves

deck/mine.html

const step = (left) => (slide) => {
  const thumb = slide.querySelector(".l-thumb");
  if (thumb) thumb.style.left = left;
};
DeckTalk.on("1.5:long", step("1500px")).on("1.5:short", step("90px"));

DeckTalk.on takes a cue id, because a handler may be registered anywhere in the deck and nothing around the call says which slide it means. A slide’s own owns and on keys are cue names, because the slide they belong to already says which slide that is.

A handler receives the mounted slide element, or null when no slide is mounted, and a context of id, the cue id of the cue, at, the second on the page clock, frozen, whether the page is a still, and slideId. A handler that throws earns PAGE_HANDLER_THREW, and the moment does nothing rather than the page failing. List in data-owns every cue a handler serves that no moment attribute names. That is what makes the slide the owner of the cue, and ownership is what decides when the slide is mounted. A cue in cues.json that no slide owns is PAGE_NO_OWNER, and a cue that fires and finds neither a moment nor a handler is PAGE_CUE_UNKNOWN.

A slide built in code

DeckTalk.scene declares a scene whose slides build their own markup. A scene declared in script and a [data-scene] wrapper with the same id are one scene, so a deck may be half markup and half code, and a slide that defines render keeps it rather than taking the markup of a template with its id.

deck/mine.html

DeckTalk.scene("2", {
  name: "How it works",
  slides: [
    {
      id: "2.1",
      previewSeconds: 14,
      enter: "crossfade",
      owns: ["sweep"],
      render: ({ frozen }) => `<h1 data-in="heading" data-describe="the heading">The average</h1>`,
      entered: (el, ctx) => { /* the slide has just mounted */ },
      on: { sweep: (el, ctx) => { /* the cue name, not the cue id */ } },
    },
  ],
});

A render returns the slide’s inner HTML and is given the scene, the slide and whether the page is frozen. It throws into PAGE_RENDER_THREW, entered throws into PAGE_ENTER_THREW and a handler in on throws into PAGE_SLIDE_HANDLER_THREW, and in every case the slide is drawn as its markup stands rather than the page failing.

Inside the backticks of a render, every backslash has to be written twice, because the markup is a JavaScript string. In a <template> a backslash is written once. That alone is reason enough to write an equation as a template.

Waiting for something of your own

deck/mine.html

const image = new Image();
image.src = "./media/status.png";
DeckTalk.waitFor(image.decode());

DeckTalk.waitFor holds the page’s readiness until the promise settles, so the recorder does not start the clock on a page that is still loading. The budget is five seconds. A promise that rejects is PAGE_WAIT_REJECTED, one that never settles is PAGE_WAIT_UNSETTLED, and the page is drawn either way, so a missing file never hangs a build.

The query keys the runtime reads

One URL decides which of four things the page is doing: it lists its scenes, it previews one, it plays one against the section clock, or it freezes one slide. The query keys lists every key and what it asks for. after and before are answered by the probe that decktalk check and decktalk storyboard inject into the page. A page you open yourself with ?freeze=1.1 freezes that slide with every one of its cues fired, and a cue those two keys name that the slide does not declare is PAGE_FREEZE_CUE_UNKNOWN on the page’s own console. No command reports it, because storyboard draws a panel only for a cue the slide declares.

Open the page yourself

The recorder opens every page over http, and decktalk serve is the one supported way to open it yourself.

$ decktalk serve
Serving http://127.0.0.1:56257

A page opened from a file:// URL draws nothing. The browser resolves /__decktalk/decktalk-runtime.js against the root of the disk, finds no file there, and the page has no runtime to mount its slides. It serves the deck directory and the files decktalk.toml declares, and nothing else. It prints where the deck is served as one object, flushed at once, and then serves until you stop it. Its output stays open while it serves, so a caller reads the object as it arrives rather than waiting for the stream to end. --host and --port choose the interface and the port, and a port of 0 takes any free one. The deck directory is every directory a page sits in, so every name under it is served however the page spells it. A file outside it, such as a clip, a words file or a sound, is served only by the spelling decktalk.toml gives it. Write the same name in the page, down to its case, because a request for Media/Intro.mp4 is refused when the project declared media/intro.mp4, on every platform alike. The recorder opens the page under the same rule, so a page that previews cleanly records cleanly. Open the page by its path under that origin, such as http://127.0.0.1:56257/deck/mine.html:

The page with no query lists every scene and every slide, and links a preview and a still of each.
deck/mine.html?scene=1 previews that scene. Once decktalk cue has run, the preview asks the origin for the cue times that run resolved and plays the film’s own timing. With none to find, it fires each cue a second apart so a deck whose cues have never been resolved still shows its whole self.
deck/mine.html?scene=1&speed=4&hud=1 reviews a long scene quickly with the clock and the cue list on screen.
deck/mine.html?freeze=1.1 freezes one slide with its cues fired.

Put the page in the project

decktalk.toml

[[section]]
number = 1
chapter = "Open"
page = "deck/mine.html"
scene = "1"

The section number, the scene its [[section]] names and the slide ids of its cues agree, which is the shape every DeckTalk project follows. Then write the section’s narration in script.md and one row per moment in cues.json, and judge the three together:

decktalk check

Make each reveal survive a check: Design a slide
Copy a pattern that already ships: Slide recipes
Look up every attribute and finding: run decktalk schema page

Get started

Use cases

Concepts

Guides

Reference

Agents

Design decisions

Help

Write a page by hand

The skeleton

Loading the runtime and KaTeX

The canvas

The scene wrapper

The slide templates

The DeckTalk object

A cue a handler serves

A slide built in code

Waiting for something of your own

The query keys the runtime reads

Open the page yourself

Put the page in the project

Next

​The skeleton

​Loading the runtime and KaTeX

​The canvas

​The scene wrapper

​The slide templates

​The DeckTalk object

​A cue a handler serves

​A slide built in code

​Waiting for something of your own

​The query keys the runtime reads

​Open the page yourself

​Put the page in the project

​Next

The skeleton

Loading the runtime and KaTeX

The canvas

The scene wrapper

The slide templates

The DeckTalk object

A cue a handler serves

A slide built in code

Waiting for something of your own

The query keys the runtime reads

Open the page yourself

Put the page in the project

Next