fix(lint): resolve all ruff and mypy errors

- Fix B023: lambda capturing loop var `ratio` in make_fade_out_frames (use default arg)
- Fix mypy [assignment]: rename local `dark` → `border` in render_png.py and svg_render.py to avoid shadowing bool param
- Fix mypy [arg-type]: resolve `int | None` fade_out_frames before passing to make_fade_out_frames in replay_cmd
- Remove now-unnecessary type: ignore comments in render_png.py

Author: deeplook

CHANGELOG.md

@@ -7,15 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.4.1] - 2026-xx-xx
+## [0.4.1] - 2026-04-03
 
 ### Added
 
-- **Automatic `gh` CLI credential fallback** — if `--github-token` and `GITHUB_TOKEN`
-  are both absent, dirplot silently runs `gh auth token`. Users authenticated with the
-  [GitHub CLI](https://cli.github.com/) (`gh auth login`) can access private repositories
-  with no extra configuration. Token resolution order: `--github-token` →
-  `$GITHUB_TOKEN` → `gh auth token`.
 - **`--last PERIOD`** for `dirplot git` — filter commits by a relative time period instead
   of (or in addition to) `--max-commits`. Accepts a number followed by a unit:
   `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `mo` (months = 30 days).
@@ -27,6 +22,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   dirplot git github://owner/repo -o history.mp4 --animate --last 2w --max-commits 10
   ```
 
+- **`dirplot demo` command** — new subcommand that runs a curated set of example commands
+  and saves outputs to a folder. Useful for first-time walkthroughs or verifying that
+  everything works in a given environment. Accepts `--output` (default: `demo/`),
+  `--github-url` (default: `https://github.com/deeplook/dirplot`), and
+  `--interactive` / `-i` to step through and confirm each command individually. Output
+  uses rich formatting with colour, section rules, and status indicators.
+  ```bash
+  dirplot demo                             # run all examples, save to ./demo/
+  dirplot demo --output ~/dp-demo --interactive
+  ```
+
+- **`--fade-out` for animated output** — appends a fade-out sequence at the end of
+  animations produced by `dirplot git --animate`, `dirplot watch --animate`, and
+  `dirplot replay`. Four flags control the effect:
+  - `--fade-out` / `--no-fade-out` — enable/disable (default: off)
+  - `--fade-out-duration SECS` — total fade length in seconds (default: 1.0)
+  - `--fade-out-frames N` — number of blend steps; defaults to 4 per second of duration
+    so longer fades are automatically finer-grained
+  - `--fade-out-color COLOR` — target colour: `auto` (black in dark mode, white in light
+    mode), `transparent` (PNG/APNG only; fades to fully transparent), any CSS colour
+    name, or hex code (e.g. `"#1a1a2e"`)
+  ```bash
+  dirplot git . -o history.png --animate --fade-out
+  dirplot git . -o history.mp4 --animate --fade-out --fade-out-duration 2.0
+  dirplot git . -o history.png --animate --fade-out --fade-out-color transparent
+  ```
+
+- **`--dark` / `--light` mode** for all treemap commands — controls background and border
+  colours. Dark mode (default) uses a near-black canvas with white directory labels; light
+  mode uses a white canvas with black labels. Available on `map`, `git`, `watch`, and
+  `replay`.
+  ```bash
+  dirplot map . --light
+  dirplot git . -o history.mp4 --animate --light
+  ```
+
+- **Metadata in MP4/MOV output** — `dirplot git`, `dirplot watch`, and `dirplot replay`
+  now embed the same dirplot metadata (date, software version, OS, Python version,
+  executed command) into MP4/MOV files that was previously only written to PNG and SVG.
+  `dirplot read-meta` reads it back via `ffprobe`.
+
+- **Automatic `gh` CLI credential fallback** — if `--github-token` and `GITHUB_TOKEN`
+  are both absent, dirplot silently runs `gh auth token`. Users authenticated with the
+  [GitHub CLI](https://cli.github.com/) (`gh auth login`) can access private repositories
+  with no extra configuration. Token resolution order: `--github-token` →
+  `$GITHUB_TOKEN` → `gh auth token`.
+
+### Changed
+
+- `--fade-out-frames` defaults dynamically to `round(fade_out_duration × 4)` rather than
+  a fixed 4, so a 2-second fade automatically uses 8 frames and a 0.5-second fade uses 2.
+
 ### Fixed
 
 - **`--total-duration` overshooting the target length** — when many commits fell within
@@ -36,6 +83,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   non-floored frames are now scaled down to compensate so the sum always matches
   `--total-duration` exactly.
 
+### Docs
+
+- Added `## dirplot read-meta` section to `docs/CLI.md` (previously undocumented).
+- Documented external tool requirements: `git` (required by `dirplot git`), `ffmpeg`
+  (required for MP4 output), `ffprobe` (required by `read-meta` on MP4 files) — in both
+  `README.md` and `docs/CLI.md`.
+
 ## [0.4.0] - 2026-03-28
 
 ### Added

README.md

@@ -34,6 +34,8 @@ Optional extras: `pip install "dirplot[ssh]"`, `"dirplot[s3]"`, `"dirplot[libarc
 
 `dirplot watch` uses [watchdog](https://github.com/gorakhargosh/watchdog) for filesystem monitoring — installed automatically as a dependency.
 
+`dirplot git` requires `git` on `PATH`. MP4 output (`dirplot git`, `dirplot watch`, `dirplot replay` with `--animate`) requires [ffmpeg](https://ffmpeg.org/) on `PATH`. `dirplot read-meta` on `.mp4` files also requires `ffprobe` (bundled with ffmpeg).
+
 ## Quick start
 
 ```bash

docs/CLI.md

@@ -106,6 +106,8 @@ dirplot map pod://my-pod:/app
 
 Monitors directories and regenerates the treemap on every change. With `--animate`, each debounced render becomes one frame; the complete APNG or MP4 is written on Ctrl-C.
 
+> **Requires** `ffmpeg` on `PATH` for MP4 output.
+
 ```bash
 # Watch and regenerate on every change
 dirplot watch . --output treemap.png
@@ -125,6 +127,11 @@ dirplot watch . --output treemap.png --animate
 dirplot watch . --output treemap.mp4 --animate
 dirplot watch . --output treemap.mp4 --animate --crf 18         # higher quality
 dirplot watch . --output treemap.mp4 --animate --codec libx265  # smaller file
+
+# Fade out to black at the end (default: 1 s, 4 fps)
+dirplot watch . --output treemap.png --animate --fade-out
+dirplot watch . --output treemap.mp4 --animate --fade-out --fade-out-duration 2.0
+dirplot watch . --output treemap.png --animate --fade-out --fade-out-color transparent  # APNG only
 ```
 
 ### Options
@@ -135,6 +142,10 @@ dirplot watch . --output treemap.mp4 --animate --codec libx265  # smaller file
 | `--debounce` | `0.5` | Seconds of quiet before regenerating; `0` disables |
 | `--event-log` | — | Write raw events as JSONL on Ctrl-C exit |
 | `--animate` / `--no-animate` | off | Capture frames and write APNG or MP4 on Ctrl-C |
+| `--fade-out` / `--no-fade-out` | off | Append a fade-out sequence at the end (animate only) |
+| `--fade-out-duration` | `1.0` | Duration of the fade-out in seconds |
+| `--fade-out-frames` | 4 × duration | Number of fade frames; defaults to 4 per second |
+| `--fade-out-color` | `auto` | Fade target: `auto` (black/white per mode), `transparent` (PNG/APNG only), CSS name, or hex |
 | `--crf` | `23` | MP4 quality: 0 = lossless, 51 = worst. Ignored for APNG |
 | `--codec` | `libx264` | MP4 codec: `libx264` (H.264) or `libx265` (H.265) |
 | `--log` / `--no-log` | off | Log scale for file sizes |
@@ -151,6 +162,8 @@ dirplot watch . --output treemap.mp4 --animate --codec libx265  # smaller file
 
 Replays a JSONL event log produced by `dirplot watch --event-log` as an animated treemap. Events are grouped into time buckets (one frame per bucket).
 
+> **Requires** `ffmpeg` on `PATH` for MP4 output.
+
 ```bash
 # Replay as APNG (60-second buckets, 30-second total)
 dirplot replay events.jsonl --output replay.apng --total-duration 30
@@ -162,16 +175,24 @@ dirplot replay events.jsonl --output replay.mp4 --codec libx265  # smaller file
 
 # Fine-grained buckets with fixed frame duration
 dirplot replay events.jsonl --output replay.apng --bucket 10 --frame-duration 200
+
+# Fade out at the end
+dirplot replay events.jsonl --output replay.mp4 --total-duration 30 --fade-out
+dirplot replay events.jsonl --output replay.png --total-duration 30 --fade-out --fade-out-color white
 ```
 
 ### Options
 
 | Flag | Default | Description |
 |---|---|---|
-| `--output` / `-o` | required | Output `.apng` or `.mp4` |
+| `--output` / `-o` | required | Output `.png`, `.apng`, or `.mp4` |
 | `--bucket` | `60.0` | Time bucket size in seconds; one frame per bucket |
 | `--frame-duration` | `500` | Frame display time in ms (when `--total-duration` is not set) |
 | `--total-duration` | — | Target total animation length in seconds; frames scale proportionally to real time gaps |
+| `--fade-out` / `--no-fade-out` | off | Append a fade-out sequence at the end |
+| `--fade-out-duration` | `1.0` | Duration of the fade-out in seconds |
+| `--fade-out-frames` | 4 × duration | Number of fade frames; defaults to 4 per second |
+| `--fade-out-color` | `auto` | Fade target: `auto` (black/white per mode), `transparent` (PNG/APNG only), CSS name, or hex |
 | `--crf` | `23` | MP4 quality: 0 = lossless, 51 = worst. Ignored for APNG |
 | `--codec` | `libx264` | MP4 codec: `libx264` (H.264) or `libx265` (H.265) |
 | `--workers` / `-w` | all CPU cores | Parallel render workers |
@@ -189,6 +210,8 @@ dirplot replay events.jsonl --output replay.apng --bucket 10 --frame-duration 20
 
 Renders a git repository's commit history as an animated treemap. Each commit becomes one frame; changed tiles are highlighted.
 
+> **Requires** `git` on `PATH`. `ffmpeg` is also required for MP4 output.
+
 The `repo` argument accepts:
 - Local path: `.`, `/path/to/repo`
 - Local path with ref: `.@my-branch`, `.@v1.0`, `.@abc1234`
@@ -222,6 +245,12 @@ dirplot git github://owner/repo@main --output history.apng --animate --max-commi
 dirplot git . --output history.mp4 --animate --last 30d
 dirplot git . --output history.mp4 --animate --last 24h
 dirplot git github://owner/repo --output history.mp4 --animate --last 2w --max-commits 10
+
+# Fade out to black at the end (animate only)
+dirplot git . --output history.png --animate --fade-out
+dirplot git . --output history.mp4 --animate --fade-out --fade-out-duration 2.0
+dirplot git . --output history.png --animate --fade-out --fade-out-color transparent  # APNG/PNG only
+dirplot git . --output history.mp4 --animate --fade-out --fade-out-color "#1a1a2e"
 ```
 
 ### Options
@@ -235,6 +264,10 @@ dirplot git github://owner/repo --output history.mp4 --animate --last 2w --max-c
 | `--last` | — | Time-period filter: `30d`, `24h`, `2w`, `1mo`, `30m`. Uses `--shallow-since` for GitHub URLs |
 | `--frame-duration` | `1000` | Frame display time in ms (when `--total-duration` is not set) |
 | `--total-duration` | — | Target total animation length in seconds; frames scale proportionally to real time gaps between commits |
+| `--fade-out` / `--no-fade-out` | off | Append a fade-out sequence at the end (animate only) |
+| `--fade-out-duration` | `1.0` | Duration of the fade-out in seconds |
+| `--fade-out-frames` | 4 × duration | Number of fade frames; defaults to 4 per second |
+| `--fade-out-color` | `auto` | Fade target: `auto` (black/white per mode), `transparent` (PNG/APNG only), CSS name, or hex |
 | `--crf` | `23` | MP4 quality: 0 = lossless, 51 = worst. Ignored for APNG |
 | `--codec` | `libx264` | MP4 codec: `libx264` (H.264) or `libx265` (~40% smaller at same quality) |
 | `--workers` / `-w` | all CPU cores | Parallel render workers; 4–8 is typically optimal |
@@ -249,6 +282,21 @@ dirplot git github://owner/repo --output history.mp4 --animate --last 2w --max-c
 
 ---
 
+## `dirplot read-meta` — read embedded metadata
+
+Reads dirplot metadata (date, software version, OS, Python version, executed command) embedded in a PNG, SVG, or MP4/MOV output file.
+
+> **Requires** `ffprobe` on `PATH` (bundled with [ffmpeg](https://ffmpeg.org/)) to read metadata from `.mp4` / `.mov` files.
+
+```bash
+dirplot read-meta treemap.png
+dirplot read-meta treemap.svg
+dirplot read-meta history.mp4
+dirplot read-meta a.png b.png c.svg   # multiple files
+```
+
+---
+
 ## `dirplot demo` — run example commands
 
 Runs a curated set of example commands covering each subcommand and saves outputs to a folder. Useful for a first-time walkthrough or to verify that everything works in your environment.
@@ -272,8 +320,9 @@ Examples produced:
 | `map-local.png` | `dirplot map .` (dark mode, PNG) |
 | `map-github.png` | `dirplot map github://owner/repo` (dark mode, PNG) |
 | `map-local.svg` | `dirplot map .` (light mode, SVG) |
-| `git.png` | `dirplot git github://owner/repo --max-commits 5` (static PNG) |
+| `git-static.png` | `dirplot git github://owner/repo --max-commits 5` (static PNG) |
 | `git.mp4` | `dirplot git github://owner/repo --max-commits 10 --animate --total-duration 20` |
+| `git-animated.png` | `dirplot git github://owner/repo --max-commits 10 --animate --total-duration 20 --fade-out` |
 | *(stdout)* | `dirplot read-meta map-local.png` |
 
 `dirplot watch` and `dirplot replay` are listed but skipped with an explanatory note — both require interactive or pre-recorded input.