Guides: tutorial pictures at 2x, and each tutorial's clip as a short film

docs/guides/README.md

@@ -2,7 +2,7 @@
 
 Task guides for people. Each one says what to tell your coding agent, the commands it runs, the files you get,
 how long it took on a named machine, the phrases that change the result, the honest limits, and an example to
-look at. A few guides are tutorials: one real run as numbered steps, a screenshot at each and a short clip at the top, then the same closing sections. The references in `skills/showtime/references/` are written for your agent; these are written for you.
+look at. A few guides are tutorials: one real run as numbered steps, a screenshot at each and a short silent film of the whole run at the top (made with showtime), then the same closing sections. The references in `skills/showtime/references/` are written for your agent; these are written for you.
 
 | Guide | When you want |
 |---|---|

docs/guides/first-video.md

@@ -6,7 +6,8 @@ Start here if you have never used showtime. Ask for a 5-second test video: your
 the video on your computer, checks it and has it reviewed. You learn that the install works, and you see every step a
 bigger video goes through. This guide follows one real run, with a screenshot of each step.
 
-![The whole run in 23 seconds: the terminal as the job is made, the check and the first look, the first render and its qa warning, the fixed render, the finished 5-second video, the review sheet and the receipt.](../../assets/readme/tutorials/first-video/clip.webp)
+<!-- video: examples/_tutorials/first-video/clip.mp4 -->
+[![The whole run in 18 seconds, one step at a time: the terminal as the job is made, the check and the first look, the first render and its qa warning, the fixed render, the finished 5-second video, the review sheet, the findings answered and the receipt.](https://github.com/FavioVazquez/showtime-examples/raw/main/examples/_tutorials/first-video/clip.jpg)](https://faviovazquez.github.io/showtime/docs/guides/first-video.html)
 
 ## Say this
 
@@ -137,7 +138,9 @@ top and were not timed. More numbers: [render § Speed](../../skills/showtime/re
   a video needs them, with their size shown first. The test video downloads nothing more.
 - The qa output in steps 3 and 4 was printed again on the saved files for the screenshots, after the silent-film line
   was in `showtime.json`, so it shows the still-hold warning only. The findings in step 7 are shortened from the
-  critic's reply. Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).
+  critic's reply. The look image and the review sheet were made again at twice their size for this page: the look
+  from the finished project (the glow's drift is the only change), the sheet from the same six frames of
+  `final-3.mp4`. Something failed? Ask your agent to run `showtime doctor`, then see [Troubleshooting](../troubleshooting.md).
 
 ## The example
 

docs/guides/studio-concepts-to-final.md

@@ -7,7 +7,8 @@ storyboard, and only then does the film get built. This guide walks through one
 screenshot of each step. The video is a 20-second trailer for Tidepool, a fictional notes app that ships with showtime
 as sample material.
 
-![The whole run in 22 seconds: the board with four concepts, a wipe between two of them, a pick and a comment, the storyboard, the approval and the finished trailer.](../../assets/readme/tutorials/studio/clip.webp)
+<!-- video: examples/_tutorials/studio/clip.mp4 -->
+[![The whole run in 18 seconds, one step at a time: the terminal as the board is built, the board with four concepts, a wipe between two of them, a comment, your agent's answer, the storyboard, the approval, then the first and last seconds of the finished trailer.](https://github.com/FavioVazquez/showtime-examples/raw/main/examples/_tutorials/studio/clip.jpg)](https://faviovazquez.github.io/showtime/docs/guides/studio-concepts-to-final.html)
 
 ## Say this
 
@@ -38,7 +39,7 @@ One concept is marked **Recommended**, with the reason.
 
 The **Compare** tab puts any two concepts on one frame. Drag across it to wipe from one to the other.
 
-![The Compare tab: a frame split down the middle, C1 Low tide on the left with its wave line and C2 Macro on the right with the words "Sync: local only".](../../assets/readme/tutorials/studio/03-compare.webp)
+![The Compare tab: one frame split by the wipe line, C1 Low tide on the left with its wave line and the words "Q4 planning draft", and C3 Keystrokes on the right with the app's command palette.](../../assets/readme/tutorials/studio/03-compare.webp)
 
 ## 4. Pick, like and comment
 
@@ -66,7 +67,7 @@ Round 2 is the storyboard of the concept you picked: every shot with its time ra
 how it moves. The thumbnails are rendered from the draft project at those moments. Open the **Storyboard** tab, and
 use **Note** under a shot to say what to change.
 
-![The Storyboard tab: shot cards C2.1 to C2.5, with a sixth cut off at the right edge, each with a thumbnail, a time range such as 0:00.0 to 0:02.5, what is on screen and a Note button.](../../assets/readme/tutorials/studio/07-storyboard.webp)
+![The Storyboard tab: the first three shot cards, C2.1 to C2.3, each with a thumbnail, a time range such as 0:00.0 to 0:02.5, what is on screen, how it moves and a Note button.](../../assets/readme/tutorials/studio/07-storyboard.webp)
 
 ![A comment box on shot C2.1: Hold the first shot a beat longer.](../../assets/readme/tutorials/studio/08-shot-note.webp)
 
@@ -121,6 +122,7 @@ Your agent's writing of the concepts and your own time on the board come on top
 - Music beds and voice samples also go on the board; this run skipped them to stay short.
 - To keep the run short, the project that was rendered in step 8 is the finished project of example 09, copied to a plain
   folder; the storyboard thumbnails and the final film come from it. The clicks on the board were made with a headless
-  browser, the way a reviewer would make them.
+  browser, the way a reviewer would make them. The board pictures were captured again later from the same job at a
+  higher resolution, with the board and its feedback put back to each round as it was.
 - The commands behind each step: [Studio mode](../../skills/showtime/references/studio.md); the board file:
   [Board format](../../skills/showtime/references/boards.md).

site/build.py

@@ -469,6 +469,22 @@ def attr(m):
         out = re.sub(r'(<(?:img|source)\b[^>]*?(?:src|srcset)="[^"]*-(?:light|dark)\.svg")', r'\1 data-themed', out)
         return out
 
+    def guide_videos(self, body: str, page: str) -> str:
+        """A guide's film: `<!-- video: examples/....mp4 -->` over a linked poster picture (on GitHub the poster
+        links to the site page). Here the pair becomes a <video> with that poster; without the film in this build
+        the poster stays, linked to the film's own address."""
+        def video(m: "re.Match[str]") -> str:
+            local, fallback = self.media(m.group(1), m.group(1).split("/")[1])
+            poster, alt = m.group(3), m.group(4)
+            if not local:
+                return '<p><a href="%s"><img src="%s" alt="%s"></a></p>' % (esc(fallback or m.group(2)), poster, alt)
+            src = esc(rel(page, local))   # a browser that plays no video shows a link to the file instead
+            return ('<figure class="guide-video"><video controls muted loop playsinline preload="metadata" poster="%s" '
+                    'aria-label="%s"><source src="%s" type="video/mp4"><a href="%s">Watch the film (MP4)</a></video></figure>'
+                    % (poster, alt, src, src))
+        return re.sub(r'<!-- video: (examples/[^ ]+\.mp4) -->\s*<p><a href="([^"]*)"><img src="([^"]*)" alt="([^"]*)"\s*/?></a></p>',
+                      video, body)
+
     def render_md(self, text: str, src: Path, page: str, drop_h1: bool = False) -> Tuple[str, str, List[Tuple[str, str, int]]]:
         """Markdown -> (html, title, headings[(text, id, level)])."""
         env: dict = {}
@@ -493,6 +509,7 @@ def render_md(self, text: str, src: Path, page: str, drop_h1: bool = False) -> T
         body = re.sub(r"<blockquote>\s*<p>\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*",
                       lambda m: '<blockquote class="alert"><p class="alert-title">%s</p><p>' % m.group(1).title(), body)
         body = self.rewrite(body, src, page)
+        body = self.guide_videos(body, page)
         body = mark_url_links(body)
         body = keep_flags_whole(body)
         return body, title, heads

site/static/style.css

@@ -271,6 +271,8 @@ p{margin:0}
 .prose blockquote > * + *{margin-top:.6em}
 .prose .alert-title{font-size:.8rem;font-weight:600;letter-spacing:.04em;color:var(--ink);text-transform:uppercase}
 .prose img{border-radius:8px;max-height:72vh;width:auto}
+.prose .guide-video{margin:1.2em 0}
+.prose .guide-video video{display:block;width:100%;height:auto;aspect-ratio:16/9;border-radius:8px;background:#15110e}
 .prose picture img{border-radius:0}
 .prose pre{font-size:.83rem}
 .crumbs{font-size:.84rem;color:var(--muted);margin-bottom:18px}