deckrun 1.4.0 → 1.6.0

package/README.md

@@ -5,7 +5,12 @@ Write slides in Markdown or bring a self-contained HTML document, run a local se
 - **Two formats** - Markdown decks with slide-by-slide presentation, or self-contained HTML documents with continuous scrolling
 - **Live editor** - edit alongside a live preview, with autosave and a library of all your decks and docs
 - **14 themes** - unique palettes, typography, animated backdrops, four type sizes, and customizable heading and body fonts
+- **Templates and motion** - four composition templates and five transitions, switchable without touching the Markdown
+- **Technical content** - KaTeX equations and Mermaid diagrams in preview, presentation, HTML, and PDF
+- **Incremental reveals** - step through bullets, prose, equations, code, or diagrams without duplicating slides
+- **Deck linting** - catch empty slides, broken fences/math, dense content, image issues, and invalid reveal markers locally or in CI
 - **Presenter tools** - laser pointer, drawing pen, blank canvas, blackout mode, and `?` for shortcuts
+- **Notes while presenting** - present from the editor and its preview and notes panel follow the deck tab, so the editor is your notes screen
 - **Export** - Markdown, HTML, headless-rendered PDF, or a standalone presenter-ready HTML page
 - **Local-first** - binds only to `127.0.0.1`; nothing is uploaded, and your work stays in browser local storage until export
 
@@ -21,7 +26,21 @@ npx deckrun
 
 ## Installation
 
-Install globally from npm:
+Install with a single command. On Linux and macOS the installer bootstraps
+Node.js (>= 16) automatically if it's missing, then installs deckrun from npm:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/arpitbbhayani/deckrun/master/install.sh | sh
+```
+
+On Windows, the PowerShell installer does the same (installs the Node.js LTS
+via winget, or downloads it, when needed):
+
+```powershell
+irm https://raw.githubusercontent.com/arpitbbhayani/deckrun/master/install.ps1 | iex
+```
+
+Or install globally from npm directly:
 
 ```bash
 npm install -g deckrun
@@ -31,8 +50,8 @@ Or run it without installing:
 
 ```bash
 npx deckrun              # open the editor
-npx deckrun slides.md    # present a local file
-npx deckrun <url>        # present a public Markdown or HTML URL
+npx deckrun slides.md    # open a local file in the editor, present from there
+npx deckrun <url>        # open a public Markdown or HTML URL in the editor
 ```
 
 ## Usage
@@ -41,10 +60,12 @@ npx deckrun <url>        # present a public Markdown or HTML URL
 # Write a new deck in the built-in editor
 deckrun
 
-# Serve on the default port 7890 and open the browser
+# Open a file in the editor on the default port 7890. The editor saves back
+# to the file, edits made to the file on disk reload the editor, and
+# Cmd/Ctrl+Enter presents.
 deckrun slides.md
 
-# Present a self-contained HTML page instead of a Markdown deck
+# Open a self-contained HTML page instead of a Markdown deck
 deckrun page.html
 
 # Serve on a custom port
@@ -53,6 +74,9 @@ deckrun slides.md -p 3000
 # Start the server without opening a browser tab
 deckrun slides.md --no-open
 
+# Open the file without watching it for changes on disk
+deckrun slides.md --no-watch
+
 # Show a launch overlay that enters fullscreen on the first key or click
 deckrun slides.md --fullscreen
 
@@ -63,19 +87,39 @@ deckrun slides.md --theme paper --size xl
 # Or set the two faces yourself
 deckrun slides.md --theme tokyo --head-font playfair --body-font lora
 
