Conversation Replay

Create annotated replays of text conversations.

After parsing the annotated conversation data you supply in a YAML file, this tool will generate a self-contained embeddable HTML file. The published conversation can help with security awareness training and other communications that involve presenting an annotated text conversation.

- Conversation Replay
- How This Is Useful
- Installation
- Run Without Installing (Recommended)
- Global Install
- Install from GitHub
- Quick Start
- CLI Reference
- YAML Schema
- Basic Structure
- Step Types
- Message Options
- Meta Options
- Output Features
- Embedding in Websites
- Automatic "Seamless" Mode
- Basic Iframe Code
- Dark Mode Sync
- Multi-Scenario Demos
- Development
- Repository Structure
- Commands
- AI Agent Quick Reference
- Key Files
- Architecture
- Threat Modeling
- Author

How This Is Useful

Security training often involves showing how attacks unfold through text conversations—phishing emails, social engineering calls, BEC attempts, scammer chat interactions. Static screenshots lose the temporal element. Video production is time-consuming and hard to update.

Conversation Replay lets you:

- Define Conversations in YAML: Easy to create, annotate, review, and version control
- Generate Self-Contained HTML: No external dependencies, works offline
- Slick Design: Modern UI, nice typography, clean colors, and smooth animations
- Embed Anywhere: Seamlessly integrates into blogs and LMS platforms

To see it in action, see the replays embedded in the article that announced this tool and the examples folder.

Installation

$3

The easiest way to use Conversation Replay (no installation required) after you create the annotated conversation file demo.yaml:

``bash


Using npx (comes with Node.js)

npx conversation-replay build demo.yaml -o demo.html

Using bunx (comes with Bun)

bunx conversation-replay build demo.yaml -o demo.html
`

$3

For frequent use, install globally:

`bash


Using npm

npm install -g conversation-replay

Using Bun

bun add -g conversation-replay

Then run directly

conversation-replay build demo.yaml -o demo.html
`

$3

To install the latest development version directly from GitHub:

`bash
npm install -g github:lennyzeltser/conversation-replay
`

Note: This requires Bun to be installed (for the build step).

Quick Start

Generate a starter template, customize it, then build:

`bash


Create a documented template

conversation-replay init demo.yaml

Edit demo.yaml to define your conversation, then build

conversation-replay build demo.yaml -o demo.html

Open in browser

open demo.html
`

The generated replay is responsive, supports dark mode automatically, and looks nice across various browsers and devices.

To experiment with an example YAML file instead:

`bash
conversation-replay build examples/london-scam.yaml -o demo.html
`

CLI Reference

| Command | Description |
|---------|-------------|
| build -o | Generate HTML from a YAML file |
| validate | Check a YAML file for errors |
| init | Create a starter template with inline documentation |
| schema [section] | Show schema reference (sections: meta, colors, speed, steps) |
| info | Show tool name, version, and author |
| --version | Show version number |
| --help | Show help |

Options for build:
- --theme — Override theme (chat, email, slack, terminal, generic)
- --no-header — Exclude the header with title and description

For IDE autocompletion, add this to the top of your YAML file:
`yaml


yaml-language-server: $schema=https://raw.githubusercontent.com/lennyzeltser/conversation-replay/master/schema.json


`

YAML Schema

Run conversation-replay schema for a quick reference, or see below for details.

$3

`yaml
meta:
title: "Demo Title"
description: "Shown in header"
theme: chat # chat | email | slack | terminal | generic
autoAdvance: true # Auto-advance between scenarios

scenarios:
- id: scenario-1
title: "Scenario Name" # Shown in tab (if multiple scenarios)
participants:
- id: attacker
label: "Scammer"
role: left # Messages appear on left
- id: victim
label: "Target"
role: right # Messages appear on right
steps:
- type: message
from: attacker
content: "Hey, how are you?"
`

$3

| Type | Purpose | Renders As |
|------|---------|------------|
| message | Conversation turn | Chat bubble aligned left or right based on participant role |
| annotation | Educational note | Highlighted callout with vertical accent bar |
| transition | Scene break | Centered text card indicating time/scene change |

$3

`yaml


Basic message

- type: message
from: attacker
content: "Transfer the funds immediately."

Message with code block

- type: message
from: analyst
content: "Here's what I found:"
codeBlock: |
error: unauthorized access
source: 192.168.1.105

Message with footnote

