From 8aa061f8d2046a3ab727f7ec39f17969cc3f8fdc Mon Sep 17 00:00:00 2001
From: codeonym <bouarourayoub0@gmail.com>
Date: Tue, 10 Nov 2026 13:26:43 +0000
Subject: [PATCH 1/2] feat: preserve narration and write SRT/VTT captions (#3)

---
 README.md                                     |  18 ++-
 .../decisions/001-one-caption-per-step.md     |  15 +++
 .../decisions/002-player-wraps-plain-text.md  |  16 +++
 .../003-skip-empty-or-zero-duration-cues.md   |  14 +++
 ...scape-text-with-srt-compatibility-limit.md |  26 +++++
 .../draft.md                                  |  23 +++-
 .../history/2026-11-10_1231_draft.md          |  24 ++++
 .../history/2026-11-10_1231_meta.md           |  12 ++
 .../history/2026-11-10_1246_meta.md           |  12 ++
 .../history/2026-11-10_1324_impl.md           |  88 +++++++++++++++
 .../history/CHANGES.md                        |   4 +
 .../impl.md                                   | 103 ++++++++++++++++++
 .../meta.md                                   |   6 +-
 src/runner/captions.ts                        |  27 +++++
 src/runner/run.ts                             |   8 +-
 test/e2e/player.ts                            |  50 +++++++++
 test/e2e/record.test.ts                       |  42 ++++++-
 test/unit/captions.test.ts                    |  69 ++++++++++++
 test/unit/schema.test.ts                      |   7 ++
 19 files changed, 546 insertions(+), 18 deletions(-)
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/001-one-caption-per-step.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/002-player-wraps-plain-text.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/003-skip-empty-or-zero-duration-cues.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/004-escape-text-with-srt-compatibility-limit.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_draft.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_meta.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1246_meta.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1324_impl.md
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/impl.md
 create mode 100644 src/runner/captions.ts
 create mode 100644 test/e2e/player.ts
 create mode 100644 test/unit/captions.test.ts

diff --git a/README.md b/README.md
index 014f975..eb93935 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,8 @@ Record reproducible feature demos from a short Playwright script. A coding agent
 writes the script, and `flow-reel` replays it in a sandbox on a virtual display while recording the screen. The same
 script gives the same video, step for step.
 
-This release records **silent** video with step timings. Narration, captions, voice, cursor and zoom polish, and sound
-effects come in later releases.
+This release records **silent** video with narration text, captions and step timings. Voice, cursor and zoom polish,
+and sound effects come in later releases.
 
 ## Requirements
 
@@ -58,8 +58,18 @@ Next to the script:
 | File | What it is |
 |---|---|
 | `settings.mp4` | The silent demo, 1920×1080, 30 fps. |
-| `settings.transcript.json` | Each step's `startMs`, `actionEndMs` and `endMs` on the video's timeline (schema version 1). |
+| `settings.transcript.json` | Each step's original narration and `startMs`, `actionEndMs` and `endMs` on the video's timeline (schema version 1). |
 | `settings.events.json` | Every move, click, keystroke run and scroll the runner made, timed the same way (schema version 1). |
+| `settings.srt` | Captions for a subtitle-capable video player. |
+| `settings.vtt` | WebVTT captions for a browser's `<video>` / `<track>`. |
+
+Each caption shows one step's narration from its `startMs` to its `endMs`. Caption whitespace is normalized and the
+player wraps the text; the transcript keeps the original narration. Blank narration and steps lasting zero
+milliseconds stay in the transcript but produce no caption. Short actions can be too brief to read: step holds for
+voice clips come in a later release.
+
+Captions escape `&`, `<` and `>` so narration is emitted without raw tags. WebVTT displays the literal text; some
+SRT players display escape sequences such as `&lt;` instead. Use WebVTT in a browser when literal symbols matter.
 
 In `.flow-reel/settings/`: the 2560×1440 master the polish steps will render from. The `.flow-reel/` folder ignores
 itself in git; the files next to the script are yours to commit or not.
@@ -76,7 +86,7 @@ a script have the same steps, each starting within ±150 ms.
 
 ## Known gaps
 
-- No narration, captions or audio yet.
+- No synthesized voice or audio yet; narration is text only.
 - No cursor drawn in the video yet: the runner logs the motion in `events.json` for the polish step.
 - Playwright calls the runner doesn't cover run without any mouse motion (the warning names them).
 
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/001-one-caption-per-step.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/001-one-caption-per-step.md
new file mode 100644
index 0000000..d209392
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/001-one-caption-per-step.md
@@ -0,0 +1,15 @@
+# 001: One caption cue per step, using its recorded boundaries
+
+**Date:** 2026-11-10 (GH-3 ticket pass, Q1; recommended option 1, agreed: "ok")
+
+**Question:** should long narration stay in one caption or be split into shorter cues?
+
+**Decision:** emit one cue per captioned step, containing its complete narration, from `startMs` to `endMs`.
+Do not split narration into separately timed chunks or extend the step for readability. GH-5 owns voice holds;
+captions use the resulting boundaries when those holds exist.
+
+- **Why:** the runner knows step boundaries but has no timing for individual words or sentences. The same rule
+  works before and after voice is added.
+- **Not chosen:** splitting long narration into shorter cues (would introduce estimated timing before voice exists).
+- **Cost accepted:** long narration can occupy several lines, and short actions can give little reading time until
+  GH-5 introduces voice holds.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/002-player-wraps-plain-text.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/002-player-wraps-plain-text.md
new file mode 100644
index 0000000..b9c7053
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/002-player-wraps-plain-text.md
@@ -0,0 +1,16 @@
+# 002: Players wrap plain caption text; the transcript preserves narration
+
+**Partly superseded by 004** (SRT players may display escape sequences instead of the literal characters).
+
+**Date:** 2026-11-10 (GH-3 ticket pass, Q2; recommended option 1, agreed: "ok")
+
+**Question:** should captions use player-controlled wrapping or fixed-length line breaks?
+
+**Decision:** normalize caption whitespace into a single line and let the player wrap it for its display. Preserve
+the original narration unchanged in the transcript. Emit narration as literal caption text, using the format's
+escaping rules so markup-like input is not interpreted as styling or cue structure.
+
+- **Why:** wrapping adapts to the player's available width without inventing fixed character limits or altering the
+  narration stored for later voice synthesis.
+- **Not chosen:** inserting line breaks at a fixed length (extra formatting rules, awkward on smaller displays).
+- **Cost accepted:** visual line breaks can differ between players and display sizes.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/003-skip-empty-or-zero-duration-cues.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/003-skip-empty-or-zero-duration-cues.md
new file mode 100644
index 0000000..58dcfea
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/003-skip-empty-or-zero-duration-cues.md
@@ -0,0 +1,14 @@
+# 003: Skip captions with blank text or no duration
+
+**Date:** 2026-11-10 (GH-3 ticket pass, Q3; recommended option 1, agreed: "ok")
+
+**Question:** should blank narration or a zero-duration step skip its caption or fail the recording?
+
+**Decision:** preserve every step and its original narration in the transcript. Emit a caption only when its
+normalized narration is nonblank and `endMs > startMs`. Skipping a cue never removes a transcript step, changes
+timing, extends a step, or fails an otherwise successful recording. Number emitted SRT cues consecutively.
+
+- **Why:** intentionally silent and instantaneous actions remain valid, while subtitle files contain only usable
+  cues on the recorded timeline.
+- **Not chosen:** failing recordings that include these steps (unnecessarily forbids silent steps).
+- **Cost accepted:** not every transcript step has a corresponding subtitle cue.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/004-escape-text-with-srt-compatibility-limit.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/004-escape-text-with-srt-compatibility-limit.md
new file mode 100644
index 0000000..d8847ea
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/decisions/004-escape-text-with-srt-compatibility-limit.md
@@ -0,0 +1,26 @@
+# 004: Escape caption text and document SRT player differences
+
+**Date:** 2026-11-10 (GH-3 ticket pass, Q4; recommended option 1, agreed: "ok")
+
+**Partly supersedes 002:** literal text is guaranteed by WebVTT escaping; SRT players may display the escape sequences.
+
+**Question:** how should markup-like narration be handled when SRT players do not consistently decode escapes?
+
+**Decision:** after normalizing caption whitespace, escape `&`, `<` and `>` as `&amp;`, `&lt;` and `&gt;` in both
+formats. Escape original characters once, preserving existing entity-looking input as literal text in WebVTT.
+Keep original narration unchanged in the transcript. Document that some SRT players display these sequences rather
+than decoding them; do not promise identical literal rendering across all players.
+
+- **Why:** captions do not emit raw tags; WebVTT can represent the original text, and SRT has a clear, documented
+  compatibility limit without changing the script API or rejecting narration.
+- **Not chosen:** raw SRT text (players may interpret tags as styling).
+- **Cost accepted:** SRT captions containing special characters may show escape sequences in some players.
+
+## Sources checked
+
+- [WebVTT syntax and cue text](https://www.w3.org/TR/webvtt1/#syntax): cue text supports character references;
+  encoding `>` also prevents a raw `-->` inside a cue payload.
+- [Library of Congress SRT description](https://www.loc.gov/preservation/digital/formats/fdd/fdd000569.shtml):
+  describes the format's structure and player-dependent formatting.
+- [FFmpeg subtitle decoder](https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/htmlsubtitles.c): handles tags
+  and otherwise copies text; HTML entity decoding must not be assumed for SRT playback.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/draft.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/draft.md
index f7b2587..6b92993 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/draft.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/draft.md
@@ -6,19 +6,30 @@ After ticket 1 the video has timings but no words: a viewer can't tell what each
 
 ## Change
 
-- Each step's `narration` (the first argument of `step()`) goes into `transcript.json` (decision 011).
-- `demo.srt` and `demo.vtt` are written from the steps' `narration`, `startMs` and `endMs`.
+- Each step's original `narration` (the first argument of `step()`) goes into `demo.transcript.json` unchanged
+  (story decision 011). Version 1 transcripts without narration remain valid.
+- `demo.srt` and `demo.vtt` are written beside the script and MP4, from the final calibrated `startMs` and `endMs`.
+- One cue per captioned step, with no splitting or added reading time (ticket decision 001).
+- Caption whitespace is normalized and players wrap the text; the transcript retains original whitespace
+  (decision 002). Blank narration and zero-duration steps produce no cue but stay in the transcript (decision 003).
+- Caption text escapes `&`, `<` and `>`. WebVTT displays literal text; some SRT players display escape sequences.
+  This compatibility limit is documented (decision 004).
 
 ## Out of scope
 
-Voice (tickets 3-4); burned-in captions (polish, a later story).
+Voice, step holds and audio muxing (GH-4/GH-5); burned-in captions; cursor/zoom polish; caption styling options.
 
 ## Done when
 
 - The sample demo writes captions that play in sync in a standard player (mpv, VLC, a `<video>` with `<track>`).
 - Two runs give identical caption text and step order.
+- New recordings preserve original narration on every transcript step, and each emitted cue uses that run's
+  final step boundaries. Recording timing stays unchanged.
+- Tests cover whitespace, escaping, Unicode, timestamp boundaries, skipped cues, old transcripts and empty output.
+- Generated WebVTT loads in a real browser with correct decoded text and times; generated SRT parses with correct
+  times, and its player-dependent escaping limitation is documented.
 
-## For the ticket pass
+## Decisions and implementation
 
-- Long narration: one cue per step, or split into cues by length?
-- Escaping and line breaking in SRT/VTT.
+Ticket decisions 001-004 settle cue boundaries, wrapping, skipped cues and escaping. See `impl.md` for the build
+steps, checks and compatibility risks.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_draft.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_draft.md
new file mode 100644
index 0000000..f7b2587
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_draft.md
@@ -0,0 +1,24 @@
+# Narrate steps in the transcript and write SRT/VTT captions
+
+## Problem
+
+After ticket 1 the video has timings but no words: a viewer can't tell what each step shows.
+
+## Change
+
+- Each step's `narration` (the first argument of `step()`) goes into `transcript.json` (decision 011).
+- `demo.srt` and `demo.vtt` are written from the steps' `narration`, `startMs` and `endMs`.
+
+## Out of scope
+
+Voice (tickets 3-4); burned-in captions (polish, a later story).
+
+## Done when
+
+- The sample demo writes captions that play in sync in a standard player (mpv, VLC, a `<video>` with `<track>`).
+- Two runs give identical caption text and step order.
+
+## For the ticket pass
+
+- Long narration: one cue per step, or split into cues by length?
+- Escaping and line breaking in SRT/VTT.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_meta.md
new file mode 100644
index 0000000..721f93c
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1231_meta.md
@@ -0,0 +1,12 @@
+---
+kind: ticket
+title: Narrate steps in the transcript and write SRT/VTT captions
+key: GH-3
+parent: GH-1
+status: tracked
+branch:
+tracker-url: https://github.com/codeonym-oss/flow-reel/issues/3
+mr:
+created: 2026-11-02
+updated: 2026-11-02
+---
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1246_meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1246_meta.md
new file mode 100644
index 0000000..c15441c
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1246_meta.md
@@ -0,0 +1,12 @@
+---
+kind: ticket
+title: Narrate steps in the transcript and write SRT/VTT captions
+key: GH-3
+parent: GH-1
+status: planned
+branch:
+tracker-url: https://github.com/codeonym-oss/flow-reel/issues/3
+mr:
+created: 2026-11-02
+updated: 2026-11-10
+---
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1324_impl.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1324_impl.md
new file mode 100644
index 0000000..c527de5
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1324_impl.md
@@ -0,0 +1,88 @@
+# Implementation: Narration text and SRT/VTT captions
+
+Planned 2026-11-10 against `main` at `a5e83798cdebfd817b7404a70868575236b55503`, after GH-2 merged as PR #10.
+Scope: preserve narration and write caption sidecars; the MP4 stays silent. Settled by story decisions 009-011,
+GH-2 decision 006 (output locations), and this ticket's decisions 001-004. No follow-ups are taken up.
+
+## Current code and baseline
+
+- `src/index.ts` already defines `step(narration, action)`; `src/runner/run.ts` receives the text but omits it from
+  `steps.push()`. The runner calibrates all step times before writing the final transcript.
+- `src/schema/transcript.ts` already accepts optional `narration` in version 1. Keep that optional field so old
+  GH-2 transcripts remain valid; new recordings write narration on every step.
+- No caption module or output exists. `test/e2e/record.test.ts` already records the same fixture twice and checks
+  output validity, timing reproducibility and click/frame alignment.
+- Baseline: all 7 schema tests and `npm run typecheck` passed during the ticket pass. The previous project check
+  passed all 36 unit tests. Docker E2E was not rerun for planning; GH-2's merged PR had passing E2E CI.
+
+## Read first
+
+- `../../decisions/009-what-counts-as-the-same-video.md`, `010-demo-script-api.md`, `011-transcript-json-schema.md`.
+- `../GH-2-silent-replay-recording-sandbox/decisions/006-intermediates-in-flow-reel-folder.md`.
+- This ticket's `decisions/001`-`004`.
+- `src/runner/run.ts`, `src/schema/transcript.ts`, `src/index.ts`.
+- `test/unit/schema.test.ts`, `test/e2e/record.test.ts`, `README.md`, `.github/workflows/ci.yml`.
+- [WebVTT file syntax](https://www.w3.org/TR/webvtt1/#syntax) and the source notes in decision 004.
+
+## Steps
+
+1. **Add a pure caption serializer**, `src/runner/captions.ts`, with
+   `renderCaptions(steps: readonly TranscriptStep[]): { srt: string; vtt: string }`. Keep timestamp formatting and
+   text escaping private to that module; no dependencies, public API additions, CLI flags or generic subtitle
+   framework. Use the final step times as supplied, without changing or mutating the steps.
+   - One cue per eligible step, in input order, from `startMs` to `endMs`. Do not split text or extend boundaries.
+   - Normalize whitespace runs to a single space and trim for captions only. Skip absent narration (old schema),
+     blank normalized text and `endMs <= startMs`. Number emitted SRT cues consecutively starting at 1.
+   - Escape original `&`, `<`, `>` exactly once as agreed in decision 004. Preserve Unicode; do not interpret
+     markup or pre-existing character references.
+   - SRT uses `HH:MM:SS,mmm`; WebVTT uses `HH:MM:SS.mmm` and starts with `WEBVTT` plus a blank line. Use LF line
+     endings, blank lines between cues and a terminating newline. Empty input produces an empty SRT string and a
+     header-only WebVTT string (`WEBVTT\n\n`). Hours have at least two digits and do not wrap after 24.
+   → check: write failing unit tests in `test/unit/captions.test.ts`, then implement. Cover exact output in both
+   formats, millisecond precision and minute/hour carries, long text staying one cue, Unicode, tabs/CRLF/blank
+   lines, `<b>`, `&`, entity-looking text and `-->`, skipped cues with consecutive numbering, empty input, old
+   steps without narration, deterministic repeated serialization and unchanged input steps.
+
+2. **Preserve narration and write captions in the recording path.** In `src/runner/run.ts`, include the original
+   `narration` in each completed step. Add `<name>.srt` and `<name>.vtt` beside the script, using the same basename
+   as its MP4 and JSON files. Generate from the validated transcript after timing calibration; write UTF-8.
+   Keep schema version 1, `endMs = actionEndMs`, recording timing, master files and audio behavior as they are.
+   → check: extend the existing E2E output assertions so they fail until recording writes narration and both
+   sidecars. Keep the schema test accepting old GH-2 transcripts; verify invalid non-string narration is rejected
+   by the existing validator, without making narration mandatory globally.
+
+3. **Verify actual output and playback.** Extend `test/e2e/record.test.ts` rather than creating another recording
+   pipeline. Assert exact narration in both transcripts, caption text/order matching the script, and cue boundaries
+   matching each run's own final transcript. Compare text/order between runs, not whole files: timestamps can
+   differ by the allowed ±150 ms. Keep the existing frame and reproducibility checks.
+   → check: parse a generated VTT through Chromium's native `<track>` loader using Playwright already in the
+   recording image (serve HTML/video/VTT from a local fixture or intercepted HTTP routes). Assert parsed cue times
+   and decoded `getCueAsHTML().textContent`; check a markup-like text fixture preserves literal text. Load generated
+   SRT with host ffprobe/ffmpeg and assert cue count and timestamps; do not mistake parsing for visual validation
+   of SRT escapes. Inspect sample caption playback in a standard player/browser and report what was verified.
+
+4. **Update documentation.** In `README.md`, describe narration text and SRT/VTT sidecars, their paths, timing,
+   skipped cues, player-controlled wrapping and silent MP4 behavior. Explain the SRT escaping limit from decision
+   004 and that short steps can be hard to read until GH-5 adds voice holds.
+   → check: README output names match a recorded fixture, and no statement claims voice/audio is implemented.
+
+5. **Validate the completed change.** Run `npm run typecheck`, `npm test`, `npm run build` and `npm run test:e2e`.
+   The existing CI runs these checks; no workflow or image change is planned.
+   → check: checks pass, and recorded outputs preserve GH-2's timing and resolution guarantees. If a required
+   playback check cannot run, report it explicitly rather than treating serializer tests as playback proof.
+
+## Tests
+
+- Unit: caption serialization and edge cases; existing version 1 schema compatibility.
+- E2E: the existing pair of fixture recordings, narration persistence, caption sidecars, a real WebVTT parser,
+  SRT parsing and timestamps, and the retained ±150 ms/two-frame checks.
+- Playback: observe captions on the recorded sample in a standard player/browser; document SRT escape differences.
+
+## Risks
+
+- Captions generated before calibration would be offset from the MP4: serialize only final transcript times.
+- SRT escaping is player-dependent; exact literal rendering is guaranteed for WebVTT, not all SRT players
+  (decision 004). Do not strip narration or add player-specific output modes.
+- A short action may be too brief to read; GH-5 owns holds. Keep empty/instantaneous steps in the transcript.
+- Reproducible text does not imply byte-identical caption files across recordings: timestamps may vary.
+- Docker E2E needs enough free CPU; capture overload remains a recording failure under GH-2 decision 007.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md
index 9d47f13..1b1c595 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md
@@ -1 +1,5 @@
 - 2026-11-02: tracked as GH-3 (https://github.com/codeonym-oss/flow-reel/issues/3).
+- 2026-11-10: ticket pass against merged GH-2: decisions 001-004 agreed, impl.md written, draft clarified and status set to planned. Seven schema tests and typecheck passed; GitHub issue description not yet updated.
+- 2026-11-10: with approval, updated GH-3's GitHub issue description to match draft.md and verified an exact match.
+- 2026-11-10: building on feat/3-narrated-transcript-and-captions; planning changes carried into the branch.
+- 2026-11-10: implementation complete: original narration, SRT/VTT sidecars, serializer and playback tests, README. Typecheck/build, 45 unit tests and 6 E2E tests passed; screenshot inspected; standards/spec reviews found no issues. Awaiting commit approval.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/impl.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/impl.md
new file mode 100644
index 0000000..c309fd9
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/impl.md
@@ -0,0 +1,103 @@
+# Implementation: Narration text and SRT/VTT captions
+
+Planned 2026-11-10 against `main` at `a5e83798cdebfd817b7404a70868575236b55503`, after GH-2 merged as PR #10.
+Scope: preserve narration and write caption sidecars; the MP4 stays silent. Settled by story decisions 009-011,
+GH-2 decision 006 (output locations), and this ticket's decisions 001-004. No follow-ups are taken up.
+
+## Build notes (2026-11-10)
+
+- Step 3's browser playback check uses `test/e2e/player.ts`, a small helper mounted into the existing recording
+  image and called by the existing recording test. Its fixture serves the MP4 as a Blob so seeking works without
+  implementing HTTP range responses. It checks parsed/active cues and saves `captions.png` beside each test video.
+- Verified: `npm run typecheck`, `npm test` (45 passed), `npm run build`, `npm run test:e2e` (6 passed). The full
+  unit suite and E2E ran outside the sandbox because it intermittently blocks Node subprocesses and Docker access.
+- Observed the expected missing-narration failure before wiring the recording outputs; serializer slices also
+  failed before their implementations. All existing resolution, reproducibility and frame-alignment checks pass.
+- Visually inspected `test/e2e/out/a/captions.png`: the active WebVTT caption appears over the sample video with
+  literal tag-like text, ampersands, an entity-looking string, an arrow and Unicode. SRT was checked with ffprobe;
+  its visual escaping differences remain documented rather than claimed as verified in every player.
+- Standards and specification reviews against the working tree at the planned base found no issues. No agreed
+  behavior was changed or left unimplemented.
+
+## Current code and baseline
+
+- `src/index.ts` already defines `step(narration, action)`; `src/runner/run.ts` receives the text but omits it from
+  `steps.push()`. The runner calibrates all step times before writing the final transcript.
+- `src/schema/transcript.ts` already accepts optional `narration` in version 1. Keep that optional field so old
+  GH-2 transcripts remain valid; new recordings write narration on every step.
+- No caption module or output exists. `test/e2e/record.test.ts` already records the same fixture twice and checks
+  output validity, timing reproducibility and click/frame alignment.
+- Baseline: all 7 schema tests and `npm run typecheck` passed during the ticket pass. The previous project check
+  passed all 36 unit tests. Docker E2E was not rerun for planning; GH-2's merged PR had passing E2E CI.
+
+## Read first
+
+- `../../decisions/009-what-counts-as-the-same-video.md`, `010-demo-script-api.md`, `011-transcript-json-schema.md`.
+- `../GH-2-silent-replay-recording-sandbox/decisions/006-intermediates-in-flow-reel-folder.md`.
+- This ticket's `decisions/001`-`004`.
+- `src/runner/run.ts`, `src/schema/transcript.ts`, `src/index.ts`.
+- `test/unit/schema.test.ts`, `test/e2e/record.test.ts`, `README.md`, `.github/workflows/ci.yml`.
+- [WebVTT file syntax](https://www.w3.org/TR/webvtt1/#syntax) and the source notes in decision 004.
+
+## Steps
+
+1. **Add a pure caption serializer**, `src/runner/captions.ts`, with
+   `renderCaptions(steps: readonly TranscriptStep[]): { srt: string; vtt: string }`. Keep timestamp formatting and
+   text escaping private to that module; no dependencies, public API additions, CLI flags or generic subtitle
+   framework. Use the final step times as supplied, without changing or mutating the steps.
+   - One cue per eligible step, in input order, from `startMs` to `endMs`. Do not split text or extend boundaries.
+   - Normalize whitespace runs to a single space and trim for captions only. Skip absent narration (old schema),
+     blank normalized text and `endMs <= startMs`. Number emitted SRT cues consecutively starting at 1.
+   - Escape original `&`, `<`, `>` exactly once as agreed in decision 004. Preserve Unicode; do not interpret
+     markup or pre-existing character references.
+   - SRT uses `HH:MM:SS,mmm`; WebVTT uses `HH:MM:SS.mmm` and starts with `WEBVTT` plus a blank line. Use LF line
+     endings, blank lines between cues and a terminating newline. Empty input produces an empty SRT string and a
+     header-only WebVTT string (`WEBVTT\n\n`). Hours have at least two digits and do not wrap after 24.
+   → check: write failing unit tests in `test/unit/captions.test.ts`, then implement. Cover exact output in both
+   formats, millisecond precision and minute/hour carries, long text staying one cue, Unicode, tabs/CRLF/blank
+   lines, `<b>`, `&`, entity-looking text and `-->`, skipped cues with consecutive numbering, empty input, old
+   steps without narration, deterministic repeated serialization and unchanged input steps.
+
+2. **Preserve narration and write captions in the recording path.** In `src/runner/run.ts`, include the original
+   `narration` in each completed step. Add `<name>.srt` and `<name>.vtt` beside the script, using the same basename
+   as its MP4 and JSON files. Generate from the validated transcript after timing calibration; write UTF-8.
+   Keep schema version 1, `endMs = actionEndMs`, recording timing, master files and audio behavior as they are.
+   → check: extend the existing E2E output assertions so they fail until recording writes narration and both
+   sidecars. Keep the schema test accepting old GH-2 transcripts; verify invalid non-string narration is rejected
+   by the existing validator, without making narration mandatory globally.
+
+3. **Verify actual output and playback.** Extend `test/e2e/record.test.ts` rather than creating another recording
+   pipeline. Assert exact narration in both transcripts, caption text/order matching the script, and cue boundaries
+   matching each run's own final transcript. Compare text/order between runs, not whole files: timestamps can
+   differ by the allowed ±150 ms. Keep the existing frame and reproducibility checks.
+   → check: parse a generated VTT through Chromium's native `<track>` loader using Playwright already in the
+   recording image (serve HTML/video/VTT from a local fixture or intercepted HTTP routes). Assert parsed cue times
+   and decoded `getCueAsHTML().textContent`; check a markup-like text fixture preserves literal text. Load generated
+   SRT with host ffprobe/ffmpeg and assert cue count and timestamps; do not mistake parsing for visual validation
+   of SRT escapes. Inspect sample caption playback in a standard player/browser and report what was verified.
+
+4. **Update documentation.** In `README.md`, describe narration text and SRT/VTT sidecars, their paths, timing,
+   skipped cues, player-controlled wrapping and silent MP4 behavior. Explain the SRT escaping limit from decision
+   004 and that short steps can be hard to read until GH-5 adds voice holds.
+   → check: README output names match a recorded fixture, and no statement claims voice/audio is implemented.
+
+5. **Validate the completed change.** Run `npm run typecheck`, `npm test`, `npm run build` and `npm run test:e2e`.
+   The existing CI runs these checks; no workflow or image change is planned.
+   → check: checks pass, and recorded outputs preserve GH-2's timing and resolution guarantees. If a required
+   playback check cannot run, report it explicitly rather than treating serializer tests as playback proof.
+
+## Tests
+
+- Unit: caption serialization and edge cases; existing version 1 schema compatibility.
+- E2E: the existing pair of fixture recordings, narration persistence, caption sidecars, a real WebVTT parser,
+  SRT parsing and timestamps, and the retained ±150 ms/two-frame checks.
+- Playback: observe captions on the recorded sample in a standard player/browser; document SRT escape differences.
+
+## Risks
+
+- Captions generated before calibration would be offset from the MP4: serialize only final transcript times.
+- SRT escaping is player-dependent; exact literal rendering is guaranteed for WebVTT, not all SRT players
+  (decision 004). Do not strip narration or add player-specific output modes.
+- A short action may be too brief to read; GH-5 owns holds. Keep empty/instantaneous steps in the transcript.
+- Reproducible text does not imply byte-identical caption files across recordings: timestamps may vary.
+- Docker E2E needs enough free CPU; capture overload remains a recording failure under GH-2 decision 007.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md
index 721f93c..26d60d5 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md
@@ -3,10 +3,10 @@ kind: ticket
 title: Narrate steps in the transcript and write SRT/VTT captions
 key: GH-3
 parent: GH-1
-status: tracked
-branch:
+status: building
+branch: feat/3-narrated-transcript-and-captions
 tracker-url: https://github.com/codeonym-oss/flow-reel/issues/3
 mr:
 created: 2026-11-02
-updated: 2026-11-02
+updated: 2026-11-10
 ---
diff --git a/src/runner/captions.ts b/src/runner/captions.ts
new file mode 100644
index 0000000..b2f4dda
--- /dev/null
+++ b/src/runner/captions.ts
@@ -0,0 +1,27 @@
+// Caption sidecars use the transcript's final, calibrated timeline (GH-3 decisions 001-004).
+import type { TranscriptStep } from "../schema/transcript.ts";
+
+function timestamp(ms: number, separator: string): string {
+  const hours = Math.floor(ms / 3_600_000);
+  const minutes = Math.floor(ms / 60_000) % 60;
+  const seconds = Math.floor(ms / 1000) % 60;
+  return [hours, minutes, seconds].map((n) => String(n).padStart(2, "0")).join(":")
+    + separator + String(ms % 1000).padStart(3, "0");
+}
+
+export function renderCaptions(steps: readonly TranscriptStep[]): { srt: string; vtt: string } {
+  let srt = "";
+  let vtt = "WEBVTT\n\n";
+  let index = 0;
+  for (const step of steps) {
+    const text = (step.narration ?? "").replace(/\s+/g, " ").trim()
+      .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    if (!text || step.endMs <= step.startMs) continue;
+    index++;
+    const cue = (separator: string) => `${index}\n${timestamp(step.startMs, separator)} --> `
+      + `${timestamp(step.endMs, separator)}\n${text}\n\n`;
+    srt += cue(",");
+    vtt += cue(".");
+  }
+  return { srt, vtt };
+}
diff --git a/src/runner/run.ts b/src/runner/run.ts
index c8a5364..de8f958 100644
--- a/src/runner/run.ts
+++ b/src/runner/run.ts
@@ -7,6 +7,7 @@ import type { Step } from "../index.ts";
 import { type RunnerEvent, validateEvents } from "../schema/events.ts";
 import { type Transcript, type TranscriptStep, validateTranscript } from "../schema/transcript.ts";
 import { launchBrowser } from "./browser.ts";
+import { renderCaptions } from "./captions.ts";
 import { screenFor, startDisplay } from "./display.ts";
 import { loadDemo } from "./load.ts";
 import { trackNetwork } from "./network.ts";
@@ -41,6 +42,8 @@ export async function record(scriptPath: string): Promise<void> {
     video: join(dir, `${name}.mp4`),
     transcript: join(dir, `${name}.transcript.json`),
     events: join(dir, `${name}.events.json`),
+    srt: join(dir, `${name}.srt`),
+    vtt: join(dir, `${name}.vtt`),
   };
   const { viewport, url } = demo.options;
 
@@ -79,7 +82,7 @@ export async function record(scriptPath: string): Promise<void> {
           throw new Error(`step ${steps.length} ("${narration}") failed: ${(e as Error).message}`, { cause: e });
         }
         const actionEndMs = Math.round(recording.now());
-        steps.push({ index: steps.length, startMs, actionEndMs, endMs: actionEndMs });
+        steps.push({ index: steps.length, narration, startMs, actionEndMs, endMs: actionEndMs });
       };
       let ranMs = 0;
       try {
@@ -119,6 +122,9 @@ export async function record(scriptPath: string): Promise<void> {
         steps,
       };
       writeChecked(out.transcript, transcript, validateTranscript(transcript));
+      const captions = renderCaptions(transcript.steps);
+      writeFileSync(out.srt, captions.srt, "utf8");
+      writeFileSync(out.vtt, captions.vtt, "utf8");
       const log = { version: 1 as const, events };
       writeChecked(out.events, log, validateEvents(log));
     } finally {
diff --git a/test/e2e/player.ts b/test/e2e/player.ts
new file mode 100644
index 0000000..a32e7e8
--- /dev/null
+++ b/test/e2e/player.ts
@@ -0,0 +1,50 @@
+// Executed in the recording image, where Chromium and Playwright are already installed.
+import { readFileSync } from "node:fs";
+import { chromium } from "playwright";
+
+const browser = await chromium.launch({ headless: true });
+try {
+  const page = await browser.newPage({ viewport: { width: 1280, height: 760 } });
+  await page.route("http://player.test/**", async (route) => {
+    const path = new URL(route.request().url()).pathname;
+    if (path === "/") {
+      await route.fulfill({ contentType: "text/html", body: `<style>body{margin:0;background:#111}</style>
+        <video controls width="1280" height="720">
+          <track default kind="captions" srclang="en" label="Narration" src="/demo.vtt">
+        </video><script>
+          // A Blob makes the fixture seekable without emulating HTTP range responses in the route handler.
+          fetch('/demo.mp4').then(r => r.blob()).then(blob => {
+            document.querySelector('video').src = URL.createObjectURL(blob);
+          });
+        </script>` });
+    } else {
+      await route.fulfill({ contentType: path.endsWith(".vtt") ? "text/vtt" : "video/mp4",
+        body: readFileSync(`/work${path}`) });
+    }
+  });
+  await page.goto("http://player.test/");
+  await page.waitForFunction(() => document.querySelector("video")!.readyState >= 2
+    && document.querySelector("track")!.readyState === 2);
+  const cues = await page.evaluate(() => Array.from(document.querySelector("video")!.textTracks[0].cues!, (cue) => {
+    const vtt = cue as VTTCue;
+    return { startMs: Math.round(vtt.startTime * 1000), endMs: Math.round(vtt.endTime * 1000),
+      text: vtt.getCueAsHTML().textContent };
+  }));
+  await page.evaluate(async () => {
+    const video = document.querySelector("video")!;
+    const cue = video.textTracks[0].cues![0];
+    await new Promise<void>((resolve) => {
+      video.addEventListener("seeked", () => resolve(), { once: true });
+      video.currentTime = (cue.startTime + cue.endTime) / 2;
+    });
+    await video.play();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    video.pause();
+  });
+  const active = await page.evaluate(() => Array.from(document.querySelector("video")!.textTracks[0].activeCues!,
+    (cue) => (cue as VTTCue).getCueAsHTML().textContent));
+  await page.screenshot({ path: "/work/captions.png" });
+  console.log(JSON.stringify({ cues, active }));
+} finally {
+  await browser.close();
+}
diff --git a/test/e2e/record.test.ts b/test/e2e/record.test.ts
index 56f6d2d..dfc1d7d 100644
--- a/test/e2e/record.test.ts
+++ b/test/e2e/record.test.ts
@@ -13,13 +13,15 @@ const OUT = resolve("test/e2e/out");
 const html = readFileSync(resolve("test/e2e/app/index.html"));
 let server: Server;
 let port: number;
+let image: string;
+const NARRATIONS = ["  Type <b>Ada</b> & &lt; --> 保存.\r\n  ", "Scroll down and save.", "Open the settings."];
 
 const script = (p: number) => `import { demo } from "flow-reel";
 
 export default demo({ url: "http://localhost:${p}/" }, async ({ page, step }) => {
-  await step("Type a name.", () => page.getByRole("textbox", { name: "Name" }).fill("Ada"));
-  await step("Scroll down and save.", () => page.getByRole("button", { name: "Save" }).click());
-  await step("Open the settings.", () => page.getByRole("link", { name: "Settings" }).click());
+  await step(${JSON.stringify(NARRATIONS[0])}, () => page.getByRole("textbox", { name: "Name" }).fill("Ada"));
+  await step(${JSON.stringify(NARRATIONS[1])}, () => page.getByRole("button", { name: "Save" }).click());
+  await step(${JSON.stringify(NARRATIONS[2])}, () => page.getByRole("link", { name: "Settings" }).click());
 });
 `;
 
@@ -62,7 +64,8 @@ let b: Run;
 beforeAll(async () => {
   rmSync(OUT, { recursive: true, force: true });
   const { version } = JSON.parse(readFileSync("package.json", "utf8"));
-  execFileSync("docker", ["build", "-q", "-t", `ghcr.io/codeonym-oss/flow-reel:${version}`, "-f", "docker/Dockerfile", "."], { stdio: "inherit" });
+  image = `ghcr.io/codeonym-oss/flow-reel:${version}`;
+  execFileSync("docker", ["build", "-q", "-t", image, "-f", "docker/Dockerfile", "."], { stdio: "inherit" });
   server = createServer((_req, res) => res.writeHead(200, { "content-type": "text/html" }).end(html));
   await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
   port = (server.address() as AddressInfo).port;
@@ -73,6 +76,37 @@ beforeAll(async () => {
 afterAll(() => server?.close());
 
 describe("flow-reel record", () => {
+  it("loads WebVTT in Chromium with literal text and displays the active caption during playback", async () => {
+    for (const run of [a, b]) {
+      const { stdout } = await promisify(execFile)("docker", ["run", "--rm", "--init", "--shm-size=1g",
+        "--user", `${process.getuid!()}:${process.getgid!()}`,
+        "-v", `${run.dir}:/work`, "-v", `${resolve("test/e2e/player.ts")}:/opt/flow-reel/player.ts:ro`,
+        "--entrypoint", "node", image, "/opt/flow-reel/player.ts"]);
+      const playback = JSON.parse(stdout);
+      expect(playback.cues).toEqual(run.transcript.steps.map((s, i) => ({
+        startMs: s.startMs, endMs: s.endMs,
+        text: ["Type <b>Ada</b> & &lt; --> 保存.", "Scroll down and save.", "Open the settings."][i],
+      })));
+      expect(playback.active).toEqual(["Type <b>Ada</b> & &lt; --> 保存."]);
+    }
+  });
+
+  it("preserves original narration and writes SRT cues on each run's calibrated timeline", () => {
+    for (const run of [a, b]) {
+      expect(run.transcript.steps.map((s) => s.narration)).toEqual(NARRATIONS);
+      const srt = readFileSync(join(run.dir, "demo.srt"), "utf8");
+      expect(srt.split("\n\n").filter(Boolean).map((cue) => cue.split("\n")[2])).toEqual([
+        "Type &lt;b&gt;Ada&lt;/b&gt; &amp; &amp;lt; --&gt; 保存.", "Scroll down and save.", "Open the settings.",
+      ]);
+      const { packets } = JSON.parse(execFileSync("ffprobe", ["-v", "error", "-show_packets",
+        "-show_entries", "packet=pts_time,duration_time", "-of", "json", join(run.dir, "demo.srt")], { encoding: "utf8" }));
+      expect(packets.map((p: { pts_time: string; duration_time: string }) => ({
+        startMs: Math.round(Number(p.pts_time) * 1000), durationMs: Math.round(Number(p.duration_time) * 1000),
+      }))).toEqual(run.transcript.steps.map((s) => ({ startMs: s.startMs, durationMs: s.endMs - s.startMs })));
+      expect(readFileSync(join(run.dir, "demo.vtt"), "utf8")).toContain("WEBVTT\n\n");
+    }
+  });
+
   it("writes a 1440p 30 fps master and a 1080p copy, dropping no frames", () => {
     const master = probe(join(a.dir, ".flow-reel/demo/master.mp4"));
     expect(master).toMatchObject({ width: 2560, height: 1440, fps: "30/1" });
diff --git a/test/unit/captions.test.ts b/test/unit/captions.test.ts
new file mode 100644
index 0000000..bfd0dae
--- /dev/null
+++ b/test/unit/captions.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { renderCaptions } from "../../src/runner/captions.ts";
+
+describe("renderCaptions", () => {
+  it("writes empty SRT and header-only WebVTT when no cues remain", () => {
+    expect(renderCaptions([])).toEqual({ srt: "", vtt: "WEBVTT\n\n" });
+    expect(renderCaptions([
+      { index: 0, narration: "", startMs: 0, actionEndMs: 1, endMs: 1 },
+    ])).toEqual({ srt: "", vtt: "WEBVTT\n\n" });
+  });
+
+  it.each([
+    [59_999, 60_001, "00:00:59,999 --> 00:01:00,001", "00:00:59.999 --> 00:01:00.001"],
+    [3_599_999, 3_600_001, "00:59:59,999 --> 01:00:00,001", "00:59:59.999 --> 01:00:00.001"],
+    [360_000_000, 360_000_001, "100:00:00,000 --> 100:00:00,001", "100:00:00.000 --> 100:00:00.001"],
+  ])("keeps millisecond precision across timestamp boundaries at %i ms", (startMs, endMs, srtTime, vttTime) => {
+    expect(renderCaptions([{ index: 0, narration: "Next.", startMs, actionEndMs: endMs, endMs }])).toEqual({
+      srt: `1\n${srtTime}\nNext.\n\n`,
+      vtt: `WEBVTT\n\n1\n${vttTime}\nNext.\n\n`,
+    });
+  });
+
+  it("keeps long narration in one cue without inserting line breaks", () => {
+    const narration = "Open the settings page and choose the theme that makes this application easier to read on your display.";
+    expect(renderCaptions([
+      { index: 0, narration, startMs: 0, actionEndMs: 1000, endMs: 1000 },
+    ])).toEqual({
+      srt: `1\n00:00:00,000 --> 00:00:01,000\n${narration}\n\n`,
+      vtt: `WEBVTT\n\n1\n00:00:00.000 --> 00:00:01.000\n${narration}\n\n`,
+    });
+  });
+
+  it("skips missing, blank and nonpositive-duration narration and numbers only emitted cues", () => {
+    expect(renderCaptions([
+      { index: 0, startMs: 0, actionEndMs: 100, endMs: 100 },
+      { index: 1, narration: " \t\r\n", startMs: 100, actionEndMs: 200, endMs: 200 },
+      { index: 2, narration: "Instant.", startMs: 200, actionEndMs: 200, endMs: 200 },
+      { index: 3, narration: "Backwards.", startMs: 300, actionEndMs: 200, endMs: 200 },
+      { index: 4, narration: "Save.", startMs: 400, actionEndMs: 600, endMs: 600 },
+    ])).toEqual({
+      srt: "1\n00:00:00,400 --> 00:00:00,600\nSave.\n\n",
+      vtt: "WEBVTT\n\n1\n00:00:00.400 --> 00:00:00.600\nSave.\n\n",
+    });
+  });
+
+  it("writes one cue per step on the final video timeline in SRT and WebVTT", () => {
+    expect(renderCaptions([
+      { index: 0, narration: "Open settings.", startMs: 512, actionEndMs: 1200, endMs: 2401 },
+      { index: 1, narration: "Save changes.", startMs: 2500, actionEndMs: 3000, endMs: 3000 },
+    ])).toEqual({
+      srt: "1\n00:00:00,512 --> 00:00:02,401\nOpen settings.\n\n2\n00:00:02,500 --> 00:00:03,000\nSave changes.\n\n",
+      vtt: "WEBVTT\n\n1\n00:00:00.512 --> 00:00:02.401\nOpen settings.\n\n2\n00:00:02.500 --> 00:00:03.000\nSave changes.\n\n",
+    });
+  });
+
+  it("normalizes caption whitespace and escapes original text once without mutating narration", () => {
+    const steps = Object.freeze([Object.freeze({
+      index: 0, narration: "  <b>Réglages</b>\r\n\r\n\t & &lt; --> 保存 😀  ",
+      startMs: 0, actionEndMs: 1000, endMs: 1000,
+    })]);
+    const captions = renderCaptions(steps);
+    expect(captions).toEqual({
+      srt: "1\n00:00:00,000 --> 00:00:01,000\n&lt;b&gt;Réglages&lt;/b&gt; &amp; &amp;lt; --&gt; 保存 😀\n\n",
+      vtt: "WEBVTT\n\n1\n00:00:00.000 --> 00:00:01.000\n&lt;b&gt;Réglages&lt;/b&gt; &amp; &amp;lt; --&gt; 保存 😀\n\n",
+    });
+    expect(renderCaptions(steps)).toEqual(captions);
+    expect(steps[0].narration).toBe("  <b>Réglages</b>\r\n\r\n\t & &lt; --> 保存 😀  ");
+  });
+});
diff --git a/test/unit/schema.test.ts b/test/unit/schema.test.ts
index 10bfc80..0dcfa87 100644
--- a/test/unit/schema.test.ts
+++ b/test/unit/schema.test.ts
@@ -45,6 +45,13 @@ describe("validateTranscript", () => {
     expect(validateTranscript(rest)).toContain("version must be 1");
   });
 
+  it("rejects non-string narration while accepting original whitespace", () => {
+    expect(validateTranscript({ ...transcript, steps: [{ ...transcript.steps[0], narration: 42 }] }))
+      .toContain("steps[0]: narration must be a string");
+    expect(validateTranscript({ ...transcript, steps: [{ ...transcript.steps[0], narration: " \r\n\t " }] }))
+      .toEqual([]);
+  });
+
   it("rejects a step that ends before it starts", () => {
     const bad = { ...transcript, steps: [{ ...transcript.steps[0], startMs: 500, actionEndMs: 400, endMs: 400 }] };
     expect(validateTranscript(bad)).toContain("steps[0]: actionEndMs must be >= startMs");

From 188cd59d839f390e34ccf2f40c3e8297b3735e82 Mon Sep 17 00:00:00 2001
From: codeonym <bouarourayoub0@gmail.com>
Date: Tue, 10 Nov 2026 13:27:24 +0000
Subject: [PATCH 2/2] chore: mark GH-3 in review (#3)

---
 .../history/2026-11-10_1327_meta.md                  | 12 ++++++++++++
 .../history/CHANGES.md                               |  1 +
 .../GH-3-narrated-transcript-and-captions/meta.md    |  4 ++--
 3 files changed, 15 insertions(+), 2 deletions(-)
 create mode 100644 planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1327_meta.md

diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1327_meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1327_meta.md
new file mode 100644
index 0000000..26d60d5
--- /dev/null
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/2026-11-10_1327_meta.md
@@ -0,0 +1,12 @@
+---
+kind: ticket
+title: Narrate steps in the transcript and write SRT/VTT captions
+key: GH-3
+parent: GH-1
+status: building
+branch: feat/3-narrated-transcript-and-captions
+tracker-url: https://github.com/codeonym-oss/flow-reel/issues/3
+mr:
+created: 2026-11-02
+updated: 2026-11-10
+---
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md
index 1b1c595..3aae8de 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/history/CHANGES.md
@@ -3,3 +3,4 @@
 - 2026-11-10: with approval, updated GH-3's GitHub issue description to match draft.md and verified an exact match.
 - 2026-11-10: building on feat/3-narrated-transcript-and-captions; planning changes carried into the branch.
 - 2026-11-10: implementation complete: original narration, SRT/VTT sidecars, serializer and playback tests, README. Typecheck/build, 45 unit tests and 6 E2E tests passed; screenshot inspected; standards/spec reviews found no issues. Awaiting commit approval.
+- 2026-11-10: committed as 8aa061f; in review at https://github.com/codeonym-oss/flow-reel/pull/11.
diff --git a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md
index 26d60d5..37180ca 100644
--- a/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md
+++ b/planning/GH-1-narrated-reproducible-feature-demos/tickets/GH-3-narrated-transcript-and-captions/meta.md
@@ -3,10 +3,10 @@ kind: ticket
 title: Narrate steps in the transcript and write SRT/VTT captions
 key: GH-3
 parent: GH-1
-status: building
+status: in-review
 branch: feat/3-narrated-transcript-and-captions
 tracker-url: https://github.com/codeonym-oss/flow-reel/issues/3
-mr:
+mr: https://github.com/codeonym-oss/flow-reel/pull/11
 created: 2026-11-02
 updated: 2026-11-10
 ---