+# Recompose the same Markdown and choose how slides move
+deckrun slides.md --template editorial --transition fade
+
+# Check one or more decks before presenting or committing them
+deckrun lint slides.md
+deckrun lint talks/*.md --format json
+
 deckrun --list-themes
 deckrun --list-sizes
 deckrun --list-fonts
+deckrun --list-templates
+deckrun --list-transitions
 ```
 
 On start, the CLI prints the slide count and the local URL:
 
 ```text
-8 slides from slides.md
-present → http://127.0.0.1:7890  (Ctrl+C to stop)
+8 slides from slides.md · opening in the editor
+editor → http://127.0.0.1:7890  (Ctrl+C to stop)
+write on the left, live deck on the right. saves back to slides.md.
+edits to slides.md on disk reload the editor as well.
 ```
 
-With no file or URL, it starts the editor instead:
+A file passed on the CLI opens straight into the editor, backed by the file
+rather than the browser library: what you type autosaves back to the file,
+and edits made to the file on disk — from your own editor, a build step, an
+agent — reload the deckrun editor and its live preview. Pass `--no-watch`
+to turn off the disk watching. Presenting (`Cmd/Ctrl+Enter`) works exactly
+as it does for library decks. A document fetched from a URL opens the same
+way, but read-only toward its origin: nothing is written back, so download
+or duplicate it to keep changes.
+
+With no file or URL, it starts the editor on its browser library instead:
 
 ```text
 editor → http://127.0.0.1:7890  (Ctrl+C to stop)
@@ -89,17 +133,22 @@ The server binds to `127.0.0.1` only, so the deck is never exposed on the networ
 
 | Option                | Default | Description                                            |
 | --------------------- | ------- | ------------------------------------------------------ |
-| `[file]`              |         | Markdown file, HTML file, or public URL to present. Omit it to open the editor. |
+| `[file]`              |         | Markdown file, HTML file, or public URL to open in the editor. Omit it for a blank editor. |
 | `-p, --port <number>` | `7890`  | Port to serve the presentation on                      |
 | `--no-open`           | `false` | Start the HTTP server without opening the browser      |
+| `--no-watch`          | `false` | Do not watch the opened file for changes on disk       |
 | `--fullscreen`        | `false` | Prompt to enter fullscreen on the first key or click   |
 | `--theme <name>`      | `nord`     | Any of the fourteen themes, by id                   |
 | `--size <name>`       | `m`     | Type size: `s`, `m`, `l`, or `xl`                       |
 | `--head-font <name>`  |         | Override the theme's heading and title face             |
 | `--body-font <name>`  |         | Override the theme's body face                          |
+| `--template <name>`   | `classic` | Composition: `classic`, `minimal`, `editorial`, or `spotlight` |
+| `--transition <name>` | `slide` | Motion: `slide`, `fade`, `zoom`, `lift`, or `none`       |
 | `--list-themes`       |         | Print every theme with its mood and blurb, then exit    |
 | `--list-sizes`        |         | Print every type size with what it is for, then exit    |
 | `--list-fonts`        |         | Print every face and its kind, then exit                |
+| `--list-templates`    |         | Print every composition template, then exit             |
+| `--list-transitions`  |         | Print every slide transition, then exit                 |
 | `-v, --version`       |         | Print the version number                               |
 | `-h, --help`          |         | Print help for the command                             |
 
@@ -107,6 +156,25 @@ An unknown `--theme`, `--size`, or font is an error rather than a silent fallbac
 
 `--size`, `--head-font`, and `--body-font` apply to Markdown decks only. An HTML doc brings its own typography; passing any of them alongside an `.html`/`.htm` file prints a notice and is otherwise ignored.
 
+### `deckrun lint`
+
+The lint command performs fast, browser-free checks and reports the source
+line, slide number, severity, and rule id for each problem:
+
+```bash
+deckrun lint slides.md
+deckrun lint intro.md architecture.md
+deckrun lint slides.md --format json
+deckrun lint slides.md --max-warnings -1
+```
+
+It catches empty decks/slides, unclosed code fences and display math, untagged
+code fences, excessive prose or bullets, overly long headings, missing image
+alt text, invalid image opacity, and malformed or excessive reveal markers.
+Errors fail the command. Warnings also fail by default, making the command
+useful in CI; `--max-warnings N` changes that threshold and `-1` allows any
+number of warnings. Pass `-` as the file to lint standard input.
+
 ## The editor
 
 Run `deckrun` with no file and it serves an editor instead of a deck. A deck already in this browser resumes with no extra step, exactly as before. The first time you run it — or any time you choose "new" from the library with nothing open yet — you land on a start screen instead: a new Markdown deck, a new or uploaded HTML doc, or the library. Pick Markdown and you get the usual pane pair, Markdown on the left and the live deck on the right, plus a library of every deck and doc you have written.
@@ -123,7 +191,7 @@ The preview is not an approximation. Every keystroke is parsed by the same parse
 ### The two bars
 
 The top bar is for decisions: the deck name, the library, and then everything
-that changes what the deck looks like — `theme`, `font`, and the `S M L XL`
+that changes what the deck looks like — `template`, `theme`, `font`, and the `S M L XL`
 type size — with `guide`, `insert`, `new`, `export`, and `present` beside
 them.
 
@@ -159,6 +227,12 @@ Three surfaces exist so you never have to remember the syntax:
 
 A tip line in the status bar cycles through the rest.
 
+The Markdown start screen also carries template and transition choices. Pick
+them before creating or importing a deck, or use the `template` menu later.
+Templates are CSS compositions rather than source transformations, so changing
+one after the deck is finished immediately recomposes every slide while the
+Markdown remains byte-for-byte unchanged.
+
 ### Images
 
 Images are referenced by path, exactly as in a file-based deck. The editor serves the directory you launched in, so launch `deckrun` next to your diagrams and `![Diagram](diagram.png "right")` resolves.
@@ -173,7 +247,7 @@ Editing is a plain source pane on the left and a live preview on the right — n
 
 Presenting wraps the doc in an iframe and layers the tool belt that still makes sense with no slides — laser pointer, pen, blank canvas, blackout, fullscreen, and `?` for controls — on top of it. There is no HUD, slide counter, overview grid, or arrow-key navigation, since there is nothing to count or step through.
 
-A doc authored in the browser editor is expected to be self-contained: inline styles and scripts, and assets from a CDN or a `data:` URI rather than a relative local path, since editor-mode present and PDF serve it from an in-memory copy, not from a folder on disk. A file passed on the CLI does not have that restriction — `deckrun page.html` serves it from the file's own directory, exactly like a Markdown deck's images, so `<img src="diagram.png">` next to `page.html` resolves normally.
+A doc authored in the browser editor is expected to be self-contained: inline styles and scripts, and assets from a CDN or a `data:` URI rather than a relative local path, since editor-mode present and PDF serve it from an in-memory copy, not from a folder on disk. A file passed on the CLI does not have that restriction — `deckrun page.html` serves assets from the file's own directory, exactly like a Markdown deck's images, so `<img src="diagram.png">` next to `page.html` resolves normally.
 
 If a doc runs its own script that listens for keyboard input — an embedded framework, a game, a chart with its own shortcuts — it may end up racing deckrun's own listener for a key, since both are attached to the same page. Presenter shortcuts are best-effort in that case, not guaranteed to win.
 
@@ -219,7 +293,7 @@ With no such browser on the machine, the editor falls back to opening the deck w
 
 The HTML export is the same page `deckrun` serves: styles and the navigation runtime are inlined, so it opens from disk, and keyboard, touch, overview, and fullscreen all still work. Two things do not travel with it, since it is one file rather than a bundle:
 
-- Fonts and syntax highlighting load from a CDN, so a viewer needs a connection to see them exactly as you do. The theme's colors and its backdrop are inline, so those hold up offline.
+- Fonts, syntax highlighting, KaTeX, and Mermaid load from pinned CDNs in a standalone export, so a viewer needs a connection to see them exactly as you do. The theme, template, transitions, colors, and backdrop are inline.
 - Images and videos referenced by path stay on your disk. Ship them alongside, or host the page where those paths resolve.
 
 An HTML doc's PDF is not paginated to 16:9 slides — it prints the doc's own `@page`/print CSS (or Chrome's defaults if it has none), exactly as if you had opened the file yourself and pressed print. There is no presenter chrome to strip, since the doc is printed on its own, without the tool-belt wrapper.
@@ -370,6 +444,67 @@ function parseSlides(markdown: string): Slide[] {
 
 Code blocks scroll horizontally when a line is too long, so long lines never reflow mid-presentation.
 
+### Math and Mermaid diagrams
+
+KaTeX renders inline math with single dollar delimiters and display math with
+double dollars. The bracket forms `\(...\)` and `\[...\]` work too:
+
+```markdown
+The amortized cost is $O(1)$ per operation.
+
+$$
+T(n) = T(n/2) + O(n) = O(n)
+$$
+```
+
+Mermaid diagrams use an ordinary language-tagged fence:
+
+````markdown
+```mermaid
+sequenceDiagram
+  Client->>API: Request
+  API->>Store: Read
+  Store-->>API: Result
+  API-->>Client: Response
+```
+````
+
+Both render in the live preview, a presented deck, standalone HTML, and PDF.
+The editor waits for the equation or diagram before measuring slide overflow,
+and PDF rendering uses the copies installed with deckrun rather than waiting on
+a CDN. Invalid source stays visible as an error on the slide instead of
+silently disappearing.
+
+### Incremental reveals
+
+Append `{reveal}` to a bullet or another Markdown block. Forward navigation
+reveals each marked block before advancing to the next slide; backward
+navigation hides revealed blocks before returning to the previous slide:
+
+```markdown
+## Three stages
+
+- Parse the Markdown
+- Build semantic HTML {reveal}
+- Render the final slide {reveal}
+```
+
+Put the marker on its own line to reveal the entire block after it. This works
+for paragraphs, blockquotes, equations, code fences, and Mermaid diagrams:
+
+````markdown
+{reveal}
+```mermaid
+graph LR
+  Markdown --> HTML --> PDF
+```
+````
+
+The editor preview and grid show the complete slide so you can author and
+detect overflow against the final state. Overview thumbnails and PDF also show
+all content; reveals are interactive only while presenting. Reduced-motion
+preferences keep the reveal but remove its movement.
+
 ### Embeds and inline HTML
 
 Raw HTML passes through untouched, so anything the browser can render can live on a slide.
@@ -403,7 +538,7 @@ Rolling deployment with zero downtime.
 <!-- notes: Review database migration rollout steps before advancing. -->
 ```
 
-Every such comment is stripped from the slide, so notes never leak into the projected output or the PDF export. There is no presenter window yet, so the notes are not displayed anywhere either. See [Not supported yet](#not-supported-yet).
+Every such comment is stripped from the slide, so notes never leak into the projected output or the PDF export. When you present from the editor, the notes of the slide on screen are shown in the editor's notes panel instead.
 
 ### Image layout directives
 
@@ -561,6 +696,32 @@ Picking does not close the menu, because choosing a heading and then a body is
 one decision. Both are remembered per browser and travel into the deck you
 present and the PDF you export.
 
+### Templates and transitions
+
+Templates compose with themes. A theme owns color and type; a template owns
+spacing, alignment, rules, image treatment, and the overall reading rhythm:
+
+| id          | composition                                                        |
+| ----------- | ------------------------------------------------------------------ |
+| `classic`   | The original balanced deckrun layout                              |
+| `minimal`   | Quiet surfaces, wider margins, fewer decorative treatments        |
+| `editorial` | Strong rules and magazine-like reading rhythm                     |
+| `spotlight` | Centered, high-impact composition for concise keynote slides       |
+
+Pick one on the editor start screen or switch it later from the `template`
+menu. Switching only changes the root `data-template` attribute and CSS, so an
+existing deck transforms instantly and its Markdown is untouched.
+
+The same menu carries five independent transitions: `slide`, `fade`, `zoom`,
+`lift`, and `none`. `prefers-reduced-motion` suppresses their spatial motion,
+and print/PDF disables them entirely.
+
+```bash
+deckrun slides.md --template spotlight --transition zoom
+deckrun --list-templates
+deckrun --list-transitions
+```
+
 ### Type and motion
 
 Slides also assemble rather than appear: each top-level block on a slide rises
@@ -623,8 +784,8 @@ built deck, so overriding a single value in a fork stays a one-line change.
 
 | Key                                  | Action                                   |
 | ------------------------------------ | ---------------------------------------- |
-| `Right`, `Down`, `Space`, `PageDown` | Advance to the next slide                 |
-| `Left`, `Up`, `Backspace`, `PageUp`  | Return to the previous slide              |
+| `Right`, `Down`, `Space`, `PageDown` | Advance to the next reveal or slide       |
+| `Left`, `Up`, `Backspace`, `PageUp`  | Return to the previous reveal or slide    |
 | `Home`                               | Jump to the first slide                   |
 | `End`                                | Jump to the last slide                    |
 | `O`                                  | Toggle the overview grid                  |
@@ -690,6 +851,17 @@ Press `B` to drop the screen to black, for the moment when the room should be lo
 
 Press `F` at any time to toggle fullscreen. Browsers only grant fullscreen from a user gesture, which is what `--fullscreen` works around: it shows a launch overlay that requests fullscreen on the first key or click, so the deck opens fullscreen without a manual step.
 
+### Notes while presenting
+
+Present **from the editor** (`Cmd+Enter`) and the deck opens in its own tab; the editor tab stays yours. Its preview and speaker-notes panel follow the deck's current slide, so the deck goes on the projector and the notes stay on your screen.
+
+- A `following deck · n` chip appears in the status bar, showing the slide the deck is on. It follows however you advance the deck — keys, footer arrows, overview.
+- Typing in the editor (or clicking the chip) stops the following and hands the screen back to the caret. Presenting again turns it back on.
+- The link is live: it survives a reload of either tab.
+- The notes shown are the slide's `<!-- notes: ... -->`, the same text the audience never sees.
+
+A deck run straight from a file has no editor to follow it; present it through the editor instead (`deckrun`, then drag the file onto it, then `Cmd+Enter`) to get the notes during the talk.
+
 ## Visual design
 
 - Terminal aesthetics throughout, set in IBM Plex Mono with a blinking mauve cursor in the top right corner.
@@ -708,23 +880,22 @@ From the editor, press `Cmd Shift S` or pick PDF from the `export` menu, and a f
 - Slides are sized in absolute units for print. Viewport units resolve against the page box in paged media, which is why a deck laid out in `vw` and `vh` came out as clipped portrait pages.
 - The HUD, arrows, overview, cursor, pets, keyboard hint, fullscreen prompt, annotation canvas, laser pointer, blackout, and controls overlay are all hidden.
 - Speaker notes are stripped at parse time, so they never reach the PDF.
+- Incremental fragments are fully revealed, so printed and exported slides never omit content.
 
-Loading any deck with `?print=1` on the URL opens the print dialog once fonts and highlighting have settled. That is the editor's fallback when there is no browser to drive, and it works on a file-backed deck too:
-
-```bash
-deckrun slides.md --no-open
-# then open http://127.0.0.1:7890/?print=1
-```
+Loading any presented deck with `&print=1` on its URL opens the print dialog once fonts and highlighting have settled. That is the editor's fallback when there is no browser to drive.
 
 ## Local asset server
 
-`deckrun` serves the generated HTML at `/` and everything else relative to the directory holding the Markdown file. In editor mode there is no Markdown file, so it serves the directory you launched in. Local images, diagrams, videos, and fonts load over `http://` instead of `file://`, which avoids CORS restrictions on local assets.
+`deckrun` serves the editor at `/` and everything else relative to the directory holding the opened file. Launched without a file, it serves the directory you launched in. Local images, diagrams, videos, and fonts load over `http://` instead of `file://`, which avoids CORS restrictions on local assets.
 
 - Served types include HTML, CSS, JS, JSON, PNG, JPEG, GIF, SVG, WebP, AVIF, ICO, MP4, WebM, WOFF, WOFF2, and TTF. Anything else is sent as `application/octet-stream`.
 - Requests that resolve outside the Markdown file's directory return `403`. Missing files return `404`.
 - If the requested port is taken, the server falls back to a random free port and prints the URL it settled on.
 
-Google Fonts, Highlight.js, and the pet sprites load from CDNs, so a first run needs network access. Once the browser has cached them, the deck renders offline apart from the pets.
+KaTeX and Mermaid are served from the copies installed with deckrun, which
+keeps live preview and PDF rendering independent of the network. Google Fonts,
+Highlight.js, and the pet sprites still load from CDNs, so a first run needs
+network access for those visual extras.
 
 ## Generating decks and docs with Claude Code
 
@@ -750,7 +921,8 @@ deckrun
 
 The skill is a personal Claude Code skill and is not bundled with this package. Add it under `~/.claude/skills/blog-to-slides/SKILL.md` to make it available across projects.
 
-One caveat: the skill emits LaTeX for formulas, which `deckrun` does not render. Rewrite formulas as inline code or a code block, or drop them.
+Formulas emitted as dollar-delimited LaTeX render with KaTeX. Mermaid fences
+from generated Markdown render as diagrams as well.
 
 ### HTML documents
 
@@ -838,16 +1010,16 @@ Two decks ship in `examples/`:
 - `examples/example-2.md` is a full technical talk on databases and agentic AI
 
 ```bash
-# Run the feature showcase deck
+# Open the feature showcase deck in the editor
 deckrun examples/example-1.md
 
-# Or open the editor and drag either file onto it to edit
+# Or open the blank editor and drag either file onto it to import
 deckrun
 
-# Run the technical talk in light theme on port 3000
+# Open the technical talk in light theme on port 3000
 deckrun examples/example-2.md -p 3000 --theme solarized --size l
 
-# Run fullscreen without opening a browser
+# Present fullscreen on the first key or click, without opening a browser
 deckrun examples/example-1.md --fullscreen --no-open
 ```
 
@@ -855,11 +1027,8 @@ deckrun examples/example-1.md --fullscreen --no-open
 
 Worth knowing before you plan a talk around them:
 
-- No presenter view while presenting. The editor shows the notes for the slide you are on, but the presented deck has no second window, no next-slide peek, and no timer.
 - No live reload in file mode. Editing the file needs a restart of the CLI. The editor previews as you type, so use it for the writing loop.
-- No LaTeX or math rendering, and no Mermaid diagrams. Use fenced code blocks or ASCII diagrams.
-- No incremental reveal of bullets within a slide.
-- No slide-level transition or layout overrides beyond the image directives.
+- Templates and transitions currently apply to the whole deck rather than one slide at a time.
 - No `file://` mode. The deck always runs through the local HTTP server.
 - The editor does not upload or embed images. It stores Markdown, and images load by path from the folder you launched in.
 - The library lives in one browser and one origin. It does not sync between browsers or machines, so download anything you cannot afford to lose.
@@ -887,6 +1056,10 @@ The source:
 - `src/index.ts` is the CLI, the HTTP server, the editor routes, and port selection
 - `src/parser.ts` splits slides, extracts notes, and resolves image directives
 - `src/themes.ts` is the theme registry and the type scale: palettes, font catalog, backdrop patterns, size presets, and the CSS they all emit
+- `src/presentation-options.ts` is the composition-template and transition registry
+- `src/fragments.ts` contains incremental-reveal styles and DOM preparation shared by preview and presentation
+- `src/lint.ts` implements the static deck authoring rules behind `deckrun lint`
+- `src/rich-content.ts` detects and renders KaTeX and Mermaid content, with a shared readiness signal
 - `src/generate.ts` holds the slide CSS, the presenter chrome, and the deck runtime
 - `src/preview.ts` is the editor's preview iframe, sharing the slide CSS with the deck
 - `src/editor.ts` is the editor page: highlighting, palette, guide, nudges, autosave

package/dist/editor-content.js

@@ -8,6 +8,7 @@ export const SNIPPET_GROUPS = [
     "Text",
     "Lists & tables",
     "Code",
+    "Math & diagrams",
     "Images",
     "Embeds",
     "Actions",
@@ -48,6 +49,23 @@ export const SNIPPETS = [
         syntax: '<!-- notes: what to say here -->',
         insert: "\n<!-- notes: {caret} -->\n",
     },
+    {
+        id: "reveal-item",
+        group: "Slides",
+        label: "Reveal step",
+        hint: "Add the marker to a bullet or paragraph. Advance reveals it before changing slides.",
+        syntax: "- next point {reveal}",
+        insert: "{sel} {reveal}",
+    },
+    {
+        id: "reveal-block",
+        group: "Slides",
+        label: "Reveal next block",
+        hint: "A marker on its own line reveals the equation, code block, diagram, or paragraph after it.",
+        syntax: "{reveal}\\n```mermaid",
+        insert: "{reveal}\n{caret}",
+        block: true,
+    },
     // ── Text ─────────────────────────────────────────────────────────────────
     {
         id: "h2",
@@ -217,6 +235,42 @@ export const SNIPPETS = [
         insert: "```text\nClient --> [ LB ] --> [ App ] --> [ DB ]\n{caret}\n```",
         block: true,
     },
+    // ── Math & diagrams ─────────────────────────────────────────────────────
+    {
+        id: "math-inline",
+        group: "Math & diagrams",
+        label: "Inline math",
+        hint: "KaTeX renders the expression in the surrounding sentence.",
+        syntax: "$E = mc^2$",
+        insert: "${caret}E = mc^2$",
+    },
+    {
+        id: "math-display",
+        group: "Math & diagrams",
+        label: "Display equation",
+        hint: "Double dollar delimiters center a standalone equation.",
+        syntax: "$$\\sum_{i=1}^{n} x_i$$",
+        insert: "$$\n\\sum_{i=1}^{n} x_i = \\frac{n(n+1)}{2}\n$$",
+        block: true,
+    },
+    {
+        id: "mermaid-flowchart",
+        group: "Math & diagrams",
+        label: "Mermaid flowchart",
+        hint: "Rendered in the preview, presentation, HTML export, and PDF.",
+        syntax: "```mermaid\ngraph LR",
+        insert: "```mermaid\ngraph LR\n  A[Input] --> B{Valid?}\n  B -->|yes| C[Process]\n  B -->|no| D[Reject]\n```",
+        block: true,
+    },
+    {
+        id: "mermaid-sequence",
+        group: "Math & diagrams",
+        label: "Mermaid sequence",
+        hint: "Use a sequence diagram for request, event, and protocol flows.",
+        syntax: "```mermaid\nsequenceDiagram",
+        insert: "```mermaid\nsequenceDiagram\n  Client->>API: Request\n  API->>Store: Read\n  Store-->>API: Result\n  API-->>Client: Response\n```",
+        block: true,
+    },
     // ── Images ───────────────────────────────────────────────────────────────
     {
         id: "img-inline",
@@ -325,6 +379,11 @@ export const TIPS = [
     "L turns on a laser pointer while presenting. D gives you a pen to draw with.",
     "C drops a blank canvas over the slide, for the diagram you did not plan.",
     "B blacks out the screen mid-talk. Press it again to come back.",
+    "Write $E = mc^2$ for inline KaTeX, or wrap a display equation in double dollars.",
+    "A fenced mermaid block becomes a diagram in the preview, presentation, and PDF.",
+    "Templates change composition without touching your Markdown; transitions are independent.",
+    "Add {reveal} to a bullet or put it before a block to step through a slide one idea at a time.",
+    "Run deckrun lint slides.md before presenting or in CI to catch common authoring mistakes.",
 ];
 /** Deck loaded on a first visit. Doubles as the feature tour. */
 export const WELCOME_DECK = `# deckrun
@@ -365,6 +424,32 @@ func (w *WAL) Append(e Entry) error {
 
 ---
 
+## Math and diagrams stay in Markdown
+
+The same source renders live and survives PDF export:
+
+$$
+T(n) = T(n/2) + O(n) = O(n)
+$$
+
+\`\`\`mermaid
+graph LR
+  Markdown --> Preview --> Present --> PDF
+\`\`\`
+
+---
+
+## Reveal one idea at a time
+
+- This point is visible when the slide opens
+- This one appears on the next advance {reveal}
+- Then this one {reveal}
+
+{reveal}
+> A marker on its own line reveals the whole block after it.
+
+---
+
 ## Tables, lists, and accents
 
 | Configuration  | Throughput | p99 latency     |