- type: message
from: ai
content: "I can help with that."
footnote: "The AI performs a RAG search here."
`

$3

Display & Behavior:
`yaml
meta:
description: "Shown below title"
theme: chat # chat | email | slack | terminal | generic
articleUrl: "/related-article" # "View Article" link in header
annotationLabel: "Security Note" # Label for annotations
autoAdvance: true # Auto-play next scenario when current ends
hideHeaderInIframe: true # Hide header when embedded (default: true)
`

Timing & Visual:
`yaml
meta:
timerStyle: circle # circle | bar (countdown display style)
cornerStyle: rounded # rounded | straight (border radius)
initialBlur: 1 # Blur amount in px for initial play overlay (default: 1)
`

Custom colors (New Slate/Indigo Default Palette):
You can override any color:
`yaml
meta:
colors:
accent: "#4f46e5" # Indigo 600 (Buttons, links)
pageBg: "#f8fafc" # Slate 50 (Page background standalone)
canvasBg: "#ffffff" # Chat container background
leftBg: "#eef2ff" # Indigo 50 (Left bubble)
leftBorder: "transparent" # Border for left bubble
rightBg: "#f1f5f9" # Slate 100 (Right bubble)
rightBorder: "transparent" # Border for right bubble
tabInactiveColor: "#94a3b8" # Slate 400
annotationText: "#475569" # Slate 600 (Annotation text color)
annotationBorder: "#cbd5e1" # Slate 300 (Annotation accent bar)
`

Output Features

Generated HTML files include:

- Zero Dependencies: Everything inlined.
- Dark Mode: Automatic system preference detection and sync support.
- Seamless Embedding: Detects iframes and automatically removes padding/backgrounds.
- Accessibility: ARIA labels, keyboard navigation, reduced motion support.
- Controls: Floating glass bar with Play/Pause, Restart, and Speed (0.5x–4x).

Embedding in Websites

The player is designed to look good when embedded in web pages.

$3


When the the player detects it is running inside an iframe:
1. Removes Padding: The outer page padding is removed.
2. Transparent Background: The page background becomes transparent, blending with your website.
3. Hides Scrollbars: Internal scrollbars are hidden for a "video" look, while keeping content scrollable.

$3

`html
src="/demos/security-awareness.html"
style="width: 100%; height: 600px; border: none; border-radius: 12px; overflow: hidden;"
title="Security Awareness Demo"
loading="lazy"
>
`

$3

To sync the player's theme with your website's dark mode toggle:

`javascript
// Send a message to the iframe
const iframe = document.querySelector('iframe');
iframe.contentWindow.postMessage({
type: 'theme-change',
theme: 'dark' // or 'light'
}, '*');
`

Multi-Scenario Demos

Create rich, multi-part interactive stories using tabs.

`yaml
scenarios:
- id: part1
title: "Phishing Attempt"
steps: [...]

- id: part2
title: "Incident Response"
steps: [...]

- id: part3
title: "Remediation"
steps: [...]
`

- Tabs appear automatically at the top of the player.
- Horizontal scrolling: When tabs exceed the available width, arrow buttons appear for navigation. Works on desktop and mobile.
- Auto-Advance: If autoAdvance: true is set, the player smoothly transitions to the next tab when a scenario finishes.

Development

$3

`
conversation-replay/
├── src/
│ ├── cli.ts # CLI entry point
│ ├── parser.ts # YAML parsing & validation
│ ├── generator.ts # HTML generation (CSS/JS injection)
│ ├── schema.ts # Template generation & schema utilities
│ └── types.ts # TypeScript definitions
├── examples/ # Demo YAML files
├── schema.json # JSON Schema for IDE autocompletion
└── package.json
`

$3

`bash


Install dependencies

bun install

Run CLI during development

bun run src/cli.ts build examples/london-scam.yaml -o demo.html
bun run src/cli.ts validate examples/london-scam.yaml
bun run src/cli.ts init my-demo.yaml
bun run src/cli.ts schema
`

---

AI Agent Quick Reference

$3

| File | Purpose |
|------|---------|
| src/types.ts | Schema definitions. Edit this to add new YAML properties. |
| src/generator.ts | The core engine. Generates the HTML, CSS, and runtime JavaScript. |
| src/parser.ts | Input validation logic. |
| src/schema.ts | Template generation, JSON schema, and CLI schema reference. |
| schema.json | JSON Schema for IDE autocompletion. Regenerate with schema --json. |

$3

`
YAML Input -> Parser -> Generator -> Single HTML File
`

The generator produces a Single File Application:
- CSS: Generated dynamically in generateCss() based on theme/colors.
- JavaScript: Logic in generateJs() handles playback, tabs, and resizing.
- Data: Scenario data is injected as a JSON object constant.

---

Threat Modeling

- No External Calls: Generated files make no network requests.
- Safe Rendering: Uses textContent` to mitigate XSS.
- Input Validation: Strict schema validation mitigates injection during build.

Author

Lenny Zeltser: Builder of security products and programs. Teacher of those who run them.