diff --git a/assets/demo.tape b/assets/demo.tape
new file mode 100644
index 0000000..60685bb
--- /dev/null
+++ b/assets/demo.tape
@@ -0,0 +1,70 @@
+# Records a live Tapper session into assets/demo.gif (converted to
+# assets/demo.webp by scripts/record-demo.sh, which is the intended
+# entrypoint — it also handles cleanup and the gif->webp conversion).
+#
+# Every command below is relative to the project root, so don't run
+# `vhs assets/demo.tape` directly unless your shell is already cd'd there.
+
+Output assets/demo.gif
+
+Require php
+
+Set Shell "bash"
+Set FontSize 18
+Set Width 1200
+Set Height 700
+Set Padding 24
+Set WindowBar Colorful
+Set Theme "Dracula"
+Set TypingSpeed 40ms
+
+# Launch the log producer in the background, detached, before Tapper itself
+# is on screen — examples/BasicExample.php has no output of its own (every
+# line it prints goes over the socket to the TUI), so there is nothing to
+# hide visually, only the launcher command itself.
+Hide
+Type "rm -f tapper.sock tapper.log" Enter
+Type "nohup bash -c 'sleep 2 && php examples/BasicExample.php' > /dev/null 2>&1 & disown; clear" Enter
+Show
+
+Type "php bin/tapper"
+Enter
+
+# examples/BasicExample.php streams its scripted tp() calls into view over
+# the next ~7s, then blocks three times in a row on tp(...)->wait() — each
+# wait() only resolves on an Enter keypress inside the Tapper window itself,
+# so we send it here to keep the recording unattended.
+Sleep 9s
+Enter
+Sleep 2s
+Enter
+Sleep 2s
+Enter
+Sleep 3s
+
+# Details view: move the cursor up onto the large structured-data payload
+# and open it (Enter/Space) to show the syntax-highlighted JSON, scroll down
+# and to the right within it (Down/j and Right/l, see Details::down() and
+# Details::scrollRight()), then close it again (Backspace/Esc).
+Up 7
+Sleep 500ms
+Enter
+Sleep 1s
+Down 6
+Sleep 600ms
+Right 8
+Sleep 2s
+Backspace
+Sleep 500ms
+
+# Filtering: `/` opens the filter line (Console/Components/Filter.php),
+# typing narrows the list live, Enter confirms it, and Esc clears the
+# filter and jumps back to the live tail.
+Type "/"
+Sleep 300ms
+Type "wait"
+Sleep 800ms
+Enter
+Sleep 2500ms
+Escape
+Sleep 1500ms
diff --git a/assets/demo.webp b/assets/demo.webp
index c6dff2a..8572162 100644
Binary files a/assets/demo.webp and b/assets/demo.webp differ
diff --git a/scripts/record-demo.sh b/scripts/record-demo.sh
new file mode 100644
index 0000000..c40c830
--- /dev/null
+++ b/scripts/record-demo.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Regenerates assets/demo.webp: boots `php bin/tapper`, drives it with
+# examples/BasicExample.php, and records the session with VHS.
+#
+# Requires: vhs (brew install vhs), webp (brew install webp) for gif2webp.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if ! command -v vhs >/dev/null 2>&1; then
+    echo "error: vhs not found — install it with 'brew install vhs'" >&2
+    exit 1
+fi
+
+if ! command -v gif2webp >/dev/null 2>&1; then
+    echo "error: gif2webp not found — install it with 'brew install webp'" >&2
+    exit 1
+fi
+
+if [ ! -d vendor ]; then
+    echo "==> Installing composer dependencies"
+    composer install --no-interaction --no-progress
+fi
+
+# A previous run that crashed or was interrupted can leave a stale socket
+# and a `php bin/tapper` process holding it open.
+pkill -f 'php bin/tapper' 2>/dev/null || true
+rm -f tapper.sock tapper.log
+
+echo "==> Recording with VHS"
+vhs assets/demo.tape
+
+# VHS doesn't reliably reap the foreground `php bin/tapper` process when the
+# recorded shell session tears down.
+pkill -f 'php bin/tapper' 2>/dev/null || true
+rm -f tapper.sock tapper.log
+
+echo "==> Converting GIF to WebP"
+gif2webp -q 80 assets/demo.gif -o assets/demo.webp
+rm -f assets/demo.gif
+
+echo "==> Done: assets/demo.webp updated"