Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
3d76e03
Journey podcasts (prototype): play a journey's audio episode; the wal…
tomeyer97 Nov 18, 2026
2645a7f
Podcast status item: the time beside the walk's own step item (Intro …
tomeyer97 Nov 18, 2026
3a7920c
Podcasts: one validator for the podcast file (validatePodcast)
tomeyer97 Nov 18, 2026
5016f8c
Podcast player: seeks land where they say, wherever the audio is serv…
tomeyer97 Nov 18, 2026
f73c357
Walk: a step can open on a beat whose code is in another file; the wa…
tomeyer97 Nov 18, 2026
ebc7324
Podcast: the place is kept per journey; skipped steps, rewritten file…
tomeyer97 Nov 18, 2026
603a507
Podcast integration tests: real audio time after seeks, skipped steps…
tomeyer97 Nov 18, 2026
f95c6a9
Podcasts: a broken podcast leaves a trace; problems in the Problems view
tomeyer97 Nov 18, 2026
d00fcc9
Podcast integration tests: broken files, the audio coming back, warni…
tomeyer97 Nov 18, 2026
37c835f
Podcast docs: seeking anywhere, the kept place, skipped steps, rewrit…
tomeyer97 Nov 18, 2026
c5a95b2
journey.py podcast: the podcast check for authors (and in check)
tomeyer97 Nov 18, 2026
ada4477
Podcast docs: the checks and what the player shows; the format doc sh…
tomeyer97 Nov 18, 2026
1281c79
journey.py podcast test: no __pycache__ beside the skill's script
tomeyer97 Nov 18, 2026
90d0f4b
Podcast panel harness: the notice line and Podcast unavailable, at th…
tomeyer97 Nov 18, 2026
ae83739
Podcast integration tests: Play in a new panel clicks once, only when…
tomeyer97 Nov 18, 2026
cc6c31e
Merge fix/podcast-validate: podcast file validation on top of the see…
tomeyer97 Nov 18, 2026
4369bac
Podcasts: optional sentence timing per segment (sentences), checked w…
tomeyer97 Nov 18, 2026
edf5351
Podcast check: a missing step said once with its times, a string beat…
tomeyer97 Nov 18, 2026
343f6b7
Walk: step code always opens in one group beside the panel, never on …
tomeyer97 Nov 18, 2026
18fa037
Podcast: a calmer editor (a view is held at least VIEW_HOLD_S = 8 s w…
tomeyer97 Nov 18, 2026
ca13710
Listening while the walk moves: the follow lock, a one-line step card…
tomeyer97 Nov 18, 2026
4ae9e1d
Tests never play sound: Chromium muted, no sound server for VS Code
tomeyer97 Nov 18, 2026
0575063
Listen: the audio plays in a Listen view; the panel's player and the …
tomeyer97 Nov 18, 2026
9d1805c
Listen: rows, the picker and the panel's list mark journeys with a po…
tomeyer97 Nov 18, 2026
739c5da
Listen tests: the harness drives the Listen view and the panel, and a…
tomeyer97 Nov 18, 2026
262dbff
Listen docs: the Listen view, the player, the chapter list, the keys
tomeyer97 Nov 18, 2026
4b1b46f
Listen: a narrow storyline puts the time under the title, the row but…
tomeyer97 Nov 18, 2026
0bfd77e
Listen tests: ≡ in a narrow storyline is clicked on the row under the…
tomeyer97 Nov 18, 2026
937c9ee
Listen: the part of the timeline the audio can't reach is visibly str…
tomeyer97 Nov 18, 2026
11b6655
Listening integration tests: the one-line card and one transport, the…
tomeyer97 Nov 18, 2026
49621c0
Podcast docs: the editor while it plays (view hold, follow lock, one-…
tomeyer97 Nov 18, 2026
9c8fb31
Panel layout: Ctrl+' V's room for the map survives VS Code expanding …
tomeyer97 Nov 18, 2026
240a6a5
Merge fix/podcast-walk: the editor while it plays, on top of the List…
tomeyer97 Nov 18, 2026
c77366c
Listen: marks, highlights lit as the words are said
tomeyer97 Nov 18, 2026
5132813
Listen marks: whole-line marks drawn per line from their text; journe…
tomeyer97 Nov 18, 2026
a70767d
Listen marks: no borders; a mark of whole lines tints them as one blo…
tomeyer97 Nov 18, 2026
d8a7f85
Listen: camera moves give time to read
tomeyer97 Nov 18, 2026
8747e17
Listen: a camera wait holds the audio and never lets the walk lag the…
tomeyer97 Nov 18, 2026
662291e
Listen: ▶ starts the sound where it was pressed
tomeyer97 Nov 18, 2026
6583d8b
Listen: a quieter editor while it plays
tomeyer97 Nov 18, 2026
e2a13ea
Listen: the panel and its player, calmer
tomeyer97 Nov 18, 2026
7fe8aa9
Merge declutter/editor: a quieter editor while it plays
tomeyer97 Nov 18, 2026
a92fa90
Listen: a panel too narrow for the map keeps the chapter list while p…
tomeyer97 Nov 18, 2026
d83e39a
Marks: one shape, finder and look for every owner (src/marks/)
tomeyer97 Nov 18, 2026
77bff01
Journeys: marks on steps and beats, the part of a line a step is about
tomeyer97 Nov 18, 2026
9ef2f8d
code-journey skill: write, check and preview marks
tomeyer97 Nov 18, 2026
e2b6975
Listen: the side bar, the status bar and the palette, quieter
tomeyer97 Nov 18, 2026
8ac2704
Merge feat/journey-marks: sub-line marks on journey steps and beats
tomeyer97 Nov 18, 2026
056287a
Release 0.26.0
tomeyer97 Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 126 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,132 @@
# Changelog

## Unreleased
## 0.26.0

- **Journey podcasts (prototype).** A journey with an audio episode next to it (`<journey>.podcast.json` and its
audio, [docs/podcast-format.md](docs/podcast-format.md)) gets a ▶ on its row and a player at the bottom of the
journey panel: play and pause, back and forward 15 s, previous and next step, speed (1×, 1.25×, 1.5×), and a
timeline marked by step (hover names the step; click or drag to go there). The walk follows the voice: steps open
and animations move beat by beat, exactly as when you walk them; any seek puts the walk where it is at that time,
backwards too. Next, Previous, a step or a beat you pick moves the audio to its part. The audio goes on while the
panel is behind another tab or VS Code is in the background. Ctrl+' Space plays and pauses from anywhere, Ctrl+' ← →
skip; the status bar shows where it is.
- Seeking works in VS Code for the web and remote windows too: the panel loads the audio whole, and the walk, the
player and the status bar always show where the audio actually is (a seek that can't get there is said and
logged). One clock: the status bar shows the player's second.
- Where you were is kept per journey: another journey, ending the walk, closing the panel, a reload, or saving the
podcast file again (the same moment of the same segment) keep it, and ▶ goes on from there.
- A step the podcast skips: the walk stays on it, the audio pauses and says so, and ▶ goes on after that step.
- A beat whose code is in another file opens that file directly; a part on the map closes the walk's code tab.
- Space and K play and pause anywhere in the panel, also after clicking the animation's ‹ ›. An audio that can't
play stays paused and says why.
- **Listen: the podcast player, reworked.** Podcasts are called **Listen** now: ▶ Listen on the row, **Code Notes:
Listen to Journey**, **Listen: Play/Pause**, **Back 15 s**, **Forward 15 s**, **Previous Step**, **Next Step**
(new, Ctrl+' Shift+← →). The command ids and the `.podcast.json` format are unchanged.
- The audio lives in a new **Listen** view (Code Notes side bar): closing the journey panel, or a layout that hides
it, no longer stops the episode. The panel's player and the status bar are remotes; the status bar says
**Listening · 6:58** / **Paused · 6:58** (the glyph shows the state), its tooltip lists the actions with their
keys, and its click opens the journey's map, whose player shows where the audio is.
- ▶ starts the sound where you pressed it: no second ▶ to find in the Listen view. VS Code lets a webview play
audio only after a click or a key in that webview, so ▶ in the journey panel plays the audio in the panel (the
Listen view follows it, and takes the audio over when the panel closes, once it has been clicked too). A start
from a row, the palette or a key before any click in either player opens the panel with its ▶ focused: Space or
one click there plays it, and later starts play at once.
- The caption is the sentence being said, two lines at most and never cut (a long sentence in parts), with the
speaker's name when the voice changes. A segment may give its own sentence times (`sentences`, checked when
present); else they are estimated from the text.
- The timeline: the player's whole width, a mark per step with its number (at least 8 px to hit), the playhead
always shown, hover says the time and the step in full and goes when the pointer leaves, the part a cut-off audio
can't reach greyed. The ±15 s buttons are gone (the keys stay); a narrow panel keeps ▶ ⏮ ⏭ first. Speed is a menu
from 0.75× to 2× (< > too); mute (M) is new; both are remembered. K works by its place on the keyboard. A seek
after the end plays on; the end offers Replay, Walk it yourself and Next journey.
- The storyline is the chapter list: start times, ♪ on the step being said, "not narrated" on a skipped step, ▶ per
step (plays that step and stops), a transcript per step (current sentence marked, click to go there, found by
Ctrl+F when shut). While it plays the panel's header is one line ("Step 6 of 14 · …"), and the animation's own
sentence and the code snippet give way to the caption; the panel scrolls to a step the voice moves to.
- Rows mark journeys with a podcast ("♪ 12:47"; "♪ Listening", "♪ Paused at 3:38"), with ⏸ / Resume on the row and a
tooltip line; the journey being walked is listed once (not again under "In this file"); Open Journey… and the
panel's journey list mark podcasts too. The scene's beat shows as dots.
- Accessibility: the timeline is an ARIA slider (↑ ↓ Home End Page Up/Down) whose value text gives the time, the
total and the step; step changes are announced once; controls have names and keys. Media keys and the system's
"now playing" work (Media Session).
- **Listen: the panel, calmer.** One player: while the journey panel shows the episode the Listen view is one line
(the journey, ⏸ / ▶, the time). While it plays the panel is the one-line header and the step's animation alone, in
the same box every step (the map where there is none, names only at the intro and the recap); the chapter list
comes back on pause, as number and title (▶ on hover) with one **Transcript** switch. The header stays one line
until the episode ends. The player: plain ⏸, ticks for the steps (hover "Step 6 · title · 5:23"), a "1×" that
cycles 1×–2×, no mute button (M stays), neutral greys; the end is Replay · Walk it yourself · Next journey only.
Beside the code the panel is 360–420 px while an episode is on. A caption or transcript sentence no longer splits
at the dot inside `repo.ReadTestFile`; the animation draws no wire stub to an actor out of view.
- **Listen: the side bar, the status bar and the palette, quieter.** The Listen view is there only while a journey is
listened to (playing or paused), with no empty-state text. A Journeys row says "♪ 12:47" and nothing more (no
"Listening", no "Paused at", no step, no speaker icon); its ▶ shows unless it plays (paused, ▶ goes on), with no ⏸ or
Resume row action and no podcast line in the tooltip unless the podcast can't play (then no ▶: the tooltip says
why). Open Journey… marks a podcast with a ♪ after the title, and the journey listened to says "listening" without a
▶. The status item shows only while the journey panel is off screen ("Listening · 6:58", a one-line tooltip), is
gone after the end, and the walk's "3/14" item steps aside meanwhile. No status-bar flashes (resume, the follow
lock, a note being written, a removed step): the output logs them. The transport commands are in the palette only
while a journey is listened to (**Listen: Pause/Play**, **Listen: Open the Map**). The panel's notice is one line,
"⚠ 3 problems · Show why", counting what the Problems view lists; a bad beat is said by the step ("Step 1: no beat 99
(it has 5); showing the whole step") and its marks aren't reported again; "Code changed since recording: steps 2, 5,
9". A journey panel closed while VS Code was restoring it no longer fails the extension's activation.
- **Listen: the editor while it plays.** The editor is calmer: a view is held at least 8 s (a shorter part in
another file stays in the view before; beats in the same file just move the highlight). Scroll or click in the
narrated code and it stops following until the next step; **Follow along** on the step card snaps back. While it
plays the step card is one line ("narrating · beat 2/6", ⏸, ⏮ ⏭) and its ⏮ ⏭, Ctrl+' A / D and the player's are one
transport (⏮ is always the part before; in the Intro and Recap the keys move the episode). The Intro and Recap close
the walk's code so the map has the editor; the code comes back in one group beside the panel, never on your own
unsaved or untitled file. The first play says "The walk follows the voice: code opens beside the map". A note or a
question being written pauses it (closing the panel does not: the audio is in the Listen view). The panel no longer changes width on its own: focusing it, ‹ Journeys and the row
of the journey you're in keep its width (VS Code widening a panel focused at its minimum is undone), a reload never
closes it, and the journey you're in is focused, not reopened; Ctrl+' V gives a narrow panel room for the map. A
journey edited under the podcast keeps the step (by id); a removed step shows what the podcast says at its time;
quick ⏭ ⏭ open only the last target; a beat it doesn't narrate pauses it; End Journey ends the listening (▶ says
where it goes on); Ctrl+' Space in a journey without a podcast says so instead of starting another one. Reopened,
the panel shows the beat it was at; the output logs plays, pauses and stops with why.
- **Listen: marks, highlights as the words are said.** A segment may carry `marks`: while the voice says "requires a
model", that check lights, down to the characters (`match`, its `nth`); on "right there", the line that rejects it.
The newest mark is a strong tint (whole lines: one tinted block with a bar on the left, no lines between rows), the
segment's earlier ones stay, lighter, over the beat's own line;
the next segment clears them. A mark lights 0.12 s before its word; marks with the same phrase light together; at
any time (a seek, paused too) exactly the marks said by then show. Code that moved is found within 20 lines (said
once in the output), else the whole lines light. An off-screen mark is scrolled to, never under a reader who is
looking around; a mark in another file opens it only after the view hold (8 s). The check (extension and
`journey.py podcast`) says marks that can't be used, phrases not in the text, marks out of order, and, reading the
code, a missing file, lines past its end, or a `match` not where it says (and whether it is found nearby).
- **Listen: camera moves give you time to read.** When the next mark, beat or step is out of view, a cue at the
editor's edge says where the code goes ("↓ 340", "↑ 212", "→ main.ts") 0.8 s before; the code moves only once what
was just lit has been on screen 2.5 s (`codeNotes.listen.readBeforeMove`), and the audio then waits 0.8 s with the
new mark lit (`codeNotes.listen.settleAfterMove`). A wait is not a pause: the player, the status bar, the Journeys
row and the step card stay as they are; the cue is all that shows it. No waits when the code is on screen, under the
follow lock, after your own seeks, or on the map. The walk never lags the voice: if the audio doesn't stop for a
wait (checked against the audio's own time), or you play on or scroll during one, the wait is dropped and the code
goes to what is being said now; waits then stay off for 30 s.
- **Listen: the player and the walk keep time with the audio.** The panel's player (a remote of the Listen view)
counts from when the audio said its time, not from when the message arrived, so a busy extension never puts its
caption behind the voice; a run of time reports that piled up is applied once, its newest. Captions of a long
sentence change part when its words are said (the marks' phrases are word-timed) instead of by character count.
- **Listen: a quieter editor while it plays.** The step card is its header line ("3/14 · title", and Follow along
while you read on your own) above the function the step is in; the full card comes back on pause. The newest mark
is the one colour on the code (its own theme colour, `codeNotes.markBackground`; no bar, no scrollbar ticks); the
step's lines keep a thin grey bar, and the beat's box, value hints and note bars wait for the pause.
- **Listen: the follow lock sees the reader.** A slow scroll in small steps now counts (measured from where the
extension left the code), and the step card growing or shrinking on pause and play no longer counts as the reader
scrolling. A mark brought on screen keeps column 1 in view; the code scrolls right only when the mark starts past
the right edge.
- **Listen: more checks of the podcast file.** A step the journey doesn't have is said once with its segments and times; a beat written
as a string, a reused segment id (with both times), and narration in another order than the journey's are warnings;
a podcast recorded for an older commit whose steps' code changed since gets a quiet note; a podcast file not named
after its journey says in the output why it's ignored. `journey.py podcast` stays in step.
- **Podcasts: broken files are explained.** One check of the podcast file, with errors (it can't be played) and
warnings (a part is not what the file says: a step or beat the journey doesn't have, overlapping or out-of-order
times, an end before its start or past the audio, a cut-off audio, written for another journey). Every problem is
in the Problems view on the `.podcast.json` and in the output at warning level. A podcast that can't be played
keeps a greyed ▶ on its row (the tooltip says why) and a "Podcast unavailable · Show why" line in the panel; one
with warnings says them in one short line. A file that breaks while it plays keeps the last good version playing;
the status item goes with its podcast; putting the audio file back brings the podcast back. `audio` outside the
journeys folder is refused at load. `journey.py podcast` (the code-journey skill) runs the same checks, and
`journey.py check` runs them too. Segments may carry other fields, e.g. `say`, the spoken form (ignored).
[docs/podcast-format.md](docs/podcast-format.md) ships with the extension.
- **Understanding check: a tour of the change.** Right after the questions, Claude writes a short journey of the change
(6-10 steps through the changed code and the code it depends on), each question placed after the step that shows
its answer. Check my understanding (or **Walk the tour** in the Check view) walks it in the journey panel: the
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,13 @@ write one.
the line of code that does it, and shows that line with a few around it under the caption.
- **Steps follow the code** like notes do: moved code is followed, changed code is flagged. Your own edits to a
step's lines (typing, an applied fix) are followed, not flagged.
- **Listen:** a journey with an audio episode next to it (`<journey>.podcast.json`) has ▶ Listen on its row. The walk
follows the voice: each step's code opens, the animation moves beat by beat, the caption shows the sentence being
said. The timeline is marked by step; click or drag anywhere and the walk is exactly where it is at that time. The
storyline becomes the chapter list (▶ for one step, the transcript of the step being said). The audio plays in the
Listen view, so it goes on when the journey panel is closed or VS Code is in the background.
[docs/podcast-format.md](docs/podcast-format.md) describes the format and its checks: problems show in the
Problems view, and a podcast that can't play says why in its row's tooltip.

![What a step's animation can draw](docs/images/objects.png)

Expand Down Expand Up @@ -179,6 +186,9 @@ One chord: **Ctrl+'** (or **Ctrl+<** on ISO keyboards), then a letter.
| **V** | The journey map |
| **P** | The current step's animation, on or off |
| **J** | Search journeys |
| **Space** | Listen: play or pause |
| **←** / **→** | Listen: back / forward 15 s |
| **Shift+←** / **Shift+→** | Listen: previous / next step |

## Requirements

Expand Down
40 changes: 40 additions & 0 deletions docs/journey-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ personal.
],
"links": [ /* { phrase, file, start, end, anchor }: a phrase of the lead or details linked to those lines */ ],
"values": [ /* { name, value, file, line, text, note? }: a value hint above that line */ ],
"marks": [ /* { lines, match?, nth?, file? }: the part of the code the text names (see "Marks") */ ],
"scene": { /* the step's animation: actors, wires, beats (see "Step animations") */ }
}
]
Expand Down Expand Up @@ -145,6 +146,45 @@ parent rule stays a `check` problem for readability, but nothing is hidden when
shortened (first clause, no timings; a generic "calls" is not drawn); the whole label and `detail` are the label's
tooltip. Function boxes open `at` (lines selected), else `path`, else their first step's lines.

## Marks: the part of a line the step is about

A step, and each beat of its animation, may carry `marks`: the few characters its text names (one call, one argument,
one condition, one field) instead of whole lines. The same shape as a podcast segment's marks
(docs/podcast-format.md, "Marks") without the time: `lines`, an optional `match` and `nth`, an optional `file`.

```jsonc
"steps": [{
"title": "An empty cart is refused first", "file": "api/orders.js", "range": { "start": 10, "end": 15 },
"marks": [{ "lines": [12, 12], "match": "total <= 0" }],
"scene": { "actors": […], "beats": [
{ "focus": "api", "caption": "It holds the stock for 30 s.", "code": { "file": "api/orders.js", "line": 13, "text": "…" },
"marks": [{ "lines": [13, 13], "match": "{ hold: 30 }" }] }
] }
}]
```

| Field | |
|---|---|
| `lines` | `[first, last]`, 1-based, inclusive, in the code at the journey's commit |
| `match` | Optional: only this text within `lines` lights (whitespace as written; it may span the lines). Without it the whole lines light |
| `nth` | Optional, 1-based: which occurrence of `match` within `lines` (default 1) |
| `file` | Optional, relative to the repository. Default: the step's file; on a beat, the beat's `code` file, else the step's |

While the step is walked:

- Opening the step lights its marks. A beat lights its own as the focus (`codeNotes.markBackground`); the step's
marks and earlier beats' stay, a lighter grey. A beat without marks keeps the newest ones before it as the focus.
The look is a podcast's: fills only, a mark within a line tints its characters, a mark of whole lines the lines.
- While there are marks, the step's lines get a thin grey bar instead of the bar and tint, and a beat with marks has
no box on its line: the marks carry the attention. A step without marks looks as it always did.
- Marks in the step's file move with the step (its anchor). `match` not where `lines` say: the nearest place with the
same lines shifted up to 20 lines up or down; not there either, the mark lights nothing (said once in the output).
Lines past the end of the file: nothing.
- `journey.py check` checks them (the file, the lines, `match` on them and its `nth`); `journey.py marks <slug> [n]`
prints each mark with the characters it lights.

Keep them sparse: at most ~3 per step or beat, and only what the text names.

## Step animations (`scene`)

A step may carry a `scene`: a few actors (`app`, `browser`, `service`, `table`, `cluster`, `terminal`, `file`,
Expand Down
Loading
Loading